https://places-api.arcgis.com/arcgis/rest/services/places-service/v1/places/within-extentThe /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. The width and height of an extent
must be greater than 0 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 (pageSize) is 10. The maximum
pageSize value is 20.
If the pagination.nextUrl 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 |
|---|---|---|---|---|
xmin | XCoord | | The minimum x coordinate, or longitude, of the search extent, in WGS84 decimal degrees. | |
ymin | YCoord | | The minimum y coordinate, or latitude, of the search extent, in WGS84 decimal degrees. | |
xmax | XCoord | | The maximum x coordinate, or longitude, of the search extent, in WGS84 decimal degrees. | |
ymax | YCoord | | The maximum y coordinate, or latitude, of the search extent, in WGS84 decimal degrees. | |
categoryIds | [CategoryId] | | Filters places to those that match the category Ids. | |
searchText | string | | Free search text for places against names, categories etc. | |
icon | string | none | Determines whether icons are returned and the type of icon to use with a place or category. | |
pageSize | integer | 10 | The number of places that should be sent in the response for a single request. | |
offset | integer | | Request results starting from the given offset. | |
f | string | json | The requested response format - either | |
token | string | | The authentication token, created from an ArcGIS Location Platform account, with the |
xmin
The minimum x coordinate, or longitude, of the search extent, in WGS84 decimal degrees.
This is the furthest west that will be searched.
- Minimum
- -180
- Maximum
- 180
ymin
The minimum y coordinate, or latitude, of the search extent, in WGS84 decimal degrees.
This is the furthest south that will be searched.
- Minimum
- -90
- Maximum
- 90
xmax
The maximum x coordinate, or longitude, of the search extent, in WGS84 decimal degrees.
This is the furthest east that will be searched.
- Minimum
- -180
- Maximum
- 180
ymax
The maximum y coordinate, or latitude, of the search extent, in WGS84 decimal degrees.
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
4bf58dd8d48988d115951735 in this property.
You can search up to a maximum of 10 category Ids.
searchText
Free search text for places against names, categories etc.
- Minimum length
- 3
- Maximum length
- 255
icon
Determines whether icons are returned and the type of icon to use with a place or category.
Use this parameter to define the type of icon URL for a given place or category. Place icons are available in the following formats:
svgcim(Cartographic Information Model)png48 x 48 pixels
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).
- Default
- none
Enumerated values
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.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.
- Minimum
- 1
- Maximum
- 20
- Default
- 10
offset
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.
- Minimum
- 0
- Maximum
- 199
- Default
- 0
f
The requested response format - either json or pjson (pretty json).
- Default
- json
Enumerated values
token
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.
This parameter is required unless you supply an access 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>
Response status
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | A successful response for a | inline |
| 400 | Bad Request | Invalid query parameters. | Error |
| 401 | Unauthorized | Authentication Error. The API key or token is missing, invalid or expired. | Error |
| 403 | Forbidden | The required parameter 'token' is valid but does not have permission to access the service. | Error |
| 5XX | **Server Error** | An error occurred on the server. | Error |
Response details
Status Code 200
| Name | Type | Required | Description |
|---|---|---|---|
results | [WithinExtentResult] | ||
pagination | Pagination | Provides pagination links for accessing more results for the current request. |
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=-73.982&ymin=40.764&xmax=-73.949&ymax=40.801 \
-H 'Authorization: Bearer <YOUR_TOKEN>'Response
{
"results": [
{
"placeId": "2da082218b6f7538e52250999c8f8ef1",
"location": {
"x": -117.194769,
"y": 34.057289
},
"categories": [
{
"categoryId": "63be6904847c3692a84b9b90",
"label": "Technology Business"
}
],
"name": "Esri International",
"icon": {
"url": "https://static.arcgis.com/icons/places/Default_Shop_or_Service_15.svg"
}
}
],
"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"
}
}