Citymapper API (v1.8.3)

Download OpenAPI specification:Download

Introduction

Our APIs are powered by our industry-leading global transport data and custom routing algorithms trained on billions of trips.

With our journey planning APIs you can:

Calculate public transport routes and travel times
Retrieve live departure information for public transport routes
Calculate walk, cycling, e-scooter and motor scooter routes and travel times, including turn-by-turn instructions

Developing a mobile app? See our iOS and Android SDK here.

Other resources

SDK Docs

Deep Links

Learn more about Powered by Citymapper

Support

Have questions?

Check out our FAQ here.

Have product feedback or suggestions?

We'd love to hear about your experiences using our APIs, and features you'd like to see next. Please contribute feedback here, and keep an eye out for future product releases.

Have a sales question?

If you are an enterprise user, or require functionality not available in our public APIs, our sales team are here to help.

Please contact us with a description of your project or business need and we'll be in touch.

Pricing

See below for our API pricing:

Travel Time API	Unit	Price per Unit
Walk Travel Time	per 1000 results	£0.40
Cycle Travel Time	per 1000 results	£0.80
E-Scooter Travel Time	per 1000 results	£0.80
Motor Scooter Travel Time	per 1000 results	£0.80
Car Travel Time	per 1000 results	£0.80
Transit Travel Time	per 1000 results	£1.00

Directions API	Unit	Price per Unit
Walk Directions: Fast Profile	per 1000 results	£0.50
Walk Directions: Main Roads Profile	per 1000 results	£0.50
Cycle Directions: Quiet Profile	per 1000 results	£1.00
Cycle Directions: Regular Profile	per 1000 results	£1.00
Cycle Directions: Fast Profile	per 1000 results	£1.00
E-Scooter Directions	per 1000 results	£1.00
Motor Scooter Directions	per 1000 results	£1.00
Car Directions	per 1000 results	£1.00
Taxi Directions	per 1000 routes¹	Available on Enterprise plans only
Taxi Directions: Real-Time Updates	per 1000 route updates¹	Available on Enterprise plans only
Transit Directions	per 1000 routes²	£1.20
Transit Directions: Real-Time Updates	per 1000 route updates³	Available on Enterprise plans only
Hire Vehicle Directions	per 1000 results	Available on Enterprise plans only

¹ : Taxi routes and route updates require additional configuration for your access to third-party Taxi provider's APIs.

² : Up to 5 transit routes can be returned in a single result.

³ : One update applies to a single transit route.

Enterprise plans to help you grow

Looking for additional features or have higher volume requirements? Please contact our sales team.

Terms of service

Read the full terms of service.

Requests

A request is defined as a single call which successfully returns a travel time, directions or navigation result. Monthly requests are aggregated across all Powered by Citymapper products. If you're not on a paid plan, you’ll be notified via email once you exceed the free usage allowance in a given month (the month-long period aligns with the calendar month). Further requests will no longer return results for the remainder of that month, and your free usage allowance will reset at the start of the next month.

Authentication

API Key

An API key can be obtained from the Powered by Citymapper website. This key must be provided with all requests in the Citymapper-Partner-Key HTTP header.

Security Scheme Type	API Key
Header parameter name:	Citymapper-Partner-Key

Directions API Calls

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. If the call returns code 200, at least one of the *_time_minutes fields will be populated. Otherwise, a code 400 response will be returned.

A request outside of the API coverage areas will be signaled with a code 400 response containing an error_code value of coverage-start or coverage-end. These failures are fast/resource-efficient and are not billed, so there's no need to pre-filter potential requests by location.

Successful responses (HTTP code 200) will consume one "Travel Time" credit for each time returned. Unsuccessful calls will not consume any credits.

Authorizations:

API Key

query Parameters

start

required

string

Example: start=51.525246,0.084672

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

required

string

Example: end=51.559098,0.074503

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.

traveltime_types

Array of strings

Items Enum: "walk" "transit" "bike" "scooter" "motorscooter" "car"

Example: traveltime_types=bike,transit

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.

Responses

Response samples

200
400
401
429

Content type

application/json

Example

{"walk_travel_time_minutes": 66,
"transit_time_minutes": 49
}

E-scooter directions between two points (ride only)

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

Authorizations:

API Key

query Parameters

start required	Array of numbers <double> 2 items Example: start=51.524247,-0.10641 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 required	Array of numbers <double> 2 items Example: end=51.507752,-0.110081 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	string Example: language=zh-Hans 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	string Example: reroute_signature=v1.eJxtkM1OwzAQhN9lrzjp%2Bi9O%2FARwgQNIH... 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	integer Example: start_bearing=37 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_loc_coords	string Example: past_loc_coords=51.542001,-0.061864,51.542114,-0.06191,51.542244,-0.061938,51.542365,-0.062009,51.542478,-0.062036,51.542609,-0.062091,51.542713,-0.06214,51.542805,-0.062168,51.542903,-0.062283,51.543006,-0.062424 Optional parameter to improve rerouting behaviour. 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_loc_ages	string Example: past_loc_ages=27,24,21,18,15,12,9,6,3,0 Optional parameter to improve rerouting behaviour. 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_loc_accuracies	string Example: past_loc_accuracies=5,5,5,5,5,5,5,17,5,20 Optional parameter to improve rerouting behaviour. 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.

Responses

Response samples

200
400
401
429

Content type

application/json

{"routes": [{"start": {"coordinates": {"lat": 51.524387,
"lon": -0.106324
}
},
"end": {"coordinates": {"lat": 51.50758,
"lon": -0.107744
}
},
"duration_seconds": 797,
"legs": [{"travel_mode": "self_piloted",
"vehicle_types": ["escooter"
],
"duration_seconds": 797,
"path": "_flyHbjPDZBTBNDJ",
"path_annotations": [{"start_index": 1,
"end_index": 3,
"should_walk": true
}
]
}
]
}
]
}

E-scooter directions between two points (hire vehicles)

NOTE this API is not available through open access, please contact sales. Please contact Citymapper using the details provided at the top of the page for information on integrating and using this API.

Gets an 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.

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.

Authorizations:

API Key

query Parameters

start

required

Array of numbers <double> 2 items

Example: start=51.524247,-0.10641

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

required

Array of numbers <double> 2 items

Example: end=51.507752,-0.110081

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

required

string

Example: brand_id=ScooterBrand

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.

ride_state

string

Enum: "walking_to_vehicle" "riding" "walking_to_end"

Example: ride_state=walking_to_vehicle

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

string

Example: current_location=51.524247,-0.106410

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.

ride_start_location

string

Example: ride_start_location=51.524247,-0.106410

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

ride_end_location

string

Example: ride_end_location=51.524247,-0.106410

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

string

Example: language=zh-Hans

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

string

Example: reroute_signature=v1.eJxtkM1OwzAQhN9lrzjp%2Bi9O%2FARwgQNIH...

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

integer

Example: start_bearing=37

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_loc_coords

string

Example: past_loc_coords=51.542001,-0.061864,51.542114,-0.06191,51.542244,-0.061938,51.542365,-0.062009,51.542478,-0.062036,51.542609,-0.062091,51.542713,-0.06214,51.542805,-0.062168,51.542903,-0.062283,51.543006,-0.062424

Optional parameter to improve rerouting behaviour. 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_loc_ages

string

Example: past_loc_ages=27,24,21,18,15,12,9,6,3,0

Optional parameter to improve rerouting behaviour. 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_loc_accuracies

string

Example: past_loc_accuracies=5,5,5,5,5,5,5,17,5,20

Optional parameter to improve rerouting behaviour. 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.

Responses

Response samples

200
400
401
429

Content type

application/json

{"routes": [{"start": {"coordinates": {"lat": 51.524387,
"lon": -0.106324
}
},
"end": {"coordinates": {"lat": 51.50758,
"lon": -0.107744
}
},
"duration_seconds": 797,
"legs": [{"travel_mode": "walk",
"duration_seconds": 211,
"path": "_flyHbjPDZBTBNDJ"
},
{"travel_mode": "self_piloted",
"vehicle_types": ["escooter"
],
"duration_seconds": 586,
"services": {"id": "ScooterBrand",
"name": "Scooter Brand",
"vehicle_types": ["escooter"
],
"brand": {"id": "ScooterBrand",
"name": "Scooter Brand",
"image_key": "scooter-brand"
},
"color": "#000000",
"text_color": "#FFFFFF"
},
"path": "_flyHbjPDZBTBNDJ"
}
]
}
]
}

Bike directions between two points (ride only)

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 API calls may be available to do so.

The maximum great-circle distance between the start and end is limited to 200km for this API.

Successful responses (HTTP code 200) will consume one "Bike Route" credit (or one "Bike Reroute" credit if reroute_signature is used) for each HTTP response. Unsuccessful calls will not consume any credits.

Authorizations:

API Key

query Parameters

start

required

Array of numbers <double> 2 items

Example: start=51.524247,-0.10641

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

required

Array of numbers <double> 2 items

Example: end=51.507752,-0.110081

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

string

Example: profiles=quiet,regular,fast

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

string

Example: language=zh-Hans

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

string

Example: reroute_signature=v1.eJxtkM1OwzAQhN9lrzjp%2Bi9O%2FARwgQNIH...

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

integer

Example: start_bearing=37

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_loc_coords

string

Example: past_loc_coords=51.542001,-0.061864,51.542114,-0.06191,51.542244,-0.061938,51.542365,-0.062009,51.542478,-0.062036,51.542609,-0.062091,51.542713,-0.06214,51.542805,-0.062168,51.542903,-0.062283,51.543006,-0.062424

Optional parameter to improve rerouting behaviour. 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_loc_ages

string

Example: past_loc_ages=27,24,21,18,15,12,9,6,3,0

Optional parameter to improve rerouting behaviour. 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_loc_accuracies

string

Example: past_loc_accuracies=5,5,5,5,5,5,5,17,5,20

Optional parameter to improve rerouting behaviour. 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.

Responses

Response samples

200
400
401
429

Content type

application/json

{"routes": [{"start": {"coordinates": {"lat": 51.524387,
"lon": -0.106324
}
},
"end": {"coordinates": {"lat": 51.50758,
"lon": -0.107744
}
},
"duration_seconds": 797,
"legs": [{"travel_mode": "self_piloted",
"vehicle_types": ["bike"
],
"duration_seconds": 797,
"path": "_flyHbjPDZBTBNDJ",
"path_annotations": [{"start_index": 1,
"end_index": 3,
"should_walk": true
}
]
}
]
}
]
}

Bike directions between two points (hire vehicles)

NOTE this API is not available through open access, please contact sales. Please contact Citymapper using the details provided at the top of the page for information on integrating and using this API.

Gets an 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.

Successful responses (HTTP code 200) will consume one "Bike Route" credit (or one "Bike Reroute" credit if reroute_signature is used) for each HTTP response. Unsuccessful calls will not consume any credits.

Authorizations:

API Key

query Parameters

start

required

Array of numbers <double> 2 items

Example: start=51.524247,-0.10641

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

required

Array of numbers <double> 2 items

Example: end=51.507752,-0.110081

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

required

string

Example: brand_id=BikeBrand

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.

ride_state

string

Enum: "walking_to_vehicle" "riding" "walking_to_end"

Example: ride_state=walking_to_vehicle

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

string

Example: current_location=51.524247,-0.106410

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.

ride_start_location

string

Example: ride_start_location=51.524247,-0.106410

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

ride_end_location

string

Example: ride_end_location=51.524247,-0.106410

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

string

Example: profiles=quiet,regular,fast

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

string

Example: language=zh-Hans

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

string

Example: reroute_signature=v1.eJxtkM1OwzAQhN9lrzjp%2Bi9O%2FARwgQNIH...

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

integer

Example: start_bearing=37

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_loc_coords

string

Example: past_loc_coords=51.542001,-0.061864,51.542114,-0.06191,51.542244,-0.061938,51.542365,-0.062009,51.542478,-0.062036,51.542609,-0.062091,51.542713,-0.06214,51.542805,-0.062168,51.542903,-0.062283,51.543006,-0.062424

Optional parameter to improve rerouting behaviour. 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_loc_ages

string

Example: past_loc_ages=27,24,21,18,15,12,9,6,3,0

Optional parameter to improve rerouting behaviour. 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_loc_accuracies

string

Example: past_loc_accuracies=5,5,5,5,5,5,5,17,5,20

Optional parameter to improve rerouting behaviour. 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.

Responses

Response samples

200
400
401
429

Content type

application/json

