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 three different endpoints:

  • images for accessing imagery
  • image_detections for accessing object detections in images
  • map_features for accessing map features

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

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

 

API endpoints and permissions

There are two modes of authentication:
  • with a client_id only
  • client_id plus token (via OAuth)

The images API is accessed as https://a.mapillary.com/v3/images and requires only a client ID for authentication to access public imagery, worldwide. For accessing private imagery, client ID together with a token is required. (More on that below.)

Accessing any data under the endpoints map_features and image_detections requires client ID together with a token. This is because map data is tied to data subscriptions of an organization on Mapillary, so there needs to be a check whether the organization and its respective members have been granted access to map data.  Furthermore, the client_id 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 ID to view public images, whether his own or anybody else’s. To access his own privately hosted images, he must generate a client ID with private access enabled. To access his subscription to map features or object detections inside the shape of the city, he must use a client ID with private access enabled, plus generate a token to go with it.

Setting up API access and obtaining a client ID

To access public imagery, private imagery, map features, or object detections via the API, the first step is to create a client ID. 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 ID 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.

 register_application.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 your access token.

If you want to use your client ID to access private imagery or map data (map features or object detections), make sure you enable private:read on the options (also called “scopes”), which will allow the client ID to access private data—including data you’ve subscribed to, which is available to only your user account or organization.

permissions.png

Once all your information is complete, click Register.

Now the client ID 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 ID column, click copy to copy the client ID to the clipboard.

 

Obtaining a token to access private imagery and map 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.

The following URL is going to be our model for retrieving a token, which together with the client ID will allow API access.

 

https://www.mapillary.com/connect?scope=private:read&client_id=<client_id>&redirect_uri=<callback_url>&state=return&response_type=token
There are two parts we will replace: <client_id> and <callback_url>. If my client ID is xyz123 and my callback URL is https://mapillary.com, then I will have the following URL:
https://www.mapillary.com/connect?scope=private:read&client_id=xyz123&redirect_uri=https://mapillary.com&state=return&response_type=token
Paste this URL into your browser, and it will ask you to log in to your Mapillary account and authorize Mapillary.

authorization.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 token_type=bearer and &access_token=. The access token is provided after that second part. Copy down that access token, and save it somewhere alongside your client ID. You are now ready to access the API.

 

Accessing the Mapillary API

A Mapillary API call requires that you include a client ID 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

client = 'xyz123' # create your client ID at https://mapillary.com/developer
token = 'ey11hhamkHHAD1666'
bbox = '32.53301,0.31393,32.59631,0.37726' # bounding box, use lon1,lat1,lon2,lat2 in format of [lower left, upper right] AKA [southwest, northeast]

# omit the bbox if you want to retrieve all data your account can access, it will automatically limit to your subscription area
url = 'https://a.mapillary.com/v3/image_detections?layers=segmentations&bbox={}&client_id={}&per_page=1000'.format(bbox,client)
headers= { "Authorization" : "Bearer {}".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 client = 'xyz123'; // create your client ID at https://mapillary.com/developer
const token = 'ey11hhamkHHAD1666';
var bbox = '32.53301,0.31393,32.59631,0.37726'; // bounding box, use lon1,lat1,lon2,lat2 in format of [lower left, upper right] AKA [southwest, northeast]
var api_url = 'https://a.mapillary.com/v3/image_detections?layers=segmentations&bbox=' + bbox + '&client_id=' + client + '&per_page=1000';

const response = await fetch(api_url, 
 { headers: 
 {'Authorization' : 'Bearer ' + token} 
 }
);
const myJson = await response.json();
console.log(JSON.stringify(myJson));
Sometimes your data will come in multiple pages, while only 1,000 items are returned on a single page. In this case, you will need to use pagination, which we describe here. To retrieve multiple pages of data, this script can be helpful.

Related articles

Comments

0 comments

Please sign in to leave a comment.