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 lab 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 lab if you need an access token.

Steps

Create a request to access the geocoding service

  1. Open Postman and click [+] in the tab bar to create a new request.

  2. 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

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

    • 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

  1. Click Send to run the request.

  2. 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
              }
          }
      ]
    }
    
  3. 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:

    • 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

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

    • 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

  1. 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
  }
}