{"routes": [{"start": {"coordinates": {"lat": 51.524387,
"lon": -0.106324
}
},
"end": {"coordinates": {"lat": 51.50758,
"lon": -0.107744
}
},
"duration_seconds": 797,
"legs": [{"travel_mode": "walk",
"duration_seconds": 211,
"path": "_flyHbjPDZBTBNDJ"
},
{"travel_mode": "self_piloted",
"vehicle_types": ["bike"
],
"duration_seconds": 586,
"services": {"id": "BikeBrand",
"name": "Bike Brand",
"vehicle_types": ["bike"
],
"brand": {"id": "BikeBrand",
"name": "Bike Brand",
"image_key": "bike-brand"
},
"color": "#000000",
"text_color": "#FFFFFF"
},
"path": "_flyHbjPDZBTBNDJ"
}
]
}
]
}

Motor scooter directions between two points (ride only)

Gets a motorscooter 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 API calls may be available to do so.

Successful responses (HTTP code 200) will consume one "Motor Scooter Route" credit (or one "Motor Scooter Reroute" credit if reroute_signature is used) for each HTTP response. Unsuccessful calls will not consume any credits.

Authorizations:

API Key

query Parameters

start required	Array of numbers <double> 2 items Example: start=51.524247,-0.10641 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 required	Array of numbers <double> 2 items Example: end=51.507752,-0.110081 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	string Example: language=zh-Hans 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	string Example: reroute_signature=v1.eJxtkM1OwzAQhN9lrzjp%2Bi9O%2FARwgQNIH... 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	integer Example: start_bearing=37 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.

Responses

Response samples

200
400
401
429

Content type

application/json

{"routes": [{"start": {"coordinates": {"lat": 51.524387,
"lon": -0.106324
}
},
"end": {"coordinates": {"lat": 51.50758,
"lon": -0.107744
}
},
"duration_seconds": 797,
"legs": [{"travel_mode": "self_piloted",
"vehicle_types": ["motorscooter"
],
"duration_seconds": 797,
"path": "_flyHbjPDZBTBNDJ",
"path_annotations": [{"start_index": 1,
"end_index": 3,
"should_walk": true
}
]
}
]
}
]
}

Motor scooter directions between two points (hire vehicles)

NOTE this API is not available through open access, please contact sales. Please contact Citymapper using the details provided at the top of the page for information on integrating and using this API.

Gets a motorscooter 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.

Successful responses (HTTP code 200) will consume one "Motor Scooter Route" credit (or one "Motor Scooter Reroute" credit if reroute_signature is used) for each HTTP response. Unsuccessful calls will not consume any credits.

Authorizations:

API Key

query Parameters

start

required

Array of numbers <double> 2 items

Example: start=51.524247,-0.10641

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

required

Array of numbers <double> 2 items

Example: end=51.507752,-0.110081

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

required

string

Example: brand_id=ScooterBrand

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.

ride_state

string

Enum: "walking_to_vehicle" "riding" "walking_to_end"

Example: ride_state=walking_to_vehicle

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

string

Example: current_location=51.524247,-0.106410

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.

ride_start_location

string

Example: ride_start_location=51.524247,-0.106410

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

ride_end_location

string

Example: ride_end_location=51.524247,-0.106410

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

string

Example: language=zh-Hans

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

string

Example: reroute_signature=v1.eJxtkM1OwzAQhN9lrzjp%2Bi9O%2FARwgQNIH...

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

integer

Example: start_bearing=37

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.

Responses

Response samples

200
400
401
429

Content type

application/json

{"routes": [{"start": {"coordinates": {"lat": 51.524387,
"lon": -0.106324
}
},
"end": {"coordinates": {"lat": 51.50758,
"lon": -0.107744
}
},
"duration_seconds": 797,
"legs": [{"travel_mode": "walk",
"duration_seconds": 211,
"path": "_flyHbjPDZBTBNDJ"
},
{"travel_mode": "self_piloted",
"vehicle_types": ["motorscooter"
],
"duration_seconds": 586,
"services": {"id": "ScooterBrand",
"name": "Scooter Brand",
"vehicle_types": ["motorscooter"
],
"brand": {"id": "ScooterBrand",
"name": "Scooter Brand",
"image_key": "scooter-brand"
},
"color": "#000000",
"text_color": "#FFFFFF"
},
"path": "_flyHbjPDZBTBNDJ"
}
]
}
]
}

Taxi directions between two points

NOTE this API is not generally available through open access, please contact sales. A number of integrations for Taxi providers are available. Please contact Citymapper using the details provided at the top of the page for information on integrating and using this API.

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 API integrations have been configured for your account.

There are two recommended ways to use this API: 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.

Successful responses (HTTP code 200) will consume one "Taxi Route" credit for each HTTP response. Unsuccessful calls will not consume any credits.

NOTE use of this API may involve sending end-user location data to Third-Parties for the purposes of providing live on-demand service estimates.

Authorizations:

API Key

query Parameters

start required	Array of numbers <double> 2 items Example: start=51.524247,-0.10641 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 required	Array of numbers <double> 2 items Example: end=51.507752,-0.110081 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_demand_services	string Enum: "true" "false" Example: fetch_on_demand_services=false If set to `"true"`, additional information will be requested from your Taxi API 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 APIs, 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 APIs.
brand_ids	Array of strings Example: brand_ids=TaxiBrand,anothertaxi 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	string Example: language=zh-Hans 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.

Responses

Response samples

200
400
401
429

Content type

application/json

Example

{"routes": [{"start": {"coordinates": {"lat": 51.507662,
"lon": -0.107549
}
},
"end": {"coordinates": {"lat": 51.521295,
"lon": -0.081549
}
},
"distance_meters": 3240,
"duration_seconds": 1026,
"duration_accuracy": "live",
"price": {"formatted": "£10-13",
"currency": "GBP",
"demand_multiplier": 1,
"amount_range_minimum": "10.00",
"amount_range_maximum": "13.00"
},
"legs": [{"duration_seconds": 786,
"path": "}akyH`_Td@KDARGd@OLEAQI_A?KAW?]?_@?u@?]?Y@w@?C?g@@_B?U?O?M?O?OUAE?IAWGI?M?K?k@AE?GGK@OAM?G?I?SBMBQ@KLw@@u@CkCEaA?aBCG?Y?O@I@YDQDOBI@OBG?M?GCECQSGGGKGIEQECEAEMEMEKCIEOACCMCQGo@AWKOEw@DO?KA[?EA_@?K?W?K?c@EQ?O?SDeA?KDOBe@B}A@[FmCBi@@e@@e@?UBe@?QBs@?I@U@S?M@i@?G?K@IAI?U@G@G?m@CUAO@ICqAFQA[AS?UAMAMAOCUCWAOCU?GAKGa@C[MeAESMeAAK?CGICOC[@QIk@Gi@IKCOCMAIGi@Gc@ESAKGm@G[AG@SAMUuAO}@E[CQKs@Ic@CMAOUuAGIAGCKCKGSGQ@a@@GBg@?G@QEKCOCUWHC@ED[Tk@\\GDSLe@Xi@ZWNE@GAEAOIQIECGCGCECw@SEAGCg@MOCAAC?IEWGa@M_@KSGEAKC[ICA[I}@UKEUGGAEASGYIICGCKEECc@SKGIBKE{@a@CAECMEOIGCUK]Q_@OUMGCIGOIIIH[BG@GH_@Rw@BS@GBONs@Hc@DGDOkAw@wA{@CCu@a@u@a@GCQGFg@DOLq@VmAX_BBOF_@Fo@?KAMCMEOQc@o@wAOW{@qA_@a@GECC[U[QGCGCOGEC",
"updatable_detail": {"leg_departure_time": "2022-08-24T12:23:06.241759+00:00",
"leg_arrival_time": "2022-08-24T12:36:12.241759+00:00",
"live_service_estimate_availability": "included",
"on_demand_service_estimates": [{"service": {"id": "cab_taxicab",
"name": "Black Cab",
"vehicle_types": ["car"
],
"brand": {"id": "TaxiCab",
"name": "Cab",
"images": [{"url": "https://d3440lt1d9mf95.cloudfront.net/aaa783b309a8c749b2b694552b7647a5bbae317eab35e29d370f33f6/d324a6fb/@2x.png",
"width": 40,
"height": 24,
"ui_role": "summary"
},
{"url": "https://d1a19ub1xx68i2.cloudfront.net/01274400dd23089d4184d73f4a54b2eb20a31cd6f42bfbe12582c7ce/d324a6fb/@2x.png",
"width": 24,
"height": 24,
"ui_role": "summary",
"is_generic": true
}
]
},
"images": [{"url": "https://d3440lt1d9mf95.cloudfront.net/7514781b44626ed639932c5b1a7c2fc16e470951c9dec306fae4a023/d324a6fb/@2x.png",
"width": 32,
"height": 20,
"ui_role": "vehicle"
},
{"url": "https://d3440lt1d9mf95.cloudfront.net/18adfb4492ef4f4cd6315de22345d952c59cdb5486a9dc2c3403399e/d324a6fb/@2x.png",
"width": 24,
"height": 24,
"ui_role": "service"
},
{"url": "https://d1a19ub1xx68i2.cloudfront.net/f4d3aadfece8d8b30d22691edbebea19a71d28cd78d33e41b1f5fccb/d324a6fb/@2x.png",
"width": 32,
"height": 20,
"ui_role": "vehicle",
"is_generic": true
}
],
"third_party_app": {"name": "CabApp",
"images": [{"url": "https://d1a19ub1xx68i2.cloudfront.net/f10db4323eb280872910b475f651b105124f48a0e76dfafe02008652/d324a6fb/@2x.png",
"width": 24,
"height": 24,
"ui_role": "icon"
}
],
"branding_color": "#000000",
"branding_text_color": "#FFFFFF",
"android_app_id": "com.cabapp",
"ios_app_id": "469463298"
}
},
"estimate_accuracy": "live",
"suggested": true,
"pickup_eta_seconds": 240,
"price": {"formatted": "£10-13",
"currency": "GBP",
"demand_multiplier": 1,
"amount_range_minimum": "10.00",
"amount_range_maximum": "13.00"
},
"external_booking_deep_link": "cabapp://?pickup[latitude]=51.507662&pickup[longitude]=-0.107549&dropoff[latitude]=51.521295&dropoff[longitude]=-0.081549&action=setPickup"
}
]
},
"travel_mode": "on_demand",
"vehicle_types": ["car"
],
"service_brands": [{"id": "TaxiCab",
"name": "Cab",
"images": [{"url": "https://d3440lt1d9mf95.cloudfront.net/aaa783b309a8c749b2b694552b7647a5bbae317eab35e29d370f33f6/d324a6fb/@2x.png",
"width": 40,
"height": 24,
"ui_role": "summary"
},
{"url": "https://d1a19ub1xx68i2.cloudfront.net/01274400dd23089d4184d73f4a54b2eb20a31cd6f42bfbe12582c7ce/d324a6fb/@2x.png",
"width": 24,
"height": 24,
"ui_role": "summary",
"is_generic": true
}
]
}
]
}
],
"route_departure_time": "2022-08-24T12:19:06.241759+00:00",
"route_arrival_time": "2022-08-24T12:36:12.241759+00:00",
"signature": "v2.eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJjbTp0YXhpMSIsImlhdCI6MTY2MTM0MzU0Niwic3JjIjoidGF4aV9xdW90ZSIsInR0bCI6MzYwMCwicGFjayI6IntcImRtXCI6MzI0MCxcImRzXCI6MTAyNixcImVjXCI6XCI1MS41MjEyOTUsLTAuMDgxNTQ5XCIsXCJsXCI6W3tcImJcIjpbXCJUYXhpQ2FiXCJdLFwiZHNcIjo3ODYsXCJlY1wiOlwiNTEuNTIxMjcsLTAuMDgxNFwiLFwibVwiOlwib25fZGVtYW5kXCIsXCJzY1wiOlwiNTEuNTA3NjcsLTAuMTA3NTNcIn1dLFwic2NcIjpcIjUxLjUwNzY2MiwtMC4xMDc1NDlcIixcInZcIjpcIjFcIn0iLCJzdGFydCI6eyJsYXQiOjUxLjUwNzY2MiwibG5nIjotMC4xMDc1NDl9LCJlbmQiOnsibGF0Ijo1MS41MjEyOTUsImxuZyI6LTAuMDgxNTQ5fSwicmVnaW9uX2lkIjoidWstbG9uZG9uIn0.nfG4DD-EBEhL8GeEOnOh1G-Y-rjmjAaQEInePbfaFe8",
"requested_time_type": "depart_approximate"
}
]
}

Walking directions 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 API will return a code 400 response.

The maximum great-circle distance between the start and end is limited to 100km for this API.

Successful responses (HTTP code 200) will consume one "Walk Route" credit (or one "Walk Reroute" credit if reroute_signature is used) for each HTTP response. Unsuccessful calls will not consume any credits.

