Introduction

LocationIQ provides flexible enterprise-grade location based solutions. We work with developers, startups and enterprises worldwide serving billions of requests everyday. This page provides an overview of the technical aspects of our API and will help you get started.

Authentication

Each request to LocationIQ's APIs or Map tiles needs to be authenticated with an access token.

Access Tokens

For user-facing applications such as Javascript websites or mobile apps, we recommend that you generate new access tokens on your User Dashboard. Create a separate access token for each application, label them accordingly - e.g. "my website" - and reissue these tokens frequently to prevent misuse. You can use access tokens in both public (websites, apps) and private environments (server backends).

If you need help creating access tokens, watch this video:

Security Best Practices

As a best practice, you need to secure your API Access Tokens. We recommend use some or all of the options below to avoid abuse of your public access tokens.

HTTP Referrer restrictions

You can define a list of HTTP referrers (commonly mis-spelled as referer!) authorized to call our APIs or Maps with an access token. If not specified or empty, it will default to any referrer. Referrers can be targeted by matching a prefix or a suffix using the * character. For multiple HTTP referrers, specify one pattern per line, upto a maximum of 10 per access token.

You can test patterns on the User Dashboard while viewing an access token:

A few examples:

• *example.com* - allow access for the full domain and sub-domains of example.com

  • These refererrs match the pattern:
    • https://example.com
    • http://www1.example.com/
  • These refererrs do not match the pattern:
    • https://example.org - .org does not match
    • https://ExamPLE.com - because patterns are case-sensitive

• https://example.com/* will restrict access to all referrers starting with https://example.com/.

  • These refererrs match the pattern:
    • https://example.com/abc
    • https://example.com/
  • These refererrs do not match the pattern:
    • https://www.example.com/ - because www. does not match
    • https://example.com - no trailing / like the pattern requires
    • http://example.com - http: does not match

• *.example.com/ - will restrict access to all referrers ending with .example.com/.

  • These refererrs match the pattern:
    • https://abc.example.com/
    • http://www.example.com/
  • These refererrs do not match the pattern:
    • http://www.example.com - no trailing / like the pattern requires
    • https://ExamPLE.com - because patterns are case-sensitive.
    • http://example.com - example does not have the leading .

The referrer is an HTTP header that is sent by browsers and like all HTTP headers, it can be spoofed. To limit misuse when using access tokens on a public site, we recommend frequent access token rotation along with referrer restrictions.

IP Address restrictions

You can define a list of IPv4 addresses or subnets authorized to call our APIs or Maps with an access token. If not specified or empty, it will default to any IP address. Specify one IPv4 address or a subnet using CIDR notation (e.g. 192.168.1.0/24). For multiple IP addresses or subnets, specify one per line, upto a maximum of 5 per access token.

A few examples:

• 192.168.1.1 will restrict access to to requests from this IP

• 172.16.1.0/24 will restrict access to IPs in the range 172.16.1.0 to 172.16.1.255

Note: It may take up to 10 minutes for settings to take effect.

API Collection

We recommend using REST clients like Postman to test our APIs. Follow the steps below to get started with our APIs using Postman.

1. Load Collection

    1.1 Download the LocationIQ Collection
   
    1.2 Open Postman and click Import and choose the LocationIQ Collection file that was downloaded from the link above.
   
      

2. Load Environment

    2.1. Download the environment file depending on the endpoint you want to use.
      - EU endpoint Environment File
      - US endpoint Environment File
   
    2.2. Now click on settings icon from the Postman app and click Manage Environments
   
      
   
    2.3. Click on Import.
   
      
   
    2.4. Import the json file that was provided.
   
      
   
    2.5. To add the API key to the environment, click Manage Environments
   
      
   
    2.6. Click on the Environment name and replace "Enter your access token here" with your Access token.
   
      
   
    2.7. In the Manage Environments window, click Update to save.

Search / Forward Geocoding

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.

Try this API in our Playground

Usage

Requests can be sent to any of the following endpoints

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

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

Query Parameters

<?php

$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)

curl --request GET \
  --url 'https://us1.locationiq.com/v1/search?key=YOUR_ACCESS_TOKEN&q=Empire%20State%20Building&format=json'

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:

All three query forms accept the optional paramters listed below.

Optional:

LocationIQ specific parameters:

The following parameters are available only on LocationIQ and are not backward-compatible with Nominatim.

Response

The above command returns JSON structured like this:

[
    {
        "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"
    }
  ]

LocationIQ specific elements in the response:

Reverse Geocoding

Reverse geocoding is the process of converting a coordinate or location (latitude, longitude) to a readable address or place name. This permits the identification of nearby street addresses, places, and/or area subdivisions such as a neighborhood, county, state, or country.

Try this API in our Playground

Usage

Requests can be sent to any of the following endpoints

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

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

Query Parameters

<?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;
}

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)

curl --request GET \
  --url 'https://us1.locationiq.com/v1/reverse?key=YOUR_ACCESS_TOKEN&lat=-37.870662&lon=144.9803321&format=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);
});

Required:

Optional:

LocationIQ specific parameters:

The following parameters are available only on LocationIQ and are not backward-compatible with Nominatim.

Response

The above command returns JSON structured like this:

{
    "place_id": "26693344",
    "licence": "https://locationiq.com/attribution",
    "osm_type": "node",
    "osm_id": "2525193585",
    "lat": "-37.870662",
    "lon": "144.9803321",
    "display_name": "Imbiss 25, Blessington Street, St Kilda, City of Port Phillip, Greater Melbourne, Victoria, 3182, Australia",
    "address": {
        "cafe": "Imbiss 25",
        "road": "Blessington Street",
        "suburb": "St Kilda",
        "county": "City of Port Phillip",
        "region": "Greater Melbourne",
        "state": "Victoria",
        "postcode": "3182",
        "country": "Australia",
        "country_code": "au"
    },
    "boundingbox": [
        "-37.870762",
        "-37.870562",
        "144.9802321",
        "144.9804321"
    ]
}

LocationIQ specific elements in the response:

Autocomplete

The Autocomplete API is a variant of the Search API that returns place predictions in response to an HTTP request. The request specifies a textual search string and optional geographic bounds. The service can be used to provide autocomplete functionality for text-based geographic searches, by returning places such as businesses, addresses and points of interest as a user types.

The Autocomplete API can match on full words as well as substrings. Applications can therefore send queries as the user types, to provide on-the-fly place predictions.

Try this API in our Playground

Usage

Requests can be sent to the following endpoint:

GET https://api.locationiq.com/v1/autocomplete?key=YOUR_ACCESS_TOKEN&q=SEARCH_STRING

Query Parameters

<?php

$curl = curl_init('https://api.locationiq.com/v1/autocomplete?key=YOUR_ACCESS_TOKEN&q=Empire');

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://api.locationiq.com/v1/autocomplete"

data = {
    'key': 'YOUR_ACCESS_TOKEN',
    'q': 'Empire'
}

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

print(response.text)

