The Mapillary v3 API is being shutdown on August 18. Here’s a summary of the updates we’ll need to make to our software as a result.
Since Facebook’s acquisition of Mapillary last year the Facebook team have been making some fairly significant changes to the backend infrastructure of the platform and how they expose it.
Part of this includes a brand new version of their API.
Our apps, rely heavily on various Mapillary API endpoints.
As some of the new API documentation is yet to be published by Mapillary and the shutdown of v3 on August 18, 2021 is rapidly approaching (evolving Mapillary API v4 documentation here), I wanted to use this weeks post to document our migration path from v3 to v4, should it prove useful to anyone else.
Mapillary have removed all v3 API documentation from their site, luckily the Wayback Machine allowed me to cross-reference the old docs.
Authorization
This still follows an Oauth 2.0 flow in v4, as was the case in v3.
The endpoint for the Oauth 2.0 token exchange remains identical between v3 and v4: https://www.mapillary.com/connect.
Mapillary JS
MapillaryJS is an interactive street imagery and semantic mapping visualization platform on the web. It takes spatial, semantic, and texture data and renders it using JavaScript and WebGL. MapillaryJS can be augmented and extended with custom rendering, animation, camera controls, interactivity, and data providers.
We use Mapillary JS for the core navigation between images in our web apps.
Mapillary JS is also used by us to create shapes for manually tagging images.
The jump for v3 to v4 brings in a lot of new features round 3D content… something we’re very interested in exploring in the future… but the core components for our current usage remain largely unchanged.
Importing Images
Users of our software can import sequences from Mapillary.
Importing images allows users to add metadata to the sequences (e.g. type of transport used to capture them) and group them together (e.g. create tours) for users to browse.
The root endpoint for getting images/sequences has changed and requires updating:
- Old:
https://a.mapillary.com/v3/images/https://a.mapillary.com/v3/sequences - New:
https://graph.mapillary.com/:image_id?sequence_id=XXX
It should also be noted that the images response for v4 no longer provides user (at time of writing) the URL to download the original image uploaded (as existed in v3), providing only a processed 2048 wide image (thumb_2048_url).
Mapillary Image Upload
Not much has changed here between v3 and v4, beyond a different endpoint;
- old:
https://a.mapillary.com/v3/me/uploads/ - new:
https://rupload.facebook.com/mapillary_public_uploads
Whilst this new endpoint is not documented at the time of writing, it’s fairly easy to understand using the logic written into Mapillary Tools, Mapillary’s own command line upload tool.
The actual upload flow, beyond endpoint change, remains unchanged between v3 and v4:
- open upload session
- start upload using users Oauth token
- close upload session
Mapping Images / Sequences
All our map views call images from the Mapillary API. Our map views show a mix of:
- imported imagery from Mapillary
- images not imported but exist on Mapillary
Using v3 of the Mapillary API we used a mix of image and sequence endpoint searches to return results in a an area (bounding box, bbox) to place on the map.
This has been completely replaced with a vector tile endpoint in v4 (https://tiles.mapillary.com).
Querying bboxes in v3 was very expensive in terms of number of API calls. Vector tiles in v4 provide a much easier way to visualise the vast amounts of results usually returned by such searches.
Mapillary vector tiles follow the Mapbox tile specification.
Chris Beddow shows a nice example of querying the tile endpoint on the Mapillary blog here.
The endpoint for coverage tiles is https://tiles.mapillary.com/maps/vtp/mly1_public/2/{z}/{x}/{y}.
Mapillary Detections / Features
We have used Mapillary detections and features in some of our tools
For our usage, the changes are not significantly different between v3 and v4.
Features
If we know the ID of a map feature, we can retrieve information about it using the same method as images. For example, with map feature ID 852766358956987 we can find out what type it is (traffic sign or point), the value, the timestamp of the first image to capture it, and the geometry of the point:
Curl -H “Authorization OAuth: MLY|XXX” https://graph.mapillary.com/852766358956987?fields=id,object_value,object_type,geometry,first_seen_at
The response is a JSON object:
{ "id": "852766358956987", "object_value": "object--street-light", "object_type": "mvd_fast", "geometry": { "type": "Point", "coordinates": [ 55.616435388977, 12.99796317955 ] }, "first_seen_at": "2013-11-01T10:41:56+0000" }
A small note; for our use-case, we lookup features on a per image basis (we only display features when a user is viewing a single image). However, I should also point out that to search for features in a given map area (not single image), the tile endpoint is what you need: https://tiles.mapillary.com/maps/vtp/mly_map_feature_point/2/{z}/{x}/{y}.
Object Detections
With an image key in mind, you can also make a request to get all detections in the image. This is achieved by making the same basic API request as previously demonstrated, but adding /detections. For detections, we also should specify fields which we want in the response data, such as value which describes what the detection’s class is, and created_at which is the timestamp when the detection was derived from the image. If a field is not specified, it will be excluded from the response data. Recycling our last example, we can make this request:
Curl -H “Authorization OAuth: MLY|XXX” https://graph.mapillary.com/1933525276802129/detections?fields=id,value,created_at
This will return a list of detections, each a JSON object:
{ "id": "1942105415944115", "value": "regulatory--no-parking--g2", "created_at": "2021-05-20T17:49:01+0000" }
Similarly, you can make the same request with a map feature ID rather than an image ID, and get a list of detections that were used to compose the map feature.
There’s more…
This post only covers our use-cases, and not everything possible using the Mapillary v4 API.
Keep an eye on the Mapillary official documentation. The team at Mapillary are making regular changes and updates to it.
Never miss an update
Sign up to receive new articles in your inbox as they published.
Discuss this post
