What is a nearby search?
A nearby search finds places within a given radius of a location. The location typically represents a point on a map or the geolocation of a device.
You can use this search to:
- Find and display places within a distance of a location.
- Get the latitude and longitude for places.
- Filter places using categories and/or text.
- Find place attributes including
place
,Id name
,categories
,distance
, andlocation
. - Find place IDs so you can request additional place details.
How to perform a nearby search
To perform a nearby search, you use the places service /places/near-point
request and set the x
and y
coordinates and the radius in meters that you would like to search. The default radius is 1,000 meters and the maximum value is 10,000 meters.
The general steps are:
- Get the places service URL.
- Set the parameters:
x
,y
radius
category
,Ids search
Text page
Size
- Execute the request.
https://places-api.arcgis.com/arcgis/rest/services/places-service/v1/places/near-point?f=json&x=-74.006792&y=40.711646&radius=450&categoryIds=63be6904847c3692a84b9bb5&pageSize=20&searchText=bar&token=<ACCESS_TOKEN>
If the number of places in the search area is greater than the page
, you can start paging.
The steps to start paging are:
- Execute the initial search request (see above).
- Use the response to check
response.links
. If the value is valid, you can page. - Build the next search request:
- Use
response.links.base
andresponse.links.next
to create the URL. - The
offset
parameter is automatically added and incremented for you. - Add
token=
to provide authentication.<ACCESS _TOKEN >
- Use
- Execute the next search request.
- Repeat the steps until
response.links
isnull
. This indicates no additional results are available.
You can use paging to request up to 200 places.
https://places-api.arcgis.com/arcgis/rest/services/places-service/v1/places/near-point?f=json&x=-74.006792&y=40.711646&radius=450&categoryIds=63be6904847c3692a84b9bb5&pageSize=20&offset=20&searchText=bar&token=<ACCESS_TOKEN>
URL request
https://places-api.arcgis.com/arcgis/rest/services/places-service/v1/near-point?x=<LONGITUDE>&y=<LATITUDE>&token=<ACCESS_TOKEN>&f=pjson
Parameters
Name | In | Type | Required | Default value | Description |
---|---|---|---|---|---|
x | query | XCoord |
| The x coordinate, or longitude, to search from, in WGS84 decimal degrees. | |
y | query | YCoord |
| The y coordinate, or latitude, to search from, in WGS84 decimal degrees. | |
radius | query | SearchDistance | 1000 | The radius in meters to search for places - measured from the supplied | |
categoryIds | query | array[string] |
| Filters places to those that match the category Ids. | |
searchText | query | string |
| Free search text for places against names, categories etc. | |
pageSize | query | integer | 10 | The number of places that should be sent in the response for a single request. | |
icon | query | string | none | Determines whether icons are returned and the type of icon to use with a place or category. | |
offset | query | integer |
| Request results starting from the given offset. | |
f | query | string | json | The requested response format - either | |
token | query | string |
| The authentication token, created from an ArcGIS Location Platform account, with the |
Code examples
Find places by category
In this example, you use specific categories to find places within a location near Helsinki within a 500 meter radius. Clicking on the map will execute a new search.
The categories are:
- Museum (
4bf58dd8d48988d181941735
) - Park (
4bf58dd8d48988d163941735
) - Monument (
4bf58dd8d48988d12d941735
)
Steps
- Reference the places service.
- Define the
x
andy
coordinates,category
, andIds radius
. - Set the token parameter to your access token.
APIs
places.queryPlacesNearPoint({
point: {
x: 24.938,
y: 60.169
},
categoryIds: ["4bf58dd8d48988d12d941735", "4bf58dd8d48988d164941735", "4bf58dd8d48988d181941735"],
radius: 500
}).then(results => {
console.log(JSON.stringify(results.places, null, 2));
});
REST API
curl 'https://places-api.arcgis.com/arcgis/rest/services/places-service/v1/places/near-point' \
-d 'x=24.938' \
-d 'y=60.169' \
-d 'radius=500' \
-d 'categoryIds=4bf58dd8d48988d12d941735,4bf58dd8d48988d164941735,4bf58dd8d48988d163941735' \
-d 'token=<ACCESS_TOKEN>' \
-d 'f=pjson'
Find places by category and text
In this example, you use the category
and search
parameters to find places that are within 1609 meters of a location in London. Clicking on the map will execute a new search.
The categories are:
- Pub (
4bf58dd8d48988d11b941735
) - Fish and Chips Shop (
4edd64a0c7ddd24ca188df1a
) - Sports Club (
52e81612bcbc57f1066b7a2e
)
Steps
- Reference the places service.
- Define the
x
andy
coordinates,category
, and theIds search
parameters.Text - Set the token parameter to your access token.
APIs
places.queryPlacesNearPoint({
point: {
x: -0.1276,
y: 51.5073
},
searchText: "sports",
radius: 1609.344,
categoryIds: ["4bf58dd8d48988d11b941735", "4edd64a0c7ddd24ca188df1a", "52e81612bcbc57f1066b7a2e"]
}).then(results => {
console.log(JSON.stringify(results.places, null, 2));
});
REST API
curl 'https://places-api.arcgis.com/arcgis/rest/services/places-service/v1/places/near-point' \
-d 'x=-0.1276' \
-d 'y=51.5073' \
-d 'searchText=sports' \
-d 'radius = 1609.344' \
-d 'categoryIds=4bf58dd8d48988d11b941735,4edd64a0c7ddd24ca188df1a,52e81612bcbc57f1066b7a2e' \
-d 'token=<ACCESS_TOKEN>' \
-d 'f=pjson'
Page through results
This example searches for all places without using categories within 250 m of a location in Wellington. Clicking on the map will execute a new search.
If there are more results than the page
, you can page through them using the next
URL in the links
attribute. The maximum number of places that you can page through is 200
.
Steps
- Reference the places service.
- Define the
x
andy
coordinates for the search. - Set the token parameter to your access token.
- Using ArcGIS REST JS, if
response.next
is valid, use thePage next
to send the next request.Page()
APIs
const getPlaces = async () => {
let lastResponse = await places.queryPlacesNearPoint({
point: {
x: 174.778,
y: -41.292
},
radius: 250
});
console.log(JSON.stringify(lastResponse.results, null, 2));
while (lastResponse.nextPage) {
try {
lastResponse = await lastResponse.nextPage();
console.log(JSON.stringify(lastResponse.results, null, 2));
} catch {
break;
}
}
};
getPlaces();
REST API
## initial request
curl 'https://places-api.arcgis.com/arcgis/rest/services/places-service/v1/places/near-point' \
-d 'x=174.778' \
-d 'y=-41.292' \
-d 'radius=250' \
-d 'pageSize=20' \
-d 'token=<ACCESS_TOKEN>' \
-d 'f=pjson'
## next request
curl 'https://places-api.arcgis.com/arcgis/rest/services/places-service/v1/places/near-point' \
-d 'x=174.778' \
-d 'y=-41.292' \
-d 'radius=250' \
-d 'pageSize=20' \
-d 'offset=40' \
-d 'token=<ACCESS_TOKEN>' \
-d 'f=pjson'
Tutorials

Find nearby places and details
Find points of interest near a location and get detailed information about them.