Meet the new Mapbox API documentation
By Lyzi Diamond
Today we’re introducing rewritten, redesigned, and expanded Mapbox API documentation. Drawing from hundreds of conversations with users, we created a new way to look at our APIs with consistent style across all services and prominent examples of integration with our SDKs & CLI.
Truthiness
Nothing is more frustrating than following documentation to the letter but still getting errors. We spent weeks consulting with teams across Mapbox — from geocoding to directions to platform — making sure that every method, example, and token scope in our documentation is correct. Every endpoint, query parameter, and limit is referenced to the code that makes it work, and reviewed by the team that builds the product.
Striving for consistency
Documentation is more than a list of URLs, it’s a piece of English writing that thousands of people will spend hours reading. Little inconsistencies — like referring to JSON as keys or members or properties — add up to a lot of confusion, especially if you’re new to maps or technology. So we examined every word we use, and insisted on consistency. If you learn the lingo for one Mapbox API, you should be comfortable jumping into another one.
And now all the APIs have the same structure whether you’re looking at the Uploads API or the Styles API, you’ll know where to find methods, definitions, and examples.
And it’s not enough to be mechanically precise: we need to be friendly, too. We use content tests to avoid using words like ‘basically’ and instead spend our time explaining and assisting.
New examples
We’re super excited about the Mapbox CLI that we launched last week, and our new JavaScript and Python SDKs. With mapbox on your command line or the library loaded in your application, it’s now much easier to try out an API method. We’ve added examples for every method in our API using cURL, Mapbox CLI, Mapbox JavaScript SDK, and Mapbox Python SDK.
Take a gander!
We think this newest documentation update is a huge improvement, but don’t take our word for it! Check out the documentation for yourself, and show us what you’re building by tweeting at @Mapbox.
