search

traveltime-dev / traveltime-python-sdk

TravelTime SDK for Python programming language
https://docs.traveltime.com/
MIT License
19 stars 5 forks source link

readme

Travel Time Python SDK

PyPI version Unit Tests Python support

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.

Takes:

from traveltimepy import TravelTimeSdk

sdk = TravelTimeSdk(app_id="YOUR_APP_ID", api_key="YOUR_APP_KEY")

Isochrones (Time Map)

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

Takes:

JSON response

Returns:

Example:

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:

Example:

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:

Example:

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:

Example:

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)

Given origin coordinates, find intersections of specified shapes.

Takes:

Returns:

Example:

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)

Given origin coordinates, find unions of specified shapes.

Finds the union of specified shapes.

Takes:

Returns:

Example:

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

Distance Map

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

Takes:

Returns:

Example:

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)

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:

Returns:

Example:

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)

A very fast version of time_filter(). However, the request parameters are much more limited.

Takes:

Returns:

Example:

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)

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:

Returns:

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

Returns routing information between source and destinations.

Takes:

Returns:

Example:

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)

Match a query string to geographic coordinates.

Takes:

Returns:

Example:

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

Match a latitude, longitude pair to an address.

Takes:

Returns:

Example:

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)

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

Takes:

Returns:

Example:

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)

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:

Returns:

Example:

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)

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:

Returns:

Example:

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

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:

Example:

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

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:

Returns:

Example:

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

Driving

from traveltimepy import Driving

transportation=Driving()
transportation=Driving(disable_border_crossing = True)

Walking

from traveltimepy import Walking 

transportation=Walking()

Cycling

from traveltimepy import Cycling 

transportation=Cycling()

Ferry

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

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

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

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

Examples

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

Examples

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
)