Skip to content

/places/near-point

GET
Use dark colors for code blocksCopy
1
https://places-api.arcgis.com/arcgis/rest/services/places-service/v1/places/near-point
Search for places near a point or location by radius.

The /places/near-point request finds places that are within a given radius of a specified location. The returned places contain basic data such as name, category and location.

To perform the request, you must supply the x and y coordinates of the point from which to search. Optionally, you can also specify the:

  • Search radius (1 to 10,000 meters)
  • Category IDs
  • Search text

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
xXCoord

The x coordinate, or longitude, to search from, in WGS84 decimal degrees.

yYCoord

The y coordinate, or latitude, to search from, in WGS84 decimal degrees.

radiusSearchDistance1000

The radius in meters to search for places - measured from the supplied x and y coordinate.

categoryIds[CategoryId]

Filters places to those that match the category Ids.

searchTextstring

Free search text for places against names, categories etc.

pageSizeinteger10

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

iconstringnone

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

offsetinteger

Request results starting from the given offset.

fstringjson

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

tokenstring

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

x

The x coordinate, or longitude, to search from, in WGS84 decimal degrees.

Minimum
-180
Maximum
180

y

The y coordinate, or latitude, to search from, in WGS84 decimal degrees.

Minimum
-90
Maximum
90

radius

The radius in meters to search for places - measured from the supplied x and y coordinate.

A radius of 100 meters will result in a circular search area that is 200 meters in diameter. If omitted, the default search radius will be 1,000 meters.

Minimum
1
Maximum
10000
Default
1000

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

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

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

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

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.

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

StatusMeaningDescriptionSchema
200OK

A successful response for a places/near-point request.

inline
400Bad Request

Invalid query parameters.

Error
401Unauthorized

Authentication Error. The API key or token is missing, invalid or expired.

Error
403Forbidden

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

NameTypeRequiredDescription
results[NearPointResult]
paginationPagination

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

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/near-point?x=-117.205&y=34.056 \
  -H 'Authorization: Bearer <YOUR_TOKEN>'

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
26
{
  "results": [
    {
      "placeId": "2da082218b6f7538e52250999c8f8ef1",
      "location": {
        "x": -117.194769,
        "y": 34.057289
      },
      "categories": [
        {
          "categoryId": "63be6904847c3692a84b9b90",
          "label": "Technology Business"
        }
      ],
      "name": "Esri International",
      "distance": 50,
      "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"
  }
}

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