/places/within-extent

Click to copy

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

NameTypeRequiredDefault valueDescription

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

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

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

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

array[string]

Filters places to those that match the category Ids.

string

Free search text for places against names, categories etc.

string

none

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

integer

10

The number of places that should be sent in the response for a single request.

integer

Request results starting from the given offset.

string

json

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

string

The authentication token, created from an ArcGIS Location Platform account, with the premium:user:places privilege, used to access the Places service.

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 17117 in this property.

You can search up to a maximum of 10 category Ids.

searchText

Free search text for places against names, categories etc.

icon

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).

Default
none
Enumerated values
none
Click to copy
svg
Click to copy
png
Click to copy
cim
Click to copy

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.

Maximum
199

f

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

Default
json
Enumerated values
json
Click to copy
pjson
Click to copy

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.

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

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

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
{
  "results": [
    {
      "placeId": "2da082218b6f7538e52250999c8f8ef1",
      "location": {
        "x": -117.194769,
        "y": 34.057289
      },
      "categories": [
        {
          "categoryId": "11167",
          "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"
  }
}
StatusMeaningDescriptionSchema

200

OK

A successful response for a places/within-extent request.

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

Unknown

An error occurred on the server.

Error

Response details

Status Code 200

NameTypeRequiredRestrictionsDescription

results

none

A result of searching for places using a places/within-extent request.

The result object includes a single place that satisfied the search.

placeId

none

The unique Id of this place.

This place Id can be passed to the places/{placeId} endpoint to retrieve additional details.

location

none

A point defined in WGS84 decimal degrees.

x

XCoord(double)

none

An x-coordinate, or longitude, in WGS84 decimal degrees.

y

YCoord(double)

none

A y-coordinate, or latitude, in WGS84 decimal degrees.

categories

none

A list of category objects for a place.

Categories are uniquely identified by a categoryId. For example, 17119 identifies a "Bicycle Store" and 10051 identifies a "Stadium". Note that a single place can belong to multiple categories (for example, a petrol station could also have a super-market).

categoryId

none

The category Id uniquely identifies this category or type of place.

The name of the category can be looked up using the places/categories endpoint. For example, "17119" is the id for a "Bicycle Store".

label

string

none

The label that describes the category.

name

string

none

The name of the place, or point of interest. You can search for places by name using the searchText property in a places/near-point or places/within-extent request.

icon

none

Details of an icon, suitable for depicting this place.

To fetch icon details use the icon query parameter.

url

string(url)

none

Url for an icon for this place or category in either svg, cim or png format.

pagination

none

Provides pagination links for accessing more results for the current request.

previousUrl

string(url)

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 token, to make a previous page request.

nextUrl

string(url)

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 token, to make a next page request.

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