Try the Reverse Geocoding demo

Call the Reverse Geocoding API in your application

This guide will help you convert geographic coordinates to addresses in no time!

🔑

Do You Have Your Access Token?

Before you proceed, ensure you have your access token at hand. Can't find your token? No worries — our guide will assist you in either creating a new one or finding your existing token.

1. Making Your First API Call

We have a set of coordinates at hand: latitude 48.8584 and longitude 2.2945. Let's find out what notable place these coordinates point to!

Use the following URL to make the API call to the Reverse Geocoding API:

https://us1.locationiq.com/v1/reverse?key=YOUR_ACCESS_TOKEN&lat=48.8584&lon=2.2945&format=json

curl "https://us1.locationiq.com/v1/reverse?key=YOUR_ACCESS_TOKEN&lat=48.8584&lon=2.2945&format=json"

For a hands-on experience, click here to make the API call right from your browser. Just replace YOUR_ACCESS_TOKEN with your token.

Sample Response

If all goes well, you'll receive a response in JSON format, which will look something like:

{
    "place_id": "123456",
    "licence": "https://locationiq.com/attribution",
    "lat": "48.8584",
    "lon": "2.2945",
    "display_name": "Eiffel Tower, Avenue Anatole France, Quartier du Gros-Caillou, Paris, Île-de-France, Metropolitan France, 75007, France",
    ...
}

The coordinates point to the iconic Eiffel Tower in Paris, France. The display_name value gives us the full address of this landmark.

3. Implement in Your Application

You can now use these coordinates to place a marker on a map in your application or for any other purpose that requires the geographic coordinates of an address.

4. Read the API Reference for more

You can tweak API responses to return less or more details, in a different format or apply additional cleaning by using additional parameters. Check the full API reference for more details.

Tips & Best Practices

• Endpoint Selection: Always choose the endpoint (us1 or eu1) closer to the majority of your user base for faster response times.
• URL Encoding: Ensure that the address string is URL encoded, especially if it contains special characters or spaces.
• Rate Limits: Be aware of the API rate limits. If you're making frequent requests, consider caching results to reduce redundant calls and retry failed requests after a short while.
• Multiple Results: The API can return multiple results for ambiguous queries. Ensure your application can handle and appropriately display multiple geocoding results.

Brief Overview of Request / Response Parameters

The information presented below is a condensed summary. For a more detailed and exhaustive list of parameters, refer to API Reference Page.

Request

Requests can be sent to any of the following endpoints

Region 1: US

https://us1.locationiq.com/v1/reverse?key=YOUR_ACCESS_TOKEN&lat=LATITUDE&lon=LONGITUDE&format=json

Region 2: Europe

https://eu1.locationiq.com/v1/reverse?key=YOUR_ACCESS_TOKEN&lat=LATITUDE&lon=LONGITUDE&format=json

Request Example

curl --request GET \
     --url 'https://us1.locationiq.com/v1/reverse?lat=51.5233879&lon=-0.1582367&format=json&key=kiara' \
     --header 'accept: application/json'

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://us1.locationiq.com/v1/reverse?key=YOUR_ACCESS_TOKEN&lat=-37.870662&lon=144.9803321&format=json",
  "method": "GET"
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

import requests

url = "https://us1.locationiq.com/v1/reverse"

data = {
    'key': 'YOUR_ACCESS_TOKEN',
    'lat': '-37.870662',
    'lon': '144.9803321',
    'format': 'json'
}

response = requests.get(url, params=data)

print(response.text)

<?php

$curl = curl_init('https://us1.locationiq.com/v1/reverse?key=YOUR_ACCESS_TOKEN&lat=-37.870662&lon=144.9803321&format=json');

curl_setopt_array($curl, array(
  CURLOPT_RETURNTRANSFER    =>  true,
  CURLOPT_FOLLOWLOCATION    =>  true,
  CURLOPT_MAXREDIRS         =>  10,
  CURLOPT_TIMEOUT           =>  30,
  CURLOPT_CUSTOMREQUEST     =>  'GET',
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Required Parameters

Frequently used parameters (optional):

📘

Note

List of all input parameters available on the API Reference page

Response

📘

Compatibility

This version (v1) of our Reverse Geocoding API is compatible with OpenStreetMap's Nominatim Geocoder in both JSON & XML formats. However, all our enhancements such as additional datasets and algorithms are supported only in json or xmlv1.1 format options.

Response Example

{
  "place_id": "60310287",
  "licence": "https://locationiq.com/attribution",
  "osm_type": "node",
  "osm_id": "5568763423",
  "lat": "51.5233879",
  "lon": "-0.1582367",
  "display_name": "221B Baker Street, Baker Street, Marylebone, London, Greater London, England, NW1 6XE, United Kingdom",
  "address": {
    "attraction": "221B Baker Street",
    "road": "Baker Street",
    "suburb": "Marylebone",
    "city": "London",
    "state_district": "Greater London",
    "state": "England",
    "postcode": "NW1 6XE",
    "country": "United Kingdom",
    "country_code": "gb"
  },
  "boundingbox": [
    "51.5233379",
    "51.5234379",
    "-0.1582867",
    "-0.1581867"
  ]
}

Response Parameters

📘

Note

List of all response parameters available on the API Reference page

Other Ways to Access Reverse Geocoding

• Interactive Playground (demo)
• Google Sheet (no-code option)