Introduction

Mapbox web services are the lowest-level API available on the platform. Every other API and functionality provided by Mapbox, such as the JavaScript API or Mapbox.js, is based on services. It uses GET REST calls to fetch the data you require from Mapbox servers.

REST services are based on HTTP verbs to perform certain actions, such as reading, creating, updating, and deleting records. GET requests are used to read data from the server; PUT requests are used usually to update data; POST requests are used to create a new record; and DELETE requests are used to delete a record. The Mapbox API is a read-only one, so we only have access to GET requests to read data.

Mapbox supports both HTTP and HTTPS secure connections. When the REST call is invalid, the server responds with the relative HTTP error code and a message in plain text, not a JSON object as usual.

Access tokens

To get access to the services, we will need an access token. We discussed access tokens in Chapter 1, Introduction to Mapbox, when we created a new project. This is a good moment to explain what an access token is.

Access tokens are unique to each account and our ticket to using Mapbox services and APIs. To be able to fetch data from Mapbox servers, the server has to identify us somehow, and providing our credentials is not a proper way to do this.

Using an access token, Mapbox knows which user is requesting data, which services are available to this user, and the bandwidth he/she uses. We are not supposed to share or publish access tokens. They should remain hidden at all costs; however, unfortunately, this is not always possible because in some cases—for example, when using JavaScript—the code, and therefore the access token, is included in the code and is easily accessible.

For this reason, Mapbox provides two different access tokens: the public access token and the secret access token. We use the public access token in places that will be exposed to the public; it is easy to access and replace. A secret access token is supposed to be used in places that remain secure and hidden, such as PHP code that will be evaluated on the server side or apps that will be compiled; changing it requires us to go through an approval process.

In the Projects dashboard, you may already have seen the public access token:

Clicking on the API access token link will open the Apps page, where you will find your secret access token:

Note

In this screen, you can find a list of applications that use the tokens.

You can also generate a new access token by clicking on the New token button in the middle of the screen. A window will open, allowing you to generate a public or secret access token, and in case of a secret token, you can define the scope.

Finding the Map ID

The second element that we need to use throughout this chapter is the Map ID. Each time we create a new map using Mapbox, it has a unique Map ID, and each time we perform a request, we have to pass the Map ID to tell Mapbox which map we are interested in.

You can find your Map ID in two different places:

• In the Projects dashboard, the Map ID is displayed directly below your map's name, and you can click on the clipboard icon next to it to copy it
• In Mapbox Editor, you can find it in the Project tab: