"Python Interface to Travel Time."

Project description

Travel Time Python SDK

Travel Time Python SDK helps users find locations by journey time rather than using ‘as the crow flies’ distance.
Time-based searching gives users more opportunities for personalisation and delivers a more relevant search.

Usage

Installation

Install Travel Time Python SDK in a virtualenv using pip. virtualenv is a tool to create isolated Python environments.

virtualenv allows to install Travel Time Python SDK without needing system install permissions, and without clashing with the installed system dependencies.

Linux/Mac

pip3 install virtualenv
virtualenv <your-env>
source <your-env>/bin/activate
<your-env>/bin/pip install traveltimepy

Windows

pip install virtualenv
virtualenv <your-env>
<your-env>\Scripts\activate
<your-env>\Scripts\pip.exe install traveltimepy

Sdk set up

In order to authenticate with Travel Time API, you will have to supply the Application Id and Api Key. If you want to speed up requests, you can also specify limit_per_host, this parameter specifies how may requests can be processed at the same time.

from traveltimepy import TravelTimeSdk

sdk = TravelTimeSdk(app_id='YOUR_APP_ID', api_key='YOUR_APP_KEY', limit_per_host=4)

Asynchronous calls

Each method below has its own asynchronous version.

Example:

from datetime import datetime

from traveltimepy import Driving, Coordinates, TravelTimeSdk

sdk = TravelTimeSdk('YOUR_APP_ID', 'YOUR_APP_KEY')

res = await sdk.time_map_async(
    coordinates=[Coordinates(lat=51.507609, lng=-0.128315), Coordinates(lat=51.517609, lng=-0.138315)],
    arrival_time=datetime.now(),
    transportation=Driving()
)

Isochrones (Time Map)

Given origin coordinates, find shapes of zones reachable within corresponding travel time.

Takes:

coordinates: List[Coordinates] - Isochrones coordinates.
arrival_time: datetime - Be at arrival location at no later than given time. Cannot be specified with departure_time.
departure_time: datetime - Leave departure location at no earlier than given time. Cannot be specified with arrival_time.
travel_time: int - Maximum journey time (in seconds). Maximum value is 14400. Default value is 3600
transportation: Union - Transportation mode and related parameters.
search_range: Range - When enabled, range adds an arrival window to the arrival time, and results are returned for any journeys that arrive during this window.

Returns:

results: List[TimeMapResult] - The list of isochrone shapes.

Example:

from datetime import datetime

from traveltimepy import Driving, Coordinates, TravelTimeSdk

sdk = TravelTimeSdk('YOUR_APP_ID', 'YOUR_APP_KEY')

results = sdk.time_map(
    coordinates=[Coordinates(lat=51.507609, lng=-0.128315), Coordinates(lat=51.517609, lng=-0.138315)],
    arrival_time=datetime.now(),
    transportation=Driving()
)

print(results)

Isochrones (Intersection)

Given origin coordinates, find intersections of specified shapes.

Takes:

coordinates: List[Coordinates] - Intersection coordinates. The size of list cannot be more than 10.
arrival_time: datetime - Be at arrival location at no later than given time. Cannot be specified with departure_time.
departure_time: datetime - Leave departure location at no earlier than given time. Cannot be specified with arrival_time.
travel_time: int - Maximum journey time (in seconds). Maximum value is 14400. Default value is 3600
transportation: Union - Transportation mode and related parameters.
search_range: Range - When enabled, range adds an arrival window to the arrival time, and results are returned for any journeys that arrive during this window.

Returns:

results: List[TimeMapResult] - The list of isochrone shapes.

Example:

from datetime import datetime

from traveltimepy import Driving, Coordinates, TravelTimeSdk

sdk = TravelTimeSdk('YOUR_APP_ID', 'YOUR_APP_KEY')

