• 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

Points of Interest (POIs)

This API call enables you to retrieve Points of Interest (POIs) in a geographical area.

You can firstly retrieve the types of POIs available using the pois.types API call.

You can supply either:

1. A bounding box, so that POIs are returned, spread out evenly within the bounding box (up to the specified limit number of items). This most suitable for desktop use.
2. A radius, so that POIs are returned in order of proximity, e.g. all bike shops within a 5km radius (up to the specified limit number of items). This is most suitable for mobile use.

This is an interface to the same data used for the Points of interest pages.

There is currently a limitation that only locations defined in the upstream datasource (OpenStreetMap) as point sources are returned. We plan to add in polygon-based original data shortly.

Example

(In these examples, a limit of 3 locations has been set, to avoid a long example on this page, but normally no limit would be set.)

Example 1 (bounding box): Retrieves cycle parking locations within a specified bounding box, also retrieving OSM metadata.

https://api.cyclestreets.net/v2/pois.locations?type=cycleparking&bbox=0.111035,52.201395,0.125325,52.209285&limit=3&fields=id,latitude,longitude,name,osmTags

Example 2 (radius): Retrieves cycle parking locations within a 5km radius of a location in Cambridge, in order of proximity, also retrieving OSM metadata.

https://api.cyclestreets.net/v2/pois.locations?type=cycleparking&longitude=0.11795&latitude=52.20530&radius=5&limit=3&fields=id,latitude,longitude,name,osmTags

Result (same structure from either example):

{
    "type": "FeatureCollection",
    "features": [
        {
            "type": "Feature",
            "properties": {
                "id": "943984",
                "name": "(Name not known)",
                "osmTags": {
                    "amenity": "bicycle_parking",
                    "capacity": "76",
                    "covered": "no",
                    "source": "survey"
                }
            },
            "geometry": {
                "type": "Point",
                "coordinates": [
                    0.118357,
                    52.205166
                ]
            }
        },
        {
            "type": "Feature",
            "properties": {
                "id": "907790",
                "name": "(Name not known)",
                "osmTags": {
                    "amenity": "bicycle_parking",
                    "capacity": "12",
                    "covered": "no",
                    "source": "survey"
                }
            },
            "geometry": {
                "type": "Point",
                "coordinates": [
                    0.118967,
                    52.205429
                ]
            }
        },
        {
            "type": "Feature",
            "properties": {
                "id": "622058",
                "name": "(Name not known)",
                "osmTags": {
                    "amenity": "bicycle_parking",
                    "capacity": "18",
                    "covered": "no",
                    "source": "survey"
                }
            },
            "geometry": {
                "type": "Point",
                "coordinates": [
                    0.118907,
                    52.204823
                ]
            }
        }
    ]
}

Request parameters - required

type string

POI type, e.g. cycleparking. You can firstly retrieve the types of POIs available using the pois.types API call, either to determine the names or to use for a selection list for the user.

Location parameter(s)

As follows:

You must also supply either a bounding box or a latitude/longitude/radius combination:

bbox string

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

or

longitude float

Longitude of the centre point

latitude float

Latitude of the centre point

radius positive integer

POIs will be present within the radius shown, ordered nearest from the centre point first.

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, default id,latitude,longitude,name,notes,website

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:

• id: An ID of the item. Clients should not assume the ID of an item will be persistent between requests.
• latitude, longitude: Result in the geometry coordinates.
• name: Name of the POI.
• notes: Any notes relating to the POI (or empty string).
• website: Website (or empty string if none defined).
• iconUrl: Icon URL.
• editlink: URL where the source data for the POI may be edited; if it is not an editable POI, this field will be present but empty.
• nodeId: OSM node ID (or empty string if the data does not originate from OSM).
• wayId: OSM way ID (or empty string if the data does not originate from OSM).
• osmTags: Array of raw OSM tag data, excluding node/way values (as these are available separately above). (Relations data will not be included.) If there are no tags or the data does not originate from OSM, this will be the value null). If specified in the form additionalMetadata[subfield1,subfield2,…], the subfields will appear at the top level of the properties instead of wrapped. This latter format is required for CSV (as it ensures a consistent number of fields are outputted).
• inferredAccessibility Work in progress Aug 2017 not yet finalized. One of: public, private, destination. This is similar to the value of the access tag, but with some additional inferences applied. Tags like accesss=no is considered private, and access=visitors,customers etc is treated as destination. Public cyle parking spaces that are detected to lie within areas marked as acess=private are also get modified to inferredAccessibility=private.

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

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

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.

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

format string, default geojson

Sets the output format. Not normally required except in the use-case of requiring an export. The appropriate HTTP headers will be sent. Available values are:

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

accessFilter Work in progress Aug 2017 not yet finalized. comma separated values of access types: public, private, destination

Limit results to those matching the given access. If omitted all results are included.

limit integer, default 50, minimum 1, maximum 400

Maximum items to return. Fewer than this number may be returned, depending on the data. If you supply a larger limit than 400, it will be silently replaced (without throwing an error) with 400.

iconsize string: 12|16|20|24|32|48|64, default 16

Size of the returned icon in the icon URL (if field specified).

Response

GeoJSON feature list as per example above.

Features will always be a GeoJSON Point type. We plan to add support for other types (e.g. Polygon) in the future, but such a future feature would only be triggered by a new parameter indicating that it supports polygon types also.

Error response

JSON object containing an error key and a text string.

Example error (text string will vary):

{
    "error": "Invalid POI type"
}