Bounding box search

Search for places in London using a category and/or text filter

What is a bounding box search?

A bounding box search finds places within an extent. An extent typically represents the visible area of a map.

You can use this search to:

Find and display places within a current map extent.
Get the latitude and longitude for places.
Filter places using categories and/or text.
Find place attributes including placeId, name, categories, and location.
Find place IDs so you can request additional place details.

How a bounding box search works

To perform a bounding box search, you use the places service /places/within-extent request and set the xmin, ymin, xmax, and ymax coordinates. The maximum width and height of the search extent is 20,000 meters.

The general steps are:

Get the places service URL.
Set the parameters:
- xmin, xmax, ymin, ymax
- categoryIds, searchText
- pageSize
Execute the request.

Use dark colors for code blocksCopy
https://places-api.arcgis.com/arcgis/rest/services/places-service/v1/places/within-extent?f=json&xmin=-0.01399040222167969&ymin=51.504148054725356&xmax=0.014548301696777345&ymax=51.51579343362533&categoryIds=4d4b7105d754a06375d81259&pageSize=20&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/within-extent?f=json&xmin=-0.01399040222167969&ymin=51.504148054725356&xmax=0.014548301696777345&ymax=51.51579343362533&categoryIds=4d4b7105d754a06375d81259&pageSize=20&offset=20&token=<ACCESS_TOKEN>

URL request

Use dark colors for code blocksCopy
https://places-api.arcgis.com/arcgis/rest/services/places-service/v1/within-extent?xmin=<LONGITUDE>&ymin=<LATITUDE>&xmax=<LONGITUDE>&ymax=<LATITUDE>&token=<ACCESS_TOKEN>&f=pjson

Parameters