Authorizations:

API Key

query Parameters

start

required

Array of numbers <double> 2 items

Example: start=51.524247,-0.10641

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

required

Array of numbers <double> 2 items

Example: end=51.507752,-0.110081

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

string

Example: language=zh-Hans

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

string

Example: profiles=fast,main_roads

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

string

Example: reroute_signature=v1.eJxtkM1OwzAQhN9lrzjp%2Bi9O%2FARwgQNIH...

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

integer

Example: start_bearing=37

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.

Responses

Response samples

200
400
401
429

Content type

application/json

{"routes": [{"start": {"coordinates": {"lat": 51.524247,
"lon": -0.10641
}
},
"end": {"coordinates": {"lat": 51.507752,
"lon": -0.110081
}
},
"duration_seconds": 1854,
"legs": [{"travel_mode": "walk",
"duration_seconds": 1854,
"path": "shxgaBdwnEZMzBiAv@?j@XnJ~JhBhBdCtDfEzGpDkEzA{BpE}G`KoOv@kALo@Cw@uC_NOwBImCH{CRuAd@mBhAmCtAaCzCkD`DmCjAwAnJjYzEdS~GpYl@e@`CjJzHbXj@`B|AlAXa@tA{@hBoArB}AxBcB~N_LvBuArFiDAwA\\i@vIsFzOmJ|AaApAk@rEqBbQwHdGqBzCnBtBq@`KgCt@Q~F_B`G}A~@UlEaAr@ORE\\GbB_@RG`DcApFcAAEbAUvLiChBg@nE{@xPkDz@Y`C_@`BKbE]dFzFbAMzAt@rMmAfFe@jE}@tI{A|AYxCk@zCiBvEeDdAU`ScBdAg@hD[vSwCle@yGlGy@bDc@z@Mt@Fp@x@~@d@\\@r@CjL}AzGeA~h@sHrIuAdFi@xAYfEi@xF{@bAKxZiElQcBj@ExCShFQd`@Ah_@l@C`BfHn@pCjB~JpKfGzJ\\e@t@{@\\k@`@s@j@PnBYlBw@vCaBnCsANCpCNz@_@hC{@nCu@tCMbC?hdCdEtD]pDMxJ}@bAgAbACG~TARMhf@j@jAGbU^nYZ~GnBlQNh@nCvKpC~KtBdMr@~DV|EH|r@LtDRrBP|A~@xEv@~D_BhB_@~Ik@lH}DlEoAd@rB`S`A@BlM",
"instructions": [{"path_index": 0,
"description_text": "Walk South on Clerkenwell Close",
"type": "depart"
},
{"path_index": 3,
"distance_meters": 12,
"time_seconds": 9,
"description_text": "Turn right onto Clerkenwell Close",
"type": "turn",
"type_direction": "right"
},
{"path_index": 8,
"distance_meters": 59,
"time_seconds": 44,
"description_text": "Turn left onto Clerkenwell Close",
"type": "turn",
"type_direction": "left"
},
{"path_index": 26,
"distance_meters": 150,
"time_seconds": 118,
"description_text": "Turn right onto Clerkenwell Green",
"type": "turn",
"type_direction": "right"
},
{"path_index": 33,
"distance_meters": 149,
"time_seconds": 112,
"description_text": "Turn left onto Farringdon Road",
"type": "turn",
"type_direction": "left"
},
{"path_index": 76,
"distance_meters": 447,
"time_seconds": 367,
"description_text": "Slight right onto Farringdon Street",
"type": "turn",
"type_direction": "slight_right"
},
{"path_index": 117,
"distance_meters": 739,
"time_seconds": 561,
"description_text": "Turn right onto Watergate",
"type": "turn",
"type_direction": "right"
},
{"path_index": 118,
"distance_meters": 3,
"time_seconds": 3,
"description_text": "Turn left",
"type": "turn",
"type_direction": "left"
},
{"path_index": 122,
"distance_meters": 71,
"time_seconds": 53,
"description_text": "Turn left",
"type": "turn",
"type_direction": "left"
},
{"path_index": 144,
"distance_meters": 375,
"time_seconds": 282,
"description_text": "Turn right",
"type": "turn",
"type_direction": "right"
},
{"path_index": 148,
"distance_meters": 72,
"time_seconds": 54,
"description_text": "Continue straight on Upper Ground",
"type": "turn",
"type_direction": "straight"
},
{"path_index": 164,
"distance_meters": 239,
"time_seconds": 185,
"description_text": "Turn right",
"type": "turn",
"type_direction": "right"
},
{"path_index": 167,
"distance_meters": 30,
"time_seconds": 22,
"description_text": "Turn right",
"type": "turn",
"type_direction": "right"
},
{"path_index": 169,
"distance_meters": 17,
"time_seconds": 13,
"description_text": "Turn left",
"type": "turn",
"type_direction": "left"
},
{"path_index": 170,
"distance_meters": 23,
"time_seconds": 17,
"description_text": "Turn left",
"type": "turn",
"type_direction": "left"
},
{"path_index": 171,
"distance_meters": 4,
"time_seconds": 3,
"description_text": "Turn right",
"type": "turn",
"type_direction": "right"
},
{"path_index": 172,
"distance_meters": 16,
"time_seconds": 12,
"description_text": "Arrive at your destination",
"type": "arrive"
}
]
}
],
"signature": "v1.eJxtkMtOwzAQRf9ltjjp2InrxF9AN2UBEguEUBS7lWliV44DQlX+nUlCWVB2fsy952gu0AafrE+gL2DG2CQXPGheyZKB9WZ+bkOIZgANkucSlZKCZZhzjlhxmBh09ki/L5R3Q2p8a0GLEiW77Wt/S6piLcG63gKDPhhKwWfTneg2XOdEKeQ6ti0UsV4ZRHtcGmE8ZV3whs4USE1MN6qULtVPvFxMk+tnjECBGeeZKJ44ai60kHeIGnGzf3jePd5T44eNw8IR07KHc3DzjuAQl3WZzXsYo7dfCq5Kb878sZppZNaf/0fmNQmqaiXD9A0DoW3iLrtbq3uV5gbbkpyVbELQf6gVXGh9"
}
]
}

Car directions between two points (ride only)

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

Successful responses (HTTP code 200) will consume one "Car Route" credit for each HTTP response. Unsuccessful calls will not consume any credits.

Authorizations:

API Key

query Parameters

start required	Array of numbers <double> 2 items Example: start=51.524247,-0.10641 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 required	Array of numbers <double> 2 items Example: end=51.507752,-0.110081 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	string Example: language=zh-Hans 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.

Responses

Response samples

200
400
401
429

Content type

application/json

{"routes": [{"start": {"coordinates": {"lat": 51.524387,
"lon": -0.106324
}
},
"end": {"coordinates": {"lat": 51.50758,
"lon": -0.107744
}
},
"duration_seconds": 1086,
"legs": [{"travel_mode": "self_piloted",
"vehicle_types": ["car"
],
"duration_seconds": 1086,
"path": "_flyHbjPDZBTBNDJ"
}
]
}
]
}

Transit directions 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.

Successful responses (HTTP code 200) will consume one "Transit Route" credit for each HTTP response. Unsuccessful calls will not consume any credits.

Authorizations:

API Key

query Parameters

start

required

Array of numbers <double> 2 items

Example: start=51.524247,-0.10641

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

required

Array of numbers <double> 2 items

Example: end=51.507752,-0.110081

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

string

Example: time=2020-08-19T08:10:42-04:00

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

string

Enum: "arrive" "depart" "depart_approximate"

Example: time_type=depart

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

string

Example: language=zh-Hans

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

integer [ 1 .. 5 ]

Default: 5

Example: limit=3

Maximum number of Routes to return.

Responses

Response samples

200
400
401
429

Content type

application/json

Example

