Place search

Locations of businesses by category found near a point with the geocoding service

What is place search?

Place search, also known as point of interest (POI) search, is the process of searching for businesses, administrative boundaries, and geographic features. For example, you can search for restaurants near a point, counties in a state, or land features such as the Grand Canyon.

You can use place search to:

Find the locations of geographic places around the world.
Locate businesses near a location.
Search for places by category such as restaurants, gas stations, or schools.
Find and display places on a map.

How place search works

You can search for a place by making an HTTPS request to the geocoding service findAddressCandidates operation or by using client APIs. Specify the place name, output data fields, and optionally, additional parameters to refine the search.

The more complete you can make the input place name, the more likely the geocoding service will find an exact match. For example, "Grand Canyon", "Disneyland in California", or "Starbucks at Newport Beach".

To refine the search or search for POI, you can specify a category such as coffee shop, restaurant, or gas station. See more categories in Category filtering. To refine it further, specify parameters such as the search extent, country code, and city.

The geocoding service parses the place name and uses the all of the parameters to return a set of place candidates. Most candidates contain a place name, full address, location, attributes, and a score of how well it matched.

Types of place search

There are two types of searches you can perform: Local and Global. A local search uses a location to search for places nearby or a search extent to confine the search area. A global search is an open search that typically isn't confined to an extent.

URL request

Use dark colors for code blocksCopy
https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?<parameters>

Required parameters

Name	Description	Examples
`f`	The format of the data returned.	`f=json` `f=pjson`
`token`	An API key or OAuth 2.0 access token. Learn how to get an access token in Security and authentication.	`token=<YOUR_API_KEY>` `token=<ACCESS_TOKEN>`

Key parameters

Name	Description	Example
`address`	The address or place name string. Different formats are supported.	address=Disneyland address=Los Angeles Starbucks address=Seattle, Washington address=Mount Everest address=-117.155579,32.703761
`location`	Use to focus the search on a specific location.	location=-117.196,34.056
`category`	Filter places by place type values.	category=food,mexican food category=coffee shop category=gas station
`outFields`	A list of data fields to return.	outFields=PlaceName,Place_addr, outFields=* (return all fields)

Additional parameters: Refine the search by using parameters such as searchExtent, neighborhood, city, and countryCode. Use langCode to return results in a specific language.

Examples

Local search (by name)

This example uses the geocoding service to search for Starbucks near a location in San Francisco. You can use this type of search to find the location of businesses, points of interest, or landmarks. Most APIs provide a LocatorTask to access the service.

Steps

Reference the geocoding service.
Set the place name to search for.
Set the location to search from.
Set the list of data fields to return. e.g. PlaceName,Place_addr
Set the API key.

The response is a set of place candidates with a place name, full address, location, score, and attributes.

APIs