results = sdk.intersection(
    coordinates=[Coordinates(lat=51.507609, lng=-0.128315), Coordinates(lat=51.517609, lng=-0.138315)],
    arrival_time=datetime.now(),
    transportation=Driving()
)

print(results)

Isochrones (Union)

Given origin coordinates, find unions of specified shapes.

Finds the union of specified shapes.

Takes:

coordinates: List[Coordinates] - Union coordinates. The size of list cannot be more than 10.
arrival_time: datetime - Be at arrival location at no later than given time. Cannot be specified with departure_time.
departure_time: datetime - Leave departure location at no earlier than given time. Cannot be specified with arrival_time.
travel_time: int - Maximum journey time (in seconds). Maximum value is 14400. Default value is 3600
transportation: Union - Transportation mode and related parameters.
search_range: Range - When enabled, range adds an arrival window to the arrival time, and results are returned for any journeys that arrive during this window.

Returns:

results: List[TimeMapResult] - The list of isochrone shapes.

Example:

from datetime import datetime

from traveltimepy import Driving, Coordinates, TravelTimeSdk

sdk = TravelTimeSdk('YOUR_APP_ID', 'YOUR_APP_KEY')

results = sdk.union(
    coordinates=[Coordinates(lat=51.507609, lng=-0.128315), Coordinates(lat=51.517609, lng=-0.138315)],
    arrival_time=datetime.now(),
    transportation=Driving()
)

print(results)

Distance Matrix (Time Filter)

Given origin and destination points filter out points that cannot be reached within specified time limit. Find out travel times, distances and costs between an origin and up to 2,000 destination points.

Takes:

locations: List[Locations] - All locations. Location ids must be unique.
search_ids: Dict[str, List[str]] - Search ids from a target location to destinations. You can define up to 2000 destinations
arrival_time: datetime - Be at arrival location at no later than given time. Cannot be specified with departure_time.
departure_time: datetime - Leave departure location at no earlier than given time. Cannot be specified with arrival_time.
transportation: Union - Transportation mode and related parameters.
travel_time: int - Maximum journey time (in seconds). Maximum value is 14400. Default value is 3600.
properties: List[Property] - Properties to be returned about the postcodes. Default value is travel_time.
range: FullRange - When enabled, range adds an arrival window to the arrival time, and results are returned for any journeys that arrive during this window.

Returns:

results: List[TimeFilterResult] - The results list of reachable and unreachable locations.

Example:

from datetime import datetime

from traveltimepy import Location, Coordinates, PublicTransport, Property, FullRange, TravelTimeSdk

sdk = TravelTimeSdk('YOUR_APP_ID', 'YOUR_APP_KEY')

locations = [
    Location(id='London center', coords=Coordinates(lat=51.508930, lng=-0.131387)),
    Location(id='Hyde Park', coords=Coordinates(lat=51.508824, lng=-0.167093)),
    Location(id='ZSL London Zoo', coords=Coordinates(lat=51.536067, lng=-0.153596))
]

results = sdk.time_filter(
    locations=locations,
    search_ids={
        'London center': ['Hyde Park', 'ZSL London Zoo'],
        'ZSL London Zoo': ['Hyde Park', 'London center'],
    },
    departure_time=datetime.now(),
    travel_time=3600,
    transportation=PublicTransport(type='bus'),
    properties=[Property.TRAVEL_TIME],
    range=FullRange(enabled=True, max_results=3, width=600)
)

print(results)

Time Filter (Fast)

A very fast version of time_filter(). However, the request parameters are much more limited. Currently only supports UK and Ireland.

Takes:

locations: List[Locations] - All locations. Location ids must be unique.
search_ids: Dict[str, List[str]] - Searches from a target location to destinations. You can define up to 100,000 destinations
transportation: Union - Transportation mode and related parameters.
travel_time: int - Maximum journey time (in seconds). Maximum value is 10800. Default value is 3600.
properties: List[Property] - Properties to be returned about the postcodes. Default value is travel_time.
one_to_many: boolean - if one_to_many is equal to true, then it'll be a forward search (one to many matrix), false - backward search (many to one matrix). Default value is False.

