How to get data from the Mapillary API v4 using Python

A while ago I wrote a script to get data from the Mapillary API v3 and that was pretty easy to do so. But in the mean time v3 of their API was discontinued, so I had to rewrite my script to use v4 of the API, but it took me a while to figure out how to talk to the v4 API using Python.

Below you can find a simple example of how to get info on available images around a certain longitude and latitude. Of course you can incorporate this concept into a larger script to get data from multiple points, that can for example be stored in a database. But for this example we’ll just request info on available Mapillary imagery for one set of coordinates and show the information.

Get a Client Token from Mapillary

If you want to get data from the Mapillary API v4 you need a Client Token. If you used an older version of the API, you will need to register a new application, because for example v3 tokens are not valid in the v4 API.

To get a Client Token you will need to register an application on https://www.mapillary.com/dashboard/developers. On that page you’ll find a button to register your application that opens a form that’s pretty self explanatory. Only the field “Callback URL” needs a little extra explanation. For our Python script this setting is not important, but it’s obligatory to fill in. It can contain any url, but if you want to see the results from the Authentication URL you can for example create a php file like the one below on a webserver and set the url of this script in the registration form.

<pre><?php print_r($_REQUEST); ?></pre>

callback.php

Your application only needs to be allowed to read for this example, but you can also make scripts to write or upload tot he Mapillary database.

If you registered your application, you can find your Client Token on your Developers Page on the Mapillary website: https://www.mapillary.com/dashboard/developers.

Your Client Token will look more or less like this example: MLY|52245453646433553|56cfcfab8eaf2cd3af2a51651879b23d

Make sure you use your own generated ClientToken, because the token above is a fictional example, that won’t work.

The example Python script

In the script there are some parts that need a little extra explanation. so I will first cover the topics bounding box, headers and JSON results and after that explain the general concept of the script and show you the complete example script

Bounding box

In this example we’ll request data on imagery that are close to an example point. By default in v4 of the API there is no longer a CloseBy request type. But instead you can call for data on imagery inside a bounding box. To define a bounding box you need 4 values:

• Minimum longitude
• Minimum latitude
• Maximum longitude
• Maximum latitude

To “create” this bounding box in the example I take the input point and add or subtract a certain value from the coordinates of that point to get the 4 values that are needed for the bounding box. In the example I use the variables x_dist and y_dist as the values that are added or substracted. I set both values to 0.00025°, but you can adjust this to your needs. One thing to keep in mind is that the API will return a maximum of 2000 images inside your bounding box. So if your bounding box is too big, you won’t get all available data.

Headers

This is the part I had most trouble with getting right. Mainly because I was over complicating things based on the API documentation (https://www.mapillary.com/developer/api-documentation/). That resulted in getting a lot of “500” errors because I couldn’t get my request authenticated. But actually the correct way to do it is pretty simple and only requires to set the header value “Authorization” to “OAuth  MLY|52245453646433553|56cfcfab8eaf2cd3af2a51651879b23d“. Of course you need to use your own Client Token and not the example token. You don’t need the “OAuth 2.0” workflow from the documentation.

JSON results

The API will return a JSON file as the result of your request. In this example I convert that JSON response into a dict using json(). That makes it easy to iterate over results.

The basic concept of the script

The first thing the script does, is collect all image id’s that are inside our bounding box using the https://graph.mapillary.com/images endpoint. After that the script iterates over all image id’s and requests per image id more detailed information for each image using the https://graph.mapillary.com/{IMAGE_ID} endpoint. For this second part you can select the fields it has to return from the Mapillary database. In the example I request the fields id, thumb_2048_url, captured_at and sequence. A description of all available fields can be found on https://www.mapillary.com/developer/api-documentation#image.

The script

import requests
metadata_endpoint = "https://graph.mapillary.com"
x_dist = 0.00025
y_dist = 0.00025
testpoint=[51.1543669,4.4436676]
client_token = 'MLY|4324601697617554|77cecffb3eef9cb3ff0a11471873f03c'
headers= { "Authorization" : "OAuth {}".format(client_token) }
# DOCS: https://www.mapillary.com/developer/api-documentation/#image (see "Image search")
url_imagesearch = metadata_endpoint+'/images?fields=id&bbox= {},{},{},{}'.format(testpoint[1]-x_dist, testpoint[0]-y_dist, testpoint[1]+x_dist, testpoint[0]+y_dist)
response_imagesearch = requests.get(url_imagesearch, headers=headers)
data_imagesearch = response_imagesearch.json()
print("Images found:" + str(len(data_imagesearch['data'])))
for image in data_imagesearch['data']:
    # DOCS: https://www.mapillary.com/developer/api-documentation/#image
    url_image = metadata_endpoint+'/{}?fields=id,thumb_2048_url,captured_at,sequence'.format(image['id'])
    response_image = requests.get(url_image, headers=headers)
    data_image = response_image.json()
    print(data_image)

test.py