Donate using PayPal

CycleStreets API (v2)

  • Details for:
  • 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.117950&latitude=52.205303&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: Latitude.
  • longitude: Longitude.
  • name: Name of the POI.
  • notes: Any notes relating to the POI (or empty string).
  • website: Website (or empty string if none defined).
  • 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.

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

We welcome your feedback, especially to report bugs or give us route feedback.

My comments relate to: *






Your comments: *
URL of page: * http://www.cyclestreets.dk/api/v2/pois.locations/
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.