Index
- Travel Time API documentation
- Auth params
- Types
- Primitive types
- Custom Types
- DateTime
- CoordsV1
- CoordsV2
- PointWithId
- TransportationMode
- EdgeType
- Accuracy
- Percentage
- Cluster
- ClusterV2
- WKT
- BoundingBox
- PostcodeParams
- InversePostcodeParams
- Ticket
- ModeFares (Route)
- ModeFares (TimeFilter)
- RequestProperties V2
- RequestProperties V3
- ResponseProperties V2
- ResponseProperties V3
- BasicDescriptionPart
- StartEndDescriptionPart
- RoadDescriptionPart
- PublicTransportDescriptionPart
- RouteDescription
- RoutingError
- Code "points-too-close"
- Error codes
- Actions
- /has_data
- /time_filter
- /v2/time_filter
- /v3/time_filter
- /time_map
- /v2/time_map
- /v2/time_map.wkt
- /v3/time_map
- /v2/routes
- /v3/routes
- /postcodes/geocode
- /v2/postcodes/geocode
- /postcodes/post_code_times
- /postcodes/post_code_times/inverse
- /postcodes/post_code_sector_times
- /postcodes/post_code_sector_times/inverse
- /postcodes/post_code_district_times
- /postcodes/post_code_district_times/inverse
- /postcodes/post_code_sector_percent
- /postcodes/post_code_sector_percent/inverse
- /postcodes/post_code_district_percent
- /postcodes/post_code_district_percent/inverse
- /postcodes/post_code_time_map
- /postcodes/post_code_time_map/inverse
- /map_info
- /bounding_box
- Content compression
- Protobuf endpoint
Travel Time API documentation
NOTICE: all v1 APIs (without /vX/ at the begining) calculates times from current time moment in UTC timezone.
Use v2 APIs if you want to provide your own start time (useful for public transport).
Read about CORS support at HTML5 Rocks.
Auth params
Each request must have following keys in request json set: "app_id"
and "app_key"
Types
Primitive types
- Int - a regular integer, e.g. 5, -1 or 19
- Double - a regular double, e.g. 2.45, -1.2 or 0.245
- Boolean - JSON boolean, e.g. true or false.
Custom Types
DateTime
ISO formatted date, e.g. "2012-11-26T18:14:52.892+02:00"
CoordsV1
Coordinates in the WGS 84 format, in degrees.
{"lat": Double, "lng": Double}
e.g. {"lat": 12.3, "lng": -3.22}
CoordsV2
Coordinates in the WGS 84 format, in degrees.
[lat (Double), lng (Double)]
e.g. [12.3, -3.22]
PointWithId
Point with id value attached.
{"id": String, "lat": Double, "lng": Double}
TransportationMode
Transportation mode that is used.
This parameter can be used in two ways.
As a String (using default values for mode parameters)
"mode": "cycling", "cycling_ferry", "cycling_public_transport", "driving", "driving+train", "driving_ferry", "public_transport", "walking", "walking+coach", "walking_bus", "walking_ferry" or "walking_train"
As a Hash (overriding default values for mode parameters)
"mode": {
"mode": "cycling", "cycling_ferry", "cycling_public_transport", "driving", "driving+train", "driving_ferry", "public_transport", "walking", "walking+coach", "walking_bus", "walking_ferry" or "walking_train",
... extra parameters may follow ...
}
!!! None of these parameters can be more than travel time !!!
Note: setting limits to a low value or penalties to a high value might result in routes not found.
walking_ferry, cycling_ferry, driving_ferry extra parameters
{
# Time it takes to board or disembark a ferry (in seconds).
# default: 0
"boarding-time": null|Int
}
"driving+train" extra parameters
{
# Change delay between driving and walking (in seconds).
# default: 300
"change-delay": null|Int,
# Maximum time spent driving (in seconds).
# default: 40% of travel time, but in range [1800, 3600]
"driving-time-limit": null|Int,
# Maximum time spent walking from last station to target location (in seconds)
# default: 40% of travel time, but in range [900, 2100]
"walking-from-station-limit": null|Int,
# Time needed to board public transportation vehicle (in seconds).
# default: 0
"pt-change-penalty": null|Int
}
Public transportation extra parameters
Applies to the following transportation modes: "public_transport"
, "walking+coach"
, "walking_bus"
or "walking_train"
{
# Maximum time (in seconds) of walking from source to a station/stop or from
# a station/stop to target. default: 40% of travel time, but in range [900, 2100]
time-to-station-limit: null|Int,
# Time needed to board public transportation vehicle (in seconds).
# default: 0
"pt-change-penalty": null|Int
}
EdgeType
String that describes type of the edge.
values: "bike"
, "bike_parking"
, "boarding"
, "bus"
, "cable_car"
, "car"
, "coach"
, "ferry"
, "parking"
, "plane"
, "rail_dlr"
, "rail_national"
, "rail_overground"
, "rail_underground"
, "train"
or "walk"
Accuracy
DEPRECATED
Will always be "exact" and can be safely ignored.
Percentage
Double between 0 and 1 that represents percentage. E.g. 45.32%
would be 0.4532
and 85.881%
would be 0.85881
Cluster
A cluster represents a closed shape.
[CoordsV2, CoordsV2, ...]
ClusterV2
A cluster represents a closed shape and its holes.
{
# Outer bounding shell.
"shell": [CoordsV2, CoordsV2, ...],
# Array of holes within that shell. Can be empty.
"holes: [
[CoordsV2, CoordsV2, ...],
[CoordsV2, CoordsV2, ...],
...
]
}
WKT
Polygon or a cluster of polygons represented as Well Known Text format.
It can be either POLYGON if only one cluster is present or MULTIPOLYGON if multiple clusters are present.
Points in polygons are oriented anti-clockwise and represented by "lon lat" pairs.
http://en.wikipedia.org/wiki/Well-known_text
BoundingBox
A shape representation using a collection of bounding boxes.
[
{
# The envelope (minimum and maximum coordinates) of a part of the shape
"envelope": Box
# A collection of bounding boxes specyfing this shape
"boxes": [Box, Box, ...]
},
...
The Box
type:
Box: {
"min_lon": Float,
"max_lon": Float,
"min_lat": Float,
"max_lat": Float
}
PostcodeParams
Input for many postcode actions.
{
"travel_time": Int,
"start_time": DateTime,
"origin": CoordsV2,
"mode": TransportationMode
}
InversePostcodeParams
Input for many inverse postcode actions.
{
"travel_time": Int,
"arrival_time": DateTime,
"origin": CoordsV2,
"mode": TransportationMode
}
Ticket
{ "type": String, # possible values: "single", "week", "month", "year" "price": Double, "currency": String # ISO 4217 currency code }
ModeFares (Route)
{ "modes": [TransportationMode, TransportationMode, ...], "tickets": [Ticket, Ticket, ...], #part ids for the fare "parts": [Int, Int, ...] }
ModeFares (TimeFilter)
{ "modes": [TransportationMode, TransportationMode, ...], "tickets": [Ticket, Ticket, ...] }
RequestProperties V2
[String, String, ...]
Specifies which data properties you want to know about the points. Valid values are:
- "time" - returns time taken to travel from source to destination in seconds.
- "distance" - returns distance from source to destination in meters. This is only valid for following modes:
"cycling"
,"cycling_ferry"
,"driving"
,"driving_ferry"
,"walking"
or"walking_ferry"
. Other transportation modes will have a constant distance of -1. - "distance_breakdown" - returns distance from source to destination broken down by EdgeType.
RequestProperties V3
[String, String, ...]
Specifies which data properties you want to know about the points. Valid values are:
- "time" - returns time taken to travel from source to destination in seconds.
- "distance" - returns distance from source to destination in meters. This is only valid for following modes:
"cycling"
,"cycling_ferry"
,"driving"
,"driving_ferry"
,"walking"
or"walking_ferry"
. Other transportation modes will have a constant distance of -1. - "distance_breakdown" - returns distance from source to destination broken down by EdgeType.
- "fares" - returns fares and fares total. This is only valid for the following modes:
"cycling_public_transport"
,"driving+train"
,"public_transport"
,"walking+coach"
,"walking_bus"
or"walking_train"
.
ResponseProperties V2
A Hash with one or more properties that you requested. Examples:
{"time": Int, "distance": Int}
{"distance": Int}
{"distance_breakdown": {EdgeType: Int}}
ResponseProperties V3
A Hash with one or more properties that you requested. Examples:
{"time": Int, "distance": Int}
{"distance": Int}
{"distance_breakdown": {EdgeType: Int}}
{"fares": [ModeFares (TimeFilter), ModeFares (TimeFilter), ...]}
{"fares_total": [Ticket, Ticket, ...]}
BasicDescriptionPart
Structure describing one part of the route.
{
"mode": EdgeType,
# Array of coordinates for this route part. Can be used to draw a polyline
# on a map.
"coords": [CoordsV2, CoordsV2, CoordsV2, ...],
"directions: String, # textual description in English of this route part
"distance": Int, # distance covered in metres for this route part
"time": Int, # time taken to travel through this route part in seconds
"id": Int
}
StartEndDescriptionPart
Structure describing route start and end.
{
"mode": EdgeType,
# Array of coordinates for this route part. Can be used to draw a polyline
# on a map.
"coords": [CoordsV2, CoordsV2, CoordsV2, ...],
"directions: String, # textual description in English of this route part
"distance": Int, # distance covered in metres for this route part
"time": Int, # time taken to travel through this route part in seconds
"direction": String, # Cardinal direction in English ("north", "northeast", "east", "southeast", ...)
"id": Int
}
RoadDescriptionPart
Structure describing routing on public roads, i.e. walking or driving.
{
"mode": EdgeType,
# Array of coordinates for this route part. Can be used to draw a polyline
# on a map.
"coords": [CoordsV2, CoordsV2, CoordsV2, ...],
"directions: String, # textual description in English of this route part
"distance": Int, # distance covered in metres for this route part
"time": Int, # time taken to travel through this route part in seconds
"road": null|String, # name of the road
"turn": null|String, # turn direction in English ("straight", "slight_left", "slight_right", "left" or "right")
"id": Int
}
PublicTransportDescriptionPart
Structure describing routing using public transport, i.e. bus or train.
{
"mode": EdgeType,
# Array of coordinates for this route part. Can be used to draw a polyline
# on a map.
"coords": [CoordsV2, CoordsV2, CoordsV2, ...],
"directions: String, # textual description in English of this route part
"distance": Int, # distance covered in metres for this route part
"time": Int, # time taken to travel through this route part in seconds
"line": String, # Name of the public transport line (e.g. bus number)
"departure_station": String, # name of the departure station
"arrival_station": String, # name of the arrival station
"depart_time": String, # local time of departure in 'HH:mm' format
"arrive_time": String, # local time of arrival in 'HH:mm' format
"num_stops": Int, # number of stops to go on this route part
"id": Int
}
RouteDescription
Structure describing route for a single target point.
{
"departure": DateTime, # departure time from the user origin point
"arrival": DateTime, # arrival time at the user destination point
"time": Int, # total travel time in seconds
"distance": Int, # total distance traveled in meters
"num_trips": Int, # total number of trips using public transport
# array of all the route parts that describe this route
"parts": [ BasicDescriptionPart | StartEndDescriptionPart | RoadDescriptionPart | PublicTransportDescriptionPart , BasicDescriptionPart | StartEndDescriptionPart | RoadDescriptionPart | PublicTransportDescriptionPart , ...],
#data included only if "include_fares": true
"fares": [ModeFares (Route), ModeFares (Route), ...],
#data included only if "include_fares": true
"fares_total": [Ticket, Ticket, ...]
}
RoutingError
Structure telling that a point cannot be routed due to an error.
{
"code": String, # One of the error codes.
"params": {String, ?}, # Error dependent parameters.
"details": String # Human-readable error description.
}
Following errors are defined:
Code "points-too-close"
This point couldn't be routed, because it was too close to the source/destination.
Params:
{
"p1": CoordsV2, # First point
"p2": CoordsV2 # Second point
}
Error codes
Each request can fail with one of predefined error codes. In the event of failure following JSON response will be returned.
{"code": one of error codes, "details": human readable error description}
Defined error codes are listed below:
- code:
"json-error"
, HTTP status:Bad Request (400)
- returned when body request cannot be parsed as valid JSON. - code:
"bad-params"
, HTTP status:Bad Request (400)
- returned when given parameters are not valid. - code:
"bad-auth-params"
, HTTP status:Bad Request (400)
- returned when auth params are missing or invalid. - code:
"no-auth"
, HTTP status:Unauthorized (401)
- returned when auth params are in correct format but are unknown to us. - code:
"limit-reached"
, HTTP status:Too Many Requests (429)
- returned when request limit for a time frame is reached. - code:
"out-of-reach"
, HTTP status:OK (200)
- returned when we have the data set, but there are no useful data around a given location. - code:
"no-data"
, HTTP status:OK (200)
- returned when we do not have any data in given location, also returned when requesting additional data (e.g. fares or postcodes) on location that does not support it. - code:
"timed-out"
, HTTP status:Service Unavailable (503)
- returned when one of our servers which might hold the requested data is down. - code:
"metadata-missing"
, HTTP status:Internal Server Error (500)
- returned when The metadata needed to finish the request is missing. - code:
"internal-server-error"
, HTTP status:Internal Server Error (500)
- returned when one of our servers which might hold the requested data has encountered an error and was unable to fulfill the request.
Actions
/has_data
Input
{"coords": CoordsV2}
Output
One of following:
- {"has": true}
- error
out-of-reach
- error
no-data
Accessible as
- POST at
/has_data
- OPTIONS at
/has_data
(CORS support)
/time_filter
Input
{
# Limits max. travel time from your origin to each of the given points.
# If travel time to a certain point exceeds this value such point will be
# omitted in the result set.
#
# In seconds.
"travel_time": Int,
"origin": CoordsV1,
# Points that wou need travel time calculated for.
"points": [PointWithId, PointWithId, ...],
"mode": TransportationMode
}
Output
{
# ids are taken from PointWithId.
# Int represents time from our origin to that point in seconds.
"id1": Int, "id2": Int, ...
}
Accessible as
- POST at
/time_filter
- OPTIONS at
/time_filter
(CORS support)
/v2/time_filter
Given origin point, max travel time and start time finds wanted properties for given set of destination points using given transportation modes.
Input
{
"travel_time": Int,
"origin": CoordsV2,
"points": {"id1": CoordsV2, "id2": CoordsV2, ...},
"modes": [TransportationMode, TransportationMode, ...],
# Specifies when do we start our search.
"start_time": DateTime,
"properties": RequestProperties V2
}
Output
{
# Each transportation mode you requested has a hash.
TransportationMode => {
"accuracy": Accuracy,
"times": {"id1": ResponseProperties V2, "id2": ResponseProperties V2, ...}
},
TransportationMode => {...},
...
}
Accessible as
- POST at
/v2/time_filter
- OPTIONS at
/v2/time_filter
(CORS support)
/v3/time_filter
Given origin and destination points find out properties of connections between origin and destination points.
Input
{
"points": {"p1": CoordsV2, "p2": CoordsV2, ...},
# We start our journey from each source and arrive at each point, returning
# requested properties.
"sources": {
"source1": {
"travel_time": Int,
"coords": CoordsV2,
"mode": TransportationMode,
"properties": RequestProperties V3,
"start_time": DateTime,
},
...
},
# We start our journey from each point and arrive at each destination,
# returning requested properties.
"destinations": {
"destination1": {
"travel_time": Int,
"coords": CoordsV2,
"mode": TransportationMode,
"properties": RequestProperties V3,
"arrival_time": DateTime,
},
...
},
# Relevant only for public transportation modes.
# If false (default) travel time to destinations (from sources) includes
# waiting time for the first vehicle at the origin point. If true waiting
# time is removed.
"remove_wait_time": null|Boolean
}
Output
Type 'Result'
{
"accuracy": Accuracy,
# If point is outside travel time it is not included in here.
"points": {
"p1": ResponseProperties V3, "p2": ResponseProperties V3, ...
}
}
Final output
{
"sources": {
# Each point gets either a result set or one of the error code hashes.
"source1": Result | error `no-data` | error `out-of-reach` | error `timed-out` | error `bad-params`,
"source2": Result | error `no-data` | error `out-of-reach` | error `timed-out` | error `bad-params`,
...
},
"destinations": {
# Each point gets either a result set or one of the error code hashes.
"destination1": Result | error `no-data` | error `out-of-reach` | error `timed-out` | error `bad-params`,
"destination2": Result | error `no-data` | error `out-of-reach` | error `timed-out` | error `bad-params`,
...
}
}
Accessible as
- POST at
/v3/time_filter
- OPTIONS at
/v3/time_filter
(CORS support)
/time_map
Input
{
# Maximum number of seconds needed to reach each point in result area.
"travel_time": Int,
"origin": CoordsV1,
"mode": TransportationMode,
# Should the shape be smoothed?
"smooth": Boolean
}
Output
Shapes with counter-clockwise orientation.
[Cluster, Cluster, ...]
Accessible as
- POST at
/time_map
- OPTIONS at
/time_map
(CORS support)
/v2/time_map
Given origin point, max travel time and start time find areas to which you can arrive in that travel time using given transportation mode.
Input
{
"start_time": DateTime,
# Maximum number of seconds needed to reach each point in result area.
"travel_time": Int,
"origin": CoordsV2,
"mode": TransportationMode,
# Should the shape be smoothed?
"smooth": Boolean,
# Optional parameter that switches shape simplification on (true, not specified - old behaviour) and
# off (false). In case this is true and max_points is not specified, shape is simplified so that
# it remains similar to the original shape.
"simplify": null|Boolean
# Optional parameter that allows you to specify maximum number of points in
# returned cluster. If more than one cluster is returned, points are divised
# proportionally between clusters.
"max_points": null|Int
}
Output
{
"accuracy": Accuracy,
# Shapes with counter-clockwise orientation.
"shape": [Cluster, Cluster, ...]
}
Accessible as
- POST at
/v2/time_map
- OPTIONS at
/v2/time_map
(CORS support)
/v2/time_map.wkt
Same as v2 of time map, but shape is returned as WKT string without holes.
Accessible as
- POST at
/v2/time_map.wkt
- OPTIONS at
/v2/time_map.wkt
(CORS support)
/v3/time_map
Given X origins find shapes of zones reachable within each corresponding travel time and intersections of those zones.
Use cases
Single origin with start_time
You are in your job and want to watch a sports game in a pub after work. Given that you have 30 minutes between your shift end and when match starts you need to find a suitable sports pub using public transport.
Multi origin with start_time
John, Tom and Bob want to meet for a chat in a pub. They all live in different places but want to meet in 30 minutes by using public transport.
You can use this method to obtain all zones in which they could meet.
Single origin with arrival_time
You get a new job in London and are searching for a place to rent. You want to arrive to work at 9 AM in 15 minutes either by walking or by public transport.
Using this request you can set your new job as the destination and receive a time map of potential places for your new home.
Multi origin with arrival_time
You and your partner both get a new job in London. However this time you have two different destinations. One of you (A) has to be at work at 8:30 AM and can spare 30 minutes of driving, whilst another one (B) must be at work at 7 AM and wants to walk for 10 minutes max.
Using this request you can find time maps for persons A and B and intersection between them where your new home could be.
Input
{
"format": "array", "hash", "wkt", "wkt-no-holes", "bounding-boxes-no-holes"
# Should the shapes be smoothed or not?
"smooth": Boolean,
"targets": {
"id1": {
"coords": CoordsV2,
# Specifies when do we want to either:
# - Start our journey from this point at given time.
# - Arrive at this point at given time.
"start_time" | "arrival_time": DateTime,
# Maximum number of seconds between target and edge of the zone.
"travel_time": Int,
"mode": TransportationMode
},
...
},
# Specify which individual targets you want to get.
"shapes": {
"id1": {"simplify": Simplify, "max_points": MaxPoints},
...
},
# Specify which intersections of areas you want to get.
"intersections": {
# Returns intersection between areas for origins id1 and id3 as inter1.
"inter1": {
"simplify": Simplify,
"max_points": MaxPoints,
"targets": ["id1", "id3"]
},
"inter2": {
"simplify": Simplify,
"max_points": MaxPoints,
"targets": ["id1", "id2", "id3"]
},
...
},
# Specify which unions of areas you want to get.
"unions": {
# Returns union of areas for origins id1 and id3 as union1.
"union1": {
"simplify": Simplify,
"max_points": MaxPoints,
"targets": ["id1", "id3"]
},
"union2": {
"simplify": Simplify,
"max_points": MaxPoints,
"targets": ["id1", "id2", "id3"]
},
...
}
}
Type 'Simplify'
Optional boolean parameter that switches simplification on or off.
If this parameter is not specified behaviour is solely decided by 'max_points' parameter.
If this is 'true' and 'max_points = 0' , shape is simplified so that it remains similar enough (and that is decided by internals of this service) to original shape.
If this is 'true' and 'max_points >= 4', shape is simplified so that it does not have more points than the given value.
This parameter is ignored for the BoundingBox format.
Type 'MaxPoints'
Maximum number of points in each polygon you want to get. If polygon has more polygons than this, its size is reduced using Ramer–Douglas–Peucker algorithm.
Specify Int (>= 4) or 0 for no limit.
This parameter is ignored for the BoundingBox format.
Output
Hash containing requested shapes for origins, their intersections and unions.
Type 'Result'
{
"accuracy": Accuracy,
"shape": Shape
}
Depending on requested format Shape will be:
- if "format" was "array" - [Cluster, Cluster, ...]
- if "format" was "hash" - [ClusterV2, ClusterV2, ...]
- if "format" was "wkt" - WKT
- if "format" was "wkt-no-holes " - WKT without holes
- if "format" was "bounding-boxes-no-holes " - BoundingBox without holes
Final output
{
# Shape, intersection and union responses. If an error occurs while obtaining
# the response, it will be missing from this hash.
"results": {
# Target polygons have exterior ring in counter-clockwise orientation and
# holes in clockwise orientation.
"id1": Result,
"id2": Result,
# For intersections and unions errors will occur if at least one of the
# targets errors out.
# Polygons of intersections and unions have both exterior ring and holes
# in clockwise orientation.
"inter1": Result,
"inter2": Result,
"union1": Result,
"union2": Result,
...
},
# If any errors occur while obtaining data for targets, they will be listed
# here. Otherwise it is an empty hash.
"target-errors": {
"id1": error `no-data` | error `out-of-reach` | error `timed-out` | error `bad-params`,
"id2": error `no-data` | error `out-of-reach` | error `timed-out` | error `bad-params`,
...
}
}
Accessible as
- POST at
/v3/time_map
- OPTIONS at
/v3/time_map
(CORS support)
/v2/routes
Given origin point, max travel time and start time return routing information using transportation mode for set of destination points.
Input
{
# Limits max. travel time from your origin to each of the given points. If
# travel time to a certain point exceeds this value such point will be
# omitted in the result set.
#
# In seconds.
"travel_time": Int,
"origin": CoordsV2,
# Points that you need travel time calculated for.
"points": {"id1": CoordsV2, "id2": CoordsV2, ...},
"mode": TransportationMode,
# When do we start our search?
"start_time": DateTime
}
Output
{
"id1" -> [ BasicDescriptionPart | StartEndDescriptionPart | RoadDescriptionPart | PublicTransportDescriptionPart ,
BasicDescriptionPart | StartEndDescriptionPart | RoadDescriptionPart | PublicTransportDescriptionPart , ...],
"id2" -> [ BasicDescriptionPart | StartEndDescriptionPart | RoadDescriptionPart | PublicTransportDescriptionPart ,
BasicDescriptionPart | StartEndDescriptionPart | RoadDescriptionPart | PublicTransportDescriptionPart , ...],
...
}
An empty array []
will be returned for a point that has the same coordinates as the origin point.
Accessible as
- POST at
/v2/routes
- OPTIONS at
/v2/routes
(CORS support)
/v3/routes
Given origin point and start time or destination point and arrival time, max travel time returns routing information using transportation mode for set of destination points.
Input
{
"target": {
"coords": CoordsV2,
# Specifies when do we want to either:
# - Start our journey from this point at given time.
# - Arrive at this point at given time.
"start_time" | "arrival_time": DateTime,
# Maximum number of seconds between target and edge of the zone.
"travel_time": Int,
"mode": TransportationMode,
# Include fares in the response, default is false.
"include_fares": null|Boolean
}
# Points that you need route for.
"points": {"id1": CoordsV2, "id2": CoordsV2, ...},
}
Output
{
"id1" -> RouteDescription | RoutingError,
"id2" -> RouteDescription | RoutingError,
...
}
Accessible as
- POST at
/v3/routes
- OPTIONS at
/v3/routes
(CORS support)
/postcodes/geocode
Geocodes UK postcodes into coordinates.
Input
{
# comma separated postcode list which we want geocoded
"q": "postcode1,postcode2,postcode3"
}
Output
[OptCoords, OptCoords, ...]
Each postcode gets its own entry in the array.
OptCoords
null
if postcode could not be geocoded.- CoordsV2 if postcode was geocoded.
Accessible as
- POST at
/postcodes/geocode
- OPTIONS at
/postcodes/geocode
(CORS support)
/v2/postcodes/geocode
Same as v1, except that input is changed into:
{
"postcodes": ["postcode1", "postcode2", ...]
}
Accessible as
- POST at
/v2/postcodes/geocode
- OPTIONS at
/v2/postcodes/geocode
(CORS support)
/postcodes/post_code_times
All postcodes reachable from origin point in given travel time.
Each postcode is mapped to time in seconds needed to travel from origin to that postcode.
Input
Output
{postcode (String): time (Int), ...}
Accessible as
- POST at
/postcodes/post_code_times
- OPTIONS at
/postcodes/post_code_times
(CORS support)
/postcodes/post_code_times/inverse
All postcodes from which we can reach destination point in given travel time.
Each postcode is mapped to time in seconds needed to travel from source to that wanted destination.
Input
Output
{postcode (String): time (Int), ...}
Accessible as
- POST at
/postcodes/post_code_times/inverse
- OPTIONS at
/postcodes/post_code_times/inverse
(CORS support)
/postcodes/post_code_sector_times
All reachable sectors in given travel time. Each sector is mapped to averaged time in seconds needed to travel from origin to all known postcodes in that sector.
Input
Output
{sector (String): time (Int), ...}
Accessible as
- POST at
/postcodes/post_code_sector_times
- OPTIONS at
/postcodes/post_code_sector_times
(CORS support)
/postcodes/post_code_sector_times/inverse
All sectors from which we can reach destination point in given travel time.
Each sector is mapped to averaged time in seconds needed to travel from all known postcodes in that sector to your wanted destination.
Input
Output
{sector (String): time (Int), ...}
Accessible as
- POST at
/postcodes/post_code_sector_times/inverse
- OPTIONS at
/postcodes/post_code_sector_times/inverse
(CORS support)
/postcodes/post_code_district_times
All reachable districts in given travel time. Each district is mapped to averaged time in seconds needed to travel from origin to all known postcodes in that district.
Input
Output
{district (String): time (Int), ...}
Accessible as
- POST at
/postcodes/post_code_district_times
- OPTIONS at
/postcodes/post_code_district_times
(CORS support)
/postcodes/post_code_district_times/inverse
All districts from which we can reach destination point in given travel time.
Each district is mapped to averaged time in seconds needed to travel from all known postcodes in that district to your wanted destination.
Input
Output
{district (String): time (Int), ...}
Accessible as
- POST at
/postcodes/post_code_district_times/inverse
- OPTIONS at
/postcodes/post_code_district_times/inverse
(CORS support)
/postcodes/post_code_sector_percent
All reachable sectors in given travel time. Each sector is mapped to percentage of postcodes reachable from origin within given travel time in that sector.
Input
Output
{sector (String): coverage (Percentage), ...}
Accessible as
- POST at
/postcodes/post_code_sector_percent
- OPTIONS at
/postcodes/post_code_sector_percent
(CORS support)
/postcodes/post_code_sector_percent/inverse
All sectors from which we can reach destination point in given travel time.
Each sector is mapped to percentage of postcodes which can reach destination within given travel time in that sector.
Input
Output
{sector (String): coverage (Percentage), ...}
Accessible as
- POST at
/postcodes/post_code_sector_percent/inverse
- OPTIONS at
/postcodes/post_code_sector_percent/inverse
(CORS support)
/postcodes/post_code_district_percent
All reachable districts in given travel time. Each district is mapped to percentage of postcodes reachable from origin within given travel time in that district.
Input
Output
{district (String): coverage (Percentage), ...}
Accessible as
- POST at
/postcodes/post_code_district_percent
- OPTIONS at
/postcodes/post_code_district_percent
(CORS support)
/postcodes/post_code_district_percent/inverse
All districts from which we can reach destination point in given travel time.
Each district is mapped to percentage of postcodes which can reach destination within given travel time in that district.
Input
Output
{district (String): coverage (Percentage), ...}
Accessible as
- POST at
/postcodes/post_code_district_percent/inverse
- OPTIONS at
/postcodes/post_code_district_percent/inverse
(CORS support)
/postcodes/post_code_time_map
A shape of all postcode sectors that have at least one postcode reachable from origin point in given time.
Input
Output
{
# Shapes with clockwise orientation.
shape: [Cluster, Cluster, ...]
}
Accessible as
- POST at
/postcodes/post_code_time_map
- OPTIONS at
/postcodes/post_code_time_map
(CORS support)
/postcodes/post_code_time_map/inverse
A shape of all postcode sectors that have at least one postcode from which you can reach destination point in given time.
Input
Output
{
# Shapes with clockwise orientation.
shape: [Cluster, Cluster, ...]
}
Accessible as
- POST at
/postcodes/post_code_time_map/inverse
- OPTIONS at
/postcodes/post_code_time_map/inverse
(CORS support)
/map_info
Info about maps currently available on API.
Input
This request doesn't take input parameters.
Output
{
"map-name1" (String) : {
"from": DateTime,
"to": DateTime
}
"map-name2" (String): { ...
}
Accessible as
- POST at
/map_info
- OPTIONS at
/map_info
(CORS support)
/bounding_box
Given X origins find bounding boxes of shapes of zones reachable within each corresponding travel time.
Input
{
"targets": {
"id1": {
"coords": CoordsV2,
# Specifies when do we want to either:
# - Start our journey from this point at given time.
# - Arrive at this point at given time.
"start_time" | "arrival_time": DateTime,
# Maximum number of seconds between target and edge of the zone.
"travel_time": Int,
"mode": TransportationMode
},
...
},
}
Type 'Result'
A Result
is a array of Polygon
s
Polygon: {
"envelope": Box
"boxes": [Box, Box, ...]
}
The Box
type:
Box: {
"min_lon": Float,
"max_lon": Float,
"min_lat": Float,
"max_lat": Float
}
Output
{
# Bounding bo responses. If an error occurs while obtaining the response, it will be missing from this hash.
"results": {
"id1": Result,
"id2": Result,
...
},
# If any errors occur while obtaining data for targets, they will be listed
# here. Otherwise it is an empty hash.
"target-errors": {
"id1": error `no-data` | error `out-of-reach` | error `timed-out` | error `bad-params`
"id2": error `no-data` | error `out-of-reach` | error `timed-out` | error `bad-params`
...
}
}
Accessible as
- POST at
/bounding_box
- OPTIONS at
/bounding_box
(CORS support)
Content compression
We support (and recommend to use) lz4
compression. Compression results in significantly reduced request size. lz4
is available for most of the popular programming languages. Get it at: https://code.google.com/p/lz4
To use compression:
- compress request binary data,
- add HTTP header "Content-Encoding: lz4",
- response data will also be compressed.
Protobuf endpoint
For those seeking maximum performance, we provide Protocol Buffers (Protobuf)
endpoint. Compared to Json
it gives reduced parsing/composing time and significantly reduced request size.
Read more: https://bitbucket.org/igeolise/protobuf-traveltime-api