Donate using PayPal

CycleStreets API (v2)

  • Details for:
  • API overview
  • Obtain API key
  • Usage policy
  • Uptime policy

Batch routes matrix - create job

This API call creates a batch matrix job, setting the parameters for a job which can then be started/controlled.

It is the API equivalent to the batch routing system UI.

When a job has been successfully created, it can then be controlled, e.g. started and stopped, using the batchroutes.controljob API call.

When you have planned a job and retrieved its data, you are expected to delete it using the batchroutes.deletejob API call. Any jobs left on the system three months after creation are subject to deletion without notice.


Example which creates a batch job to plan a matrix of routes between a set of specified points, in both directions.

	[name] => Journey matrix for Cambridge
	[serverId] => 1
	[geometry] => {"type": "FeatureCollection", "features": [
		{"type": "Feature", "id": 1,   "properties": {}, "geometry": {"type": "Point", "coordinates": [0.14187, 52.20303]}},
		{"type": "Feature", "id": "a", "properties": {}, "geometry": {"type": "Point", "coordinates": [0.14711, 52.20061]}},
		{"type": "Feature", "id": 56,  "properties": {}, "geometry": {"type": "Point", "coordinates": [0.11638, 52.20360]}},
	[strategies] => fastest,quietest
	[bothDirections] => 1
	[minDistance] => 50
	[maxDistance] => 5000
	[filename] => cambridge
	[includeJsonOutput] => 1
	[emailOnCompletion] =>
	[autostart] => 1
	[username] => myusername
	[password] => mypassword


    "id": 69158,
    "status": "open",
    "statusUrl": ""

Request parameters - required

name string
A descriptive name for the job.
serverId int
Server ID. Use 1 unless you have been informed otherwise.
geometry string

GeoJSON string, containing either:

  1. A list of known points (e.g. bike docks), as GeoJSON Points, with IDs*; or
  2. Pre-defined A-B O/D pair combinations, as GeoJSON LineStrings, with IDs*; or
  3. A polygon area, as GeoJSON Polygons, which will be converted automatically into a set of boxes based on the resolution you set below.

* For (1) and (2), there must be an 'id' property for each feature, either in the properties or at the top level; if both present, top-level will dominate.

The maximum permitted size of the data is 64MB. To avoid unnecessarily bulky data, we recommend you ensure that there are no extraneous properties being submitted and that you trim co-ordinates to 5 decimal places, which gives ~1m resolution.

strategies string, comma-separated (balanced|fastest|quietest)
The route type(s) to be used.
bothDirections int (1|0)
Whether to plan in both directions, i.e. A-B as well as B-A.
filename string
Base filename string for the result files.
includeJsonOutput int (1|0)
Whether to include a column in the resulting CSV data giving the full JSON output from the API, rather than just summary information like distance and time.
username string
Your CycleStreets account username. In due course this will be replaced with an OAuth token.
password string
Your CycleStreets account password.

Request parameters - optional

Note: The batch routing system UI provides a range of other options. These are not yet supported here, but if you particularly require one/some option(s), please do get in touch and we can expedite adding it/them.

resolution int default 100
Resolution in metres, if auto-generating boxes from an area polygon.
minDistance int
Minimum crow-fly distance in metres for each route; if a pair is below this, it will be skipped.
maxDistance int
Maximum crow-fly distance in metres for each route; if a pair is above this, it will be skipped.
successThreshold int 0-100 default 99
Percentage threshold of planned routes required for a successful job.
emailOnCompletion string
E-mail address to which completion notifications are sent, if required.
autostart int (1|0) default 1
Whether to auto-start the job, saving the need to call batchroutes.controljob


As shown in the example above, returns the job ID, and the status.

If not autostarted, the job ID can be used to start the job with batchroutes.controljob.

Error response

JSON object containing an error key and a text string.

Example error (text string will vary):

    "error": "An error occurred while creating the job."
    "error": "The submitted geometry is too large. The maximum permitted size is 64MB. The data you submitted is 66.7MB. (You may wish to check you are avoiding sending unnecessarily bulky data. We recommend you ensure that in the geometry data there are no extraneous properties being submitted and that you trim co-ordinates to 5 decimal places, which gives ~1m resolution.)"

We welcome your feedback, especially to report bugs or give us route feedback.

My comments relate to: *

Your comments: *
URL of page: *
How did you find out about CycleStreets?:
Your name:
Our ref: Please leave blank - anti-spam measure

* Items marked with an asterisk [*] are required fields and must be fully completed.