CycleStreets API (v2)

Contents:

Geocoder

Example

Request parameters - required

Request parameters - optional

Response

Error response

Geocoder

This API call provides location results for a given search phrase.

The results are derived from Nominatim with extra processing to handle additional location types (e.g. postcodes) and bounding box logic.

Search-as-you-type (autocomplete search) usage is permitted, as we are using our own installation rather than the central OSM installation which forbids such use.

Location types included are:

Streets, paths, settlements (e.g. cities/towns/villages), places - standard OSM data
UK postcodes (full or partial)
Station codes, e.g. KGX for King's Cross
OS grid references, e.g. TQ2894879697 (which is Buckingham Palace)
CycleStreets itinerary number (as per the journey.retrieve API call)

The ordering of results mainly comes from Nominatim.

Note: indexing of new data updates is currently paused.

Example

Example which finds results for Downing Street (a common street name around the UK), returning GeoJSON results, limited to the British Isles / UK.

https://api.cyclestreets.net/v2/geocoder?q=downing+street&bounded=1&bbox=-6.6577,49.9370,1.7797,57.6924

Result:

{
    "type": "FeatureCollection",
    "features": [
        {
            "type": "Feature",
            "properties": {
                "name": "Downing Street",
                "near": "City of Westminster, London",
                "bbox": "-0.1264298,51.5031644,-0.1262112,51.5031667"
            },
            "geometry": {
                "type": "Point",
                "coordinates": [
                    -0.1262112,
                    51.5031667
                ]
            }
        },
        {
            "type": "Feature",
            "properties": {
                "name": "Downing Street",
                "near": "Cambridge, Cambridgeshire",
                "bbox": "0.1206122,52.2028319,0.1216765,52.2030956"
            },
            "geometry": {
                "type": "Point",
                "coordinates": [
                    0.1213628,
                    52.2030187
                ]
            }
        },
        
        …
    ]
}

Same example, but with full geometries enabled, and specifying fields to display.

https://api.cyclestreets.net/v2/geocoder?q=downing+street&bounded=1&bbox=-6.6577,49.9370,1.7797,57.6924&geometries=1&fields=near,name,bbox,type,osmType,osmId,osmTagKey,osmTagValue

Result:

{
    "type": "FeatureCollection",
    "features": [
        {
            "type": "Feature",
            "properties": {
                "near": "City of Westminster, London",
                "name": "Downing Street",
                "bbox": "-0.1264298,51.5031644,-0.1262112,51.5031667",
                "type": "OSM",
                "osmType": "way",
                "osmId": 139726517,
                "osmTagKey": "highway",
                "osmTagValue": "residential"
            },
            "geometry": {
                "type": "LineString",
                "coordinates": [
                    [
                        -0.1264298,
                        51.5031644
                    ],
                    [
                        -0.1262112,
                        51.5031667
                    ]
                ]
            }
        },
        {
            "type": "Feature",
            "properties": {
                "near": "Cambridge, Cambridgeshire",
                "name": "Downing Street",
                "bbox": "0.1206122,52.2028319,0.1216765,52.2030956",
                "type": "OSM",
                "osmType": "way",
                "osmId": 3993066,
                "osmTagKey": "highway",
                "osmTagValue": "unclassified"
            },
            "geometry": {
                "type": "LineString",
                "coordinates": [
                    [
                        0.1206122,
                        52.2028319
                    ],
                    [
                        0.1213628,
                        52.2030187
                    ],
                    [
                        0.1216765,
                        52.2030956
                    ]
                ]
            }
        },
        
        …
    ]
}

Example with no results:

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

Request parameters - required

q string: The search string, e.g. for a name/street/place/postcode, URL-encoded (e.g. 'buckingham+palace'). Strings are treated case-insensitively. Values longer than 750 characters will be ignored (assumed to be spam).

Request parameters - optional

These parameters are very similar to Nominatim.

limit positive integer Defaults to 12.

Limit of the returned results (the maximum is 100). Slightly more may be returned when results come from more than one source such as Nominatim and the table of UK railway stations.

countrycodes string e.g. gb,ie

Limit search results to a specific country (or a comma separated list of countries). Each countrycode should be the ISO 3166-1alpha2 code such as gb for the United Kingdom, de for Germany, etc.

bbox string west,south,east,north

Bounding box of longitudes and latitudes defining the preferred area to search for results.

bounded 0|1 Defaults to 0 (unbounded search)

Restrict the results to only items contained with the bounding box. When using an unbounded search, even if a bbox is supplied the top items on the list may lie outside that bbox.

geometries 0|1 Defaults to 0 (Point type only)

Enables full geometries. By default, a Point geometry with the centrepoint is returned. This option enables other GeoJSON types, such as Polygon, LineString. This gives the exact layout of each geographical feature, but the output is more verbose. Note that this does not currently display the administrative centrepoint for a boundary. This option should only be needed if you need to display exact geometries; in all other cases, the bbox property (returned by default) enables the location to be zoomed in appropriately.

fields string, comma-separated list of fields, default name,near,bbox

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:

name: Main name, e.g. the street name
near: Name context, e.g. town
bbox: Bounding box string as w,s,e,n containing the result
type: Item type, e.g. 'OSM', 'Postcode', 'lat,lon'
osmType: OSM type (e.g. way, relation), if type = 'OSM'
osmId: OSM ID, if type = 'OSM'
osmTagKey: OSM tag key, if type = 'OSM'
osmTagValue: OSM tag value, if type = 'OSM'

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

The fields name,near are always returned.

Fields are returned in the ordering specified by the caller.

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

Response

Returns a list of results as a GeoJSON object, as per example above.

By default the geometry will be a Point with the centrepoint, but fuller geometries can be enabled with geometries=1 as documented above.

The properties section for each feature includes the name, latitude, longitude and where the requested location is 'near'.

Error response

JSON object containing an error key and a text string.

Example error (text string will vary):

{
    "error": "Empty search string"
}

* Items marked with an asterisk [*] are required fields and must be fully completed.

We welcome your feedback, especially to report bugs or give us route feedback.
My comments relate to: *	Route problem/feedback Other Journey Planner problem Photomap Mobile app feedback Bug report Report abuse Other, general feedback
Your comments: *
URL of page: *	https://oxford.cyclestreets.net/api/v2/geocoder/
How did you find out about CycleStreets?:
Your name:
Your e-mail address:
Our ref:	Please leave blank - anti-spam measure