{"routes": [{"start": {"coordinates": {"lat": 40.74244,
"lon": -74.006144
}
},
"end": {"coordinates": {"lat": 40.643351,
"lon": -73.7892
}
},
"duration_seconds": 3628,
"route_departure_time": "2020-08-19T08:10:21-04:00",
"route_arrival_time": "2020-08-19T09:11:08-04:00",
"price": {"formatted": "$18.25",
"amount": "18.25",
"currency": "USD"
},
"legs": [{"travel_mode": "walk",
"duration_seconds": 474,
"path": "_flyHbjPDZBTBNDJ",
"updatable_detail": {"leg_departure_time": "2020-08-19T08:10:21-04:00",
"leg_arrival_time": "2020-08-19T08:18:15-04:00"
}
},
{"travel_mode": "transit",
"vehicle_types": ["subway",
"metro",
"rail"
],
"duration_seconds": 240,
"services": [{"id": "C",
"name": "C",
"vehicle_types": ["subway",
"metro",
"rail"
],
"brand": {"id": "NewYorkSubway",
"image_key": "us-nyc-subway"
},
"image_key": "us-nyc-subway-c",
"image_replaces_name": true,
"color": "#2850AD",
"background_color": "#2850AD",
"text_color": "#FFFFFF"
},
{"id": "E",
"name": "E",
"vehicle_types": ["subway",
"metro",
"rail"
],
"brand": {"id": "NewYorkSubway",
"image_key": "us-nyc-subway"
},
"image_key": "us-nyc-subway-e",
"image_replaces_name": true,
"color": "#2850AD",
"background_color": "#2850AD",
"text_color": "#FFFFFF"
}
],
"path": "_flyHbjPDZBTBNDJ",
"stops": [{"id": "Subway8Av14St",
"name": "8 Av - 14 St",
"coordinates": {"lat": 40.740893,
"lon": -74.00169
}
},
{"id": "Subway23StCE",
"name": "23 St",
"coordinates": {"lat": 40.745906,
"lon": -73.998041
}
},
{"id": "Subway34StPennStationACE",
"name": "34 St - Penn Station",
"coordinates": {"lat": 40.752287,
"lon": -73.993391
}
}
],
"updatable_detail": {"departures": [{"service_id": "E",
"type": "frequency",
"frequency_seconds_range": [188,
188
],
"platform_description": "Uptown"
},
{"service_id": "C",
"type": "frequency",
"frequency_seconds_range": [720,
1080
],
"platform_description": "Uptown"
}
],
"live_departure_availability": "additional_request",
"statuses": [{"type": "travel_affected",
"title": "Changed Frequency",
"description": "<C> trains are running approximately every 12-18 minutes between 168 St and Euclid Av.",
"service_ids": ["C"
]
},
{"type": "travel_affected",
"title": "Changed Frequency",
"description": "<E> trains are running approximately every 6-8 minutes between Jamaica Center - Parsons/Archer and World Trade Center.",
"service_ids": ["E"
]
}
],
"leg_departure_time": "2020-08-19T08:21:30-04:00",
"leg_arrival_time": "2020-08-19T08:25:30-04:00"
}
},
{"travel_mode": "walk",
"duration_seconds": 200,
"path": "_flyHbjPDZBTBNDJ",
"updatable_detail": {"leg_departure_time": "2020-08-19T08:25:30-04:00",
"leg_arrival_time": "2020-08-19T08:28:50-04:00"
}
},
{"travel_mode": "transit",
"vehicle_types": ["rail"
],
"duration_seconds": 1380,
"services": [{"id": "LIRRBabylon",
"name": "Babylon",
"vehicle_types": ["rail"
],
"brand": {"id": "LIRR",
"image_key": "us-nyc-lirr"
},
"image_key": "us-nyc-lirr-babylon",
"image_replaces_name": false,
"color": "#00985F",
"background_color": "#00985F",
"text_color": "#FFFFFF"
},
{"id": "LIRRLongBeach",
"name": "Lg Beach",
"vehicle_types": ["rail"
],
"brand": {"id": "LIRR",
"image_key": "us-nyc-lirr"
},
"image_key": "us-nyc-lirr-long-beach",
"image_replaces_name": false,
"color": "#FF6319",
"background_color": "#FF6319",
"text_color": "#FFFFFF"
},
{"id": "LIRRPortJefferson",
"name": "Port Jeff",
"vehicle_types": ["rail"
],
"brand": {"id": "LIRR",
"image_key": "us-nyc-lirr"
},
"image_key": "us-nyc-lirr-port-jefferson",
"image_replaces_name": false,
"color": "#0039A6",
"background_color": "#0039A6",
"text_color": "#FFFFFF"
},
{"id": "LIRRRonkonkoma",
"name": "Ronkonkoma",
"vehicle_types": ["rail"
],
"brand": {"id": "LIRR",
"image_key": "us-nyc-lirr"
},
"image_key": "us-nyc-lirr-ronkonkoma",
"image_replaces_name": false,
"color": "#A626AA",
"background_color": "#A626AA",
"text_color": "#FFFFFF"
}
],
"path": "_flyHbjPDZBTBNDJ",
"stops": [{"id": "RailStationPennStation",
"name": "New York Penn",
"coordinates": {"lat": 40.750239,
"lon": -73.992829
}
},
{"id": "RailStationForestHills",
"name": "Forest Hills",
"coordinates": {"lat": 40.719576,
"lon": -73.844814
}
},
{"id": "RailStationKewGardens",
"name": "Kew Gardens",
"coordinates": {"lat": 40.709649,
"lon": -73.830888
}
},
{"id": "RailStationJamaica",
"name": "Jamaica",
"coordinates": {"lat": 40.6996,
"lon": -73.80853
}
}
],
"updatable_detail": {"departures": [{"service_id": "LIRRBabylon",
"type": "scheduled",
"scheduled_time": "2020-08-19T08:33:00-04:00",
"short_name": "28",
"frequency_seconds_range": [188,
188
],
"platform_description": "Uptown"
}
],
"live_departure_availability": "additional_request",
"statuses": [{"type": "travel_affected",
"title": "Service Alert",
"description": "About 90% of our regular weekday trains are running. While we're running on the Essential Schedule, off peak fares remain in effect on all LIRR trains, including trains operating in traditional peak/rush hour time periods. To minimize contact with crew members, use MTA eTix on smartphones and activate eTix just before boarding. Ticket machines are available at most stations for cash &amp; credit card purchases. Remember: If you're using MTA services, you must wear a face covering (mask/bandana/scarf) at the station and for the entire duration of your train ride.",
"service_ids": ["LIRRBabylon",
"LIRRLongBeach",
"LIRRPortJefferson",
"LIRRRonkonkoma"
]
}
],
"leg_departure_time": "2020-08-19T08:33:00-04:00",
"leg_arrival_time": "2020-08-19T08:56:00-04:00"
}
},
{"travel_mode": "walk",
"duration_seconds": 60,
"path": "_flyHbjPDZBTBNDJ",
"updatable_detail": {"leg_departure_time": "2020-08-19T08:56:00-04:00",
"leg_arrival_time": "2020-08-19T08:57:00-04:00"
}
},
{"travel_mode": "transit",
"vehicle_types": ["metro",
"rail"
],
"duration_seconds": 420,
"services": [{"id": "AirTrainAirtrainjfk",
"name": "AirTrain JFK",
"vehicle_types": ["metro",
"rail"
],
"brand": {"id": "AirTrain",
"image_key": "us-nyc-airtrain"
},
"image_key": "us-nyc-airtrain-jfk",
"image_replaces_name": true,
"color": "#008CD1",
"background_color": "#008CD1"
}
],
"path": "_flyHbjPDZBTBNDJ",
"stops": [{"id": "AirTrainJamaica",
"name": "Jamaica",
"coordinates": {"lat": 40.6989,
"lon": -73.80845
}
},
{"id": "AirTrainFederalCircle",
"name": "Federal Circle",
"coordinates": {"lat": 40.65982,
"lon": -73.80349
}
},
{"id": "AirTrainJFKTerminal1",
"name": "Terminal 1",
"coordinates": {"lat": 40.643378,
"lon": -73.789097
}
}
],
"updatable_detail": {"departures": [{"service_id": "AirTrainAirtrainjfk",
"type": "frequency",
"frequency_seconds_range": [750,
750
],
"platform_description": "Airport Terminals"
},
{"service_id": "C",
"type": "frequency",
"frequency_seconds_range": [720,
1080
],
"platform_description": "Uptown"
}
],
"live_departure_availability": "none_available",
"leg_departure_time": "2020-08-19T09:02:30-04:00",
"leg_arrival_time": "2020-08-19T09:09:30-04:00"
}
},
{"travel_mode": "walk",
"duration_seconds": 98,
"path": "_flyHbjPDZBTBNDJ",
"updatable_detail": {"leg_departure_time": "2020-08-19T09:09:30-04:00",
"leg_arrival_time": "2020-08-19T09:11:08-04:00"
}
}
],
"signature": "eJyNUl2P0zAQ/CuRX0mOtWMncR9B3IdAgFQQD6dTZOKlyjVnF9vhkKL+d+ykRaEPJyQ/2Lvj2ZnRTqRTjmwyxkSdZ0SPToXemlihpYBYQaPjYyJKa4fexzuhBctuVfjR46B9nn2wRluTbd/RTH6+ybOv70n811nr9AwX9EpALaq8gCsKdQ1l6hv1hP9HdozoR9f2RuPv+COJGnCXqO8nonsflOkSFZMXDhhLBezOIhiHkwjJkoQnq2cJz2rYp7dfITldkFVZJQHTmrem8m8whEsAWsqSb9eUwSnj+5BKzo4B237O4p4s/t6MvirJQ5oZlAtnHuCM1jOPD/bQdnY0qdcsAlZOK3nhlJb/OI1xy1Pc4mWn0LCTU84ackySDq7vsD3gMovOW+Bwt0wi474YZg9nb73ZtQ5/juhDdJkgDWje8AqK70qLgoOoCykoFoyXkgvAqqkbsvI+XSxLSr8+xy/peltKlr0d0O3RPOMwxLv1mGfXyrkoI4lKyxL6BcyAQQFNQdkXKjfxMPYK6Abg9cdP3+62t4n4Fzp/yvD4B94v0po=",
"requested_time_type": "depart_approximate"
}
],
"language": "en-US"
}

Scenario based directions between two points

NOTE This API requires the use of a Scenario ID to select the routing scenario used to determine the type and properties of Routes returned from this endpoint. Please contact Citymapper using the details provided at the top of the page for information on integrating and using this API.

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.

Successful responses (HTTP code 200) will consume "Scenario Route" credits depending on a provided scenario and may vary. Unsuccessful calls will not consume any credits.

Authorizations:

API Key

query Parameters

scenario_id

required

string

Example: scenario_id=transit

Scenario ID for directions.

start

required

Array of numbers <double> 2 items

Example: start=51.524247,-0.10641

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

required

Array of numbers <double> 2 items

Example: end=51.507752,-0.110081

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

string

Example: time=2020-08-19T08:10:42-04:00

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

string

Enum: "arrive" "depart" "depart_approximate"

Example: time_type=depart

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

string

Example: language=zh-Hans

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.

Responses

Response samples

200
400
401
429

Content type

application/json

{"routes": [{"start": {"coordinates": {"lat": 51.524247,
"lon": -0.10641
}
},
"end": {"coordinates": {"lat": 51.524247,
"lon": -0.10641
}
},
"distance_meters": 562,
"duration_seconds": 1139,
"duration_accuracy": "scheduled",
"price": {"formatted": "£1.50",
"amount": "1.50",
"amount_range_minimum": "1.50",
"amount_range_maximum": "3.50",
"currency": "GBP",
"demand_multipler": 1.2
},
"emissions_grams_co2e": 8.2,
"legs": [{"travel_mode": "self_piloted",
"duration_seconds": 622,
"path": "_flyHbjPDZBTBNDJ",
"instructions": [{"path_index": 0,
"distance_meters": 221,
"time_seconds": 64,
"description_text": "Turn left onto Hatfields",
"description_format": "Turn left onto {key_1}",
"description_format_replacements": [{"key": "key_1",
"type": "street_name",
"text": "Hatfields",
"language": "en-GB"
}
],
"type": "turn",
"type_direction": "left"
}
]
}
],
"route_departure_time": "string",
"route_arrival_time": "string",
"route_metadata": {"groups": [{"group_id": "transit",
"group_name": "Transit",
"route_position": 0
}
],
"profile_name": "Hauptstraßen"
},
"profile": "string",
"signature": "v2.eJyNUl2P0zAQ/CuRX0mOtWMncR9B3IdAgFQQD6dTZOKlyjVnF9vhkKL+d+ykRaEPJyQ/2Lvj2ZnRTqRTjmwyxkSdZ0SPToXemlihpYBYQaPjYyJKa4fexzuhBctuVfjR46B9nn2wRluTbd/RTH6+ybOv70n811nr9AwX9EpALaq8gCsKdQ1l6hv1hP9HdozoR9f2RuPv+COJGnCXqO8nonsflOkSFZMXDhhLBezOIhiHkwjJkoQnq2cJz2rYp7dfITldkFVZJQHTmrem8m8whEsAWsqSb9eUwSnj+5BKzo4B237O4p4s/t6MvirJQ5oZlAtnHuCM1jOPD/bQdnY0qdcsAlZOK3nhlJb/OI1xy1Pc4mWn0LCTU84ackySDq7vsD3gMovOW+Bwt0wi474YZg9nb73ZtQ5/juhDdJkgDWje8AqK70qLgoOoCykoFoyXkgvAqqkbsvI+XSxLSr8+xy/peltKlr0d0O3RPOMwxLv1mGfXyrkoI4lKyxL6BcyAQQFNQdkXKjfxMPYK6Abg9cdP3+62t4n4Fzp/yvD4B94v0po=",
"requested_time": "2020-08-19T08:10:42-04:00",
"requested_time_type": "depart_approximate"
}
],
"language": "en-US"
}

Live departure and availability information for multiple Routes at once

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

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.

Authorizations:

API Key

Request Body schema: application/json

signatures

required

Array of strings

An array of signature properties from previously-obtained Routes

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 API), if this is set to "true", additional information will be requested from Taxi API 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 APIs, 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 APIs.

If no update can be produced for a Leg without this parameter being set true, the response will indicate this within the updateable detail.

Responses

Request samples

Payload

Content type

application/json

{"signatures": ["eJyNUl2P0zAQ/CuRX0mOtWMncR9B3IdAgFQQD6dTZOKlyjVnF9vhkKL+d+ykRaEPJyQ/2Lvj2ZnRTqRTjmwyxkSdZ0SPToXemlihpYBYQaPjYyJKa4fexzuhBctuVfjR46B9nn2wRluTbd/RTH6+ybOv70n811nr9AwX9EpALaq8gCsKdQ1l6hv1hP9HdozoR9f2RuPv+COJGnCXqO8nonsflOkSFZMXDhhLBezOIhiHkwjJkoQnq2cJz2rYp7dfITldkFVZJQHTmrem8m8whEsAWsqSb9eUwSnj+5BKzo4B237O4p4s/t6MvirJQ5oZlAtnHuCM1jOPD/bQdnY0qdcsAlZOK3nhlJb/OI1xy1Pc4mWn0LCTU84ackySDq7vsD3gMovOW+Bwt0wi474YZg9nb73ZtQ5/juhDdJkgDWje8AqK70qLgoOoCykoFoyXkgvAqqkbsvI+XSxLSr8+xy/peltKlr0d0O3RPOMwxLv1mGfXyrkoI4lKyxL6BcyAQQFNQdkXKjfxMPYK6Abg9cdP3+62t4n4Fzp/yvD4B94v0po="
],
"fetch_on_demand_services": false
}

Response samples

200
400
401
429

Content type

application/json

Example

{"route_updates": [{"leg_updates": [{ },
{"departures": [{"type": "live",
"service_id": "C",
"headsign": "168 St",
"live_time": "2020-08-19T08:15:42-04:00",
"scheduled_time": "2020-08-19T08:15:00-04:00",
"suggested_departure": "suggested",
"time_status": "on_time"
},
{"type": "live",
"service_id": "E",
"headsign": "Jamaica Center - Parsons/Archer",
"live_time": "2020-08-19T08:12:42-04:00",
"scheduled_time": "2020-08-19T08:13:30-04:00",
"time_status": "on_time"
},
{"type": "scheduled",
"service_id": "E",
"headsign": "Jamaica Center - Parsons/Archer",
"scheduled_time": "2020-08-19T08:16:30-04:00"
}
],
"live_departure_availability": "included"
},
{ },
{"departures": [{"type": "live",
"service_id": "LIRRBabylon",
"headsign": "Babylon",
"short_name": "24",
"live_time": "2020-08-19T09:09:00-04:00",
"scheduled_time": "2020-08-19T09:09:00-04:00",
"time_status": "on_time",
"platform_short_name": "18",
"suggested_departure": "suggested"
},
{"type": "live",
"service_id": "LIRRRonkonkoma",
"headsign": "Ronkonkoma",
"short_name": "2012",
"live_time": "2020-08-19T09:14:00-04:00",
"scheduled_time": "2020-08-19T09:14:00-04:00",
"time_status": "on_time"
}
],
"live_departure_availability": "included"
},
{ },
{"departures": [{"type": "frequency",
"service_id": "AirTrainAirtrainjfk",
"headsign": "Jamaica",
"frequency_seconds_range": [750,
750
],
"frequency_start_time": "2020-08-19T08:00:00-04:00",
"frequency_end_time": "2020-08-19T10:42:30-04:00",
"suggested_departure": "suggested"
}
],
"live_departure_availability": "included"
},
{ }
]
}
]
}

