• Help
• Journey Planner
• How it works
• OSM
• Developers
• API
• Photomap
• Photo licensing

CycleStreets API (v2)

• Details for:

  * Introduction * Overview & how to specify the API key Cycle routing - plan new journey Cycle routing - retrieve Cycle routing - plan leisure (circular) route Journeys of user Isochrones - show Nearest point Batch routes matrix - create job Batch routes matrix - control job Batch routes matrix - job data Batch routes matrix - delete job Geocoder Photomap locations Photomap location Photomap categories Add photo Update photo Like photo Photo of the day Photomap tags Points of Interest (POIs) Points of Interest (POIs) - types Collisions data Collision report Collisions metadata Traffic counts data Popup cycleways - locations being implemented Popup cycleways - suggested LTNs: Modal filters LTNs: Streets LTN statistics Infrastructure locations Infrastructure location Infrastructure schema GPS tracks - add List galleries Retrieve a specified gallery Create a gallery Update a gallery User authenticate User create Map downloads Status API testing - multiple API testing - run one API testing - list of tests Add feedback API V1 documentation (deprecated)
• 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

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

POST https://api.cyclestreets.net/v2/batchroutes.createjob?key=...
(
	[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] => webmaster@example.com
	[autostart] => 1
	[username] => myusername
	[password] => mypassword
)

Result:

{
    "id": 69158,
    "status": "open",
    "statusUrl": "https://api.cyclestreets.net/v2/batchroutes.jobdata?key=..."
}

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.

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

Response

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