Global access to map data with the Mapillary API
As we announced just a couple of weeks ago, Mapillary’s map data is now available for free, globally, to everyone. This also means that you can access map features and object detections via our APIs anywhere in the world, without a subscription, at no cost. In this post, we will summarize how to access and use imagery and map data via the Mapillary REST APIs.
The Mapillary API has three key parts for downloading data: the images API, the object detections API, and the map features API. Each one of these offers a different type of data, but is accessible with a single client ID.
Register a client ID
The first step to get access to Mapillary data is to generate a new client ID. If you don’t already have a Mapillary account, you can sign up here. Next, you’ll need to open the side panel on mapillary.com/app/, and click the white dashboard icon.
Access the dashboard following the link near your profile.
On the left side menu of the dashboard, you will see a Developers option. Click on it, and you’ll see a list of registered applications, probably empty if you’ve never created a client ID before. At the top right, you will click Register Application in order to create a client ID.
Register new client IDs or view existing client IDs in the developer dashboard.
A window will pop up, asking you to input some basic information. ~~Most of this is very flexible and for your own reference, and it’s up to you how you want to fill it out.~~ Your app name and description can be handy if you start registering multiple client IDs, and the callback URL is only needed if you will be doing authentication, such as allowing users to log in with their own Mapillary account inside of a web app. Finally, we do not need to allow access with any scopes, so all can be left disabled.
Fill in the form to register a client iD.
Once you’ve entered all the information, you can click Register and the client ID will be saved. Now on the dashboard, you need to click View on the client ID and then copy it to the clipboard. The next steps will depend on how you want to access the API. No matter what method you choose, you will be using the client ID to construct an API call.
Construct an API URL
The basic building block of any API call starts with:
Next, we need to specify which API is being accessed. The three options are:
https://a.mapillary.com/v3/images/
https://a.mapillary.com/v3/object_detections/
https://a.mapillary.com/v3/map_features/
In the query string, we need to then add our client ID. Let’s assume the client ID is xyz123abc456, then we can access these APIs as:
https://a.mapillary.com/v3/images?client_id=xyz123abc456
https://a.mapillary.com/v3/object_detections?client_id=xyz123abc456
https://a.mapillary.com/v3/map_features?client_id=xyz123abc456
Each of these three URLs will now access the API, whether you are using the browser, the command line, or making a request in Javascript, Python, or another coding language. Next, we’ll look at the search parameters accepted by each of these to help you retrieve the data you need.
Images API
The images API is best accessed using a spatial filter, which can be either a radius search or a bounding box. Other search parameters can include username, date, camera make or model, or whether or not the image is a 360-degree panorama. For example, to find images in London near Hyde Park with a default search radius of 200 meters and default maximum number of 200 images returned:
https://a.mapillary.com/v3/images
?client_id=xyz123abc456&closeto=-0.1624,51.5114
And to search in a 500 meter radius, for up to 1000 images, which are only 360 degree panoramas, in July 2019:
https://a.mapillary.com/v3/images?client_id=xyz123abc456
&closeto=-0.1624,51.5114&radius=500&start_time=2019-07-01
&end_time=2019-07-31&per_page=1000&pano=true
Make sure to see the documentation for more examples and definitions. All data is returned as a GeoJSON and can be saved as such.
Object detections API
The object detections API offers a way to query by the content of images. Each returned item is an object detection, and not an image. A search for sidewalks, for example, may yield several unique detections from different sections of the same image, and will have the same geographic coordinates, but unique pixel coordinates. This API requires setting one of three layers: traffic signs, segmentations (sections of the image with a particular classification, such as vegetation with no particular point location), or instances (unique points).
As an example, we’ll look for images in a bounding box encompassing Mexico City’s Zocalo which contain instances of benches:
https://a.mapillary.com/v3/object_detections/instances
?client_id=xyz123abc456&values=object--bench
&bbox=-99.13418769836426,19.431983303542843
,-99.1321277618408,19.433258127527285
The API returns a geojson response that includes the geographic location of the image that contains the detection, but not the specific location of the detected object. See more about this API in the documentation, which also includes examples of different types of values that can be used to filter.
Map Features API
Unlike the images and object detections APIs, the map features API returns locations of objects as point features on the map extracted from multiple images, rather than the location of the images. This API also requires setting a layer, either traffic signs or points. Traffic signs include point data for objects such as stop signs or speed limit signs, while the points layer includes a general category of objects such as bicycle racks, benches, crosswalks, street lamps, and utility poles. Each of these points is extracted from a composite of multiple images, and represents the predicted location of that object on the map.
For our final example, we’ll look at an API call to the map features API to retrieve fire hydrants from the points layer in Wellington which were first seen on November 1, 2017 or later. We’ll use a radius search of 5 kilometers which will be provided in meters:
https://a.mapillary.com/v3/map_features?client_id=xyz123abc456
&layers=points&closeto=174.77977752685547,-41.29389809542171
&radius=5000&values=object--fire-hydrant&start_first_seen_at=2017-11-01
Open Access
All of the data in these APIs is available for personal, community, and commercial use. You only need a client ID to get started, and if you’re looking at getting larger volumes of data you can consider creating a shape on the Mapillary platform, or using pagination in the API. You may be also interested in using this Jupyter Notebooks tutorial to get started, but keep in mind that a token and authentication are no longer required to access the APIs. When building anything with Mapillary, remember that your use of Mapillary services is governed by our terms and our Developer Usage Policy.
We’re excited to provide our imagery and data to anyone anywhere, and we can’t wait to see what new projects will be built on top of it. Feel free to share your ideas with us, as we love to see what developers and geospatial enthusiasts are doing with Mapillary in the wild!
/Chris