Nearby API Calls

Nearby Tiles

NOTE this API is not available through open access, please contact sales.

Please contact Citymapper using the details provided at the top of the page for information on integrating and using this API.

The zoom, x and y parameters follow the OpenStreetMap Slippy Map Tiles convention. This z,x,y tuple follows the same convention as many basemap layers, including Mapbox and OSM. Note that it is not a basemap though, it returns a custom format that must be drawn onto a map client-side. This provides an API to get what various transport related features are in an area, from metro lines to bike hire dock locations and train stations.

This API can be used in conjuction with the details APIs to get further details on the features returned in a tile, for example: live departures of a bus stop or brand details for a metro line.

Authorizations:

API Key

path Parameters

tileset required	string Example: bus_stops Current tilesets include: `transit:stops` `transit:lines` `[brand_id]:hire_vehicles` `[brand_id]:coverage_zones` `[brand_id]:unroutable_zones` `[brand_id]:parking_zones` `[brand_id]:preferred_parking_zones` `[brand_id]:forbidden_parking_zones` `[brand_id]:slow_zones`
zoom required	integer Example: 12 Zoom-level, in the range from `0` to `18`. Not all tilesets will show everything or anything at every zoom level.
x required	integer Example: 2048 Longitudinal tile grid column, upper-left of viewport. Note that this is not a lat-long coord.
y required	integer Example: 1361 Lateral tile grid row, upper-left of viewport. Note that this is not a lat-long coord.

query Parameters

format

string

Example: format=geojson

Select the output format of the tile, current options are geojson or tile_geojson. With geojson, the geometry is described as [lon, lat] world coordinates. With tile_geojson, the geometry is desribed using [x, y] coordinates where x and y are coordinates on a 4096x4096 grid representing the position of the geometry relative to the tile bounds.

Responses

Response samples

200
400
401
429

Content type

application/json

{"id": "bus_stops/12/2048/1361",
"type": "FeatureCollection",
"properties": {"bounds": {"top_left": {"lat": 51.524247,
"lon": -0.10641
},
"bottom_right": {"lat": 51.524247,
"lon": -0.10641
}
},
"services": [{"id": "E",
"name": "E",
"vehicle_types": ["escooter"
],
"brand": {"id": "NewYorkSubway",
"name": "Subway",
"images": [{"url": "string",
"ui_role": "pin",
"width": 0,
"height": 0,
"pixel_ratio": 2,
"format": "png",
"is_generic": false,
"has_space_for_text": false,
"is_dropoff_place": false,
"low_capacity": false
}
]
},
"images": [{"url": "string",
"ui_role": "service",
"width": 0,
"height": 0,
"pixel_ratio": 2,
"format": "png",
"replaces_name": false
}
],
"color": "#2850AD",
"background_color": "#2850AD",
"text_color": "#FFFFFF",
"third_party_app": {"name": "string",
"images": [{"url": "string",
"ui_role": "icon",
"width": 0,
"height": 0,
"pixel_ratio": 2,
"format": "png"
}
],
"branding_color": "string",
"branding_text_color": "string",
"open_or_install_deep_link": "string",
"android_open_or_install_deep_link": "string",
"ios_open_or_install_deep_link": "string",
"android_app_id": "string",
"ios_app_id": "string"
}
}
]
},
"features": [{"id": "Subway59StColumbusCircle",
"type": "Feature",
"properties": {"feature_type": "stop",
"vehicle_type": "bike",
"zone_type": "coverage_zones",
"feature_details": {"stop": {"id": "Subway8Av14St",
"name": "8 Av - 14 St",
"coordinates": {"lat": 51.524247,
"lon": -0.10641
},
"indicator_text": "AF",
"code": "032A05"
},
"hire_vehicle_station": {"hire_vehicle_station_id": "string",
"name": "string",
"service_id": "string",
"num_vehicles_available": 0,
"num_docks_available": 0
},
"hire_vehicle": {"hire_vehicle_id": "string",
"name": "string",
"service_id": "string",
"propulsion_type": "electric",
"current_range_meters": 0,
"current_fuel_percent": 0
},
"service_id": "string",
"service_ids": "string"
}
},
"geometry": {"type": "Point",
"coordinates": [-0.107616,
51.507657
]
}
}
]
}

Details API Calls

Details about a stop

NOTE this API is not available through open access, please contact sales.

Please contact Citymapper using the details provided at the top of the page for information on integrating and using this API.

Returns back details about a stop. If you ask for live in the request you will also get the departures for the stop.

The ID you provide must be from the nearby tile API, IDs from the directions APIs do not currently work.

Authorizations:

API Key

query Parameters

id required	string Example: id=123 The ID of the stop you want details for.
live	boolean Example: live=true Whether you want to get live details i.e. departures or just static details about the stop

Responses

Response samples

200
400
401
429

Content type

application/json

{"stop": {"id": "Subway8Av14St",
"name": "8 Av - 14 St",
"coordinates": {"lat": 51.524247,
"lon": -0.10641
},
"indicator_text": "AF",
"code": "032A05"
},
"departures": [{"type": "live",
"service_id": "LondonBus63",
"suggested_departure": "suggested",
"headsign": "Honor Oak",
"time_name": "19:08",
"short_name": "63",
"live_time": "2020-08-13T19:06:55+01:00",
"scheduled_time": "2020-08-13T19:08:00+01:00",
"time_status": "on_time"
}
]
}

Details about a service

NOTE this API is not available through open access, please contact sales.

Please contact Citymapper using the details provided at the top of the page for information on integrating and using this API.

Returns back the Service object for a given service ID. This contains details about the service, the brand related to the service including any related assets.

The ID you provide must be from the nearby tile API, IDs from the directions APIs do not currently work.

Authorizations:

API Key

query Parameters

id

required

string

Example: id=123

The ID of the service you want details for.

Responses

Response samples

200
400
401
429

Content type

application/json

{"service": {"id": "E",
"name": "E",
"vehicle_types": ["escooter"
],
"brand": {"id": "NewYorkSubway",
"name": "Subway",
"images": [{"url": "string",
"ui_role": "pin",
"width": 0,
"height": 0,
"pixel_ratio": 2,
"format": "png",
"is_generic": false,
"has_space_for_text": false,
"is_dropoff_place": false,
"low_capacity": false
}
]
},
"images": [{"url": "string",
"ui_role": "service",
"width": 0,
"height": 0,
"pixel_ratio": 2,
"format": "png",
"replaces_name": false
}
],
"color": "#2850AD",
"background_color": "#2850AD",
"text_color": "#FFFFFF",
"third_party_app": {"name": "string",
"images": [{"url": "string",
"ui_role": "icon",
"width": 0,
"height": 0,
"pixel_ratio": 2,
"format": "png"
}
],
"branding_color": "string",
"branding_text_color": "string",
"open_or_install_deep_link": "string",
"android_open_or_install_deep_link": "string",
"ios_open_or_install_deep_link": "string",
"android_app_id": "string",
"ios_app_id": "string"
}
}
}

Object Reference

Brand

id required	string The identifier for this Brand
name required	string The name of Brand
	Array of objects (BrandImage) A list of `Image`s that can be used to represent this `Brand` in a user interface. API consumers should use the first `Image` in the list that meets their criteria.

{"id": "NewYorkSubway",
"name": "Subway",
"images": [{"url": "string",
"ui_role": "pin",
"width": 0,
"height": 0,
"pixel_ratio": 2,
"format": "png",
"is_generic": false,
"has_space_for_text": false,
"is_dropoff_place": false,
"low_capacity": false
}
]
}

BrandImage

url required	string The URL from which this `Image` can be retrieved. The image will be encoded in PNG format unless the `format` field indicates otherwise.
ui_role required	string Enum: "pin" "station" "vehicle" "vehicle_compact" "pin_vehicle" "summary" Indicates the role that this image plays in a user interface. New values may be added at any time. See the parent object in the response for valid values in this context.
width	number The width of the image in screen units. This corresponds to `px` in CSS, "points" on iOS, and "density-independent pixels" on Android.
height	number The height of the image in screen units. This corresponds to `px` in CSS, "points" on iOS, and "density-independent pixels" on Android.
pixel_ratio	number Default: 2 Indicates the ratio of image pixels to screen units. When not provided, `2` should be assumed. For instance, an `Image` with a `width` of `38`, `height` of `41`, and `pixel_ratio` of `2` has image pixel dimensions of 76 x 82.
format	string Default: "png" Value: "png" Indicates the file format of the image. The default value is `png`, indicating Portable Network Graphics bitmap format. At time of writing, all `Images` returned are in `png` format, and therefore this field will usually be omitted. However, in the future, additional `format` types may be provided in responses.
is_generic	boolean Default: false If `true`, this indicates that this is a generic image entirely based on the vehicle type, rather than being customized for the specific brand or service. When a specific branded image of the same `ui_role` is available, it will be provided earlier in the list of images.
has_space_for_text	boolean Default: false If `true`, this image contains a designated area for overlaying extra textual elements such as "stop indicator" letters. (Some regions have 2-4 letter codes on bus stop poles to distinguish between nearby stops.) The specific renderable area will depend on the `ui_role`. When this is `true`, there will generally also be a peer `Image` without space for text, for the more common case where no text rendering is needed. This alternate `Image` will appear earlier in the list of `Image`s.
is_dropoff_place	boolean Default: false Applies to `BrandImage`s with `ui_role` of `pin` or `station` if Brand offers hire vehicles. If `true`, then this image represents a drop-off place for hire vehicles, for example a docking station for cycles or a parking area for e-scooters. An image representing drop-off place (`is_dropoff_place` set to `true`) will always be accompanied by an image representing pick-up place (`is_dropoff_place` set to `false`) provided earlier in the list of images.
low_capacity	boolean Default: false Applies to `BrandImage`s with `ui_role` of `pin` or `station` if Brand offers hire vehicles. If `true`, then this image represents a low capacity variant of pick-up or drop-off place for hire vehicles. Low capacity variant will always be accompanied by high capacity variant provided earlier in the list of images.

{"url": "string",
"ui_role": "pin",
"width": 0,
"height": 0,
"pixel_ratio": 2,
"format": "png",
"is_generic": false,
"has_space_for_text": false,
"is_dropoff_place": false,
"low_capacity": false
}

Coordinates

lat required	number <double> A latitude in WGS84 encoding, with 6 digits of decimal precision.
lon required	number <double> A longitude in WGS84 encoding, with 6 digits of decimal precision.

{"lat": 51.524247,
"lon": -0.10641
}

Departure

type

required

string

Enum: "scheduled" "frequency" "live"

Indicates what type of departure this object represents:

value	description
scheduled	A scheduled departure at an exact time according to the published timetable, does not include real-time/live information
frequency	An approximate departure frequency such as "every 7 minutes" or "every 10-12 minutes"
live	Real-time information determined from vehicle tracking systems

service_id

required

string

Indicates which Service in the Leg this Departure refers to, in order to indicate Service and Brand naming and imagery. This is redundant in single-Service Legs, but it's essential in Legs that have alternate equivalent services.

suggested_departure

string

Enum: "suggested" "alternative"

When Departures are given as part of a transit directions response in a Leg, the suggested_departure flag indicates whether Citymapper thinks this departure should be caught, following the estimated route_departure_time and subsequent leg_departure_time and leg_arrival_times. Note that these times assume the user is at the start of the Route.

A value of suggested indicates that this departure is the one used to calculate the leg_{depart,arrive}_time, while alternative indicates that taking this departure would still result in arriving at the same final route_arrival_time.

This means that departures before the first one with this suggested_departure field are likely too early for the user to be able to catch, while those after could be taken but would result in a later arrival time than the estimated route_arrival_time.

