Compartir a través de


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

Creating a connection

The connector supports the following authentication types:

Default Parameters for creating connection. All regions Not shareable

Default

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

Throttling Limits

Name Calls Renewal Period
API calls per connection 100 60 seconds

Actions

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.

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.

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.

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.

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.

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

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.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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.