Thread by @lyzidiamond

Welcome to Map University. Today’s topic: using mapping APIs for fun and profit.

“API” stands for Application Programming Interface. It’s a generic term for a set of tools, commands, or communication methods that aid in software development.

In the context of mapping, there are two general types of tools that share this ambiguous term:

- JavaScript APIs, or libraries, which contain a set of functions for making maps and map components e.g. Leaflet
- Web services APIs, aka “REST” APIs, which allow you to connect ...

… to a service running on a server that can do something for you. That can include creating/updating/deleting a resource or taking the info you gave it, calculating something, and sending you back the result.

A good example of a web services API that allows you to access resources is the Mapbox Styles API. These are also called CRUD APIs: CRUD stands for Create, Retrieve, Upload, and Delete. With the Styles API you can create, delete, update, and retrieve a style.

Indeed, when you make a new style in Mapbox Studio, that’s what it’s doing in the background — sending a POST request to the Styles API and telling it to create a new style + put it in the database. When a map loads, a request is made to the Styles API to retrieve a style.

A good example of an API that makes calculations is the Mapbox Directions API — you give it coordinates, it runs calculations on a server and then sends back a response.

Oh yeah, PS, I work at Mapbox if you didn’t know.

So the term “API” refers to these different types of tools, but for the time being we’ll use the term to refer to web services APIs: systems for communicating with a specific server that is doing something useful, like giving you a resource or doing a calculation.

When you create a web map, that map is interacting with at least one API, if not more. You may not have to manage those API requests manually — your web mapping library is probably doing it for you — but they’re happening in the background regardless.

Example time!

I’m sure some of you have seen this beautiful map from @UpshotNYT showing voting precincts from the last election and how they voted: nytimes.com/interactive/20… This map uses Mapbox GL JS, which means in the background it is making requests to Mapbox APIs.

@UpshotNYT One of the cool things you can do in the browser is inspect the network requests that are happening as the page is loading. If I search for “mapbox” in the Network tab of the Chrome Developer Console, I can see all the requests that are being made:

@UpshotNYT All the requests that are being made to Mapbox, that is!

In the image above, you can see a file being requested with a long gibberish looking name: cjixdygm36… If you click on it, you can see the request that was actually made from the browser, via GL JS

This is a request to the Styles API to retrieve the style for the map. Request Method tells us that it was a GET request — aka the “Retrieve” part of a CRUD API. The server knows which style to return because it’s in the URL — nytgeographics/cjixdygm36rt…

You can also see at the end of the request, there is a ? with some text after. These are called query parameters — additional information you can send along with your API request that tells the server to do something additional or give more granularity to your request.

Some APIs rely on query parameters heavily and there are lots of options. Some have fewer. It all depends on how the API is written.

An example of an API with many query parameters is the Mapbox Directions API. (Yes, I’m on the Navigation team, I’m biased, deal with it)

As our documentation demonstrates, there are lots of options you can use to get exactly what you want from the Directions API.

If I want to exclude ferries from a route, I can add exclude=ferry to my request and the route returned will not have any ferry segments.

Obviously, the way you use query parameters depends on the API you’re using and what you’re trying to do. But there are a few general principles to keep in mind when working with APIs:

1. READ THE DOCUMENTATION. The documentation will tell you how to use the API and all of the different knobs you can turn (usually in the form of parameters). The documentation also will tell you what you can expect as a response from the API, which is helpful.

2. You are often not interacting with APIs directly — you are using a library or some other tool (like an SDK — software development kit) to make the request and do something with the response. For each API, learn about how the requests are made and how to customize them.

3. It’s tempting to adapt your application/problem to what is available from the API, but remember that you can always take the response and manipulate it more. If an API will only give you distances in meters and you need them in miles, you can write that calculation.

4. If you need data from an API but don’t want to write code or put that logic into an app, you can use some other fun tools:

- cURL, on the command line
- Postman, a visual UI for making requests and analyze responses getpostman.com

5. Share what you make! If you’re using a query parameter to get a response that better solves your problem, share that info with others! Blog posts are awesome always, your experience is valid whether or not you’re an expert, your voice is an important part of the conversation!

This topic is hard because there are thousands of paths to walk down and things to explore. If you’re interested in learning more of the fundamentals of this, check out this thing I wrote about how the internet works: lyzidiamond.com/explains/how-t…

If you have specific mapping and/or API questions, let me know and I can answer them!