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
place
,Id name
,categories
, andlocation
. - 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
category
,Ids search
Text page
Size
- Execute the request.
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 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/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
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 | Required | 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 | |
token | query | string |
| The authentication token, created from an ArcGIS Location Platform account, with the |
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
andy
values for the extent and thecategory
.Ids - Set the token parameter to your access token.
APIs
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));
});
REST API
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'
Find places by category and text
In this example, you use the category
and search
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
category
andIds search
parameters with the keywords.Text - Set the token parameter to your access token.
APIs
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));
});
REST API
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'
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 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 extent for the search.
- Set the token parameter to your access token.
- Using ArcGIS REST JS, if
response.next
is valid, use thePage next
to send the next request.Page()
APIs
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();
REST API
## 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.