TravelTime Python SDK

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.

Features

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

Requirements

Python 3.9 or higher

To check your Python version:

python --version

Installation

Install the TravelTime Python SDK using pip:

pip install traveltimepy

Getting Started

Authentication

Get your API credentials from the TravelTime Developer Portal.

Basic Usage

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

Async Usage

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())

Core Methods

The SDK provides both synchronous (Client) and asynchronous (AsyncClient) versions of all methods:

Time Matrix & Filtering

time_filter() - Calculate travel times between locations
time_filter_fast() - High-performance version for large datasets
time_filter_proto() - Ultra-fast protocol buffer implementation

Isochrone Generation

time_map() - Generate travel time polygons
time_map_geojson() - GeoJSON format isochrones
time_map_wkt() - WKT format isochrones
time_map_fast() - High-performance isochrones
time_map_fast_geojson() - Fast GeoJSON isochrones
time_map_fast_wkt() - Fast WKT isochrones

Route Planning

routes() - Calculate detailed routes between locations

Geocoding

geocoding() - Convert addresses to coordinates
reverse_geocoding() - Convert coordinates to addresses

Specialized Analysis

h3() - H3 hexagon analysis
h3_fast() - Fast H3 analysis
geohash() - Geohash analysis
geohash_fast() - Fast geohash analysis
postcodes() - UK postcode analysis
postcode_districts() - UK postcode district analysis
postcode_sectors() - UK postcode sector analysis
distance_map() - Distance-based catchment areas

Utility Methods

map_info() - Get supported countries and features
supported_locations() - Check location support

Configuration

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
)

Error Handling and Retries

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

Configuring Retries

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
)

Examples

The examples/ directory contains practical examples. See examples/README.md for setup instructions and detailed descriptions.

Performance Tips

Use *_fast() methods for high-volume use cases
Use time_filter_proto() for maximum performance with large datasets
Use async methods for I/O-bound applications

Documentation

For comprehensive documentation, including detailed parameter references and advanced usage examples, visit:

TravelTime API Documentation

Support

If you have questions or need help:

License

This project is licensed under the MIT License - see the LICENSE file for details.