Finds Locations within a geographic area, ordered by proximity or rating.
The search area is defined either by a center point and radius or by a bounding box, supplied via
the search parameters. Results are restricted to Locations you are licensed to access and
return the full Location representation, optionally with a single representative photo.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Search Nearby Locations requests
A Search Nearby Locations request takes a geographic area and returns the Locations within it, ordered by distance or rating. Results are limited to Locations on your allowlist.
Define the search area in one of three ways. The strategies are mutually exclusive.
| Strategy | Parameters |
|---|---|
| Radius around a point | lat, lon, radius, unit |
| Radius around a Location | location_id, radius, unit |
| Bounding box | sw_lat, sw_lon, ne_lat, ne_lon |
Search Nearby Locations responses
The response is a paged object. The data array contains the matching Locations. Each entry carries the full Location representation plus distance_kilometers, distance_miles and bearing, measured from the center point. The pagination object carries page, size, total_elements and total_pages. Pages are 1-based.
Both distance fields are returned regardless of the unit parameter. unit controls only how the radius value is interpreted.
bearing is the initial forward azimuth in degrees from the center point to the Location.
Search parameters
radius and unit
unit is MI (default) or KM. radius must be greater than 0, and has a maximum that depends on the unit:
| Unit | Maximum radius |
|---|---|
KM | 8 |
MI | 5 |
A larger value returns 400 with the message `radius` cannot be greater than 8.0 KM.
Bounding box
All four corners are required when radius is not given. Omitting any returns 400 with the message `sw_lat`, `sw_lon`, `ne_lat`, `ne_lon` are required when `radius` is not specified.
sw_lat must be less than ne_lat, otherwise 400 with the message `sw_lat` must be less than `ne_lat`.
min_rating
Returns only Locations rated at least this value, from 1 to 5.
sort
rating,desc by default. distance,asc is available for radius searches only, not for bounding boxes.
include_photo
When true, adds a single representative photo to each result. For the full set, use Location Photos.
Limits
size must be between 1 and 20 inclusive, and defaults to 20. A larger value returns 400 with the message 'size' should not go over 20.
The result offset, calculated as size × (page − 1), must not exceed 40. A larger offset returns 400 with the message The requested offset ('size' times 'page') should not go over 40. At the default size of 20, pages 1 through 3 are available and page 4 is not, so a single center point returns at most 60 Locations. To reach more, narrow the radius and issue separate requests, or apply filters.
Note: mixing parameters from two strategies returns 400 with the message Ambiguous set of parameters, unable to determine searching strategy. Send lat and lon, or location_id, or the four bounding-box corners — not a combination.
Note: the search and nearby endpoints have a lower rate limit than the rest of your package. Wait for a map to settle rather than issuing a request per pan. See API Access and Limits.
Note: results are restricted to your allowlist. An empty data array in a dense area usually indicates the allowlist rather than absent data.
Examples
Find restaurants within 2 km of a point
curl "https://terra.tripadvisor.com/api/locations/nearby?version=1&lat=48.8566&lon=2.3522&radius=2&unit=KM&category=RESTAURANT" \
-H "X-API-Key: API_KEY"Find highly rated Locations around a known Location
curl "https://terra.tripadvisor.com/api/locations/nearby?version=1&location_id=187147&radius=1&unit=KM&min_rating=4" \
-H "X-API-Key: API_KEY"Search a bounding box and include a photo
curl "https://terra.tripadvisor.com/api/locations/nearby?version=1&sw_lat=48.84&sw_lon=2.32&ne_lat=48.87&ne_lon=2.37&include_photo=true" \
-H "X-API-Key: API_KEY"Order results by distance
curl "https://terra.tripadvisor.com/api/locations/nearby?version=1&lat=48.8566&lon=2.3522&radius=2&unit=KM&sort=distance,asc" \
-H "X-API-Key: API_KEY"Related
- Search Nearby Locations Catalog — not restricted by allowlist, and no offset ceiling
- Search Locations — text search
- Catalog Search vs Location Search