CycleStreets API (v2)
Photomap location
The photomap location API retrieves a single photo of cycling-related infrastructure which has been submitted by a user. The same data is visible on our Photomap.
This call is effectively a single-location version of the photomap.locations call, which retrieves the same data but on an area basis.
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.
Example
Example which returns a location in an area of Cambridge, returning the fields specified.
https://api.cyclestreets.net/v2/photomap.location?id=80&fields=id,latitude,longitude,caption,hasPhoto,thumbnailUrl,username,licenseName&thumbnailsize=400
Result:
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"properties": {
"id": 80,
"caption": "Bicycle outside a house in York Street.",
"hasPhoto": true,
"thumbnailUrl": "https://www.cyclestreets.net/location/80/cyclestreets80-size400.jpg",
"username": "martin",
"licenseName": "CC Attribution-Share Alike (by-sa)"
},
"geometry": {
"type": "Point",
"coordinates": [
0.141554,
52.205318
]
}
}
]
}
Request parameters - required
- id int
- The location ID.
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 format=csv.
Unrecognised fieldnames are simply ignored rather than an error being thrown.
- 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.)
- format string, default geojson
-
Sets the output format. Available values are:
- geojson: GeoJSON output (see example) (default)
- flat: Flat-structured JSON. This can be more useful if the data is to be pre-loaded into an editing form, e.g. for submission to photomap.update.
- 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 available fields are as follows:
(These are shown grouped for clarity; the groupings themselves are not part of the API itself.)
- Core fields:
- id: The unique identifier of the location, which will be numeric
- latitude: Latitude of the location
- longitude: Longitude of the location
- caption: Caption (as plain text)
- clusterCount: Count of number in cell for the spread algorithm
- Image/video fields:
- hasPhoto: Whether the location has a photo (boolean true/false)
- thumbnailUrl: Full URL of the image (thumbnail size)
- thumbnailLocation: Location of the image (thumbnail size)
- imageUrl: Full URL of original image file
- imageLocation: Location of image file (for local use)
- hasVideo: Whether the location has a video (boolean true/false)
- videoFormats: Video formats, and their URLs, as an associative array. If not a video, or no videos available, this will be an empty array.
- type: Type (photo/video/placeholder)
- Icon (categorisation) fields:
- iconProperties: Icon details, as an array of icon properties, suitable for direct use in Leaflet.js or adaptable to other libraries
- iconLocation: Location of category icon image file
- iconUrl: Full URL of category icon image file
- Categorisation fields:
- categoryId: The category identifier (which will match category=... if set) (e.g. 'obstructions')
- categoryName: Category name (e.g. 'Obstruction')
- categoryPlural: Category name, pluralised (e.g. 'Obstructions')
- categoryDescription: Category description (e.g. 'A narrow place, difficult for cycles to pass.')
- metacategoryId: The metacategory identifier (which will match metacategory=... if set) (e.g. 'bad')
- metacategoryName: Metacategory name (e.g. 'Problem')
- metacategoryDescription: Metacategory description (e.g. 'A problem that needs to be fixed')
- categoryLink: Location of category/metacategory page
- Date/time field:
- datetime: Time when the photo was taken; the format of this can be set using datetime=... as documented above
- User/credit/licensing fields:
- username: Username of the user who submitted the location
- usernameWithImportingHtml: Username of the user who submitted the location, with importing details, as HTML
- userProfileUrl: URL of the user profile of the user who submitted the location
- credit: Credit (e.g. username of Flickr user, if image imported); often empty
- creditUrl: URL relating to credit (e.g. Flickr user page, if image imported); often empty
- sourceUrl: URL of source image (if imported, e.g. from Flickr)
- license: License identifer
- licenseName: License name
- licenseUrl: License URL
- editRights: Indicates whether the user has edit rights; not yet implemented
- Social field:
- likes: The number of submitted 'Likes'
- URL fields:
- url: Full URL of location page on the CycleStreets website
- shortlink: Shortlink URL of location page on the CycleStreets website
- apiUrl: URL of API URL of the location
- dayLink: Location of link to photos taken the same day of the year
- Geography fields:
- zoom: Map zoom of the location at the time of saving
- basemap: Basemap (as identifier) used at the time of saving
- areaName: Name of the Local Authority
- areaSubdomain: Area subdomain on CycleStreets website
- areaCountry: Area country
- photomapletLocation: Location of maplet image; subject to change
- mapUrl: Link to map location on Photomap page (or urlprefix)
- nearbyStreets: Nearby streets; currently disabled, pending performance work
- Detail fields:
- bearing: Bearing
- bearingString: Bearing, as a string, with the first letter capitalised (e.g. 'North west')
- azimuth: Azimuth
- elevation: Elevation
- elevationString: Elevation, as a string (e.g. '2m above ground')
- proximity: Proximity
- Dimensions fields:
- dimensions: Dimensions string as wxh
- width: Width in pixels
- height: Height in pixels
- thumbnailDimensions: Dimensions of thumbnail string as wxh
- thumbnailWidth: Width of thumbnail in pixels
- thumbnailHeight: Height of thumbnail in pixels
- Caption (more) fields:
- captionHtml: Caption, as HTML
- title: Title, currently emulated from the start of the caption
- Pagination fields:
- previous: Previous image, numerically
- next: Next image, numerically
- earlier: Previous image, chronologically
- later: Next image, chronologically
- Grouping fields:
- tags: Tags, as an array
- galleryMembershipHtml: Gallery membership, as HTML; not yet implemented
- Extensible metadata field:
- additionalMetadata: A special field which acts as an expandable container - see the section below which explains its handling.
This call supports the additionalMetadata field (including subfields), as documented in detail on the photomap.locations page.
The following example includes the additionalMetadata field, with subfields specified so that these are promoted to top-level keys (rather than nested):
https://api.cyclestreets.net/v2/photomap.location?id=62972&fields=id,caption,hasPhoto,additionalMetadata[landtype,capacity],thumbnailUrl,username,licenseName
Result:
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"properties": {
"id": 62972,
"caption": "This is a very busy cycling haven every weekend and so secure parking is needed.",
"hasPhoto": false,
"Landtype": "unknown",
"Capacity": "6",
"thumbnailUrl": "",
"username": "martin",
"licenseName": "Public domain"
},
"geometry": {
"type": "Point",
"coordinates": [
-0.343738,
51.403187
]
}
}
]
}
Response
GeoJSON object containing one Point
feature:
See example above.
Example using format=flat
:
{
"id": 80,
"latitude": 52.205318,
"longitude": 0.141554,
"caption": "Bicycle outside a house in York Street.",
"hasPhoto": true,
"thumbnailUrl": "https://www.cyclestreets.net/location/80/cyclestreets80-size400.jpg",
"username": "martin",
"licenseName": "CC Attribution-Share Alike (by-sa)"
}
Error response
JSON object containing an error key and a text string.
Example error (text string will vary):
{
"error": "Photo #999999999 does not exist."
}
* Items marked with an asterisk [*] are required fields and must be fully completed.