NAV Navbar
shell php python javascript
  • Introduction
  • Authentication
  • Search / Forward Geocoding
  • Reverse Geocoding
  • Autocomplete
  • Maps
  • Static Maps
  • Nearby - Points of Interest (PoI) (Private BETA)
  • Nearby - Countries (Private BETA)
  • Balance
  • 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 Query string to search for Either
    street
    city
    county
    state
    country
    postalcode
    Alternative query string format for structured requests. Do not combine with q= parameter Either
    postalcode Alternative query string format for postal code requests. Do not combine with q= parameter. Combine with countrycodes= parameter for a better response Either

    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 [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.
    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>) <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]

    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]

    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 extratags defined for this element. Returned when extratags=1 is set in the request.
    namedetails The names defined in other languages for this element. 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. [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.
    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>) <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]

    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 extratags defined for this element. Returned when extratags=1 is set in the request.
    namedetails The names defined in other languages for this element. 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]

    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 >

    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 included a quick-start guide 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.

    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
        }
    }
    
    Name Description
    status ok on success; error on error
    day Balance requests left in the account for the day

    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.

    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

    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
    Unable to geocode 404 No location or places were found for the given input
    Invalid key 401 An invalid API key was provided
    Invalid Request 400 Required parameters are missing, or invalid
    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
    Key not active - Please write to [email protected] 401 API Key provided is invalid or inactive
    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.