Search / Forward Geocoding

Forward Geocoding is the process of converting addresses (like "Statue of Liberty, New York") into geographic coordinates (latitude and longitude), allowing you to place markers on a map, tidy mismatched or incomplete addresses, optimize delivery routes, enhance customer profiling, and offer location-specific promotions.

Try the Forward Geocoding demo


Call the Forward Geocoding API in your application

This guide will help you convert addresses into geographic coordinates 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

To geocode the address "Statue of Liberty, New York", use the following API call in curl or open the URL in your browser:

https://us1.locationiq.com/v1/search?key=YOUR_API_KEY&q=Statue%20of%20Liberty,%20New%20York&format=json
curl -G "https://us1.locationiq.com/v1/search?key=YOUR_API_KEY&q=Statue%20of%20Liberty,%20New%20York&format=json"

Replace YOUR_API_KEY with the API Access Token you obtained in the previous step.

2. Sample Response

You'll receive a response in JSON format, which will look something like:

[  
  {  
    "place_id": "123456",  
    "lat": "40.689247",  
    "lon": "-74.044502",  
    "display_name": "Statue of Liberty, New York, USA",  
    ...  
  }  
]

The key details here are the lat and lon values, which represent the latitude and longitude of the Statue of Liberty.

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.

πŸ“˜

Compatibility

This version (v1) of our Search 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.


Request Types

TypeEndpointDescription
Free-Form Queryhttps://us1.locationiq.com/v1/searchDefault way to Forward Geocode
Structured Geocodinghttps://us1.locationiq.com/v1/search/structuredTo be used if address can be bucketed into distinct address components
Postal Code Searchhttps://us1.locationiq.com/v1/search/postalcodeTo be used when only a postal code match is necessary.

Request

Requests can be sent to any of the following endpoints

Region 1: US

https://us1.locationiq.com/v1/search?key=YOUR_ACCESS_TOKEN&q=SEARCH_STRING&format=json

Region 2: Europe

https://eu1.locationiq.com/v1/search?key=YOUR_ACCESS_TOKEN&q=SEARCH_STRING&format=json

Request Example

curl --request GET \
  --url 'https://us1.locationiq.com/v1/search?key=YOUR_ACCESS_TOKEN&q=Empire%20State%20Building&format=json'
$curl = curl_init('https://us1.locationiq.com/v1/search?key=YOUR_ACCESS_TOKEN&q=Empire%20State%20Building&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;
}
?>
import requests

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

data = {
    'key': 'YOUR_ACCESS_TOKEN',
    'q': 'Empire State Building',
    'format': 'json'
}

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

print(response.text)
var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://us1.locationiq.com/v1/search?key=YOUR_ACCESS_TOKEN&q=Empire%20State%20Building&format=json",
  "method": "GET"
}

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

Required:

NameDescriptionRequired
keyYour API KeyYes
qFree-form query string to search for. Commas are optional, but improves performance by reducing the complexity of the search. Do not combine with structured/postalcode parametersEither
street, city, county, state, country, postalcodeAlternative query string format split into several parameters for structured requests. Structured requests are faster but are less robust against alternative OSM tagging schemas. Do not combine with q=<query> parameter.Either
postalcodeAlternative query string format for postal code requests that uses a special postal code dataset for geocoding. Do not combine with q=<query> or other structured parameters for postal code search. Combine with countrycodes=<countrycode> parameter for a better responseEither

Frequently used parameters (optional):

NameDescriptionValues
formatOutput Format. Defaults to xml.[json|xml|xmlv1.1]
addressdetailsInclude a breakdown of the address of this result into elements. Defaults to 0. Read more.[0|1]
accept-languagePreferred language order for showing search results, overrides the value specified in the Accept-Language HTTP header. Defaults to en. To use native language for the response when available, use accept-language=native. Either uses standard rfc2616 accept-language string or a simple comma-separated list of language codes. Read more.
countrycodesLimit search to a list of countries. Read more.
normalizeaddressMakes parsing of the address object easier by returning a predictable and defined list of elements. Defaults to 0 for backward compatibility. We recommend setting this to 1 for new projects.[0|1]

πŸ“˜

List of all input parameters available on the API Reference page


Response

Response Example

[
    {
        "place_id": "218751965",
        "licence": "https://locationiq.com/attribution",
        "osm_type": "way",
        "osm_id": "34633854",
        "boundingbox": [
            "40.7479226",
            "40.7489422",
            "-73.9864855",
            "-73.9848259"
        ],
        "lat": "40.7484284",
        "lon": "-73.9856546198733",
        "display_name": "Empire State Building, 350, 5th Avenue, Korea Town, Manhattan Community Board 5, New York County, NYC, New York, 10018, United States of America",
        "class": "tourism",
        "type": "attraction",
        "importance": 0.82289665394454,
        "icon": "https://locationiq.com/static/images/mapicons/poi_point_of_interest.p.20.png"
    },
    {
        "place_id": "29167569",
        "licence": "https://locationiq.com/attribution",
        "osm_type": "node",
        "osm_id": "2709306673",
        "boundingbox": [
            "40.7481128",
            "40.7482128",
            "-73.9850458",
            "-73.9849458"
        ],
        "lat": "40.7481628",
        "lon": "-73.9849958",
        "display_name": "Empire State Building, 350, 5th Avenue, Korea Town, Manhattan Community Board 5, New York County, NYC, New York, 10118, United States of America",
        "class": "tourism",
        "type": "attraction",
        "importance": 0.301,
        "icon": "https://locationiq.com/static/images/mapicons/poi_point_of_interest.p.20.png"
    }
  ]

Response Parameters

NameDescription
latThe Latitude of this result
lonThe Longitude of this result
display_nameThe display name of this result, with complete address
addressThe address breakdown into individual components. Returned when addressdetails=1 is set in the request. Important components include (but not limited to) country, country_code, postcode, state, county, city, town. Read more.
statecodeA state or province code when available. Returned when statecode is set in the request.
matchqualityAdditional information about quality of the result. Returned when matchquality is set in the request. Read more
postal_addressReturns address specifically formatted for each country. Returned when postaladdress is set in the request.

πŸ“˜

List of all response parameters available on the API Reference page


Other Ways to Access Geocoding


What’s Next