The new API

Mapillary is launching a new API by the end of May 2021, making the transition to the API version 4 and moving on from version 3, which was launched in June 2017. This change will have a broad effect on many applications and developers in the Mapillary universe, and it is our mission to make sure you understand the changes and how to adapt. There are a few key differences between the current API and the future version:

1. API v4 will be built primarily around vector tiles, rather than GeoJSON
2. Images will be queried by tile z/x/y location, rather than a bounding box or radius search
3. Filtering will happen on the client side of the vector tiles (for example filtering image point data by a date range, a set of usernames, or spatial overlap with a polygon)
4. URLs for image JPEGs will not be static, and can be retrieved from the API with a lookup by image key
5. Object detections will no longer be spatial data, but metadata associated with an image key that is available as point data

Goals

The goal of the new API is to provide effective Mapillary developer resources while also operating at increased efficiency and scale. The majority of the Mapillary API clients are interested in small areas of the data and we are optimizing for this by providing two APIs in version 4: vector tiles and entity endpoints.

With this method, most users can query data spatially using vector tiles, then apply detailed filters or look up additional metadata using the entity endpoints. Overall, we aim to provide a more streamlined API that effectively leverages vector tiles as the favored way to access data.

Filtering

Users will filter metadata within vector tiles on the client, using the methods seen in Mapbox JS GL and other JavaScript web mapping libraries. Using libraries such as tilebelt in JavaScript and Polygon Geohasher in Python may also be useful for developers working with the Mapillary API v4. No filters may be sent to the new API, meaning that requests can only be made for a specific tile, or a specific key of an image or map feature. Previous filters from API v3 such as dates, usernames, bounding boxes, or values will be applied by the client in API v4 after the API response is received.

Retiring Mapillary API v3

The Mapillary API v3 will continue working for several weeks after we launch API v4 in May 2021, but will no longer retrieve data that has been uploaded after the API v4 launch date. The upload endpoints in API v3 will no longer be active, and all new image uploads must go through API v4 after launch. Client IDs created for API v3 will not be viable for API v4, and developers must register a new client ID to use API v4. From now until the end of May, API v3 will continue to function, but it is recommended that developers start using the upcoming API v4 sandbox to begin migrating their apps during March, April, and May in order for a seamless transition.

Testing and feedback

We are building this API with our developer users in mind, and that means we want to enable developers to test the API and provide feedback directly to us. A sandbox API will be available in March 2021 for testing, and we want to get it in the hands of volunteer developers. We also want to hear from you about your use cases, pain points, and transition plans. If you are interested in getting access to the Mapillary API v4 sandbox in March, please reach out to us. In the meantime, keep an eye on our blog, newsletter, and social media for further updates, examples, and details about the new Mapillary API.

/Chris