v1

latestOpenAPI 3.0.02026-07-241437122.4 KB

Nearby

Nearby - Places (Public BETA)

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.

Note: 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.

get/nearby

Query parameters

latnumber float required

Example:40.748442

Latitude of the location to generate an address for.

lonnumber float required

Example:-73.985658

Longitude of the location to generate an address for.

tagstring

Example:amenity:school

You can use a tag to restrict Nearby API results to specific types of places. 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)

For most use-cases, the list of tags below should suffice. Multiple tags can be specified as a comma-separated list.

Tag	Description
all	Return a list of all places
airport	List of airports
city	List of nearby cities
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
toilet	List of toilets
park	List of parks
stadium	List of stadiums
parking	List of parking
cardealer	List of car dealers

2. Key Value Format (Advanced)

For advanced use-cases that need additional tags not present in the table above, we also support tags based on OpenStreetMap''s (OSM) <a href="https://wiki.openstreetmap.org/wiki/Map_Features" target="_blank">exhaustive list</a> 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:

To return a list of all places: tag=all
To return city records: tag=place:city
To return records with amenity class (e.g., restaurants, hospitals, banks): tag=amenity:*
To return records with the amenity class and school as type (i.e., a list of schools): tag=amenity:school
To return all records except those with amenity as class: tag=all,!amenity:*
To return all records in the amenity class except gym: tag=amenity:*,!amenity:gym
To return all records except elements with amenity as class and gym as type: tag=!amenity:gym
To return a list of airports, hotels, and parking spaces nearby: tag=aeroway:aerodrome,tourism:hotel,amenity:parking

radiusinteger

Radius (in meters) from the given latitude and longitude to search for results in. Accepted value: 1 to 500000. Defaults to 100.

Note: Nearby API results are matched using each result's associated location point, not the full boundary or area of the result. A result is returned only when the search radius reaches that point.

For example, a search near outer London may not return London until the radius is large enough to reach London's associated location point, even if part of the wider London area is already within the search radius.

limitinteger

Limit the number of returned results. Accepted value: 1 to 50. Defaults to 10.

dedupe0 | 1

When enabled, the geocoder attempts to filter out duplicate results for the same real-world place. Because limit is applied before deduplication, fewer results than requested may be returned.

Response

place_idstring required

Unique identifier for the place.

licencestring required

License information for the data.

osm_typestring

Type of OpenStreetMap object.

osm_idstring

Unique identifier for the OpenStreetMap object.

latstring required

Latitude of the location.

lonstring required

Longitude of the location.

display_namestring required

Formatted address for display.

classstring

The category of this result

typestring

The 'type' of the class/category of this result

boundingboxstring[] required

List of bounding box coordinates [min_lat, max_lat, min_lon, max_lon].

Example response

[
  {
    "address": {
      "house_number": "3894",
      "road": "Spring Mill Way",
      "residential": "Hunter’s Point",
      "village": "Landen",
      "city": "Landen",
      "county": "Warren County",
      "state": "Ohio",
      "postcode": "45039",
      "country": "United States of America",
      "country_code": "us",
      "state_code": "oh"
    }
  }
]