Returns:

results: List[TimeFilterFastResult] - The results list of reachable and unreachable locations.

Example:

from traveltimepy import Location, Coordinates, Transportation, TravelTimeSdk

sdk = TravelTimeSdk('YOUR_APP_ID', 'YOUR_APP_KEY')

locations = [
    Location(id='London center', coords=Coordinates(lat=51.508930, lng=-0.131387)),
    Location(id='Hyde Park', coords=Coordinates(lat=51.508824, lng=-0.167093)),
    Location(id='ZSL London Zoo', coords=Coordinates(lat=51.536067, lng=-0.153596))
]

results = sdk.time_filter_fast(
    locations=locations,
    search_ids={
        'London center': ['Hyde Park', 'ZSL London Zoo'],
        'ZSL London Zoo': ['Hyde Park', 'London center'],
    },
    transportation=Transportation(type='public_transport'),
    one_to_many=False
)

print(results)

Time Filter Fast (Proto)

A fast version of time filter communicating using protocol buffers.

The request parameters are much more limited and only travel time is returned. In addition, the results are only approximately correct (95% of the results are guaranteed to be within 5% of the routes returned by regular time filter). This inflexibility comes with a benefit of faster response times (Over 5x faster compared to regular time filter) and larger limits on the amount of destination points.

Takes:

origin: Coordinates - Origin point.
destinations: List[Coordinates] - Destination points. Cannot be more than 200,000.
transportation: ProtoTransportation - Transportation type.
travel_time: int - Time limit. Maximum value is 7200.
country: ProtoCountry - Return the results that are within the specified country.

Returns:

travel_times: List[int] - The responses are in the form of a list where each position denotes either a travel time (in seconds) of a journey, or if negative that the journey from the origin to the destination point is impossible.

Example:

from traveltimepy import ProtoCountry, Coordinates, ProtoTransportation, TravelTimeSdk

sdk = TravelTimeSdk('YOUR_APP_ID', 'YOUR_APP_KEY')

travel_times = sdk.time_filter_proto(
    origin=Coordinates(lat=51.425709, lng=-0.122061),
    destinations=[
        Coordinates(lat=51.348605, lng=-0.314783),
        Coordinates(lat=51.337205, lng=-0.315793)
    ],
    transportation=ProtoTransportation.DRIVING_FERRY,
    travel_time=7200,
    country=ProtoCountry.UNITED_KINGDOM
)

print(travel_times)

Routes

Returns routing information between source and destinations.

Takes:

locations: List[Locations] - All locations. Location ids must be unique.
search_ids: Dict[str, List[str]] - Searches from a target location to destinations.
arrival_time: datetime - Be at arrival location at no later than given time. Cannot be specified with departure_time.
departure_time: datetime - Leave departure location at no earlier than given time. Cannot be specified with arrival_time.
transportation: Union - Transportation mode and related parameters.
properties: List[Property] - Properties to be returned about the postcodes. Default value is travel_time.
range: FullRange - When enabled, range adds an arrival window to the arrival time, and results are returned for any journeys that arrive during this window.

Returns:

results: List[RoutesResult] - The results list of routes.

Example:

from datetime import datetime

from traveltimepy import Location, Coordinates, PublicTransport, TravelTimeSdk

sdk = TravelTimeSdk('YOUR_APP_ID', 'YOUR_APP_KEY')

locations = [
  Location(id='London center', coords=Coordinates(lat=51.508930, lng=-0.131387)),
  Location(id='Hyde Park', coords=Coordinates(lat=51.508824, lng=-0.167093)),
  Location(id='ZSL London Zoo', coords=Coordinates(lat=51.536067, lng=-0.153596))
]

