Skip to Content
Citymapper API

Citymapper API (v1.8.3)

Download OpenAPI specification:Download

Introduction

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

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 routes1 Available on Enterprise plans only
Taxi Directions: Real-Time Updates per 1000 route updates1 Available on Enterprise plans only
Transit Directions per 1000 routes2 £1.20
Transit Directions: Real-Time Updates per 1000 route updates3 Available on Enterprise plans only
Hire Vehicle Directions per 1000 results Available on Enterprise plans only

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

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

3 : 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:
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

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