The TravelTime Python SDK provides a simple and efficient way to access the TravelTime API, enabling you to calculate travel times and distances, generate isochrones, and perform location-based queries using real-world transportation data.
- Time Matrix & Filtering: Calculate travel times between multiple origins and destinations
- Isochrone Generation: Create time-based catchment areas in multiple formats (GeoJSON, WKT)
- Route Planning: Get detailed turn-by-turn directions between locations
- Geocoding: Convert addresses to coordinates and vice versa
- Specialized Analysis: UK postcode analysis, H3 hexagon analysis, and geohash analysis
- Transportation Modes: Support for driving, public transport, walking, cycling, and multimodal transport
- Async Support: Both synchronous and asynchronous clients available
- Performance Options: Fast endpoints for high-volume use cases
- Python 3.10 or higher
To check your Python version:
python --version
Install the TravelTime Python SDK using pip:
pip install traveltimepy
For protocol buffer (protobuf) support (required for TimeFilterFastProto endpoints):
pip install 'traveltimepy[proto]'
Get your API credentials from the TravelTime Developer Portal.
from datetime import datetime
from traveltimepy import Client
from traveltimepy.requests.common import Location, Coordinates, Property
from traveltimepy.requests.time_filter import TimeFilterDepartureSearch
from traveltimepy.requests.transportation import PublicTransport
from traveltimepy.errors import TravelTimeApiError
# Define locations
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))
]
# Option 1: Standard usage (manual session management)
client = Client(app_id="YOUR_APP_ID", api_key="YOUR_API_KEY")
try:
response = client.time_filter(
locations=locations,
departure_searches=[
TimeFilterDepartureSearch(
id="London center",
departure_location_id="London center",
arrival_location_ids=["Hyde Park", "ZSL London Zoo"],
departure_time=datetime.now(),
transportation=PublicTransport(),
travel_time=1800, # 30 minutes
properties=[Property.TRAVEL_TIME]
)
],
arrival_searches=[]
)
print(f"Found {len(response.results)} results")
for result in response.results:
print(f"Search ID: {result.search_id}")
except TravelTimeApiError as e:
print(e)
finally:
client.close() # Manually close session
# Option 2: Context manager (automatic session cleanup)
with Client(app_id="YOUR_APP_ID", api_key="YOUR_API_KEY") as client:
try:
response = client.time_filter(
locations=locations,
departure_searches=[
TimeFilterDepartureSearch(
id="London center",
departure_location_id="London center",
arrival_location_ids=["Hyde Park", "ZSL London Zoo"],
departure_time=datetime.now(),
transportation=PublicTransport(),
travel_time=1800,
properties=[Property.TRAVEL_TIME]
)
],
arrival_searches=[]
)
print(f"Found {len(response.results)} results")
for result in response.results:
print(f"Search ID: {result.search_id}")
except TravelTimeApiError as e:
print(e)
# Session automatically closed when exiting 'with' block
import asyncio
from datetime import datetime
from traveltimepy import AsyncClient
from traveltimepy.requests.common import Location, Coordinates
from traveltimepy.requests.time_filter import TimeFilterDepartureSearch
from traveltimepy.requests.transportation import PublicTransport
from traveltimepy.errors import TravelTimeApiError
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))
]
# Option 1: Standard async usage (manual session management)
async def main():
client = AsyncClient(app_id="YOUR_APP_ID", api_key="YOUR_API_KEY")
try:
response = await client.time_filter(
locations=locations,
departure_searches=[
TimeFilterDepartureSearch(
id="London center",
departure_location_id="London center",
arrival_location_ids=["Hyde Park", "ZSL London Zoo"],
departure_time=datetime.now(),
transportation=PublicTransport(),
travel_time=1800
)
],
arrival_searches=[]
)
print(f"Found {len(response.results)} results")
for result in response.results:
print(f"Search ID: {result.search_id}")
except TravelTimeApiError as e:
print(e)
finally:
await client.close() # Manually close session
# Option 2: Async context manager (automatic session cleanup)
async def main_with_context():
async with AsyncClient(app_id="YOUR_APP_ID", api_key="YOUR_API_KEY") as client:
try:
response = await client.time_filter(
locations=locations,
departure_searches=[
TimeFilterDepartureSearch(
id="London center",
departure_location_id="London center",
arrival_location_ids=["Hyde Park", "ZSL London Zoo"],
departure_time=datetime.now(),
transportation=PublicTransport(),
travel_time=1800
)
],
arrival_searches=[]
)
print(f"Found {len(response.results)} results")
for result in response.results:
print(f"Search ID: {result.search_id}")
except TravelTimeApiError as e:
print(e)
# Session automatically closed when exiting 'async with' block
# Run either version
asyncio.run(main())
# or
asyncio.run(main_with_context())
The SDK provides both synchronous (Client) and asynchronous (AsyncClient) versions of all methods:
time_filter()- Calculate travel times between locationstime_filter_fast()- High-performance version for large datasetstime_filter_proto()- Ultra-fast protocol buffer implementation (requirespip install 'traveltimepy[proto]')
time_map()- Generate travel time polygonstime_map_geojson()- GeoJSON format isochronestime_map_wkt()- WKT format isochronestime_map_fast()- High-performance isochronestime_map_fast_geojson()- Fast GeoJSON isochronestime_map_fast_wkt()- Fast WKT isochrones
routes()- Calculate detailed routes between locations
geocoding()- Convert addresses to coordinatesreverse_geocoding()- Convert coordinates to addresses
h3()- H3 hexagon analysish3_fast()- Fast H3 analysisgeohash()- Geohash analysisgeohash_fast()- Fast geohash analysispostcodes()- UK postcode analysispostcode_districts()- UK postcode district analysispostcode_sectors()- UK postcode sector analysisdistance_map()- Distance-based catchment areas
map_info()- Get supported countries and featuressupported_locations()- Check location support
The SDK supports various configuration options:
from traveltimepy import Client, AsyncClient
# Synchronous client
client = Client(
app_id="YOUR_APP_ID",
api_key="YOUR_API_KEY",
timeout=300, # Request timeout in seconds
retry_attempts=3, # Number of retry attempts for 5xx errors
max_rpm=60, # Maximum requests per minute
)
# Asynchronous client
async_client = AsyncClient(
app_id="YOUR_APP_ID",
api_key="YOUR_API_KEY",
timeout=300,
retry_attempts=3,
max_rpm=60
)
The SDK automatically handles both rate limiting and server error retries:
- Rate limiting: Automatically handled with exponential backoff
- Server errors (5xx): Automatically retried up to 3 times with immediate retry
- Client errors (4xx): Not retried (indicates invalid request)
# Retries are built-in - no additional code needed
client = Client(app_id="YOUR_APP_ID", api_key="YOUR_API_KEY")
response = client.time_filter(
locations=locations,
departure_searches=searches
) # Automatically retries on 5xx errors
You can configure the number of retry attempts:
# Custom retry attempts
client = Client(
app_id="YOUR_APP_ID",
api_key="YOUR_API_KEY",
retry_attempts=5 # Will retry up to 5 times on 5xx errors
)
# Disable retries completely
client = Client(
app_id="YOUR_APP_ID",
api_key="YOUR_API_KEY",
retry_attempts=0 # No retries, fail immediately
)
The examples/ directory contains practical examples.
See examples/README.md for setup instructions and detailed descriptions.
- Use
*_fast()methods for high-volume use cases - Use
time_filter_proto()for maximum performance with large datasets (install withpip install 'traveltimepy[proto]') - Use async methods for I/O-bound applications
For comprehensive documentation, including detailed parameter references and advanced usage examples, visit:
If you have questions or need help:
- Create an issue on GitHub
- Check the API documentation
- Contact TravelTime support
This project is licensed under the MIT License - see the LICENSE file for details.