Geocoding

Address text geocoded to a location with the geocoding service

What is geocoding?

Geocoding, also known as address search, is the process of converting text for an address or place to a complete address with a location. For example, you can convert "1600 Pennsylvania Ave NW, DC" to -77.03654 longitude and 38.89767 latitude.

You can use geocoding to:

  • Find the location of an address.
  • Convert address text to a complete address.
  • Provide a list of address candidates for an incomplete address.

How geocoding works

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

The more complete you can make the input address, the more likely the geocoding service will find an exact match. For example, "1600 Pennsylvania Ave NW, Washington, District of Columbia, 20500".

To refine the search, you can provide additional parameters such as the location, search extent, country code, city, and neighborhood.

The geocoding service parses the address and uses all of the parameters to return a set of address candidates. Each candidate contains a full address, location, attributes, and a score of how well it matched. By default the address, score, and location are returned, but to return all of the data fields available, you can set the outFields parameter to *.

URL request

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

Key parameters

NameDescriptionExamples
addressThe address or place name. Different formats are supported.address=1600 Pennsylvania Ave NW,DC address=Washington,DC address=81301 address=-117.155579,32.703761
outFieldsThe list of data fields to return.outFields=PlaceName,Addr_type, outFields=* (return all fields)

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

Examples

Geocode an address

This example illustrates how to geocode address text. Most APIs provide a LocatorTask to access the service.

Steps

  1. Reference the geocoding service.
  2. Set the address.
  3. Set the token to your API key.

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

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
<html>
<head>
<meta charset="utf-8">
<meta name="viewport" content="initial-scale=1, maximum-scale=1, user-scalable=no">
<title>ArcGIS Developer Guide: Forward geocoding</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/Graphic",
    "esri/tasks/Locator"
  ],(esriConfig, Map, MapView, Graphic, LocatorTask)=> {
    esriConfig.apiKey = "YOUR-API-KEY";
    const map = new Map({
      basemap: "arcgis-light-gray" //Basemap layer service
    const view = new MapView({
      container: "viewDiv",
      map: map,
      constraints: {
        snapToZoom: false
    view.when(()=>{
      const locatorTask = new LocatorTask({
        url: "https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer"
      });

      const params = {
        address: {
          "address": "1600 Pennsylvania Ave NW, DC"
        }
      }

      locatorTask.addressToLocations(params).then((results) => {
        showResult(results);
      });
      function showResult(results) {
        if (results.length) {
          const result = results[0];
          view.graphics.add(new Graphic({
              symbol: {
                type: "simple-marker",
                color: "#000000",
                size: "8px",
                outline: {
                  color: "#ffffff",
                  width: "1px"
              geometry: result.location,
              attributes: {
                title: "Address",
                address: result.address,
                score: result.score
              popupTemplate: {
                title: "{title}",
                content: "{address}" + "<br><br>" + result.location.longitude.toFixed(5) + "," + result.location.latitude.toFixed(5)
            features: view.graphics,
            location: result.location
            target: result.location,
            zoom: 13
</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=1600 Pennsylvania Ave NW, DC' \
-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": "1600 Pennsylvania Ave NW, Washington, District of Columbia, 20500",
      "location": {
        "x": -77.036548499999995,
        "y": 38.89767599999999
      },
      "score": 100,
      "attributes": {
        "Loc_name": "World",
        "Status": "M",
        "Score": 100,
        "Match_addr": "1600 Pennsylvania Ave NW, Washington, District of Columbia, 20500",
        "LongLabel": "1600 Pennsylvania Ave NW, Washington, DC, 20500, USA",
        "ShortLabel": "1600 Pennsylvania Ave NW",
        "Addr_type": "PointAddress",
        "Type": "",
        "PlaceName": "",
        "Place_addr": "1600 Pennsylvania Ave NW, Washington, District of Columbia, 20500",
        "Phone": "",
        "URL": "",
        "Rank": 20,
        "AddBldg": "",
        "AddNum": "1600",
        "AddNumFrom": "",
        "AddNumTo": "",
        "AddRange": "",
        "Side": "",
        "StPreDir": "",
        "StPreType": "",
        "StName": "Pennsylvania",
        "StType": "Ave",
        "StDir": "NW",
        "BldgType": "",
        "BldgName": "",
        "LevelType": "",
        "LevelName": "",
        "UnitType": "",
        "UnitName": "",
        "SubAddr": "",
        "StAddr": "1600 Pennsylvania Ave NW",
        "Block": "",
        "Sector": "",
        "Nbrhd": "",
        "District": "",
        "City": "Washington",
        "MetroArea": "",
        "Subregion": "District of Columbia",
        "Region": "District of Columbia",
        "RegionAbbr": "DC",
        "Territory": "",
        "Zone": "",
        "Postal": "20500",
        "PostalExt": "",
        "Country": "USA",
        "LangCode": "ENG",
        "Distance": 0,
        "X": -77.036548499999995,
        "Y": 38.89767599999999,
        "DisplayX": -77.036548499999995,
        "DisplayY": 38.89767599999999,
        "Xmin": -77.0375485,
        "Xmax": -77.03554849999999,
        "Ymin": 38.896675999999992,
        "Ymax": 38.898675999999988,
        "ExInfo": ""
      },
      "extent": {
        "xmin": -77.0375485,
        "ymin": 38.896675999999992,
        "xmax": -77.03554849999999,
        "ymax": 38.898675999999988
      }
    }
  ]
}

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.