• 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

Photomap locations

The photomap locations API retrieves photos of categorised cycling-related infrastructure from a specified geographical area which have been submitted by users. The same data is visible on our Photomap.

As well as this call, a single-location equivalent is available as the photomap.location call.

Each location has various metadata attached to it, such as a caption, a category (e.g. cycleparking/obstruction/etc.), a metacategory (e.g. good/bad), date/time, location, and more.

You can retrieve arbitrary metadata fields added to a location using additionalMetadata. This could be useful for auditing and similar uses.

Note that each location has a license (e.g. Creative Commons, Public Domain, No reproduction permitted, etc.) as specified by the contributor. You are required to respect the specified license. Also, CycleStreets naturally has a database right in the collective dataset.

Not all locations have a photo attached to them. Such 'placeholders', however, do contain the other metadata.

The data is optimised to give an even spread within a map view when there would be too many to show at the current zoom level. To do this, it breaks the visible map into a 10x10 grid and chooses one photo from each grid cell.

Example

Example which returns problem cycle parking locations in an area of Cambridge.

(In this example, a limit of only 3 locations has been set, to avoid a long example on this page, but normally a limit of perhaps 150 would be appropriate for web viewing.)

https://api.cyclestreets.net/v2/photomap.locations?category=cycleparking&metacategory=bad&limit=3&fields=id,hasPhoto,thumbnailUrl,license,caption&bbox=0.1456,52.1990,0.1487,52.2006

https://api.cyclestreets.net/v2/photomap.locations?category=cycleparking&metacategory=bad&limit=3&fields=id,hasPhoto,thumbnailUrl,license,caption&boundary=[[0.145246,52.199900],[0.146663,52.200873],[0.148401,52.200189],[0.147156,52.198808],[0.145246,52.199900]]

Result:

{
    "type": "FeatureCollection",
    "features": [
        {
            "type": "Feature",
            "properties": {
                "id": 10289,
                "hasPhoto": "yes",
                "thumbnailUrl": "https://www.cyclestreets.net/location/10289/cyclestreets10289-size200.jpg",
                "license": "cc-by-sa",
                "caption": "Complete lack of cycle parking on the highway forces cyclists to do this sort of thing. The pavement is totally blocked."
            },
            "geometry": {
                "type": "Point",
                "coordinates": [
                    0.146092,
                    52.199314
                ]
            }
        },
        {
            "type": "Feature",
            "properties": {
                "id": 23583,
                "hasPhoto": "no",
                "thumbnailUrl": null,
                "license": "publicdomain",
                "caption": "A lot of residents in side streets off Mill Road use bicycles as their primary means of transport. Converting a few car parking spaces into bicycle parking would be enormously helpful, since current bicycle parking provisions are virtually non-existent."
            },
            "geometry": {
                "type": "Point",
                "coordinates": [
                    0.147658,
                    52.200581
                ]
            }
        },
        {
            "type": "Feature",
            "properties": {
                "id": 53500,
                "hasPhoto": "yes",
                "thumbnailUrl": "https://www.cyclestreets.net/location/53500/cyclestreets53500-size200.jpg",
                "license": "publicdomain",
                "caption": "No home for bikes on a street dominated by car storage."
            },
            "geometry": {
                "type": "Point",
                "coordinates": [
                    0.14748,
                    52.1996
                ]
            }
        }
    ]
}

Request parameters - required

bbox csv string of longitude/latitudes: w,s,e,n

A bounding box string as w,s,e,n in which the locations must reside. Locations will be spread evenly around this bounding box.

boundary GeoJSON fragment string, as [[lon1,lat1],[lon2,lat2],…,[lon1,lat1]]

A boundary string as geojson-style polygonal coordinates of longitude,latitude that encloses the results.

The bbox and boundary parameters are mutually exclusive.

Request parameters - optional

It is strongly recommended to specify a fields list, so that clients receive exactly the data they need.

fields string, comma-separated list of fields from the list below,
  default id,latitude,longitude,caption,hasPhoto,thumbnailUrl,username,licenseName

Controls what information is returned for each location. It is strongly recommended to send this, so that clients receive exactly the data they need.

Available fields are listed below.

If fields is not supplied, the default is used, which represents a sensible and useful set of fields.

The fields id,latitude,longitude,caption are always returned.

When the data is returned in the geojson format, the values for latitude,longitude appear only in the /geometry/coordinates field rather than being duplicated in the properties list.

Fields are returned in the ordering specified by the caller, which can be useful when using export=csv.

Unrecognised fieldnames are simply ignored rather than an error being thrown.

category string

Filter to locations with the specified category or comma separated list thereof, e.g. cycleparking,obstructions. The values for category [see examples] can be found using the photomap.categories API call.

metacategory string

Filter to locations with the specified metacategory or comma separated list thereof, e.g. good,bad. The values for metacategory [see examples] can be found using the photomap.categories API call.

limit int, max 400

Maximum number of locations returned. It is strongly recommended to use this parameter. A value of 25 is recommended for mobile apps, and 150 for desktop apps. Photos will be spread evenly around the viewport where possible. There is a limit of 400.

suppressplaceholders int (0|1), default 0

Suppress locations that have no attached image. Recommended for mobile apps.

thumbnailsize int 60|120|150|180|200|250|300|350|400|425|450|500|640|800|1000|1200|1500|1800|2000 (default 425)

The thumbnail size used in the thumbnail URLs shown within the data. At present, only the stated sizes are supported; however we plan to remove this limitation shortly; for now, if you require another size, please let us know and we will add it as a supported size. If an unsupported size is specified, the default (425) is currently returned.

