Overview

Mapillary API v3 is meant to enable developers to create their own Mapillary apps or integrate Mapillary with their systems as easily as we do. It lets you manage resources such as images, sequences, map objects, image detections, etc. in a programmatic way. With a little programming, you can do things that are difficult or impossible to do with the website interface. For example, to know which camera brands are popularly used by a local Mapillary community, you can fetch all photos with API v3, and examine their camera_make property in your code.

Other than the data contributed to Mapillary, we also offer automatically detected segments from images as well as recognized objects on the map through API v3. With API v3 you can select traffic signs in a bounding box or filter images that have trees detected in a consistent way. Edits are another important resource we'd like to provide. When this gets integrated with GIS tools such as QGIS or ArcGIS, you should be able to upload changes you made locally, or review changes with your favorite GIS tool.

API v3 response visualised: detections within a bounding box

We like GeoJSON; it is simple and well supported. Whenever possible, we use GeoJSON to represent resources that can be shown on the map (e.g. images, map objects and image detections). We believe this facilitates integrating API v3 with open map platforms like Mapbox GL, Leaflet, and OpenLayers.

API v3 supports simple filters to search for resources of interest. For example, you can get all images in your city by specifying the bounding box of your city, or images captured by specified users, or images that are “looking at” a point (i.e. the photos have been taken in the direction of a specified point, and therefore that point is likely to be visible in the images). Combining these filters, you will get more powerful usages. Below we will give some concrete examples.

Getting started

If you're interested to quickly check it out, just start playing with the command lines and demos below. However, to get started seriously, you need to register an application, and refer to the API v3 documentation for more information.

Examples

Here is a Mapillary API v3 demo page to visualize your API response:

https://bl.ocks.org/ptpt/raw/bd2097d1e8c1f480d5dcc87cb687f313/

You can try to copy and paste the following examples either in the demo page or in your console to see how it works.

• Images in a bounding box that are "looking at" a point:

  curl "https://a.mapillary.com/v3/images/?lookat=12.9981086701,55.6075236275&bbox=12.9981086701,55.6075236275,13.0006076843,55.6089295863&client_id=TG1sUUxGQlBiYWx2V05NM0pQNUVMQTo2NTU3NTBiNTk1NzM1Y2U2"

• The closest image to a point within 100 meters:

  curl "https://a.mapillary.com/v3/images/?closeto=13.0006076843,55.6089295863&radius=100&per_page=1&client_id=TG1sUUxGQlBiYWx2V05NM0pQNUVMQTo2NTU3NTBiNTk1NzM1Y2U2"

• Images close to a point within 100 m radius, and also "looking at" another point:

  curl "https://a.mapillary.com/v3/images/?lookat=12.9981086701,55.6075236275&closeto=13.0006076843,55.6089295863&radius=100&client_id=TG1sUUxGQlBiYWx2V05NM0pQNUVMQTo2NTU3NTBiNTk1NzM1Y2U2"

• Sequences taken by a list of users:

  curl "https://a.mapillary.com/v3/sequences/?userkeys=2BJl04nvnfW1y2GNaj7x5w,LmlQLFBPbalvWNM3JP5ELA&client_id=TG1sUUxGQlBiYWx2V05NM0pQNUVMQTo2NTU3NTBiNTk1NzM1Y2U2"

• Objects/detections within a bounding box:

  curl "https://a.mapillary.com/v3/objects/?bbox=12.9981086701,55.6075236275,13.0006076843,55.6089295863&client_id=TG1sUUxGQlBiYWx2V05NM0pQNUVMQTo2NTU3NTBiNTk1NzM1Y2U2"


  curl "https://a.mapillary.com/v3/detections/?bbox=12.9981086701,55.6075236275,13.0006076843,55.6089295863&client_id=TG1sUUxGQlBiYWx2V05NM0pQNUVMQTo2NTU3NTBiNTk1NzM1Y2U2"

Future

As it is the first version of API v3, we manage to keep things simple. There are still lots of work to do to achieve a simple, flexible and powerful API. Here are some of our high priorities ahead.

• Add more filters — e.g. panorama filter, username filter.
• Add more sub-resources — e.g objects of a user, image detections of an image.
• Support more operations — e.g. upload or update images.
• Support more media types — e.g. when you request an image with Content-Type: image/png we would redirect you to the link to download the image file.

Happy hacking!

/Tao and the Mapillary team