Skip to Content
Citymapper API

Citymapper API (v1.6.0)

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.

Ready to start?

Get Access →

 

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

Get started for free

Get 5,000 monthly requests for free across all our products, making it easy to start building with our API or SDK.

 

Pay as you go

Ready to launch? Scale quickly and flexibly with our pay-as-you-go plan.

Pick the products you need and only get charged for what you use – plus enjoy £100 free credit allowance from us each month.

To switch to the pay-as-you-go plan, please visit the enterprise dashboard and add a payment method. It’s that simple.

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

* Up to 5 transit routes can be returned in a single result

** One update applies to a single transit route. Updates are refreshed every minute

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

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

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

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

Content type
application/json
{
  • "routes": [
    ]
}

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 sc