Nearby search

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

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 placeId, name, categories, distance, and location.
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
- categoryIds, searchText
- pageSize
Execute the request.

Use dark colors for code blocksCopy
 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 pageSize, 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 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.
Execute the next search request.
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
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

Use dark colors for code blocksCopy
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	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 `x` and `y` coordinate. 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.
`categoryIds`	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 `places/categories` endpoint. For example, to filter for places where the category is "Bicycle Store", include the categoryId `17117` in this property. You can search up to a maximum of `10` 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. You can set this to any value up to `20` when you need to control the size of responses that your app downloads. If the query results in more than this page size, then the response object will contain a `next` url fragment. This fragment can be used to form a request url to fetch the next page of results. The maximum number of places that can be returned in total is `200`. If a request reaches this limit without returning all of the available places, the response will contain the property `"maxResultsExceeded":true` in addition to place results. The default `pageSize` is 10.
`offset`	query	`integer`		Request results starting from the given offset. This parameter works with the `pageSize` parameter to fetch results from subsequent pages. For example, with a page size of 2, setting the `offset` to `2` would return the 3rd and 4th results. Regardless of paging, the maximum number of places that can be returned by a single query is `200`. When a query results in more than `200` places, the response will contain the property `"maxResultsExceeded":true` in addition to place results.
`f`	query	`string`	`json`	The requested response format - either `json` or `pjson` (pretty json).
`token`	query	`string`		The authentication token with the `premium:user:places` privilege, used to access the Places service. The `token` parameter can be either an API Key or short-lived token. See ArcGIS security documentation for more information on authenticating with a token or API key. Alternatively, you can supply a token in the request header with one of the following keys using the "Bearer" scheme: `Authorization: Bearer <YOUR_TOKEN>` `X-Esri-Authorization: Bearer <YOUR_TOKEN>`

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 and y coordinates, categoryIds, and radius.
Set the token parameter to your access token.

Find places in specific categories within a 500 meter search radius.

APIs

ArcGIS REST JS

Esri Leaflet

MapLibre GL JS

OpenLayers

Use dark colors for code blocks

Copy

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
import { ApiKeyManager } from "@esri/arcgis-rest-request";
import { findPlacesNearPoint } from "@esri/arcgis-rest-places";

const apiKey = "YOUR_API_KEY";

const authentication = ApiKeyManager.fromKey(apiKey);

findPlacesNearPoint({
  x: 24.938,
  y: 60.169,
  categoryIds: ["16026", "16041", "10027"],
  radius: 500,
  authentication,
}).then(results => {
  console.log(JSON.stringify(results.places, null, 2));
});

Go to tutorial

REST API

cURL

HTTP

Use dark colors for code blocks

Copy

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/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'

Run in Postman

Use dark colors for code blocks

Copy

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
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
{
    "results": [
        {
            "placeId": "ab756a46cd59b2998f386367fd11e7cd",
            "location": {
                "x": 24.937485,
                "y": 60.168314
            },
            "categories": [
                {
                    "categoryId": "10027",
                    "label": "Museum"
                }
            ],
            "name": "Amos Andersonin taidemuseo",
            "distance": 81.4
        },
        {
            "placeId": "cc8b3eb4e906e8d3e1fbf0d9413e2b74",
            "location": {
                "x": 24.939931,
                "y": 60.169082
            },
            "categories": [
                {
                    "categoryId": "16041",
                    "label": "Plaza"
                }
            ],
            "name": "Ylioppilasaukio",
            "distance": 107.2
        },
        // more results...
    ],
    "maxResultsExceeded": false,
    "links": {
        "base": "https://places-api.arcgis.com",
        "next": "/arcgis/rest/services/places-service/v1/places/within-extent?xmin=24.89700000&ymin=60.15900000&xmax=24.97900000&ymax=60.17800000&categoryIds=16026,10027,16032&f=pjson&offset=20&pageSize=20"
    }
}

See full response

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 (13018)
Fish and Chips Shop (13051)
Sports Club (18065)

Steps

Reference the places service.
Define the x and y coordinates, categoryIds, and the searchText parameters.
Set the token parameter to your access token.

Filter results from specific categories using a text search

APIs

ArcGIS REST JS

Esri Leaflet

MapLibre GL JS

OpenLayers

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
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));
});

Expand

Go to API reference

REST API

cURL

HTTP

Use dark colors for code blocks

Copy

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/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'

Run in Postman

Use dark colors for code blocks

Copy

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
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103

{
  "results": [
    {
        "placeId": "22a25084338d14aa48e41a2387880c44",
        "location": {
            "x": -0.12833,
            "y": 51.50711
        },
        "categories": [
            {
                "categoryId": "18065",
                "label": "Sports Club"
            }
        ],
        "name": "News Sports",
        "distance": 54.8
    },
    {
        "placeId": "4b8962295377a7d46e7acea54dab3198",
        "location": {
            "x": -0.12721,
            "y": 51.50643
        },
        "categories": [
            {
                "categoryId": "18065",
                "label": "Sports Club"
            }
        ],
        "name": "Ireland Wales Rugby",
        "distance": 100.4
    },,
    // more results...
  ],
  "maxResultsExceeded": false,
  "links": {
      "base": "https://places-api.arcgis.com",
      "next": "/arcgis/rest/services/places-service/v1/places/near-point?x=-0.12760000&y=51.50730000&radius=1609.34400000&searchText=sports&categoryIds=13018,13051,18065&f=pjson&offset=20&pageSize=20"
  }
}

See full response

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

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

APIs

ArcGIS REST JS

Esri Leaflet

MapLibre GL JS

OpenLayers

Use dark colors for code blocks

Copy

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
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();

Go to API reference

REST API

cURL

HTTP

Use dark colors for code blocks

Copy

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'

Run in Postman

Use dark colors for code blocks

Copy

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
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
// initial request
{
    "results":"results...",
    "maxResultsExceeded": true,
    "links": {
        "base": "https://places-api.arcgis.com",
        "next": "/arcgis/rest/services/places-service/v1/places/near-point?x=174.77800000&y=-41.29200000&f=pjson&offset=20&pageSize=20"
    }
}

// next request
{
    "results":["results..."],
    "maxResultsExceeded": true,
    "links": {
        "base": "https://places-api.arcgis.com",
        "previous": "/arcgis/rest/services/places-service/v1/places/near-point?x=174.77800000&y=-41.29200000&f=pjson&offset=0&pageSize=20",
        "next": "/arcgis/rest/services/places-service/v1/places/near-point?x=174.77800000&y=-41.29200000&f=pjson&offset=40&pageSize=20"
    }
}

See full initial response See full next response

Tutorials

Find nearby places and details

Find points of interest near a location and get detailed information about them

Services

Places service (Beta)

Find and get details about businesses, places, and other POI.

API support

	Category search	Nearby search	Boundary search	Place details
ArcGIS Maps SDK for JavaScript	¹	¹	¹	¹
ArcGIS Maps SDK for .NET
ArcGIS Maps SDK for Kotlin
ArcGIS Maps SDK for Swift
ArcGIS Maps SDK for Java
ArcGIS Maps SDK for Qt
ArcGIS API for Python
ArcGIS REST JS
Esri Leaflet	¹	¹	¹	¹
MapLibre GL JS	¹	¹	¹	¹
OpenLayers	¹	¹	¹	¹
CesiumJS	¹	¹	¹	¹

Full supportPartial supportNo support

1. Access via ArcGIS REST JS.

Tools

Places category finder

Find and select categories to create a JSON array of IDs.

Mapping APIs and location services

Nearby search

Was this page helpful?

Was this page helpful?