ArcGIS API for JavaScriptArcGIS API for JavaScriptEsri LeafletMapLibre GL JSOpenLayersArcGIS REST JSArcGIS Runtime API for .NETArcGIS Runtime API for AndroidArcGIS Runtime API for iOSArcGIS Runtime API for JavaArcGIS Runtime API for Qt (C++)ArcGIS Runtime API for Qt (QML)ArcGIS API for Python
Expand
Use dark colors for code blocksCopy
      function findPlaces(pt) {
        const geocodingServiceUrl = "http://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer";

        const params = {
          address: {
            address: "Starbucks"
          },
          location: pt,  // San Francisco (-122.4194, 37.7749)
          outFields: ["PlaceName","Place_addr"]
        }

        locator.addressToLocations(geocodingServiceUrl, params).then((results)=> {
          showResults(results);
        });
Expand
Go to tutorial

REST API

cURL

HTTP

Use dark colors for code blocks

Copy

1
2
3
4
5
6
curl https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates \
-d 'f=pjson' \
-d 'address=Starbucks' \
-d 'location=-122.4194,37.7749' \
-d 'outfields=PlaceName,Place_addr' \
-d 'token=YOUR_API_KEY'

View in Postman

Response (JSON)

Use dark colors for code blocksCopy
{
  "spatialReference": {
    "wkid": 4326,
    "latestWkid": 4326
  },
  "candidates": [
    {
      "address": "Starbucks",
      "location": {
        "x": -122.41732199999996,
        "y": 37.777066000000048
      },
      "score": 100,
Expand

Local search (by category)

This example searches for gas stations near a location by setting the Gas Station category near a location in Paris.

To see a full list of categories, visit Category filtering.

Steps

Reference the geocoding service.
Set location to search from.
Set the category of places to search for.
Set the list of data fields to return. e.g. PlaceName,Place_addr
Set the API key.

The response is a set of place candidates with a place name, full address, location, score, and attributes.

APIs

ArcGIS API for JavaScriptArcGIS API for JavaScriptEsri LeafletMapLibre GL JSOpenLayersArcGIS REST JSArcGIS Runtime API for .NETArcGIS Runtime API for AndroidArcGIS Runtime API for iOSArcGIS Runtime API for JavaArcGIS Runtime API for Qt (C++)ArcGIS Runtime API for Qt (QML)ArcGIS API for Python
Expand
Use dark colors for code blocksCopy
      function findPlaces(pt) {
        const geocodingServiceUrl = "http://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer";

        const params = {
          categories: ["gas station"],
          location: pt,  // Paris (2.34602,48.85880)
          outFields: ["PlaceName","Place_addr"]
        }

        locator.addressToLocations(geocodingServiceUrl, params).then((results)=> {
          showResults(results);
        });
Expand
Go to tutorial

REST API

cURL

HTTP

Use dark colors for code blocks

Copy

1
2
3
4
5
6
curl https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates \
-d 'f=pjson' \
-d 'category=gas station' \
-d 'location=2.34602,48.85880' \
-d 'outfields=PlaceName,Place_addr' \
-d 'token=<ACCESS_TOKEN>'

View in Postman

Response (JSON)

Use dark colors for code blocksCopy
{
  "spatialReference": {
   "wkid": 4326,
   "latestWkid": 4326
  },
  "candidates": [
    {
      "address": "Oil",
      "location": {
      "x": 2.341350000000034,
      "y": 48.861050000000034
      },
      "score": 100,
Expand

Global search

This example executes a global search for Grand Canyon. No location or extent parameters are provided.

Steps

Reference the geocoding service.
Set the place name or address to search.
Set the list of data fields to return.
Set the API key.

The response is a set of candidates with an address, location, score, and many other attributes.

APIs

ArcGIS API for JavaScriptArcGIS API for JavaScriptEsri LeafletMapLibre GL JSOpenLayersArcGIS REST JSArcGIS Runtime API for .NETArcGIS Runtime API for AndroidArcGIS Runtime API for iOSArcGIS Runtime API for JavaArcGIS Runtime API for Qt (C++)ArcGIS Runtime API for Qt (QML)ArcGIS API for Python
Expand
Use dark colors for code blocksCopy
      function findPlaces() {
        const geocodingServiceUrl = "http://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer";

        const params = {
          address: {
            address: "Grand Canyon"
          },
          outFields: "*"
        }

        locator.addressToLocations(geocodingServiceUrl,params).then((results)=> {
          showResults(results);
        });
Expand
Go to tutorial

REST API

cURL

HTTP

Use dark colors for code blocks

Copy

1
2
3
4
curl https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates \
-d 'f=pjson' \
-d 'address=grand canyon' \
-d 'token=<ACCESS_TOKEN>'

View in Postman

Response (JSON)

Use dark colors for code blocksCopy
{
  "spatialReference": {
    "wkid": 4326,
    "latestWkid": 4326
  },
  "candidates": [
    {
      "address": "Grand Canyon",
      "location": {
        "x": -113.76891999999998,
        "y": 35.973910000000046
      },
      "score": 100,
Expand

Tutorials

Search for an address

Convert an address or place to a location with the geocoding service.

Reverse geocode

Get an address, business, or place from coordinates with the geocoding service.

Find places

Find an address, business, or place with the geocoding service.

Display your location

Find and track your device location on a map.

Services

Geocoding service

Search for addresses, businesses, and places around the world.

API support

	Geocoding	Reverse Geocoding	Batch Geocoding	Place/POI Search	Autosuggest
ArcGIS API for JavaScript
ArcGIS API for Android			¹
ArcGIS API for iOS			¹
ArcGIS API for Java			¹
ArcGIS API for .NET			¹
ArcGIS API for Qt			¹
ArcGIS API for Python
Esri Leaflet			²
MapLibre GL JS	²	²	²	²	²
OpenLayers	²	²	²	²	²
ArcGIS REST JS

Full supportPartial supportNo support

1. No runtime API. Access via HTTP request.
2. Access via ArcGIS REST JS.

Tools

Developer dashboard

Manage API keys, service usage, and data with the ArcGIS Developers website.

ArcGIS Online

Create, manage, and share content and data with cloud-based GIS tools.

Map Viewer

Create, explore, and share web maps for 2D applications.

Scene Viewer

Create, explore, and share web scenes for 3D applications.

ArcGIS Pro

Explore, visualize, and analyze both 2D and 3D data with desktop GIS tools.

Mapping APIs and location services

Place search

Was this page helpful?

Was this page helpful?