If there are no estimated times (the Leg and Route don't have the *_time fields) then no Departures will have a suggested_departure field. In this case it is likely that the user cannot successfully complete this Route at this time.

headsign

string

Text identifying the destination or pattern of this departure. This generally corresponds to text shown on the front of a transit vehicle. It will not include the Service or Brand name.

time_name

string

A user-facing identifier for the scheduled time of this departure, effectively the original time of the departure in the local format. It will only be present where the scheduled time is commonly used as part of the name (typically along with the headsign) when referring to this departure in e.g. station announcements. A concrete example of this type of departure in an announcement might be the "10:45 to Liverpool Street", where "10:45" is the time_name, and "Liverpool Street" is the headsign

Most often used in rail systems, but can appear in other contexts like some intercity coach services

short_name

string

A user-facing identifier for this specific departure or class of departures. This is generally used in commuter rail systems as a train number.

live_time

string

(Only included when type is live.)

The current time when the service is expected to depart, based on live vehicle tracking.

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.

scheduled_time

string

(Included when type is scheduled and sometimes live.)

The time when the service is expected to depart, according to the pre-published timetable. In departures with type of live, the scheduled_time is included when possible to indicate which timetabled departure the Citymapper service has associated the live departure with.

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.

alight_stop_time_name

string

A user-facing identifier for the scheduled time of this departure, at the last stop in this leg. This will generally be included when time_name is present.

alight_stop_live_time

string

(Sometimes included when type is scheduled or live.)

The time that this service is expected to arrive at the last stop in this leg, based on live vehicle tracking. This may not be available for all departures, even if live_time is present.

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.

alight_stop_scheduled_time

string

(Sometimes included when type is scheduled or live.)

The time that this service is expected to arrive at the last stop in this leg, according to the pre-published timetable. This may not be available for all departures, even if scheduled_time is present.

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.

frequency_seconds_range

Array of integers 2 items

(Included when type is frequency.)

The approximate time between departures during the time of day specified by frequency_start_time and frequency_end_time. The frequency is expressed as an array of two integers, which encode a range of headways.

For instance, a value of [180, 300] means that vehicles are expected to depart roughly every 3-5 minutes. Providing the same number twice indicates a simple headway rather than a range. For instance, the value [750, 750] means that the headway is every 12.5 minutes.

Multiple Departures with type of frequency can be returned in the same array, indicating how the frequency changes during different parts of the day. In this case, each Departure of type frequency will have a distinct frequency_start_time and frequency_end_time to indicate the time of day, along with the frequency_seconds_range expressing the service frequencies during that period.

frequency_start_time

string

(Included when type is frequency.)

The beginning of the period in the day in which this service has the frequency expressed by frequency_seconds_range.

frequency_end_time

string

(Included when type is frequency.)

The end of the period in the day in which this service has the frequency expressed by frequency_seconds_range.

time_status

string

Enum: "unknown" "on_time" "delay" "cancellation"

Indicates whether or not the service is on time. This is generally only provided for services where this information is commonly provided to the rider, for instance commuter trains.

value	description
unknown	The status of this departure is unknown (also signaled by the `time_status` property being omitted).
on_time	This departure is on time.
delay	This departure is running behind schedule. In this case, the amount of delay can be determined from the difference between `live_time` and `scheduled_time`.
cancellation	This departure has been canceled and will no longer arrive.

platform_short_name

string

A short string indicating the "platform" or "track", such as 18 or A, when available. This is only used for short identifiers that would appear next to the word "Platform" or "Track"; longer platform names that can be shown on their own will be passed in direction_description on TransitLeg instead.

{"type": "live",
"service_id": "LondonBus63",
"suggested_departure": "suggested",
"headsign": "Honor Oak",
"time_name": "19:08",
"short_name": "63",
"live_time": "2020-08-13T19:06:55+01:00",
"scheduled_time": "2020-08-13T19:08:00+01:00",
"time_status": "on_time"
}

Error Response

message

string

A developer-readable message explaining the problem. Must not be displayed to the end user.

error_code

string

A string code that can be used for triggering error handling code paths. Only present in responses with non-200 HTTP code. Note new values may be added at any time.

value	description
no-results	The request was in Citymapper's coverage regions, but no results were found.
coverage-region	The request is outside of Citymapper's coverage regions, or spans disconnected regions.
coverage-start	The request's `start` location falls outside of Citymapper's coverage regions.
coverage-end	The request's `end` location falls outside of Citymapper's coverage regions.
coverage-distance	The request's `start` and `end` locations are further apart than the maximum allowed for this API.
signature	A signature included in the request is invalid for use with this API.
unknown-brand	The request references an unknown Brand ID.
unknown-scenario	The request references an unknown Scenario ID.
request-format	The request was semantically malformed. The `message` field may contain additional details.
configuration-required	The request can't be completed because of missing configuration. The `message` should give details.
deprecated	The request was made to a deprecated API.

{"message": "'start' parameter not present",
"error_code": "request-format"
}

Instruction

path_index required	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_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_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_text	string Plain-text description of the Instruction to the user.
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.
	Array of objects
type	string Enum: "depart" "turn" "enter_roundabout" "exit_roundabout" "arrive" Indicates the type of Instruction. NOTE: New values may be added to this list at any time.
type_direction	string Enum: "straight" "uturn" "left" "slight_left" "sharp_left" "right" "slight_right" "sharp_right" Indicates a direction that modifies this Instruction. NOTE: New values may be added to this list at any time.

{"path_index": 0,
"distance_meters": 221,
"time_seconds": 64,
"description_text": "Turn left onto Hatfields",
"description_format": "Turn left onto {key_1}",
"description_format_replacements": [{"key": "key_1",
"type": "street_name",
"text": "Hatfields",
"language": "en-GB"
}
],
"type": "turn",
"type_direction": "left"
}

Leg

travel_mode

required

string

Identifies the kind of travel described by this leg. New options are likely to be added over time. This value indicates which other fields are likely to be populated in the Leg.

value	description
walk	Walking
transit	Public transportation with fixed routes & stops such as bus, metro, train, ferry
self_piloted	Vehicles such as e-scooters, bicycles, motor scooters, private automobiles that the user pilots themselves
on_demand	Services such as rideshare, cab, demand-responsive transit services where the path, pickup and dropoff points are determined by the user rather than fully pre-determined

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

required

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

Array of objects (Instruction)

(May be included when travel_mode is walk or self_piloted.)

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.

vehicle_types

Array of strings (Vehicle Type)

Items Enum: "bike" "bus" "bus_rapid_transit" "car" "ebike" "escooter" "ferry" "funicular" "gondola" "helicopter" "light_rail" "metro" "monorail" "motorscooter" "rail" "subway" "streetcar" "tram" "trolley" "trolleybus"

This is a priority list of vehicle types that can be used to describe the vehicle used in this leg. The list is ordered from more specific to less specific vehicle type, to allow for refinements to the list of types to be added over time, and to allow consumers of the API to make more generic distinctions if desired. In the case that this Leg has Services specified, this value will contain the intersection of values given in the individual Services' vehicle_types fields.

This property is omitted when no vehicle is involved, such as when travel_mode is walk.

Array of objects (Path Annotation)

Array of Path Annotations providing extra metadata about sections of the path. For instance, in Legs with travel_mode of self_piloted, these annotations can indicate sections of the path where the user should dismount their vehicle and walk alongside it due to terrain or restrictions.

Each Path Annotation specifies a start_index and end_index, which are indices into the series of coordinates encoded by path. (For example, an index of 1 refers to the coordinate (51.51341, -0.08896) in the path example above.)

path_annotations will contain annotations in order of increasing start_index, and will not contain overlapped ranges (though multiple annotations can refer to the same coordinate).

Array of objects (Service)

Indicates the services that can be used to complete this Leg. This field is omitted when the concept is not relevant, for instance when travel_mode is walk or self_piloted (in non-branded results). When more than one service is listed, that means that alternate equivalent services are available (for instance, two buses or trains that travel between the same set of stops).

object (SelfPilotedLegUpdatableDetail)

This object contains elements that can be updated using /api/1/live/routeupdates calls, to provide the latest departure information. When receiving updates, the previous Leg Updatable Detail for each Leg can be replaced with the new one.

Example

{"travel_mode": "self_piloted",
"duration_seconds": 622,
"path": "_flyHbjPDZBTBNDJ",
"instructions": [{"path_index": 0,
"distance_meters": 221,
"time_seconds": 64,
"description_text": "Turn left onto Hatfields",
"description_format": "Turn left onto {key_1}",
"description_format_replacements": [{"key": "key_1",
"type": "street_name",
"text": "Hatfields",
"language": "en-GB"
}
],
"type": "turn",
"type_direction": "left"
}
],
"vehicle_types": ["escooter"
],
"path_annotations": [{"start_index": 1,
"end_index": 3,
"should_walk": true
}
],
"services": [{"id": "E",
"name": "E",
"vehicle_types": ["escooter"
],
"brand": {"id": "NewYorkSubway",
"name": "Subway",
"images": [{"url": "string",
"ui_role": "pin",
"width": 0,
"height": 0,
"pixel_ratio": 2,
"format": "png",
"is_generic": false,
"has_space_for_text": false,
"is_dropoff_place": false,
"low_capacity": false
}
]
},
"images": [{"url": "string",
"ui_role": "service",
"width": 0,
"height": 0,
"pixel_ratio": 2,
"format": "png",
"replaces_name": false
}
],
"color": "#2850AD",
"background_color": "#2850AD",
"text_color": "#FFFFFF",
"third_party_app": {"name": "string",
"images": [{"url": "string",
"ui_role": "icon",
"width": 0,
"height": 0,
"pixel_ratio": 2,
"format": "png"
}
],
"branding_color": "string",
"branding_text_color": "string",
"open_or_install_deep_link": "string",
"android_open_or_install_deep_link": "string",
"ios_open_or_install_deep_link": "string",
"android_app_id": "string",
"ios_app_id": "string"
}
}
],
"updatable_detail": {"leg_departure_time": "string",
"leg_arrival_time": "string",
"vehicle_pickup_places": [{ }
],
"vehicle_dropoff_places": [{"coordinates": {"lat": 51.524247,
"lon": -0.10641
},
"hire_vehicle_station": {"hire_vehicle_station_id": "string",
"name": "string",
"service_id": "string",
"num_vehicles_available": 0,
"num_docks_available": 0
},
"suggested": true
}
]
}
}

Leg Updatable Detail

One of

leg_departure_time

string

The time at which Citymapper thinks the user will set out on this leg, given available departure information. In the case of Legs of travel_type transit, this excludes waiting time.

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.

leg_arrival_time

string

The time at which Citymapper thinks the user will arrive at the end of this leg, given available departure information and expected travel speed.

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.

expected_wait_before_boarding_seconds

integer

Where available, the estimated duration a rider will spend between arriving at the platform, stop, or boarding area and being able to board the service. Typically set in cases of crowding where passenger flow is restricted.

Where departure times are known, the rider is expected to be able to board the next departure after the rider reaches the platform plus the expected wait duration.

For frequency-based services, this can be used as the expected wait time.

Array of objects (Departure)

An array of Departure objects, giving alternate departures for the services in the Legs in which this property appears. The array can contain a mixture of different Departure types—for example, it's common to receive live information for the next few departures, followed by scheduled information. For legs with multiple alternate Services, this array is likely to contain a mixture of departures corresponding to the different alternate services.

The number of Departures returned will depend on the availability of information.

live_departure_availability

string

Enum: "unknown" "none_available" "included" "additional_request"

This indicates the availability of live departure information for the Services used in this Leg. Live departure information is not available for all transit services, and some transit services have live information that cannot be determined quickly enough to be included in all requests. The value of this property characterizes the contents of the departures array in this Leg Updatable Detail, and indicates whether an additional request is likely to yield additional live times for this Leg.

value	description
unknown	The availability of live departure information can't be determined
none_available	No live departure information is available for the services used in this leg. Typically the `departures` list will contain entries of type `scheduled` or `frequency` in this case
included	Live departure information is available for the services in this Leg, and it is included in the `departures` list
additional_request	Live information is available for the services in this Leg, but some of it will require an additional `/api/1/live/routeupdate` request to retrieve

Array of objects (Status)

An array of Status objects that relate to this Leg.

Example

{"leg_departure_time": "string",
"leg_arrival_time": "string",
"expected_wait_before_boarding_seconds": 0,
"departures": [{"type": "live",
"service_id": "LondonBus63",
"suggested_departure": "suggested",
"headsign": "Honor Oak",
"time_name": "19:08",
"short_name": "63",
"live_time": "2020-08-13T19:06:55+01:00",
"scheduled_time": "2020-08-13T19:08:00+01:00",
"time_status": "on_time"
}
],
"live_departure_availability": "unknown",
"statuses": [{"type": "travel_affected",
"title": "Service Alert",
"description": "About 90% of our regular weekday trains are running. While we're running on the Essential Schedule,\noff peak fares remain in effect on all LIRR trains, including trains operating in traditional peak/rush\nhour time periods. To minimize contact with crew members, use MTA eTix on smartphones and activate eTix\njust before boarding. Ticket machines are available at most stations for cash &amp; credit card purchases.\nRemember: If you're using MTA services, you must wear a face covering (mask/bandana/scarf) at the station\nand for the entire duration of your train ride.\n",
"service_ids": ["LIRRBabylon",
"LIRRLongBeach",
"LIRRPortJefferson",
"LIRRRonkonkoma"
]
}
]
}

On-Demand Service Estimate

required

object (Service)

A service describes a transportation offering such as a specific numbered or named bus or train line.

estimate_accuracy

required

string

Enum: "live" "representative"

The accuracy of this estimate. If the value is representitive, then a live estimate from the provider may be available with an additional /api/1/live/routeupdates request (see live_service_estimate_availibility in the parent object)

value	description
representative	Any pickup duration estimate and price is indicative of the typical values for this service
live	This estimate comes from the provider's API and is likely to be based on live vehicle positions
service_not_available	This service is not currently available to book - e.g. if this is a cab service, there may be no vehicles nearby

pickup_eta_seconds

integer

An estimate of the time it will take for a vehicle to arrive at the pickup location if this service is booked now. estimate_accuracy indicates the source of this data.

object (Price)

Represents a monetary amount. This may either be

An exact amount, represented by amount. Formatted as e.g. "£1.50"
A range of values between amount_range_minimum and amount_range_maximum. Formatted as e.g. "£18-22"
A minimum price where the maximum is not known, represented by amount_range_minimum but no amount_range_maximum. Formatted as e.g. "£18+"

external_booking_deep_link

string

A URL which can be launched to book this service in an external app, pre-populating the A-B of this Leg where possible. Depending on the service, this URL may be:

A HTTPS link which will either open the installed app for this service, or forward to the relevant platform's app store if the app is not installed
An app scheme link which will deep-link into the app directly

Since the latter may fail if the relevant app is not installed, the implementor must use the platform-specific mechanism for catching this failure. In this case, the information from the Service's third_party_app can be used to display the service's app in the relevant app store for the platform.

android_external_booking_deep_link

string

A URL which can be launched to book this service in an external app, pre-populating the A-B of this Leg where possible, specific to the Android platform.

When present, this should be preferred over external_booking_deep_link when running on Android devices.

ios_external_booking_deep_link

string

A URL which can be launched to book this service in an external app, pre-populating the A-B of this Leg where possible, specific to Apple platforms.

When present, this should be preferred over external_booking_deep_link when running on iOS devices.

suggested

boolean

When true, indicates that this service's estimate is the one used as the source of duration and pricing information when calculating the overall cost and travel time for this Route

{"service": {"id": "E",
"name": "E",
"vehicle_types": ["escooter"
],
"brand": {"id": "NewYorkSubway",
"name": "Subway",
"images": [{"url": "string",
"ui_role": "pin",
"width": 0,
"height": 0,
"pixel_ratio": 2,
"format": "png",
"is_generic": false,
"has_space_for_text": false,
"is_dropoff_place": false,
"low_capacity": false
}
]
},
"images": [{"url": "string",
"ui_role": "service",
"width": 0,
"height": 0,
"pixel_ratio": 2,
"format": "png",
"replaces_name": false
}
],
"color": "#2850AD",
"background_color": "#2850AD",
"text_color": "#FFFFFF",
"third_party_app": {"name": "string",
"images": [{"url": "string",
"ui_role": "icon",
"width": 0,
"height": 0,
"pixel_ratio": 2,
"format": "png"
}
],
"branding_color": "string",
"branding_text_color": "string",
"open_or_install_deep_link": "string",
"android_open_or_install_deep_link": "string",
"ios_open_or_install_deep_link": "string",
"android_app_id": "string",
"ios_app_id": "string"
}
},
"estimate_accuracy": "live",
"pickup_eta_seconds": 0,
"price": {"formatted": "£1.50",
"amount": "1.50",
"amount_range_minimum": "1.50",
"amount_range_maximum": "3.50",
"currency": "GBP",
"demand_multipler": 1.2
},
"external_booking_deep_link": "string",
"android_external_booking_deep_link": "string",
"ios_external_booking_deep_link": "string",
"suggested": true
}

Path Annotation

start_index required	integer The start index of the coordinate range, as a 0-based index into the list of coordinates encoded by the `path` of a Leg.
end_index required	integer The end index of the coordinate range, as a 0-based index into the list of coordinates encoded by the `path` of a Leg. `end_index` must be greater than or equal to `start_index`. If `end_index` = `start_index`, this refers to a single coordinate in the path.
should_walk	boolean If present and `true`, this Path Annotation refers to a section of the path where the user should dismount and walk alongside their vehicle. This only relevant in the case of Legs where `travel_mode` is `self_piloted`.

{"start_index": 1,
"end_index": 3,
"should_walk": true
}

Price

formatted required	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	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	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	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	string The currency in which the price is given, in three-letter ISO 4217 form.
demand_multipler	number <double> 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

{"formatted": "£1.50",
"amount": "1.50",
"amount_range_minimum": "1.50",
"amount_range_maximum": "3.50",
"currency": "GBP",
"demand_multipler": 1.2
}

Route

required

object (Waypoint)

required

object (Waypoint)

distance_meters

integer

The overall distance of the entire Route, in meters.

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

string (Duration Accuracy)

Default: "scheduled"

Enum: "estimated" "scheduled" "live"

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.

object

The price to take the Route. Omitted when not available. Generally available only on transit Routes. The price is computed assuming no special passes, with the user paying with cash or the most common fare instrument.

emissions_grams_co2e

number <float>

An estimate of the greenhouse gas emissions of the route, expressed in grams of carbon dioxide equivalent (CO2e).

required

Array of objects (Leg) non-empty

Array of Legs comprising the Route, in the order in which they should be traversed. Every valid Route will have at least one.

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 /api/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.

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 /api/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.

object (Route Metadata)

Any metadata associated with the Route.

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

required

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 /api/1/live/routeupdates). It must be treated as an opaque value.

