• 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

Journeys of user

This API provides a listing of the saved journeys of a specified user, having regard to any privacy settings.

Journeys are listed most recent first.

This API call implements cursor-based pagination.

In order to return a successful listing, a user must have enabled the listing of their journeys in their profile. However, in future, it is likely that this call will be expanded to enable credentials to be supplied so that the private journeys of an authenticated user can be retrieved.

Example

Example which retrieves the most recent 3 routes planned by a user who has made their route listing public. (In this example, a limit of 3 locations has been set, to avoid a long example on this page, but normally a limit of perhaps 25 or 50 would be a good starting point for the first page of results.)

https://api.cyclestreets.net/v2/journeys.user?username=someuser&format=flat&datetime=friendly&limit=3

Result:

{
    "pagination": {
        "latest": 43047091,
        "urlLater": "https://api.cyclestreets.net/v2/journeys.user?username=someuser&format=flat&limit=3&datetime=friendly&after=43047091",
        "hasLater": false,
        "top": 43047091,
        "bottom": 43047056,
        "hasEarlier": true,
        "urlEarlier": "https://api.cyclestreets.net/v2/journeys.user?username=someuser&format=flat&limit=3&datetime=friendly&before=43047056",
        "earliest": 37022101,
        "count": 3,
        "total": 15
    },
    "journeys": {
        "43047091": {
            "id": 43047091,
            "name": "Belgrove Street to The Mall",
            "datetime": "10:28am, 8th December 2014",
            "plans": {
                "balanced": {
                    "name": "Balanced",
                    "length": 3862,
                    "time": 901,
                    "url": "https://api.cyclestreets.net/v2/journey.retrieve?itinerary=43047091&plans=balanced"
                },
                "quietest": {
                    "name": "Quietest",
                    "length": 4170,
                    "time": 1154,
                    "url": "https://api.cyclestreets.net/v2/journey.retrieve?itinerary=43047091&plans=quietest"
                },
                "fastest": {
                    "name": "Fastest",
                    "length": 3801,
                    "time": 850,
                    "url": "https://api.cyclestreets.net/v2/journey.retrieve?itinerary=43047091&plans=fastest"
                }
            },
            "lengthAverage": 3944,
            "timeAverage": 968,
            "url": "https://www.cyclestreets.net/journey/43047091/",
            "idText": "43,053,458"
        },
        "43053453": {
            "id": 43053453,
            "name": "York Street to Thoday Street",
            "datetime": "10:27am, 8th December 2014",
            "plans": {
                "balanced": {
                    "name": "Balanced",
                    "length": 2011,
                    "time": 390,
                    "url": "https://api.cyclestreets.net/v2/journey.retrieve?itinerary=43053453&plans=balanced"
                }
            },
            "lengthAverage": 2011,
            "timeAverage": 390,
            "url": "https://www.cyclestreets.net/journey/43053453/",
            "idText": "43,053,453"
        },
        "43047056": {
            "id": 43047056,
            "name": "York Street to Riverside Bridge",
            "datetime": "10:27am, 8th December 2014",
            "plans": {
                "balanced": {
                    "name": "Balanced",
                    "length": 808,
                    "time": 193,
                    "url": "https://api.cyclestreets.net/v2/journey.retrieve?itinerary=43047056&plans=balanced"
                },
                "quietest": {
                    "name": "Quietest",
                    "length": 936,
                    "time": 242,
                    "url": "https://api.cyclestreets.net/v2/journey.retrieve?itinerary=43047056&plan=quietest"
                },
                "fastest": {
                    "name": "Fastest",
                    "length": 750,
                    "time": 158,
                    "url": "https://api.cyclestreets.net/v2/journey.retrieve?itinerary=43047056&plans=fastest"
                }
            },
            "lengthAverage": 831,
            "timeAverage": 198,
            "url": "https://www.cyclestreets.net/journey/43047056/",
            "idText": "43,053,451"
        }
    }
}

