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


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:

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.


This is the part I had most trouble with getting right. Mainly because I was over complicating things based on the 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 endpoint. After that the script iterates over all image id’s and requests per image id more detailed information for each image using the{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

The script

import requests
metadata_endpoint = ""
x_dist = 0.00025
y_dist = 0.00025
client_token = 'MLY|4324601697617554|77cecffb3eef9cb3ff0a11471873f03c'
headers= { "Authorization" : "OAuth {}".format(client_token) }
# DOCS: (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:
    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()

5 Replies to “How to get data from the Mapillary API v4 using Python”

  1. Thank you, good work.

    I put fake URL “” in call back url while registering application in mapillary. My application was registered successfully but my client token is not working. Below are details.

    Client Token

    Client ID

    rest of the code i copied from your code,

    Could you help me out.

    Thank you,

    1. Hi Rizwan Ali,

      I tested it with your Client Token and it worked just fine. So that token isn’t the problem.

      I have noticed that while testing code you can get temporarily blacklisted for a couple of hours. So if you try it again at a later moment, it’s possible the same code and token work as intended.

  2. Hi and thank you for your post, really interestin and useful. I noticed that when using a big bb I get some errors

    print(“Images found:” + str(len(data_imagesearch[‘data’])))
    KeyError: ‘data’

    Did you encounter similar problem or do you have an explaination? (I know the limit for the images is 2000 but I expect another type of response)

    1. @Francesco. That error probably means no data is returned from the API. I guess the API doesn’t like big bbox’s. It probably means an error is returned instead of data. You could check by copying the generated url (the value of url_imagesearch) to your browser and see what the result of that is.

  3. Hi and thank you for your post. I wonder if you could provide with your Redirect URL parameter. When I authorized, it always give me an error with Invalid OAuth 2.0 Access Token .

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.