Mapillary API: Hello to v3 and Goodbye to v2
Here is what you need to know about migrating to Mapillary API v3 as v2 retires.
Early this year we released Mapillary API v3, which represents the best of the previous versions combined with new functionality to keep up with our growing platform. With over 140 million photos on Mapillary, the latest API gives developers the best way of accessing what Mapillary has to offer, now more than ever. Meanwhile, the sun is setting on Mapillary API v2 after nearly two years. Today we’ll tell you what has changed between these two APIs and how to make sure your code is up to speed.
What’s changed?
There are two prominent changes between v2 and v3. The first is that in v3 we now use GeoJSON format to present geographic resources by default, rather than pinging a specific endpoint as in v2. The second change of note is the end of /search in the API calls. When retrieving images, sequences, or users, it is now assumed that a search is occurring, and we ask only that you specify which of these resources you want to query. The table below shows some before and after examples.
| Resource | API v2 | API v3 |
|---|---|---|
| Sequences | v2/search/s | v3/sequences |
| Images | v2/search/im | v3/images |
| Users | v2/search/u | v3/users |
| Stats | v2/stats/im/toplist | v3/leaderboard/images |
Notice that the stats have changed to a leaderboard, which you can learn more about using here.
There are also some changes to how different parameters are added. The next table has some examples.
| Parameter | API v2 | API v3 |
|---|---|---|
| Username | &user={username} | &usernames={username1},{username2} |
| Bounding box | &min_lon={lon1},&min_lat={lat1},&max_lon={lon2},&max_lat={lat2} | &bbox={lon1,lat1,lon2lat2} |
| Search radius | &distance={number} | &radius={number} |
What’s next?
We already have comprehensive documentation for Mapillary API v3. We also have several examples of how to use the API, including on our blog. New features in API v3 expand the capabilities you have as a developer, a data wrangler, or a casual mapper. Most importantly, API v3 is here to stay as our one and only API. Mapillary API v2 will be deprecated in July, so we encourage you to get familiar with the new documentation and check out our developer resources.
In addition, we’re happy to give visibility to anyone building off of our API. Drop us a note if you’re developing any language-specific API libraries based on Mapillary API v3. We hope to see developers enabled and encouraged by our improvements, and look forward to building the future of maps together.
/Chris & the Mapillary developers