A simple command line application for batching requests to the Google Directions API. Requests are handled asynchronously, enabling many to be resolved concurrently in a short amount of time.
Licensed under MIT.
- Installation
- About
- Command line reference
- Input data scheme
- Output data scheme
- Directions API terms of service
- What does the name mean?
Pre-compiled binaries of Telesto are available for Windows, macOS and Linux in the releases section. Users can alternatively compile Telesto from the source:
$ git clone https://github.com/MichaelByrneAU/Telesto
$ cd Telesto
$ cargo build --release
$ ./target/release/telesto --help
For transport planners and modellers, it can be useful to understand what route someone will likely take when travelling between A to B at specific times of the day, as well as how long this journey will take. The Google Directions API service can serve as a useful tool in this respect, providing a constantly updating source of data to sense-check against when simulating travel behaviour.
Given a list of origins, destinations and other parameters, this application will return the Google Directions API JSON response for each entry. Requests are handled asynchronously using Futures and the Tokio runtime, meaning that many can be handled concurrently at once - increasing the speed of data retrieval. This can make it feasible to facilitate thousands of requests in a short amount of time.
You will require a Directions API key or client ID/private key pair (for premium plan users) to use this application. More information on this is available here.
# telesto [options...]
Given a CSV of route parameters, returns corresponding Directions API responses in a JSON list. Credentials, either through an API key or client ID/private key pair must be provided.
Output usage information.
# telesto -V
# telesto --version
Output version information.
# telesto -i file
# telesto --input file
Specify the input CSV data file path. If this option is not included, defaults to stdin.
# telesto -o file
# telesto --output file
Specify the output JSON file path. If this option is not included, defaults to stout.
# telesto -a value
# telesto --api-key value
Specify the API key the application will use when making requests to the Google Directions API. Unless using a client ID/private key pair, this option is required. You cannot simultaneously supply an API key and a client ID/private key pair.
# telesto -c value
# telesto --client-id value
Specify the client ID the application will use when making requests to the Google Directions API. Unless using an API key, this option is required, and must be accompanied by the accompanying private key. You cannot simultaneously supply a client ID/private key pair and an API key.
# telesto -C value
# telesto --channel value
Specify the channel name the application will use when making requests to the Google Directions API. This is optional but can only be used when accompanied by a client ID/private key pair.
Telesto takes a CSV file as an input with nine fields. Here is an example:
id origin_lat origin_lon destination_lat destination_lon departure_time mode avoidances traffic_model
---- ------------ ------------ ----------------- ----------------- ---------------- --------- ---------------- ---------------
1 -37.820189 145.149954 -37.819681 144.952302 1534284000 driving tolls|highways best_guess
2 -37.820189 145.149954 -37.819681 144.952302 1534284000 transit
# field id string
A string that acts as an identifier for that request. This string must be unique across all requests in the CSV input.
# field origin_lat float
The latitude coordinate of the request's origin.
# field origin_lon float
The longitude coordinate of the request's origin.
# field destination_lat float
The latitude coordinate of the request's destination.
# field destination_lon float
The longitude coordinate of the request's destination.
# field departure_time integer
The departure time of the request in unix epoch time. Note that the Directions API only accepts future times for requests. If a departure time in the past is specified, then this time will be replaced with the closest future time that falls on the same day of the week and time of day. If you wish to have finer control over the desired departure time for a request, specify a future time relative to when you run the application.
# field mode string
The mode of transport for the request. This can be one of the following:
- bicycling
- driving
- transit
- walking
# field avoidances string
Any avoidances the Directions API should take into account when providing a route for a request. This can include the following conditions:
- ferries
- highways
- indoors
- tolls
Multiple conditions can be specified simultaneously by separating them with a pipe, e.g. 'tolls|highways'. It is optional to include values in this field.
# field traffic_model string
The traffic model the Directions API should use when providing travel time estimates for driving trips. This can be one of the following:
- best_guess
- pessimistic
- optimistic
This field is required when the specified mode is 'driving', otherwise it should be left blank.
Telesto will provide as output a JSON list with the following structure:
[
{
id: your_request_id,
response: {
... JSON response from the Directions API ...
}
},
...
]
Essentially, a list of request ID and response pairs. The format of the Directions API JSON response is described in more detail here.
The data you collect through Telesto using your API key or client ID/private key pair is subject to the particular terms of service that you agreed to with the Google Maps Platform when supplied with those credentials. This includes, but is not limited to, the storage, reporting, visualisation and attribution of this data in accordance with your particular agreement with Google.
Nothing, I like naming my projects after moons in the solar system. Telesto is a potato-shaped moon of Saturn that was discovered in 1980.