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=13000&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=13000&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=<LONGITUIDE>&y=<LATITUDE>&token=<ACCESS_TOKEN>&f=pjson
Parameters
Name | In | Type | Required | Default value | Description |
---|---|---|---|---|---|
query |
| The x coordinate, or longitude, to search from, in WGS84 decimal degrees. | |||
query |
| The y coordinate, or latitude, to search from, in WGS84 decimal degrees. | |||
query | 1000 | The radius in meters to search for places - measured from the supplied A radius of 100 meters will result in a circular search area that is 200 meters in diameter. If omitted, the default search radius will be 1,000 meters. | |||
query | array[string] |
| Filters places to those that match the category Ids. Places will be returned if they match any of the category Ids. If this property is not set, places will be returned regardless of their category. You can obtain information on category Ids from the
You can search up to a maximum of | ||
query | string |
| Free search text for places against names, categories etc. | ||
query | integer | 10 | The number of places that should be sent in the response for a single request. You can set this to any value up to If the query results in more than this page size, then the response
object will contain a Regardless of paging, the maximum number of places that can be returned
in total is The default | ||
query | string | none | Determines whether icons are returned and the type of icon to use with a place or category. Use this parameter to define the type of icon URL for a given place or category. Place icons are available in the following formats:
The SVG and CIM symbols default to 15 x 15 pixels but can be scaled smoothly for display in larger UI elements or to emphasize these features on a map. The PNG icons are provided as 48 x 48 pixels but for map display the recommended size is 16 x 16 pixels. The default is | ||
query | integer |
| Request results starting from the given offset. This parameter works with the Regardless of paging, the maximum number of places that can be returned
in total is | ||
query | string | json | The requested response format - either | ||
query | string |
| The authentication token, created from an ArcGIS Location Platform account, with the The Alternatively, you can supply a token in the request header with one of the following keys using the "Bearer" scheme:
|
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 (10027)
- Park (16032)
- Monument (16026)
Steps
- Reference the places service.
- Define the
x
andy
coordinates,category
, andIds radius
. - Set the token parameter to your access token.
APIs
findPlacesNearPoint({
x: 24.938,
y: 60.169,
categoryIds: ["16026", "16041", "10027"],
radius: 500,
authentication,
}).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=16026,16041,16032' \
-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 (13018)
- Fish and Chips Shop (13051)
- Sports Club (18065)
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
findPlacesNearPoint({
x: -0.1276,
y: 51.5073,
searchText: "sports",
radius: 1609.344,
categoryids: ["13018", "13051", "18065"],
authentication,
}).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=13018,13051,18065' \
-d 'token=<ACCESS_TOKEN>' \
-d 'f=pjson'
Page through results
This example searches for all places without using categories within 250m 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
repsponse.next
is valid, use thePage next
to send the next request.Page()
APIs
const getPlaces = async () => {
let lastResponse = await arcgisRest.findPlacesNearPoint({
x: 174.778,
y: -41.292,
radius: 250,
authentication,
})
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.