Bounding box search

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

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:

  1. Get the places service URL.
  2. Set the parameters:
    • xmin, xmax, ymin, ymax
    • 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/within-extent?f=json&xmin=-0.01399040222167969&ymin=51.504148054725356&xmax=0.014548301696777345&ymax=51.51579343362533&categoryIds=11000&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:

  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/within-extent?f=json&xmin=-0.01399040222167969&ymin=51.504148054725356&xmax=0.014548301696777345&ymax=51.51579343362533&categoryIds=11000&pageSize=20&offset=20&token=<ACCESS_TOKEN>

URL request

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

NameInTypeRequiredDefault valueDescription
query

The minimum x coordinate, or longitude, of the search extent, in WGS84 decimal degrees.

This is the furthest west that will be searched.

query

The minimum y coordinate, or latitude, of the search extent, in WGS84 decimal degrees.

This is the furthest south that will be searched.

query

The maximum x coordinate, or longitude, of the search extent, in WGS84 decimal degrees.

This is the furthest east that will be searched.

query

The maximum y coordinate, or latitude, of the search extent, in WGS84 decimal degrees.

This is the furthest north that will be searched.

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.

query
string

Free search text for places against names, categories etc.

query
string
none

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

example icon

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 none (no icon URL will be returned).

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 pagination.nextUrl. This can be used to request the next page of results.

Regardless of paging, the maximum number of places that can be returned in total is 200.

The default pageSize is 10.

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 in total is 200.

query
string
json

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

query
string

The authentication token, created from an ArcGIS Location Platform account, 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 map extent for Helsinki. Moving the map will execute a search for the new extent.

The categories are:

  • Museum (16027)
  • Park (16032)
  • Monument (16026)
  • Dog parks (16033)
  • Playgrounds (16037)

Steps

  1. Reference the places service.
  2. Set the min and max x and y values for the extent and the categoryIds.
  3. Set the token parameter to your access token.
Find places in specific categories within the current map extent.

APIs

ArcGIS REST JSArcGIS REST JSArcGIS Maps SDK for JavaScriptArcGIS API for PythonEsri LeafletMapLibre GL JSOpenLayers
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
50
findPlacesWithinExtent({
  xmin: 24.897,
  ymin: 60.159,
  xmax: 24.979,
  ymax: 60.178,
  categoryIds: ["16026", "10027", "16032", "16033", "16037"],
  authentication,
}).then(response => {
  console.log(JSON.stringify(response.results, 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
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=["16026", "10027", "16032", "16033", "16037"]' \
-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 the map extent for area in London. Moving the map will execute a search for the new extent.

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

Steps

  1. Reference the places service.
  2. Define the extent for the search and set the categoryIds and searchText parameters with the keywords.
  3. Set the token parameter to your access token.
Find places based on search text.

APIs

ArcGIS REST JSArcGIS REST JSArcGIS Maps SDK for JavaScriptArcGIS API for PythonEsri LeafletMapLibre GL JSOpenLayers
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
50
findPlacesWithinExtent({
  xmin: -0.107,
  ymin: 51.513,
  xmax: -0.148,
  ymax: 51.502,
  searchText: "sports",
  categoryIds: ["13018", "13051", "18065"],
  authentication,
}).then(response => {
  console.log(JSON.stringify(response.results, 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
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=["13018", "13051", "18065"]' \
-d 'token=<ACCESS_TOKEN>' \
-d 'f=pjson'

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

  1. Reference the places service.
  2. Define the extent for the search.
  3. Set the token parameter to your access token.
  4. Using ArcGIS REST JS, if repsponse.nextPage is valid, use the nextPage() to send the next request.
Return 200 places by paging through result response.

APIs

ArcGIS REST JSArcGIS REST JSArcGIS Maps SDK for JavaScriptArcGIS API for PythonEsri LeafletMapLibre GL JSOpenLayers
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
50
const getPlaces = async () => {
  let places = await arcgisRest.findPlacesWithinExtent({
    xmin: -122.322,
    ymin: 47.609,
    xmax: -122.342,
    ymax: 47.603,
    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

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

Tutorials

Find places in a bounding box

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


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