| Name | traveltimepy JSON |
| Version |
3.9.17
JSON |
| download |
| home_page | None |
| Summary | Python Interface to Travel Time. |
| upload_time | 2024-10-21 12:12:43 |
| maintainer | None |
| docs_url | None |
| author | TravelTime |
| requires_python | >=3.8 |
| license | MIT |
| keywords |
traveltimepy
api
maps
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Travel Time Python SDK
[](https://badge.fury.io/py/traveltimepy) [](https://github.com/traveltime-dev/traveltime-python-sdk/actions/workflows/ci.yml) [](https://img.shields.io/badge/python-3.8+-blue)
[Travel Time](https://docs.traveltime.com/api/overview/introduction) 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.
#### Takes:
* app_id: str - Application Id
* api_key: str - Api Key
* limit_per_host: int - Number of simultaneous connections to one host.
* rate_limit: int - Number of searches which can be made in a time window.
* time_window: int - Duration, in seconds, of the time period in which to limit the rate.
* retry_attempts: int - Number of retries for failed requests.
* host: str - TravelTime host, default value is api.traveltimeapp.com.
* timeout: int - Maximum session time until timeout. Default value is 300 (5 minutes).
```python
from traveltimepy import TravelTimeSdk
sdk = TravelTimeSdk(app_id="YOUR_APP_ID", api_key="YOUR_APP_KEY")
```
### [Isochrones (Time Map)](https://docs.traveltime.com/api/reference/isochrones)
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](#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.
* [level_of_detail](#level-of-detail): LevelOfDetail - When enabled, allows the user to specify how detailed the isochrones should be.
* [snapping](#snapping): Snapping - Adjusts the process of looking up the nearest roads from the departure / arrival points.
### JSON response
#### Returns:
* results: List[TimeMapResult] - The list of isochrone shapes.
#### Example:
```python
import asyncio
from datetime import datetime
from traveltimepy import Driving, Coordinates, TravelTimeSdk
async def main():
sdk = TravelTimeSdk("YOUR_APP_ID", "YOUR_APP_KEY")
results = 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()
)
print(results)
asyncio.run(main())
```
### GEOJSON response
#### Returns:
* results: FeatureCollection - The list of Features.
#### Example:
```python
import asyncio
from datetime import datetime
from traveltimepy import Driving, Coordinates, TravelTimeSdk
async def main():
sdk = TravelTimeSdk("YOUR_APP_ID", "YOUR_APP_KEY")
results = await sdk.time_map_geojson_async(
coordinates=[Coordinates(lat=51.507609, lng=-0.128315), Coordinates(lat=51.517609, lng=-0.138315)],
arrival_time=datetime.now(),
transportation=Driving()
)
print(results)
asyncio.run(main())
```
### WKT response
#### Returns:
* results: TimeMapWKTResponse - TimeMapWktResponse with isochrone shapes.
#### Example:
```python
import asyncio
from datetime import datetime
from traveltimepy import Driving, Coordinates, TravelTimeSdk
async def main():
sdk = TravelTimeSdk("YOUR_APP_ID", "YOUR_APP_KEY")
response = await sdk.time_map_wkt_async(
coordinates=[Coordinates(lat=51.507609, lng=-0.128315), Coordinates(lat=51.517609, lng=-0.138315)],
arrival_time=datetime.now(),
transportation=Driving()
)
response.pretty_print() # for a custom formatted response
print(response) # default Python print
asyncio.run(main())
```
### WKT_NO_HOLES response
#### Returns:
* results: TimeMapWKTResponse - TimeMapWktResponse with isochrone shapes (no holes).
#### Example:
```python
import asyncio
from datetime import datetime
from traveltimepy import Driving, Coordinates, TravelTimeSdk
async def main():
sdk = TravelTimeSdk("YOUR_APP_ID", "YOUR_APP_KEY")
response = await sdk.time_map_wkt_no_holes_async(
coordinates=[Coordinates(lat=51.507609, lng=-0.128315), Coordinates(lat=51.517609, lng=-0.138315)],
arrival_time=datetime.now(),
transportation=Driving()
)
response.pretty_print() # for a custom formatted response
print(response) # default Python print
asyncio.run(main())
```
### [Isochrones (Intersection)](https://docs.traveltime.com/api/reference/isochrones)
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](#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.
* [snapping](#snapping): Snapping - Adjusts the process of looking up the nearest roads from the departure / arrival points.
#### Returns:
* results: List[TimeMapResult] - The list of isochrone shapes.
#### Example:
```python
import asyncio
from datetime import datetime
from traveltimepy import Driving, Coordinates, TravelTimeSdk
async def main():
sdk = TravelTimeSdk("YOUR_APP_ID", "YOUR_APP_KEY")
results = await sdk.intersection_async(
coordinates=[Coordinates(lat=51.507609, lng=-0.128315), Coordinates(lat=51.517609, lng=-0.138315)],
arrival_time=datetime.now(),
transportation=Driving()
)
print(results)
asyncio.run(main())
```
### [Isochrones (Union)](https://docs.traveltime.com/api/reference/isochrones)
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](#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.
* [snapping](#snapping): Snapping - Adjusts the process of looking up the nearest roads from the departure / arrival points.
#### Returns:
* results: List[TimeMapResult] - The list of isochrone shapes.
#### Example:
```python
import asyncio
from datetime import datetime
from traveltimepy import Driving, Coordinates, TravelTimeSdk
async def main():
sdk = TravelTimeSdk("YOUR_APP_ID", "YOUR_APP_KEY")
results = await sdk.union_async(
coordinates=[Coordinates(lat=51.507609, lng=-0.128315), Coordinates(lat=51.517609, lng=-0.138315)],
arrival_time=datetime.now(),
transportation=Driving()
)
print(results)
asyncio.run(main())
```
### [Time Map (Fast)](https://docs.traveltime.com/api/reference/isochrones-fast)
A very fast version of `time_map()`. However, the request parameters are much more limited.
#### Takes:
* coordinates: List[Coordinates] - Isochrones coordinates.
* [transportation]: Transportation - Transportation mode and related parameters.
* travel_time: int - Maximum journey time (in seconds). Maximum value is 10800. Default value is 3600.
* one_to_many: boolean - returns the reachable area for journeys arriving at the chosen arrival location if false,
returns the reachable area for journeys departing from the chosen departure location if true.
* [level_of_detail](#level-of-detail): LevelOfDetail - When enabled, allows the user to specify how detailed the isochrones should be.
* [snapping](#snapping): Snapping - Adjusts the process of looking up the nearest roads from the departure / arrival points.
### JSON response
#### Returns:
* results: List[TimeMapResult] - The list of isochrone shapes.
#### Example:
```python
import asyncio
from traveltimepy import Coordinates, TravelTimeSdk
from traveltimepy.dto.requests.time_map_fast import Transportation
async def main():
sdk = TravelTimeSdk("YOUR_APP_ID", "YOUR_APP_KEY")
results = await sdk.time_map_fast_async(
coordinates=[Coordinates(lat=51.507609, lng=-0.128315), Coordinates(lat=51.517609, lng=-0.138315)],
transportation=Transportation(type="driving+ferry"),
travel_time=900
)
print(results)
asyncio.run(main())
```
### GEOJSON response
#### Returns:
* results: FeatureCollection - The list of Features.
#### Example:
```python
import asyncio
from traveltimepy import Coordinates, TravelTimeSdk
from traveltimepy.dto.requests.time_map_fast import Transportation
async def main():
sdk = TravelTimeSdk("YOUR_APP_ID", "YOUR_APP_KEY")
results = await sdk.time_map_fast_geojson_async(
coordinates=[Coordinates(lat=51.507609, lng=-0.128315), Coordinates(lat=51.517609, lng=-0.138315)],
transportation=Transportation(type="driving+ferry"),
travel_time=900
)
print(results)
asyncio.run(main())
```
### [Distance Map](https://docs.traveltime.com/api/reference/distance-map)
Given origin coordinates, find shapes of zones reachable within corresponding travel distance.
#### Takes:
* coordinates: List[Coordinates] - Coordinates of the arrival or departure location.
* 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_distance: int - Maximum journey distance (in meters). Maximum value is 800000 (800km). Minimum value is 75.
Default value is 900.
* [transportation](#transportation): Union - Transportation mode and related parameters.
* [level_of_detail](#level-of-detail): LevelOfDetail - When enabled, allows the user to specify how detailed the isochrones should be.
* [snapping](#snapping): Snapping - Adjusts the process of looking up the nearest roads from the departure / arrival points.
#### Returns:
* results: List[TimeMapResult] - The list of isochrone shapes
#### Example:
```python
import asyncio
from datetime import datetime
from traveltimepy import Driving, Coordinates, TravelTimeSdk
async def main():
sdk = TravelTimeSdk("YOUR_APP_ID", "YOUR_APP_KEY")
results = await sdk.distance_map_async(
coordinates=[Coordinates(lat=51.507609, lng=-0.128315), Coordinates(lat=51.517609, lng=-0.138315)],
arrival_time=datetime.now(),
transportation=Driving()
)
print(results)
asyncio.run(main())
```
### [Distance Matrix (Time Filter)](https://docs.traveltime.com/api/reference/travel-time-distance-matrix)
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](#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 points. 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.
* snapping: Snapping - Adjusts the process of looking up the nearest roads from the departure / arrival points.
* [snapping](#snapping): Snapping - Adjusts the process of looking up the nearest roads from the departure / arrival points.
#### Returns:
* results: List[TimeFilterResult] - The results list of reachable and unreachable locations.
#### Example:
```python
import asyncio
from datetime import datetime
from traveltimepy import Location, Coordinates, PublicTransport, Property, FullRange, TravelTimeSdk
async def main():
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 = await sdk.time_filter_async(
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)
asyncio.run(main())
```
### [Time Filter (Fast)](https://docs.traveltime.com/api/reference/time-filter-fast)
A very fast version of `time_filter()`. However, the request parameters are much more limited.
#### 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]: Transportation - 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 points. 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 True.
* [snapping](#snapping): Snapping - Adjusts the process of looking up the nearest roads from the departure / arrival points.
#### Returns:
* results: List[TimeFilterFastResult] - The results list of reachable and unreachable locations.
#### Example:
```python
import asyncio
from traveltimepy import Location, Coordinates, Transportation, TravelTimeSdk
async def main():
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 = await sdk.time_filter_fast_async(
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)
asyncio.run(main())
```
### [Time Filter Fast (Proto)](https://docs.traveltime.com/api/reference/travel-time-distance-matrix-proto)
A fast version of time filter communicating using [protocol buffers](https://github.com/protocolbuffers/protobuf).
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.
* 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 True.
* properties: List[PropertyProto] - specifies which extra properties should be calculated in the response.
#### Returns:
* results: TimeFilterProtoResponse - The response contains:
* list of travel times, where each position denotes either a travel time (in seconds)
of a journey, or if travel time is negative, that the journey from the origin to the destination point is impossible.
* (optional) list of distances where each position denotes distance (in meters) to the specified location.
#### Example:
```python
import asyncio
from traveltimepy import ProtoCountry, Coordinates, ProtoTransportation, TravelTimeSdk, PropertyProto
async def main():
sdk = TravelTimeSdk("YOUR_APP_ID", "YOUR_APP_KEY")
travel_times = await sdk.time_filter_proto_async(
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,
properties=[PropertyProto.DISTANCE],
)
print(travel_times)
asyncio.run(main())
```
### [Routes](https://docs.traveltime.com/api/reference/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](#transportation): Union - Transportation mode and related parameters.
* properties: List[Property] - Properties to be returned about the locations. 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.
* [snapping](#snapping): Snapping - Adjusts the process of looking up the nearest roads from the departure / arrival points.
#### Returns:
* results: List[RoutesResult] - The results list of routes.
#### Example:
```python
import asyncio
from datetime import datetime
from traveltimepy import Location, Coordinates, PublicTransport, TravelTimeSdk
async def main():
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 = await sdk.routes_async(
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)
asyncio.run(main())
```
### [Geocoding (Search)](https://docs.traveltime.com/api/reference/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:
```python
import asyncio
from traveltimepy import TravelTimeSdk
async def main():
sdk = TravelTimeSdk("YOUR_APP_ID", "YOUR_APP_KEY")
results = await sdk.geocoding_async(query="Parliament square", limit=30)
print(results.features)
asyncio.run(main())
```
### [Reverse Geocoding](https://docs.traveltime.com/api/reference/geocoding-reverse)
Match a latitude, longitude pair to an address.
#### Takes:
* lat: float - Latitude
* lng: float - Longitude
#### Returns:
* Matched locations in a geojson format
#### Example:
```python
import asyncio
from traveltimepy import TravelTimeSdk
async def main():
sdk = TravelTimeSdk("YOUR_APP_ID", "YOUR_APP_KEY")
results = await sdk.geocoding_reverse_async(lat=51.507281, lng=-0.132120)
print(results.features)
asyncio.run(main())
```
### [Time Filter (Postcodes)](https://docs.traveltime.com/api/reference/postcode-search)
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](#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:
```python
import asyncio
from datetime import datetime
from traveltimepy import Coordinates, PublicTransport, TravelTimeSdk
async def main():
sdk = TravelTimeSdk("YOUR_APP_ID", "YOUR_APP_KEY")
results = await sdk.postcodes_async(
coordinates=[Coordinates(lat=51.507609, lng=-0.128315)],
departure_time=datetime.now(),
transportation=PublicTransport()
)
print(results)
asyncio.run(main())
```
### [Time Filter (Postcode Districts)](https://docs.traveltime.com/api/reference/postcode-district-filter)
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](#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:
```python
import asyncio
from datetime import datetime
from traveltimepy import Coordinates, PublicTransport, TravelTimeSdk
async def main():
sdk = TravelTimeSdk("YOUR_APP_ID", "YOUR_APP_KEY")
results = await sdk.postcodes_districts_async(
coordinates=[Coordinates(lat=51.507609, lng=-0.128315)],
departure_time=datetime.now(),
transportation=PublicTransport()
)
print(results)
asyncio.run(main())
```
### [Time Filter (Postcode Sectors)](https://docs.traveltime.com/api/reference/postcode-sector-filter)
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](#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:
```python
import asyncio
from datetime import datetime
from traveltimepy import Coordinates, PublicTransport, TravelTimeSdk, ZonesProperty
async def main():
sdk = TravelTimeSdk("YOUR_APP_ID", "YOUR_APP_KEY")
results = await sdk.postcodes_sectors_async(
coordinates=[Coordinates(lat=51.507609, lng=-0.128315)],
departure_time=datetime.now(),
transportation=PublicTransport(),
properties=[ZonesProperty.TRAVEL_TIME_REACHABLE, ZonesProperty.TRAVEL_TIME_ALL]
)
print(results)
asyncio.run(main())
```
### [Map Info](https://docs.traveltime.com/api/reference/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:
```python
import asyncio
from traveltimepy import TravelTimeSdk
async def main():
sdk = TravelTimeSdk("YOUR_APP_ID", "YOUR_APP_KEY")
results = await sdk.map_info_async()
print(results)
asyncio.run(main())
```
### [Supported Locations](https://docs.traveltime.com/api/reference/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:
```python
import asyncio
from traveltimepy import Location, Coordinates, TravelTimeSdk
async def main():
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 = await sdk.supported_locations_async(locations)
print(results.locations)
print(results.unsupported_locations)
asyncio.run(main())
```
## Parameter usage examples
### Transportation
In [transportation.py](https://github.com/traveltime-dev/traveltime-python-sdk/blob/master/traveltimepy/dto/transportation.py)
you can find all implemented transportation types, their sub-parameters and their default values.
These examples don't apply to proto / fast endpoints. For more examples you can always refer to [Unit Tests](https://github.com/traveltime-dev/traveltime-python-sdk/tree/master/tests)
#### Driving
```python
from traveltimepy import Driving
transportation=Driving()
transportation=Driving(disable_border_crossing = True)
```
#### Walking
```python
from traveltimepy import Walking
transportation=Walking()
```
#### Cycling
```python
from traveltimepy import Cycling
transportation=Cycling()
```
#### Ferry
```python
from traveltimepy import Ferry
transportation=Ferry()
transportation=Ferry(type="cycling+ferry")
transportation=Ferry(type="driving+ferry")
transportation=Ferry(type="cycling+ferry", boarding_time = 300)
```
#### DrivingTrain
```python
from traveltimepy import DrivingTrain, MaxChanges
transportation=DrivingTrain()
transportation=DrivingTrain(
pt_change_delay = 300,
driving_time_to_station=1800,
parking_time=800,
walking_time=500,
max_changes=MaxChanges(enabled=True, limit=3)
)
```
#### PublicTransport
```python
from traveltimepy import PublicTransport, MaxChanges
transportation=PublicTransport() # type="public_transport" - any public transport
transportation=PublicTransport(type="train")
transportation=PublicTransport(type="bus")
transportation=PublicTransport(type="coach")
transportation=PublicTransport(
pt_change_delay = 300,
walking_time=500,
max_changes=MaxChanges(enabled=True, limit=3)
)
```
#### CyclingPublicTransport
```python
from traveltimepy import CyclingPublicTransport, MaxChanges
transportation=CyclingPublicTransport()
transportation=CyclingPublicTransport(
walking_time=500,
pt_change_delay = 300,
cycling_time_to_station=300,
parking_time=800,
boarding_time=300,
max_changes=MaxChanges(enabled=True, limit=3)
)
```
### Level of Detail
`level_of_detail` can be used to specify how detailed the isochrone result should be.
For a more detailed description of how to use this parameter, you can refer to our [API Docs](https://docs.traveltime.com/api/reference/isochrones#arrival_searches-level_of_detail)
#### Examples
```python
from traveltimepy import LevelOfDetail
# scale_type "simple"
level_of_detail=LevelOfDetail(scale_type="simple", level="lowest")
# scale_type "simple_numeric"
level_of_detail=LevelOfDetail(scale_type="simple_numeric", level=0)
# scale_type "coarse_grid"
level_of_detail=LevelOfDetail(scale_type="coarse_grid", square_size=600)
```
### Snapping
`snapping` Adjusts the process of looking up the nearest roads from the departure / arrival points.
For a more detailed description of how to use this parameter, you can refer to our [API Docs](https://docs.traveltime.com/api/reference/isochrones#departure_searches-snapping)
#### Examples
```python
from traveltimepy.dto.common import Snapping, SnappingAcceptRoads, SnappingPenalty
snapping=Snapping(
penalty=SnappingPenalty.ENABLED, # default
accept_roads=SnappingAcceptRoads.BOTH_DRIVABLE_AND_WALKABLE # default
)
snapping=Snapping(
penalty=SnappingPenalty.DISABLED,
accept_roads=SnappingAcceptRoads.ANY_DRIVABLE
)
```
Raw data
{
"_id": null,
"home_page": null,
"name": "traveltimepy",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "traveltimepy, api, maps",
"author": "TravelTime",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/be/ed/9f470d8f11078fe8690e8549f6a6bf9a445207b552f9eb98b9222bc621e6/traveltimepy-3.9.17.tar.gz",
"platform": null,
"description": "# Travel Time Python SDK\n\n[](https://badge.fury.io/py/traveltimepy) [](https://github.com/traveltime-dev/traveltime-python-sdk/actions/workflows/ci.yml) [](https://img.shields.io/badge/python-3.8+-blue)\n\n[Travel Time](https://docs.traveltime.com/api/overview/introduction) Python SDK helps users find locations by journey\ntime rather than using \u2018as the crow flies\u2019 distance. \nTime-based searching gives users more opportunities for personalisation and delivers a more relevant search.\n\n## Usage\n\n## Installation\n\nInstall Travel Time Python SDK in a `virtualenv` using `pip`. `virtualenv` is a tool to create isolated Python\nenvironments.\n\n`virtualenv` allows to install Travel Time Python SDK without needing system install permissions, and without clashing\nwith the installed system dependencies.\n\n### Linux/Mac\n\n```\npip3 install virtualenv\nvirtualenv <your-env>\nsource <your-env>/bin/activate\n<your-env>/bin/pip install traveltimepy\n```\n\n### Windows\n\n```\npip install virtualenv\nvirtualenv <your-env>\n<your-env>\\Scripts\\activate\n<your-env>\\Scripts\\pip.exe install traveltimepy\n```\n\n### Sdk set up\n\nIn order to authenticate with Travel Time API, you will have to supply the Application Id and Api Key.\n\n#### Takes:\n\n* app_id: str - Application Id\n* api_key: str - Api Key\n* limit_per_host: int - Number of simultaneous connections to one host.\n* rate_limit: int - Number of searches which can be made in a time window.\n* time_window: int - Duration, in seconds, of the time period in which to limit the rate.\n* retry_attempts: int - Number of retries for failed requests.\n* host: str - TravelTime host, default value is api.traveltimeapp.com.\n* timeout: int - Maximum session time until timeout. Default value is 300 (5 minutes).\n\n```python\nfrom traveltimepy import TravelTimeSdk\n\nsdk = TravelTimeSdk(app_id=\"YOUR_APP_ID\", api_key=\"YOUR_APP_KEY\")\n```\n\n### [Isochrones (Time Map)](https://docs.traveltime.com/api/reference/isochrones)\n\nGiven origin coordinates, find shapes of zones reachable within corresponding travel time.\n\n#### Takes:\n\n* coordinates: List[Coordinates] - Isochrones coordinates.\n* arrival_time: datetime - Be at arrival location at no later than given time. Cannot be specified with departure_time.\n* departure_time: datetime - Leave departure location at no earlier than given time. Cannot be specified with\n arrival_time.\n* travel_time: int - Maximum journey time (in seconds). Maximum value is 14400. Default value is 3600\n* [transportation](#transportation): Union - Transportation mode and related parameters.\n* search_range: Range - When enabled, range adds an arrival window to the arrival time, and results are returned for any\n journeys that arrive during this window.\n* [level_of_detail](#level-of-detail): LevelOfDetail - When enabled, allows the user to specify how detailed the isochrones should be.\n* [snapping](#snapping): Snapping - Adjusts the process of looking up the nearest roads from the departure / arrival points.\n\n### JSON response\n\n#### Returns:\n\n* results: List[TimeMapResult] - The list of isochrone shapes.\n\n#### Example:\n\n```python\nimport asyncio\nfrom datetime import datetime\n\nfrom traveltimepy import Driving, Coordinates, TravelTimeSdk\n\n\nasync def main():\n sdk = TravelTimeSdk(\"YOUR_APP_ID\", \"YOUR_APP_KEY\")\n\n results = await sdk.time_map_async(\n coordinates=[Coordinates(lat=51.507609, lng=-0.128315), Coordinates(lat=51.517609, lng=-0.138315)],\n arrival_time=datetime.now(),\n transportation=Driving()\n )\n print(results)\n\n\nasyncio.run(main())\n```\n\n### GEOJSON response\n\n#### Returns:\n\n* results: FeatureCollection - The list of Features.\n\n#### Example:\n\n```python\nimport asyncio\nfrom datetime import datetime\n\nfrom traveltimepy import Driving, Coordinates, TravelTimeSdk\n\n\nasync def main():\n sdk = TravelTimeSdk(\"YOUR_APP_ID\", \"YOUR_APP_KEY\")\n\n results = await sdk.time_map_geojson_async(\n coordinates=[Coordinates(lat=51.507609, lng=-0.128315), Coordinates(lat=51.517609, lng=-0.138315)],\n arrival_time=datetime.now(),\n transportation=Driving()\n )\n print(results)\n\n\nasyncio.run(main())\n```\n\n### WKT response\n\n#### Returns:\n\n* results: TimeMapWKTResponse - TimeMapWktResponse with isochrone shapes.\n\n#### Example:\n\n```python\nimport asyncio\nfrom datetime import datetime\n\nfrom traveltimepy import Driving, Coordinates, TravelTimeSdk\n\n\nasync def main():\n sdk = TravelTimeSdk(\"YOUR_APP_ID\", \"YOUR_APP_KEY\")\n\n response = await sdk.time_map_wkt_async(\n coordinates=[Coordinates(lat=51.507609, lng=-0.128315), Coordinates(lat=51.517609, lng=-0.138315)],\n arrival_time=datetime.now(),\n transportation=Driving()\n )\n response.pretty_print() # for a custom formatted response \n \n print(response) # default Python print\n\n \nasyncio.run(main())\n```\n\n### WKT_NO_HOLES response\n\n#### Returns:\n\n* results: TimeMapWKTResponse - TimeMapWktResponse with isochrone shapes (no holes).\n\n#### Example:\n\n```python\nimport asyncio\nfrom datetime import datetime\n\nfrom traveltimepy import Driving, Coordinates, TravelTimeSdk\n\n\nasync def main():\n sdk = TravelTimeSdk(\"YOUR_APP_ID\", \"YOUR_APP_KEY\")\n\n response = await sdk.time_map_wkt_no_holes_async(\n coordinates=[Coordinates(lat=51.507609, lng=-0.128315), Coordinates(lat=51.517609, lng=-0.138315)],\n arrival_time=datetime.now(),\n transportation=Driving()\n )\n response.pretty_print() # for a custom formatted response \n\n print(response) # default Python print\n\n\nasyncio.run(main())\n```\n\n### [Isochrones (Intersection)](https://docs.traveltime.com/api/reference/isochrones)\n\nGiven origin coordinates, find intersections of specified shapes.\n\n#### Takes:\n\n* coordinates: List[Coordinates] - Intersection coordinates. The size of list cannot be more than 10.\n* arrival_time: datetime - Be at arrival location at no later than given time. Cannot be specified with departure_time.\n* departure_time: datetime - Leave departure location at no earlier than given time. Cannot be specified with\n arrival_time.\n* travel_time: int - Maximum journey time (in seconds). Maximum value is 14400. Default value is 3600\n* [transportation](#transportation): Union - Transportation mode and related parameters.\n* search_range: Range - When enabled, range adds an arrival window to the arrival time, and results are returned for any\n journeys that arrive during this window.\n* [snapping](#snapping): Snapping - Adjusts the process of looking up the nearest roads from the departure / arrival points.\n\n#### Returns:\n\n* results: List[TimeMapResult] - The list of isochrone shapes.\n\n#### Example:\n\n```python\nimport asyncio\nfrom datetime import datetime\n\nfrom traveltimepy import Driving, Coordinates, TravelTimeSdk\n\n\nasync def main():\n sdk = TravelTimeSdk(\"YOUR_APP_ID\", \"YOUR_APP_KEY\")\n results = await sdk.intersection_async(\n coordinates=[Coordinates(lat=51.507609, lng=-0.128315), Coordinates(lat=51.517609, lng=-0.138315)],\n arrival_time=datetime.now(),\n transportation=Driving()\n )\n\n print(results)\n\n\nasyncio.run(main())\n```\n\n### [Isochrones (Union)](https://docs.traveltime.com/api/reference/isochrones)\n\nGiven origin coordinates, find unions of specified shapes.\n\nFinds the union of specified shapes.\n\n#### Takes:\n\n* coordinates: List[Coordinates] - Union coordinates. The size of list cannot be more than 10.\n* arrival_time: datetime - Be at arrival location at no later than given time. Cannot be specified with departure_time.\n* departure_time: datetime - Leave departure location at no earlier than given time. Cannot be specified with\n arrival_time.\n* travel_time: int - Maximum journey time (in seconds). Maximum value is 14400. Default value is 3600\n* [transportation](#transportation): Union - Transportation mode and related parameters.\n* search_range: Range - When enabled, range adds an arrival window to the arrival time, and results are returned for any\n journeys that arrive during this window.\n* [snapping](#snapping): Snapping - Adjusts the process of looking up the nearest roads from the departure / arrival points.\n\n#### Returns:\n\n* results: List[TimeMapResult] - The list of isochrone shapes.\n\n#### Example:\n\n```python\nimport asyncio\nfrom datetime import datetime\n\nfrom traveltimepy import Driving, Coordinates, TravelTimeSdk\n\n\nasync def main():\n sdk = TravelTimeSdk(\"YOUR_APP_ID\", \"YOUR_APP_KEY\")\n results = await sdk.union_async(\n coordinates=[Coordinates(lat=51.507609, lng=-0.128315), Coordinates(lat=51.517609, lng=-0.138315)],\n arrival_time=datetime.now(),\n transportation=Driving()\n )\n\n print(results)\n\n\nasyncio.run(main())\n```\n\n### [Time Map (Fast)](https://docs.traveltime.com/api/reference/isochrones-fast)\n\nA very fast version of `time_map()`. However, the request parameters are much more limited.\n\n#### Takes:\n\n* coordinates: List[Coordinates] - Isochrones coordinates.\n* [transportation]: Transportation - Transportation mode and related parameters.\n* travel_time: int - Maximum journey time (in seconds). Maximum value is 10800. Default value is 3600.\n* one_to_many: boolean - returns the reachable area for journeys arriving at the chosen arrival location if false,\nreturns the reachable area for journeys departing from the chosen departure location if true.\n* [level_of_detail](#level-of-detail): LevelOfDetail - When enabled, allows the user to specify how detailed the isochrones should be.\n* [snapping](#snapping): Snapping - Adjusts the process of looking up the nearest roads from the departure / arrival points.\n\n### JSON response\n\n#### Returns:\n\n* results: List[TimeMapResult] - The list of isochrone shapes.\n\n#### Example:\n\n```python\nimport asyncio\n\nfrom traveltimepy import Coordinates, TravelTimeSdk\nfrom traveltimepy.dto.requests.time_map_fast import Transportation\n\nasync def main():\n sdk = TravelTimeSdk(\"YOUR_APP_ID\", \"YOUR_APP_KEY\")\n\n results = await sdk.time_map_fast_async(\n coordinates=[Coordinates(lat=51.507609, lng=-0.128315), Coordinates(lat=51.517609, lng=-0.138315)],\n transportation=Transportation(type=\"driving+ferry\"),\n travel_time=900\n )\n\n print(results)\n\nasyncio.run(main())\n```\n\n### GEOJSON response\n\n#### Returns:\n\n* results: FeatureCollection - The list of Features.\n\n#### Example:\n\n```python\nimport asyncio\n\nfrom traveltimepy import Coordinates, TravelTimeSdk\nfrom traveltimepy.dto.requests.time_map_fast import Transportation\n\nasync def main():\n sdk = TravelTimeSdk(\"YOUR_APP_ID\", \"YOUR_APP_KEY\")\n\n results = await sdk.time_map_fast_geojson_async(\n coordinates=[Coordinates(lat=51.507609, lng=-0.128315), Coordinates(lat=51.517609, lng=-0.138315)],\n transportation=Transportation(type=\"driving+ferry\"),\n travel_time=900\n )\n\n print(results)\n\nasyncio.run(main())\n```\n\n### [Distance Map](https://docs.traveltime.com/api/reference/distance-map)\n\nGiven origin coordinates, find shapes of zones reachable within corresponding travel distance.\n\n#### Takes:\n\n* coordinates: List[Coordinates] - Coordinates of the arrival or departure location.\n* arrival_time: datetime - Be at arrival location at no later than given time. Cannot be specified with departure_time.\n* departure_time: datetime - Leave departure location at no earlier than given time. Cannot be specified with\n arrival_time.\n* travel_distance: int - Maximum journey distance (in meters). Maximum value is 800000 (800km). Minimum value is 75. \n Default value is 900.\n* [transportation](#transportation): Union - Transportation mode and related parameters.\n* [level_of_detail](#level-of-detail): LevelOfDetail - When enabled, allows the user to specify how detailed the isochrones should be.\n* [snapping](#snapping): Snapping - Adjusts the process of looking up the nearest roads from the departure / arrival points.\n\n#### Returns:\n\n* results: List[TimeMapResult] - The list of isochrone shapes\n\n#### Example:\n\n```python\nimport asyncio\nfrom datetime import datetime\n\nfrom traveltimepy import Driving, Coordinates, TravelTimeSdk\n\n\nasync def main():\n sdk = TravelTimeSdk(\"YOUR_APP_ID\", \"YOUR_APP_KEY\")\n\n results = await sdk.distance_map_async(\n coordinates=[Coordinates(lat=51.507609, lng=-0.128315), Coordinates(lat=51.517609, lng=-0.138315)],\n arrival_time=datetime.now(),\n transportation=Driving()\n )\n print(results)\n\n\nasyncio.run(main())\n```\n\n### [Distance Matrix (Time Filter)](https://docs.traveltime.com/api/reference/travel-time-distance-matrix)\n\nGiven origin and destination points filter out points that cannot be reached within specified time limit. Find out\ntravel times, distances and costs between an origin and up to 2,000 destination points.\n\n#### Takes:\n\n* locations: List[Locations] - All locations. Location ids must be unique.\n* search_ids: Dict[str, List[str]] - Search ids from a target location to destinations. You can define up to 2000\n destinations\n* arrival_time: datetime - Be at arrival location at no later than given time. Cannot be specified with departure_time.\n* departure_time: datetime - Leave departure location at no earlier than given time. Cannot be specified with\n arrival_time.\n* [transportation](#transportation): Union - Transportation mode and related parameters.\n* travel_time: int - Maximum journey time (in seconds). Maximum value is 14400. Default value is 3600.\n* properties: List[Property] - Properties to be returned about the points. Default value is travel_time.\n* range: FullRange - When enabled, range adds an arrival window to the arrival time, and results are returned for any\n journeys that arrive during this window.\n* snapping: Snapping - Adjusts the process of looking up the nearest roads from the departure / arrival points.\n* [snapping](#snapping): Snapping - Adjusts the process of looking up the nearest roads from the departure / arrival points.\n\n#### Returns:\n\n* results: List[TimeFilterResult] - The results list of reachable and unreachable locations.\n\n#### Example:\n\n```python\nimport asyncio\nfrom datetime import datetime\n\nfrom traveltimepy import Location, Coordinates, PublicTransport, Property, FullRange, TravelTimeSdk\n\n\nasync def main():\n sdk = TravelTimeSdk(\"YOUR_APP_ID\", \"YOUR_APP_KEY\")\n\n locations = [\n Location(id=\"London center\", coords=Coordinates(lat=51.508930, lng=-0.131387)),\n Location(id=\"Hyde Park\", coords=Coordinates(lat=51.508824, lng=-0.167093)),\n Location(id=\"ZSL London Zoo\", coords=Coordinates(lat=51.536067, lng=-0.153596))\n ]\n\n results = await sdk.time_filter_async(\n locations=locations,\n search_ids={\n \"London center\": [\"Hyde Park\", \"ZSL London Zoo\"],\n \"ZSL London Zoo\": [\"Hyde Park\", \"London center\"],\n },\n departure_time=datetime.now(),\n travel_time=3600,\n transportation=PublicTransport(type=\"bus\"),\n properties=[Property.TRAVEL_TIME],\n range=FullRange(enabled=True, max_results=3, width=600)\n )\n\n print(results)\n\n\nasyncio.run(main())\n```\n\n### [Time Filter (Fast)](https://docs.traveltime.com/api/reference/time-filter-fast)\n\nA very fast version of `time_filter()`. However, the request parameters are much more limited.\n\n#### Takes:\n\n* locations: List[Locations] - All locations. Location ids must be unique.\n* search_ids: Dict[str, List[str]] - Searches from a target location to destinations. You can define up to 100,000\n destinations\n* [transportation]: Transportation - Transportation mode and related parameters.\n* travel_time: int - Maximum journey time (in seconds). Maximum value is 10800. Default value is 3600.\n* properties: List[Property] - Properties to be returned about the points. Default value is travel_time.\n* one_to_many: boolean - if one_to_many is equal to true, then it'll be a forward search (one to many matrix), false -\n backward search (many to one matrix). Default value is True.\n* [snapping](#snapping): Snapping - Adjusts the process of looking up the nearest roads from the departure / arrival points.\n\n#### Returns:\n\n* results: List[TimeFilterFastResult] - The results list of reachable and unreachable locations.\n\n#### Example:\n\n```python\nimport asyncio\n\nfrom traveltimepy import Location, Coordinates, Transportation, TravelTimeSdk\n\nasync def main():\n sdk = TravelTimeSdk(\"YOUR_APP_ID\", \"YOUR_APP_KEY\")\n \n locations = [\n Location(id=\"London center\", coords=Coordinates(lat=51.508930, lng=-0.131387)),\n Location(id=\"Hyde Park\", coords=Coordinates(lat=51.508824, lng=-0.167093)),\n Location(id=\"ZSL London Zoo\", coords=Coordinates(lat=51.536067, lng=-0.153596))\n ]\n \n results = await sdk.time_filter_fast_async(\n locations=locations,\n search_ids={\n \"London center\": [\"Hyde Park\", \"ZSL London Zoo\"],\n \"ZSL London Zoo\": [\"Hyde Park\", \"London center\"],\n },\n transportation=Transportation(type=\"public_transport\"),\n one_to_many=False\n )\n \n print(results)\n \nasyncio.run(main())\n```\n\n### [Time Filter Fast (Proto)](https://docs.traveltime.com/api/reference/travel-time-distance-matrix-proto)\n\nA fast version of time filter communicating using [protocol buffers](https://github.com/protocolbuffers/protobuf).\n\nThe request parameters are much more limited and only travel time is returned. In addition, the results are only\napproximately correct (95% of the results are guaranteed to be within 5% of the routes returned by regular time filter).\nThis inflexibility comes with a benefit of faster response times (Over 5x faster compared to regular time filter) and\nlarger limits on the amount of destination points.\n\n#### Takes:\n\n* origin: Coordinates - Origin point.\n* destinations: List[Coordinates] - Destination points. Cannot be more than 200,000.\n* transportation: ProtoTransportation - Transportation type.\n* travel_time: int - Time limit. Maximum value is 7200.\n* country: ProtoCountry - Return the results that are within the specified country.\n* one_to_many: boolean - if one_to_many is equal to true, then it'll be a forward search (one to many matrix), false -\n backward search (many to one matrix). Default value is True.\n* properties: List[PropertyProto] - specifies which extra properties should be calculated in the response. \n\n#### Returns:\n\n* results: TimeFilterProtoResponse - The response contains:\n * list of travel times, where each position denotes either a travel time (in seconds)\n of a journey, or if travel time is negative, that the journey from the origin to the destination point is impossible. \n * (optional) list of distances where each position denotes distance (in meters) to the specified location. \n#### Example:\n\n```python\nimport asyncio\nfrom traveltimepy import ProtoCountry, Coordinates, ProtoTransportation, TravelTimeSdk, PropertyProto\n\nasync def main():\n sdk = TravelTimeSdk(\"YOUR_APP_ID\", \"YOUR_APP_KEY\")\n travel_times = await sdk.time_filter_proto_async(\n origin=Coordinates(lat=51.425709, lng=-0.122061),\n destinations=[\n Coordinates(lat=51.348605, lng=-0.314783),\n Coordinates(lat=51.337205, lng=-0.315793)\n ],\n transportation=ProtoTransportation.DRIVING_FERRY,\n travel_time=7200,\n country=ProtoCountry.UNITED_KINGDOM,\n properties=[PropertyProto.DISTANCE],\n )\n \n print(travel_times)\n\nasyncio.run(main())\n```\n\n### [Routes](https://docs.traveltime.com/api/reference/routes)\n\nReturns routing information between source and destinations.\n\n#### Takes:\n\n* locations: List[Locations] - All locations. Location ids must be unique.\n* search_ids: Dict[str, List[str]] - Searches from a target location to destinations.\n* arrival_time: datetime - Be at arrival location at no later than given time. Cannot be specified with departure_time.\n* departure_time: datetime - Leave departure location at no earlier than given time. Cannot be specified with\n arrival_time.\n* [transportation](#transportation): Union - Transportation mode and related parameters.\n* properties: List[Property] - Properties to be returned about the locations. Default value is travel_time.\n* range: FullRange - When enabled, range adds an arrival window to the arrival time, and results are returned for any\n journeys that arrive during this window.\n* [snapping](#snapping): Snapping - Adjusts the process of looking up the nearest roads from the departure / arrival points.\n\n#### Returns:\n\n* results: List[RoutesResult] - The results list of routes.\n\n#### Example:\n\n```python\nimport asyncio\nfrom datetime import datetime\n\nfrom traveltimepy import Location, Coordinates, PublicTransport, TravelTimeSdk\n\nasync def main():\n sdk = TravelTimeSdk(\"YOUR_APP_ID\", \"YOUR_APP_KEY\")\n \n locations = [\n Location(id=\"London center\", coords=Coordinates(lat=51.508930, lng=-0.131387)),\n Location(id=\"Hyde Park\", coords=Coordinates(lat=51.508824, lng=-0.167093)),\n Location(id=\"ZSL London Zoo\", coords=Coordinates(lat=51.536067, lng=-0.153596))\n ]\n\n results = await sdk.routes_async(\n locations=locations,\n search_ids={\n \"London center\": [\"Hyde Park\", \"ZSL London Zoo\"],\n \"ZSL London Zoo\": [\"Hyde Park\", \"London center\"],\n },\n transportation=PublicTransport(),\n departure_time=datetime.now()\n )\n print(results)\n\nasyncio.run(main())\n```\n\n### [Geocoding (Search)](https://docs.traveltime.com/api/reference/geocoding-search)\n\nMatch a query string to geographic coordinates.\n\n#### Takes:\n\n* query: str - A query to geocode. Can be an address, a postcode or a venue.\n* within_countries: List[str] - Only return the results that are within the specified country.\n* limit: int - Expected integer between 1 and 50. Limits amount of results returned to specified number.\n* format_name: bool - Format the name field of the geocoding search response to a well formatted, human-readable address\n of the location.\n* format_exclude_country: bool - Exclude the country from the formatted name field.\n* bounds: Rectangle - Used to limit the results to a bounding box.\n\n#### Returns:\n\n* Matched locations in geojson format\n\n#### Example:\n\n```python\nimport asyncio\nfrom traveltimepy import TravelTimeSdk\n\nasync def main():\n sdk = TravelTimeSdk(\"YOUR_APP_ID\", \"YOUR_APP_KEY\")\n results = await sdk.geocoding_async(query=\"Parliament square\", limit=30)\n print(results.features)\n\nasyncio.run(main())\n```\n\n### [Reverse Geocoding](https://docs.traveltime.com/api/reference/geocoding-reverse)\n\nMatch a latitude, longitude pair to an address.\n\n#### Takes:\n\n* lat: float - Latitude\n* lng: float - Longitude\n\n#### Returns:\n\n* Matched locations in a geojson format\n\n#### Example:\n\n```python\nimport asyncio\nfrom traveltimepy import TravelTimeSdk\n\nasync def main():\n sdk = TravelTimeSdk(\"YOUR_APP_ID\", \"YOUR_APP_KEY\")\n results = await sdk.geocoding_reverse_async(lat=51.507281, lng=-0.132120)\n print(results.features)\n\nasyncio.run(main())\n```\n\n### [Time Filter (Postcodes)](https://docs.traveltime.com/api/reference/postcode-search)\n\nFind reachable postcodes from origin (or to destination) and get statistics about such postcodes. Currently only\nsupports United Kingdom.\n\n#### Takes:\n\n* coordinates: List[Coordinates] - Location coordinates.\n* arrival_time: datetime - Be at arrival location at no later than given time. Cannot be specified with departure_time.\n* departure_time: datetime - Leave departure location at no earlier than given time. Cannot be specified with\n arrival_time.\n* travel_time: int - Maximum journey time (in seconds). Maximum value is 14400. Default value is 1800\n* [transportation](#transportation): Union - Transportation mode and related parameters.\n* properties: List[Property] - Properties to be returned about the postcodes. Default value is travel_time.\n* range: FullRange - When enabled, range adds an arrival window to the arrival time, and results are returned for any\n journeys that arrive during this window.\n\n#### Returns:\n\n* results: List[PostcodesResult] - The results list of postcodes.\n\n#### Example:\n\n```python\nimport asyncio\nfrom datetime import datetime\n\nfrom traveltimepy import Coordinates, PublicTransport, TravelTimeSdk\n\nasync def main():\n sdk = TravelTimeSdk(\"YOUR_APP_ID\", \"YOUR_APP_KEY\")\n results = await sdk.postcodes_async(\n coordinates=[Coordinates(lat=51.507609, lng=-0.128315)],\n departure_time=datetime.now(),\n transportation=PublicTransport()\n )\n \n print(results)\n\nasyncio.run(main())\n```\n\n### [Time Filter (Postcode Districts)](https://docs.traveltime.com/api/reference/postcode-district-filter)\n\nFind districts that have a certain coverage from origin (or to destination) and get statistics about postcodes within\nsuch districts. Currently only supports United Kingdom.\n\n#### Takes:\n\n* coordinates: List[Coordinates] - Location coordinates.\n* arrival_time: datetime - Be at arrival location at no later than given time. Cannot be specified with departure_time.\n* departure_time: datetime - Leave departure location at no earlier than given time. Cannot be specified with\n arrival_time.\n* travel_time: int - Maximum journey time (in seconds). Maximum value is 14400. Default value is 1800\n* [transportation](#transportation): Union - Transportation mode and related parameters.\n* reachable_postcodes_threshold: float - A number between 0.0 and 1.0. Default value is 0.1. For example, if 0.5 is\n used, only districts that have at least 50% postcodes that can be reached within the given travel_time will be\n included in the response. 0 will return districts that have at least a single reachable postcode.\n* properties: List[Property] - Properties to be returned about the districts. Default value is travel_time_all.\n* range: FullRange - When enabled, range adds an arrival window to the arrival time, and results are returned for any\n journeys that arrive during this window.\n\n#### Returns:\n\n* results: List[DistrictsResult] - The results list of districts.\n\n#### Example:\n\n```python\nimport asyncio\nfrom datetime import datetime\n\nfrom traveltimepy import Coordinates, PublicTransport, TravelTimeSdk\n\nasync def main():\n sdk = TravelTimeSdk(\"YOUR_APP_ID\", \"YOUR_APP_KEY\")\n results = await sdk.postcodes_districts_async(\n coordinates=[Coordinates(lat=51.507609, lng=-0.128315)],\n departure_time=datetime.now(),\n transportation=PublicTransport()\n )\n \n print(results)\n \nasyncio.run(main())\n\n```\n\n### [Time Filter (Postcode Sectors)](https://docs.traveltime.com/api/reference/postcode-sector-filter)\n\nFind sectors that have a certain coverage from origin (or to destination) and get statistics about postcodes within such\nsectors. Currently only supports United Kingdom.\n\n#### Takes:\n\n* coordinates: List[Coordinates] - Location coordinates.\n* arrival_time: datetime - Be at arrival location at no later than given time. Cannot be specified with departure_time.\n* departure_time: datetime - Leave departure location at no earlier than given time. Cannot be specified with\n arrival_time.\n* travel_time: int - Maximum journey time (in seconds). Maximum value is 14400. Default value is 1800\n* [transportation](#transportation): Union - Transportation mode and related parameters.\n* reachable_postcodes_threshold: float - A number between 0.0 and 1.0. Default value is 0.1. For example, if 0.5 is\n used, only sectors that have at least 50% postcodes that can be reached within the given travel_time will be included\n in the response. 0 will return sectors that have at least a single reachable postcode.\n* properties: List[Property] - Properties to be returned about the sectors. Default value is travel_time_all.\n* range: FullRange - When enabled, range adds an arrival window to the arrival time, and results are returned for any\n journeys that arrive during this window.\n\n#### Returns:\n\n* results: List[SectorsResult] - The results list of postcode sectors.\n\n#### Example:\n\n```python\nimport asyncio\nfrom datetime import datetime\n\nfrom traveltimepy import Coordinates, PublicTransport, TravelTimeSdk, ZonesProperty\n\nasync def main():\n sdk = TravelTimeSdk(\"YOUR_APP_ID\", \"YOUR_APP_KEY\")\n results = await sdk.postcodes_sectors_async(\n coordinates=[Coordinates(lat=51.507609, lng=-0.128315)],\n departure_time=datetime.now(),\n transportation=PublicTransport(),\n properties=[ZonesProperty.TRAVEL_TIME_REACHABLE, ZonesProperty.TRAVEL_TIME_ALL]\n )\n \n print(results)\nasyncio.run(main())\n```\n\n### [Map Info](https://docs.traveltime.com/api/reference/map-info)\n\nReturns information about currently supported countries.\n\nIt is useful when you have an application that can do searches in any country that we support, you can use Supported\nLocations to get the map name for a certain point and then use this endpoint to check what features are available for\nthat map. That way you could show fares for routes in the maps that support it.\n\n#### Returns:\n\n* maps: List[Map]\n* name - An internal map id. The first two characters usually correspond to the ISO 3166-2 standard (e.g th, ie)\n sometimes followed by additional characters (e.g ca_pst, us_pst). To get features of a specific map, use the map\n info endpoint.\n* features - Features that are supported in the specified map\n\n#### Example:\n\n```python\nimport asyncio\nfrom traveltimepy import TravelTimeSdk\n\nasync def main():\n sdk = TravelTimeSdk(\"YOUR_APP_ID\", \"YOUR_APP_KEY\")\n results = await sdk.map_info_async()\n print(results)\n\nasyncio.run(main())\n```\n\n### [Supported Locations](https://docs.traveltime.com/api/reference/supported-locations)\n\nFind out what points are supported by our api. The returned map name for a point can be used to determine what features\nare supported.\n\n#### Takes:\n\n* locations: List[Location] - Each location requires an id and lat/lng values\n\n#### Returns:\n\n* locations: List[SupportedLocation]\n* id - Location id that you specified in the request.\n* map_name - An internal map id. The first two characters usually correspond to the ISO 3166-2 standard (e.g th, ie)\n sometimes followed by additional characters (e.g ca_pst, us_pst). To get features of a specific map, use the map\n info endpoint.\n* additional_map_names - In case the location is in more than one map, other map ids are listed here.\n* unsupported_locations: List[str] - List that contains ids of locations that are unsupported.\n\n#### Example:\n\n```python\nimport asyncio\nfrom traveltimepy import Location, Coordinates, TravelTimeSdk\n\nasync def main():\n sdk = TravelTimeSdk(\"YOUR_APP_ID\", \"YOUR_APP_KEY\")\n \n locations = [\n Location(id=\"Kaunas\", coords=Coordinates(lat=54.900008, lng=23.957734)),\n Location(id=\"London\", coords=Coordinates(lat=51.506756, lng=-0.12805)),\n Location(id=\"Bangkok\", coords=Coordinates(lat=13.761866, lng=100.544818)),\n Location(id=\"Lisbon\", coords=Coordinates(lat=38.721869, lng=-9.138549)),\n ]\n \n results = await sdk.supported_locations_async(locations)\n \n print(results.locations)\n print(results.unsupported_locations)\n\nasyncio.run(main())\n```\n\n## Parameter usage examples\n\n### Transportation\n\nIn [transportation.py](https://github.com/traveltime-dev/traveltime-python-sdk/blob/master/traveltimepy/dto/transportation.py)\nyou can find all implemented transportation types, their sub-parameters and their default values.\n\nThese examples don't apply to proto / fast endpoints. For more examples you can always refer to [Unit Tests](https://github.com/traveltime-dev/traveltime-python-sdk/tree/master/tests)\n\n#### Driving \n\n```python\nfrom traveltimepy import Driving\n\ntransportation=Driving()\ntransportation=Driving(disable_border_crossing = True)\n```\n\n#### Walking \n\n```python\nfrom traveltimepy import Walking \n\ntransportation=Walking()\n```\n\n#### Cycling \n\n```python\nfrom traveltimepy import Cycling \n\ntransportation=Cycling()\n``` \n\n#### Ferry \n\n```python\nfrom traveltimepy import Ferry \n\ntransportation=Ferry()\ntransportation=Ferry(type=\"cycling+ferry\")\ntransportation=Ferry(type=\"driving+ferry\")\ntransportation=Ferry(type=\"cycling+ferry\", boarding_time = 300)\n``` \n\n#### DrivingTrain \n\n```python\nfrom traveltimepy import DrivingTrain, MaxChanges\n\ntransportation=DrivingTrain()\n\ntransportation=DrivingTrain(\n pt_change_delay = 300, \n driving_time_to_station=1800, \n parking_time=800,\n walking_time=500,\n max_changes=MaxChanges(enabled=True, limit=3)\n)\n``` \n\n#### PublicTransport \n\n```python\nfrom traveltimepy import PublicTransport, MaxChanges\n\ntransportation=PublicTransport() # type=\"public_transport\" - any public transport\ntransportation=PublicTransport(type=\"train\")\ntransportation=PublicTransport(type=\"bus\")\ntransportation=PublicTransport(type=\"coach\")\n\ntransportation=PublicTransport(\n pt_change_delay = 300, \n walking_time=500,\n max_changes=MaxChanges(enabled=True, limit=3)\n)\n``` \n\n#### CyclingPublicTransport \n\n```python\nfrom traveltimepy import CyclingPublicTransport, MaxChanges\n\ntransportation=CyclingPublicTransport()\n\ntransportation=CyclingPublicTransport(\n walking_time=500,\n pt_change_delay = 300,\n cycling_time_to_station=300,\n parking_time=800,\n boarding_time=300,\n max_changes=MaxChanges(enabled=True, limit=3)\n)\n``` \n\n### Level of Detail\n\n`level_of_detail` can be used to specify how detailed the isochrone result should be.\n\nFor a more detailed description of how to use this parameter, you can refer to our [API Docs](https://docs.traveltime.com/api/reference/isochrones#arrival_searches-level_of_detail)\n\n#### Examples\n\n```python\nfrom traveltimepy import LevelOfDetail\n\n# scale_type \"simple\"\nlevel_of_detail=LevelOfDetail(scale_type=\"simple\", level=\"lowest\")\n\n# scale_type \"simple_numeric\"\nlevel_of_detail=LevelOfDetail(scale_type=\"simple_numeric\", level=0)\n\n# scale_type \"coarse_grid\"\nlevel_of_detail=LevelOfDetail(scale_type=\"coarse_grid\", square_size=600)\n```\n\n### Snapping\n\n`snapping` Adjusts the process of looking up the nearest roads from the departure / arrival points.\n\nFor a more detailed description of how to use this parameter, you can refer to our [API Docs](https://docs.traveltime.com/api/reference/isochrones#departure_searches-snapping)\n\n#### Examples\n\n```python\nfrom traveltimepy.dto.common import Snapping, SnappingAcceptRoads, SnappingPenalty\n\nsnapping=Snapping(\n penalty=SnappingPenalty.ENABLED, # default\n accept_roads=SnappingAcceptRoads.BOTH_DRIVABLE_AND_WALKABLE # default\n)\n\nsnapping=Snapping(\n penalty=SnappingPenalty.DISABLED,\n accept_roads=SnappingAcceptRoads.ANY_DRIVABLE\n)\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python Interface to Travel Time.",
"version": "3.9.17",
"project_urls": null,
"split_keywords": [
"traveltimepy",
" api",
" maps"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a9da09f4028faf94d6b65ccc64049c94159afdd0bf111bfb02938b4d8d9110ed",
"md5": "89123be27bcca10ecfce5504fbc94e26",
"sha256": "5999452845b07764756543d33a4df13a3dcc53356e7af53ec9705c980ff819fb"
},
"downloads": -1,
"filename": "traveltimepy-3.9.17-py3-none-any.whl",
"has_sig": false,
"md5_digest": "89123be27bcca10ecfce5504fbc94e26",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 54314,
"upload_time": "2024-10-21T12:12:40",
"upload_time_iso_8601": "2024-10-21T12:12:40.624595Z",
"url": "https://files.pythonhosted.org/packages/a9/da/09f4028faf94d6b65ccc64049c94159afdd0bf111bfb02938b4d8d9110ed/traveltimepy-3.9.17-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "beed9f470d8f11078fe8690e8549f6a6bf9a445207b552f9eb98b9222bc621e6",
"md5": "34f8b5f991899000e8dbd758e0397ad6",
"sha256": "965fe3934c5d5e32f46156d74fb30dde812eb8ece804e2b51563c87e815f570f"
},
"downloads": -1,
"filename": "traveltimepy-3.9.17.tar.gz",
"has_sig": false,
"md5_digest": "34f8b5f991899000e8dbd758e0397ad6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 46523,
"upload_time": "2024-10-21T12:12:43",
"upload_time_iso_8601": "2024-10-21T12:12:43.442985Z",
"url": "https://files.pythonhosted.org/packages/be/ed/9f470d8f11078fe8690e8549f6a6bf9a445207b552f9eb98b9222bc621e6/traveltimepy-3.9.17.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-21 12:12:43",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "traveltimepy"
}
