NAV Navbar
shell php python javascript
  • Introduction
  • Forward Geocoding
  • Reverse Geocoding
  • 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.

    Forward Geocoding

    Geocoding is the process of 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 API is fully compatible with OpenStreetMap's Nominatim API.

    Usage

    Requests can be sent to any of the following endpoints

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

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

    Query Parameters

    <?php
    
    $curl = curl_init('https://us1.locationiq.org/v1/search.php?key=YOUR_API_KEY&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.org/v1/search.php"
    
    data = {
        'KEY': 'YOUR_API_KEY',
        'q': 'Empire State Building'
        'format': 'json'
    }
    
    response = requests.get(url, params=data)
    
    print(response.text)
    
    curl --request GET \
      --url 'https://us1.locationiq.org/v1/search.php?key=YOUR_API_KEY&q=Empire%20State%20Building&format=json'
    
    var settings = {
      "async": true,
      "crossDomain": true,
      "url": "https://us1.locationiq.org/v1/search.php?key=YOUR_API_KEY&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

    Optional:

    Name Description Values
    format Output Format. Defaults to xml [json | xml]
    viewbox The preferred area to find search results. Any two corner points of the box are accepted in any order as long as they span a real box. <left>,<top>,<right>,<bottom>
    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. Max 50 <integer>
    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. Defaults to en. [Read more]. (#accept-language)
    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]

    Response

    The above command returns JSON structured like this:

    [
        {
            "place_id": "218751965",
            "licence": "© LocationIQ.org 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.org/static/images/mapicons/poi_point_of_interest.p.20.png"
        },
        {
            "place_id": "29167569",
            "licence": "© LocationIQ.org 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.org/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.

    This API is fully compatible with OpenStreetMap's Nominatim API.

    Usage

    Requests can be sent to any of the following endpoints

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

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

    Query Parameters

    <?php
    
    $curl = curl_init('https://us1.locationiq.org/v1/reverse.php?key=YOUR_API_KEY&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.org/v1/reverse.php"
    
    data = {
        'key': 'YOUR_API_KEY',
        'lat': '-37.870662',
        'lon': '144.9803321',
        'format': 'json'
    }
    
    response = requests.get(url, params=data)
    
    print(response.text)
    
    curl --request GET \
      --url 'https://us1.locationiq.org/v1/reverse.php?key=YOUR_API_KEY&lat=-37.870662&lon=144.9803321&format=json'
    
    var settings = {
      "async": true,
      "crossDomain": true,
      "url": "https://us1.locationiq.org/v1/reverse.php?key=YOUR_API_KEY&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-18]
    format Output Format. Defaults to xml. [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. Either uses standard rfc2616 accept-language string or a simple comma separated list of language codes. Defaults to en. [Read more]. (#accept-language)
    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]

    Response

    The above command returns JSON structured like this:

    {
        "place_id": "26693344",
        "licence": "© LocationIQ.org 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
    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.

    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.org/v1/nearby.php?key=YOUR_API_KEY&lat=LATITUDE&lon=LONGITUDE&tag=POI&radius=IN_METERS&format=json

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

    Query Parameters

    <?php
    
    $curl = curl_init('https://us1.locationiq.org/v1/nearby.php?key=YOUR_API_KEY&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.org/v1/nearby.php"
    
    data = {
        'key': 'YOUR_API_KEY',
        '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.org/v1/nearby.php?key=YOUR_API_KEY&lat=-37.870983&lon=144.980714&tag=restaurant&radius=300&format=json'
    
    var settings = {
      "async": true,
      "crossDomain": true,
      "url": "https://us1.locationiq.org/v1/nearby.php?key=YOUR_API_KEY&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.org/v1/nearby.php?key=YOUR_API_KEY&lat=50.110653&lon=8.682093&tag=countries&radius=400000&format=json

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

    Query Parameters

    <?php
    
    $curl = curl_init('https://us1.locationiq.org/v1/nearby.php?key=YOUR_API_KEY&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.org/v1/nearby.php"
    
    data = {
        'key': 'YOUR_API_KEY',
        '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.org/v1/nearby.php?key=YOUR_API_KEY&lat=50.110653&lon=8.682093&tag=countries&radius=400000&format=json'
    
    var settings = {
      "async": true,
      "crossDomain": true,
      "url": "https://us1.locationiq.org/v1/nearby.php?key=YOUR_API_KEY&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

    Region 1: US
    GET https://us1.locationiq.org/v1/balance.php?key=YOUR_API_KEY&format=json

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

    Query Parameters

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

    The above command returns JSON structured like this:

    {
        "status": "ok",
        "balance": {
            "day": 30000
        }
    }
    
    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 429 Request exceeded the per-second / minute / 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.