Request parameters - required

username string

The username of the user whose saved journeys are being requested.

format string: 'flat'

The requested format of the response. At present, only the string 'flat' is supported. (In future it is likely that GeoJSON output, giving a drawable route summary, will be available.)

Request parameters - optional

limit integer, default 100

The maximum number of journeys to return for the current pagination view.

before integer

Sets that journey IDs should be before (earlier than) this value. This is used to enable cursor-based pagination. Note that the value supplied is available as the pagination/bottom value in a result. In general you should not need to construct a URL manually which sets the before parameter; instead, use the pagination/urlEarlier value which provides a pre-constructed URL representing the next page of results, and which relays the parameters of the current request.

after integer

Sets that journey IDs should be after (more recent than) this value. This is used to enable cursor-based pagination. Note that the value supplied is available as the pagination/top value in a result. In general you should not need to construct a URL manually which sets the after parameter; instead, check the pagination/hasLater flag and then use the pagination/urlLater value which provides a pre-constructed URL representing the next page of results, and which relays the parameters of the current request.

datetime string

If specified, the datetime field (if requested in the fields list) will be converted from unixtime (the default output format) to a formatted version; the available output formats are:

• friendly A friendly format suitable for showing on a webpage, e.g. '6:55pm, 4th October 2013'; this is equivalent to date ('g:ia, jS F Y', $date) in PHP
• friendlydate A friendly date format suitable for showing on a webpage, e.g. '4th October, 2013'; this is equivalent to date ('jS F, Y', $date) in PHP
• sqldatetime SQL DATETIME format (i.e. simplified ISO 8601 format): YYYY-MM-DD HH:MM:SS
• unixtime Unixtime (the default)

Response

JSON object, as per the example above.

The results are always ordered most-recent first.

Each itinerary shows a list of plan types that were planned at the time of creation, with API URLs and basic metadata for each. The ordering of plans, filtered by their existence, is balanced, quietest, fastest, leisure1, leisure2, … .

For each itinerary, a route length in metres and time is shown. These are each the average of the values in the plans.

Each itinerary shows a list of plan types that were planned at the time of creation, with API URLs for each.

There is a pagination data block at the start. The pagination fields are documented below.

Pagination

This API call implements cursor-based pagination.

The key fields top and bottom restate the top-most and bottom-most values in the current view of the data. The latest and earliest give the user's absolute latest and earliest journeys planned. The *later/*earlier fields enable clients to make further requests to paginate forwards or backwards.

The pagination fields are as follows:

• latest (integer): The latest journey number planned by the user (at the time of the API request).
• urlLater (URL string): The URL to retrieve later journeys; this will always result in a URL even if there are no later URLs at the time of the request, as the client may wish to enable the user to request subsequent journeys that have been planned after the current pagination is loaded; hasLater can be used to determine if there are actually any later URLs as of the time of the request. The URL will relay the parameters of the current request (i.e. maintain the username, etc.).
• hasLater (boolean): Whether (at the time of the API request) there are any later journeys planned after the top-most journey number (as per top).
• top (integer): The top-most journey number in the (current pagination view of) data which follows, for easy reference.
• bottom (integer): The bottom-most journey number in the (current pagination view of) data which follows, for easy reference.
• hasEarlier (boolean): Whether (at the time of the API request) there are any earlier journeys planned after the bottom-most journey number (as per bottom).
• urlEarlier (URL string): The URL to retrieve earlier journeys; if there are no earlier journeys this will be boolean false. The URL will relay the parameters of the current request (i.e. maintain the username, etc.).
• earliest (integer): The earliest journey number planned by the user
• count (integer): Count of the number of journeys in the current pagination view
• total (integer): The total number of all journeys planned by the user, regardless of the current pagination view

Error response

JSON object containing an error key and a text string.

Example error (text string will vary):

{
    "error": "There is no such user, or they have disabled viewing of journeys."
}