Articles in this section

Accessing imagery and data through the Mapillary API

Avatar
  • Updated
Follow

To access the data on Mapillary through the Mapillary API, there are different endpoints:

See our API documentation for more details about the parameters for all the calls. In this article, we're looking at how to obtain and use the credentials you need for accessing the APIs: user and application access tokens

  1. API endpoints and permissions
  2. Setting up API access and obtaining a client token
  3. Obtaining a token to access private imagery and map data
  4. Accessing the Mapillary API

 

API endpoints and permissions

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.

The client access_token must be appropriately configured with permissions to access map data (map features and detections).

For example, if Bob from CityGov subscribes to data in the city of Madison, Wisconsin, then he must generate a client token to view public images, whether his own or anybody else’s. To access the images, he must generate a client token with the desired access scopes enabled (READ, WRITE, UPLOAD).

Setting up API access and obtaining a client token

To access data via the 3rd party API, the first step is to create a client token. To do this, visit https://www.mapillary.com/dashboard/developers and click on the Register application button. This will show an input form asking for several pieces of information. If you make an application, you need a client token to access Mapillary. We are going to make the foundation of the application in order to access API data, even if you won’t be building a proper application in full.

Screenshot_2021-06-09_at_15.41.52.png

Name your application in a way that helps you remember the purpose, for example, Map feature API access. Put whatever applies to you in the other boxes.

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. 

Paste that URL into your browser, and it will ask you to authorize your application the access to the Mapillary data based on the previously selected access scopes.

 

Screenshot_2021-06-09_at_17.59.25.png

Click Authorize, and the page will redirect. The redirect will correspond to the callback URL you provided. Even if the redirect fails—with a message such as This site can't be reached—then you will still have what you need. Check the URL in your web browser, and notice the end of it has code={authorization_code}. With that code the application makes a request to https://graph.mapillary.com/token endpoint, in order to exchange the authorization code.
The application then receives user access token and refresh token so it can make the authorized requests on behalf of the user.
Note: Make an authorized request against https://graph.mapillary.com/token endpoint with the refresh token, to receive a new pair of tokens.

 

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)
In Javascript, you can use fetch, or AJAX, among other methods. For example:

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));

Related articles

Comments

0 comments

Please sign in to leave a comment.