curl --request GET \
  --url 'https://api.locationiq.com/v1/autocomplete?key=YOUR_ACCESS_TOKEN&q=Empire'

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://api.locationiq.com/v1/autocomplete?key=YOUR_ACCESS_TOKEN&q=Empire",
  "method": "GET"
}

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

Required:

Optional:

Response

The above command returns JSON structured like this:

[
    {
        "place_id": "0",
        "osm_id": "34633854",
        "osm_type": "way",
        "licence": "https://locationiq.com/attribution",
        "lat": "40.7484284",
        "lon": "-73.985654619873",
        "boundingbox": [
            "40.7479226",
            "40.7489422",
            "-73.9864855",
            "-73.9848259"
        ],
        "class": "tourism",
        "type": "attraction",
        "display_name": "Empire State Building, 350, 5th Avenue, New York City, New York, 10018, United States of America",
        "display_place": "Empire State Building",
        "display_address": "350, 5th Avenue, New York City, New York, 10018, United States of America",
        "address": {
            "name": "Empire State Building",
            "house_number": "350",
            "road": "5th Avenue",
            "city": "New York City",
            "state": "New York",
            "postcode": "10018",
            "country": "United States of America"
        }
    },
    {
        "place_id": "0",
        "osm_id": "34633854",
        "osm_type": "way",
        "licence": "https://locationiq.com/attribution",
        "lat": "40.7484284",
        "lon": "-73.985654619873",
        "boundingbox": [
            "40.7479226",
            "40.7489422",
            "-73.9864855",
            "-73.9848259"
        ],
        "class": "office",
        "type": "yes",
        "display_name": "Empire State Building, 350, 5th Avenue, New York City, New York, 10018, United States of America",
        "display_place": "Empire State Building",
        "display_address": "350, 5th Avenue, New York City, New York, 10018, United States of America",
        "address": {
            "name": "Empire State Building",
            "house_number": "350",
            "road": "5th Avenue",
            "city": "New York City",
            "state": "New York",
            "postcode": "10018",
            "country": "United States of America"
        }
    }
]

Maps

LocationIQ provides beautiful and customizable map tiles to visualize location data on your websites and apps.

Endpoints

Depending on which Maps SDK you decide to use, you will need to use either the Style Specification URL or Tile URLs.

Style Specification URL:

For MapLibre-GL SDKs, use a Style Specification URL. A Style URL looks like this:

https://tiles.locationiq.com/v3/<theme>/<type>.json?key=<access_token>

Parameters

Tile URLs:

For LeafletJS and other mapping libraries, you need to specify Tile URLs instead:

https://{s}-tiles.locationiq.com/v3/<theme>/r/{z}/{x}/{y}.<format>?key=<access_token>

Parameters

Available Themes

Theme	Format	Sample
streets	png
dark	png
light	png

Websites

Our map tiles can be rendered by most open-source libraries like OpenLayers, MapLibre GL JS or Leaflet JS to add a map to your website.

We've added demos & code-samples for most popular use-cases:

• Maps using MapLibre GL JS(recommended)

• Maps using OpenLayers

• Maps using LeafletJS (for compatibility with older browsers)

Android

MapLibre-gl Native SDK

For your Android apps, we recommend you use the excellent and open-source MapLibre GL Native Android SDK. We've created a sample app showcasing popular use-cases among our users.

• Android Maps Sample App - Demo

• Android Maps Sample - Source Code

OSMDroid

In case you'd like to use OSMDroid, we've added sample code for you on the right:
For more info and documentation, please refer to osmdroid Wiki

iOS

For iOS apps, we recommend you use the excellent and open-source MapLibre GL Native iOS SDK. We've created a sample app showcasing popular use-cases among our users.

• iOS Maps Sample - Source Code

Errors

All errors - authentication, invalid tile URLs, etc - will return JSON along with a corresponding HTTP response code as specified in the Errors section.

Static Maps

Static maps are standalone images (in JPG or PNG format) that can be displayed on web and mobile devices without the aid of a mapping library or API. Our Static Maps API returns an image in response to an HTTP request. For each request, you can specify the map's location, size of the image, zoom level, type of map. You can also place markers or draw paths at locations on the map.

You can simply embed static map image within an <img> tag's src attribute.

Usage

Requests can be sent to the following endpoint

GET https://maps.locationiq.com/v3/staticmap

Query Parameters

curl -o mystaticmap.png 'https://maps.locationiq.com/v3/staticmap?key=<YOUR_ACCESS_TOKEN>&center=<latitude>,<longitude>&zoom=<zoom>&size=<width>x<height>&format=<format>&maptype=<MapType>&markers=icon:<icon>|<latitude>,<longitude>&markers=icon:<icon>|<latitude>,<longitude>'

<img src='https://maps.locationiq.com/v3/staticmap?key=<YOUR_ACCESS_TOKEN>&center=<latitude>,<longitude>&zoom=<zoom>&size=<width>x<height>&format=<format>&maptype=<MapType>&markers=icon:<icon>|<latitude>,<longitude>&markers=icon:<icon>|<latitude>,<longitude>'>

<img src='https://maps.locationiq.com/v3/staticmap?key=<YOUR_ACCESS_TOKEN>&center=<latitude>,<longitude>&zoom=<zoom>&size=<width>x<height>&format=<format>&maptype=<MapType>&markers=icon:<icon>|<latitude>,<longitude>&markers=icon:<icon>|<latitude>,<longitude>'>

<img src='https://maps.locationiq.com/v3/staticmap?key=<YOUR_ACCESS_TOKEN>&center=<latitude>,<longitude>&zoom=<zoom>&size=<width>x<height>&format=<format>&maptype=<MapType>&markers=icon:<icon>|<latitude>,<longitude>&markers=icon:<icon>|<latitude>,<longitude>'>

Markers

Markers are a type of overlay used to identify locations on the map. The markers parameter accepts a set of values in the following format:

markers=icon:|markerStyles|markerLocation&markers=icon:|markerStyles|markerLocation

For using same icon-name for all markerLocations, you can send multiple markerLocations in the same markers parameter.

markers=icon:|markerLocation|markerLocation|..

curl -o mystaticmap.png 'https://maps.locationiq.com/v3/staticmap?key=<YOUR_ACCESS_TOKEN>&size=600x600&zoom=14&markers=45.5165,-122.6764|icon:large-blue-cutout&format=png'

Below are the list of values that are accepted by markers param :

• icon : Icon to use for the marker. Must choose one of the icons mentioned below. If an invalid icon is specified, the marker will not be rendered. Below are the available icon names :
  

  large-red-cutout	small-red-cutout	tiny-red-cutout	large-red-blank	small-red-blank	tiny-red-blank
  large-blue-cutout	small-blue-cutout	tiny-blue-cutout	large-blue-blank	small-blue-blank	tiny-blue-blank
  large-gray-cutout	small-gray-cutout	tiny-gray-cutout	large-gray-blank	small-gray-blank	tiny-gray-blank
  large-yellow-cutout	small-yellow-cutout	tiny-yellow-cutout	large-yellow-blank	small-yellow-blank	tiny-yellow-blank
  large-purple-cutout	small-purple-cutout	tiny-purple-cutout	large-purple-blank	small-purple-blank	tiny-purple-blank
  large-orange-cutout	small-orange-cutout	tiny-orange-cutout	large-orange-blank	small-orange-blank	tiny-orange-blank
  large-green-cutout	small-green-cutout	tiny-green-cutout	large-green-blank	small-green-blank	tiny-green-blank
  large-black-cutout	small-black-cutout	tiny-black-cutout	large-black-blank	small-black-blank	tiny-black-blank

