Accessing imagery and data through the Mapillary API

All requests against https://graph.mapillary.com must be authorized. They require a client or user access tokens. Tokens can be sent in two ways

• using ?access_token=XXX query parameters. This is a preferred method for interacting with vector tiles. Using this method is STRONGLY discouraged for sending user access tokens.
• using a header such as Authorization: OAuth XXX, where XXX is the token obtained either through the OAuth flow that your application implements or a client token from https://mapillary.com/dashboard/developers.

Setting up API access and obtaining a client token

Take special note of the Callback URL. This must be a real web address, whether it is your company website, your personal website, or something else. This is important because we are going to use this URL for retrieving the authorization code.

Make sure you select the appropriate access scopes from READ, WRITE, UPLOAD to define the scopes your application supports. 

Once all your information is complete, click Register.

Now the application access token will be available on the same page, and you’ll see it listed in the table under the application name you chose, under the Client Token column.

Obtaining an authorization token to access Mapillary data

The authorization for private and subscription data is based on OAuth 2.0, and you can also read about OAuth in Mapillary in our documentation. In this guide, we will replicate the OAuth procedures to retrieve an access token, then start downloading data from the API with authorization.

In the same table as the Client Token, there is another column called Authentication URL. Click on View then Copy to copy the url containing the client id needed to get authorization for your newly created application. 

Accessing the Mapillary API

A Mapillary API call requires that you include the application access token in the API call URL, and that the token is in the header. This means you need to access it via the command line or in a script, such as Javascript or Python.

In Python, you will use the requests module to access the API. An example is:

import requests

access_token = 'xyz123' # create your access token at https://mapillary.com/developer
image_id = '169979785061521'
url = 'https://graph.mapillary.com/{}/detections?fields=id,value,created_at&access_token={}'.format(image_id,app_access_token)
# or instead of adding it to the url, add the token in headers (strongly recommended for user tokens)
headers= { "Authorization" : "OAuth {}".format(token) }
response = requests.get(url, headers=header)
data = response.json()
print(data)

const access_token = 'xyz123'; # create your access token at https://mapillary.com/developer
const image_id = '169979785061521';
const api_url = 'https://graph.mapillary.com/' + image_id + '/detections?fields=id,value,created_at&access_token=' + token;
# or instead of adding it to the url, add the token in headers (strongly recommended for user tokens)
const response = await fetch(api_url, 
 { 
   headers: {'Authorization' : 'OAuth ' + token} 
 }
);
const myJson = await response.json();
console.log(JSON.stringify(myJson));