/places/near-point

Click to copy

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 (up 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

Name	Type	Default value	Description
`x`	`XCoord`		The x coordinate, or longitude, to search from, in WGS84 decimal degrees.
`y`	`YCoord`		The y coordinate, or latitude, to search from, in WGS84 decimal degrees.
`radius`	`SearchDistance`	`1000`	The radius in meters to search for places - measured from the supplied `x` and `y` coordinate.
`categoryIds`	`array[string]`		Filters places to those that match the category Ids.
`searchText`	`string`		Free search text for places against names, categories etc.
`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 `json` or `pjson` (pretty json).
`token`	`string`		The authentication token 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 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.

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 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
# You can also use wget
curl -X GET https://places-api.arcgis.com/arcgis/rest/services/places-service/v1/places/near-point?x=-117.194769&y=34.057289 \
  -H 'Accept: application/json'

Response

200 Response

Use dark colors for code blocksCopy
{
  "results": [
    {
      "placeId": "722d8e1ba4db8ec5ef256b09cf060782",
      "location": {
        "x": -117.194769,
        "y": 34.057289
      },
      "categories": [
        {
          "categoryId": 17119,
          "label": "Bicycle Store"
        }
      ],
      "name": "Esri International",
      "distance": 50
    }
  ],
  "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
`200`	OK	A successful response for a `places/near-point` 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

Name	Type	Restrictions	Description
`results`	`[NearPointResult]`	none	A result of searching for places using a `places/near-point` request. The result object includes a single place that satisfied the search and the distance from the search point, in meters.
`placeId`	`PlaceId`	none	The unique Id of this place. This place Id can be passed to the `places/{placeId}` endpoint to retrieve additional details.
`location`	`Point`	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`	`[Category]`	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`	`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.
`distance`	`number`	none	The distance, in meters, from the place to the search point of a 'places/near-point` query.
`pagination`	`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.

ArcGIS REST APIsPlaces service (beta)API reference

/places/near-point

Was this page helpful?