iconset string cyclestreets|camcycle (default cyclestreets)

Specifies the style of the icons.

iconformat string svg|png|@2x.png (default svg)

Format of icons, if specifying iconProperties/iconLocation/iconUrl in the fields list. For retina displays, use a value containing @2x. (Please note that the camcycle iconset supports only png and the API will respond with an error if a different format is requested.)

urlprefix string

If set, this will prefix the supplied string to URL-related fields. Currently only mapLocation, iconProperties->iconUrl and iconProperties->shadowUrl are affected but other fields will have support for this in due course.

selectedid int

If supplied, this location ID will be included as an extra result, if it exists, irrespective of the bounding box or any other conditions, and is additional to the limit if set. This parameter is useful if, after adding a location using photomap.add, you wish to show the map again with the just-uploaded item shown, or if you wish to start the map at a certain location. If it does not exist, this will not cause an error to be thrown.

since int

If supplied as a Unixtime value, this will limit locations to be at least this time.

search string

Limit to locations where caption contains the search value.

Currently there is a limitation that a bbox/boundary must be included.

tags string

Limit to a specific tag. Currently only a single tag is supported.

username string

If supplied, locations will be limited to those contributed by this username. If the username does not exist, no results will be returned but no error will be thrown.

export string (csv|geojson)

Ouputs the data for export, with the specified format. The appropriate HTTP headers will be sent. The limit is increased to 2,000. Available values are:

• csv: CSV text. If set to this, the specified fields order will be respected.
• geojson: GeoJSON output (see example).

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)

Fields available

The additionalMetadata field

https://api.cyclestreets.net/v2/photomap.locations?category=cycleparking&fields=id,latitude,longitude,caption,additionalMetadata,datetime,shortlink&bbox=-0.489,51.28,0.236,51.686&limit=3&datetime=sqldatetime

{
    "type": "FeatureCollection",
    "features": [
        {
            "type": "Feature",
            "properties": {
                "id": 57141,
                "caption": "Cycle parking needed",
                "additionalMetadata": {
                    "landtype": "highway"
                },
                "datetime": "2014-03-18 13:33:55",
                "shortlink": "https://cycle.st/p57141"
            },
            "geometry": {
                "type": "Point",
                "coordinates": [
                    0.077049,
                    51.620388
                ]
            }
        },
        {
            "type": "Feature",
            "properties": {
                "id": 56208,
                "caption": "12 stands needed",
                "additionalMetadata": null,
                "datetime": "2014-01-16 18:06:39",
                "shortlink": "https://cycle.st/p56208"
            },
            "geometry": {
                "type": "Point",
                "coordinates": [
                    -0.003292,
                    51.462429
                ]
            }
        },
        {
            "type": "Feature",
            "properties": {
                "id": 57143,
                "caption": "test",
                "additionalMetadata": {
                    "landtype": "highway",
                    "capacity": "2"
                },
                "datetime": "2013-04-25 10:02:10",
                "shortlink": "https://cycle.st/p57143"
            },
            "geometry": {
                "type": "Point",
                "coordinates": [
                    -0.163186,
                    51.523872
                ]
            }
        }
    ]
}

https://api.cyclestreets.net/v2/photomap.locations?category=cycleparking&fields=id,latitude,longitude,caption,additionalMetadata[landtype,capacity],datetime,shortlink&bbox=-0.489,51.28,0.236,51.686&limit=3&datetime=sqldatetime

{
    "type": "FeatureCollection",
    "features": [
        {
            "type": "Feature",
            "properties": {
                "id": 58827,
                "caption": "Incredible there is now such a large amount of space, but no cycle parking. A sign of a modern city is the presence of plenty of cycle parking at a station.",
                "Landtype": "highway",
                "Capacity": "200",
                "datetime": "2014-05-16 17:58:40",
                "shortlink": "https://cycle.st/p58827"
            },
            "geometry": {
                "type": "Point",
                "coordinates": [
                    -0.123687,
                    51.53035
                ]
            }
        },
        {
            "type": "Feature",
            "properties": {
                "id": 30754,
                "caption": "The supermarket have provided good cycle parking outside their store, but as this picture clearly shows they need to provide more!",
                "Landtype": false,
                "Capacity": false,
                "datetime": "2011-03-12 17:04:53",
                "shortlink": "https://cycle.st/p30754"
            },
            "geometry": {
                "type": "Point",
                "coordinates": [
                    -0.399704,
                    51.658985
                ]
            }
        },
        {
            "type": "Feature",
            "properties": {
                "id": 39233,
                "caption": "Segregated cycle lanes in both directions along King Henry's Drive",
                "Landtype": false,
                "Capacity": false,
                "datetime": "2012-06-10 13:48:02",
                "shortlink": "https://cycle.st/p39233"
            },
            "geometry": {
                "type": "Point",
                "coordinates": [
                    -0.024977,
                    51.352341
                ]
            }
        }
    ]
}

Response

GeoJSON feature list as per example above. Geometry types will always be Point.

(If export has been specified, the relevant export format will be returned instead.)

Example with no locations in an area:

{
    "type": "FeatureCollection",
    "features": [

    ]
}

Error response

JSON object containing an error key and a text string.

Even if export=… is specified, any error response will still be a JSON object, as shown below.

Example errors (text string will vary):

{
    "error": "Neither a bbox nor a detailed boundary have been supplied."
}

{
    "error": "The category is not valid"
}