Citymapper (Independent Publisher) (Preview)
Citymapper allows you to add journey planning and turn-by-turn navigation to your products. Our services are powered by our industry-leading global transport data and custom routing algorithms trained on billions of trips.
This connector is available in the following products and regions:
Service | Class | Regions |
---|---|---|
Logic Apps | Standard | All Logic Apps regions except the following: - Azure Government regions - Azure China regions - US Department of Defense (DoD) |
Power Automate | Premium | All Power Automate regions except the following: - US Government (GCC) - US Government (GCC High) - China Cloud operated by 21Vianet - US Department of Defense (DoD) |
Power Apps | Premium | All Power Apps regions except the following: - US Government (GCC) - US Government (GCC High) - China Cloud operated by 21Vianet - US Department of Defense (DoD) |
Contact | |
---|---|
Name | Troy Taylor |
URL | https://www.hitachisolutions.com |
ttaylor@hitachisolutions.com |
Connector Metadata | |
---|---|
Publisher | Troy Taylor |
Website | https://citymapper.com/ |
Privacy policy | https://citymapper.com/api/1/resources?id=citymapper-privacy-policy |
Categories | Lifestyle and Entertainment |
The connector supports the following authentication types:
Default | Parameters for creating connection. | All regions | Not shareable |
Applicable: All regions
Parameters for creating connection.
This is not shareable connection. If the power app is shared with another user, another user will be prompted to create new connection explicitly.
Name | Type | Description | Required |
---|---|---|---|
API Key | securestring | The API Key for this api | True |
Name | Calls | Renewal Period |
---|---|---|
API calls per connection | 100 | 60 seconds |
Get a bike route between two points |
Gets a bike route between two points, providing enough information to render it on a map, along with a duration estimate. This call assumes that the rider has a bicycle at the 'start' point, and provides a biking route from there to the 'end' point if both are within Citymapper's supported areas. The resulting route should contain a single bike leg, though the 'path_annotations' property of the leg may indicate sections during which the user should walk beside the bike. This call does not incorporate any information about bike operators' coverage or parking areas, but other service calls may be available to do so. The maximum great-circle distance between the start and end is limited to 200km for this service. |
Get a driving route between two points |
Gets a car route between two points, providing enough information to render it on a map, along with a duration estimate. This call assumes that the rider has a car at the 'start' point, and provides a car route from there to the 'end' point if both are within Citymapper's supported areas. The resulting route should contain a single car leg. The maximum great-circle distance between the start and end is limited to 1000km for this service. |
Get a hired bike route between two points |
Gets a hired bike route between two points, including any initial and final walks. The resulting route provides enough information to render it on a map, along with a duration estimate. This call can be used in several different ways: Use any bike of the specified Brand This is the simplest call, only requiring 'start', 'end', and 'brand_id'. Citymapper assumes that the user is at the 'start' point, and chooses a bike of the specified Brand, if possible. Use a bike at a specified location By adding 'original_vehicle_location' to 'start', 'end', and 'brand_id', Citymapper plans a route that assumes the bike is at the given location. Update a route in progress In order to retrieve an updated route that includes rerouting from the user's current location if they've diverged from the planned Route, the caller can add the 'current_location' and 'ride_state' properties, which indicates which leg of the resulting route should be rerouted around the user's 'current_location'. |
Get a hired motor scooter route between two points |
Gets a hired motor scooter route between two points, including any initial and final walks. The resulting route provides enough information to render it on a map, along with a duration estimate. (These results are optimized for larger internal combustion or electric scooters where the rider is seated.) NOTE: The resulting route currently assumes that the user can ride directly to the specified 'end' location, not taking into account any parking or coverage zones. Thus, the resulting route will contain only an initial leg of 'travel_mode' 'walk' and a second leg of 'travel_mode' 'self_piloted'. A future update will incorporate parking and coverage zones and add a final 'walk' leg. This call can be used in several different ways: Use any scooter of the specified Brand This is the simplest call, only requiring 'start', 'end', and 'brand_id'. Citymapper assumes that the user is at the 'start' point, and chooses a scooter of the specified Brand, if possible. Use a scooter at a specified location By adding 'original_vehicle_location' to 'start', 'end', and 'brand_id', Citymapper plans a route that assumes the scooter is at the given location. Update a route in progress In order to retrieve an updated route that includes rerouting from the user's current location if they've diverged from the planned Route, the caller can add the 'current_location' and 'ride_state' properties, which indicates which leg of the resulting route should be rerouted around the user's 'current_location'. |
Get a motor scooter route between two points |
Gets a motor scooter route between two points, providing enough information to render it on a map, along with a duration estimate. (These results are optimized for larger internal combustion or electric scooters where the rider is seated.) This call assumes that the rider has a scooter at the 'start' point, and provides an e-scooter route from there to the 'end' point if both are within Citymapper's supported areas. The resulting route should contain a single scooter leg, though the 'path_annotations' property of the leg may indicate sections during which the user should walk beside the scooter. This call does not incorporate any information about scooter operators' coverage or parking areas, but other service calls may be available to do so. |
Get a route between two points for a scenario |
Computes routes between two points based on a provided scenario. One or more groups of routes can be provided depending on a scenario. Each group will contain several routes. Each route will contain one or more legs. |
Get a taxi route between two points |
Gets a taxi route between two points. The resulting route provides enough information to render it on a map, along with a duration estimate. The route may contain starting and ending walk legs if the pick-up or drop-off points aren't close to the requested start and end coordinates. The Services in the response will vary depending on the local availability, time of day and, additionally, which Taxi service integrations have been configured for your account. There are two recommended ways to use this service: You can request a taxi route with live on-demand service estimates included up-front by calling with '?fetch_on_demand_services=true'; or you can make the initial request without fetching estimates which will respond with the non-live route, then immediately call '1/live/routeupdates' to get the additional live estimates. The first approach is simpler, but the second may better fit your use-case. |
Get a transit route between two points |
Computes several public transportation routes between two points. By default, the results will contain up to 5 routes. Each one will contain several legs: usually one at the start and end of the route with 'travel_mode' of 'walk', with at least one with 'travel_mode' of 'transit' in between. |
Get a walking route between two points |
Gets a walking route between two points, providing enough information to render it on a map, along with a duration estimate. Walking routes are expected to have a single leg with a 'travel_mode' of 'walk'. If Citymapper can't compute walking directions for those points (generally for coverage reasons), the service will return a code '400' response. The maximum great-circle distance between the 'start' and 'end' is limited to 100km for this service. |
Get e-scooter directions between two points |
Gets a scooter route between two points, providing enough information to render it on a map, along with a duration estimate. (These results are optimized for small battery-powered scooters that the rider stands on.) This call assumes that the rider has a scooter at the 'start' point, and provides an e-scooter route from there to the 'end' point if both are within Citymapper's supported areas. The resulting route should contain a single scooter leg, though the 'path_annotations' property of the leg may indicate sections during which the user should walk beside the scooter. This call does not incorporate any information about scooter operators' coverage or parking areas, but other service calls may be available to do so. Successful responses (HTTP code '200') will consume one 'Scooter Route' credit (or one 'Scooter Reroute' credit if 'reroute_signature' is used) for each HTTP response. Unsuccessful calls will not consume any credits. |
Get hired e-scooter directions between two points |
Gets a hired e-scooter route between two points, including any initial and final walks. The resulting route provides enough information to render it on a map, along with a duration estimate. These results are optimized for small battery-powered scooters that the rider stands on. This call can be used in several different ways: Use any scooter of the specified Brand This is the simplest call, only requiring 'start', 'end', and 'brand_id'. Citymapper assumes that the user is at the 'start' point, and chooses a scooter of the specified Brand, if possible. Use a scooter at a specified location By adding 'original_vehicle_location' to 'start', 'end', and 'brand_id', Citymapper plans a route that assumes the scooter is at the given location. Update a route in progress In order to retrieve an updated route that includes rerouting from the user's current location if they've diverged from the planned Route, the caller can add the 'current_location' and 'ride_state' properties, which indicates which leg of the resulting route should be rerouted around the user's 'current_location'. |
Get live departure and availability information for multiple routes |
This retrieves current and live departure information and live on-demand quotes for multiple routes previously obtained from the 'directions' endpoints. Only routes that have at least one leg with a leg Updatable Detail can be updated using this service. Note it may not always be possible for Citymapper to provide current times or live departure and disruption information for a leg. Successful responses (HTTP code '200') will consume one 'Live Update' credit for each HTTP response. Unsuccessful calls will not consume any credits. |
Get travel times between two locations |
Determines the travel time in various modes of travel between the given two points at the time the request is made. |
Gets a bike route between two points, providing enough information to render it on a map, along with a duration estimate. This call assumes that the rider has a bicycle at the 'start' point, and provides a biking route from there to the 'end' point if both are within Citymapper's supported areas. The resulting route should contain a single bike leg, though the 'path_annotations' property of the leg may indicate sections during which the user should walk beside the bike. This call does not incorporate any information about bike operators' coverage or parking areas, but other service calls may be available to do so. The maximum great-circle distance between the start and end is limited to 200km for this service.
Parameters
Name | Key | Required | Type | Description |
---|---|---|---|---|
Start
|
start | True | array |
The geographical start of the route, in WGS84 'latitude,longitude' format. Coordinates should be in decimal, and only the first 6 decimal places will be used. |
End
|
end | True | array |
The geographical end of the route, in WGS84 'latitude,longitude' format. Coordinates should be in decimal, and only the first 6 decimal places will be used. |
Profiles
|
profiles | string |
Indicates which 'profiles' to use when calculating bike directions. Each profile can generate a different route option, so requesting more profiles will generally give more options. Note that sometimes some of the resulting routes will be identical (in the case of one route being optimal in more than one way), and a profile may not always yield a Route. | value | description | | ----- | ----------- | | quiet | Attempts to use roads with less traffic | | regular | The default profile, balances traffic with directness | | fast | Attempts to find the shortest sensible route | If no profiles are specified, 'regular' will be used. |
|
Language
|
language | string |
An IETF BCP 47 language tag that indicates the end-user's language preference. When provided, the response will contain a 'language' property that indicates the language used for any localizable elements of the response (such as turning instructions). This language will be a best-effort attempt to fulfill the expressed preference, but it may contain a value that wasn't expressed in the request (this will generally be 'en-US' as a fallback). Note that language preference will generally only affect Citymapper-generated content such as turning instructions. External content such as Stop names and Status descriptions will generally be passed through in their original language. |
|
Reroute Signature
|
reroute_signature | string |
When rerouting (requesting an update to a previous response that accounts for the user's updated location), this value should be set to the 'signature' provided in the original Route. This allows for more efficient determination of the updated Route. This value must be URL-encoded. When providing this parameter, the 'current_location' (when applicable) or 'start' location should be set to the user's latest location. When this parameter is included, Citymapper may not return results in cases where the request differs significantly from the original, for instance if the 'end' location is different, or if more than 1 hour has passed since the original request. |
|
Start Bearing
|
start_bearing | integer |
An angle clockwise from North between 0 and 359, where North is 0 and East is 90. This bearing is used to influence the initial instruction text and/or routing, most-commonly to avoid the user from being asked to make a u-turn, if continuing on their current bearing gives a comparable route. This should be provided only if you wish to influence the initial direction of travel for the route. |
|
Past Locations
|
past_loc_coords | string |
Optional parameter to improve rerouting behavior. The Coordinates of up to 10 of the past locations of the user as a comma separated list. Coordinates must be in WGS84 'latitude,longitude' format. Coordinates must be in decimal, and only the first 6 digits of precision will be used. Must be chronologically ordered, most recent last. 'past_loc_ages' and 'past_loc_accuracies' must be provided alongside. The server will only consider a maximum of 10 locations, if more than 10 locations are provided the least recent locations will be ignored. The server is likely to ignore any locations older than 30 seconds or any that are less than 1 second apart. |
|
Past Location Ages
|
past_loc_ages | string |
Optional parameter to improve rerouting behavior. The Ages of up to 10 of the past locations of the user as a comma separated list. Ages must be in integer seconds since the current location. Must be chronologically ordered, most recent last. 'past_loc_coords' and 'past_loc_accuracies' must be provided alongside. The server will only consider a maximum of 10 locations, if more than 10 locations are provided the least recent locations will be ignored. The server is likely to ignore any locations older than 30 seconds or any that are less than 1 second apart. |
|
Past Location Accuracies
|
past_loc_accuracies | string |
Optional parameter to improve rerouting behavior. The GPS Accuracies of up to 10 of the past locations of the user as a comma separated list. Accuracies must be in integer meters. Must be chronologically ordered, most recent last. 'past_loc_ages' and 'past_loc_coords' must be provided alongside. The server will only consider a maximum of 10 locations, if more than 10 locations are provided the least recent locations will be ignored. The server is likely to ignore any locations older than 30 seconds or any that are less than 1 second apart. |
Returns
Name | Path | Type | Description |
---|---|---|---|
routes
|
routes | array of object | |
Latitude
|
routes.start.coordinates.lat | float |
A latitude in WGS84 encoding, with 6 digits of decimal precision. |
Longitude
|
routes.start.coordinates.lon | float |
A longitude in WGS84 encoding, with 6 digits of decimal precision. |
Latitude
|
routes.end.coordinates.lat | float |
A latitude in WGS84 encoding, with 6 digits of decimal precision. |
Longitude
|
routes.end.coordinates.lon | float |
A longitude in WGS84 encoding, with 6 digits of decimal precision. |
Distance in Meters
|
routes.distance_meters | integer |
The overall distance of the entire Route, in meters. |
Duration
|
routes.duration_seconds | integer |
The overall estimated time to traverse the entire Route, in seconds, based on the selected vehicle or departure in the response. |
Duration Accuracy
|
routes.duration_accuracy | string |
Citymapper's assessment of how the accuracy level of 'duration_seconds' should be displayed to the user. This is largely based on the 'type' of the Departures used for times, but it involves additional heuristics developed over time for the Citymapper app. When this field is not provided, the value 'scheduled' should be used. | value | description | | ----- | ----------- | | estimated | A duration that should be considered approximate, as its calculation involved more uncertainty than usual. This is the lowest accuracy. | | scheduled | A normal duration, typically based on published timetable information. | | live | A duration largely based on real-time/live departure information. This is the highest accuracy. | |
Formatted
|
routes.price.formatted | string |
The given price as a formatted string. By default, this is in the native currency format of the region where the route occurs. |
Amount
|
routes.price.amount | string |
The price as a decimal value, encoded as a string to avoid floating-point accuracy issues. It will not include currency symbols, and the separator between major and minor units will always be '.', regardless of the region. |
Amount Range Minimum
|
routes.price.amount_range_minimum | string |
If this Price represents a range of possible values, the minimum price as a decimal value, encoded as a string to avoid floating-point accuracy issues. It will not include currency symbols, and the separator between major and minor units will always be '.', regardless of the region. |
Amount range Maximum
|
routes.price.amount_range_maximum | string |
If this Price represents a range of possible values, the maximum price as a decimal value, encoded as a string to avoid floating-point accuracy issues. It will not include currency symbols, and the separator between major and minor units will always be '.', regardless of the region. This may not be included if the range is open-ended |
Currency
|
routes.price.currency | string |
The currency in which the price is given, in three-letter ISO 4217 form. |
Demand Multiplier
|
routes.price.demand_multipler | float |
Indicates that prices are higher than usual because of demand, usually for Taxi (On-Demand) legs. May in rare cases be less than 1.0 |
CO2e Emissions
|
routes.emissions_grams_co2e | float |
An estimate of the greenhouse gas emissions of the route, expressed in grams of carbon dioxide equivalent (CO2e). |
Legs
|
routes.legs | array of object |
Array of legs comprising the Route, in the order in which they should be traversed. Every valid route will have at least one. |
Travel Mode
|
routes.legs.travel_mode | string |
The travel mode. |
Duration
|
routes.legs.duration_seconds | integer |
The time required to traverse this leg, excluding any waiting or boarding time at the beginning. May be omitted in rare circumstances when the duration cannot be computed. |
Path
|
routes.legs.path | string |
The geographic path that the leg traverses, as a series of WGS84 coordinates encoded in Google Polyline Format, with a decimal precision of 5 digits. For example, the value '_flyHbjPDZBTBNDJ' encodes the following series of (latitude, longitude) coordinates: '' [(51.51344, -0.08882), (51.51341, -0.08896), (51.51339, -0.08907), (51.51337, -0.08915), (51.51334, -0.08921)] '' |
Instructions
|
routes.legs.instructions | array of object |
This provides the list of turn instructions to guide the user through legs where the user needs to navigate, such as when walking or using a scooter or bike. |
Path Index
|
routes.legs.instructions.path_index | integer |
0-based index into the list of coordinates provided by the 'path' property of the leg. This indicates the location at which the instruction is to be followed, so it will be the location of the turn on the path, or the start or end of the leg. |
Distance
|
routes.legs.instructions.distance_meters | integer |
The distance in meters of the section of the 'path' prior to this instruction. This property will be omitted for initial instructions of type 'depart'. |
Time
|
routes.legs.instructions.time_seconds | integer |
The time in seconds that the user is expected to take to traverse the section of the 'path' prior to this instruction. This property will be omitted for initial instructions of type 'depart'. |
Description
|
routes.legs.instructions.description_text | string |
Plain-text description of the Instruction to the user. |
Description Format
|
routes.legs.instructions.description_format | string |
Text format for rendering the Instruction with emphasized elements, where '{key}' indicates a part of the string that must be replaced with content defined by the entry corresponding to 'key' in 'description_format_replacements'. This allows the elements described by the replacements to be formatted differently by the client, if desired. Key strings will contain only the characters '[a-zA-Z0-9]'. '{ }' will not be nested, and the literal characters '{' and '}' are encoded by the escape sequences '{' and '}', respectively. |
description_format_replacements
|
routes.legs.instructions.description_format_replacements | array of object | |
Key
|
routes.legs.instructions.description_format_replacements.key | string |
A key corresponding to a string enclosed in '{}' in 'description_format'. |
Text
|
routes.legs.instructions.description_format_replacements.text | string |
The text to be used to replace the '{key}' substring in the 'description_format'. |
Type
|
routes.legs.instructions.description_format_replacements.type | string |
A value indicating what kind of real-world thing is being identified by this format replacement. This allows service clients to apply application-specific formatting if desired. | value | description | | ----- | ----------- | | street_name | The name of a street, road, or other way | | exit_number | The number of an exit, generally from a roundabout | |
Language
|
routes.legs.instructions.description_format_replacements.language | string |
An IETF BCP 47 language tag that indicates what language the associated 'text' is in. Note that this can be different from the language of the surrounding description - this is most common when the replacement is a place-name in a local language whilst the description is in a different language. |
Type
|
routes.legs.instructions.type | string |
Indicates the type of Instruction. |
Type Direction
|
routes.legs.instructions.type_direction | string |
Indicates a direction that modifies this Instruction. |
Departure Time
|
routes.route_departure_time | string |
The time at which Citymapper thinks the user will set out on this route, given available departure information. This is computed assuming that user is at the start of the route. Updated values for 'route_departure_time' and 'route_arrival_time' are returned by 'service/1/live/routeupdates' to reflect any updated departure information. The time is expressed in ISO 8601 format, including a date, time, and time zone in which the event occurs. For example, '2020-08-19T08:10:42-04:00' expresses August 19, 2020 at 8:10am in Eastern Daylight Time. |
Arrival Time
|
routes.route_arrival_time | string |
The time at which Citymapper thinks the user will arrive at the end of this route, given available departure information and expected travel speed. This is computed assuming that user is at the start of the route. Updated values for 'route_departure_time' and 'route_arrival_time' are returned by 'service/1/live/routeupdates' to reflect any updated departure information. The time is expressed in ISO 8601 format, including a date, time, and time zone in which the event occurs. For example, '2020-08-19T08:10:42-04:00' expresses August 19, 2020 at 8:10am in Eastern Daylight Time. |
groups
|
routes.route_metadata.groups | array of object | |
Group ID
|
routes.route_metadata.groups.group_id | string |
ID of a group a route contains in. |
Group
|
routes.route_metadata.groups.group_name | string |
Localized name of a route group, e.g. 'Transit' or 'Le metro'. |
Route Position
|
routes.route_metadata.groups.route_position | integer |
A zero-based position of a route within specific group. |
Profile Name
|
routes.route_metadata.profile_name | string |
Human-readable localized name of the 'profile' identifier. |
Profile
|
routes.profile | string |
Indicates which routing 'profile' was used to calculate this Route. For example, a response from a bike routing endpoint may return multiple routes, one with a 'quiet' profile and another with a 'fast' profile. Note that new values can be added at any time, so any code parsing this field must be able to handle unexpected values. This value will match the 'profiles' request parameter on endpoints that support selecting specific routing profiles. This value is intended to be machine readable only. For a profile name to show to a user, use the 'profile_name' in the 'route_metadata' object instead. |
Signature
|
routes.signature | string |
A value to be passed back to the server in subsequent calls to refer to this route (for instance, when requesting live departure information via 'service/1/live/routeupdates'). It must be treated as an opaque value. |
Requested Time
|
routes.requested_time | string |
Contains the 'time' parameter used as a departure or arrival time constraint when getting directions, if applicable. |
Requested Time Type
|
routes.requested_time_type | string |
Contains the 'time_type' parameter used to determine how the 'time' will be used to constrain the directions that are returned, if applicable. If no parameter was given in the request, will return the 'time_type' used by default to plan the Route. |
Language
|
language | string |
A IETF BCP 47 language tag that indicates the language used to encode localizable content, such as turning instructions, in this response. This will reflect a best-effort attempt to fulfill any language preference expressed by the 'language' request parameter, or 'en-US' as default. |
Gets a car route between two points, providing enough information to render it on a map, along with a duration estimate. This call assumes that the rider has a car at the 'start' point, and provides a car route from there to the 'end' point if both are within Citymapper's supported areas. The resulting route should contain a single car leg. The maximum great-circle distance between the start and end is limited to 1000km for this service.
Parameters
Name | Key | Required | Type | Description |
---|---|---|---|---|
Start
|
start | True | array |
The geographical start of the route, in WGS84 'latitude,longitude' format. Coordinates should be in decimal, and only the first 6 decimal places will be used. |
End
|
end | True | array |
The geographical end of the route, in WGS84 'latitude,longitude' format. Coordinates should be in decimal, and only the first 6 decimal places will be used. |
Language
|
language | string |
An IETF BCP 47 language tag that indicates the end-user's language preference. When provided, the response will contain a 'language' property that indicates the language used for any localizable elements of the response (such as turning instructions). This language will be a best-effort attempt to fulfill the expressed preference, but it may contain a value that wasn't expressed in the request (this will generally be 'en-US' as a fallback). Note that language preference will generally only affect Citymapper-generated content such as turning instructions. External content such as Stop names and Status descriptions will generally be passed through in their original language. |
Returns
Name | Path | Type | Description |
---|---|---|---|
routes
|
routes | array of object | |
Latitude
|
routes.start.coordinates.lat | float |
A latitude in WGS84 encoding, with 6 digits of decimal precision. |
Longitude
|
routes.start.coordinates.lon | float |
A longitude in WGS84 encoding, with 6 digits of decimal precision. |
Latitude
|
routes.end.coordinates.lat | float |
A latitude in WGS84 encoding, with 6 digits of decimal precision. |
Longitude
|
routes.end.coordinates.lon | float |
A longitude in WGS84 encoding, with 6 digits of decimal precision. |
Distance in Meters
|
routes.distance_meters | integer |
The overall distance of the entire Route, in meters. |
Duration
|
routes.duration_seconds | integer |
The overall estimated time to traverse the entire Route, in seconds, based on the selected vehicle or departure in the response. |
Duration Accuracy
|
routes.duration_accuracy | string |
Citymapper's assessment of how the accuracy level of 'duration_seconds' should be displayed to the user. This is largely based on the 'type' of the Departures used for times, but it involves additional heuristics developed over time for the Citymapper app. When this field is not provided, the value 'scheduled' should be used. | value | description | | ----- | ----------- | | estimated | A duration that should be considered approximate, as its calculation involved more uncertainty than usual. This is the lowest accuracy. | | scheduled | A normal duration, typically based on published timetable information. | | live | A duration largely based on real-time/live departure information. This is the highest accuracy. | |
Formatted
|
routes.price.formatted | string |
The given price as a formatted string. By default, this is in the native currency format of the region where the route occurs. |
Amount
|
routes.price.amount | string |
The price as a decimal value, encoded as a string to avoid floating-point accuracy issues. It will not include currency symbols, and the separator between major and minor units will always be '.', regardless of the region. |
Amount Range Minimum
|
routes.price.amount_range_minimum | string |
If this Price represents a range of possible values, the minimum price as a decimal value, encoded as a string to avoid floating-point accuracy issues. It will not include currency symbols, and the separator between major and minor units will always be '.', regardless of the region. |
Amount range Maximum
|
routes.price.amount_range_maximum | string |
If this Price represents a range of possible values, the maximum price as a decimal value, encoded as a string to avoid floating-point accuracy issues. It will not include currency symbols, and the separator between major and minor units will always be '.', regardless of the region. This may not be included if the range is open-ended |
Currency
|
routes.price.currency | string |
The currency in which the price is given, in three-letter ISO 4217 form. |
Demand Multiplier
|
routes.price.demand_multipler | float |
Indicates that prices are higher than usual because of demand, usually for Taxi (On-Demand) legs. May in rare cases be less than 1.0 |
CO2e Emissions
|
routes.emissions_grams_co2e | float |
An estimate of the greenhouse gas emissions of the route, expressed in grams of carbon dioxide equivalent (CO2e). |
Legs
|
routes.legs | array of object |
Array of legs comprising the Route, in the order in which they should be traversed. Every valid route will have at least one. |
Travel Mode
|
routes.legs.travel_mode | string |
The travel mode. |
Duration
|
routes.legs.duration_seconds | integer |
The time required to traverse this leg, excluding any waiting or boarding time at the beginning. May be omitted in rare circumstances when the duration cannot be computed. |
Path
|
routes.legs.path | string |
The geographic path that the leg traverses, as a series of WGS84 coordinates encoded in Google Polyline Format, with a decimal precision of 5 digits. For example, the value '_flyHbjPDZBTBNDJ' encodes the following series of (latitude, longitude) coordinates: '' [(51.51344, -0.08882), (51.51341, -0.08896), (51.51339, -0.08907), (51.51337, -0.08915), (51.51334, -0.08921)] '' |
Instructions
|
routes.legs.instructions | array of object |
This provides the list of turn instructions to guide the user through legs where the user needs to navigate, such as when walking or using a scooter or bike. |
Path Index
|
routes.legs.instructions.path_index | integer |
0-based index into the list of coordinates provided by the 'path' property of the leg. This indicates the location at which the instruction is to be followed, so it will be the location of the turn on the path, or the start or end of the leg. |
Distance
|
routes.legs.instructions.distance_meters | integer |
The distance in meters of the section of the 'path' prior to this instruction. This property will be omitted for initial instructions of type 'depart'. |
Time
|
routes.legs.instructions.time_seconds | integer |
The time in seconds that the user is expected to take to traverse the section of the 'path' prior to this instruction. This property will be omitted for initial instructions of type 'depart'. |
Description
|
routes.legs.instructions.description_text | string |
Plain-text description of the Instruction to the user. |
Description Format
|
routes.legs.instructions.description_format | string |
Text format for rendering the Instruction with emphasized elements, where '{key}' indicates a part of the string that must be replaced with content defined by the entry corresponding to 'key' in 'description_format_replacements'. This allows the elements described by the replacements to be formatted differently by the client, if desired. Key strings will contain only the characters '[a-zA-Z0-9]'. '{ }' will not be nested, and the literal characters '{' and '}' are encoded by the escape sequences '{' and '}', respectively. |
description_format_replacements
|
routes.legs.instructions.description_format_replacements | array of object | |
Key
|
routes.legs.instructions.description_format_replacements.key | string |
A key corresponding to a string enclosed in '{}' in 'description_format'. |
Text
|
routes.legs.instructions.description_format_replacements.text | string |
The text to be used to replace the '{key}' substring in the 'description_format'. |
Type
|
routes.legs.instructions.description_format_replacements.type | string |
A value indicating what kind of real-world thing is being identified by this format replacement. This allows service clients to apply application-specific formatting if desired. | value | description | | ----- | ----------- | | street_name | The name of a street, road, or other way | | exit_number | The number of an exit, generally from a roundabout | |
Language
|
routes.legs.instructions.description_format_replacements.language | string |
An IETF BCP 47 language tag that indicates what language the associated 'text' is in. Note that this can be different from the language of the surrounding description - this is most common when the replacement is a place-name in a local language whilst the description is in a different language. |
Type
|
routes.legs.instructions.type | string |
Indicates the type of Instruction. |
Type Direction
|
routes.legs.instructions.type_direction | string |
Indicates a direction that modifies this Instruction. |
Departure Time
|
routes.route_departure_time | string |
The time at which Citymapper thinks the user will set out on this route, given available departure information. This is computed assuming that user is at the start of the route. Updated values for 'route_departure_time' and 'route_arrival_time' are returned by 'service/1/live/routeupdates' to reflect any updated departure information. The time is expressed in ISO 8601 format, including a date, time, and time zone in which the event occurs. For example, '2020-08-19T08:10:42-04:00' expresses August 19, 2020 at 8:10am in Eastern Daylight Time. |
Arrival Time
|
routes.route_arrival_time | string |
The time at which Citymapper thinks the user will arrive at the end of this route, given available departure information and expected travel speed. This is computed assuming that user is at the start of the route. Updated values for 'route_departure_time' and 'route_arrival_time' are returned by 'service/1/live/routeupdates' to reflect any updated departure information. The time is expressed in ISO 8601 format, including a date, time, and time zone in which the event occurs. For example, '2020-08-19T08:10:42-04:00' expresses August 19, 2020 at 8:10am in Eastern Daylight Time. |
groups
|
routes.route_metadata.groups | array of object | |
Group ID
|
routes.route_metadata.groups.group_id | string |
ID of a group a route contains in. |
Group
|
routes.route_metadata.groups.group_name | string |
Localized name of a route group, e.g. 'Transit' or 'Le metro'. |
Route Position
|
routes.route_metadata.groups.route_position | integer |
A zero-based position of a route within specific group. |
Profile Name
|
routes.route_metadata.profile_name | string |
Human-readable localized name of the 'profile' identifier. |
Profile
|
routes.profile | string |
Indicates which routing 'profile' was used to calculate this Route. For example, a response from a bike routing endpoint may return multiple routes, one with a 'quiet' profile and another with a 'fast' profile. Note that new values can be added at any time, so any code parsing this field must be able to handle unexpected values. This value will match the 'profiles' request parameter on endpoints that support selecting specific routing profiles. This value is intended to be machine readable only. For a profile name to show to a user, use the 'profile_name' in the 'route_metadata' object instead. |
Signature
|
routes.signature | string |
A value to be passed back to the server in subsequent calls to refer to this route (for instance, when requesting live departure information via 'service/1/live/routeupdates'). It must be treated as an opaque value. |
Requested Time
|
routes.requested_time | string |
Contains the 'time' parameter used as a departure or arrival time constraint when getting directions, if applicable. |
Requested Time Type
|
routes.requested_time_type | string |
Contains the 'time_type' parameter used to determine how the 'time' will be used to constrain the directions that are returned, if applicable. If no parameter was given in the request, will return the 'time_type' used by default to plan the Route. |
Language
|
language | string |
A IETF BCP 47 language tag that indicates the language used to encode localizable content, such as turning instructions, in this response. This will reflect a best-effort attempt to fulfill any language preference expressed by the 'language' request parameter, or 'en-US' as default. |
Gets a hired bike route between two points, including any initial and final walks. The resulting route provides enough information to render it on a map, along with a duration estimate. This call can be used in several different ways: Use any bike of the specified Brand This is the simplest call, only requiring 'start', 'end', and 'brand_id'. Citymapper assumes that the user is at the 'start' point, and chooses a bike of the specified Brand, if possible. Use a bike at a specified location By adding 'original_vehicle_location' to 'start', 'end', and 'brand_id', Citymapper plans a route that assumes the bike is at the given location. Update a route in progress In order to retrieve an updated route that includes rerouting from the user's current location if they've diverged from the planned Route, the caller can add the 'current_location' and 'ride_state' properties, which indicates which leg of the resulting route should be rerouted around the user's 'current_location'.
Parameters
Name | Key | Required | Type | Description |
---|---|---|---|---|
Start
|
start | True | array |
The geographical start of the route, in WGS84 'latitude,longitude' format. Coordinates should be in decimal, and only the first 6 decimal places will be used. |
End
|
end | True | array |
The geographical end of the route, in WGS84 'latitude,longitude' format. Coordinates should be in decimal, and only the first 6 decimal places will be used. |
Brand ID
|
brand_id | True | string |
The ID of the Brand of bike to use for this route. This is necessary in order to determine the location of available bikes, along with any associated coverage and parking restrictions. |
State
|
ride_state | string |
Indicates where along the route the user is. If omitted, 'walking_to_vehicle' is used. This property along with 'current_location' allows the retrieval of an updated route that reflects the user's current progress through it. | value | description | | ----- | ----------- | | walking_to_vehicle | Indicates that the user is walking to collect the vehicle | | riding | Indicates that the user is riding the vehicle | | walking_to_end | Indicates that the user has left the vehicle and is walking to their destination | |
|
Current Location
|
current_location | string |
The user's current location, in order to update the route based on the user's location. Provided in WGS84 'latitude,longitude' format. Coordinates should be in decimal, and only the first 6 digits of precision will be used. This parameter is used to get an updated route that reflects the user's actual location if they diverge from the path given in the Route. If this is provided, the returned route will contain this location. Which leg of the route will contain this location is decided by the value of the 'ride_state' parameter. |
|
Start Location
|
ride_start_location | string |
The location of the vehicle to be used, at the beginning of the vehicle ride part of the user's trip along the Route. Provided in WGS84 'latitude,longitude' format. Coordinates should be in decimal, and only the first 6 digits of precision will be used. This must be provided when 'ride_state' is 'riding' or 'walking_to_end'. If not provided when 'ride_state' is 'walking_to_vehicle' (or not specified), Citymapper will attempt to find the most appropriate vehicle that belongs to the specified 'brand_id'. For compatibility, 'original_vehicle_location' is an alias for this parameter |
|
End Location
|
ride_end_location | string |
The location the vehicle was dropped off at the end of the vehicle ride part of the user's trip along the Route. Provided in WGS84 'latitude,longitude' format. Coordinates should be in decimal, and only the first 6 digits of precision will be used. This must be provided when 'ride_state' is 'walking_to_end'. In all other states this parameter is ignored. |
|
Profiles
|
profiles | string |
Indicates which 'profiles' to use when calculating bike directions. Each profile can generate a different route option, so requesting more profiles will generally give more options. Note that sometimes some of the resulting routes will be identical (in the case of one route being optimal in more than one way), and a profile may not always yield a Route. | value | description | | ----- | ----------- | | quiet | Attempts to use roads with less traffic | | regular | The default profile, balances traffic with directness | | fast | Attempts to find the shortest sensible route | If no profiles are specified, 'regular' will be used. |
|
Language
|
language | string |
An IETF BCP 47 language tag that indicates the end-user's language preference. When provided, the response will contain a 'language' property that indicates the language used for any localizable elements of the response (such as turning instructions). This language will be a best-effort attempt to fulfill the expressed preference, but it may contain a value that wasn't expressed in the request (this will generally be 'en-US' as a fallback). Note that language preference will generally only affect Citymapper-generated content such as turning instructions. External content such as Stop names and Status descriptions will generally be passed through in their original language. |
|
Reroute Signature
|
reroute_signature | string |
When rerouting (requesting an update to a previous response that accounts for the user's updated location), this value should be set to the 'signature' provided in the original Route. This allows for more efficient determination of the updated Route. This value must be URL-encoded. When providing this parameter, the 'current_location' (when applicable) or 'start' location should be set to the user's latest location. When this parameter is included, Citymapper may not return results in cases where the request differs significantly from the original, for instance if the 'end' location is different, or if more than 1 hour has passed since the original request. |
|
Start Bearing
|
start_bearing | integer |
An angle clockwise from North between 0 and 359, where North is 0 and East is 90. This bearing is used to influence the initial instruction text and/or routing, most-commonly to avoid the user from being asked to make a u-turn, if continuing on their current bearing gives a comparable route. This should be provided only if you wish to influence the initial direction of travel for the route. |
|
Past Locations
|
past_loc_coords | string |
Optional parameter to improve rerouting behavior. The Coordinates of up to 10 of the past locations of the user as a comma separated list. Coordinates must be in WGS84 'latitude,longitude' format. Coordinates must be in decimal, and only the first 6 digits of precision will be used. Must be chronologically ordered, most recent last. 'past_loc_ages' and 'past_loc_accuracies' must be provided alongside. The server will only consider a maximum of 10 locations, if more than 10 locations are provided the least recent locations will be ignored. The server is likely to ignore any locations older than 30 seconds or any that are less than 1 second apart. |
|
Past Location Ages
|
past_loc_ages | string |
Optional parameter to improve rerouting behavior. The Ages of up to 10 of the past locations of the user as a comma separated list. Ages must be in integer seconds since the current location. Must be chronologically ordered, most recent last. 'past_loc_coords' and 'past_loc_accuracies' must be provided alongside. The server will only consider a maximum of 10 locations, if more than 10 locations are provided the least recent locations will be ignored. The server is likely to ignore any locations older than 30 seconds or any that are less than 1 second apart. |
|
Past Location Accuracies
|
past_loc_accuracies | string |
Optional parameter to improve rerouting behavior. The GPS Accuracies of up to 10 of the past locations of the user as a comma separated list. Accuracies must be in integer meters. Must be chronologically ordered, most recent last. 'past_loc_ages' and 'past_loc_coords' must be provided alongside. The server will only consider a maximum of 10 locations, if more than 10 locations are provided the least recent locations will be ignored. The server is likely to ignore any locations older than 30 seconds or any that are less than 1 second apart. |
Returns
Name | Path | Type | Description |
---|---|---|---|
routes
|
routes | array of object | |
Latitude
|
routes.start.coordinates.lat | float |
A latitude in WGS84 encoding, with 6 digits of decimal precision. |
Longitude
|
routes.start.coordinates.lon | float |
A longitude in WGS84 encoding, with 6 digits of decimal precision. |
Latitude
|
routes.end.coordinates.lat | float |
A latitude in WGS84 encoding, with 6 digits of decimal precision. |
Longitude
|
routes.end.coordinates.lon | float |
A longitude in WGS84 encoding, with 6 digits of decimal precision. |
Distance in Meters
|
routes.distance_meters | integer |
The overall distance of the entire Route, in meters. |
Duration
|
routes.duration_seconds | integer |
The overall estimated time to traverse the entire Route, in seconds, based on the selected vehicle or departure in the response. |
Duration Accuracy
|
routes.duration_accuracy | string |
Citymapper's assessment of how the accuracy level of 'duration_seconds' should be displayed to the user. This is largely based on the 'type' of the Departures used for times, but it involves additional heuristics developed over time for the Citymapper app. When this field is not provided, the value 'scheduled' should be used. | value | description | | ----- | ----------- | | estimated | A duration that should be considered approximate, as its calculation involved more uncertainty than usual. This is the lowest accuracy. | | scheduled | A normal duration, typically based on published timetable information. | | live | A duration largely based on real-time/live departure information. This is the highest accuracy. | |
Formatted
|
routes.price.formatted | string |
The given price as a formatted string. By default, this is in the native currency format of the region where the route occurs. |
Amount
|
routes.price.amount | string |
The price as a decimal value, encoded as a string to avoid floating-point accuracy issues. It will not include currency symbols, and the separator between major and minor units will always be '.', regardless of the region. |
Amount Range Minimum
|
routes.price.amount_range_minimum | string |
If this Price represents a range of possible values, the minimum price as a decimal value, encoded as a string to avoid floating-point accuracy issues. It will not include currency symbols, and the separator between major and minor units will always be '.', regardless of the region. |
Amount range Maximum
|
routes.price.amount_range_maximum | string |
If this Price represents a range of possible values, the maximum price as a decimal value, encoded as a string to avoid floating-point accuracy issues. It will not include currency symbols, and the separator between major and minor units will always be '.', regardless of the region. This may not be included if the range is open-ended |
Currency
|
routes.price.currency | string |
The currency in which the price is given, in three-letter ISO 4217 form. |
Demand Multiplier
|
routes.price.demand_multipler | float |
Indicates that prices are higher than usual because of demand, usually for Taxi (On-Demand) legs. May in rare cases be less than 1.0 |
CO2e Emissions
|
routes.emissions_grams_co2e | float |
An estimate of the greenhouse gas emissions of the route, expressed in grams of carbon dioxide equivalent (CO2e). |
Legs
|
routes.legs | array of object |
Array of legs comprising the Route, in the order in which they should be traversed. Every valid route will have at least one. |
Travel Mode
|
routes.legs.travel_mode | string |
The travel mode. |
Duration
|
routes.legs.duration_seconds | integer |
The time required to traverse this leg, excluding any waiting or boarding time at the beginning. May be omitted in rare circumstances when the duration cannot be computed. |
Path
|
routes.legs.path | string |
The geographic path that the leg traverses, as a series of WGS84 coordinates encoded in Google Polyline Format, with a decimal precision of 5 digits. For example, the value '_flyHbjPDZBTBNDJ' encodes the following series of (latitude, longitude) coordinates: '' [(51.51344, -0.08882), (51.51341, -0.08896), (51.51339, -0.08907), (51.51337, -0.08915), (51.51334, -0.08921)] '' |
Instructions
|
routes.legs.instructions | array of object |
This provides the list of turn instructions to guide the user through legs where the user needs to navigate, such as when walking or using a scooter or bike. |
Path Index
|
routes.legs.instructions.path_index | integer |
0-based index into the list of coordinates provided by the 'path' property of the leg. This indicates the location at which the instruction is to be followed, so it will be the location of the turn on the path, or the start or end of the leg. |
Distance
|
routes.legs.instructions.distance_meters | integer |
The distance in meters of the section of the 'path' prior to this instruction. This property will be omitted for initial instructions of type 'depart'. |
Time
|
routes.legs.instructions.time_seconds | integer |
The time in seconds that the user is expected to take to traverse the section of the 'path' prior to this instruction. This property will be omitted for initial instructions of type 'depart'. |
Description
|
routes.legs.instructions.description_text | string |
Plain-text description of the Instruction to the user. |
Description Format
|
routes.legs.instructions.description_format | string |
Text format for rendering the Instruction with emphasized elements, where '{key}' indicates a part of the string that must be replaced with content defined by the entry corresponding to 'key' in 'description_format_replacements'. This allows the elements described by the replacements to be formatted differently by the client, if desired. Key strings will contain only the characters '[a-zA-Z0-9]'. '{ }' will not be nested, and the literal characters '{' and '}' are encoded by the escape sequences '{' and '}', respectively. |
description_format_replacements
|
routes.legs.instructions.description_format_replacements | array of object | |
Key
|
routes.legs.instructions.description_format_replacements.key | string |
A key corresponding to a string enclosed in '{}' in 'description_format'. |
Text
|
routes.legs.instructions.description_format_replacements.text | string |
The text to be used to replace the '{key}' substring in the 'description_format'. |
Type
|
routes.legs.instructions.description_format_replacements.type | string |
A value indicating what kind of real-world thing is being identified by this format replacement. This allows service clients to apply application-specific formatting if desired. | value | description | | ----- | ----------- | | street_name | The name of a street, road, or other way | | exit_number | The number of an exit, generally from a roundabout | |
Language
|
routes.legs.instructions.description_format_replacements.language | string |
An IETF BCP 47 language tag that indicates what language the associated 'text' is in. Note that this can be different from the language of the surrounding description - this is most common when the replacement is a place-name in a local language whilst the description is in a different language. |
Type
|
routes.legs.instructions.type | string |
Indicates the type of Instruction. |
Type Direction
|
routes.legs.instructions.type_direction | string |
Indicates a direction that modifies this Instruction. |
Departure Time
|
routes.route_departure_time | string |
The time at which Citymapper thinks the user will set out on this route, given available departure information. This is computed assuming that user is at the start of the route. Updated values for 'route_departure_time' and 'route_arrival_time' are returned by 'service/1/live/routeupdates' to reflect any updated departure information. The time is expressed in ISO 8601 format, including a date, time, and time zone in which the event occurs. For example, '2020-08-19T08:10:42-04:00' expresses August 19, 2020 at 8:10am in Eastern Daylight Time. |
Arrival Time
|
routes.route_arrival_time | string |
The time at which Citymapper thinks the user will arrive at the end of this route, given available departure information and expected travel speed. This is computed assuming that user is at the start of the route. Updated values for 'route_departure_time' and 'route_arrival_time' are returned by 'service/1/live/routeupdates' to reflect any updated departure information. The time is expressed in ISO 8601 format, including a date, time, and time zone in which the event occurs. For example, '2020-08-19T08:10:42-04:00' expresses August 19, 2020 at 8:10am in Eastern Daylight Time. |
groups
|
routes.route_metadata.groups | array of object | |
Group ID
|
routes.route_metadata.groups.group_id | string |
ID of a group a route contains in. |
Group
|
routes.route_metadata.groups.group_name | string |
Localized name of a route group, e.g. 'Transit' or 'Le metro'. |
Route Position
|
routes.route_metadata.groups.route_position | integer |
A zero-based position of a route within specific group. |
Profile Name
|
routes.route_metadata.profile_name | string |
Human-readable localized name of the 'profile' identifier. |
Profile
|
routes.profile | string |
Indicates which routing 'profile' was used to calculate this Route. For example, a response from a bike routing endpoint may return multiple routes, one with a 'quiet' profile and another with a 'fast' profile. Note that new values can be added at any time, so any code parsing this field must be able to handle unexpected values. This value will match the 'profiles' request parameter on endpoints that support selecting specific routing profiles. This value is intended to be machine readable only. For a profile name to show to a user, use the 'profile_name' in the 'route_metadata' object instead. |
Signature
|
routes.signature | string |
A value to be passed back to the server in subsequent calls to refer to this route (for instance, when requesting live departure information via 'service/1/live/routeupdates'). It must be treated as an opaque value. |
Requested Time
|
routes.requested_time | string |
Contains the 'time' parameter used as a departure or arrival time constraint when getting directions, if applicable. |
Requested Time Type
|
routes.requested_time_type | string |
Contains the 'time_type' parameter used to determine how the 'time' will be used to constrain the directions that are returned, if applicable. If no parameter was given in the request, will return the 'time_type' used by default to plan the Route. |
Language
|
language | string |
A IETF BCP 47 language tag that indicates the language used to encode localizable content, such as turning instructions, in this response. This will reflect a best-effort attempt to fulfill any language preference expressed by the 'language' request parameter, or 'en-US' as default. |
Gets a hired motor scooter route between two points, including any initial and final walks. The resulting route provides enough information to render it on a map, along with a duration estimate. (These results are optimized for larger internal combustion or electric scooters where the rider is seated.) NOTE: The resulting route currently assumes that the user can ride directly to the specified 'end' location, not taking into account any parking or coverage zones. Thus, the resulting route will contain only an initial leg of 'travel_mode' 'walk' and a second leg of 'travel_mode' 'self_piloted'. A future update will incorporate parking and coverage zones and add a final 'walk' leg. This call can be used in several different ways: Use any scooter of the specified Brand This is the simplest call, only requiring 'start', 'end', and 'brand_id'. Citymapper assumes that the user is at the 'start' point, and chooses a scooter of the specified Brand, if possible. Use a scooter at a specified location By adding 'original_vehicle_location' to 'start', 'end', and 'brand_id', Citymapper plans a route that assumes the scooter is at the given location. Update a route in progress In order to retrieve an updated route that includes rerouting from the user's current location if they've diverged from the planned Route, the caller can add the 'current_location' and 'ride_state' properties, which indicates which leg of the resulting route should be rerouted around the user's 'current_location'.
Parameters
Name | Key | Required | Type | Description |
---|---|---|---|---|
Start
|
start | True | array |
The geographical start of the route, in WGS84 'latitude,longitude' format. Coordinates should be in decimal, and only the first 6 decimal places will be used. |
End
|
end | True | array |
The geographical end of the route, in WGS84 'latitude,longitude' format. Coordinates should be in decimal, and only the first 6 decimal places will be used. |
Brand ID
|
brand_id | True | string |
The ID of the Brand of scooters to use for this route. This is necessary in order to determine the location of available scooters, along with any associated coverage and parking restrictions. |
State
|
ride_state | string |
Indicates where along the route the user is. If omitted, 'walking_to_vehicle' is used. This property along with 'current_location' allows the retrieval of an updated route that reflects the user's current progress through it. | value | description | | ----- | ----------- | | walking_to_vehicle | Indicates that the user is walking to collect the vehicle | | riding | Indicates that the user is riding the vehicle | | walking_to_end | Indicates that the user has left the vehicle and is walking to their destination | |
|
Current Location
|
current_location | string |
The user's current location, in order to update the route based on the user's location. Provided in WGS84 'latitude,longitude' format. Coordinates should be in decimal, and only the first 6 digits of precision will be used. This parameter is used to get an updated route that reflects the user's actual location if they diverge from the path given in the Route. If this is provided, the returned route will contain this location. Which leg of the route will contain this location is decided by the value of the 'ride_state' parameter. |
|
Start Location
|
ride_start_location | string |
The location of the vehicle to be used, at the beginning of the vehicle ride part of the user's trip along the Route. Provided in WGS84 'latitude,longitude' format. Coordinates should be in decimal, and only the first 6 digits of precision will be used. This must be provided when 'ride_state' is 'riding' or 'walking_to_end'. If not provided when 'ride_state' is 'walking_to_vehicle' (or not specified), Citymapper will attempt to find the most appropriate vehicle that belongs to the specified 'brand_id'. For compatibility, 'original_vehicle_location' is an alias for this parameter |
|
End Location
|
ride_end_location | string |
The location the vehicle was dropped off at the end of the vehicle ride part of the user's trip along the Route. Provided in WGS84 'latitude,longitude' format. Coordinates should be in decimal, and only the first 6 digits of precision will be used. This must be provided when 'ride_state' is 'walking_to_end'. In all other states this parameter is ignored. |
|
Language
|
language | string |
An IETF BCP 47 language tag that indicates the end-user's language preference. When provided, the response will contain a 'language' property that indicates the language used for any localizable elements of the response (such as turning instructions). This language will be a best-effort attempt to fulfill the expressed preference, but it may contain a value that wasn't expressed in the request (this will generally be 'en-US' as a fallback). Note that language preference will generally only affect Citymapper-generated content such as turning instructions. External content such as Stop names and Status descriptions will generally be passed through in their original language. |
|
Reroute Signature
|
reroute_signature | string |
When rerouting (requesting an update to a previous response that accounts for the user's updated location), this value should be set to the 'signature' provided in the original Route. This allows for more efficient determination of the updated Route. This value must be URL-encoded. When providing this parameter, the 'current_location' (when applicable) or 'start' location should be set to the user's latest location. When this parameter is included, Citymapper may not return results in cases where the request differs significantly from the original, for instance if the 'end' location is different, or if more than 1 hour has passed since the original request. |
|
Start Bearing
|
start_bearing | integer |
An angle clockwise from North between 0 and 359, where North is 0 and East is 90. This bearing is used to influence the initial instruction text and/or routing, most-commonly to avoid the user from being asked to make a u-turn, if continuing on their current bearing gives a comparable route. This should be provided only if you wish to influence the initial direction of travel for the route. |
Returns
Name | Path | Type | Description |
---|---|---|---|
routes
|
routes | array of object | |
Latitude
|
routes.start.coordinates.lat | float |
A latitude in WGS84 encoding, with 6 digits of decimal precision. |
Longitude
|
routes.start.coordinates.lon | float |
A longitude in WGS84 encoding, with 6 digits of decimal precision. |
Latitude
|
routes.end.coordinates.lat | float |
A latitude in WGS84 encoding, with 6 digits of decimal precision. |
Longitude
|
routes.end.coordinates.lon | float |
A longitude in WGS84 encoding, with 6 digits of decimal precision. |
Distance in Meters
|
routes.distance_meters | integer |
The overall distance of the entire Route, in meters. |
Duration
|
routes.duration_seconds | integer |
The overall estimated time to traverse the entire Route, in seconds, based on the selected vehicle or departure in the response. |
Duration Accuracy
|
routes.duration_accuracy | string |
Citymapper's assessment of how the accuracy level of 'duration_seconds' should be displayed to the user. This is largely based on the 'type' of the Departures used for times, but it involves additional heuristics developed over time for the Citymapper app. When this field is not provided, the value 'scheduled' should be used. | value | description | | ----- | ----------- | | estimated | A duration that should be considered approximate, as its calculation involved more uncertainty than usual. This is the lowest accuracy. | | scheduled | A normal duration, typically based on published timetable information. | | live | A duration largely based on real-time/live departure information. This is the highest accuracy. | |
Formatted
|
routes.price.formatted | string |
The given price as a formatted string. By default, this is in the native currency format of the region where the route occurs. |
Amount
|
routes.price.amount | string |
The price as a decimal value, encoded as a string to avoid floating-point accuracy issues. It will not include currency symbols, and the separator between major and minor units will always be '.', regardless of the region. |
Amount Range Minimum
|
routes.price.amount_range_minimum | string |
If this Price represents a range of possible values, the minimum price as a decimal value, encoded as a string to avoid floating-point accuracy issues. It will not include currency symbols, and the separator between major and minor units will always be '.', regardless of the region. |
Amount range Maximum
|
routes.price.amount_range_maximum | string |
If this Price represents a range of possible values, the maximum price as a decimal value, encoded as a string to avoid floating-point accuracy issues. It will not include currency symbols, and the separator between major and minor units will always be '.', regardless of the region. This may not be included if the range is open-ended |
Currency
|
routes.price.currency | string |
The currency in which the price is given, in three-letter ISO 4217 form. |
Demand Multiplier
|
routes.price.demand_multipler | float |
Indicates that prices are higher than usual because of demand, usually for Taxi (On-Demand) legs. May in rare cases be less than 1.0 |
CO2e Emissions
|
routes.emissions_grams_co2e | float |
An estimate of the greenhouse gas emissions of the route, expressed in grams of carbon dioxide equivalent (CO2e). |
Legs
|
routes.legs | array of object |
Array of legs comprising the Route, in the order in which they should be traversed. Every valid route will have at least one. |
Travel Mode
|
routes.legs.travel_mode | string |
The travel mode. |
Duration
|
routes.legs.duration_seconds | integer |
The time required to traverse this leg, excluding any waiting or boarding time at the beginning. May be omitted in rare circumstances when the duration cannot be computed. |
Path
|
routes.legs.path | string |
The geographic path that the leg traverses, as a series of WGS84 coordinates encoded in Google Polyline Format, with a decimal precision of 5 digits. For example, the value '_flyHbjPDZBTBNDJ' encodes the following series of (latitude, longitude) coordinates: '' [(51.51344, -0.08882), (51.51341, -0.08896), (51.51339, -0.08907), (51.51337, -0.08915), (51.51334, -0.08921)] '' |
Instructions
|
routes.legs.instructions | array of object |
This provides the list of turn instructions to guide the user through legs where the user needs to navigate, such as when walking or using a scooter or bike. |
Path Index
|
routes.legs.instructions.path_index | integer |
0-based index into the list of coordinates provided by the 'path' property of the leg. This indicates the location at which the instruction is to be followed, so it will be the location of the turn on the path, or the start or end of the leg. |
Distance
|
routes.legs.instructions.distance_meters | integer |
The distance in meters of the section of the 'path' prior to this instruction. This property will be omitted for initial instructions of type 'depart'. |
Time
|
routes.legs.instructions.time_seconds | integer |
The time in seconds that the user is expected to take to traverse the section of the 'path' prior to this instruction. This property will be omitted for initial instructions of type 'depart'. |
Description
|
routes.legs.instructions.description_text | string |
Plain-text description of the Instruction to the user. |
Description Format
|
routes.legs.instructions.description_format | string |
Text format for rendering the Instruction with emphasized elements, where '{key}' indicates a part of the string that must be replaced with content defined by the entry corresponding to 'key' in 'description_format_replacements'. This allows the elements described by the replacements to be formatted differently by the client, if desired. Key strings will contain only the characters '[a-zA-Z0-9]'. '{ }' will not be nested, and the literal characters '{' and '}' are encoded by the escape sequences '{' and '}', respectively. |
description_format_replacements
|
routes.legs.instructions.description_format_replacements | array of object | |
Key
|
routes.legs.instructions.description_format_replacements.key | string |
A key corresponding to a string enclosed in '{}' in 'description_format'. |
Text
|
routes.legs.instructions.description_format_replacements.text | string |
The text to be used to replace the '{key}' substring in the 'description_format'. |
Type
|
routes.legs.instructions.description_format_replacements.type | string |
A value indicating what kind of real-world thing is being identified by this format replacement. This allows service clients to apply application-specific formatting if desired. | value | description | | ----- | ----------- | | street_name | The name of a street, road, or other way | | exit_number | The number of an exit, generally from a roundabout | |
Language
|
routes.legs.instructions.description_format_replacements.language | string |
An IETF BCP 47 language tag that indicates what language the associated 'text' is in. Note that this can be different from the language of the surrounding description - this is most common when the replacement is a place-name in a local language whilst the description is in a different language. |
Type
|
routes.legs.instructions.type | string |
Indicates the type of Instruction. |
Type Direction
|
routes.legs.instructions.type_direction | string |
Indicates a direction that modifies this Instruction. |
Departure Time
|
routes.route_departure_time | string |
The time at which Citymapper thinks the user will set out on this route, given available departure information. This is computed assuming that user is at the start of the route. Updated values for 'route_departure_time' and 'route_arrival_time' are returned by 'service/1/live/routeupdates' to reflect any updated departure information. The time is expressed in ISO 8601 format, including a date, time, and time zone in which the event occurs. For example, '2020-08-19T08:10:42-04:00' expresses August 19, 2020 at 8:10am in Eastern Daylight Time. |
Arrival Time
|
routes.route_arrival_time | string |
The time at which Citymapper thinks the user will arrive at the end of this route, given available departure information and expected travel speed. This is computed assuming that user is at the start of the route. Updated values for 'route_departure_time' and 'route_arrival_time' are returned by 'service/1/live/routeupdates' to reflect any updated departure information. The time is expressed in ISO 8601 format, including a date, time, and time zone in which the event occurs. For example, '2020-08-19T08:10:42-04:00' expresses August 19, 2020 at 8:10am in Eastern Daylight Time. |
groups
|
routes.route_metadata.groups | array of object | |
Group ID
|
routes.route_metadata.groups.group_id | string |
ID of a group a route contains in. |
Group
|
routes.route_metadata.groups.group_name | string |
Localized name of a route group, e.g. 'Transit' or 'Le metro'. |
Route Position
|
routes.route_metadata.groups.route_position | integer |
A zero-based position of a route within specific group. |
Profile Name
|
routes.route_metadata.profile_name | string |
Human-readable localized name of the 'profile' identifier. |
Profile
|
routes.profile | string |
Indicates which routing 'profile' was used to calculate this Route. For example, a response from a bike routing endpoint may return multiple routes, one with a 'quiet' profile and another with a 'fast' profile. Note that new values can be added at any time, so any code parsing this field must be able to handle unexpected values. This value will match the 'profiles' request parameter on endpoints that support selecting specific routing profiles. This value is intended to be machine readable only. For a profile name to show to a user, use the 'profile_name' in the 'route_metadata' object instead. |
Signature
|
routes.signature | string |
A value to be passed back to the server in subsequent calls to refer to this route (for instance, when requesting live departure information via 'service/1/live/routeupdates'). It must be treated as an opaque value. |
Requested Time
|
routes.requested_time | string |
Contains the 'time' parameter used as a departure or arrival time constraint when getting directions, if applicable. |
Requested Time Type
|
routes.requested_time_type | string |
Contains the 'time_type' parameter used to determine how the 'time' will be used to constrain the directions that are returned, if applicable. If no parameter was given in the request, will return the 'time_type' used by default to plan the Route. |
Language
|
language | string |
A IETF BCP 47 language tag that indicates the language used to encode localizable content, such as turning instructions, in this response. This will reflect a best-effort attempt to fulfill any language preference expressed by the 'language' request parameter, or 'en-US' as default. |
Gets a motor scooter route between two points, providing enough information to render it on a map, along with a duration estimate. (These results are optimized for larger internal combustion or electric scooters where the rider is seated.) This call assumes that the rider has a scooter at the 'start' point, and provides an e-scooter route from there to the 'end' point if both are within Citymapper's supported areas. The resulting route should contain a single scooter leg, though the 'path_annotations' property of the leg may indicate sections during which the user should walk beside the scooter. This call does not incorporate any information about scooter operators' coverage or parking areas, but other service calls may be available to do so.
Parameters
Name | Key | Required | Type | Description |
---|---|---|---|---|
Start
|
start | True | array |
The geographical start of the route, in WGS84 'latitude,longitude' format. Coordinates should be in decimal, and only the first 6 decimal places will be used. |
End
|
end | True | array |
The geographical end of the route, in WGS84 'latitude,longitude' format. Coordinates should be in decimal, and only the first 6 decimal places will be used. |
Language
|
language | string |
An IETF BCP 47 language tag that indicates the end-user's language preference. When provided, the response will contain a 'language' property that indicates the language used for any localizable elements of the response (such as turning instructions). This language will be a best-effort attempt to fulfill the expressed preference, but it may contain a value that wasn't expressed in the request (this will generally be 'en-US' as a fallback). Note that language preference will generally only affect Citymapper-generated content such as turning instructions. External content such as Stop names and Status descriptions will generally be passed through in their original language. |
|
Reroute Signature
|
reroute_signature | string |
When rerouting (requesting an update to a previous response that accounts for the user's updated location), this value should be set to the 'signature' provided in the original Route. This allows for more efficient determination of the updated Route. This value must be URL-encoded. When providing this parameter, the 'current_location' (when applicable) or 'start' location should be set to the user's latest location. When this parameter is included, Citymapper may not return results in cases where the request differs significantly from the original, for instance if the 'end' location is different, or if more than 1 hour has passed since the original request. |
|
Start Bearing
|
start_bearing | integer |
An angle clockwise from North between 0 and 359, where North is 0 and East is 90. This bearing is used to influence the initial instruction text and/or routing, most-commonly to avoid the user from being asked to make a u-turn, if continuing on their current bearing gives a comparable route. This should be provided only if you wish to influence the initial direction of travel for the route. |
Returns
Name | Path | Type | Description |
---|---|---|---|
routes
|
routes | array of object | |
Latitude
|
routes.start.coordinates.lat | float |
A latitude in WGS84 encoding, with 6 digits of decimal precision. |
Longitude
|
routes.start.coordinates.lon | float |
A longitude in WGS84 encoding, with 6 digits of decimal precision. |
Latitude
|
routes.end.coordinates.lat | float |
A latitude in WGS84 encoding, with 6 digits of decimal precision. |
Longitude
|
routes.end.coordinates.lon | float |
A longitude in WGS84 encoding, with 6 digits of decimal precision. |
Distance in Meters
|
routes.distance_meters | integer |
The overall distance of the entire Route, in meters. |
Duration
|
routes.duration_seconds | integer |
The overall estimated time to traverse the entire Route, in seconds, based on the selected vehicle or departure in the response. |
Duration Accuracy
|
routes.duration_accuracy | string |
Citymapper's assessment of how the accuracy level of 'duration_seconds' should be displayed to the user. This is largely based on the 'type' of the Departures used for times, but it involves additional heuristics developed over time for the Citymapper app. When this field is not provided, the value 'scheduled' should be used. | value | description | | ----- | ----------- | | estimated | A duration that should be considered approximate, as its calculation involved more uncertainty than usual. This is the lowest accuracy. | | scheduled | A normal duration, typically based on published timetable information. | | live | A duration largely based on real-time/live departure information. This is the highest accuracy. | |
Formatted
|
routes.price.formatted | string |
The given price as a formatted string. By default, this is in the native currency format of the region where the route occurs. |
Amount
|
routes.price.amount | string |
The price as a decimal value, encoded as a string to avoid floating-point accuracy issues. It will not include currency symbols, and the separator between major and minor units will always be '.', regardless of the region. |
Amount Range Minimum
|
routes.price.amount_range_minimum | string |
If this Price represents a range of possible values, the minimum price as a decimal value, encoded as a string to avoid floating-point accuracy issues. It will not include currency symbols, and the separator between major and minor units will always be '.', regardless of the region. |
Amount range Maximum
|
routes.price.amount_range_maximum | string |
If this Price represents a range of possible values, the maximum price as a decimal value, encoded as a string to avoid floating-point accuracy issues. It will not include currency symbols, and the separator between major and minor units will always be '.', regardless of the region. This may not be included if the range is open-ended |
Currency
|
routes.price.currency | string |
The currency in which the price is given, in three-letter ISO 4217 form. |
Demand Multiplier
|
routes.price.demand_multipler | float |
Indicates that prices are higher than usual because of demand, usually for Taxi (On-Demand) legs. May in rare cases be less than 1.0 |
CO2e Emissions
|
routes.emissions_grams_co2e | float |
An estimate of the greenhouse gas emissions of the route, expressed in grams of carbon dioxide equivalent (CO2e). |
Legs
|
routes.legs | array of object |
Array of legs comprising the Route, in the order in which they should be traversed. Every valid route will have at least one. |
Travel Mode
|
routes.legs.travel_mode | string |
The travel mode. |
Duration
|
routes.legs.duration_seconds | integer |
The time required to traverse this leg, excluding any waiting or boarding time at the beginning. May be omitted in rare circumstances when the duration cannot be computed. |
Path
|
routes.legs.path | string |
The geographic path that the leg traverses, as a series of WGS84 coordinates encoded in Google Polyline Format, with a decimal precision of 5 digits. For example, the value '_flyHbjPDZBTBNDJ' encodes the following series of (latitude, longitude) coordinates: '' [(51.51344, -0.08882), (51.51341, -0.08896), (51.51339, -0.08907), (51.51337, -0.08915), (51.51334, -0.08921)] '' |
Instructions
|
routes.legs.instructions | array of object |
This provides the list of turn instructions to guide the user through legs where the user needs to navigate, such as when walking or using a scooter or bike. |
Path Index
|
routes.legs.instructions.path_index | integer |
0-based index into the list of coordinates provided by the 'path' property of the leg. This indicates the location at which the instruction is to be followed, so it will be the location of the turn on the path, or the start or end of the leg. |
Distance
|
routes.legs.instructions.distance_meters | integer |
The distance in meters of the section of the 'path' prior to this instruction. This property will be omitted for initial instructions of type 'depart'. |
Time
|
routes.legs.instructions.time_seconds | integer |
The time in seconds that the user is expected to take to traverse the section of the 'path' prior to this instruction. This property will be omitted for initial instructions of type 'depart'. |
Description
|
routes.legs.instructions.description_text | string |
Plain-text description of the Instruction to the user. |
Description Format
|
routes.legs.instructions.description_format | string |
Text format for rendering the Instruction with emphasized elements, where '{key}' indicates a part of the string that must be replaced with content defined by the entry corresponding to 'key' in 'description_format_replacements'. This allows the elements described by the replacements to be formatted differently by the client, if desired. Key strings will contain only the characters '[a-zA-Z0-9]'. '{ }' will not be nested, and the literal characters '{' and '}' are encoded by the escape sequences '{' and '}', respectively. |
description_format_replacements
|
routes.legs.instructions.description_format_replacements | array of object | |
Key
|
routes.legs.instructions.description_format_replacements.key | string |
A key corresponding to a string enclosed in '{}' in 'description_format'. |
Text
|
routes.legs.instructions.description_format_replacements.text | string |
The text to be used to replace the '{key}' substring in the 'description_format'. |
Type
|
routes.legs.instructions.description_format_replacements.type | string |
A value indicating what kind of real-world thing is being identified by this format replacement. This allows service clients to apply application-specific formatting if desired. | value | description | | ----- | ----------- | | street_name | The name of a street, road, or other way | | exit_number | The number of an exit, generally from a roundabout | |
Language
|
routes.legs.instructions.description_format_replacements.language | string |
An IETF BCP 47 language tag that indicates what language the associated 'text' is in. Note that this can be different from the language of the surrounding description - this is most common when the replacement is a place-name in a local language whilst the description is in a different language. |
Type
|
routes.legs.instructions.type | string |
Indicates the type of Instruction. |
Type Direction
|
routes.legs.instructions.type_direction | string |
Indicates a direction that modifies this Instruction. |
Departure Time
|
routes.route_departure_time | string |
The time at which Citymapper thinks the user will set out on this route, given available departure information. This is computed assuming that user is at the start of the route. Updated values for 'route_departure_time' and 'route_arrival_time' are returned by 'service/1/live/routeupdates' to reflect any updated departure information. The time is expressed in ISO 8601 format, including a date, time, and time zone in which the event occurs. For example, '2020-08-19T08:10:42-04:00' expresses August 19, 2020 at 8:10am in Eastern Daylight Time. |
Arrival Time
|
routes.route_arrival_time | string |
The time at which Citymapper thinks the user will arrive at the end of this route, given available departure information and expected travel speed. This is computed assuming that user is at the start of the route. Updated values for 'route_departure_time' and 'route_arrival_time' are returned by 'service/1/live/routeupdates' to reflect any updated departure information. The time is expressed in ISO 8601 format, including a date, time, and time zone in which the event occurs. For example, '2020-08-19T08:10:42-04:00' expresses August 19, 2020 at 8:10am in Eastern Daylight Time. |
groups
|
routes.route_metadata.groups | array of object | |
Group ID
|
routes.route_metadata.groups.group_id | string |
ID of a group a route contains in. |
Group
|
routes.route_metadata.groups.group_name | string |
Localized name of a route group, e.g. 'Transit' or 'Le metro'. |
Route Position
|
routes.route_metadata.groups.route_position | integer |
A zero-based position of a route within specific group. |
Profile Name
|
routes.route_metadata.profile_name | string |
Human-readable localized name of the 'profile' identifier. |
Profile
|
routes.profile | string |
Indicates which routing 'profile' was used to calculate this Route. For example, a response from a bike routing endpoint may return multiple routes, one with a 'quiet' profile and another with a 'fast' profile. Note that new values can be added at any time, so any code parsing this field must be able to handle unexpected values. This value will match the 'profiles' request parameter on endpoints that support selecting specific routing profiles. This value is intended to be machine readable only. For a profile name to show to a user, use the 'profile_name' in the 'route_metadata' object instead. |
Signature
|
routes.signature | string |
A value to be passed back to the server in subsequent calls to refer to this route (for instance, when requesting live departure information via 'service/1/live/routeupdates'). It must be treated as an opaque value. |
Requested Time
|
routes.requested_time | string |
Contains the 'time' parameter used as a departure or arrival time constraint when getting directions, if applicable. |
Requested Time Type
|
routes.requested_time_type | string |
Contains the 'time_type' parameter used to determine how the 'time' will be used to constrain the directions that are returned, if applicable. If no parameter was given in the request, will return the 'time_type' used by default to plan the Route. |
Language
|
language | string |
A IETF BCP 47 language tag that indicates the language used to encode localizable content, such as turning instructions, in this response. This will reflect a best-effort attempt to fulfill any language preference expressed by the 'language' request parameter, or 'en-US' as default. |
Computes routes between two points based on a provided scenario. One or more groups of routes can be provided depending on a scenario. Each group will contain several routes. Each route will contain one or more legs.
Parameters
Name | Key | Required | Type | Description |
---|---|---|---|---|
Scenario ID
|
scenario_id | True | string |
Scenario ID for directions. |
Start
|
start | True | array |
The geographical start of the route, in WGS84 'latitude,longitude' format. Coordinates should be in decimal, and only the first 6 decimal places will be used. |
End
|
end | True | array |
The geographical end of the route, in WGS84 'latitude,longitude' format. Coordinates should be in decimal, and only the first 6 decimal places will be used. |
Time
|
time | string |
The time to be used as a departure or arrival time constraint when getting directions. The time is expressed in ISO 8601 format, including a date, time, and time zone. For example, '2020-08-19T08:10:42-04:00' expresses August 19, 2020 at 8:10am in Eastern Daylight Time. |
|
Time Type
|
time_type | string |
When a 'time' value is given, this determines how the time will be used to constrain the directions that are returned. When this isn't specified, 'depart_approximate' is used. If no 'time' is given, this has no effect. | value | description | | ----- | ----------- | | arrive | Directions are chosen that get the user to their destination on or before 'time' | | depart | Directions are chosen assuming the user leaves their origin as soon after 'time' as possible | | depart_approximate | Similar to 'depart', but allowing for later departures in order to return more preferable options even if they leave a bit later. This is Citymapper's default way of choosing directions when the time isn't specified | |
|
Language
|
language | string |
An IETF BCP 47 language tag that indicates the end-user's language preference. When provided, the response will contain a 'language' property that indicates the language used for any localizable elements of the response (such as turning instructions). This language will be a best-effort attempt to fulfill the expressed preference, but it may contain a value that wasn't expressed in the request (this will generally be 'en-US' as a fallback). Note that language preference will generally only affect Citymapper-generated content such as turning instructions. External content such as Stop names and Status descriptions will generally be passed through in their original language. |
Returns
Name | Path | Type | Description |
---|---|---|---|
routes
|
routes | array of object | |
Latitude
|
routes.start.coordinates.lat | float |
A latitude in WGS84 encoding, with 6 digits of decimal precision. |
Longitude
|
routes.start.coordinates.lon | float |
A longitude in WGS84 encoding, with 6 digits of decimal precision. |
Latitude
|
routes.end.coordinates.lat | float |
A latitude in WGS84 encoding, with 6 digits of decimal precision. |
Longitude
|
routes.end.coordinates.lon | float |
A longitude in WGS84 encoding, with 6 digits of decimal precision. |
Distance in Meters
|
routes.distance_meters | integer |
The overall distance of the entire Route, in meters. |
Duration
|
routes.duration_seconds | integer |
The overall estimated time to traverse the entire Route, in seconds, based on the selected vehicle or departure in the response. |
Duration Accuracy
|
routes.duration_accuracy | string |
Citymapper's assessment of how the accuracy level of 'duration_seconds' should be displayed to the user. This is largely based on the 'type' of the Departures used for times, but it involves additional heuristics developed over time for the Citymapper app. When this field is not provided, the value 'scheduled' should be used. | value | description | | ----- | ----------- | | estimated | A duration that should be considered approximate, as its calculation involved more uncertainty than usual. This is the lowest accuracy. | | scheduled | A normal duration, typically based on published timetable information. | | live | A duration largely based on real-time/live departure information. This is the highest accuracy. | |
Formatted
|
routes.price.formatted | string |
The given price as a formatted string. By default, this is in the native currency format of the region where the route occurs. |
Amount
|
routes.price.amount | string |
The price as a decimal value, encoded as a string to avoid floating-point accuracy issues. It will not include currency symbols, and the separator between major and minor units will always be '.', regardless of the region. |
Amount Range Minimum
|
routes.price.amount_range_minimum | string |
If this Price represents a range of possible values, the minimum price as a decimal value, encoded as a string to avoid floating-point accuracy issues. It will not include currency symbols, and the separator between major and minor units will always be '.', regardless of the region. |
Amount range Maximum
|
routes.price.amount_range_maximum | string |
If this Price represents a range of possible values, the maximum price as a decimal value, encoded as a string to avoid floating-point accuracy issues. It will not include currency symbols, and the separator between major and minor units will always be '.', regardless of the region. This may not be included if the range is open-ended |
Currency
|
routes.price.currency | string |
The currency in which the price is given, in three-letter ISO 4217 form. |
Demand Multiplier
|
routes.price.demand_multipler | float |
Indicates that prices are higher than usual because of demand, usually for Taxi (On-Demand) legs. May in rare cases be less than 1.0 |
CO2e Emissions
|
routes.emissions_grams_co2e | float |
An estimate of the greenhouse gas emissions of the route, expressed in grams of carbon dioxide equivalent (CO2e). |
Legs
|
routes.legs | array of object |
Array of legs comprising the Route, in the order in which they should be traversed. Every valid route will have at least one. |
Travel Mode
|
routes.legs.travel_mode | string |
The travel mode. |
Duration
|
routes.legs.duration_seconds | integer |
The time required to traverse this leg, excluding any waiting or boarding time at the beginning. May be omitted in rare circumstances when the duration cannot be computed. |
Path
|
routes.legs.path | string |
The geographic path that the leg traverses, as a series of WGS84 coordinates encoded in Google Polyline Format, with a decimal precision of 5 digits. For example, the value '_flyHbjPDZBTBNDJ' encodes the following series of (latitude, longitude) coordinates: '' [(51.51344, -0.08882), (51.51341, -0.08896), (51.51339, -0.08907), (51.51337, -0.08915), (51.51334, -0.08921)] '' |
Instructions
|
routes.legs.instructions | array of object |
This provides the list of turn instructions to guide the user through legs where the user needs to navigate, such as when walking or using a scooter or bike. |
Path Index
|
routes.legs.instructions.path_index | integer |
0-based index into the list of coordinates provided by the 'path' property of the leg. This indicates the location at which the instruction is to be followed, so it will be the location of the turn on the path, or the start or end of the leg. |
Distance
|
routes.legs.instructions.distance_meters | integer |
The distance in meters of the section of the 'path' prior to this instruction. This property will be omitted for initial instructions of type 'depart'. |
Time
|
routes.legs.instructions.time_seconds | integer |
The time in seconds that the user is expected to take to traverse the section of the 'path' prior to this instruction. This property will be omitted for initial instructions of type 'depart'. |
Description
|
routes.legs.instructions.description_text | string |
Plain-text description of the Instruction to the user. |
Description Format
|
routes.legs.instructions.description_format | string |
Text format for rendering the Instruction with emphasized elements, where '{key}' indicates a part of the string that must be replaced with content defined by the entry corresponding to 'key' in 'description_format_replacements'. This allows the elements described by the replacements to be formatted differently by the client, if desired. Key strings will contain only the characters '[a-zA-Z0-9]'. '{ }' will not be nested, and the literal characters '{' and '}' are encoded by the escape sequences '{' and '}', respectively. |
description_format_replacements
|
routes.legs.instructions.description_format_replacements | array of object | |
Key
|
routes.legs.instructions.description_format_replacements.key | string |
A key corresponding to a string enclosed in '{}' in 'description_format'. |
Text
|
routes.legs.instructions.description_format_replacements.text | string |
The text to be used to replace the '{key}' substring in the 'description_format'. |
Type
|
routes.legs.instructions.description_format_replacements.type | string |
A value indicating what kind of real-world thing is being identified by this format replacement. This allows service clients to apply application-specific formatting if desired. | value | description | | ----- | ----------- | | street_name | The name of a street, road, or other way | | exit_number | The number of an exit, generally from a roundabout | |
Language
|
routes.legs.instructions.description_format_replacements.language | string |
An IETF BCP 47 language tag that indicates what language the associated 'text' is in. Note that this can be different from the language of the surrounding description - this is most common when the replacement is a place-name in a local language whilst the description is in a different language. |
Type
|
routes.legs.instructions.type | string |
Indicates the type of Instruction. |
Type Direction
|
routes.legs.instructions.type_direction | string |
Indicates a direction that modifies this Instruction. |
Departure Time
|
routes.route_departure_time | string |
The time at which Citymapper thinks the user will set out on this route, given available departure information. This is computed assuming that user is at the start of the route. Updated values for 'route_departure_time' and 'route_arrival_time' are returned by 'service/1/live/routeupdates' to reflect any updated departure information. The time is expressed in ISO 8601 format, including a date, time, and time zone in which the event occurs. For example, '2020-08-19T08:10:42-04:00' expresses August 19, 2020 at 8:10am in Eastern Daylight Time. |
Arrival Time
|
routes.route_arrival_time | string |
The time at which Citymapper thinks the user will arrive at the end of this route, given available departure information and expected travel speed. This is computed assuming that user is at the start of the route. Updated values for 'route_departure_time' and 'route_arrival_time' are returned by 'service/1/live/routeupdates' to reflect any updated departure information. The time is expressed in ISO 8601 format, including a date, time, and time zone in which the event occurs. For example, '2020-08-19T08:10:42-04:00' expresses August 19, 2020 at 8:10am in Eastern Daylight Time. |
groups
|
routes.route_metadata.groups | array of object | |
Group ID
|
routes.route_metadata.groups.group_id | string |
ID of a group a route contains in. |
Group
|
routes.route_metadata.groups.group_name | string |
Localized name of a route group, e.g. 'Transit' or 'Le metro'. |
Route Position
|
routes.route_metadata.groups.route_position | integer |
A zero-based position of a route within specific group. |
Profile Name
|
routes.route_metadata.profile_name | string |
Human-readable localized name of the 'profile' identifier. |
Profile
|
routes.profile | string |
Indicates which routing 'profile' was used to calculate this Route. For example, a response from a bike routing endpoint may return multiple routes, one with a 'quiet' profile and another with a 'fast' profile. Note that new values can be added at any time, so any code parsing this field must be able to handle unexpected values. This value will match the 'profiles' request parameter on endpoints that support selecting specific routing profiles. This value is intended to be machine readable only. For a profile name to show to a user, use the 'profile_name' in the 'route_metadata' object instead. |
Signature
|
routes.signature | string |
A value to be passed back to the server in subsequent calls to refer to this route (for instance, when requesting live departure information via 'service/1/live/routeupdates'). It must be treated as an opaque value. |
Requested Time
|
routes.requested_time | string |
Contains the 'time' parameter used as a departure or arrival time constraint when getting directions, if applicable. |
Requested Time Type
|
routes.requested_time_type | string |
Contains the 'time_type' parameter used to determine how the 'time' will be used to constrain the directions that are returned, if applicable. If no parameter was given in the request, will return the 'time_type' used by default to plan the Route. |
Language
|
language | string |
A IETF BCP 47 language tag that indicates the language used to encode localizable content, such as turning instructions, in this response. This will reflect a best-effort attempt to fulfill any language preference expressed by the 'language' request parameter, or 'en-US' as default. |
Gets a taxi route between two points. The resulting route provides enough information to render it on a map, along with a duration estimate. The route may contain starting and ending walk legs if the pick-up or drop-off points aren't close to the requested start and end coordinates. The Services in the response will vary depending on the local availability, time of day and, additionally, which Taxi service integrations have been configured for your account. There are two recommended ways to use this service: You can request a taxi route with live on-demand service estimates included up-front by calling with '?fetch_on_demand_services=true'; or you can make the initial request without fetching estimates which will respond with the non-live route, then immediately call '1/live/routeupdates' to get the additional live estimates. The first approach is simpler, but the second may better fit your use-case.
Parameters
Name | Key | Required | Type | Description |
---|---|---|---|---|
Start
|
start | True | array |
The geographical start of the route, in WGS84 'latitude,longitude' format. Coordinates should be in decimal, and only the first 6 decimal places will be used. |
End
|
end | True | array |
The geographical end of the route, in WGS84 'latitude,longitude' format. Coordinates should be in decimal, and only the first 6 decimal places will be used. |
Fetch On-Domain Services
|
fetch_on_demand_services | string |
If set to 'true', additional information will be requested from your Taxi service integrations to provide more accurate and complete pricing, duration and service availability, returned in the on-demand leg's updatable detail. To provide this, the Route's start and end locations need to be transmitted to these Third-Party services, including in the case that one or the other is the user's current or recent location. Be aware that you may need to have explicit informed consent from your end-user to set this to 'true' depending on applicable laws and regulations. If set to 'false' or omitted, no requests will be made to any Third-Party services. |
|
Brand IDs
|
brand_ids | array |
Comma-separated list of Brand IDs to limit this directions request to. If omitted (default), all brands available to you will have a Taxi route returned. |
|
Language
|
language | string |
An IETF BCP 47 language tag that indicates the end-user's language preference. When provided, the response will contain a 'language' property that indicates the language used for any localizable elements of the response (such as turning instructions). This language will be a best-effort attempt to fulfill the expressed preference, but it may contain a value that wasn't expressed in the request (this will generally be 'en-US' as a fallback). Note that language preference will generally only affect Citymapper-generated content such as turning instructions. External content such as Stop names and Status descriptions will generally be passed through in their original language. |
Returns
Name | Path | Type | Description |
---|---|---|---|
routes
|
routes | array of object | |
Latitude
|
routes.start.coordinates.lat | float |
A latitude in WGS84 encoding, with 6 digits of decimal precision. |
Longitude
|
routes.start.coordinates.lon | float |
A longitude in WGS84 encoding, with 6 digits of decimal precision. |
Latitude
|
routes.end.coordinates.lat | float |
A latitude in WGS84 encoding, with 6 digits of decimal precision. |
Longitude
|
routes.end.coordinates.lon | float |
A longitude in WGS84 encoding, with 6 digits of decimal precision. |
Distance in Meters
|
routes.distance_meters | integer |
The overall distance of the entire Route, in meters. |
Duration
|
routes.duration_seconds | integer |
The overall estimated time to traverse the entire Route, in seconds, based on the selected vehicle or departure in the response. |
Duration Accuracy
|
routes.duration_accuracy | string |
Citymapper's assessment of how the accuracy level of 'duration_seconds' should be displayed to the user. This is largely based on the 'type' of the Departures used for times, but it involves additional heuristics developed over time for the Citymapper app. When this field is not provided, the value 'scheduled' should be used. | value | description | | ----- | ----------- | | estimated | A duration that should be considered approximate, as its calculation involved more uncertainty than usual. This is the lowest accuracy. | | scheduled | A normal duration, typically based on published timetable information. | | live | A duration largely based on real-time/live departure information. This is the highest accuracy. | |
Formatted
|
routes.price.formatted | string |
The given price as a formatted string. By default, this is in the native currency format of the region where the route occurs. |
Amount
|
routes.price.amount | string |
The price as a decimal value, encoded as a string to avoid floating-point accuracy issues. It will not include currency symbols, and the separator between major and minor units will always be '.', regardless of the region. |
Amount Range Minimum
|
routes.price.amount_range_minimum | string |
If this Price represents a range of possible values, the minimum price as a decimal value, encoded as a string to avoid floating-point accuracy issues. It will not include currency symbols, and the separator between major and minor units will always be '.', regardless of the region. |
Amount range Maximum
|
routes.price.amount_range_maximum | string |
If this Price represents a range of possible values, the maximum price as a decimal value, encoded as a string to avoid floating-point accuracy issues. It will not include currency symbols, and the separator between major and minor units will always be '.', regardless of the region. This may not be included if the range is open-ended |
Currency
|
routes.price.currency | string |
The currency in which the price is given, in three-letter ISO 4217 form. |
Demand Multiplier
|
routes.price.demand_multipler | float |
Indicates that prices are higher than usual because of demand, usually for Taxi (On-Demand) legs. May in rare cases be less than 1.0 |
CO2e Emissions
|
routes.emissions_grams_co2e | float |
An estimate of the greenhouse gas emissions of the route, expressed in grams of carbon dioxide equivalent (CO2e). |
Legs
|
routes.legs | array of object |
Array of legs comprising the Route, in the order in which they should be traversed. Every valid route will have at least one. |
Travel Mode
|
routes.legs.travel_mode | string |
The travel mode. |
Duration
|
routes.legs.duration_seconds | integer |
The time required to traverse this leg, excluding any waiting or boarding time at the beginning. May be omitted in rare circumstances when the duration cannot be computed. |
Path
|
routes.legs.path | string |
The geographic path that the leg traverses, as a series of WGS84 coordinates encoded in Google Polyline Format, with a decimal precision of 5 digits. For example, the value '_flyHbjPDZBTBNDJ' encodes the following series of (latitude, longitude) coordinates: '' [(51.51344, -0.08882), (51.51341, -0.08896), (51.51339, -0.08907), (51.51337, -0.08915), (51.51334, -0.08921)] '' |
Instructions
|
routes.legs.instructions | array of object |
This provides the list of turn instructions to guide the user through legs where the user needs to navigate, such as when walking or using a scooter or bike. |
Path Index
|
routes.legs.instructions.path_index | integer |
0-based index into the list of coordinates provided by the 'path' property of the leg. This indicates the location at which the instruction is to be followed, so it will be the location of the turn on the path, or the start or end of the leg. |
Distance
|
routes.legs.instructions.distance_meters | integer |
The distance in meters of the section of the 'path' prior to this instruction. This property will be omitted for initial instructions of type 'depart'. |
Time
|
routes.legs.instructions.time_seconds | integer |
The time in seconds that the user is expected to take to traverse the section of the 'path' prior to this instruction. This property will be omitted for initial instructions of type 'depart'. |
Description
|
routes.legs.instructions.description_text | string |
Plain-text description of the Instruction to the user. |
Description Format
|
routes.legs.instructions.description_format | string |
Text format for rendering the Instruction with emphasized elements, where '{key}' indicates a part of the string that must be replaced with content defined by the entry corresponding to 'key' in 'description_format_replacements'. This allows the elements described by the replacements to be formatted differently by the client, if desired. Key strings will contain only the characters '[a-zA-Z0-9]'. '{ }' will not be nested, and the literal characters '{' and '}' are encoded by the escape sequences '{' and '}', respectively. |
description_format_replacements
|
routes.legs.instructions.description_format_replacements | array of object | |
Key
|
routes.legs.instructions.description_format_replacements.key | string |
A key corresponding to a string enclosed in '{}' in 'description_format'. |
Text
|
routes.legs.instructions.description_format_replacements.text | string |
The text to be used to replace the '{key}' substring in the 'description_format'. |
Type
|
routes.legs.instructions.description_format_replacements.type | string |
A value indicating what kind of real-world thing is being identified by this format replacement. This allows service clients to apply application-specific formatting if desired. | value | description | | ----- | ----------- | | street_name | The name of a street, road, or other way | | exit_number | The number of an exit, generally from a roundabout | |
Language
|
routes.legs.instructions.description_format_replacements.language | string |
An IETF BCP 47 language tag that indicates what language the associated 'text' is in. Note that this can be different from the language of the surrounding description - this is most common when the replacement is a place-name in a local language whilst the description is in a different language. |
Type
|
routes.legs.instructions.type | string |
Indicates the type of Instruction. |
Type Direction
|
routes.legs.instructions.type_direction | string |
Indicates a direction that modifies this Instruction. |
Departure Time
|
routes.route_departure_time | string |
The time at which Citymapper thinks the user will set out on this route, given available departure information. This is computed assuming that user is at the start of the route. Updated values for 'route_departure_time' and 'route_arrival_time' are returned by 'service/1/live/routeupdates' to reflect any updated departure information. The time is expressed in ISO 8601 format, including a date, time, and time zone in which the event occurs. For example, '2020-08-19T08:10:42-04:00' expresses August 19, 2020 at 8:10am in Eastern Daylight Time. |
Arrival Time
|
routes.route_arrival_time | string |
The time at which Citymapper thinks the user will arrive at the end of this route, given available departure information and expected travel speed. This is computed assuming that user is at the start of the route. Updated values for 'route_departure_time' and 'route_arrival_time' are returned by 'service/1/live/routeupdates' to reflect any updated departure information. The time is expressed in ISO 8601 format, including a date, time, and time zone in which the event occurs. For example, '2020-08-19T08:10:42-04:00' expresses August 19, 2020 at 8:10am in Eastern Daylight Time. |
groups
|
routes.route_metadata.groups | array of object | |
Group ID
|
routes.route_metadata.groups.group_id | string |
ID of a group a route contains in. |
Group
|
routes.route_metadata.groups.group_name | string |
Localized name of a route group, e.g. 'Transit' or 'Le metro'. |
Route Position
|
routes.route_metadata.groups.route_position | integer |
A zero-based position of a route within specific group. |
Profile Name
|
routes.route_metadata.profile_name | string |
Human-readable localized name of the 'profile' identifier. |
Profile
|
routes.profile | string |
Indicates which routing 'profile' was used to calculate this Route. For example, a response from a bike routing endpoint may return multiple routes, one with a 'quiet' profile and another with a 'fast' profile. Note that new values can be added at any time, so any code parsing this field must be able to handle unexpected values. This value will match the 'profiles' request parameter on endpoints that support selecting specific routing profiles. This value is intended to be machine readable only. For a profile name to show to a user, use the 'profile_name' in the 'route_metadata' object instead. |
Signature
|
routes.signature | string |
A value to be passed back to the server in subsequent calls to refer to this route (for instance, when requesting live departure information via 'service/1/live/routeupdates'). It must be treated as an opaque value. |
Requested Time
|
routes.requested_time | string |
Contains the 'time' parameter used as a departure or arrival time constraint when getting directions, if applicable. |
Requested Time Type
|
routes.requested_time_type | string |
Contains the 'time_type' parameter used to determine how the 'time' will be used to constrain the directions that are returned, if applicable. If no parameter was given in the request, will return the 'time_type' used by default to plan the Route. |
Language
|
language | string |
A IETF BCP 47 language tag that indicates the language used to encode localizable content, such as turning instructions, in this response. This will reflect a best-effort attempt to fulfill any language preference expressed by the 'language' request parameter, or 'en-US' as default. |
Computes several public transportation routes between two points. By default, the results will contain up to 5 routes. Each one will contain several legs: usually one at the start and end of the route with 'travel_mode' of 'walk', with at least one with 'travel_mode' of 'transit' in between.
Parameters
Name | Key | Required | Type | Description |
---|---|---|---|---|
Start
|
start | True | array |
The geographical start of the route, in WGS84 'latitude,longitude' format. Coordinates should be in decimal, and only the first 6 decimal places will be used. |
End
|
end | True | array |
The geographical end of the route, in WGS84 'latitude,longitude' format. Coordinates should be in decimal, and only the first 6 decimal places will be used. |
Time
|
time | string |
The time to be used as a departure or arrival time constraint when getting directions. The time is expressed in ISO 8601 format, including a date, time, and time zone. For example, '2020-08-19T08:10:42-04:00' expresses August 19, 2020 at 8:10am in Eastern Daylight Time. |
|
Time Type
|
time_type | string |
When a 'time' value is given, this determines how the time will be used to constrain the directions that are returned. When this isn't specified, 'depart_approximate' is used. If no 'time' is given, this has no effect. | value | description | | ----- | ----------- | | arrive | Directions are chosen that get the user to their destination on or before 'time' | | depart | Directions are chosen assuming the user leaves their origin as soon after 'time' as possible | | depart_approximate | Similar to 'depart', but allowing for later departures in order to return more preferable options even if they leave a bit later. This is Citymapper's default way of choosing directions when the time isn't specified | |
|
Language
|
language | string |
An IETF BCP 47 language tag that indicates the end-user's language preference. When provided, the response will contain a 'language' property that indicates the language used for any localizable elements of the response (such as turning instructions). This language will be a best-effort attempt to fulfill the expressed preference, but it may contain a value that wasn't expressed in the request (this will generally be 'en-US' as a fallback). Note that language preference will generally only affect Citymapper-generated content such as turning instructions. External content such as Stop names and Status descriptions will generally be passed through in their original language. |
|
Limit
|
limit | integer |
Maximum number of routes to return. |
Returns
Name | Path | Type | Description |
---|---|---|---|
routes
|
routes | array of object | |
Latitude
|
routes.start.coordinates.lat | float |
A latitude in WGS84 encoding, with 6 digits of decimal precision. |
Longitude
|
routes.start.coordinates.lon | float |
A longitude in WGS84 encoding, with 6 digits of decimal precision. |
Latitude
|
routes.end.coordinates.lat | float |
A latitude in WGS84 encoding, with 6 digits of decimal precision. |
Longitude
|
routes.end.coordinates.lon | float |
A longitude in WGS84 encoding, with 6 digits of decimal precision. |
Distance in Meters
|
routes.distance_meters | integer |
The overall distance of the entire Route, in meters. |
Duration
|
routes.duration_seconds | integer |
The overall estimated time to traverse the entire Route, in seconds, based on the selected vehicle or departure in the response. |
Duration Accuracy
|
routes.duration_accuracy | string |
Citymapper's assessment of how the accuracy level of 'duration_seconds' should be displayed to the user. This is largely based on the 'type' of the Departures used for times, but it involves additional heuristics developed over time for the Citymapper app. When this field is not provided, the value 'scheduled' should be used. | value | description | | ----- | ----------- | | estimated | A duration that should be considered approximate, as its calculation involved more uncertainty than usual. This is the lowest accuracy. | | scheduled | A normal duration, typically based on published timetable information. | | live | A duration largely based on real-time/live departure information. This is the highest accuracy. | |
Formatted
|
routes.price.formatted | string |
The given price as a formatted string. By default, this is in the native currency format of the region where the route occurs. |
Amount
|
routes.price.amount | string |
The price as a decimal value, encoded as a string to avoid floating-point accuracy issues. It will not include currency symbols, and the separator between major and minor units will always be '.', regardless of the region. |
Amount Range Minimum
|
routes.price.amount_range_minimum | string |
If this Price represents a range of possible values, the minimum price as a decimal value, encoded as a string to avoid floating-point accuracy issues. It will not include currency symbols, and the separator between major and minor units will always be '.', regardless of the region. |
Amount range Maximum
|
routes.price.amount_range_maximum | string |
If this Price represents a range of possible values, the maximum price as a decimal value, encoded as a string to avoid floating-point accuracy issues. It will not include currency symbols, and the separator between major and minor units will always be '.', regardless of the region. This may not be included if the range is open-ended |
Currency
|
routes.price.currency | string |
The currency in which the price is given, in three-letter ISO 4217 form. |
Demand Multiplier
|
routes.price.demand_multipler | float |
Indicates that prices are higher than usual because of demand, usually for Taxi (On-Demand) legs. May in rare cases be less than 1.0 |
CO2e Emissions
|
routes.emissions_grams_co2e | float |
An estimate of the greenhouse gas emissions of the route, expressed in grams of carbon dioxide equivalent (CO2e). |
Legs
|
routes.legs | array of object |
Array of legs comprising the Route, in the order in which they should be traversed. Every valid route will have at least one. |
Travel Mode
|
routes.legs.travel_mode | string |
The travel mode. |
Duration
|
routes.legs.duration_seconds | integer |
The time required to traverse this leg, excluding any waiting or boarding time at the beginning. May be omitted in rare circumstances when the duration cannot be computed. |
Path
|
routes.legs.path | string |
The geographic path that the leg traverses, as a series of WGS84 coordinates encoded in Google Polyline Format, with a decimal precision of 5 digits. For example, the value '_flyHbjPDZBTBNDJ' encodes the following series of (latitude, longitude) coordinates: '' [(51.51344, -0.08882), (51.51341, -0.08896), (51.51339, -0.08907), (51.51337, -0.08915), (51.51334, -0.08921)] '' |
Instructions
|
routes.legs.instructions | array of object |
This provides the list of turn instructions to guide the user through legs where the user needs to navigate, such as when walking or using a scooter or bike. |
Path Index
|
routes.legs.instructions.path_index | integer |
0-based index into the list of coordinates provided by the 'path' property of the leg. This indicates the location at which the instruction is to be followed, so it will be the location of the turn on the path, or the start or end of the leg. |
Distance
|
routes.legs.instructions.distance_meters | integer |
The distance in meters of the section of the 'path' prior to this instruction. This property will be omitted for initial instructions of type 'depart'. |
Time
|
routes.legs.instructions.time_seconds | integer |
The time in seconds that the user is expected to take to traverse the section of the 'path' prior to this instruction. This property will be omitted for initial instructions of type 'depart'. |
Description
|
routes.legs.instructions.description_text | string |
Plain-text description of the Instruction to the user. |
Description Format
|
routes.legs.instructions.description_format | string |
Text format for rendering the Instruction with emphasized elements, where '{key}' indicates a part of the string that must be replaced with content defined by the entry corresponding to 'key' in 'description_format_replacements'. This allows the elements described by the replacements to be formatted differently by the client, if desired. Key strings will contain only the characters '[a-zA-Z0-9]'. '{ }' will not be nested, and the literal characters '{' and '}' are encoded by the escape sequences '{' and '}', respectively. |
description_format_replacements
|
routes.legs.instructions.description_format_replacements | array of object | |
Key
|
routes.legs.instructions.description_format_replacements.key | string |
A key corresponding to a string enclosed in '{}' in 'description_format'. |
Text
|
routes.legs.instructions.description_format_replacements.text | string |
The text to be used to replace the '{key}' substring in the 'description_format'. |
Type
|
routes.legs.instructions.description_format_replacements.type | string |
A value indicating what kind of real-world thing is being identified by this format replacement. This allows service clients to apply application-specific formatting if desired. | value | description | | ----- | ----------- | | street_name | The name of a street, road, or other way | | exit_number | The number of an exit, generally from a roundabout | |
Language
|
routes.legs.instructions.description_format_replacements.language | string |
An IETF BCP 47 language tag that indicates what language the associated 'text' is in. Note that this can be different from the language of the surrounding description - this is most common when the replacement is a place-name in a local language whilst the description is in a different language. |
Type
|
routes.legs.instructions.type | string |
Indicates the type of Instruction. |
Type Direction
|
routes.legs.instructions.type_direction | string |
Indicates a direction that modifies this Instruction. |
Departure Time
|
routes.route_departure_time | string |
The time at which Citymapper thinks the user will set out on this route, given available departure information. This is computed assuming that user is at the start of the route. Updated values for 'route_departure_time' and 'route_arrival_time' are returned by 'service/1/live/routeupdates' to reflect any updated departure information. The time is expressed in ISO 8601 format, including a date, time, and time zone in which the event occurs. For example, '2020-08-19T08:10:42-04:00' expresses August 19, 2020 at 8:10am in Eastern Daylight Time. |
Arrival Time
|
routes.route_arrival_time | string |
The time at which Citymapper thinks the user will arrive at the end of this route, given available departure information and expected travel speed. This is computed assuming that user is at the start of the route. Updated values for 'route_departure_time' and 'route_arrival_time' are returned by 'service/1/live/routeupdates' to reflect any updated departure information. The time is expressed in ISO 8601 format, including a date, time, and time zone in which the event occurs. For example, '2020-08-19T08:10:42-04:00' expresses August 19, 2020 at 8:10am in Eastern Daylight Time. |
groups
|
routes.route_metadata.groups | array of object | |
Group ID
|
routes.route_metadata.groups.group_id | string |
ID of a group a route contains in. |
Group
|
routes.route_metadata.groups.group_name | string |
Localized name of a route group, e.g. 'Transit' or 'Le metro'. |
Route Position
|
routes.route_metadata.groups.route_position | integer |
A zero-based position of a route within specific group. |
Profile Name
|
routes.route_metadata.profile_name | string |
Human-readable localized name of the 'profile' identifier. |
Profile
|
routes.profile | string |
Indicates which routing 'profile' was used to calculate this Route. For example, a response from a bike routing endpoint may return multiple routes, one with a 'quiet' profile and another with a 'fast' profile. Note that new values can be added at any time, so any code parsing this field must be able to handle unexpected values. This value will match the 'profiles' request parameter on endpoints that support selecting specific routing profiles. This value is intended to be machine readable only. For a profile name to show to a user, use the 'profile_name' in the 'route_metadata' object instead. |
Signature
|
routes.signature | string |
A value to be passed back to the server in subsequent calls to refer to this route (for instance, when requesting live departure information via 'service/1/live/routeupdates'). It must be treated as an opaque value. |
Requested Time
|
routes.requested_time | string |
Contains the 'time' parameter used as a departure or arrival time constraint when getting directions, if applicable. |
Requested Time Type
|
routes.requested_time_type | string |
Contains the 'time_type' parameter used to determine how the 'time' will be used to constrain the directions that are returned, if applicable. If no parameter was given in the request, will return the 'time_type' used by default to plan the Route. |
Language
|
language | string |
A IETF BCP 47 language tag that indicates the language used to encode localizable content, such as turning instructions, in this response. This will reflect a best-effort attempt to fulfill any language preference expressed by the 'language' request parameter, or 'en-US' as default. |
Gets a walking route between two points, providing enough information to render it on a map, along with a duration estimate. Walking routes are expected to have a single leg with a 'travel_mode' of 'walk'. If Citymapper can't compute walking directions for those points (generally for coverage reasons), the service will return a code '400' response. The maximum great-circle distance between the 'start' and 'end' is limited to 100km for this service.
Parameters
Name | Key | Required | Type | Description |
---|---|---|---|---|
Start
|
start | True | array |
The geographical start of the route, in WGS84 'latitude,longitude' format. Coordinates should be in decimal, and only the first 6 decimal places will be used. |
End
|
end | True | array |
The geographical end of the route, in WGS84 'latitude,longitude' format. Coordinates should be in decimal, and only the first 6 decimal places will be used. |
Language
|
language | string |
An IETF BCP 47 language tag that indicates the end-user's language preference. When provided, the response will contain a 'language' property that indicates the language used for any localizable elements of the response (such as turning instructions). This language will be a best-effort attempt to fulfill the expressed preference, but it may contain a value that wasn't expressed in the request (this will generally be 'en-US' as a fallback). Note that language preference will generally only affect Citymapper-generated content such as turning instructions. External content such as Stop names and Status descriptions will generally be passed through in their original language. |
|
Profiles
|
profiles | string |
Indicates which 'profiles' to use when calculating walking directions. Each profile can generate a different route option, so requesting more profiles will generally give more options. Note that sometimes some of the resulting routes will be identical (in the case of one route being optimal in more than one way), and a profile may not always yield a Route. Not all profiles will be available for all start and end routes. Unavailable profiles will be omitted from the response. | value | description | | ----- | ----------- | | fast | The default profile, attempts to find the fastest sensible route | | main_roads | Attempts to avoid backstreets and parks | If no profiles are specified, 'fast' will be used. |
|
Reroute Signature
|
reroute_signature | string |
When rerouting (requesting an update to a previous response that accounts for the user's updated location), this value should be set to the 'signature' provided in the original Route. This allows for more efficient determination of the updated Route. This value must be URL-encoded. When providing this parameter, the 'current_location' (when applicable) or 'start' location should be set to the user's latest location. When this parameter is included, Citymapper may not return results in cases where the request differs significantly from the original, for instance if the 'end' location is different, or if more than 1 hour has passed since the original request. |
|
Start Bearing
|
start_bearing | integer |
An angle clockwise from North between 0 and 359, where North is 0 and East is 90. This bearing is used to influence the initial instruction text and/or routing, most-commonly to avoid the user from being asked to make a u-turn, if continuing on their current bearing gives a comparable route. This should be provided only if you wish to influence the initial direction of travel for the route. |
Returns
Name | Path | Type | Description |
---|---|---|---|
routes
|
routes | array of object | |
Latitude
|
routes.start.coordinates.lat | float |
A latitude in WGS84 encoding, with 6 digits of decimal precision. |
Longitude
|
routes.start.coordinates.lon | float |
A longitude in WGS84 encoding, with 6 digits of decimal precision. |
Latitude
|
routes.end.coordinates.lat | float |
A latitude in WGS84 encoding, with 6 digits of decimal precision. |
Longitude
|
routes.end.coordinates.lon | float |
A longitude in WGS84 encoding, with 6 digits of decimal precision. |
Distance in Meters
|
routes.distance_meters | integer |
The overall distance of the entire Route, in meters. |
Duration
|
routes.duration_seconds | integer |
The overall estimated time to traverse the entire Route, in seconds, based on the selected vehicle or departure in the response. |
Duration Accuracy
|
routes.duration_accuracy | string |
Citymapper's assessment of how the accuracy level of 'duration_seconds' should be displayed to the user. This is largely based on the 'type' of the Departures used for times, but it involves additional heuristics developed over time for the Citymapper app. When this field is not provided, the value 'scheduled' should be used. | value | description | | ----- | ----------- | | estimated | A duration that should be considered approximate, as its calculation involved more uncertainty than usual. This is the lowest accuracy. | | scheduled | A normal duration, typically based on published timetable information. | | live | A duration largely based on real-time/live departure information. This is the highest accuracy. | |
Formatted
|
routes.price.formatted | string |
The given price as a formatted string. By default, this is in the native currency format of the region where the route occurs. |
Amount
|
routes.price.amount | string |
The price as a decimal value, encoded as a string to avoid floating-point accuracy issues. It will not include currency symbols, and the separator between major and minor units will always be '.', regardless of the region. |
Amount Range Minimum
|
routes.price.amount_range_minimum | string |
If this Price represents a range of possible values, the minimum price as a decimal value, encoded as a string to avoid floating-point accuracy issues. It will not include currency symbols, and the separator between major and minor units will always be '.', regardless of the region. |
Amount range Maximum
|
routes.price.amount_range_maximum | string |
If this Price represents a range of possible values, the maximum price as a decimal value, encoded as a string to avoid floating-point accuracy issues. It will not include currency symbols, and the separator between major and minor units will always be '.', regardless of the region. This may not be included if the range is open-ended |
Currency
|
routes.price.currency | string |
The currency in which the price is given, in three-letter ISO 4217 form. |
Demand Multiplier
|
routes.price.demand_multipler | float |
Indicates that prices are higher than usual because of demand, usually for Taxi (On-Demand) legs. May in rare cases be less than 1.0 |
CO2e Emissions
|
routes.emissions_grams_co2e | float |
An estimate of the greenhouse gas emissions of the route, expressed in grams of carbon dioxide equivalent (CO2e). |
Legs
|
routes.legs | array of object |
Array of legs comprising the Route, in the order in which they should be traversed. Every valid route will have at least one. |
Travel Mode
|
routes.legs.travel_mode | string |
The travel mode. |
Duration
|
routes.legs.duration_seconds | integer |
The time required to traverse this leg, excluding any waiting or boarding time at the beginning. May be omitted in rare circumstances when the duration cannot be computed. |
Path
|
routes.legs.path | string |
The geographic path that the leg traverses, as a series of WGS84 coordinates encoded in Google Polyline Format, with a decimal precision of 5 digits. For example, the value '_flyHbjPDZBTBNDJ' encodes the following series of (latitude, longitude) coordinates: '' [(51.51344, -0.08882), (51.51341, -0.08896), (51.51339, -0.08907), (51.51337, -0.08915), (51.51334, -0.08921)] '' |
Instructions
|
routes.legs.instructions | array of object |
This provides the list of turn instructions to guide the user through legs where the user needs to navigate, such as when walking or using a scooter or bike. |
Path Index
|
routes.legs.instructions.path_index | integer |
0-based index into the list of coordinates provided by the 'path' property of the leg. This indicates the location at which the instruction is to be followed, so it will be the location of the turn on the path, or the start or end of the leg. |
Distance
|
routes.legs.instructions.distance_meters | integer |
The distance in meters of the section of the 'path' prior to this instruction. This property will be omitted for initial instructions of type 'depart'. |
Time
|
routes.legs.instructions.time_seconds | integer |
The time in seconds that the user is expected to take to traverse the section of the 'path' prior to this instruction. This property will be omitted for initial instructions of type 'depart'. |
Description
|
routes.legs.instructions.description_text | string |
Plain-text description of the Instruction to the user. |
Description Format
|
routes.legs.instructions.description_format | string |
Text format for rendering the Instruction with emphasized elements, where '{key}' indicates a part of the string that must be replaced with content defined by the entry corresponding to 'key' in 'description_format_replacements'. This allows the elements described by the replacements to be formatted differently by the client, if desired. Key strings will contain only the characters '[a-zA-Z0-9]'. '{ }' will not be nested, and the literal characters '{' and '}' are encoded by the escape sequences '{' and '}', respectively. |
description_format_replacements
|
routes.legs.instructions.description_format_replacements | array of object | |
Key
|
routes.legs.instructions.description_format_replacements.key | string |
A key corresponding to a string enclosed in '{}' in 'description_format'. |
Text
|
routes.legs.instructions.description_format_replacements.text | string |
The text to be used to replace the '{key}' substring in the 'description_format'. |
Type
|
routes.legs.instructions.description_format_replacements.type | string |
A value indicating what kind of real-world thing is being identified by this format replacement. This allows service clients to apply application-specific formatting if desired. | value | description | | ----- | ----------- | | street_name | The name of a street, road, or other way | | exit_number | The number of an exit, generally from a roundabout | |
Language
|
routes.legs.instructions.description_format_replacements.language | string |
An IETF BCP 47 language tag that indicates what language the associated 'text' is in. Note that this can be different from the language of the surrounding description - this is most common when the replacement is a place-name in a local language whilst the description is in a different language. |
Type
|
routes.legs.instructions.type | string |
Indicates the type of Instruction. |
Type Direction
|
routes.legs.instructions.type_direction | string |
Indicates a direction that modifies this Instruction. |
Departure Time
|
routes.route_departure_time | string |
The time at which Citymapper thinks the user will set out on this route, given available departure information. This is computed assuming that user is at the start of the route. Updated values for 'route_departure_time' and 'route_arrival_time' are returned by 'service/1/live/routeupdates' to reflect any updated departure information. The time is expressed in ISO 8601 format, including a date, time, and time zone in which the event occurs. For example, '2020-08-19T08:10:42-04:00' expresses August 19, 2020 at 8:10am in Eastern Daylight Time. |
Arrival Time
|
routes.route_arrival_time | string |
The time at which Citymapper thinks the user will arrive at the end of this route, given available departure information and expected travel speed. This is computed assuming that user is at the start of the route. Updated values for 'route_departure_time' and 'route_arrival_time' are returned by 'service/1/live/routeupdates' to reflect any updated departure information. The time is expressed in ISO 8601 format, including a date, time, and time zone in which the event occurs. For example, '2020-08-19T08:10:42-04:00' expresses August 19, 2020 at 8:10am in Eastern Daylight Time. |
groups
|
routes.route_metadata.groups | array of object | |
Group ID
|
routes.route_metadata.groups.group_id | string |
ID of a group a route contains in. |
Group
|
routes.route_metadata.groups.group_name | string |
Localized name of a route group, e.g. 'Transit' or 'Le metro'. |
Route Position
|
routes.route_metadata.groups.route_position | integer |
A zero-based position of a route within specific group. |
Profile Name
|
routes.route_metadata.profile_name | string |
Human-readable localized name of the 'profile' identifier. |
Profile
|
routes.profile | string |
Indicates which routing 'profile' was used to calculate this Route. For example, a response from a bike routing endpoint may return multiple routes, one with a 'quiet' profile and another with a 'fast' profile. Note that new values can be added at any time, so any code parsing this field must be able to handle unexpected values. This value will match the 'profiles' request parameter on endpoints that support selecting specific routing profiles. This value is intended to be machine readable only. For a profile name to show to a user, use the 'profile_name' in the 'route_metadata' object instead. |
Signature
|
routes.signature | string |
A value to be passed back to the server in subsequent calls to refer to this route (for instance, when requesting live departure information via 'service/1/live/routeupdates'). It must be treated as an opaque value. |
Requested Time
|
routes.requested_time | string |
Contains the 'time' parameter used as a departure or arrival time constraint when getting directions, if applicable. |
Requested Time Type
|
routes.requested_time_type | string |
Contains the 'time_type' parameter used to determine how the 'time' will be used to constrain the directions that are returned, if applicable. If no parameter was given in the request, will return the 'time_type' used by default to plan the Route. |
Language
|
language | string |
A IETF BCP 47 language tag that indicates the language used to encode localizable content, such as turning instructions, in this response. This will reflect a best-effort attempt to fulfill any language preference expressed by the 'language' request parameter, or 'en-US' as default. |
Gets a scooter route between two points, providing enough information to render it on a map, along with a duration estimate. (These results are optimized for small battery-powered scooters that the rider stands on.) This call assumes that the rider has a scooter at the 'start' point, and provides an e-scooter route from there to the 'end' point if both are within Citymapper's supported areas. The resulting route should contain a single scooter leg, though the 'path_annotations' property of the leg may indicate sections during which the user should walk beside the scooter. This call does not incorporate any information about scooter operators' coverage or parking areas, but other service calls may be available to do so. Successful responses (HTTP code '200') will consume one 'Scooter Route' credit (or one 'Scooter Reroute' credit if 'reroute_signature' is used) for each HTTP response. Unsuccessful calls will not consume any credits.
Parameters
Name | Key | Required | Type | Description |
---|---|---|---|---|
Start
|
start | True | array |
The geographical start of the route, in WGS84 'latitude,longitude' format. Coordinates should be in decimal, and only the first 6 decimal places will be used. |
End
|
end | True | array |
The geographical end of the route, in WGS84 'latitude,longitude' format. Coordinates should be in decimal, and only the first 6 decimal places will be used. |
Language
|
language | string |
An IETF BCP 47 language tag that indicates the end-user's language preference. When provided, the response will contain a 'language' property that indicates the language used for any localizable elements of the response (such as turning instructions). This language will be a best-effort attempt to fulfill the expressed preference, but it may contain a value that wasn't expressed in the request (this will generally be 'en-US' as a fallback). Note that language preference will generally only affect Citymapper-generated content such as turning instructions. External content such as Stop names and Status descriptions will generally be passed through in their original language. |
|
Reroute Signature
|
reroute_signature | string |
When rerouting (requesting an update to a previous response that accounts for the user's updated location), this value should be set to the 'signature' provided in the original Route. This allows for more efficient determination of the updated Route. This value must be URL-encoded. When providing this parameter, the 'current_location' (when applicable) or 'start' location should be set to the user's latest location. When this parameter is included, Citymapper may not return results in cases where the request differs significantly from the original, for instance if the 'end' location is different, or if more than 1 hour has passed since the original request. |
|
Start Bearing
|
start_bearing | integer |
An angle clockwise from North between 0 and 359, where North is 0 and East is 90. This bearing is used to influence the initial instruction text and/or routing, most-commonly to avoid the user from being asked to make a u-turn, if continuing on their current bearing gives a comparable route. This should be provided only if you wish to influence the initial direction of travel for the route. |
|
Past Locations
|
past_loc_coords | string |
Optional parameter to improve rerouting behavior. The Coordinates of up to 10 of the past locations of the user as a comma separated list. Coordinates must be in WGS84 'latitude,longitude' format. Coordinates must be in decimal, and only the first 6 digits of precision will be used. Must be chronologically ordered, most recent last. 'past_loc_ages' and 'past_loc_accuracies' must be provided alongside. The server will only consider a maximum of 10 locations, if more than 10 locations are provided the least recent locations will be ignored. The server is likely to ignore any locations older than 30 seconds or any that are less than 1 second apart. |
|
Past Location Ages
|
past_loc_ages | string |
Optional parameter to improve rerouting behavior. The Ages of up to 10 of the past locations of the user as a comma separated list. Ages must be in integer seconds since the current location. Must be chronologically ordered, most recent last. 'past_loc_coords' and 'past_loc_accuracies' must be provided alongside. The server will only consider a maximum of 10 locations, if more than 10 locations are provided the least recent locations will be ignored. The server is likely to ignore any locations older than 30 seconds or any that are less than 1 second apart. |
|
Past Location Accuracies
|
past_loc_accuracies | string |
Optional parameter to improve rerouting behavior. The GPS Accuracies of up to 10 of the past locations of the user as a comma separated list. Accuracies must be in integer meters. Must be chronologically ordered, most recent last. 'past_loc_ages' and 'past_loc_coords' must be provided alongside. The server will only consider a maximum of 10 locations, if more than 10 locations are provided the least recent locations will be ignored. The server is likely to ignore any locations older than 30 seconds or any that are less than 1 second apart. |
Returns
Name | Path | Type | Description |
---|---|---|---|
routes
|
routes | array of object | |
Latitude
|
routes.start.coordinates.lat | float |
A latitude in WGS84 encoding, with 6 digits of decimal precision. |
Longitude
|
routes.start.coordinates.lon | float |
A longitude in WGS84 encoding, with 6 digits of decimal precision. |
Latitude
|
routes.end.coordinates.lat | float |
A latitude in WGS84 encoding, with 6 digits of decimal precision. |
Longitude
|
routes.end.coordinates.lon | float |
A longitude in WGS84 encoding, with 6 digits of decimal precision. |
Distance in Meters
|
routes.distance_meters | integer |
The overall distance of the entire Route, in meters. |
Duration
|
routes.duration_seconds | integer |
The overall estimated time to traverse the entire Route, in seconds, based on the selected vehicle or departure in the response. |
Duration Accuracy
|
routes.duration_accuracy | string |
Citymapper's assessment of how the accuracy level of 'duration_seconds' should be displayed to the user. This is largely based on the 'type' of the Departures used for times, but it involves additional heuristics developed over time for the Citymapper app. When this field is not provided, the value 'scheduled' should be used. | value | description | | ----- | ----------- | | estimated | A duration that should be considered approximate, as its calculation involved more uncertainty than usual. This is the lowest accuracy. | | scheduled | A normal duration, typically based on published timetable information. | | live | A duration largely based on real-time/live departure information. This is the highest accuracy. | |
Formatted
|
routes.price.formatted | string |
The given price as a formatted string. By default, this is in the native currency format of the region where the route occurs. |
Amount
|
routes.price.amount | string |
The price as a decimal value, encoded as a string to avoid floating-point accuracy issues. It will not include currency symbols, and the separator between major and minor units will always be '.', regardless of the region. |
Amount Range Minimum
|
routes.price.amount_range_minimum | string |
If this Price represents a range of possible values, the minimum price as a decimal value, encoded as a string to avoid floating-point accuracy issues. It will not include currency symbols, and the separator between major and minor units will always be '.', regardless of the region. |
Amount range Maximum
|
routes.price.amount_range_maximum | string |
If this Price represents a range of possible values, the maximum price as a decimal value, encoded as a string to avoid floating-point accuracy issues. It will not include currency symbols, and the separator between major and minor units will always be '.', regardless of the region. This may not be included if the range is open-ended |
Currency
|
routes.price.currency | string |
The currency in which the price is given, in three-letter ISO 4217 form. |
Demand Multiplier
|
routes.price.demand_multipler | float |
Indicates that prices are higher than usual because of demand, usually for Taxi (On-Demand) legs. May in rare cases be less than 1.0 |
CO2e Emissions
|
routes.emissions_grams_co2e | float |
An estimate of the greenhouse gas emissions of the route, expressed in grams of carbon dioxide equivalent (CO2e). |
Legs
|
routes.legs | array of object |
Array of legs comprising the Route, in the order in which they should be traversed. Every valid route will have at least one. |
Travel Mode
|
routes.legs.travel_mode | string |
The travel mode. |
Duration
|
routes.legs.duration_seconds | integer |
The time required to traverse this leg, excluding any waiting or boarding time at the beginning. May be omitted in rare circumstances when the duration cannot be computed. |
Path
|
routes.legs.path | string |
The geographic path that the leg traverses, as a series of WGS84 coordinates encoded in Google Polyline Format, with a decimal precision of 5 digits. For example, the value '_flyHbjPDZBTBNDJ' encodes the following series of (latitude, longitude) coordinates: '' [(51.51344, -0.08882), (51.51341, -0.08896), (51.51339, -0.08907), (51.51337, -0.08915), (51.51334, -0.08921)] '' |
Instructions
|
routes.legs.instructions | array of object |
This provides the list of turn instructions to guide the user through legs where the user needs to navigate, such as when walking or using a scooter or bike. |
Path Index
|
routes.legs.instructions.path_index | integer |
0-based index into the list of coordinates provided by the 'path' property of the leg. This indicates the location at which the instruction is to be followed, so it will be the location of the turn on the path, or the start or end of the leg. |
Distance
|
routes.legs.instructions.distance_meters | integer |
The distance in meters of the section of the 'path' prior to this instruction. This property will be omitted for initial instructions of type 'depart'. |
Time
|
routes.legs.instructions.time_seconds | integer |
The time in seconds that the user is expected to take to traverse the section of the 'path' prior to this instruction. This property will be omitted for initial instructions of type 'depart'. |
Description
|
routes.legs.instructions.description_text | string |
Plain-text description of the Instruction to the user. |
Description Format
|
routes.legs.instructions.description_format | string |
Text format for rendering the Instruction with emphasized elements, where '{key}' indicates a part of the string that must be replaced with content defined by the entry corresponding to 'key' in 'description_format_replacements'. This allows the elements described by the replacements to be formatted differently by the client, if desired. Key strings will contain only the characters '[a-zA-Z0-9]'. '{ }' will not be nested, and the literal characters '{' and '}' are encoded by the escape sequences '{' and '}', respectively. |
description_format_replacements
|
routes.legs.instructions.description_format_replacements | array of object | |
Key
|
routes.legs.instructions.description_format_replacements.key | string |
A key corresponding to a string enclosed in '{}' in 'description_format'. |
Text
|
routes.legs.instructions.description_format_replacements.text | string |
The text to be used to replace the '{key}' substring in the 'description_format'. |
Type
|
routes.legs.instructions.description_format_replacements.type | string |
A value indicating what kind of real-world thing is being identified by this format replacement. This allows service clients to apply application-specific formatting if desired. | value | description | | ----- | ----------- | | street_name | The name of a street, road, or other way | | exit_number | The number of an exit, generally from a roundabout | |
Language
|
routes.legs.instructions.description_format_replacements.language | string |
An IETF BCP 47 language tag that indicates what language the associated 'text' is in. Note that this can be different from the language of the surrounding description - this is most common when the replacement is a place-name in a local language whilst the description is in a different language. |
Type
|
routes.legs.instructions.type | string |
Indicates the type of Instruction. |
Type Direction
|
routes.legs.instructions.type_direction | string |
Indicates a direction that modifies this Instruction. |
Departure Time
|
routes.route_departure_time | string |
The time at which Citymapper thinks the user will set out on this route, given available departure information. This is computed assuming that user is at the start of the route. Updated values for 'route_departure_time' and 'route_arrival_time' are returned by 'service/1/live/routeupdates' to reflect any updated departure information. The time is expressed in ISO 8601 format, including a date, time, and time zone in which the event occurs. For example, '2020-08-19T08:10:42-04:00' expresses August 19, 2020 at 8:10am in Eastern Daylight Time. |
Arrival Time
|
routes.route_arrival_time | string |
The time at which Citymapper thinks the user will arrive at the end of this route, given available departure information and expected travel speed. This is computed assuming that user is at the start of the route. Updated values for 'route_departure_time' and 'route_arrival_time' are returned by 'service/1/live/routeupdates' to reflect any updated departure information. The time is expressed in ISO 8601 format, including a date, time, and time zone in which the event occurs. For example, '2020-08-19T08:10:42-04:00' expresses August 19, 2020 at 8:10am in Eastern Daylight Time. |
groups
|
routes.route_metadata.groups | array of object | |
Group ID
|
routes.route_metadata.groups.group_id | string |
ID of a group a route contains in. |
Group
|
routes.route_metadata.groups.group_name | string |
Localized name of a route group, e.g. 'Transit' or 'Le metro'. |
Route Position
|
routes.route_metadata.groups.route_position | integer |
A zero-based position of a route within specific group. |
Profile Name
|
routes.route_metadata.profile_name | string |
Human-readable localized name of the 'profile' identifier. |
Profile
|
routes.profile | string |
Indicates which routing 'profile' was used to calculate this Route. For example, a response from a bike routing endpoint may return multiple routes, one with a 'quiet' profile and another with a 'fast' profile. Note that new values can be added at any time, so any code parsing this field must be able to handle unexpected values. This value will match the 'profiles' request parameter on endpoints that support selecting specific routing profiles. This value is intended to be machine readable only. For a profile name to show to a user, use the 'profile_name' in the 'route_metadata' object instead. |
Signature
|
routes.signature | string |
A value to be passed back to the server in subsequent calls to refer to this route (for instance, when requesting live departure information via 'service/1/live/routeupdates'). It must be treated as an opaque value. |
Requested Time
|
routes.requested_time | string |
Contains the 'time' parameter used as a departure or arrival time constraint when getting directions, if applicable. |
Requested Time Type
|
routes.requested_time_type | string |
Contains the 'time_type' parameter used to determine how the 'time' will be used to constrain the directions that are returned, if applicable. If no parameter was given in the request, will return the 'time_type' used by default to plan the Route. |
Language
|
language | string |
A IETF BCP 47 language tag that indicates the language used to encode localizable content, such as turning instructions, in this response. This will reflect a best-effort attempt to fulfill any language preference expressed by the 'language' request parameter, or 'en-US' as default. |
Gets a hired e-scooter route between two points, including any initial and final walks. The resulting route provides enough information to render it on a map, along with a duration estimate. These results are optimized for small battery-powered scooters that the rider stands on. This call can be used in several different ways: Use any scooter of the specified Brand This is the simplest call, only requiring 'start', 'end', and 'brand_id'. Citymapper assumes that the user is at the 'start' point, and chooses a scooter of the specified Brand, if possible. Use a scooter at a specified location By adding 'original_vehicle_location' to 'start', 'end', and 'brand_id', Citymapper plans a route that assumes the scooter is at the given location. Update a route in progress In order to retrieve an updated route that includes rerouting from the user's current location if they've diverged from the planned Route, the caller can add the 'current_location' and 'ride_state' properties, which indicates which leg of the resulting route should be rerouted around the user's 'current_location'.
Parameters
Name | Key | Required | Type | Description |
---|---|---|---|---|
Start
|
start | True | array |
The geographical start of the route, in WGS84 'latitude,longitude' format. Coordinates should be in decimal, and only the first 6 decimal places will be used. |
End
|
end | True | array |
The geographical end of the route, in WGS84 'latitude,longitude' format. Coordinates should be in decimal, and only the first 6 decimal places will be used. |
Brand ID
|
brand_id | True | string |
The ID of the Brand of e-scooters to use for this route. This is necessary in order to determine the location of available scooters, along with any associated coverage and parking restrictions. |
State
|
ride_state | string |
Indicates where along the route the user is. If omitted, 'walking_to_vehicle' is used. This property along with 'current_location' allows the retrieval of an updated route that reflects the user's current progress through it. | value | description | | ----- | ----------- | | walking_to_vehicle | Indicates that the user is walking to collect the vehicle | | riding | Indicates that the user is riding the vehicle | | walking_to_end | Indicates that the user has left the vehicle and is walking to their destination | |
|
Current Location
|
current_location | string |
The user's current location, in order to update the route based on the user's location. Provided in WGS84 'latitude,longitude' format. Coordinates should be in decimal, and only the first 6 digits of precision will be used. This parameter is used to get an updated route that reflects the user's actual location if they diverge from the path given in the Route. If this is provided, the returned route will contain this location. Which leg of the route will contain this location is decided by the value of the 'ride_state' parameter. |
|
Start Location
|
ride_start_location | string |
The location of the vehicle to be used, at the beginning of the vehicle ride part of the user's trip along the Route. Provided in WGS84 'latitude,longitude' format. Coordinates should be in decimal, and only the first 6 digits of precision will be used. This must be provided when 'ride_state' is 'riding' or 'walking_to_end'. If not provided when 'ride_state' is 'walking_to_vehicle' (or not specified), Citymapper will attempt to find the most appropriate vehicle that belongs to the specified 'brand_id'. For compatibility, 'original_vehicle_location' is an alias for this parameter |
|
End Location
|
ride_end_location | string |
The location the vehicle was dropped off at the end of the vehicle ride part of the user's trip along the Route. Provided in WGS84 'latitude,longitude' format. Coordinates should be in decimal, and only the first 6 digits of precision will be used. This must be provided when 'ride_state' is 'walking_to_end'. In all other states this parameter is ignored. |
|
Language
|
language | string |
An IETF BCP 47 language tag that indicates the end-user's language preference. When provided, the response will contain a 'language' property that indicates the language used for any localizable elements of the response (such as turning instructions). This language will be a best-effort attempt to fulfill the expressed preference, but it may contain a value that wasn't expressed in the request (this will generally be 'en-US' as a fallback). Note that language preference will generally only affect Citymapper-generated content such as turning instructions. External content such as Stop names and Status descriptions will generally be passed through in their original language. |
|
Reroute Signature
|
reroute_signature | string |
When rerouting (requesting an update to a previous response that accounts for the user's updated location), this value should be set to the 'signature' provided in the original Route. This allows for more efficient determination of the updated Route. This value must be URL-encoded. When providing this parameter, the 'current_location' (when applicable) or 'start' location should be set to the user's latest location. When this parameter is included, Citymapper may not return results in cases where the request differs significantly from the original, for instance if the 'end' location is different, or if more than 1 hour has passed since the original request. |
|
Start Bearing
|
start_bearing | integer |
An angle clockwise from North between 0 and 359, where North is 0 and East is 90. This bearing is used to influence the initial instruction text and/or routing, most-commonly to avoid the user from being asked to make a u-turn, if continuing on their current bearing gives a comparable route. This should be provided only if you wish to influence the initial direction of travel for the route. |
|
Past Locations
|
past_loc_coords | string |
Optional parameter to improve rerouting behavior. The Coordinates of up to 10 of the past locations of the user as a comma separated list. Coordinates must be in WGS84 'latitude,longitude' format. Coordinates must be in decimal, and only the first 6 digits of precision will be used. Must be chronologically ordered, most recent last. 'past_loc_ages' and 'past_loc_accuracies' must be provided alongside. The server will only consider a maximum of 10 locations, if more than 10 locations are provided the least recent locations will be ignored. The server is likely to ignore any locations older than 30 seconds or any that are less than 1 second apart. |
|
Past Location Ages
|
past_loc_ages | string |
Optional parameter to improve rerouting behavior. The Ages of up to 10 of the past locations of the user as a comma separated list. Ages must be in integer seconds since the current location. Must be chronologically ordered, most recent last. 'past_loc_coords' and 'past_loc_accuracies' must be provided alongside. The server will only consider a maximum of 10 locations, if more than 10 locations are provided the least recent locations will be ignored. The server is likely to ignore any locations older than 30 seconds or any that are less than 1 second apart. |
|
Past Location Accuracies
|
past_loc_accuracies | string |
Optional parameter to improve rerouting behavior. The GPS Accuracies of up to 10 of the past locations of the user as a comma separated list. Accuracies must be in integer meters. Must be chronologically ordered, most recent last. 'past_loc_ages' and 'past_loc_coords' must be provided alongside. The server will only consider a maximum of 10 locations, if more than 10 locations are provided the least recent locations will be ignored. The server is likely to ignore any locations older than 30 seconds or any that are less than 1 second apart. |
Returns
Name | Path | Type | Description |
---|---|---|---|
routes
|
routes | array of object | |
Latitude
|
routes.start.coordinates.lat | float |
A latitude in WGS84 encoding, with 6 digits of decimal precision. |
Longitude
|
routes.start.coordinates.lon | float |
A longitude in WGS84 encoding, with 6 digits of decimal precision. |
Latitude
|
routes.end.coordinates.lat | float |
A latitude in WGS84 encoding, with 6 digits of decimal precision. |
Longitude
|
routes.end.coordinates.lon | float |
A longitude in WGS84 encoding, with 6 digits of decimal precision. |
Distance in Meters
|
routes.distance_meters | integer |
The overall distance of the entire Route, in meters. |
Duration
|
routes.duration_seconds | integer |
The overall estimated time to traverse the entire Route, in seconds, based on the selected vehicle or departure in the response. |
Duration Accuracy
|
routes.duration_accuracy | string |
Citymapper's assessment of how the accuracy level of 'duration_seconds' should be displayed to the user. This is largely based on the 'type' of the Departures used for times, but it involves additional heuristics developed over time for the Citymapper app. When this field is not provided, the value 'scheduled' should be used. | value | description | | ----- | ----------- | | estimated | A duration that should be considered approximate, as its calculation involved more uncertainty than usual. This is the lowest accuracy. | | scheduled | A normal duration, typically based on published timetable information. | | live | A duration largely based on real-time/live departure information. This is the highest accuracy. | |
Formatted
|
routes.price.formatted | string |
The given price as a formatted string. By default, this is in the native currency format of the region where the route occurs. |
Amount
|
routes.price.amount | string |
The price as a decimal value, encoded as a string to avoid floating-point accuracy issues. It will not include currency symbols, and the separator between major and minor units will always be '.', regardless of the region. |
Amount Range Minimum
|
routes.price.amount_range_minimum | string |
If this Price represents a range of possible values, the minimum price as a decimal value, encoded as a string to avoid floating-point accuracy issues. It will not include currency symbols, and the separator between major and minor units will always be '.', regardless of the region. |
Amount range Maximum
|
routes.price.amount_range_maximum | string |
If this Price represents a range of possible values, the maximum price as a decimal value, encoded as a string to avoid floating-point accuracy issues. It will not include currency symbols, and the separator between major and minor units will always be '.', regardless of the region. This may not be included if the range is open-ended |
Currency
|
routes.price.currency | string |
The currency in which the price is given, in three-letter ISO 4217 form. |
Demand Multiplier
|
routes.price.demand_multipler | float |
Indicates that prices are higher than usual because of demand, usually for Taxi (On-Demand) legs. May in rare cases be less than 1.0 |
CO2e Emissions
|
routes.emissions_grams_co2e | float |
An estimate of the greenhouse gas emissions of the route, expressed in grams of carbon dioxide equivalent (CO2e). |
Legs
|
routes.legs | array of object |
Array of legs comprising the Route, in the order in which they should be traversed. Every valid route will have at least one. |
Travel Mode
|
routes.legs.travel_mode | string |
The travel mode. |
Duration
|
routes.legs.duration_seconds | integer |
The time required to traverse this leg, excluding any waiting or boarding time at the beginning. May be omitted in rare circumstances when the duration cannot be computed. |
Path
|
routes.legs.path | string |
The geographic path that the leg traverses, as a series of WGS84 coordinates encoded in Google Polyline Format, with a decimal precision of 5 digits. For example, the value '_flyHbjPDZBTBNDJ' encodes the following series of (latitude, longitude) coordinates: '' [(51.51344, -0.08882), (51.51341, -0.08896), (51.51339, -0.08907), (51.51337, -0.08915), (51.51334, -0.08921)] '' |
Instructions
|
routes.legs.instructions | array of object |
This provides the list of turn instructions to guide the user through legs where the user needs to navigate, such as when walking or using a scooter or bike. |
Path Index
|
routes.legs.instructions.path_index | integer |
0-based index into the list of coordinates provided by the 'path' property of the leg. This indicates the location at which the instruction is to be followed, so it will be the location of the turn on the path, or the start or end of the leg. |
Distance
|
routes.legs.instructions.distance_meters | integer |
The distance in meters of the section of the 'path' prior to this instruction. This property will be omitted for initial instructions of type 'depart'. |
Time
|
routes.legs.instructions.time_seconds | integer |
The time in seconds that the user is expected to take to traverse the section of the 'path' prior to this instruction. This property will be omitted for initial instructions of type 'depart'. |
Description
|
routes.legs.instructions.description_text | string |
Plain-text description of the Instruction to the user. |
Description Format
|
routes.legs.instructions.description_format | string |
Text format for rendering the Instruction with emphasized elements, where '{key}' indicates a part of the string that must be replaced with content defined by the entry corresponding to 'key' in 'description_format_replacements'. This allows the elements described by the replacements to be formatted differently by the client, if desired. Key strings will contain only the characters '[a-zA-Z0-9]'. '{ }' will not be nested, and the literal characters '{' and '}' are encoded by the escape sequences '{' and '}', respectively. |
description_format_replacements
|
routes.legs.instructions.description_format_replacements | array of object | |
Key
|
routes.legs.instructions.description_format_replacements.key | string |
A key corresponding to a string enclosed in '{}' in 'description_format'. |
Text
|
routes.legs.instructions.description_format_replacements.text | string |
The text to be used to replace the '{key}' substring in the 'description_format'. |
Type
|
routes.legs.instructions.description_format_replacements.type | string |
A value indicating what kind of real-world thing is being identified by this format replacement. This allows service clients to apply application-specific formatting if desired. | value | description | | ----- | ----------- | | street_name | The name of a street, road, or other way | | exit_number | The number of an exit, generally from a roundabout | |
Language
|
routes.legs.instructions.description_format_replacements.language | string |
An IETF BCP 47 language tag that indicates what language the associated 'text' is in. Note that this can be different from the language of the surrounding description - this is most common when the replacement is a place-name in a local language whilst the description is in a different language. |
Type
|
routes.legs.instructions.type | string |
Indicates the type of Instruction. |
Type Direction
|
routes.legs.instructions.type_direction | string |
Indicates a direction that modifies this Instruction. |
Departure Time
|
routes.route_departure_time | string |
The time at which Citymapper thinks the user will set out on this route, given available departure information. This is computed assuming that user is at the start of the route. Updated values for 'route_departure_time' and 'route_arrival_time' are returned by 'service/1/live/routeupdates' to reflect any updated departure information. The time is expressed in ISO 8601 format, including a date, time, and time zone in which the event occurs. For example, '2020-08-19T08:10:42-04:00' expresses August 19, 2020 at 8:10am in Eastern Daylight Time. |
Arrival Time
|
routes.route_arrival_time | string |
The time at which Citymapper thinks the user will arrive at the end of this route, given available departure information and expected travel speed. This is computed assuming that user is at the start of the route. Updated values for 'route_departure_time' and 'route_arrival_time' are returned by 'service/1/live/routeupdates' to reflect any updated departure information. The time is expressed in ISO 8601 format, including a date, time, and time zone in which the event occurs. For example, '2020-08-19T08:10:42-04:00' expresses August 19, 2020 at 8:10am in Eastern Daylight Time. |
groups
|
routes.route_metadata.groups | array of object | |
Group ID
|
routes.route_metadata.groups.group_id | string |
ID of a group a route contains in. |
Group
|
routes.route_metadata.groups.group_name | string |
Localized name of a route group, e.g. 'Transit' or 'Le metro'. |
Route Position
|
routes.route_metadata.groups.route_position | integer |
A zero-based position of a route within specific group. |
Profile Name
|
routes.route_metadata.profile_name | string |
Human-readable localized name of the 'profile' identifier. |
Profile
|
routes.profile | string |
Indicates which routing 'profile' was used to calculate this Route. For example, a response from a bike routing endpoint may return multiple routes, one with a 'quiet' profile and another with a 'fast' profile. Note that new values can be added at any time, so any code parsing this field must be able to handle unexpected values. This value will match the 'profiles' request parameter on endpoints that support selecting specific routing profiles. This value is intended to be machine readable only. For a profile name to show to a user, use the 'profile_name' in the 'route_metadata' object instead. |
Signature
|
routes.signature | string |
A value to be passed back to the server in subsequent calls to refer to this route (for instance, when requesting live departure information via 'service/1/live/routeupdates'). It must be treated as an opaque value. |
Requested Time
|
routes.requested_time | string |
Contains the 'time' parameter used as a departure or arrival time constraint when getting directions, if applicable. |
Requested Time Type
|
routes.requested_time_type | string |
Contains the 'time_type' parameter used to determine how the 'time' will be used to constrain the directions that are returned, if applicable. If no parameter was given in the request, will return the 'time_type' used by default to plan the Route. |
Language
|
language | string |
A IETF BCP 47 language tag that indicates the language used to encode localizable content, such as turning instructions, in this response. This will reflect a best-effort attempt to fulfill any language preference expressed by the 'language' request parameter, or 'en-US' as default. |
This retrieves current and live departure information and live on-demand quotes for multiple routes previously obtained from the 'directions' endpoints. Only routes that have at least one leg with a leg Updatable Detail can be updated using this service. Note it may not always be possible for Citymapper to provide current times or live departure and disruption information for a leg. Successful responses (HTTP code '200') will consume one 'Live Update' credit for each HTTP response. Unsuccessful calls will not consume any credits.
Parameters
Name | Key | Required | Type | Description |
---|---|---|---|---|
Signatures
|
signatures | True | array of string |
An array of 'signature' properties from previously-obtained routes |
Fetch On-Demand Services
|
fetch_on_demand_services | boolean |
When updating using one or more Signatures from routes containing on-demand legs with updatable details (e.g. from the Taxi Directions service), if this is set to 'true', additional information will be requested from Taxi service intrgrations to provide more accurate and complete pricing, duration and service availability. To provide this, the original Route's start and end locations need to be transmitted to these Third-Party services, including in the case that one or the other is the user's current or recent location. Be aware that you may need to have explicit informed consent from your end-user to set this to 'true' depending on applicable laws and regulations. If set to 'false' or omitted, no requests will be made to any Third-Party services. If no update can be produced for a leg without this parameter being set 'true', the response will indicate this within the updateable detail. |
Returns
Name | Path | Type | Description |
---|---|---|---|
route_updates
|
route_updates | array of object | |
Leg Updates
|
route_updates.leg_updates | array of |
This is an parallel array of leg Updatable Detail objects, one for every leg in the original route being updated. The ones corresponding to walking legs will be empty, but the details corresponding to transit legs will contain updated departure information. |
Departure Time
|
route_updates.route_departure_time | string |
The time at which Citymapper thinks the user will set out on this route, given available departure information. This is computed assuming that user is at the start of the route at the time of the request. The time is expressed in ISO 8601 format, including a date, time, and time zone in which the event occurs. For example, '2020-08-19T08:10:42-04:00' expresses August 19, 2020 at 8:10am in Eastern Daylight Time. |
Arrival Time
|
route_updates.route_arrival_time | string |
The time at which Citymapper thinks the user will arrive at the end of this route, given available departure information and expected travel speed. This is computed assuming that user is at the start of the route at the time of the request. The time is expressed in ISO 8601 format, including a date, time, and time zone in which the event occurs. For example, '2020-08-19T08:10:42-04:00' expresses August 19, 2020 at 8:10am in Eastern Daylight Time. |
Duration
|
route_updates.route_duration_seconds | integer |
The overall estimated time to traverse the entire route, in seconds. This value replaces the 'duration_seconds' value from the original Route, as it will be recomputed to use the specific departure information contained in this route update response. May be omitted in rare circumstances when the duration cannot be computed, for instance if the route can't be completed at the given time because the Services involved are not running. |
DurationAccuracy
|
route_updates.route_duration_accuracy | string |
Citymapper's assessment of how the accuracy level of 'duration_seconds' should be displayed to the user. This is largely based on the 'type' of the Departures used for times, but it involves additional heuristics developed over time for the Citymapper app. When this field is not provided, the value 'scheduled' should be used. | value | description | | ----- | ----------- | | estimated | A duration that should be considered approximate, as its calculation involved more uncertainty than usual. This is the lowest accuracy. | | scheduled | A normal duration, typically based on published timetable information. | | live | A duration largely based on real-time/live departure information. This is the highest accuracy. | |
Request Signature
|
route_updates.request_signature | string |
This is a route 'signature' from the update request, which should be used to associate this update with the correct Route. |
Determines the travel time in various modes of travel between the given two points at the time the request is made.
Parameters
Name | Key | Required | Type | Description |
---|---|---|---|---|
Start
|
start | True | string |
The geographical start point of the trip, in WGS84 'latitude,longitude' format. Coordinates should be in decimal, and only the first 6 digits of precision will be used. |
End
|
end | True | string |
The geographical end point of the trip, in WGS84 'latitude,longitude' format. Coordinates should be in decimal, and only the first 6 digits of precision will be used. |
Travel Types
|
traveltime_types | array |
A comma-separated list of different travel time types to attempt to request. Each request value corresponds to a particular field in the response (response fields will only be present when Citymapper was able to calculate a time for that travel time type). | value | response property | description | | ----- | ----------------- | ------------| | walk | walk_travel_time_minutes | Walking | | transit | transit_time_minutes | Public transit travel | | bike | bike_time_minutes | Bicycle travel (riding the entire way) | | scooter | scooter_time_minutes | Standing e-scooter travel (riding the entire way) | | motorscooter | motorscooter_time_minutes | Seated motor scooter travel (riding the entire way) | | car | car_time_minutes | Car travel (riding the entire way). Available on Enterprise plans only | When this field is omitted or empty, a default value of 'walk,transit' will be used. |
Returns
Name | Path | Type | Description |
---|---|---|---|
Walk Time
|
walk_travel_time_minutes | integer |
Estimated walking time between the two given points in minutes. |
Transit Time
|
transit_time_minutes | integer |
Estimated public transit travel time between the two given points in minutes. |
Bike Time
|
bike_time_minutes | integer |
Estimated bicycle travel time between two points in minutes. |
Scooter Time
|
scooter_time_minutes | integer |
Estimated e-scooter travel time between two points in minutes. |
Motorscooter Time
|
motorscooter_time_minutes | integer |
Estimated motor scooter travel time between two points in minutes. |
Drive Time
|
car_time_minutes | integer |
Estimated car travel time between two points in minutes. |