Back to Website
Guides
Dashboard
Start typing to search…

Nearby - Places

The Nearby API returns nearby places around a specified location. Results can include points of interest such as cafes, hospitals, and airports, as well as place-level features such as cities, depending on the requested tag.

🚧

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

Name

Description

lat

Latitude of the location to return results for

lon

Longitude of the location to return results for

radius

Radius (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
  }
]

Additional Tag Examples

Use tag=city when you want nearby city results with the simple format.

curl --request GET \
  --url 'https://us1.locationiq.com/v1/nearby?key=YOUR_ACCESS_TOKEN&lat=51.5073219&lon=-0.1276474&tag=city&radius=30000&format=json'

Use the key-value format when you need exclusions such as returning place-level results but excluding villages.

curl --request GET \
  --url 'https://us1.locationiq.com/v1/nearby?key=YOUR_ACCESS_TOKEN&lat=51.5073219&lon=-0.1276474&tag=place:*,!place:village&radius=30000&format=json'

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
cityReturns nearby cities
amenity:*Returns records with amenity class. PoIs such as restaurants, hospitals, banks are returned under the amenity class.
place:*,!place:villageReturns place-level results except villages
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 4 days ago