NAV Navbar
shell php python javascript
  • Introduction
  • Authentication
  • Search / Forward Geocoding
  • Reverse Geocoding
  • Autocomplete
  • Maps
  • Static Maps
  • Directions service (Public BETA)
  • Nearby - Points of Interest (PoI) (Private BETA)
  • Nearby - Countries (Private BETA)
  • Balance
  • Client Libraries
  • Notes
  • Errors
  • 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 a token (also known as a key or an access token).

    Private Token

    When you sign-up for an account, you are assigned a private token. You can use this token in secure, private environments where end users cannot view or misuse your 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:

    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.

    Usage

    Requests can be sent to any of the following endpoints

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

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

    Query Parameters

    <?php
    
    $curl = curl_init('https://us1.locationiq.com/v1/search.php?key=YOUR_PRIVATE_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.php"
    
    data = {
        'key': 'YOUR_PRIVATE_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.php?key=YOUR_PRIVATE_TOKEN&q=Empire%20State%20Building&format=json'
    
    var settings = {
      "async": true,
      "crossDomain": true,
      "url": "https://us1.locationiq.com/v1/search.php?key=YOUR_PRIVATE_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

    All three query forms accept the optional paramters listed below.

    Optional:

    Name Description Values
    format Output Format. Defaults to xml. See note [json | xml]
    viewbox 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. <string>
    bounded Restrict the results to only items contained with the viewbox [0 | 1]
    addressdetails Include a breakdown of the address into elements. Defaults to 0 [0 | 1]
    limit Limit the number of returned results. Default is 10. [1 to 50]
    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. <string>
    countrycodes Limit search to a list of countries. Read more.
    namedetails Include a list of alternative names in the results. These may include language variants, references, operator and brand. [0 | 1]
    dedupe 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. Nominatim 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. [0 | 1]
    json_callback Wrap json output in a callback function (JSONP) i.e. <string>(<json>). Only has an effect for JSON output formats. <string>
    polygon Output polygon outlines for items found [0 | 1]
    polygon_geojson Output geometry of results in geojson format. [0 | 1]
    polygon_kml Output geometry of results in kml format. [0 | 1]
    polygon_svg Output geometry of results in svg format. [0 | 1]
    polygon_text Output geometry of results as a WKT. [0 | 1]
    extratags Include additional information in the result if available, e.g. wikipedia link, opening hours. [0 | 1]
    exclude_place_ids If you do not want certain OSM objects to appear in the search result, give a comma separated list of the place_ids you want to skip. This can be used to broaden search results. For example, if a previous query only returned a few results, then including those here would cause the search to return other, less accurate, matches (if possible). <comma_separated_place_ids>

    LocationIQ specific parameters:

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

    Name Description Values
    normalizecity 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. [0 | 1]
    statecode Adds state or province code when available to the statecode key inside the address element. Currently supported for addresses in the USA, Canada and Australia. Defaults to 0 [0 | 1]

    Response

    The above command returns JSON structured like this:

    [
        {
            "place_id": "218751965",
            "licence": "© LocationIQ.com CC BY 4.0, Data © OpenStreetMap contributors, ODbL 1.0",
            "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": "© LocationIQ.com CC BY 4.0, Data © OpenStreetMap contributors, ODbL 1.0",
            "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"
        }
      ]
    
    
    Name Description
    place_id Unique ID for this element in LocationIQ database. Useful for debugging in cases of errors.
    licence The Licence and attribution requirements
    osm_type The type of this element. One of node way relation.
    osm_id The OSM ID of this element type.
    boundingbox Array of bounding box coordinates where this element is located. The order is as below:
    - min lat / bottom-left Latitude
    - max lat / top-right Latitude
    - min lon / bottom-left Longitude
    - max lon / top-right Longitude
    lat The Latitude of this element
    lon The Longitude of this element
    display_name The display name of this element, with complete address
    class The category of this element
    type The 'type' of the class/category of this element
    importance Calculated importance of this element compared to the search query the user has provided. Ranges between 0 and 1. Type: float
    icon The URL of an icon representing this element, if applicable.
    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.
    extratags The dictionary with additional useful tags like website or maxspeed. Returned when extratags=1 is set in the request.
    namedetails The dictionary with full list of available names including ref etc. Returned when namedetails=1 is set in the request.
    geojson Output geometry of results in geojson format. Returned when polygon_geojson=1 is set in the request.
    geokml Output geometry of results in kml format. Returned when polygon_kml=1 is set in the request.
    svg Output geometry of results in svg format. Returned when polygon_svg=1 is set in the request.
    geotext Output geometry of results as a WKT. Returned when polygon_text=1 is set in the request.

    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.

    Usage

    Requests can be sent to any of the following endpoints

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

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

    Query Parameters

    <?php
    
    $curl = curl_init('https://us1.locationiq.com/v1/reverse.php?key=YOUR_PRIVATE_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.php"
    
    data = {
        'key': 'YOUR_PRIVATE_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.php?key=YOUR_PRIVATE_TOKEN&lat=-37.870662&lon=144.9803321&format=json'
    
    var settings = {
      "async": true,
      "crossDomain": true,
      "url": "https://us1.locationiq.com/v1/reverse.php?key=YOUR_PRIVATE_TOKEN&lat=-37.870662&lon=144.9803321&format=json",
      "method": "GET"
    }
    
    $.ajax(settings).done(function (response) {
      console.log(response);
    });
    

    Required:

    Name Description
    key Authentication key.
    lat Latitude of the location to generate an address for.
    lon Longitude of the location to generate an address for.

    Optional:

    Name Description Values
    zoom Level of detail required where 0 is country and 18 is house/building. Defaults to 18. A lower number increases speed of the server's response. Read more. [0 to 18]
    format Output Format. Defaults to xml. See note [json | xml]
    addressdetails Include a breakdown of the address into elements. Defaults to 1. [0 | 1]
    namedetails Include a list of alternative names in the results. These may include language variants, references, operator and brand. [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. <string>
    osm_type A specific osm type, node / way / relation to search an address for [N | W | R]
    osm_id A specific osm node / way / relation to return an address for <value>
    countrycodes Limit search to a list of countries. Read more.
    json_callback Wrap json output in a callback function (JSONP) i.e. <string>(<json>). Only has an effect for JSON output formats. <string>
    polygon_geojson Output geometry of results in geojson format. [0 | 1]
    polygon_kml Output geometry of results in kml format. [0 | 1]
    polygon_svg Output geometry of results in svg format. [0 | 1]
    polygon_text Output geometry of results as a WKT. [0 | 1]
    extratags Include additional information in the result if available, e.g. wikipedia link, opening hours. [0 | 1]

    LocationIQ specific parameters:

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

    Name Description Values
    normalizecity 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. [0 | 1]
    statecode Adds state or province code when available to the statecode key inside the address element. Currently supported for addresses in the USA, Canada and Australia. Defaults to 0 [0 | 1]

    Response

    The above command returns JSON structured like this:

    {
        "place_id": "26693344",
        "licence": "© LocationIQ.com CC BY 4.0, Data © OpenStreetMap contributors, ODbL 1.0",
        "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"
        ]
    }
    
    Name Description
    place_id Unique ID for this element in LocationIQ database. Useful for debugging in cases of errors.
    licence The Licence and attribution requirements
    osm_type The type of this element. One of node way relation.
    osm_id The OSM ID of this element type.
    boundingbox Array of bounding box coordinates where this element is located. The order is as below:
    - min lat / bottom-left Latitude
    - max lat / top-right Latitude
    - min lon / bottom-left Longitude
    - max lon / top-right Longitude
    lat The Latitude of this element
    lon The Longitude of this element
    display_name The display name of this element, with complete address
    importance Calculated importance of this element compared to the search query the user has provided. Ranges between 0 and 1. Type: float
    icon The URL of an icon representing this element, if applicable.
    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.
    extratags The dictionary with additional useful tags like website or maxspeed. Returned when extratags=1 is set in the request.
    namedetails The dictionary with full list of available names including ref etc. Returned when namedetails=1 is set in the request.
    geojson Output geometry of results in geojson format. Returned when polygon_geojson=1 is set in the request.
    geokml Output geometry of results in kml format. Returned when polygon_kml=1 is set in the request.
    svg Output geometry of results in svg format. Returned when polygon_svg=1 is set in the request.
    geotext Output geometry of results as a WKT. Returned when polygon_text=1 is set in the request.

    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.

    Usage

    Requests can be sent to the following endpoint:

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

    Query Parameters

    <?php
    
    $curl = curl_init('https://api.locationiq.com/v1/autocomplete.php?key=YOUR_PRIVATE_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.php"
    
    data = {
        'key': 'YOUR_PRIVATE_TOKEN',
        'q': 'Empire'
    }
    
    response = requests.get(url, params=data)
    
    print(response.text)
    
    curl --request GET \
      --url 'https://api.locationiq.com/v1/autocomplete.php?key=YOUR_PRIVATE_TOKEN&q=Empire'
    
    var settings = {
      "async": true,
      "crossDomain": true,
      "url": "https://api.locationiq.com/v1/autocomplete.php?key=YOUR_PRIVATE_TOKEN&q=Empire",
      "method": "GET"
    }
    
    $.ajax(settings).done(function (response) {
      console.log(response);
    });
    

    Required:

    Name Description Required
    key Your API Key Yes
    q Query string to search for Yes

    Optional:

    Name Description Values
    limit Limit the number of returned results. Default is 10. [1 to 50]
    viewbox 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. Currently, this option in the Autocomplete API only increases weigtage of results inside the viewbox. It does not restrict results to this box. <string>
    json_callback Wrap json output in a callback function (JSONP) i.e. <string>(<json>) <string>
    normalizecity 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. [0 | 1]
    accept-language Preferred language for showing search results. Defaults to en. Unlike Search and Reverse endpoints, the Autocomplete endpoint supports only a single 2 digit language code. The Autocomplete endpoint currently support 4 languages: English en, French fr, German de and Italian it. If you'd like us to add support for a specific language, please reach out. Read more. [en]

    Response

    The above command returns JSON structured like this:

    [
        {
            "place_id": "0",
            "osm_id": "34633854",
            "osm_type": "way",
            "licence": "© LocationIQ.org CC BY 4.0, Data © OpenStreetMap contributors, ODbL 1.0",
            "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": "© LocationIQ.org CC BY 4.0, Data © OpenStreetMap contributors, ODbL 1.0",
            "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"
            }
        }
    ]
    
    
    Name Description
    place_id Unique ID for this element in LocationIQ database. Useful for debugging in cases of errors.
    licence The Licence and attribution requirements
    osm_type The type of this element. One of node way relation.
    osm_id The OSM ID of this element type.
    boundingbox Array of bounding box coordinates where this element is located. The order is as below:
    - min lat / bottom-left Latitude
    - max lat / top-right Latitude
    - min lon / bottom-left Longitude
    - max lon / top-right Longitude
    lat The Latitude of this element
    lon The Longitude of this element
    display_place Only the name part of the address; if the type is a city, just the city's name. If the type is highway, just the road's name. This is helpful when a client library wants to display this information separately.
    display_address The complete address without the text already present in display_place
    display_name The display name of this element, with complete address
    class The category of this element
    type The 'type' of the class/category of this element
    importance Calculated importance of this element compared to the search query the user has provided. Ranges between 0 and 1. Type: float
    icon The URL of an icon representing this element, if applicable.
    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.

    Maps

    All LocationIQ developers have access to Unwired Maps which provides world-wide Street and Satellite maps. We recommend that you generate new access tokens on your User Dashboard to access these maps. Do not use your Private API Token.

    Our map tiles can be rendered by most open-source libraries. We recommend that you use Mapbox's open-source GL javascript library for web projects and their iOS and Android SDKs for mobile projects to render our map tiles. Quick start with Mapbox >

    If you need to support older browsers (IE 9 and older), you should Leaflet instead. Quick start with Leaflet >

    Tile Urls

    You can include our map tiles in your favourite mapping library with these URLs. If you’d like to read about integrating our map tiles with Leaflet or Mapbox GL JS libraries, read on.

    Street maps in local languages
    https://{s}-tiles.locationiq.org/v2/obk/r/{z}/{x}/{y}.png?key={Your_Access_Token}

    Street maps in English (when available)
    https://{s}-tiles.locationiq.org/v2/obk-en/r/{z}/{x}/{y}.png?key={Your_Access_Token}

    Errors

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

    Desktop Maps with Mapbox GL

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

    Desktop Maps with Leaflet

    The raster maps below are rendered by the popular and open-source LeafletJS library.

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

    There's also included a quick-start guide below which will get you started on basics, including setting up a basic map, working with markers, polylines and popups, and dealing with events. For further reading, we recommend the comprehensive LeafletJS documentation.

    Before writing any code for the map, you need to do the following preparation steps on your page:

    Now you’re ready to initialize the map and do some stuff with it.

    Setting up the map

    Markers, circles and polygons

    Working with popups

    Dealing with events

    Leaflet Further reading

    For more advanced configurations and options, please refer to Leaflet's documentation.

    Mobile SDKs

    For mobile platforms, there are again 2 libraries you can use:

    Mapbox-gl Native SDK

    For everything other than the most basic Android apps, you should use the Mapbox SDKs. We've created sample apps using these SDKs for both Android & iOS show-casing use-cases popular among our customers:

    OSMDroid

    Gradle dependency

      repositories {
          mavenCentral()
      }
    
      dependencies {
          compile 'org.osmdroid:osmdroid-android:5.6.5'
      }
    

    Set a custom map tile source to Unwired Maps

      mMapView.setTileSource(new OnlineTileSourceBase("UnwiredMaps", 0, 18, 256, "",
          new String[] {
              "https://a-tiles.unwiredmaps.com/v2/obk/r/",
              "https://b-tiles.unwiredmaps.com/v2/obk/r/",
              "https://c-tiles.unwiredmaps.com/v2/obk/r/"
          }) {
    
                @Override
                public String getTileURLString(MapTile aTile) {
                    return getBaseUrl() + aTile.getZoomLevel() + "/"
                                + aTile.getX() + "/" + aTile.getY() + ".png"
                                + "?key=API_ACCESS_TOKEN";
                }
      });
    

    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

    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/v2/staticmap

    Query Parameters

    curl -o mystaticmap.png 'https://maps.locationiq.com/v2/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/v2/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/v2/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/v2/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>'>
    
    Name Description Required Values
    key Authentication key. Yes Access token
    center Defines the center of the map. It takes a comma seperated value of a latitude, longitude pair. This parameter is required if markers are not defined. Either Latitude [-90 to 90], Longitude [-180 to 180]
    zoom Set the zoom level for the map. Required if markers are not present. Defaults to 18 Yes [0 to 18]
    scale Affects the number of pixels that are returned. Defaults to 1. No [1,2].
    size Defines the rectangular dimensions of the map image. This parameter takes a string of the form {width}x{height}. Defaults to 300x300. No <string>
    format Defines the format of the resulting image. Defaults to png. No [jpeg | jpg | png]
    maptype Defines the type of the map to construct. Only roadmap is supported at the moment. No <string>
    markers Defines one or more markers to overlay on the map. Parameters are specified as key:value seperated by Pipe character. See below for the full list of parameters. Required if center is not set. Either
    path Defines one or more paths to draw on the map. Path parameters are seperated by Pipe character. See below for the full list of parameters No

    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/v2/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 :

    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.

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

    curl -o mystaticmap.png 'https://maps.locationiq.com/v2/staticmap?key=<YOUR_ACCESS_TOKEN>&center=17.450419,78.381149&size=600x600&zoom=14&path=17.452945,78.380055|17.452765,78.382026|17.452020,78.381375|17.452045,78.380846||17.452945,78.380055|fillcolor:%2390EE90|weight:2|color:blue'
    

    Example

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



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

    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.

    Directions service (Public BETA)

    The Directions service is based on work by the OSRM Project.

    General options

    All Directions service 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

    Parameter Description
    service One of the following values: directions, matching, matrix
    profile Mode of transportation. Only driving is supported at the moment.
    coordinates String of format {longitude},{latitude};{longitude},{latitude}[;{longitude},{latitude} ...] or polyline({polyline}) or polyline6({polyline6}).
    key Your public access token

    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

    Option Values Description
    bearings {bearing};{bearing}[;{bearing} ...] Limits the search to segments with given bearing in degrees towards true north in clockwise direction.
    radiuses {radius};{radius}[;{radius} ...] Limits the search to given radius in meters.
    generate_hints true (default), false Adds a Hint to the response which can be used in subsequent requests, see hints parameter.
    hints {hint};{hint}[;{hint} ...] Hint from previous request to derive position in street network.
    approaches {approach};{approach}[;{approach} ...] Keep waypoints on curb side.
    exclude {class}[,{class}] Additive list of classes to avoid, order does not matter.

    Where the elements follow the following format:

    Element Values
    bearing {value},{range} integer 0 .. 360,integer 0 .. 180
    radius double >= 0 or unlimited (default)
    hint Base64 string
    approach curb or unrestricted (default)
    class A class name determined by the profile or none.

    {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 Berlin with three coordinates:
    curl 'https://us1.locationiq.com/v1/directions/driving/13.388860,52.517037;13.397634,52.529407;13.428555,52.523219?key=<YOUR_ACCESS_TOKEN>&overview=false'
    
    # Query on Berlin excluding the usage of motorways:
    curl 'https://us1.locationiq.com/v1/directions/driving/13.388860,52.517037;13.397634,52.529407?key=<YOUR_ACCESS_TOKEN>&exclude=motorway'
    
    # Using polyline:
    curl 'https://us1.locationiq.com/v1/directions/driving/polyline([email protected]@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:

    Type HTTP Response Code Description
    Ok 200 Request could be processed as expected.
    InvalidUrl 400 URL string is invalid.
    InvalidService 400 Service name is invalid.
    InvalidOptions 400 Options are invalid.
    InvalidQuery 400 The query string is synctactically malformed.
    InvalidValue 400 The successfully parsed query parameters are invalid.
    NoSegment 404 One of the supplied input coordinates could not snap to street segment.
    TooBig 400 The request size violates one of the service specific request size restrictions.
    NoMatch 404 No matchings found.

    Directions

    Finds the fastest route between coordinates in the supplied order.

    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:

    Option Values Description
    alternatives true, false (default), or Number Search for alternative routes. Passing a number alternatives=n searches for up to n alternative routes.*
    steps true, false (default) Returned route steps for each route leg
    annotations true, false (default), nodes, distance, duration, datasources, weight, speed Returns additional metadata for each coordinate along the route geometry.
    geometries polyline (default), polyline6, geojson Returned route geometry format (influences overview and per step)
    overview simplified (default), full, false Add overview geometry either full, simplified according to highest zoom level it could be display on, or not at all.
    continue_straight default (default), true, false Forces the route to keep going straight at waypoints constraining uturns there even if it would be faster. Default value depends on the profile.

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

    Example Request

    # Query on Berlin with three coordinates and no overview geometry returned:
    curl 'https://us1.locationiq.com/v1/directions/driving/13.388860,52.517037;13.397634,52.529407;13.428555,52.523219?key=<YOUR_ACCESS_TOKEN>&overview=false'
    

    Response

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

    Type Description
    NoRoute No route found.

    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.

    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:

    Option Values Description
    steps true, false (default) Returned route steps for each route
    geometries polyline (default), polyline6, geojson Returned route geometry format (influences overview and per step)
    annotations true, false (default), nodes, distance, duration, datasources, weight, speed Returns additional metadata for each coordinate along the route geometry.
    overview simplified (default), full, false Add overview geometry either full, simplified according to highest zoom level it could be display on, or not at all.
    timestamps {timestamp};{timestamp}[;{timestamp} ...] Timestamps for the input locations in seconds since UNIX epoch. Timestamps need to be monotonically increasing.
    radiuses {radius};{radius}[;{radius} ...] Standard deviation of GPS precision used for map matching. If applicable use GPS accuracy.
    gaps split (default), ignore Allows the input track splitting based on huge timestamp gaps between points.
    tidy true, false (default) Allows the input track modification to obtain better matching quality for noisy tracks.
    waypoints {index};{index};{index}... Treats input coordinates indicated by given indices as waypoints in returned Match object. Default is to treat all input coordinates as waypoints.
    Parameter Values
    timestamp integer seconds since UNIX epoch
    radius double >= 0 (default 5m)

    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

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

    Type Description
    NoMatch No matchings found.

    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/13.388860,52.517037;13.397634,52.529407;13.428555,52.523219?key=<YOUR_ACCESS_TOKEN>'
    
    # Returns a 1x3 duration matrix
    curl 'https://us1.locationiq.com/v1/matrix/driving/13.388860,52.517037;13.397634,52.529407;13.428555,52.523219?sources=0&key=<YOUR_ACCESS_TOKEN>'
    
    # Returns a 3x3 duration matrix and a 3x3 distance matrix:
    curl 'https://us1.locationiq.com/v1/matrix/driving/13.388860,52.517037;13.397634,52.529407;13.428555,52.523219?annotations=distance,duration&key=<YOUR_ACCESS_TOKEN>'
    

    Options

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

    Option Values Description
    sources {index};{index}[;{index} ...] or all (default) Use location with given index as source.
    destinations {index};{index}[;{index} ...] or all (default) Use location with given index as destination.
    annotations duration (default), distance, or duration,distance Return the requested matrix in response.
    fallback_speed double > 0 If no route found between a source/destination pair, calculate the as-the-crow-flies distance, then use this speed to estimate duration.
    fallback_coordinate input (default), or snapped When using a fallback_speed, use the user-supplied coordinate (input), or the snapped location (snapped) for calculating distances.

    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

    Element Values
    index 0 <= integer < #locations

    Example Response

    {
      "sources": [
        {
          "location": [13.3888, 52.517033],
          "hint": "PAMAgEVJAoAUAAAAIAAAAAcAAAAAAAAArss0Qa7LNEHiVIRA4lSEQAoAAAAQAAAABAAAAAAAAADMAAAAAEzMAKlYIQM8TMwArVghAwEA3wps52D3",
          "name": "Friedrichstraße"
        },{
          "location": [13.397631, 52.529432],
          "hint": "WIQBgL6mAoAEAAAABgAAAAAAAAA7AAAAhU6PQHvHj0IAAAAAQbyYQgQAAAAGAAAAAAAAADsAAADMAAAAf27MABiJIQOCbswA_4ghAwAAXwVs52D3",
          "name": "Torstraße"
        },{
          "location": [13.428554, 52.523239]],
          "hint": "7UcAgP___38fAAAAUQAAACYAAABTAAAAhSQKQrXq5kKRbiZCWJo_Qx8AAABRAAAAJgAAAFMAAADMAAAASufMAOdwIQNL58wA03AhAwMAvxBs52D3",
          "name": "Platz der Vereinten Nationen"
        }
      ],
      "durations": [[0, 192.6, 382.8], [199, 0, 283.9], [344.7, 222.3, 0]],
      "destinations": [
        {
          "location": [13.3888, 52.517033],
          "hint": "PAMAgEVJAoAUAAAAIAAAAAcAAAAAAAAArss0Qa7LNEHiVIRA4lSEQAoAAAAQAAAABAAAAAAAAADMAAAAAEzMAKlYIQM8TMwArVghAwEA3wps52D3",
          "name": "Friedrichstraße"
        },{
          "location": [13.397631, 52.529432],
          "hint": "WIQBgL6mAoAEAAAABgAAAAAAAAA7AAAAhU6PQHvHj0IAAAAAQbyYQgQAAAAGAAAAAAAAADsAAADMAAAAf27MABiJIQOCbswA_4ghAwAAXwVs52D3",
          "name": "Torstraße"
        },{
          "location": [13.428554,52.523239],
          "hint": "7UcAgP___38fAAAAUQAAACYAAABTAAAAhSQKQrXq5kKRbiZCWJo_Qx8AAABRAAAAJgAAAFMAAADMAAAASufMAOdwIQNL58wA03AhAwMAvxBs52D3",
          "name": "Platz der Vereinten Nationen"
        }
      ],
      "code": "Ok",
      "distances": [[0, 1886.89, 3791.3], [1824, 0, 2838.09], [3275.36, 2361.73, 0]]
    }
    

    Response

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

    Type Description
    NoTable No route found.
    NotImplemented This request is not supported

    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

    overview Description
    simplified Geometry is simplified according to the highest zoom level it can still be displayed on full.
    full Geometry is not simplified.
    false Geometry is not added.

    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

    summary
    true Names of the two major roads used. Can be empty if route is too short.
    false empty string
    steps
    true array of RouteStep objects describing the turn-by-turn instructions
    false empty array
    annotations
    true An Annotation object containing node ids, durations, distances and weights.
    false undefined

    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

    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

    geometry
    polyline polyline with precision 5 in [latitude,longitude] encoding
    polyline6 polyline with precision 6 in [latitude,longitude] encoding
    geojson GeoJSON LineString

    StepManeuver object

    Properties

    type Description
    turn a basic turn into direction of the modifier
    new name no turn is taken/possible, but the road name changes. The road can take a turn itself, following modifier.
    depart indicates the departure of the leg
    arrive indicates the destination of the leg
    merge merge onto a street (e.g. getting on the highway from a ramp, the modifier specifies the direction of the merge)
    ramp Deprecated. Replaced by on_ramp and off_ramp.
    on ramp take a ramp to enter a highway (direction given my modifier)
    off ramp take a ramp to exit a highway (direction given my modifier)
    fork take the left/right side at a fork depending on modifier
    end of road road ends in a T intersection turn in direction of modifier
    use lane Deprecated replaced by lanes on all intersection entries
    continue Turn in direction of modifier to stay on the same road
    roundabout traverse roundabout, if the route leaves the roundabout there will be an additional property exit for exit counting. The modifier specifies the direction of entering the roundabout.
    rotary a traffic circle. While very similar to a larger version of a roundabout, it does not necessarily follow roundabout rules for right of way. It can offer rotary_name and/or rotary_pronunciation parameters (located in the RouteStep object) in addition to the exit parameter (located on the StepManeuver object).
    roundabout turn Describes a turn at a small roundabout that should be treated as normal turn. The modifier indicates the turn direciton. Example instruction: At the roundabout turn left.
    notification not an actual turn but a change in the driving conditions. For example the travel mode or classes. If the road takes a turn itself, the modifier describes the direction
    exit roundabout Describes a maneuver exiting a roundabout (usually preceeded by a roundabout instruction)
    exit rotary Describes the maneuver exiting a rotary (large named roundabout)

    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 Description
    uturn indicates reversal of direction
    sharp right a sharp right turn
    right a normal turn to the right
    slight right a slight turn to the right
    straight no relevant change in direction
    slight left a slight turn to the left
    left a normal turn to the left
    sharp left a sharp turn to the left

    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.

    type Description
    turn modifier indicates the change in direction accomplished through the turn
    depart/arrive modifier indicates the position of departure point and arrival point in relation to the current direction of travel

    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

    value Description
    none No dedicated indication is shown.
    uturn An indication signaling the possibility to reverse (i.e. fully bend arrow).
    sharp right An indication indicating a sharp right turn (i.e. strongly bend arrow).
    right An indication indicating a right turn (i.e. bend arrow).
    slight right An indication indicating a slight right turn (i.e. slightly bend arrow).
    straight No dedicated indication is shown (i.e. straight arrow).
    slight left An indication indicating a slight left turn (i.e. slightly bend arrow).
    left An indication indicating a left turn (i.e. bend arrow).
    sharp left An indication indicating a sharp left turn (i.e. strongly bend arrow).

    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

    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

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

    The Nearby Points of Interest (PoI) API returns specified PoIs or Places around a given coordinate.

    Usage

    Requests can be sent to any of the following endpoints

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

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

    Query Parameters

    <?php
    
    $curl = curl_init('https://us1.locationiq.com/v1/nearby.php?key=YOUR_PRIVATE_TOKEN&lat=-37.870983&lon=144.980714&tag=restaurant&radius=3000&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.php"
    
    data = {
        'key': 'YOUR_PRIVATE_TOKEN',
        'lat': '-37.870983',
        'lon': '144.980714',
        'tag': 'restaurant',
        'radius': 300,
        'format': 'json'
    }
    
    response = requests.get(url, params=data)
    
    print(response.text)
    
    curl --request GET \
      --url 'https://us1.locationiq.com/v1/nearby.php?key=YOUR_PRIVATE_TOKEN&lat=-37.870983&lon=144.980714&tag=restaurant&radius=300&format=json'
    
    var settings = {
      "async": true,
      "crossDomain": true,
      "url": "https://us1.locationiq.com/v1/nearby.php?key=YOUR_PRIVATE_TOKEN&lat=-37.870983&lon=144.980714&tag=restaurant&radius=300&format=json",
      "method": "GET"
    }
    
    $.ajax(settings).done(function (response) {
      console.log(response);
    });
    
    Name Description
    key Authentication key
    lat Latitude of the location to generate the PoI list for.
    lon Longitude of the location to generate the PoI list for.
    radius Radius (in meters) from the given latitude and longitude to generate the PoI list for. Defaults to 100 meters. Max value is 30000 meters.
    tag PoI to generate the list for. Defaults to country (check Nearby-Countries). Check here for the list of supported PoIs.
    limit No of results to look for. Defaults to 10. Max value is 50. (Pagination is not supported yet).

    Response

    The above command returns JSON structured like this:

    [  
      {
        "lat": "-37.8704051",
        "lon": "144.980984",
        "tag_type": "restaurant",
        "name": "lentil as anything",
        "distance": 68
      },
      {
        "lat": "-37.8694796",
        "lon": "144.980439",
        "tag_type": "restaurant",
        "name": "La Roche",
        "distance": 168
      }
    ]
    

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

    Name Description
    lat Latitude of the PoI.
    lon Longitude of the PoI.
    tag_type Type of the PoI.
    name Name of the PoI
    distance Distance of the PoI from the user-supplied latitude and longitude in meters.

    List of PoIs supported

    The following are the PoI tags that we currently support. This list will expand over time as we add more tags to API. If you'd like to request addition of a specific PoI tag, send us a mail here.

    Tag Description
    airport List of airports
    restaurant List of restaurants
    bank List of banks
    atm List of ATMs
    hotel List of hotels
    pub List of pubs
    bus_station List of bus stations
    railway_station List of railway stations
    cinema List of cinema theatres
    hospital List of hospitals
    college List of colleges
    school List of schools
    pharmacy List of pharmacies
    supermarket List of supermarket
    fuel List of fuel stations
    gym List of gyms
    place_of_worship List of places of worship (Temple, Church, Mosque, etc)
    toilet List of toilets
    park List of parks
    stadium List of stadiums

    Nearby - Countries (Private BETA)

    The Nearby Countries API returns countries whose geographic borders lie within a given radius.

    Usage

    Requests can be sent to any of the following endpoints

    Region 1: US
    GET https://us1.locationiq.com/v1/nearby.php?key=YOUR_PRIVATE_TOKEN&lat=50.110653&lon=8.682093&tag=countries&radius=400000&format=json

    Region 2: Europe
    GET https://eu1.locationiq.com/v1/nearby.php?key=YOUR_PRIVATE_TOKEN&lat=50.110653&lon=8.682093&tag=countries&radius=400000&format=json

    Query Parameters

    <?php
    
    $curl = curl_init('https://us1.locationiq.com/v1/nearby.php?key=YOUR_PRIVATE_TOKEN&lat=50.110653&lon=8.682093&tag=countries&radius=400000&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.php"
    
    data = {
        'key': 'YOUR_PRIVATE_TOKEN',
        'lat': '50.110653',
        'lon': '8.682093',
        'tag': 'countries',
        'radius': 400000,
        'format': 'json'
    }
    
    response = requests.get(url, params=data)
    
    print(response.text)
    
    curl --request GET \
      --url 'https://us1.locationiq.com/v1/nearby.php?key=YOUR_PRIVATE_TOKEN&lat=50.110653&lon=8.682093&tag=countries&radius=400000&format=json'
    
    var settings = {
      "async": true,
      "crossDomain": true,
      "url": "https://us1.locationiq.com/v1/nearby.php?key=YOUR_PRIVATE_TOKEN&lat=50.110653&lon=8.682093&tag=countries&radius=400000&format=json",
      "method": "GET"
    }
    
    $.ajax(settings).done(function (response) {
      console.log(response);
    });
    
    Name Description
    key Authentication key
    lat Latitude of the location to generate the POI list for.
    lon Longitude of the location to generate the POI list for.
    radius Radius (in meters) from the given latitude and longitude. Limited to 5,000,000 meters (5000 KM / 3106 miles)
    tag (optional) defaults to country.

    Response

    The above command returns JSON structured like this:

    [
        "at",
        "lu",
        "li",
        "ch",
        "it",
        "de",
        "cz",
        "be",
        "fr",
        "nl"
    ]
    

    A JSON object containing the names of the countries that fall within proximity.

    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.php?key=YOUR_PRIVATE_TOKEN&format=json

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

    Query Parameters

    <?php
    
    $curl = curl_init('https://us1.locationiq.com/v1/balance.php?key=YOUR_PRIVATE_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.php"
    
    data = {
        'key': 'YOUR_PRIVATE_TOKEN'
    }
    
    response = requests.get(url, params=data)
    
    print(response.text)
    
    curl --request GET \
      --url 'https://us1.locationiq.com/v1/balance.php?key=YOUR_PRIVATE_TOKEN&format=json'
    
    var settings = {
      "async": true,
      "crossDomain": true,
      "url": "https://us1.locationiq.com/v1/balance.php?key=YOUR_PRIVATE_TOKEN&format=json",
      "method": "GET"
    }
    
    $.ajax(settings).done(function (response) {
      console.log(response);
    });
    
    Name Description Required
    key Authentication key Yes

    Response

    The above command returns JSON structured like this:

    {
        "status": "ok",
        "balance": {
            "day": 30000,
            "bonus" : 0
        }
    }
    
    Name Description
    status ok on success; error on error
    balance An array comprising individual components such as day and bonus. See Balance Object below for details.

    Balance Object

    Name Description
    day Balance of requests credits in your account for the day
    bonus Balance of bonus / promotional request credits in your account

    Client Libraries

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

    Official Client Libraries

    The official libraries currently support the following endpoints:

    Language Tested by LocationIQ
    java yes
    objc yes
    php yes
    python yes
    swift4 yes
    clojure no
    csharp no
    dart no
    go no
    haskell no
    nodejs no
    kotlin no
    perl no
    qt5cpp no
    r no
    ruby no
    rust no
    scala no

    Unofficial Client Libraries

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

    Language Author
    go Jerry Zhao
    node Nicolas Chaulet
    php William Durand
    python Denis Carriere
    ruby Alex Reisner

    Notes

    Address details

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

    Name Description
    house_number House Number
    road Road Name
    neighbourhood Neighbourhood
    hamlet Hamlet
    suburb Suburb
    village Village name
    town Town name
    city City name
    region Region name
    county County name
    state_district District name
    state State name
    postcode Postal code
    country Country name
    country_code Country code
    name Name of the entity/road in given location

    Accept Language

    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.

    Country Codes

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

    Country code Country
    de Germany
    gb United Kingdom
    us United States of America

    Zoom Levels

    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:

    zoom address detail
    3 country
    5 state
    8 county
    10 city
    14 suburb
    16 street
    18 building

    Errors

    {
        "error": "Error message"  
    }
    

    When the API encounters any errors it responds the following error messages in the body and corresponding HTTP codes in the header:

    Error message HTTP Response code Description
    Invalid Request 400 Required parameters are missing, or invalid
    Invalid key 401 An invalid API key was provided
    Key not active - Please write to [email protected] 401 API Key provided is invalid or inactive
    Service not enabled 403 The specific service is not enabled on your token. Write to [email protected] to enable this.
    Unable to geocode 404 No location or places were found for the given input
    Imagery not found 404 No tile available for the specified url
    Rate Limited Second 429 Request exceeded the per-second rate-limits set on your account
    Rate Limited Minute 429 Request exceeded the per-minute rate-limits set on your account
    Rate Limited Day 429 Request exceeded the per-day rate-limits set on your account
    Unknown error - Please try again after some time 500 This is an error on the server's side, we monitor this 24x7 and you should try again.