results = sdk.routes(
  locations=locations,
  search_ids={
    'London center': ['Hyde Park', 'ZSL London Zoo'],
    'ZSL London Zoo': ['Hyde Park', 'London center'],
  },
  transportation=PublicTransport(),
  departure_time=datetime.now()
)

print(results)

Geocoding (Search)

Match a query string to geographic coordinates.

Takes:

query: str - A query to geocode. Can be an address, a postcode or a venue.
within_countries: List[str] - Only return the results that are within the specified country.
limit: int - Expected integer between 1 and 50. Limits amount of results returned to specified number.
format_name: bool - Format the name field of the geocoding search response to a well formatted, human-readable address of the location.
format_exclude_country: bool - Exclude the country from the formatted name field.
bounds: Rectangle - Used to limit the results to a bounding box.

Returns:

Matched locations in geojson format

Example:

from traveltimepy import TravelTimeSdk

sdk = TravelTimeSdk('YOUR_APP_ID', 'YOUR_APP_KEY')

results = sdk.geocoding(query='Parliament square', limit=30)

print(results.features)

Reverse Geocoding

Match a latitude, longitude pair to an address.

Takes:

lat: float - Latitude
lng: float - Longitude

Returns:

Matched locations in a geojson format

Example:

from traveltimepy import TravelTimeSdk

sdk = TravelTimeSdk('YOUR_APP_ID', 'YOUR_APP_KEY')

results = sdk.geocoding_reverse(lat=51.507281, lng=-0.132120)

print(results.features)

Time Filter (Postcodes)

Find reachable postcodes from origin (or to destination) and get statistics about such postcodes. Currently only supports United Kingdom.

Takes:

coordinates: List[Coordinates] - Location coordinates.
arrival_time: datetime - Be at arrival location at no later than given time. Cannot be specified with departure_time.
departure_time: datetime - Leave departure location at no earlier than given time. Cannot be specified with arrival_time.
travel_time: int - Maximum journey time (in seconds). Maximum value is 14400. Default value is 1800
transportation: Union - Transportation mode and related parameters.
properties: List[Property] - Properties to be returned about the postcodes. Default value is travel_time.
range: FullRange - When enabled, range adds an arrival window to the arrival time, and results are returned for any journeys that arrive during this window.

Returns:

results: List[PostcodesResult] - The results list of postcodes.

Example:

from datetime import datetime

from traveltimepy import Coordinates, PublicTransport, TravelTimeSdk

sdk = TravelTimeSdk('YOUR_APP_ID', 'YOUR_APP_KEY')

results = sdk.postcodes(
    coordinates=[Coordinates(lat=51.507609, lng=-0.128315)],
    departure_time=datetime.now(),
    transportation=PublicTransport()
)

print(results)

Time Filter (Postcode Districts)

Find districts that have a certain coverage from origin (or to destination) and get statistics about postcodes within such districts. Currently only supports United Kingdom.

Takes:

coordinates: List[Coordinates] - Location coordinates.
arrival_time: datetime - Be at arrival location at no later than given time. Cannot be specified with departure_time.
departure_time: datetime - Leave departure location at no earlier than given time. Cannot be specified with arrival_time.
travel_time: int - Maximum journey time (in seconds). Maximum value is 14400. Default value is 1800
transportation: Union - Transportation mode and related parameters.
reachable_postcodes_threshold: float - A number between 0.0 and 1.0. Default value is 0.1. For example, if 0.5 is used, only districts that have at least 50% postcodes that can be reached within the given travel_time will be included in the response. 0 will return districts that have at least a single reachable postcode.
properties: List[Property] - Properties to be returned about the districts. Default value is travel_time_all.
range: FullRange - When enabled, range adds an arrival window to the arrival time, and results are returned for any journeys that arrive during this window.

Returns:

results: List[DistrictsResult] - The results list of districts.

Example:

from datetime import datetime

from traveltimepy import Coordinates, PublicTransport, TravelTimeSdk

sdk = TravelTimeSdk('YOUR_APP_ID', 'YOUR_APP_KEY')