• markerLocation : Each markerLocation param should contain latitude, longitude pair which defines the postion of the marker.

  • Example: markers=icon:large-red-cutout|17.451377,78.379525|17.450419,78.381149
    
    

• markerStyles : consists of visual attributes like size and color, which are used to display the markers on the map.

  • size : accepted values - [tiny, small, large]. Defaults to small.
  • color : accepted values - [blue, gray, red, yellow, orange, green, purple]. Defaults to red.
  • Example: markers=size:small|color:red|17.451377,78.379525|17.450419,78.381149

Paths

The path parameter defines a set of one or more locations connected by a path to overlay on the map image. The path parameter takes set of values in the following format:

path=pathStyles|pathLocation1|pathLocation2|... etc. See note

Below are the list of values that are accepted by path parameter :

• pathStyles : consists of visual attributes to use when displaying the path.
  • weight : specifies the thickness of the path in pixels.
  • color : color of the path stroke (e.g. red, rgba(255,255,255,0.5), #0000ff)
  • fillcolor : color to use as the fill (e.g. red, rgba(255,255,255,0.5), #0000ff)
  • Example: path=weight:2|color:blue|fillcolor:%23add8e6|17.452945,78.380055|17.452765,78.382026
• pathLocation :
  
  • Using coordinates: Each pathLocation parameter contains latitude, longitude pair seperated by comma.
    • Format: path=lat1,lon1|lat2,lon2|
    • Example: https://maps.locationiq.com/v3/staticmap?key=<YOUR_ACCESS_TOKEN>&center=17.450419,78.381149&size=600x600&zoom=14&path=fillcolor:%2390EE90|weight:2|color:blue|17.452945,78.380055|17.452765,78.382026|17.452020,78.381375|17.452045,78.380846|17.452945,78.380055
  • Using an encoded polyline: Prefix with enc: followed by the encoded polyline string
    • Format: path=enc:<encoded_polyline
    • Example: https://maps.locationiq.com/v3/staticmap?key=<YOUR_ACCESS_TOKEN>&center=17.450419,78.381149&size=600x600&zoom=14&path=fillcolor:%2390EE90|weight:2|color:blue|enc:}woiBkrk}Mb@iKtC`CEhBsD|C

Example

Below is the sample static map having two markers, polygonal area and is centered at 17.450419,78.381149.

https://maps.locationiq.com/v3/staticmap?key=<YOUR_ACCESS_TOKEN>&center=17.450419,78.381149&zoom=16&size=480x480&markers=icon:large-red-cutout|17.450419,78.381149&markers=icon:large-red-cutout|17.451377,78.379525&path=fillcolor:%23add8e6|weight:1|color:blue|17.452945,78.380055|17.452765,78.382026|17.452020,78.381375|17.452045,78.380846|17.452945,78.380055

Errors

For all errors except authentication errors, the Static Map API returns the following blank image in grey to help preserve user experience. An error code is set in the HTTP Response code as per the Errors section.

Authentication errors will return JSON in the format specified in the Errors section.

Routing

The Routing APIs are based on work by the OSRM Project.

General options

All Routing HTTP requests use a common structure.

The following syntax applies to all services, except as noted.

Requests

Requests can be sent to any of the following endpoints

Region 1: US
GET https://us1.locationiq.com/v1/{service}/{profile}/{coordinates}?key=<YOUR_ACCESS_TOKEN>&option=value&option=value

Region 2: Europe
GET https://eu1.locationiq.com/v1/{service}/{profile}/{coordinates}?key=<YOUR_ACCESS_TOKEN>&option=value&option=value

Passing any option=value is optional. polyline follows Google's polyline format with precision 5 by default and can be generated using this package.

To pass parameters to each location some options support an array like encoding:

Request options

Where the elements follow the following format:

{option}={element};{element}[;{element} ... ]

Example: 2nd location use the default value for option:

{option}={element};;{element}

The number of elements must match exactly the number of locations (except for generate_hints and exclude). If you don't want to pass a value but instead use the default you can pass an empty element.

Example Requests

# Query on London with three coordinates:
curl 'https://us1.locationiq.com/v1/directions/driving/-0.127627,51.503355;-0.087199,51.509562;-0.076134,51.508037?key=<YOUR_ACCESS_TOKEN>&overview=false'

# Query on London excluding the usage of motorways:
curl 'https://us1.locationiq.com/v1/directions/driving/-0.127627,51.503355;-0.087199,51.509562;-0.076134,51.508037?key=<YOUR_ACCESS_TOKEN>&exclude=motorway'

# Using polyline:
curl 'https://us1.locationiq.com/v1/directions/driving/polyline(ofp_Ik_vpAilAyu@te@g`E)?key=<YOUR_ACCESS_TOKEN>&overview=false'

Example response

{
"code": "Ok",
"message": "Everything worked"
}

Responses

Every response object has a code property containing one of the strings below or a service dependent code:

Directions

Finds the fastest route between coordinates in the supplied order.

Try this API in our Playground

GET  https://us1.locationiq.com/v1/directions/driving/{coordinates}?key=<YOUR_ACCESS_TOKEN>&alternatives={true|false|number}&steps={true|false}&geometries={polyline|polyline6|geojson}&overview={full|simplified|false}&annotations={true|false}

In addition to the general options the following options are supported for this service:

* Please note that even if alternative routes are requested, a result cannot be guaranteed.

Example Request

# Query on London with three coordinates and no overview geometry returned:
curl 'https://us1.locationiq.com/v1/directions/driving/-0.127627,51.503355;-0.087199,51.509562;-0.076134,51.508037?key=<YOUR_ACCESS_TOKEN>&overview=false'

Response

• code if the request was successful Ok otherwise see the service dependent and general status codes.
• waypoints: Array of Waypoint objects representing all waypoints in order:
• routes: An array of Route objects, ordered by descending recommendation rank.

In case of error the following codes are supported in addition to the general ones:

All other properties might be undefined.

Matching

Matching API matches or snaps given GPS points to the road network in the most plausible way. Please note the request might result multiple sub-traces. Large jumps in the timestamps (> 60s) or improbable transitions lead to trace splits if a complete matching could not be found. The algorithm might not be able to match all points. Outliers are removed if they can not be matched successfully.

Try this API in our Playground

GET  https://us1.locationiq.com/v1/matching/driving/{coordinates}?key=<YOUR_ACCESS_TOKEN>&steps={true|false}&geometries={polyline|polyline6|geojson}&overview={simplified|full|false}&annotations={true|false}

In addition to the general options the following options are supported for this service:

The radius for each point should be the standard error of the location measured in meters from the true location. Use Location.getAccuracy() on Android or CLLocation.horizontalAccuracy on iOS. This value is used to determine which points should be considered as candidates (larger radius means more candidates) and how likely each candidate is (larger radius means far-away candidates are penalized less). The area to search is chosen such that the correct candidate should be considered 99.9% of the time.

Response

• code if the request was successful Ok otherwise see the service dependent and general status codes.
• tracepoints: Array of Waypoint objects representing all points of the trace in order. If the trace point was ommited by map matching because it is an outlier, the entry will be null. Each Waypoint object has the following additional properties:
  • matchings_index: Index to the Route object in matchings the sub-trace was matched to.
  • waypoint_index: Index of the waypoint inside the matched route.
  • alternatives_count: Number of probable alternative matchings for this trace point. A value of zero indicate that this point was matched unambiguously. Split the trace at these points for incremental map matching.
• matchings: An array of Route objects that assemble the trace. Each Route object has the following additional properties:
  • confidence: Confidence of the matching. float value between 0 and 1. 1 is very confident that the matching is correct.

In case of error the following codes are supported in addition to the general ones:

All other properties might be undefined.

Matrix

Computes duration of the fastest route between all pairs of supplied coordinates. Returns the durations or distances or both between the coordinate pairs. Note that the distances are not the shortest distance between two coordinates, but rather the distances of the fastest routes.

GET  https://us1.locationiq.com/v1/matrix/driving/{coordinates}?key=<YOUR_ACCESS_TOKEN>&sources={elem1};{elem2};..&destinations={elem1};{elem2};...&annotations={duration|distance|duration,distance}

Example Request

# Returns a 3x3 duration matrix:
curl 'https://us1.locationiq.com/v1/matrix/driving/-0.127627,51.503355;-0.087199,51.509562;-0.076134,51.508037?key=<YOUR_ACCESS_TOKEN>'

# Returns a 1x3 duration matrix
curl 'https://us1.locationiq.com/v1/matrix/driving/-0.127627,51.503355;-0.087199,51.509562;-0.142001,51.501284?sources=0&key=<YOUR_ACCESS_TOKEN>'

# Returns a 3x3 duration matrix and a 3x3 distance matrix:
curl 'https://us1.locationiq.com/v1/matrix/driving/-0.127627,51.503355;-0.087199,51.509562;-0.142001,51.501284?annotations=distance,duration&key=<YOUR_ACCESS_TOKEN>'

Options

In addition to the general options the following options are supported for this service:

Unlike other array encoded options, the length of sources and destinations can be smaller or equal to number of input locations;

Example:

sources=0;5;7&destinations=5;1;4;2;3;6

Example Response

{
    "code": "Ok",
    "distances": [
        [0, 3833.6, 1552.8],
        [3763.8, 0, 4963],
        [1622.7, 4953.2, 0]
    ],
    "durations": [
        [0, 529, 185.7],
        [472.3, 0, 622.4],
        [197.7, 663.1, 0]
    ],
    "sources": [{
        "hint": "dRJAiW_vt4sOAAAAAAAAAAAAAAAAAAAA1kBzQQAAAAAAAAAAAAAAAA4AAAAAAAAAAAAAAAAAAAAIFwEAIhL-_zzgEQN1Df7_--ARAwAAzxB42O4j",
        "distance": 85.752389,
        "location": [-0.12643, 51.503164],
        "name": "Downing Street"
    }, {
        "hint": "BdAMgP___38BAAAAKAAAAFsAAAC7AAAAdwJqP1dc30EhbYFCWlnxQgEAAAAoAAAAWwAAALsAAAAIFwEAYKv-_zr5EQNhq_7_OvkRAwQA3wB42O4j",
        "distance": 0.069405,
        "location": [-0.0872, 51.509562],
        "name": "King William Street"
    }, {
        "hint": "inUjk411I5MAAAAADwAAAF0AAAAfAQAAAAAAAIdkSEB2P51Ba9xvQgAAAAAHAAAAMAAAAJEAAAAIFwEARdb9__DVEQNP1f3_5NgRAwYAXwV42O4j",
        "distance": 85.827043,
        "location": [-0.141755, 51.500528],
        "name": "Ambassador's Court"
    }],
    "destinations": [{
        "hint": "dRJAiW_vt4sOAAAAAAAAAAAAAAAAAAAA1kBzQQAAAAAAAAAAAAAAAA4AAAAAAAAAAAAAAAAAAAAIFwEAIhL-_zzgEQN1Df7_--ARAwAAzxB42O4j",
        "distance": 85.752389,
        "location": [-0.12643, 51.503164],
        "name": "Downing Street"
    }, {
        "hint": "BdAMgP___38BAAAAKAAAAFsAAAC7AAAAdwJqP1dc30EhbYFCWlnxQgEAAAAoAAAAWwAAALsAAAAIFwEAYKv-_zr5EQNhq_7_OvkRAwQA3wB42O4j",
        "distance": 0.069405,
        "location": [-0.0872, 51.509562],
        "name": "King William Street"
    }, {
        "hint": "inUjk411I5MAAAAADwAAAF0AAAAfAQAAAAAAAIdkSEB2P51Ba9xvQgAAAAAHAAAAMAAAAJEAAAAIFwEARdb9__DVEQNP1f3_5NgRAwYAXwV42O4j",
        "distance": 85.827043,
        "location": [-0.141755, 51.500528],
        "name": "Ambassador's Court"
    }]
}

Response

• code: if the request was successful Ok otherwise see the service dependent and general status codes.
• durations: array of arrays that stores the matrix in row-major order. durations[i][j] gives the travel time from the i-th waypoint to the j-th waypoint. Values are given in seconds. Can be null if no route between i and j can be found.
• distances: array of arrays that stores the matrix in row-major order. distances[i][j] gives the travel distance from the i-th waypoint to the j-th waypoint. Values are given in meters. Can be null if no route between i and j can be found.
• sources: array of Waypoint objects describing all sources in order
• destinations: array of Waypoint objects describing all destinations in order

In case of error the following codes are supported in addition to the general ones:

All other properties might be undefined.

Nearest

Snaps a coordinate to the street network and returns the nearest n matches.

GET https://us1.locationiq.com/v1/nearest/driving/{coordinates}?key=<YOUR_ACCESS_TOKEN>&number={number}

Example Request

# Querying nearest two snapped locations of `-0.142001,51.501284` with a bearing between `20° - 340°`.
curl 'https://us1.locationiq.com/v1/nearest/driving/-0.142001,51.501284?key=<YOUR_ACCESS_TOKEN>&number=2&bearings=0,20'

Where coordinates only supports a single {longitude},{latitude} entry.

In addition to the general options the following options are supported for this service:

Example Response

{
    "waypoints": [{
            "nodes": [
                5393917730,
                5393917729
            ],
            "hint": "inUjk411IxMPAAAAAAAAACEAAABbAQAAlUZNQAAAAAD1D9xAA1aRQggAAAAAAAAAEAAAALAAAAAIFwEA3dX9_7zVEQNP1f3_5NgRAwIA3wB42O4j",
            "distance": 90.435751,
            "location": [
                -0.141859,
                51.500476
            ],
            "name": "Ambassador's Court"
        },
        {
            "nodes": [
                5393917731,
                5393917730
            ],
            "hint": "inUjk411IxMRAAAAAAAAABAAAABqAQAAHdpdQAAAAADMRVpAOMCXQggAAAAAAAAACAAAALgAAAAIFwEA0tX9_6DVEQNP1f3_5NgRAwEALxZ42O4j",
            "distance": 93.4557,
            "location": [
                -0.14187,
                51.500448
            ],
            "name": "Ambassador's Court"
        }
    ],
    "code": "Ok"
}

Response

• code if the request was successful Ok otherwise see the service dependent and general status codes.
• waypoints array of Waypoint objects sorted by distance to the input coordinate. Each object has at least the following additional properties:
  • nodes: Array of OpenStreetMap node ids.

Optimize

Optimize API solves the Traveling Salesman Problem(TSP) using a greedy heuristic (farthest-insertion algorithm) for 10 or more waypoints and uses brute force for less than 10 waypoints. The returned path does not have to be the fastest path. As TSP is NP-hard it only returns an approximation. Note that all input coordinates have to be connected for the optimize service to work.

Try this API in our Playground

GET  https://us1.locationiq.com/v1/optimize/driving/{coordinates}?key=<YOUR_ACCESS_TOKEN>&roundtrip={true|false}&source{any|first}&destination{any|last}&steps={true|false}&geometries={polyline|polyline6|geojson}&overview={simplified|full|false}&annotations={true|false}

Example Request

# Round trip in London with three stops:
curl 'https://us1.locationiq.com/v1/optimize/driving/-0.127627,51.503355;-0.087199,51.509562;-0.076134,51.508037?key=<YOUR_ACCESS_TOKEN>'

# Round trip in London with four stops, starting at the first stop, ending at the last:
curl 'https://us1.locationiq.com/v1/optimize/driving/-0.127627,51.503355;-0.087199,51.509562;-0.076134,51.508037;-0.142001,51.501284?key=<YOUR_ACCESS_TOKEN>&source=first&destination=last

Options

In addition to the general options the following options are supported for this service:

Fixing Start and End Points

It is possible to explicitely set the start or end coordinate of the trip. When source is set to first, the first coordinate is used as start coordinate of the trip in the output. When destination is set to last, the last coordinate will be used as destination of the trip in the returned output. If you specify any, any of the coordinates can be used as the first or last coordinate in the output.

However, if source=any&destination=any the returned round-trip will still start at the first input coordinate by default.

Currently, not all combinations of roundtrip, source and destination are supported. Right now, the following combinations are possible:

Example Response

{
    "code": "Ok",
    "waypoints": [{
        "waypoint_index": 0,
        "trips_index": 0,
        "hint": "dRJAiW_vt4sOAAAAAAAAAAAAAAAAAAAA1kBzQQAAAAAAAAAAAAAAAA4AAAAAAAAAAAAAAAAAAAAIFwEAIhL-_zzgEQN1Df7_--ARAwAAzxB42O4j",
        "distance": 85.752389,
        "location": [-0.12643, 51.503164],
        "name": "Downing Street"
    }, {
        "waypoint_index": 1,
        "trips_index": 0,
        "hint": "BdAMgP___38BAAAAKAAAAFsAAAC7AAAAdwJqP1dc30EhbYFCWlnxQgEAAAAoAAAAWwAAALsAAAAIFwEAYKv-_zr5EQNhq_7_OvkRAwQA3wB42O4j",
        "distance": 0.069405,
        "location": [-0.0872, 51.509562],
        "name": "King William Street"
    }, {
        "waypoint_index": 2,
        "trips_index": 0,
        "hint": "kXleipl5XooAAAAAFgAAAAAAAAAAAAAAAAAAAOHmE0EAAAAAAAAAAAAAAAAWAAAAAAAAAAAAAAAIFwEAlNn-_zzwEQOa1v7_RfMRAwAAbwt42O4j",
        "distance": 101.342282,
        "location": [-0.075372, 51.50726],
        "name": ""
    }],
    "trips": [{
        "legs": [{
            "steps": [],
            "weight": 529,
            "distance": 3826.2,
            "summary": "",
            "duration": 529
        }, {
            "steps": [],
            "weight": 3505.1,
            "distance": 1274.1,
            "summary": "",
            "duration": 228.4
        }, {
            "steps": [],
            "weight": 3783.4,
            "distance": 4260.8,
            "summary": "",
            "duration": 509.1
        }],
        "weight_name": "routability",
        "geometry": "wejyHduWAsApLXh@_t@|@uD{@mDzJkThBsIqDyrAXqAeL{U{PgMaJ_MeVwHmGwBhAuUbEoQrBbFnCeMpB_AhCsRs@Ir@HiCrRqB~@aClNsC`e@cClP{C`_@N~iBfBbUpEjSdDdGtDhDnHbFpHvB{@`Kd@dF|Hq@@rA",
        "weight": 7817.5,
        "distance": 9361.1,
        "duration": 1266.5
    }]
}

Response

• code: if the request was successful Ok otherwise see the service dependent and general status codes.
• waypoints: Array of Waypoint objects representing all waypoints in input order. Each Waypoint object has the following additional properties:
  • trips_index: Index to trips of the sub-trip the point was matched to.
  • waypoint_index: Index of the point in the trip.
• trips: An array of Route objects that assemble the trace.

In case of error the following codes are supported in addition to the general ones:

All other properties might be undefined.

Result objects

Route object

Represents a route through (potentially multiple) waypoints.

Route object example with three input coordinates, geometry=geojson, steps=false:

{
  "distance": 90.0,
  "duration": 300.0,
  "weight": 300.0,
  "weight_name": "duration",
  "geometry": {"type": "LineString", "coordinates": [[120.0, 10.0], [120.1, 10.0], [120.2, 10.0], [120.3, 10.0]]},
  "legs": [
    {
      "distance": 30.0,
      "duration": 100.0,
      "steps": []
    },
    {
      "distance": 60.0,
      "duration": 200.0,
      "steps": []
    }
  ]
}

Properties

• distance: The distance traveled by the route, in float meters.
• duration: The estimated travel time, in float number of seconds.
• geometry: The whole geometry of the route value depending on overview parameter, format depending on the geometries parameter. See RouteStep's geometry property for a parameter documentation.
• weight: The calculated weight of the route.
• weight_name: The name of the weight profile used during extraction phase.

• legs: The legs between the given waypoints, an array of RouteLeg objects.

RouteLeg object

Represents a route between two waypoints.

RouteLeg object example with steps=false and annotations=true:

{
  "distance": 30.0,
  "duration": 100.0,
  "weight": 100.0,
  "steps": [],
  "annotation": {
    "distance": [5,5,10,5,5],
    "duration": [15,15,40,15,15],
    "datasources": [1,0,0,0,1],
    "metadata": { "datasource_names": ["traffic","lua profile","lua profile","lua profile","traffic"] },
    "nodes": [49772551,49772552,49786799,49786800,49786801,49786802],
    "speed": [0.3, 0.3, 0.3, 0.3, 0.3]
  }
}

Properties

• distance: The distance traveled by this route leg, in float meters.
• duration: The estimated travel time, in float number of seconds.
• weight: The calculated weight of the route leg.
• summary: Summary of the route taken as string. Depends on the summary parameter:

• steps: Depends on the steps parameter.

• annotation: Additional details about each coordinate along the route geometry:

Annotation object

Annotation of the whole route leg with fine-grained information about each segment or node id.

Annotation object example

{
  "distance": [5,5,10,5,5],
  "duration": [15,15,40,15,15],
  "datasources": [1,0,0,0,1],
  "metadata": { "datasource_names": ["traffic","lua profile","lua profile","lua profile","traffic"] },
  "nodes": [49772551,49772552,49786799,49786800,49786801,49786802],
  "weight": [15,15,40,15,15]
}

Properties

• distance: The distance, in metres, between each pair of coordinates
• duration: The duration between each pair of coordinates, in seconds. Does not include the duration of any turns.
• datasources: The index of the datasource for the speed between each pair of coordinates. 0 is the default profile, other values are supplied via --segment-speed-file to osrm-contract or osrm-customize. String-like names are in the metadata.datasource_names array.
• nodes: The OSM node ID for each coordinate along the route, excluding the first/last user-supplied coordinates
• weight: The weights between each pair of coordinates. Does not include any turn costs.
• speed: Convenience field, calculation of distance / duration rounded to one decimal place
• metadata: Metadata related to other annotations
  • datasource_names: The names of the datasources used for the speed between each pair of coordinates. lua profile is the default profile, other values arethe filenames supplied via --segment-speed-file to osrm-contract or osrm-customize

RouteStep object

A step consists of a maneuver such as a turn or merge, followed by a distance of travel along a single way to the subsequent step.

RouteStep object example

{
   "geometry" : "{lu_IypwpAVrAvAdI",
   "mode" : "driving",
   "duration" : 15.6,
   "weight" : 15.6,
   "intersections" : [
      {  "bearings" : [ 10, 92, 184, 270 ],
         "lanes" : [
            { "indications" : [ "left", "straight" ],
               "valid" : "false" },
            { "valid" : "true",
               "indications" : [ "right" ] }
         ],
         "out" : 2,
         "in" : 3,
         "entry" : [ "true", "true", "true", "false" ],
         "location" : [ 13.39677, 52.54366 ]
      },
      {  "out" : 1,
         "lanes" : [
            { "indications" : [ "straight" ],
               "valid" : "true" },
            { "indications" : [ "right" ],
               "valid" : "false" }
         ],
         "bearings" : [ 60, 240, 330 ],
         "in" : 0,
         "entry" : [ "false", "true", "true" ],
         "location" : [ 13.394718, 52.543096 ]
      }
   ],
   "name" : "Lortzingstraße",
   "distance" : 152.3,
   "maneuver" : {
      "modifier" : "right",
      "type" : "turn"
   }
}

Properties

• distance: The distance of travel from the maneuver to the subsequent step, in float meters.
• duration: The estimated travel time, in float number of seconds.
• geometry: The unsimplified geometry of the route segment, depending on the geometries parameter.
• weight: The calculated weight of the step.

• name: The name of the way along which travel proceeds.
• ref: A reference number or code for the way. Optionally included, if ref data is available for the given way.
• pronunciation: A string containing an IPA phonetic transcription indicating how to pronounce the name in the name property. This property is omitted if pronunciation data is unavailable for the step.
• destinations: The destinations of the way. Will be undefined if there are no destinations.
• exits: The exit numbers or names of the way. Will be undefined if there are no exit numbers or names.
• mode: A string signifying the mode of transportation.
• maneuver: A StepManeuver object representing the maneuver.
• intersections: A list of Intersection objects that are passed along the segment, the very first belonging to the StepManeuver
• rotary_name: The name for the rotary. Optionally included, if the step is a rotary and a rotary name is available.
• rotary_pronunciation: The pronunciation hint of the rotary name. Optionally included, if the step is a rotary and a rotary pronunciation is available.
• driving_side: The legal driving side at the location for this step. Either left or right.

StepManeuver object

Properties

• location: A [longitude, latitude] pair describing the location of the turn.
• bearing_before: The clockwise angle from true north to the direction of travel immediately before the maneuver. Range 0-359.
• bearing_after: The clockwise angle from true north to the direction of travel immediately after the maneuver. Range 0-359.
• type A string indicating the type of maneuver. new identifiers might be introduced without API change Types unknown to the client should be handled like the turn type, the existence of correct modifier values is guranteed.

Please note that even though there are new name and notification instructions, the mode and name can change between all instructions. They only offer a fallback in case nothing else is to report.

• modifier An optional string indicating the direction change of the maneuver.

The list of turns without a modifier is limited to: depart/arrive. If the source/target location is close enough to the depart/arrive location, no modifier will be given.

The meaning depends on the type property.

• exit An optional integer indicating number of the exit to take. The property exists for the roundabout / rotary property: Number of the roundabout exit to take. If exit is undefined the destination is on the roundabout.

New properties (potentially depending on type) may be introduced in the future without an API version change.

Lane object

A Lane represents a turn lane at the corresponding turn location.

Lane object example

{
    "indications": ["left", "straight"],
    "valid": "false"
}

Properties

• indications: a indication (e.g. marking on the road) specifying the turn lane. A road can have multiple indications (e.g. an arrow pointing straight and left). The indications are given in an array, each containing one of the following types. Further indications might be added on without an API version change.

• valid: a boolean flag indicating whether the lane is a valid choice in the current maneuver

Intersection object

An intersection gives a full representation of any cross-way the path passes bay. For every step, the very first intersection (intersections[0]) corresponds to the location of the StepManeuver. Further intersections are listed for every cross-way until the next turn instruction.

Interssection object example

{
    "location":[13.394718,52.543096],
    "in":0,
    "out":2,
    "bearings":[60,150,240,330],
    "entry":["false","true","true","true"],
    "classes": ["toll", "restricted"],
    "lanes":{
        "indications": ["left", "straight"],
        "valid": "false"
    }
}

Properties

• location: A [longitude, latitude] pair describing the location of the turn.
• bearings: A list of bearing values (e.g. [0,90,180,270]) that are available at the intersection. The bearings describe all available roads at the intersection. Values are between 0-359 (0=true north)
• classes: An array of strings signifying the classes (as specified in the profile) of the road exiting the intersection.
• entry: A list of entry flags, corresponding in a 1:1 relationship to the bearings. A value of true indicates that the respective road could be entered on a valid route. false indicates that the turn onto the respective road would violate a restriction.
• in: index into bearings/entry array. Used to calculate the bearing just before the turn. Namely, the clockwise angle from true north to the direction of travel immediately before the maneuver/passing the intersection. Bearings are given relative to the intersection. To get the bearing in the direction of driving, the bearing has to be rotated by a value of 180. The value is not supplied for depart maneuvers.
• out: index into the bearings/entry array. Used to extract the bearing just after the turn. Namely, The clockwise angle from true north to the direction of travel immediately after the maneuver/passing the intersection. The value is not supplied for arrive maneuvers.
• lanes: Array of Lane objects that denote the available turn lanes at the intersection. If no lane information is available for an intersection, the lanes property will not be present.

Waypoint object

Object used to describe waypoint on a route.

Waypoint object example

{
   "hint" : "KSoKADRYroqUBAEAEAAAABkAAAAGAAAAAAAAABhnCQCLtwAA_0vMAKlYIQM8TMwArVghAwEAAQH1a66g",
   "distance" : 4.152629,
   "name" : "Friedrichstraße",
   "location" : [
      13.388799,
      52.517033
   ]
}

Properties

• name Name of the street the coordinate snapped to
• distance The distance, in metres, from the input coordinate to the snapped coordinate
• location Array that contains the [longitude, latitude] pair of the snapped coordinate
• hint Unique internal identifier of the segment (ephemeral, not constant over data updates) This can be used on subsequent request to significantly speed up the query and to connect multiple services. E.g. you can use the hint value obtained by the nearest query as hint values for route inputs.

Nearby - Points of Interest (PoI) (Public BETA)

The Nearby API returns Points of Interest (PoI) such as cafes, hospitals or even airports near a specified location.

Usage

Requests can be sent to any of the following endpoints

Region 1: US
GET https://us1.locationiq.com/v1/nearby?key=YOUR_ACCESS_TOKEN&lat=LATITUDE&lon=LONGITUDE&tag=POI&radius=IN_METERS&format=json

Region 2: Europe
GET https://eu1.locationiq.com/v1/nearby?key=YOUR_ACCESS_TOKEN&lat=LATITUDE&lon=LONGITUDE&tag=POI&radius=IN_METERS&format=json

Query Parameters

<?php

$curl = curl_init('https://us1.locationiq.com/v1/nearby?key=YOUR_ACCESS_TOKEN&lat=-37.870983&lon=144.980714&tag=restaurant&radius=100&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/nearby"

data = {
    'key': 'YOUR_ACCESS_TOKEN',
    'lat': '-37.870983',
    'lon': '144.980714',
    'tag': 'restaurant',
    'radius': 100,
    'format': 'json'
}

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

print(response.text)

curl --request GET \
  --url 'https://us1.locationiq.com/v1/nearby?key=YOUR_ACCESS_TOKEN&lat=-37.870983&lon=144.980714&tag=restaurant&radius=100&format=json'

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://us1.locationiq.com/v1/nearby?key=YOUR_ACCESS_TOKEN&lat=-37.870983&lon=144.980714&tag=restaurant&radius=100&format=json",
  "method": "GET"
}

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

Response

The above command returns JSON structured like this:

[
  {
    "place_id": "424228872143",
    "osm_type": "node",
    "osm_id": "3214984449",
    "lat": "-37.8704051",
    "lon": "144.980984",
    "class": "amenity",
    "type": "restaurant",
    "tag_type": "restaurant",
    "name": "Lentil as Anything",
    "display_name": "Lentil as Anything, 41, Blessington Street, St Kilda, St Kilda, Melbourne, 3182, Australia",
    "address": {
        "name": "Lentil as Anything",
        "house_number": "41",
        "road": "Blessington Street",
        "suburb": "St Kilda",
        "city": "St Kilda",
        "state": "Melbourne",
        "postcode": "3182",
        "country": "Australia",
        "country_code": "au"
    },
    "boundingbox": [
        "-37.8704051",
        "-37.8704051",
        "144.980984",
        "144.980984"
    ],
    "distance": 68
  },
  {
    "place_id": "420473963056",
    "osm_type": "node",
    "osm_id": "6911892785",
    "lat": "-37.8701731",
    "lon": "144.9805448",
    "class": "amenity",
    "type": "restaurant",
    "tag_type": "restaurant",
    "name": "Mr Natural",
    "display_name": "Mr Natural, Barkly Street, St Kilda, St Kilda, Melbourne, 3182, Australia",
    "address": {
        "name": "Mr Natural",
        "road": "Barkly Street",
        "suburb": "St Kilda",
        "city": "St Kilda",
        "state": "Melbourne",
        "postcode": "3182",
        "country": "Australia",
        "country_code": "au"
    },
    "boundingbox": [
        "-37.8701731",
        "-37.8701731",
        "144.9805448",
        "144.9805448"
    ],
    "distance": 91
  }
]

The nearby PoI endpoint returns a json array of objects sorted by their distance from the given point in ascending order.

PoI Tags

You can use a tag to restrict your results on the Nearby API. We support two types of tags, a single-word format for common use-cases and key-value pairs for advanced use-cases.

1. Single-word Format (Simple)

The below example lists schools within 1000 meters

<?php

$curl = curl_init('https://us1.locationiq.com/v1/nearby?key=YOUR_ACCESS_TOKEN&lat=-37.870983&lon=144.980714&tag=school&radius=1000&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/nearby"

data = {
    'key': 'YOUR_ACCESS_TOKEN',
    'lat': '-37.870983',
    'lon': '144.980714',
    'tag': 'school',
    'radius': 1000,
    'format': 'json'
}

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

print(response.text)

curl --request GET \
  --url 'https://us1.locationiq.com/v1/nearby?key=YOUR_ACCESS_TOKEN&lat=-37.870983&lon=144.980714&tag=school&radius=1000&format=json'

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://us1.locationiq.com/v1/nearby?key=YOUR_ACCESS_TOKEN&lat=-37.870983&lon=144.980714&tag=school&radius=1000&format=json",
  "method": "GET"
}

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

The above command returns JSON structured like this:

[
  {
    "place_id": "422634715054",
    "osm_type": "way",
    "osm_id": "27695264",
    "lat": "-37.86973755",
    "lon": "144.98925509",
    "class": "amenity",
    "type": "school",
    "tag_type": "school",
    "name": "St Kilda Primary School",
    "display_name": "St Kilda Primary School, Nightingale Street, St Kilda, Balaclava, Melbourne, 3182, Australia",
    "address": {
        "name": "St Kilda Primary School",
        "road": "Nightingale Street",
        "suburb": "St Kilda",
        "city": "Balaclava",
        "state": "Melbourne",
        "postcode": "3182",
        "country": "Australia",
        "country_code": "au"
    },
    "boundingbox": [
        "-37.8705392",
        "-37.8688718",
        "144.9882414",
        "144.9901112"
    ],
    "distance": 762
  }
]

For most use-cases, the list of tags below should suffice. Multiple tags can be specified as a comma-separated list.

2. Key Value Format (Advanced)

The below example lists all records of tourism class within 50 meters

<?php

$curl = curl_init('https://us1.locationiq.com/v1/nearby?key=YOUR_ACCESS_TOKEN&lat=40.748428&lon=-73.985654&tag=tourism:*&radius=50&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/nearby"

data = {
    'key': 'YOUR_ACCESS_TOKEN',
    'lat': '40.748428',
    'lon': '-73.985654',
    'tag': 'tourism:*',
    'radius': 50,
    'format': 'json'
}

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

print(response.text)

curl --request GET \
  --url 'https://us1.locationiq.com/v1/nearby?key=YOUR_ACCESS_TOKEN&lat=40.748428&lon=-73.985654&tag=tourism:*&radius=50&format=json'

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://us1.locationiq.com/v1/nearby?key=YOUR_ACCESS_TOKEN&lat=40.748428&lon=-73.985654&tag=tourism:*&radius=50&format=json",
  "method": "GET"
}

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

The above command returns JSON structured like this:

[
  {
    "place_id": "423028398818",
    "osm_type": "way",
    "osm_id": "34633854",
    "lat": "40.7484284",
    "lon": "-73.98565462",
    "class": "tourism",
    "type": "attraction",
    "tag_type": "attraction",
    "name": "Empire State Building",
    "display_name": "Empire State Building, 350, 5th Avenue, Korea Town, Midtown South, New York, New York, 10001, United States of America",
    "address": {
        "name": "Empire State Building",
        "house_number": "350",
        "road": "5th Avenue",
        "neighbourhood": "Korea Town",
        "suburb": "Midtown South",
        "city": "New York",
        "state": "New York",
        "postcode": "10001",
        "country": "United States of America",
        "country_code": "us"
    },
    "boundingbox": [
        "40.7479226",
        "40.7489422",
        "-73.9864855",
        "-73.9848259"
    ],
    "distance": 1
  },
  {
    "place_id": "423629875658",
    "osm_type": "node",
    "osm_id": "5190610589",
    "lat": "40.7483271",
    "lon": "-73.9856549",
    "class": "tourism",
    "type": "attraction",
    "tag_type": "attraction",
    "name": "NY Skyride",
    "display_name": "NY Skyride, 350, 5th Avenue, Korea Town, Midtown South, New York, New York, 10001, United States of America",
    "address": {
        "name": "NY Skyride",
        "house_number": "350",
        "road": "5th Avenue",
        "neighbourhood": "Korea Town",
        "suburb": "Midtown South",
        "city": "New York",
        "state": "New York",
        "postcode": "10001",
        "country": "United States of America",
        "country_code": "us"
    },
    "boundingbox": [
        "40.7483271",
        "40.7483271",
        "-73.9856549",
        "-73.9856549"
    ],
    "distance": 9
  }
]

For advanced use-cases that need additional tags not present in the table above, we also support tags based on OpenStreetMap's (OSM) exhaustive list of tags. These tags are represented as key-value pairs of class and type values. Multiple class and type values can be specified as a comma-separated list.

Examples:

Timezone

The Timezone API provides time offset data for locations on the surface of the earth.

Usage

Requests can be sent to any of the following endpoints

Region 1: US
GET https://us1.locationiq.com/v1/timezone?key=YOUR_ACCESS_TOKEN&lat=LATITUDE&lon=LONGITUDE

Region 2: Europe
GET https://eu1.locationiq.com/v1/timezone?key=YOUR_ACCESS_TOKEN&lat=LATITUDE&lon=LONGITUDE

Query Parameters

<?php

$curl = curl_init('https://us1.locationiq.com/v1/timezone?key=YOUR_ACCESS_TOKEN&lat=LATITUDE&lon=LONGITUDE');

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/timezone"

data = {
    'key': 'YOUR_ACCESS_TOKEN',
    'lat': 'LATITUDE',
    'lon': 'LONGITUDE'
}

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

print(response.text)

curl --request GET \
  --url 'https://us1.locationiq.com/v1/timezone?key=YOUR_ACCESS_TOKEN&lat=LATITUDE&lon=LONGITUDE'

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://us1.locationiq.com/v1/timezone?key=YOUR_ACCESS_TOKEN&lat=LATITUDE&lon=LONGITUDE",
  "method": "GET"
}

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

Response

The above command returns JSON structured like this:

{
  "timezone": {
    "name": "Asia/Kolkata",
    "now_in_dst": 0,
    "offset_sec": 19800,
    "short_name": "IST"
  }
}

Timezone object

Balance

The Balance API provides a count of request credits left in the user's account for the day. Balance is reset at midnight UTC everyday (00:00 UTC).

Usage

Requests can be sent to any of the following endpoints. To prevent abuse, this endpoint is rate limited at 1 request per second.

Region 1: US
GET https://us1.locationiq.com/v1/balance?key=YOUR_ACCESS_TOKEN&format=json

Region 2: Europe
GET https://eu1.locationiq.com/v1/balance?key=YOUR_ACCESS_TOKEN&format=json

Query Parameters

<?php

$curl = curl_init('https://us1.locationiq.com/v1/balance?key=YOUR_ACCESS_TOKEN&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/balance"

data = {
    'key': 'YOUR_ACCESS_TOKEN'
}

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

print(response.text)

curl --request GET \
  --url 'https://us1.locationiq.com/v1/balance?key=YOUR_ACCESS_TOKEN&format=json'

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://us1.locationiq.com/v1/balance?key=YOUR_ACCESS_TOKEN&format=json",
  "method": "GET"
}

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

Response

The above command returns JSON structured like this:

{
    "status": "ok",
    "balance": {
        "day": 30000,
        "bonus" : 0
    }
}

Balance Object

Client Libraries

This section lists Client libraries you can use to interact with our APIs.

Official Client Libraries

The following libraries have been deprecated:

Unofficial Client Libraries

These libraries are user contributed and haven't been tested by the LocationIQ team.

Notes

Address details

• addressdetails=[0|1]

All these elements are optional and only those elements that are available for a given location will be returned.

• normalizeaddress=[0|1]

The default address section returns a wide range of elements - from common ones such as road and country to obscure ones such as hamlet, cycleway, park. This was done to maintain backward compatibility with OpenStreetMap's Nominatim. To make parsing easier for developers, the normalizeaddress parameter rolls up elements in the address section of the response to the list of elements defined below.

Accept Language

• accept-language=<ISO 639-1 Code>

Preferred language order for showing search results, overrides the value specified in the Accept-Language HTTP header. Either uses standard rfc2616 accept-language string or a simple comma separated list of language codes. The Autocomplete endpoint only supporst a single ISO 639-1 language code, while Search and Reverse support multiple language codes separated by a comma.

• List of Accept-Language codes: List of ISO 639-1 codes
• Use ISO 639-1 Code (2 characters). If the language is not available, use ISO 639-2 Code (3 characters) from here
• Default: en

Country Codes

• countrycodes=<ISO_3166-1_alpha-2 Code>

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

• List of accepted country codes: Officially assigned code elements

Zoom Levels

• zoom=[0-18]

Level of detail required for the address. This is a number that corresponds roughly to the zoom level used in map frameworks like Leaflet.js, Openlayers etc.

In terms of address details the zoom levels are as follows:

Match Quality

• matchquality=[0|1]

This parameter returns an additional object matchquality for every result in the response, containing the following elements: matchcode, matchtype, matchlevel.

Match Code

Specifies the quality of the returned address

Match Type

Specifies quality of the returned location match