Finding coordinates for an address

There are times when you have an address or just a city or a country, and you try to find the coordinates (latitude and longitude). The reverse is also true; you may have the latitude and longitude and want to get an address. This process is called geocoding.

Reverse geocoding is useful if, for example, we create a marker using the latitude and longitude and want to show the marker's address. Mapbox services also give you the ability to get the coordinates (latitude and longitude) from an address; this process is called forward geocoding.

How to do it…

The following steps need to be performed:

1. Construct a GET request by specifying the master source and query.
2. Paste the request in the browser or in a REST client.

   You will get back a JSON with coordinates that match your query.

The format of the requests has to be similar to the following:

{dataset}/{lon},{lat}.json?access_token=<your access token>

A complete request will look similar to the following example:

http://api.tiles.mapbox.com/v4/geocode/mapbox.places-v1/OConnel+Dublin+Ireland.json?access_token=pk.eyJ1Ijoibmltcm9kNyIsImEiOiJkNkw1WWRnIn0.pnQn9P2nbHyhKf2FY_XJog

If you try to execute the query as it is here, you will notice that the geocoder returns an array of results sorted by relevance, which is also the key name that has a float value. The result appearing at the top is the one that matches your query the most and has a higher value, while the others may have partial matches with your query:

How it works…

We will look at it from two perspectives.

Query parameters

The first question to ask yourself is, what do you need exactly from the Mapbox services geocoder? You may need just postcodes, or addresses, or the full stack, including every detail for the specified coordinates.

First of all, let's dissect a forward geocoding request:

http://api.tiles.mapbox.com/v4/geocode/{master-source}/{query}.json?access_token=<your access token>

The parameter to choose what you want back from the geocoder is called a master source.

The available master sources are the following:

• mapbox.places-v1: This sends back every detail, including address, province, postcode, and so on.
• mapbox.places-country-v1: This sends back just the countries.
• mapbox.places-province-v1: This sends back the provinces.
• mapbox.places-postcode-v1: This sends back the postcodes. Postcodes are separated by country; for example, you can use mapbox.places-postcode-fr-v1 to get back postcodes in France or mapbox.places-postcode-uk-v1 to get back postcodes in the UK.
• mapbox.places-city-v1: This sends back places, such as cities.
• mapbox.places-address-v1: This sends back addresses.

The next parameter we need to know is the query itself. The query can be as detailed as you want; for example, you can just specify Ireland as a parameter, the city Dublin through Dublin+Ireland, O'Connel street through OConnel+Dublin+Ireland, or the street number 432 through OConnel+432+Dublin+Ireland.

Depending on the accuracy of the query, the geocoder may return a single result or multiple results as an array that matches the criteria you specified.

Returned results

You have probably noticed that this is the first time that we will get back data instead of images. There is an important parameter in each request that defines the kind of format Mapbox services will return to us.

The most common formats returned by REST services are XML (Extensible Markup Language) and JSON (JavaScript Object Notation).

XML used to rule the world, but most services these days use JSON, which is faster to submit and easier to process and read. Mapbox services, at the moment, support only the JSON format.

Let's examine a partial JSON response from the geocoder, as follows:

{
            "id": "city.10560743",
            "type": "Feature",
            "text": "Dublin",
            "place_name": "Dublin, Dublin City, Ireland",
            "relevance": 0.48,
            "center": [
                -6.300364,
                53.333637
            ]
}

You will notice that there are curly brackets {} and square brackets []. The latter represents an array of values, while the curly brackets represent an object. Each object may include other arrays, objects, or just key-values.

Note

Key-values are represented with the key first, then with a double colon (:), and then with the value; here, the value may be a string, integer, float, or array. Using this specific format is very easy and efficient because you can simply ask to get the value using a key, which is the same in every request.

Using the preceding example, you can get the place name simply using this specific key, and the returned object will be "Dublin, Dublin City, Ireland" or the relevant value for other similar requests.