results = sdk.districts(
    coordinates=[Coordinates(lat=51.507609, lng=-0.128315)],
    departure_time=datetime.now(),
    transportation=PublicTransport()
)

print(results)

Time Filter (Postcode Sectors)

Find sectors that have a certain coverage from origin (or to destination) and get statistics about postcodes within such sectors. Currently only supports United Kingdom.

Takes:

coordinates: List[Coordinates] - Location coordinates.
arrival_time: datetime - Be at arrival location at no later than given time. Cannot be specified with departure_time.
departure_time: datetime - Leave departure location at no earlier than given time. Cannot be specified with arrival_time.
travel_time: int - Maximum journey time (in seconds). Maximum value is 14400. Default value is 1800
transportation: Union - Transportation mode and related parameters.
reachable_postcodes_threshold: float - A number between 0.0 and 1.0. Default value is 0.1. For example, if 0.5 is used, only sectors that have at least 50% postcodes that can be reached within the given travel_time will be included in the response. 0 will return sectors that have at least a single reachable postcode.
properties: List[Property] - Properties to be returned about the sectors. Default value is travel_time_all.
range: FullRange - When enabled, range adds an arrival window to the arrival time, and results are returned for any journeys that arrive during this window.

Returns:

results: List[SectorsResult] - The results list of postcode sectors.

Example:

from datetime import datetime

from traveltimepy import Coordinates, PublicTransport, TravelTimeSdk

sdk = TravelTimeSdk('YOUR_APP_ID', 'YOUR_APP_KEY')

results = sdk.sectors(
    coordinates=[Coordinates(lat=51.507609, lng=-0.128315)],
    departure_time=datetime.now(),
    transportation=PublicTransport()
)

print(results)

Map Info

Returns information about currently supported countries.

It is useful when you have an application that can do searches in any country that we support, you can use Supported Locations to get the map name for a certain point and then use this endpoint to check what features are available for that map. That way you could show fares for routes in the maps that support it.

Returns:

maps: List[Map]
- name - An internal map id. The first two characters usually correspond to the ISO 3166-2 standard (e.g th, ie) sometimes followed by additional characters (e.g ca_pst, us_pst). To get features of a specific map, use the map info endpoint.
- features - Features that are supported in the specified map

Example:

from traveltimepy import TravelTimeSdk

sdk = TravelTimeSdk('YOUR_APP_ID', 'YOUR_APP_KEY')

results = sdk.map_info()

print(results)

Supported Locations

Find out what points are supported by our api. The returned map name for a point can be used to determine what features are supported.

Takes:

locations: List[Location] - Each location requires an id and lat/lng values

Returns:

locations: List[SupportedLocation]
- id - Location id that you specified in the request.
- map_name - An internal map id. The first two characters usually correspond to the ISO 3166-2 standard (e.g th, ie) sometimes followed by additional characters (e.g ca_pst, us_pst). To get features of a specific map, use the map info endpoint.
- additional_map_names - In case the location is in more than one map, other map ids are listed here.
unsupported_locations: List[str] - List that contains ids of locations that are unsupported.

Example:

from traveltimepy import Location, Coordinates, TravelTimeSdk

sdk = TravelTimeSdk('YOUR_APP_ID', 'YOUR_APP_KEY')

locations = [
    Location(id='Kaunas', coords=Coordinates(lat=54.900008, lng=23.957734)),
    Location(id='London', coords=Coordinates(lat=51.506756, lng=-0.12805)),
    Location(id='Bangkok', coords=Coordinates(lat=13.761866, lng=100.544818)),
    Location(id='Lisbon', coords=Coordinates(lat=38.721869, lng=-9.138549)),
]

results = sdk.supported_locations(locations)

print(results.locations)
print(results.unsupported_locations)

Project details

Release history Release notifications | RSS feed

3.9.8

May 6, 2024

3.9.6

Apr 25, 2024

3.9.4

Apr 11, 2024

3.9.3

Mar 4, 2024

3.9.2

Feb 12, 2024

3.9.1

Jan 31, 2024

3.9.0

Nov 30, 2023

3.8.1

Nov 14, 2023

3.8.0

Nov 13, 2023

3.7.1

Nov 6, 2023

3.7.0

Oct 30, 2023

3.6.2

Oct 23, 2023

3.6.1

Oct 20, 2023

3.6.0

Oct 3, 2023

3.5.1

Sep 26, 2023

3.5.0

Sep 11, 2023

3.4.0

Jun 26, 2023

3.3.0

May 15, 2023

3.3.0b1 pre-release

May 29, 2023

3.2.2

Apr 26, 2023

3.2.1

Apr 4, 2023

3.2.0

Mar 22, 2023

3.1.0

Mar 16, 2023

3.0.6

Mar 13, 2023

3.0.5

Mar 13, 2023

This version

3.0.4

Mar 6, 2023

3.0.3

Feb 13, 2023

3.0.2

Feb 9, 2023

3.0.1

Feb 8, 2023

3.0.1rc2 pre-release

Feb 8, 2023

3.0.1rc1 pre-release

Feb 8, 2023

3.0.0

Feb 7, 2023

3.0.0rc2 pre-release

Jan 27, 2023

3.0.0rc1 pre-release

Jan 24, 2023

2.0.7

Jan 23, 2023

2.0.6

Dec 20, 2022

2.0.5

Dec 14, 2022

2.0.4

Dec 13, 2022

2.0.3

Dec 13, 2022

2.0.2

Dec 13, 2022

2.0.1

Dec 6, 2022

1.0.0

Sep 20, 2022

1.0.0b1 pre-release

Sep 20, 2022

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

traveltimepy-3.0.4.tar.gz (24.7 kB view hashes)

Uploaded Mar 6, 2023 Source

Built Distribution

traveltimepy-3.0.4-py3-none-any.whl (35.1 kB view hashes)

Uploaded Mar 6, 2023 Python 3

Hashes for traveltimepy-3.0.4.tar.gz

Hashes for traveltimepy-3.0.4.tar.gz
Algorithm	Hash digest
SHA256	`7c18f760799392b18c59c276d9406e014e16b9822c5833c3aa21833aa5bcea0d`
MD5	`691397e016fd3c5c2ddb06311db12fc0`
BLAKE2b-256	`0ee0eb5421aefcdc680baa707e4475cee54accc024bb3bad2ca17e06ecf5251e`

Hashes for traveltimepy-3.0.4-py3-none-any.whl

Hashes for traveltimepy-3.0.4-py3-none-any.whl
Algorithm	Hash digest
SHA256	`258a44ec3a5be40f589c8b2e9001552fa9f2f329955c973a305fe9eeaaa10cf7`
MD5	`e807d18d3102e33ea8eaf9db5f348035`
BLAKE2b-256	`0f63ff3889f172cd48cba69fd0e3d0c059083c376f4b394898ae2146f768769f`

traveltimepy 3.0.4

Navigation

Verified details

Maintainers

Unverified details

Meta

Project description

Travel Time Python SDK

Usage

Installation

Linux/Mac

Windows

Sdk set up

Asynchronous calls

Example:

Takes:

Returns:

Example:

Takes:

Returns:

Example:

Takes:

Returns:

Example:

Takes:

Returns:

Example:

Takes:

Returns:

Example:

Takes:

Returns:

Example:

Takes:

Returns:

Example:

Takes:

Returns:

Example:

Takes:

Returns:

Example:

Takes:

Returns:

Example:

Takes:

Returns:

Example:

Takes:

Returns:

Example:

Returns:

Example:

Takes:

Returns:

Example:

Project details

Verified details

Maintainers

Unverified details

Meta

Release history Release notifications | RSS feed

Download files

Source Distribution

Built Distribution