requested_time

string

Contains the time parameter used as a departure or arrival time constraint when getting directions, if applicable.

requested_time_type

string

Enum: "arrive" "depart" "depart_approximate"

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 thetime_type` used by default to plan the Route.

{"start": {"coordinates": {"lat": 51.524247,
"lon": -0.10641
}
},
"end": {"coordinates": {"lat": 51.524247,
"lon": -0.10641
}
},
"distance_meters": 562,
"duration_seconds": 1139,
"duration_accuracy": "scheduled",
"price": {"formatted": "£1.50",
"amount": "1.50",
"amount_range_minimum": "1.50",
"amount_range_maximum": "3.50",
"currency": "GBP",
"demand_multipler": 1.2
},
"emissions_grams_co2e": 8.2,
"legs": [{"travel_mode": "self_piloted",
"duration_seconds": 622,
"path": "_flyHbjPDZBTBNDJ",
"instructions": [{"path_index": 0,
"distance_meters": 221,
"time_seconds": 64,
"description_text": "Turn left onto Hatfields",
"description_format": "Turn left onto {key_1}",
"description_format_replacements": [{"key": "key_1",
"type": "street_name",
"text": "Hatfields",
"language": "en-GB"
}
],
"type": "turn",
"type_direction": "left"
}
]
}
],
"route_departure_time": "string",
"route_arrival_time": "string",
"route_metadata": {"groups": [{"group_id": "transit",
"group_name": "Transit",
"route_position": 0
}
],
"profile_name": "Hauptstraßen"
},
"profile": "string",
"signature": "v2.eJyNUl2P0zAQ/CuRX0mOtWMncR9B3IdAgFQQD6dTZOKlyjVnF9vhkKL+d+ykRaEPJyQ/2Lvj2ZnRTqRTjmwyxkSdZ0SPToXemlihpYBYQaPjYyJKa4fexzuhBctuVfjR46B9nn2wRluTbd/RTH6+ybOv70n811nr9AwX9EpALaq8gCsKdQ1l6hv1hP9HdozoR9f2RuPv+COJGnCXqO8nonsflOkSFZMXDhhLBezOIhiHkwjJkoQnq2cJz2rYp7dfITldkFVZJQHTmrem8m8whEsAWsqSb9eUwSnj+5BKzo4B237O4p4s/t6MvirJQ5oZlAtnHuCM1jOPD/bQdnY0qdcsAlZOK3nhlJb/OI1xy1Pc4mWn0LCTU84ackySDq7vsD3gMovOW+Bwt0wi474YZg9nb73ZtQ5/juhDdJkgDWje8AqK70qLgoOoCykoFoyXkgvAqqkbsvI+XSxLSr8+xy/peltKlr0d0O3RPOMwxLv1mGfXyrkoI4lKyxL6BcyAQQFNQdkXKjfxMPYK6Abg9cdP3+62t4n4Fzp/yvD4B94v0po=",
"requested_time": "2020-08-19T08:10:42-04:00",
"requested_time_type": "depart_approximate"
}

Route Metadata

	Array of objects (Route Group)
profile_name	string Human-readable localized name of the `profile` identifier. For example, if a response has `"language": "de-DE"`, `profile` in a walk Route object may be `"main_roads"` and this localized `profile_name` will be `"Hauptstraßen"`.

{"groups": [{"group_id": "transit",
"group_name": "Transit",
"route_position": 0
}
],
"profile_name": "Hauptstraßen"
}

Service

id required	string The identifier for the service
name required	string A string that can be displayed to the user to describe this service
vehicle_types	Array of strings (Vehicle Type) Items Enum: "bike" "bus" "bus_rapid_transit" "car" "ebike" "escooter" "ferry" "funicular" "gondola" "helicopter" "light_rail" "metro" "monorail" "motorscooter" "rail" "subway" "streetcar" "tram" "trolley" "trolleybus" This is a priority list of vehicle types that can be used to describe the vehicle used by this Service. The list is ordered from more specific to less specific vehicle type, to allow for refinements to the list of types to be added over time, and to allow consumers of the API to make more generic distinctions if desired.
	object Provides the branding attached to the service. The main purpose of Brand is to determine which specific imagery to show for the service, particularly in the case where the Service doesn't have distinct `images` of its own.
	Array of objects (ServiceImage) A list of `Image`s that can be used to represent this `Service` in a user interface. API consumers should use the first `Image` in the list that meets their criteria. Images given here will have a `ui_role` of `service`, as they are identifying the specific `Service` rather than the general `Brand`. If no suitable `Image` is provided here, one of the images in the adjacent `brand` should be used.
color	string The basic color associated with this service, for graphical uses such as map lines. The color is encoded as a capitalized hexadecimal RGB value starting with `#`. For instance, `#2850AD` encodes the 24-bit RGB value of (40, 80, 173).
background_color	string A background color for use with this service, in cases where text will be shown on a colored background. Used in conjunction with `text_color`. The color is encoded as a capitalized hexadecimal RGB value starting with `#`. For instance, `#2850AD` encodes the 24-bit RGB value of (40, 80, 173).
text_color	string A text color for use with this service, in cases where text will be shown on a colored background. Used in conjunction with `background_color`. If omitted, it means that white (`#FFFFFF`) has sufficient contrast against the given `background_color` or `color` values. The color is encoded as a capitalized hexadecimal RGB value starting with `#`. For instance, `#2850AD` encodes the 24-bit RGB value of (40, 80, 173).
	object (Third Party Application) An app associated with a `Service` which, depending on the type of service, can be used to make bookings or unlock vehicles. These are usually associated with on-demand (cabs or taxis) and other private-hire vehicle services.

{"id": "E",
"name": "E",
"vehicle_types": ["escooter"
],
"brand": {"id": "NewYorkSubway",
"name": "Subway",
"images": [{"url": "string",
"ui_role": "pin",
"width": 0,
"height": 0,
"pixel_ratio": 2,
"format": "png",
"is_generic": false,
"has_space_for_text": false,
"is_dropoff_place": false,
"low_capacity": false
}
]
},
"images": [{"url": "string",
"ui_role": "service",
"width": 0,
"height": 0,
"pixel_ratio": 2,
"format": "png",
"replaces_name": false
}
],
"color": "#2850AD",
"background_color": "#2850AD",
"text_color": "#FFFFFF",
"third_party_app": {"name": "string",
"images": [{"url": "string",
"ui_role": "icon",
"width": 0,
"height": 0,
"pixel_ratio": 2,
"format": "png"
}
],
"branding_color": "string",
"branding_text_color": "string",
"open_or_install_deep_link": "string",
"android_open_or_install_deep_link": "string",
"ios_open_or_install_deep_link": "string",
"android_app_id": "string",
"ios_app_id": "string"
}
}

ServiceImage

