Place search

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

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.

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

 
1
https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?<parameters>

Key parameters

NameDescriptionExample
addressThe 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
locationUse to focus the search on a specific location.location=-117.196,34.056
categoryFilter places by place type values.category=food,mexican food category=coffee shop category=gas station
outFieldsA 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

  1. Reference the geocoding service.

  2. Set the place name to search for.

  3. Set the location to search from.

  4. Set the list of data fields to return. e.g. PlaceName,Place_addr

  5. Set the API key.

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

APIs

ArcGIS JS APIEsri LeafletMapBox GL JSOpenLayersArcGIS REST JSArcGIS .NET APIArcGIS Android APIArcGIS iOS APIArcGIS Java APIArcGIS Qt API (C++)ArcGIS Qt API (QML)ArcGIS Python API
                                                                                                            
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
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
<html>
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="initial-scale=1, maximum-scale=1, user-scalable=no">
  <title>ArcGIS Developer Guide: Local search(name)</title>
     <!-- ArcGIS Mapping APIs and Location Services Developer Guide
    Learn more: https://developers.arcgis.com/documentation/mapping-apis-and-services/search/
    -->
  <style>
    html, body, #viewDiv {
      padding: 0;
      margin: 0;
      height: 100%;
      width: 100%;
  </style>

  <link rel="stylesheet" href="https://js.arcgis.com/4.19/esri/themes/light/main.css">
  <script src="https://js.arcgis.com/4.19/"></script>

  <script>
    require([
      "esri/config",
      "esri/Map",
      "esri/views/MapView",
      "esri/tasks/Locator",
      "esri/Graphic"
    ],(esriConfig, Map, MapView, Locator, Graphic)=> {
      esriConfig.apiKey = "YOUR-API-KEY";
      const map = new Map({
        basemap: "osm-standard" //Basemap layer service
      const view = new MapView({
        container: "viewDiv",
        map: map,
        center: [-122.4194, 37.7749], // San Francisco
        zoom: 13
      view.when(()=>{
      // Find places and add them to the map
      function findPlaces(pt) {
        const locator = new Locator({
         url: "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(params).then((results)=> {
          showResults(results);
        });
      function showResults(results) {
          results.forEach((result)=>{
              new Graphic({
                attributes: result.attributes,
                geometry: result.location,
                symbol: {
                 type: "simple-marker",
                 color: "black",
                 size: "10px",
                 outline: {
                   color: "#ffffff",
                   width: "2px"
                popupTemplate: {
                  title: "{PlaceName}",
                  content: "{Place_addr}" + "<br><br>" + result.location.x.toFixed(5) + "," + result.location.y.toFixed(5)
          if (results.length) {
            const g = view.graphics.getItemAt(0);
              features: [g],
              location: g.geometry
  </script>
</head>
<body>
  <div id="viewDiv"></div>
</body>
</html>

REST API

RequestResponse
      
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'

Response (JSON)

                          
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
{
  "spatialReference": {
    "wkid": 4326,
    "latestWkid": 4326
  },
  "candidates": [
    {
      "address": "Starbucks",
      "location": {
        "x": -122.41732199999996,
        "y": 37.777066000000048
      },
      "score": 100,
      "attributes": {
        "PlaceName": "Starbucks",
        "Place_addr": "1390 Market Street 107 Fox Plz, San Francisco, California, 94102"
      },
      "extent": {
        "xmin": -122.41832199999996,
        "ymin": 37.77606600000005,
        "xmax": -122.41632199999995,
        "ymax": 37.778066000000045
      }
    }
  ]
 }

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

  1. Reference the geocoding service.

  2. Set location to search from.

  3. Set the category of places to search for.

  4. Set the list of data fields to return. e.g. PlaceName,Place_addr

  5. Set the API key.

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

APIs

ArcGIS JS APIEsri LeafletMapBox GL JSOpenLayersArcGIS REST JSArcGIS .NET APIArcGIS Android APIArcGIS iOS APIArcGIS Java APIArcGIS Qt API (C++)ArcGIS Qt API (QML)ArcGIS Python API
                                                                                                          
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
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
<html>
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="initial-scale=1, maximum-scale=1, user-scalable=no">
  <title>ArcGIS Developer Guide: Local search (category)</title>
     <!-- ArcGIS Mapping APIs and Location Services Developer Guide
    Learn more: https://developers.arcgis.com/documentation/mapping-apis-and-services/search/
    -->
  <style>
    html, body, #viewDiv {
      padding: 0;
      margin: 0;
      height: 100%;
      width: 100%;
  </style>

  <link rel="stylesheet" href="https://js.arcgis.com/4.19/esri/themes/light/main.css">
  <script src="https://js.arcgis.com/4.19/"></script>

  <script>
    require([
      "esri/config",
      "esri/Map",
      "esri/views/MapView",
      "esri/tasks/Locator",
      "esri/Graphic"
    ],(esriConfig, Map, MapView, Locator, Graphic)=> {
      esriConfig.apiKey = "YOUR-API-KEY";
      const map = new Map({
        basemap: "arcgis-streets-night" //Basemap layer service
      const view = new MapView({
        container: "viewDiv",
        map: map,
        center: [2.34602,48.85880], // Paris
        zoom: 13
      view.when(()=>{
      // Find places and add them to the map
      function findPlaces(pt) {
        const locator = new Locator({
         url: "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(params).then((results)=> {
          showResults(results);
        });
      function showResults(results) {
          results.forEach((result)=>{
              new Graphic({
                attributes: result.attributes,
                geometry: result.location,
                symbol: {
                 type: "simple-marker",
                 color: "black",
                 size: "10px",
                 outline: {
                   color: "#ffffff",
                   width: "2px"
                popupTemplate: {
                  title: "{PlaceName}",
                  content: "{Place_addr}" + "<br><br>" + result.location.x.toFixed(5) + "," + result.location.y.toFixed(5)
          if (results.length) {
            const g = view.graphics.getItemAt(0);
              features: [g],
              location: g.geometry
  </script>
</head>
<body>
  <div id="viewDiv"></div>
</body>
</html>

REST API

RequestResponse
      
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>'

Response (JSON)

                          
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
{
  "spatialReference": {
   "wkid": 4326,
   "latestWkid": 4326
  },
  "candidates": [
    {
      "address": "Oil",
      "location": {
      "x": 2.341350000000034,
      "y": 48.861050000000034
      },
      "score": 100,
      "attributes": {
      "PlaceName": "Oil",
      "Place_addr": "Rue Bailleul, 75001, 1er Arrondissement, Paris, Île-de-France"
      },
      "extent": {
      "xmin": 2.3363500000000341,
      "ymin": 48.856050000000032,
      "xmax": 2.3463500000000339,
      "ymax": 48.866050000000037
      }
    }
  ]
}

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

Steps

  1. Reference the geocoding service.

  2. Set the place name or address to search.

  3. Set the list of data fields to return.

  4. Set the API key.

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

APIs

ArcGIS JS APIEsri LeafletMapBox GL JSOpenLayersArcGIS REST JSArcGIS .NET APIArcGIS Android APIArcGIS iOS APIArcGIS Java APIArcGIS Qt API (C++)ArcGIS Qt API (QML)ArcGIS Python API
                                                                                                              
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
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
<html>
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="initial-scale=1, maximum-scale=1, user-scalable=no">
  <title>ArcGIS Developer Guide: Global search</title>
     <!-- ArcGIS Mapping APIs and Location Services Developer Guide
    Learn more: https://developers.arcgis.com/documentation/mapping-apis-and-services/search/
    -->
  <style>
    html, body, #viewDiv {
      padding: 0;
      margin: 0;
      height: 100%;
      width: 100%;
  </style>

  <link rel="stylesheet" href="https://js.arcgis.com/4.19/esri/themes/light/main.css">
  <script src="https://js.arcgis.com/4.19/"></script>

  <script>
    require([
      "esri/config",
      "esri/Map",
      "esri/views/MapView",
      "esri/tasks/Locator",
      "esri/Graphic"
    ],(esriConfig, Map, MapView, Locator, Graphic)=> {
      esriConfig.apiKey = "YOUR-API-KEY";
      const map = new Map({
        basemap: "arcgis-topographic" //Basemap layer service
      const view = new MapView({
        container: "viewDiv",
        map: map,
        center: [-25,30],
        zoom: 2
      view.when(()=>{
      // Find places and add them to the map
      function findPlaces() {
        const locator = new Locator({
         url: "http://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer"
        });

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

        locator.addressToLocations(params).then((results)=> {
          showResults(results);
        });
      function showResults(results) {
          results.forEach((result)=>{
              new Graphic({
                attributes: result.attributes,
                geometry: result.location,
                symbol: {
                 type: "simple-marker",
                 color: "black",
                 size: "10px",
                 outline: {
                   color: "#ffffff",
                   width: "2px"
                popupTemplate: {
                  title: "{PlaceName}",
                  content: "{LongLabel}" + "<br><br>" + result.location.x.toFixed(5) + "," + result.location.y.toFixed(5)
          if (results.length) {
            const g = view.graphics.getItemAt(0);
              target: g.geometry,
              zoom: 13
              features: [g],
              location: g.geometry
  </script>
</head>
<body>
  <div id="viewDiv"></div>
</body>
</html>

REST API

RequestResponse
    
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>'

Response (JSON)

                                                                                 
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
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
{
  "spatialReference": {
    "wkid": 4326,
    "latestWkid": 4326
  },
  "candidates": [
    {
      "address": "Grand Canyon",
      "location": {
        "x": -113.76891999999998,
        "y": 35.973910000000046
      },
      "score": 100,
      "attributes": {
        "Loc_name": "World",
        "Status": "M",
        "Score": 100,
        "Match_addr": "Grand Canyon",
        "LongLabel": "Grand Canyon, AZ, USA",
        "ShortLabel": "Grand Canyon",
        "Addr_type": "POI",
        "Type": "Canyon",
        "PlaceName": "Grand Canyon",
        "Place_addr": "Arizona",
        "Phone": "",
        "URL": "",
        "Rank": 2.5,
        "AddBldg": "",
        "AddNum": "",
        "AddNumFrom": "",
        "AddNumTo": "",
        "AddRange": "",
        "Side": "",
        "StPreDir": "",
        "StPreType": "",
        "StName": "",
        "StType": "",
        "StDir": "",
        "BldgType": "",
        "BldgName": "",
        "LevelType": "",
        "LevelName": "",
        "UnitType": "",
        "UnitName": "",
        "SubAddr": "",
        "StAddr": "",
        "Block": "",
        "Sector": "",
        "Nbrhd": "",
        "District": "",
        "City": "",
        "MetroArea": "",
        "Subregion": "Mohave County",
        "Region": "Arizona",
        "RegionAbbr": "AZ",
        "Territory": "",
        "Zone": "",
        "Postal": "",
        "PostalExt": "",
        "Country": "USA",
        "LangCode": "ENG",
        "Distance": 0,
        "X": -113.76891999999998,
        "Y": 35.973910000000046,
        "DisplayX": -113.76891999999998,
        "DisplayY": 35.973910000000046,
        "Xmin": -115.76891999999998,
        "Xmax": -111.76891999999998,
        "Ymin": 33.973910000000046,
        "Ymax": 37.973910000000046,
        "ExInfo": ""
      },
      "extent": {
        "xmin": -115.76891999999998,
        "ymin": 33.973910000000046,
        "xmax": -111.76891999999998,
        "ymax": 37.973910000000046
      }
    }
  ]
}

Tutorials

Services

Geocoding service

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

API support

GeocodingReverse GeocodingBatch GeocodingPlace/POI SearchAutosuggestUI Component
ArcGIS API for JavaScriptFully supportedFully supportedFully supportedFully supportedFully supportedFully supported
ArcGIS API for AndroidFully supportedFully supportedFully supportedFully supportedFully supportedNot supported
ArcGIS API for iOSFully supportedFully supportedFully supportedFully supportedFully supportedNot supported
ArcGIS API for JavaFully supportedFully supportedFully supportedFully supportedFully supportedNot supported
ArcGIS API for .NETFully supportedFully supportedFully supportedFully supportedFully supportedNot supported
ArcGIS API for QtFully supportedFully supportedFully supportedFully supportedFully supportedNot supported
ArcGIS API for PythonFully supportedFully supportedFully supportedFully supportedFully supportedNot supported
Esri LeafletFully supportedFully supportedAccess via ArcGIS REST JSFully supportedFully supportedFully supported
MapBox GL JSAccess via ArcGIS REST JSAccess via ArcGIS REST JSAccess via ArcGIS REST JSAccess via ArcGIS REST JSAccess via ArcGIS REST JSNot supported
OpenLayersAccess via ArcGIS REST JSAccess via ArcGIS REST JSAccess via ArcGIS REST JSAccess via ArcGIS REST JSAccess via ArcGIS REST JSNot supported
ArcGIS REST JSFully supportedFully supportedFully supportedFully supportedFully supportedNot supported
Full supportPartial support (see notes)Not supported

Tools

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