Whenever you enter an address into Google Maps, it will instantly figure out where on Earth it's located. We sometimes take it for granted, and it's not always perfect, but it remains a cool software engineering achievement. This process of converting addresses to a pair of latitude/longitude coordinates is known as geocoding.

There are some interesting use cases for geocoding beyond Google Maps. A food delivery service may want to calculate delivery costs based on the distance between the delivery address and the restaurant, which requires resolving the addresses of both to coordinates. While Google Maps provides a geocoding API for third-party applications, it'll cost you about $5 per 1,000 requests.

But there's no need to pay. Positionstack has a generous free tier allowing 25,000 API requests per month.

To start using their geolocation service, first create an account. When you finish signing up, you'll receive an API key.

Unfortunately, Positionstack does not allow you to issue additional API keys for each of your projects. Per-project keys are a common security practice to make it easier to revoke access in case one of your keys leak. Since Positionstack is a free service, the worst thing that can happen is that your account gets suspended if anyone abuses your key. While better than a massive bill, it's still a good reason to keep your key safe.

With your key in hand, let's try a request! I'm using the excellent command-line tool HTTPie below, but Postman or cURL will work just as well.

❯ http -b get 'http://api.positionstack.com/v1/forward?access_key=[your API key here]&limit=1&query=3%20abbey%20road,%20london'
{
    "data": [
        {
            "administrative_area": null,
            "confidence": 1,
            "continent": "Europe",
            "country": "United Kingdom",
            "country_code": "GBR",
            "county": null,
            "label": "3 Abbey Road, London, England, United Kingdom",
            "latitude": 51.53218,
            "locality": "London",
            "longitude": -0.177866,
            "name": "3 Abbey Road",
            "neighbourhood": "St. John's Wood",
            "number": "3",
            "postal_code": "NW8 9AY",
            "region": "Greater London",
            "region_code": null,
            "street": "Abbey Road",
            "type": "address"
        }
    ]
}

A couple of observations here. In addition to the latitude and longitude, you'll receive a number of other attributes from which you can derive a cleaned version of the address you looked up. These attributes may not be relevant now, but if you ever need to split unstructured addresses into street, number, postal code, locality, and country, they come in handy.

You will get up to 10 results by default. The limit parameter will let you reduce or increase the cap depending on your needs.

We just used Positionstack's forward geocoding service. If you have a latitude/longitude pair that you'd like to resolve to an address, that's possible too. We can use their reverse geocoding API for this purpose. Here's an example for 42.8130,-1.6475.

❯ http -b get 'http://api.positionstack.com/v1/reverse?access_key=[your API key]&limit=1&query=42.8130,-1.6475'
{
    "data": [
        {
            "administrative_area": "Pamplona/Iruña",
            "confidence": 0.8,
            "continent": "Europe",
            "country": "Spain",
            "country_code": "ESP",
            "county": null,
            "distance": 0.033,
            "label": "Entrada al Parking del Baluarte, Pamplona, NA, Spain",
            "latitude": 42.813258,
            "locality": "Pamplona",
            "longitude": -1.647702,
            "name": "Entrada al Parking del Baluarte",
            "neighbourhood": null,
            "number": null,
            "postal_code": null,
            "region": "Navarre",
            "region_code": "NA",
            "street": null,
            "type": "venue"
        }
    ]
}

One major drawback of Positionstack is that the free version does not allow HTTPS requests. The lack of HTTPS support has privacy implications for the addresses you submit. Alternatively, Bing Maps has a developer tier that supports HTTPS, but its usage limit does not reset. In other words: Bing's alternative is more of a trial account than a free tier. On the other hand, Bing has the advantage of being licensed for commercial use - which Positionstack's free version is not. Another free option worth considering is OpenWeatherMap's geocoder, which appears to work up to the municipality level but not down to street level.

There are a few niche features in Positionstack's API that I haven't covered above, so do check their documentation for some interesting nuggets. If you ever needed to, you could even use Positionstack to retrieve the currency or calling code of the location you looked up. Happy geocoding!