Mapillary (V4) API provides two surfaces for interacting with the data: vector tiles and entity endpoints. Vector tiles provide a fast and easy way to render positions and encode filterable metadata, while entity endpoints provide additional metadata which is not present in the tiles.
With this version of the API (V4) we tried to find a right balance between optimizing for the most common use-cases (rendering a lot of spatial data with basic filtering), tile sizes which would make sense and providing the rest of the properties through additional endpoints. One thing to keep in mind is that entity endpoints do not provide any spatial filtering capabilities and it is expected that clients use vector tiles for such use-cases.
Add Mapillary images to a web site or app with the Mapillary embed in an iframe.
The iframe tag below would show a 640x480px image with ID 550092599700936.
<iframe
src="https://www.mapillary.com/embed?image_key=550092599700936&style=photo"
height="480"
width="640"
frameborder="0">
</iframe>
The URL has the following format:
https://www.mapillary.com/embed?image_key=IMAGE_ID&style=STYLE
Parameters:
All requests against https://graph.mapillary.com and https://tiles.mapillary.com must be authorized. They require a client or user access tokens. Tokens can be sent in two ways
Our authentication endpoints follow the standard OAuth 2.0 authorization code flow, as per specification.
Endpoint: GET https://www.mapillary.com/connect
URL Parameters:
Responses:
When successful, the user’s browser is redirected back to the app's configured callback URL with the following query parameters:
In case of an error, the following parameters will be redirected:
Examples:
Assume your app's callback URL is "https://yourapp.com/callback". Open the following authorization link:
https://www.mapillary.com/connect?client_id=12345&state=foo
https://yourapp.com/callback?state=foo&code=LONG_AUTHORIZATION_CODE
https://yourapp.com/callback?error=user_denied
Endpoint: POST https://graph.mapillary.com/token
This endpoint exchanges an authorization code or a refresh token for the user access token. Authorization is required, and the OAuth token must be the app's client secret.
Parameters:
Responses:
When successful, the following properties will be returned in the JSON payloadExamples:
curl https://graph.mapillary.com/token \
-H "Content-Type: application/json" \
-H "Authorization: OAuth CLIENT_SECRET" \
-d'
{
"grant_type": "authorization_code",
"code": "LONG_AUTHORIZATION_CODE",
"client_id": 1234
}'
{
"access_token": "USER_ACCESS_TOKEN",
"expires_in": 9000,
"token_type": "bearer"
}Since the user access token returned from the Token Exchange endpoint will expire at some time, as developers you need to refresh the token before it expires.
The recommended refresh flow:
Examples:
curl https://graph.mapillary.com/token \
-H "Content-Type: application/json" \
-H "Authorization: OAuth CLIENT_SECERT" \
-d'
{
"grant_type": "refresh_token",
"refresh_token": "USER_ACCESS_TOKEN",
"client_id": 1234
}'
{
"access_token": "NEW_USER_ACCESS_TOKEN",
"expires_in": 9000,
"token_type": "bearer"
}Vector tiles provide an easy way to visualize vast amounts of data. Mapillary APIs are heavily based on vector tiles to provide the developers with flexibility to programmatically interact with the data they contain in custom ways. Vector tiles support filtering and querying rendered features. Mapillary vector tiles follow the Mapbox tile specification.
Endpoint: https://tiles.mapillary.com/maps/vtp/mly1_public/2/{z}/{x}/{y}?access_token=XXX
Contain positions of images and sequences with original geometries (not computed)
Endpoint: https://tiles.mapillary.com/maps/vtp/mly1_computed_public/2/{z}/{x}/{y}?access_token=XXX
Contain positions of images and sequences with computed geometries (not original)
The tile metadata is exactly the same as Coverage tiles.
Endpoint: https://tiles.mapillary.com/maps/vtp/mly_map_feature_point/2/{z}/{x}/{y}?access_token=XXX
These tiles represent positions of map features which are detected on the Mapillary platform and are not traffic signs.
You can see the full list of available points here.
Endpoint: https://tiles.mapillary.com/maps/vtp/mly_map_feature_traffic_sign/2/{z}/{x}/{y}?access_token=XXX
These tiles represent positions of map features which are detected on the Mapillary platform and are traffic signs.
The tile metadata is exactly the same as Map feature tiles, points, except that the layer name is traffic_sign.
You can see the full list of available traffic signs here.
Each API call requires specifying the fields of the Entity you're interested in explicitly. A sample image by ID request which returns the id and a computed geometry could look as below. For each entity available fields are listed in the relevant sections. All IDs are unique and the underlying metadata for each entity is accessible at https://graph.mapillary.com/:id?fields=A,B,C. The responses are uniform and always return a single object, unless otherwise stated (collection endpoints). All collection endpoint metadata are wrapped in a {"data": [ {...}, ...]} JSON object.
Represents the metadata of the image on the Mapillary platform with the following properties.
Sample image request:
GET https://graph.mapillary.com/$IMAGE_ID?access_token=$TOKEN&fields=id,computed_geometry,detections.value
{
"id": "$IMAGE_ID",
"computed_geometry": {
"type": "Point",
"coordinates": [
0,
0
]
},
"detections": {
"data": [
{
"value": "information--general-directions--g1",
"geometry": "GjgKBm1weS1vchIYEgIAABgDIhAJ4iDyJhq8AQAApAG7AQAPGgR0eXBlIgkKB3BvbHlnb24ogCB4AQ==",
"id": "34567"
}
]
}
}Image search can be done using the graph.mapillary.com/images endpoint and specifying fields as stated above in addition to a filter:
Sample image search request:
GET https://graph.mapillary.com/images?access_token=$TOKEN&fields=id&bbox=12.967,55.597,13.008,55.607
{
"data": [
{
"id": "$IMAGE_ID_1"
},
{
"id": "$IMAGE_ID_2"
}
]
}
These are objects with a location which have been derived from multiple detections in multiple images.
You can see the full list of available points here and traffic signs here.
Sample map feature request:
GET https://graph.mapillary.com/$MAP_FEATURE_ID?access_token=$TOKEN&fields=id,geometry,object_value
{
"id": "$MAP_FEATURE_ID",
"geometry": {
"type": "Point",
"coordinates": [0, 0]
},
"object_value": "object--support--utility-pole"
}Map feature search can be done using the graph.mapillary.com/map_features endpoint and specifying fields as stated above in addition to a filter:
Sample map feature search request:
GET https://graph.mapillary.com/map_features?access_token=$TOKEN&fields=id,object_value&bbox=12.967,55.597,13.008,55.607
{
"data": [
{
"object_value": "object--sign--advertisement",
"id": "$MAP_FEATURE_ID_1"
},
{
"object_value": "object--support--utility-pole",
"id": "$MAP_FEATUREE_ID_2"
}
]
}
You can download points and traffic signs from the Mapillary website. The data is in the GeoJSON format.
To download data, zoom in on the map to the location you’re interested in and turn on the map data (points or traffic signs). Press the “Download” button to download all visible points or traffic signs in a JSON file.
Represent an object detected in a single image. For convenience this version of the API serves detections as collections. They can be requested as a collection on the resource (e.g. image or map feature) they contribute or belong to.
Sample detection request:
GET https://graph.mapillary.com/$IMAGE_ID/detections?access_token=$TOKEN&fields=image,value,geometry
{
"id": "$IMAGE_ID"
"image": {
"geometry": {
"type": "Point",
"coordinates": [0, 0]
},
"id": "$DETECTION_ID"
},
"value": "information--highway-interchange--g1",
"geometry": "GjgKBm1weS1vchIYEgIAABgDIhAJnC3uFxroAwAA7AbnAwAPGgR0eXBlIgkKB3BvbHlnb24ogCB4AQ=="
}The geometry field of a detection contains the segmentation data for each detection, but it must be decoded in order to get normalized coordinates for use with MapillaryJS or any image.
Sample decoding
In Python, segmentation can be decoded according to the following example:
import base64
import mapbox_vector_tile
base64_string = "GjgKBm1weS1vchIYEgIAABgDIhAJnC3uFxroAwAA7AbnAwAPGgR0eXBlIgkKB3BvbHlnb24ogCB4AQ=="
decoded_data = base64.decodebytes(base64_string.encode('utf-8'))
detection_geometry = mapbox_vector_tile.decode(decoded_data)
print(detection_geometry) The output of the decoding will not be normalized, but gives a series of coordinates:
detection_geometry = {'mpy-or': {'extent': 4096, 'version': 2, 'features': [{'geometry': {'type': 'Polygon', 'coordinates': [[[2402, 2776], [2408, 2776], [2413, 2762], [2413, 2746], [2409, 2736], [2404, 2732], [2363, 2734], [2357, 2747], [2359, 2771], [2363, 2776], [2377, 2779], [2383, 2789], [2389, 2788], [2392, 2783], [2396, 2783], [2402, 2776]]]}, 'properties': {}, 'id': 1, 'type': 3}]}}
To normalize this, divide each x and y coordinate by the extent (4096). To get exact pixel coordinates, multiply the normalized x by the width of the image containing the detection, and the normalized y coordinate by the height, remembering that pixel coordinates start at the top left corner of the image when visualized. Retrieve the height and width by making an API request for the image key with the height and width fields.
Detections are contained in images, so searched according to image location and timestamps. Detection search can be done using the graph.mapillary.com/detections endpoint and specifying fields as stated above in addition to a filter:
Sample detection search request:
GET https://graph.mapillary.com/detections?access_token=$TOKEN&fields=value&bbox=12.967,55.597,13.008,55.607
{
{
"data": [
{
"value": "general--traffic-sign--g1",
"id": "1203507933411555"
},
{
"value": "object--support--utility-pole",
"id": "1213804269051588"
},
]
}
Represents an organization which can own the imagery if users upload to it.
Sample organization request:
GET https://graph.mapillary.com/$ORGANIZATION_ID?access_token=$TOKEN&fields=name
{
"id": "$ORGANIZATION_ID"
"name": "My Organization"
}Represents a sequence of Image IDs ordered by capture time.
Returns multiple entities based on their IDs.
Requests to graph.mapillary.com are limited to 50,000 per minute per app. Exceeding the limit your app will be throttled and users will receive "Application request limit reached" error.
Requests to tiles.mapillary.com are limited to 50,000 per day.
Is a token required for all API calls, whether they're Entity API calls or vector tile requests. This token identifies the application used for generating it and enables making requests on behalf of it. If a hacker steals it, they would be able to make a request on behalf of your application!
Is a token obtained by the user when authentication through the OAuth2 flow. It authenticates both the user and the application it used. It is preferred to send user tokens as the authorization header (see Authentication section). This token is equivalent to a user password, if a hacker steals it, they'll be able to call the API on behalf of the user.