Search for places within an extent (bounding box).
The /places/within-extent
request searches for places within an extent (bounding box).
You must supply the xmin
,
ymin
, xmax
and ymax
coordinates to define the extent. The maximum width
and height of an extent that can be used in a search is 20,000 meters.
You can also provide multiple categories or search text to find specific types of places within the extent.
The default number of places returned (page
) is 10. The maximum page
value is 20.
If the pagination.next
property in the response is populated, then you can
page through the results to return more places. The maximum number of
places that can be paged to is 200.
Note: You cannot permanently store places. Please see the Terms of use.
Note: Query parameters are case-sensitive.
Query parameters
Name | Type | Required | Default value | Description |
---|---|---|---|---|
| The minimum x coordinate, or longitude, of the search extent. | |||
| The minimum y coordinate, or latitude, of the search extent. | |||
| The maximum x coordinate, or longitude, of the search extent. | |||
| The maximum y coordinate, or latitude, of the search extent. | |||
|
| Filters places to those that match the category Ids. | ||
|
| Free search text for places against names, categories etc. | ||
|
| The number of places that should be sent in the response for a single request. | ||
|
| Request results starting from the given offset. | ||
|
| The requested response format - either | ||
|
| The authentication token with the |
xmin
The minimum x coordinate, or longitude, of the search extent.
This is the furthest west that will be searched.
- Minimum
- -180
- Maximum
- 180
ymin
The minimum y coordinate, or latitude, of the search extent.
This is the furthest south that will be searched.
- Minimum
- -90
- Maximum
- 90
xmax
The maximum x coordinate, or longitude, of the search extent.
This is the furthest east that will be searched.
- Minimum
- -180
- Maximum
- 180
ymax
The maximum y coordinate, or latitude, of the search extent.
This is the furthest north that will be searched.
- Minimum
- -90
- Maximum
- 90
categoryIds
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.
pageSize
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.next
. 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 page
is 10.
- Minimum
- 1
- Maximum
- 20
- Default
- 10
offset
Request results starting from the given offset.
This parameter works with the page
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
.
- Maximum
- 199
f
The requested response format - either json
or pjson
(pretty json).
- Default
- json
Enumerated values
token
The authentication token with the premium:
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>
Examples
Request
# You can also use wget
curl -X GET https://places-api.arcgis.com/arcgis/rest/services/places-service/v1/places/within-extent?xmin=-117.194769&ymin=34.057289&xmax=-117.194769&ymax=34.057289 \
-H 'Accept: application/json'
Response
200 Response
{
"results": [
{
"placeId": "722d8e1ba4db8ec5ef256b09cf060782",
"location": {
"x": -117.194769,
"y": 34.057289
},
"categories": [
{
"categoryId": 17119,
"label": "Bicycle Store"
}
],
"name": "Esri International"
}
],
"pagination": {
"previousUrl": "https://places-api.arcgis.com/arcgis/rest/services/places-service/v1/places/near-point?x=-117.194769&y=34.057289&radius=50.0&offset=0&pageSize=10",
"nextUrl": "https://places-api.arcgis.com/arcgis/rest/services/places-service/v1/places/near-point?x=-117.194769&y=34.057289&radius=50.0&offset=20&pageSize=10"
}
}
Status | Meaning | Description | Schema |
---|---|---|---|
| A successful response for a | Inline | |
| Invalid query parameters. | ||
| Authentication Error. The API key or token is missing, invalid or expired. | ||
| The required parameter 'token' is valid but does not have permission to access the service. | ||
| Unknown | An error occurred on the server. |
Response details
Status Code 200
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
| none | A result of searching for places using a The result object includes a single place that satisfied the search. | ||
| none | The unique Id of this place. This place Id can be passed to the | ||
| none | A point defined in WGS84 decimal degrees. | ||
|
| none | An x-coordinate, or longitude, in WGS84 decimal degrees. | |
|
| none | A y-coordinate, or latitude, in WGS84 decimal degrees. | |
|
| none | A list of category objects for a place. Categories are uniquely identified by a | |
| none | The category Id uniquely identifies this category or type of place. The name of the category can be looked up using the
| ||
|
| none | The label that describes the category. | |
|
| none | The name of the place, or point of interest.
You can search for places by name using the | |
| none | Provides pagination links for accessing more results for the current request. | ||
|
| none | A url for fetching the previous page of results. Use this property to request the previous page of results if
available. If this property is omitted then there are no previous
pages of results. You must also supply authentication details, such
as a | |
|
| none | A url for fetching the next page of results. Use this property to request the next page of results if available. If
this property is omitted then there are no more pages of results
available. You must also supply authentication details, such as a
|