Back to Website
Guides
Dashboard

Nearby - Points of Interest

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

Suggest Edits

🚧

Public Beta

The Nearby API endpoint is presently in BETA. The request or response format may change without notice. While we don't expect to remove any elements, there will be additions.

Request

Requests can be sent to any of the following endpoints

Region 1: US

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

Region 2: Europe

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

Request Example

<?php

$curl = curl_init('https://us1.locationiq.com/v1/nearby?key=YOUR_ACCESS_TOKEN&lat=-37.870983&lon=144.980714&tag=restaurant&radius=100&format=json');

curl_setopt_array($curl, array(
  CURLOPT_RETURNTRANSFER    =>  true,
  CURLOPT_FOLLOWLOCATION    =>  true,
  CURLOPT_MAXREDIRS         =>  10,
  CURLOPT_TIMEOUT           =>  30,
  CURLOPT_CUSTOMREQUEST     =>  'GET',
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

import requests

url = "https://us1.locationiq.com/v1/nearby"

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

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

print(response.text)

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

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

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

Request parameters

NameDescription
latLatitude of the location to return results for
lonLongitude of the location to return results for
radiusRadius (in meters) from the given latitude and longitude to search for results in.
- Accepted value: 1 to 30,000.
- Defaults to 100.

📘

List of all input parameters available on the API Reference page

Response

Response Example

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

🚧

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

Response Parameters

NameDescription
latLatitude of the PoI
lonLongitude of the PoI
nameName of the PoI
display_nameThe display name of this result, with complete address
addressThe address breakdown into individual components. Important components include (but not limited to) country, country_code, postcode, state, county, city, town. Read more.

📘

List of all response parameters available on the API Reference page

Filter Results with Tags

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

1. Single-word Format (Simple)

The below example lists schools within 1000 meters

<?php

$curl = curl_init('https://us1.locationiq.com/v1/nearby?key=YOUR_ACCESS_TOKEN&lat=-37.870983&lon=144.980714&tag=school&radius=1000&format=json');

curl_setopt_array($curl, array(
  CURLOPT_RETURNTRANSFER    =>  true,
  CURLOPT_FOLLOWLOCATION    =>  true,
  CURLOPT_MAXREDIRS         =>  10,
  CURLOPT_TIMEOUT           =>  30,
  CURLOPT_CUSTOMREQUEST     =>  'GET',
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

import requests

url = "https://us1.locationiq.com/v1/nearby"

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

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

print(response.text)

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

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

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

The above command returns JSON structured like this:

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

📘

List of all supported tags is available on the API Reference page

2. Key Value Format (Advanced)

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

<?php

$curl = curl_init('https://us1.locationiq.com/v1/nearby?key=YOUR_ACCESS_TOKEN&lat=40.748428&lon=-73.985654&tag=tourism:*&radius=50&format=json');

curl_setopt_array($curl, array(
  CURLOPT_RETURNTRANSFER    =>  true,
  CURLOPT_FOLLOWLOCATION    =>  true,
  CURLOPT_MAXREDIRS         =>  10,
  CURLOPT_TIMEOUT           =>  30,
  CURLOPT_CUSTOMREQUEST     =>  'GET',
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

import requests

url = "https://us1.locationiq.com/v1/nearby"

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

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

print(response.text)

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

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

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

The above command returns JSON structured like this:

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

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

Examples:

TagDescription
allReturn a list of all PoIs
amenity:*Returns records with amenity class. PoIs such as restaurants, hospitals, banks are returned under the amenity class.
amenity:schoolReturns records with the amenity class and school as type, i.e. a list of schools.
all,!amenity:*Returns all records except those with amenity as class
amenity:*,!amenity:gymReturns all records in the amenity class except gym
!amenity:gymReturns of all records except elements with amenity as class and gym as type.
aeroway:aerodrome,tourism:hotel,amenity:parkingReturns a list of airports, hotels and parking spaces nearby.

Updated about 1 year ago