Free Form Query

get

https://us1.locationiq.com/v1/search

The Search API allows converting addresses, such as a street address, into geographic coordinates (latitude and longitude). These coordinates can serve various use-cases, from placing markers on a map to helping algorithms determine nearby bus stops. This process is also known as Forward Geocoding.

Query Params

string

required

Free-form query string to search for. Commas are optional, but improves performance by reducing the complexity of the search.

format

string

enum

Defaults to xml

Output Format. Defaults to xml.

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.

Allowed:

addressdetails

integer

enum

Defaults to 0

Include a breakdown of the address of this result into elements. Defaults to 0.

Allowed:

statecode

integer

enum

Defaults to 0

Adds state or province code when available to the state_code key inside the address object when available. Defaults to 0.

Allowed:

viewbox

string

The preferred area to find search results. Any two corner points of the box - max_lon,max_lat,min_lon,min_lat or min_lon,min_lat,max_lon,max_lat - are accepted in any order as long as they span a real box. To restrict results to those within the viewbox, use along with the bounded option.

bounded

integer

enum

Restrict result to items contained within the bounds specified in the viewbox parameter. Defaults to 0.

Allowed:

limit

integer

1 to 50

Limit the number of returned results. Accepted value: 1 to 50. Defaults to 10.

accept-language

string

Defaults to en

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.

countrycodes

string

Limit search results to a specific country or a comma-separated list of countries. Should be the ISO 3166-1 alpha-2 code(s).

normalizeaddress

integer

enum

Defaults to 0

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.

Element Name	Description
name	House name or Point of Interest (POI) such as a Cafe or School
house_number	House or Building number
road	Roads, Highways, Freeways, Motorways
neighbourhood	Neighbourhoods, Allotments, Quarters, Communities
suburb	Suburbs, Subdivisions
island	Islands, Islets
city	Cities, Towns, Villages, Municipalities, Districts, Boroughs, Hamlets
county	Counties
state	States, Provinces, Regions, State Districts
state_code	State or Province Code
postcode	Postal Codes, Zipcodes
country	Countries, Nation-states
country_code	Country Code - 2 letter (ISO 3166-1 alpha-2)

Allowed:

normalizecity

integer

enum

Defaults to 0

For responses with no city value in the address section, the next available element in this order - city_district, locality, town, borough, municipality, village, hamlet, quarter, neighbourhood - from the address section will be normalized to city. Defaults to 0.

Allowed:

postaladdress

integer

enum

Defaults to 0

Returns address inside the postaladdress key, that is specifically formatted for each country. Currently supported for addresses in Belgium, Brazil, France, Germany, Greece, India, Ireland, Italy, Portugal, South Africa, Spain and United Kingdom. Defaults to 0.

Allowed:

matchquality

integer

enum

Defaults to 0

Returns additional information about quality of the result in a matchquality object. Defaults to 0.

Allowed:

source

string

If this parameter is not specified, LocationIQ uses multiple public and proprietary datasets to return results. If you'd like to restrict results to only OpenStreetMap data, you can set the value of this parameter to nom. This will only query our internal cluster of Nominatim servers, and return results. We may still apply some post-processing steps to these results though, so results may vary from the official Nominatim instance.

normalizeimportance

integer

enum

Defaults to 1

When this parameter is absent or set to 1, the importance value(s) in the API response is limited to the range of 0 to 1. Values outside this range are adjusted to the nearest boundary (0 or 1). Setting normalizeimportance to 0 allows the importance value to be lower or higher than the specified range of 0 to 1. Defaults to 1

Allowed:

dedupe

integer

enum

Defaults to 1

Sometimes you have several objects in OSM identifying the same place or object in reality. The simplest case is a street being split in many different OSM ways due to different characteristics. Our Geocoder will attempt to detect such duplicates and only return one match; this is controlled by the dedupe parameter which defaults to 1. Since the limit is, for reasons of efficiency, enforced before and not after de-duplicating, it is possible that de-duplicating leaves you with less results than requested.

Allowed:

namedetails

integer

enum

Defaults to 0

Include a list of alternative names in the results. These may include language variants, references, operator and brand. Defaults to 0.

Allowed:

extratags

integer

enum

Defaults to 0

Include additional information in the result if available, e.g. wikipedia link, opening hours. Defaults to 0.

Allowed:

polygon_geojson

integer

enum

Defaults to 0

Output geometry of results in geojson format. Defaults to 0.

Allowed:

polygon_kml

integer

enum

Defaults to 0

Output geometry of results in kml format. Defaults to 0.

Allowed:

polygon_svg

integer

enum

Defaults to 0

Output geometry of results in svg format. Defaults to 0.

Allowed:

polygon_text

integer

enum

Defaults to 0

Output geometry of results as a WKT. Defaults to 0.

Allowed:

json_callback

string

Wrap json output in a callback function (JSONP) i.e. <string>(<json>). Only has an effect for JSON output formats.

polygon_threshold

number

Defaults to 0

When one of the polygon_* outputs is chosen, return a simplified version of the output geometry. The parameter describes the tolerance in degrees with which the geometry may differ from the original geometry. Topology is preserved in the geometry.

Headers

string

enum

Defaults to application/json

Generated from available response content types

Allowed:

Responses

200OK

400Bad Request

401Unauthorized

403The request has been made from an unauthorized domain.

404No location or places were found for the given input.

429Request exceeded the rate-limits set on your account.

500Internal Server Error