Skip to content

Nearby search

Search for places in New York using a category, text filter, and radius

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 placeId, name, categories, distance, and location.
  • Find place IDs so you can request additional place details.

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:

  1. Get the places service URL.
  2. Set the parameters:
    • x, y
    • radius
    • categoryIds, searchText
    • pageSize
  3. Execute the request.
Use dark colors for code blocksCopy
1
 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 pageSize, you can start paging.

The steps to start paging are:

  1. Execute the initial search request (see above).
  2. Use the response to check response.links. If the value is valid, you can page.
  3. Build the next search request:
    • Use response.links.base and response.links.next to create the URL.
    • The offset parameter is automatically added and incremented for you.
    • Add token=<ACCESS_TOKEN> to provide authentication.
  4. Execute the next search request.
  5. Repeat the steps until response.links is null. This indicates no additional results are available.

You can use paging to request up to 200 places.

Use dark colors for code blocksCopy
1
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

Use dark colors for code blocksCopy
1
https://places-api.arcgis.com/arcgis/rest/services/places-service/v1/near-point?x=<LONGITUDE>&y=<LATITUDE>&token=<ACCESS_TOKEN>&f=pjson

Parameters

NameInTypeRequiredDefault valueDescription
xqueryXCoord

The x coordinate, or longitude, to search from, in WGS84 decimal degrees.

yqueryYCoord

The y coordinate, or latitude, to search from, in WGS84 decimal degrees.

radiusquerySearchDistance1000

The radius in meters to search for places - measured from the supplied x and y coordinate.

categoryIdsqueryarray[string]

Filters places to those that match the category Ids.

searchTextquerystring

Free search text for places against names, categories etc.

pageSizequeryinteger10

The number of places that should be sent in the response for a single request.

iconquerystringnone

Determines whether icons are returned and the type of icon to use with a place or category.

offsetqueryinteger

Request results starting from the given offset.

fquerystringjson

The requested response format - either json or pjson (pretty json).

tokenquerystring

The authentication token, created from an ArcGIS Location Platform account, with the premium:user:places privilege, used to access the Places service.


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

  1. Reference the places service.
  2. Define the x and y coordinates, categoryIds, and radius.
  3. Set the token parameter to your access token.
Find places in specific categories within a 500 meter search radius.

APIs

ArcGIS Maps SDK for JavaScriptArcGIS Maps SDK for JavaScriptArcGIS API for PythonArcGIS REST JSEsri LeafletMapLibre GL JSOpenLayersCesiumJS
Expand
Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
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

cURLcURLHTTP
Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
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 categoryIds and searchText 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

  1. Reference the places service.
  2. Define the x and y coordinates, categoryIds, and the searchText parameters.
  3. Set the token parameter to your access token.
Filter results from specific categories using a text search

APIs

ArcGIS Maps SDK for JavaScriptArcGIS Maps SDK for JavaScriptArcGIS API for PythonArcGIS REST JSEsri LeafletMapLibre GL JSOpenLayersCesiumJS
Expand
Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
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

cURLcURLHTTP
Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

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 pageSize, 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

  1. Reference the places service.
  2. Define the x and y coordinates for the search.
  3. Set the token parameter to your access token.
  4. Using ArcGIS REST JS, if response.nextPage is valid, use the nextPage() to send the next request.

APIs

ArcGIS Maps SDK for JavaScriptArcGIS Maps SDK for JavaScriptArcGIS API for PythonArcGIS REST JSEsri LeafletMapLibre GL JSOpenLayersCesiumJS
Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
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

cURLcURLHTTP
Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
## 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.


Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.