Donate using PayPal

CycleStreets API (v2)

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

GPS tracks - add

This API call enables the user to upload a GPS track which will be associated with their user account.

It was originally created to enable an organisation to undertake crowdsourced data capture of where users undertake utility cycling trips.

Currently submissions only appear in a user's profile page, but future functionality is planned.

Currently, uploaded track geometry is not modified (e.g. snapped to OSM geometry or has metadata attached) but a future option may enable this.


Example which uploads a GPS track, shown in the user's profile.


    [coords] => {"1400489389":{"a":14.66793441772461,"h":5,"l":52.20531,"n":0.14173,"r":"1400489389","s":0.6899999976158142,"v":3},"1400489392":{"a":14.95821762084961,"h":5,"l":52.2053,"n":0.14173,"r":"1400489392","s":1.289999961853027,"v":3},"1400489394":{"a":14.89309310913086,"h":5,"l":52.20526,"n":0.14171,"r":"1400489394","s":1.210000038146973,"v":3},"1400489396":{"a":15.18856430053711,"h":5,"l":52.20524,"n":0.1417,"r":"1400489396","s":0.7300000190734863,"v":3},"1400489397":{"a":15.84542465209961,"h":5,"l":52.20522,"n":0.14168,"r":"1400489397","s":1.269999980926514,"v":3}}
    [format] => atlanta
    [device] => 58FE58DE-6C3C-5357-142B-11228DC8CCAB
    [notes] => My important journey.
    [purpose] => Errand
    [start] => 1400489390
    [user] => {"age":"25-44","gender":"Male"}
    [username] => myusername
    [password] => mypa$sw0rd


    "result": true

Request parameters - required

This call requires a POST operation, as the data size could be large, and to avoid us logging user credentials in the server logs.

coords string containing JSON-encoded object
String representing the GPS track data. This will be saved as-is and also converted to a GeoJSON representation for GUI display purposes. Must be in the format specified by format below.
format string

A string specifying the format of the co-ordinate data. Formats are:

  • atlanta: JSON-encoded structure as follows:
    {"1400489389":{"a":14.66793441772461,"h":5,"l":52.20531,"n":0.14173,"r":"1400489389","s":0.6899999976158142,"v":3},"1400489392":{"a":14.95821762084961,"h":5,"l":52.2053,"n":0.14173,"r":"1400489392","s":1.289999961853027,"v":3}, … }
    The keys in this are:
    • r: Unix timestamp
    • l: Latitude
    • n: Longitude
    • a: Altitude
    • s: Speed
    • h: Horizontal accuracy
    • v: Vertical accuracy
  • geojson: A GeoJSON string containing one or more LineString features only. If other feature types are present, or the structure is wrong, an error will be returned. If there is more than one feature, adjacent features must join up (i.e. the last co-ordinate of a feature must be the same as the first co-ordinate of the next feature), so as to make a single line.
  • gpx: Not yet supported
notes string, max 255 characters
User notes about the journey. You may supply an empty string if not required by the app/user.
purpose string, max 255 characters
User summary of the purpose of the journey. Suggested values are: 'Commute', 'Errand', 'Exercise', 'School', 'Shopping', 'Social', 'Work-related', 'Other'. You may supply an empty string if not required by the app/user.
start int
Start date/time as a Unix timestamp.
user string containing JSON-encoded object
JSON-encoded object containing user-supplied details for journey profiling purposes. The data is internally stored as-is. E.g.
If any of the fields age,gender,experience are present, they will be extracted to a separate field for easier subsequent data analysis. Suggested values are:
  • age: 0-10,11-16,17-24,25-44,45-64,75-84,85+
  • gender: female,male,prefer not to say
  • experience: experienced/infrequent/beginner
device string, max 255 characters
Unique identifier for the device. Can be any string - not necessarily the device's unique identifier.
username string
A valid CycleStreets account username. (See the user.create API call.)
password string
A valid CycleStreets account password. (See the user.create API call.)

Request parameters - optional



    "result": true

Error response

JSON object containing an error key and a text string.

Example error (text string will vary):

    "error": "The username/password combination did not match any validated account."

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.