Name	In	Type	Default value	Description
`xmin`	query	`XCoord`		The minimum x coordinate, or longitude, of the search extent, in WGS84 decimal degrees.
`ymin`	query	`YCoord`		The minimum y coordinate, or latitude, of the search extent, in WGS84 decimal degrees.
`xmax`	query	`XCoord`		The maximum x coordinate, or longitude, of the search extent, in WGS84 decimal degrees.
`ymax`	query	`YCoord`		The maximum y coordinate, or latitude, of the search extent, in WGS84 decimal degrees.
`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.
`icon`	query	`string`	`none`	Determines whether icons are returned and the type of icon to use with a place or category.
`pageSize`	query	`integer`	`10`	The number of places that should be sent in the response for a single request.
`offset`	query	`integer`		Request results starting from the given offset.
`f`	query	`string`	`json`	The requested response format - either `json` or `pjson` (pretty json).
`token`	query	`string`		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 map extent for Helsinki. Moving the map will execute a search for the new extent.

The categories are:

Museum (4bf58dd8d48988d181941735)
Park (4bf58dd8d48988d163941735)
Monument (4bf58dd8d48988d12d941735)
Dog parks (4bf58dd8d48988d1e5941735)
Playground (4bf58dd8d48988d1e7941735)

Steps

Reference the places service.
Set the min and max x and y values for the extent and the categoryIds.
Set the token parameter to your access token.

Find places in specific categories within the current map extent.

APIs

ArcGIS Maps SDK for JavaScript

ArcGIS API for Python

ArcGIS REST JS

Esri Leaflet

MapLibre GL JS

OpenLayers

CesiumJS

Expand

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
places.queryPlacesWithinExtent({
  extent: {
    xmin: 24.897,
    ymin: 60.159,
    xmax: 24.979,
    ymax: 60.178
  },
  categoryIds: ["4bf58dd8d48988d12d941735", "4bf58dd8d48988d181941735", "4bf58dd8d48988d163941735", "4bf58dd8d48988d1e5941735", "4bf58dd8d48988d1e7941735"]
}).then(response => {
  console.log(JSON.stringify(response.results, 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
37
38
39
40

curl 'https://places-api.arcgis.com/arcgis/rest/services/places-service/v1//within-extent' \
-d 'xmin=24.897' \
-d 'ymin=60.159' \
-d 'xmax=24.979' \
-d 'ymax=60.178' \
-d 'categoryIds=["4bf58dd8d48988d12d941735", "4bf58dd8d48988d181941735", "4bf58dd8d48988d163941735", "4bf58dd8d48988d1e5941735", "4bf58dd8d48988d1e7941735"]' \
-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

{
"results": [
    {
    "placeId": "f0a1450694ba6d102d164249631f0919",
    "location": {
        "x": 24.929854,
        "y": 60.174766
    },
    "categories": [
        {
        "categoryId": "4bf58dd8d48988d163941735",
        "label": "Park"
        }
    ],
    "name": "Museon puisto"
    },
    {
    "placeId": "6ce75addaa6db1471e0beb51d8e21bc9",
    "location": {
        "x": 24.943898,
        "y": 60.165202
    },
    "categories": [
        {
        "categoryId": "4bf58dd8d48988d163941735",
        "label": "Park"
        },
        {
        "categoryId": "4bf58dd8d48988d164941735",
        "label": "Plaza"
        }
    ],
    // more results...
  ],
    "pagination": {
        "nextUrl": "https://places-api.arcgis.com/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 the map extent for area in London. Moving the map will execute a search for the new extent.

This example uses the restaurants (4d4b7105d754a06374d81259) category to find and filter places.

Steps

Reference the places service.
Define the extent for the search and set the categoryIds and searchText parameters with the keywords.
Set the token parameter to your access token.

Find places based on search text.

APIs

ArcGIS Maps SDK for JavaScript

ArcGIS API for Python

ArcGIS REST JS

Esri Leaflet

MapLibre GL JS

OpenLayers

CesiumJS

Expand

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
places.queryPlacesWithinExtent({
  extent: {
    xmin: -0.107,
    ymin: 51.513,
    xmax: -0.148,
    ymax: 51.502
  },
  searchText: "sports",
  categoryIds: ["4bf58dd8d48988d11b941735", "4edd64a0c7ddd24ca188df1a", "52e81612bcbc57f1066b7a2e"]
}).then(response => {
  console.log(JSON.stringify(response.results, 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
37
38
39
40
curl 'https://places-api.arcgis.com/arcgis/rest/services/places-service/v1//within-extent' \
-d 'xmin=-0.107' \
-d 'ymin=51.513' \
-d 'xmax=-0.148' \
-d 'ymax=51.502' \
-d 'searchText="sports"' \
-d 'categoryIds=["4bf58dd8d48988d11b941735", "4edd64a0c7ddd24ca188df1a", "52e81612bcbc57f1066b7a2e"]' \
-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
{
    "results": [
        {
            "placeId": "22a25084338d14aa48e41a2387880c44",
            "location": {
                "x": -0.128309,
                "y": 51.50718
            },
            "categories": [
                {
                    "categoryId": "52e81612bcbc57f1066b7a2e",
                    "label": "Sports Club"
                }
            ],
            "name": "News Sports"
        },
      // more results...
  ],
}

See full response

Page through results

This example searches for all places without using categories for an extent near Seattle. Moving the map will execute a search for the new extent.

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 extent for the search.
Set the token parameter to your access token.
Using ArcGIS REST JS, if response.nextPage is valid, use the nextPage() to send the next request.

Return 200 places by paging through result response.

APIs

ArcGIS Maps SDK for JavaScript

ArcGIS API for Python

ArcGIS REST JS

Esri Leaflet

MapLibre GL JS

OpenLayers

CesiumJS

Expand

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
const getPlaces = async () => {
  let place = await places.queryPlacesWithinExtent({
    extent: {
      xmin: -122.322,
      ymin: 47.609,
      xmax: -122.342,
      ymax: 47.603
    }
  });

  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
37
38
39
40
## initial request
curl 'https://places-api.arcgis.com/arcgis/rest/services/places-service/v1/places/within-extent' \
-d 'xmin=-122.322' \
-d 'ymin=47.609' \
-d 'xmax=-122.342' \
-d 'ymax=47.603' \
-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/within-extent' \
-d 'xmin=-122.322' \
-d 'ymin=47.609' \
-d 'xmax=-122.342' \
-d 'ymax=47.603' \
-d 'offset=40' \
-d 'pageSize=20' \
-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
// initial request
{
  "results":["<results array>"]
  "pagination": {
    "nextUrl": "https://places-api.arcgis.com/arcgis/rest/services/places-service/v1/places/within-extent?xmin=-122.32164860&ymin=47.60912875&xmax=-122.34233379&ymax=47.60286441&f=pjson&offset=20&pageSize=20"
  }
}

// next request
{
  "results":["<results array>"],
  "links": {
    "previousUrl": "https://places-api.arcgis.com/arcgis/rest/services/places-service/v1/places/within-extent?xmin=-122.32164860&ymin=47.60912875&xmax=-122.34233379&ymax=47.60286441&f=pjson&offset=0&pageSize=20",
    "nextUrl": "https://places-api.arcgis.com/arcgis/rest/services/places-service/v1/places/within-extent?xmin=-122.32164860&ymin=47.60912875&xmax=-122.34233379&ymax=47.60286441&f=pjson&offset=40&pageSize=20"
  }
}

See full initial response See full next response

Tutorials

Find places in a bounding box

Perform a text-based search to find places within a bounding box.

Esri Leaflet MapLibre GL JS OpenLayers CesiumJS REST JS REST API