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 (
us1oreu1) 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
jsonorxmlv1.1format options.
Request Types
| Type | Endpoint | Description |
|---|---|---|
| Free-Form Query | https://us1.locationiq.com/v1/search | Default way to Forward Geocode |
| Structured Geocoding | https://us1.locationiq.com/v1/search/structured | To be used if address can be bucketed into distinct address components |
| Postal Code Search | https://us1.locationiq.com/v1/search/postalcode | To 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:
| Name | Description | Required |
|---|---|---|
| key | Your API Key | Yes |
| q | Free-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 parameters | Either |
| street, city, county, state, country, postalcode | Alternative 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 |
| postalcode | Alternative 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 response | Either |
Frequently used parameters (optional):
| Name | Description | Values |
|---|---|---|
| format | Output Format. Defaults to xml. | [json|xml|xmlv1.1] |
| addressdetails | Include a breakdown of the address of this result into elements. Defaults to 0. Read more. | [0|1] |
| accept-language | Preferred 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. | |
| countrycodes | Limit search to a list of countries. Read more. | |
| normalizeaddress | Makes 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
| Name | Description |
|---|---|
| lat | The Latitude of this result |
| lon | The Longitude of this result |
| display_name | The display name of this result, with complete address |
| address | The 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. |
| statecode | A state or province code when available. Returned when statecode is set in the request. |
| matchquality | Additional information about quality of the result. Returned when matchquality is set in the request. Read more |
| postal_address | Returns 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
- Interactive Playground (demo)
- Google Sheet (no-code option)
Updated about 1 year ago