Find places | ArcGIS for Developers

ArcGIS Tutorials REST API Geocoding

Overview

You will learn: how to search for places with the ArcGIS World Geocoding Service.

The ArcGIS World Geocoding Service can find addresses, places, convert addresses to coordinates, and perform batch geocoding. If you would like to create an application that can search for places such as coffee shops, gas stations, or parks, you can use the ArcGIS REST API and the findAddressCandidates operation. All you need to do is pass in the location and the category (e.g., "Coffee Shop") to search for, and the service will return a set of candidates. Once you have candidates, you can add them to a map, create a route, or integrate them further into your application. To learn more about the capabilities of the geocoding service, please visit the documentation.

In this tutorial you will use the ArcGIS REST API to access the ArcGIS World Geocoding Service to search for places near a location.

Before you begin

Install Postman to execute HTTP requests. Go to this tutorial if you need an access token.

Steps

Create a request to access the geocoding service

Open Postman and click [+] in the tab bar to create a new request.
In the new tab, set the following:
- HTTP Method: GET
- Request URL: https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates

Add parameters to define the search category and response data

Click on Params next to the URL and add the following:

The f=json parameter tells the API to return JSON.

The category is the type of places to search for such as Restaurants, Coffee Shop, Gas Stations.

location is the x and y coordinate or the geometry used to conduct the search.

outFields represents the fields you would like to request from the geocoding database. You can find a list of fields in the service output. You can also use the special value of * to request all fields.

maxLocations is the maximum number of candidates to return.

To learn more about using findAddressCandidates and its associated parameters for searching for places, visit the REST API reference.
- f: json
- category: Coffee Shop
- location: -118.58864,34.06145 (Malibu Beach, CA)
- outFields: Place_addr, PlaceName
- maxLocations: 5

Execute the request to find coffee shops

Click Send to run the request.

In the response window, change the view to JSON and it should look something like this:

{
  "spatialReference": {
      "wkid": 4326,
      "latestWkid": 4326
  },
  "candidates": [
      {
          "address": "Cafe Mimosa",
          "location": {
              "x": -118.5998300150036,
              "y": 34.084189996104918
          },
          "score": 100,
          "attributes": {
              "PlaceName": "Cafe Mimosa",
              "Place_addr": "395 S Topanga Canyon Blvd, Topanga, California, 90290"
          },
          "extent": {
              "xmin": -118.60499999999996,
              "ymin": 34.079090000000058,
              "xmax": -118.59499999999997,
              "ymax": 34.089090000000063
          }
      },
      {
          "address": "Starbucks",
          "location": {
              "x": -118.55195993003072,
              "y": 34.045630043857145
          },
          "score": 100,
          "attributes": {
              "PlaceName": "Starbucks",
              "Place_addr": "514 Palisades Dr, Pacific Palisades, California, 90272"
          },
          "extent": {
              "xmin": -118.55666999999994,
              "ymin": 34.040680000000059,
              "xmax": -118.54666999999995,
              "ymax": 34.050680000000064
          }
      },
      {
          "address": "Starbucks",
          "location": {
              "x": -118.55466992555867,
              "y": 34.039489948352696
          },
          "score": 100,
          "attributes": {
              "PlaceName": "Starbucks",
              "Place_addr": "17380 W Sunset Blvd, Pacific Palisades, California, 90272"
          },
          "extent": {
              "xmin": -118.55904999999996,
              "ymin": 34.034240000000061,
              "xmax": -118.54904999999997,
              "ymax": 34.044240000000066
          }
      },
      {
          "address": "Starbucks",
          "location": {
              "x": -118.52608000057688,
              "y": 34.0475699594612
          },
          "score": 100,
          "attributes": {
              "PlaceName": "Starbucks",
              "Place_addr": "15300 W Sunset Blvd, Pacific Palisades, California, 90272"
          },
          "extent": {
              "xmin": -118.53130999999996,
              "ymin": 34.042390000000061,
              "xmax": -118.52130999999997,
              "ymax": 34.052390000000067
          }
      },
      {
          "address": "The Coffee Bean & Tea Leaf",
          "location": {
              "x": -118.52557999999999,
              "y": 34.046860000000038
          },
          "score": 100,
          "attributes": {
              "PlaceName": "The Coffee Bean & Tea Leaf",
              "Place_addr": "15278 Antioch St, Pacific Palisades, California, 90272"
          },
          "extent": {
              "xmin": -118.53057999999999,
              "ymin": 34.041860000000035,
              "xmax": -118.52058,
              "ymax": 34.05186000000004
          }
      }
  ]
}

Go to the top of the response and find the candidates property. This is an array of possible matches for the place and location passed in. Each match consists of:

Refer to the ArcGIS geometries concept documentation for more details about the location and extent responses. Remember that x will be the longitude and y will be the latitude. You can learn more about why ArcGIS uses x and y in the introduction to spatial reference systems.
- address: The address of this match.
- location: The x/y coordinates of this match. Note that x is longitude and y is latitude.
- score: The confidence level of the geocoder in this match, on a scale of 1-100.
- attributes: Any additional fields requested by the outFields parameter. In this case the PlaceName and Place_addr for the place found.
- extent: a rectangular bounding box around the location given as a pair of x/y coordinates.
```
  "candidates": [
    {
        "address": "Cafe Mimosa",
        "location": {
            "x": -118.5998300150036,
            "y": 34.084189996104918
        },
        "score": 100,
        "attributes": {
            "PlaceName": "Cafe Mimosa",
            "Place_addr": "395 S Topanga Canyon Blvd, Topanga, California, 90290"
        },
        "extent": {
            "xmin": -118.60499999999996,
            "ymin": 34.079090000000058,
            "xmax": -118.59499999999997,
            "ymax": 34.089090000000063
        }
    },
  ...
```

Update the parameters to search for different categories

In the Body, change the maxLocations to 25. Try changing the category parameter to ones below and run the request again:

If you plan on storing the results returned by this service, authentication is required.
- Parks and Outdoors
- Food
- Gas Station
- Hotel,Motel,Bed and Breakfast,Resort
- Arts and Entertainment
- Education
- Airport, Bridge, Bus Station, Bus Stop, Metro Station, Parking, Rest Area, Tourist Information, Train Station, Travel Agency, Truck Stop

In Postman click Code below the Send button. Select a programming language and use Postman to generate sample code for your application to run this request.

Congratulations, you're done!

You have successfully located coffee shops and other places near a given location.

Challenge

Confine your search to a bounding box

You can use the Esri World Geocoding Service to search more specific areas by proving an extent parameter to define a bounding box. Try adding searchExtent as a new parameter, supply the following JSON geometry object and run the request again.

{
  "xmin": -118.68702,
  "ymin": 34.03076,
  "xmax": -118.68105,
  "ymax": 34.03592,
  "spatialReference":{
    "latestWkid":3857,
    "wkid":102100
  }
}