url required	string The URL from which this `Image` can be retrieved. The image will be encoded in PNG format unless the `format` field indicates otherwise.
ui_role required	string Enum: "service" "vehicle" Indicates the role that this image plays in a user interface. New values may be added at any time. See the parent object in the response for valid values in this context.
width	number The width of the image in screen units. This corresponds to `px` in CSS, "points" on iOS, and "density-independent pixels" on Android.
height	number The height of the image in screen units. This corresponds to `px` in CSS, "points" on iOS, and "density-independent pixels" on Android.
pixel_ratio	number Default: 2 Indicates the ratio of image pixels to screen units. When not provided, `2` should be assumed. For instance, an `Image` with a `width` of `38`, `height` of `41`, and `pixel_ratio` of `2` has image pixel dimensions of 76 x 82.
format	string Default: "png" Value: "png" Indicates the file format of the image. The default value is `png`, indicating Portable Network Graphics bitmap format. At time of writing, all `Images` returned are in `png` format, and therefore this field will usually be omitted. However, in the future, additional `format` types may be provided in responses.
replaces_name	boolean Default: false Generally only applies to `Image`s with `ui_role` of `service`. When present and `true`, this indicates that this image can be displayed instead of the `Service`'s `name`, as the image contains enough information to identify the service unambiguously. This is often the case with metro services, where the image would depict the number or color of the metro line, and displaying both the image and the name could appear redundant.

{"url": "string",
"ui_role": "service",
"width": 0,
"height": 0,
"pixel_ratio": 2,
"format": "png",
"replaces_name": false
}

Station Exit

id required	string Identifies this station exit. This is an internal identifier and must not be shown to the rider.
stop_id required	string Identifies the station that this exit gives access to. When used in a walk Leg, this value will match a Stop `id` value in an adjoining transit Leg. This is an internal identifier and must not be shown to the rider.
required	object The geographical location of this exit.
name	string A rider-facing longer descriptive name for this exit. Depending on the station signage, an exit may have any combination of `name` and `short_name` (or neither).
short_name	string A rider-facing short code identifying this exit, usually a few numbers and/or letters. Depending on the station signage, an exit may have any combination of `name` and `short_name` (or neither).

{"id": "string",
"stop_id": "string",
"coordinates": {"lat": 51.524247,
"lon": -0.10641
},
"name": "Buses/Dalston Square",
"short_name": "2A"
}

Station Walk Details

	object Provides information about the station entrance/exit that the rider passes through as part of this walk.
	Array of objects (Station Exit) Provides information about the other station entrances/exits for contextual display.
duration_seconds	integer Indicates how much of the walking time in this Leg occurs inside of the station between the recommended entrance/exit and the platform. When omitted, this indicates that no information about the duration of the in-station portion of the walk is available. To determine the amount of walking time that occurs outside of the station, subtract this value from the Leg's overall `duration_seconds`. (The value is encoded this way so that API consumers that don't want to display this level of detail can simply display the Leg's `duration_seconds`.)

{"recommended_exit": {"id": "string",
"stop_id": "string",
"coordinates": {"lat": 51.524247,
"lon": -0.10641
},
"name": "Buses/Dalston Square",
"short_name": "2A"
},
"alternate_exits": [{"id": "string",
"stop_id": "string",
"coordinates": {"lat": 51.524247,
"lon": -0.10641
},
"name": "Buses/Dalston Square",
"short_name": "2A"
}
],
"duration_seconds": 0
}

Status

type

required

string

Enum: "unknown" "no_issues" "travel_affected" "travel_prevented"

Indicates the type/level/severity expressed by this Status. This can be used to choose icons, and determine whether to show different Status entries.

value	description
unknown	The type/severity of this status couldn't be determined. Should be rare. May still populate `title` and `description`.
no_issues	No known issues that would affect travel over the specified services and/or stops. May still populate `title` and `description`.
travel_affected	Travel over the specified services and/or stops may be delayed or otherwise affected.
travel_prevented	Travel over the specified services and/or stops may not be possible.

title

string

A relatively short title for the Status.

description

string

An in-depth description of the Status. This will be provided as plain text.

service_ids

Array of strings

If this Status relates to Services rather than Stops, this will contain the id of one or more Services. The ability to specify multiple services is intended to prevent needless duplication of Status reporting.

stop_ids

Array of strings

If this Status relates to specific stops (as opposed to Services, or sections of Services running between specific stops), this will contain the id of one or more relevant Stops.

Example: A Status might use this to identify specific metro Stops where riders can't board or alight because they're closed, even though trains are passing through them.

Array of objects

If this Status relates to sections of Services between different Stops, this will indicate which sections, in combination with service_ids. This field relates to services traveling between Stops, rather than whether or not the Stops are open or closed (which is represented by stop_ids).

Example: A Status might use this to indicate that a particular train isn't running between a set of Stops, even if those Stops remain open for other services.

{"type": "travel_affected",
"title": "Service Alert",
"description": "About 90% of our regular weekday trains are running. While we're running on the Essential Schedule,\noff peak fares remain in effect on all LIRR trains, including trains operating in traditional peak/rush\nhour time periods. To minimize contact with crew members, use MTA eTix on smartphones and activate eTix\njust before boarding. Ticket machines are available at most stations for cash &amp; credit card purchases.\nRemember: If you're using MTA services, you must wear a face covering (mask/bandana/scarf) at the station\nand for the entire duration of your train ride.\n",
"service_ids": ["LIRRBabylon",
"LIRRLongBeach",
"LIRRPortJefferson",
"LIRRRonkonkoma"
]
}

Stop

id required	string An internal identifier used to refer to this stop.
name required	string The user-facing name of the stop.
required	object (Coordinates)
indicator_text	string Some transit systems (particularly in the UK) have 2-4 letter codes displayed prominently on bus stop poles to distinguish between nearby stops. When relevant, such "indicators" are provided in this field to allow them to be rendered into stop icons.
code	string A short text or number that identifies the stop for the rider. These codes are often used by other transit information systems and/or printed on signs to make it easier to get information about a specific stop. Where as the indicator text will just identify the stop from other nearby stops, the stop code will uniquely identify the stop for the entire service and will match up with the stop codes used on other information systems.

{"id": "Subway8Av14St",
"name": "8 Av - 14 St",
"coordinates": {"lat": 51.524247,
"lon": -0.10641
},
"indicator_text": "AF",
"code": "032A05"
}

Third-Party App

name required	string The user-facing name of the app
	Array of objects (ThirdPartyAppImage) A list of `Image`s that can be used to represent this app in a user interface. API consumers should use the first `Image` in the list that meets their criteria.
branding_color	string The main brand color associated with this application. May be different to any color associated with an attached `Service`. The color is encoded as a capitalized hexadecimal RGB value starting with `#`. For instance, `#2850AD` encodes the 24-bit RGB value of (40, 80, 173).
branding_text_color	string A color suitable for text which is displayed over `branding_color`. The color is encoded as a capitalized hexadecimal RGB value starting with `#`. For instance, `#2850AD` encodes the 24-bit RGB value of (40, 80, 173).
open_or_install_deep_link	string A deep link URL to the home page of the application. This URL may be: A HTTPS link which will either open the installed app for this service, or forward to the relevant platform's app store if the app is not installed An app scheme link which will deep-link into the app directly Since the latter may fail if the relevant app is not installed, the implementor must use the platform-specific mechanism for catching this failure. In this case, the `android_app_id` or `ios_app_id` can be used to show the service's app in the relevant app store for the platform. Launching this deep link should always be attempted before launching the platform's app store directly, even if it has been previously determined that the app is not installed.
android_open_or_install_deep_link	string A deep link URL to the home page of the application, specific to the Android platform. When present, this should be preferred over `open_or_install_deep_link` when running on Android devices.
ios_open_or_install_deep_link	string A deep link URL to the home page of the application, specific to Apple platforms. When present, this should be preferred over `open_or_install_deep_link` when running on iOS devices.
android_app_id	string The ID (package name) of the application in the Google Play store. This may be used to open the relevant app install page if opening the deep link fails due to the app not being present on the device.
ios_app_id	string The ID of the application in the App Store. This may be used to open the relevant app install page if opening the deep link fails due to the app not being present on the device.

{"name": "string",
"images": [{"url": "string",
"ui_role": "icon",
"width": 0,
"height": 0,
"pixel_ratio": 2,
"format": "png"
}
],
"branding_color": "string",
"branding_text_color": "string",
"open_or_install_deep_link": "string",
"android_open_or_install_deep_link": "string",
"ios_open_or_install_deep_link": "string",
"android_app_id": "string",
"ios_app_id": "string"
}

Third-Party App Image

url required	string The URL from which this `Image` can be retrieved. The image will be encoded in PNG format unless the `format` field indicates otherwise.
ui_role required	string Value: "icon" Indicates the role that this image plays in a user interface. New values may be added at any time. See the parent object in the response for valid values in this context.
width	number The width of the image in screen units. This corresponds to `px` in CSS, "points" on iOS, and "density-independent pixels" on Android.
height	number The height of the image in screen units. This corresponds to `px` in CSS, "points" on iOS, and "density-independent pixels" on Android.
pixel_ratio	number Default: 2 Indicates the ratio of image pixels to screen units. When not provided, `2` should be assumed. For instance, an `Image` with a `width` of `38`, `height` of `41`, and `pixel_ratio` of `2` has image pixel dimensions of 76 x 82.
format	string Default: "png" Value: "png" Indicates the file format of the image. The default value is `png`, indicating Portable Network Graphics bitmap format. At time of writing, all `Images` returned are in `png` format, and therefore this field will usually be omitted. However, in the future, additional `format` types may be provided in responses.

{"url": "string",
"ui_role": "icon",
"width": 0,
"height": 0,
"pixel_ratio": 2,
"format": "png"
}

Vehicle Type

string (Vehicle Type)

Enum: "bike" "bus" "bus_rapid_transit" "car" "ebike" "escooter" "ferry" "funicular" "gondola" "helicopter" "light_rail" "metro" "monorail" "motorscooter" "rail" "subway" "streetcar" "tram" "trolley" "trolleybus"

This is an enumeration of a possible vehicle types used in Legs. This is generally used in a list of multiple Vehicle Type values, ordered from more specific to less specific vehicle type, to allow for refinements to the list of types to be added over time. In this way, an API client can iterate through and use the first matching vehicle type to decide how to render things.

value	description
`bike`	Generic bicycles
`bus`	Generic buses that run on streets or bus lanes
`bus_rapid_transit`	Buses with limited stops, sometimes has stations where the rider pays before boarding
`car`	A car
`ebike`	Bicycles with battery-powered assistance
`escooter`	Battery powered e-scooters that the rider stands on
`ferry`	Water-based vehicles
`funicular`	Cable-driven counterbalanced rail vehicles that travel up steep slopes
`gondola`	Vehicles that are suspended from cables
`helicopter`	Helicopter transportation services
`light_rail`	A regional variation of `tram`, less likely to run on streets
`metro`	Urban rail vehicles that generally run underground at high service frequencies
`monorail`	Vehicles that travel on a single rail
`motorscooter`	Seated scooters
`rail`	Generic rail-based vehicles (generally this is a fallback for more specific Vehicle Types)
`subway`	A regional variation of `metro`
`streetcar`	A regional variation of `tram`
`tram`	Rail vehicles that generally run on streets above ground, and use overhead wires
`trolley`	A regional variation of `tram`
`trolleybus`	Electric buses powered by overhead wires

"bike"

Waypoint

required

object (Coordinates)

{"coordinates": {"lat": 51.524247,
"lon": -0.10641
}
}

Citymapper API (v1.8.3)

Introduction

Add journey planning and turn-by-turn navigation to your products with our APIs.

Other resources

Support

Have questions?

Have product feedback or suggestions?

Have a sales question?

Pricing

Enterprise plans to help you grow

Terms of service

Requests

Authentication

API Key

Directions API Calls

Travel times between two locations

Authorizations:

query Parameters

Responses

Response samples

E-scooter directions between two points (ride only)

Authorizations:

query Parameters

Responses

Response samples

E-scooter directions between two points (hire vehicles)

Authorizations:

query Parameters

Responses

Response samples

Bike directions between two points (ride only)

Authorizations:

query Parameters

Responses

Response samples

Bike directions between two points (hire vehicles)

Authorizations:

query Parameters

Responses

Response samples

Motor scooter directions between two points (ride only)

Authorizations:

query Parameters

Responses

Response samples

Motor scooter directions between two points (hire vehicles)

Authorizations:

query Parameters

Responses

Response samples

Taxi directions between two points

Authorizations:

query Parameters

Responses

Response samples

Walking directions between two points

Authorizations:

query Parameters

Responses

Response samples

Car directions between two points (ride only)

Authorizations:

query Parameters

Responses

Response samples

Transit directions between two points

Authorizations:

query Parameters

Responses

Response samples

Scenario based directions between two points

Authorizations:

query Parameters

Responses

Response samples

Live departure and availability information for multiple Routes at once

Authorizations:

Request Body schema: application/json

Responses

Request samples