Geocode an address with the ArcGIS REST API

What you will build

A script that turns an address into coordinates with the ArcGIS Geocoding service. Pick cURL, Python or JavaScript (Node.js 18+) in the code header: every step follows along in the language you chose.

You will need an API key with the Geocoding privilege from an ArcGIS Location Platform or ArcGIS Online account.

Each step with a request has a Run request button in the Result pane: it sends the request from your browser with the access token you enter below. Without a token, the pane shows a response captured earlier.

Set your access token

The service URL points at the World geocode service, and the access token authorizes every request. Paste your API key here; it fills the code, the downloads and the requests you run from this page, and stays in this browser.

Find address candidates

findAddressCandidates takes the whole address in singleLine. outFields picks the attributes each candidate returns and f=json asks for JSON.

Press Run request to send the same request from this page. It uses the access token you entered above; with the YOUR_ACCESS_TOKEN placeholder the service answers with error 498.

Print the candidates

Each candidate has an address, a location and a score from 0 to 100. ArcGIS REST services report most errors inside an HTTP 200 response ({ "error": { "code": 498, … } }), so check for error before reading candidates.

When a request fails

Change a character of the access token above and run the request again. The service still answers 200 OK, but the body holds error 498: the Result pane marks it as a failure and explains it, because this tutorial describes the ArcGIS error format in requests/errors.json.

cURLPythonJavaScriptcURLcURLPythonJavaScriptgeocode-post.shgeocode.shgeocode.pygeocode_post.pyrequirements.txtgeocode-post.mjsgeocode.mjs
#!/usr/bin/env bash
SERVICE_URL="https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer"
ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

curl --silent "$SERVICE_URL/findAddressCandidates" \
  --header "X-Esri-Authorization: Bearer $ACCESS_TOKEN" \
  --data-urlencode "singleLine=380 New York St, Redlands, CA" \
  --data "outFields=Match_addr,Addr_type" \
  --data "f=json"
#!/usr/bin/env bash
SERVICE_URL="https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer"
ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

curl --silent --get "$SERVICE_URL/findAddressCandidates" \
  --data-urlencode "singleLine=380 New York St, Redlands, CA" \
  --data "outFields=Match_addr,Addr_type" \
  --data "f=json" \
  --data "token=$ACCESS_TOKEN"
import requests

SERVICE_URL = "https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer"
ACCESS_TOKEN = "YOUR_ACCESS_TOKEN"

response = requests.get(
    f"{SERVICE_URL}/findAddressCandidates",
    params={
        "singleLine": "380 New York St, Redlands, CA",
        "outFields": "Match_addr,Addr_type",
        "f": "json",
        "token": ACCESS_TOKEN,
    },
)
data = response.json()

if "error" in data:
    raise SystemExit(f"{data['error']['code']}: {data['error']['message']}")

for candidate in data["candidates"]:
    print(candidate["address"], candidate["score"])
import requests

SERVICE_URL = "https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer"
ACCESS_TOKEN = "YOUR_ACCESS_TOKEN"

response = requests.post(
    f"{SERVICE_URL}/findAddressCandidates",
    headers={"X-Esri-Authorization": f"Bearer {ACCESS_TOKEN}"},
    data={
        "singleLine": "380 New York St, Redlands, CA",
        "outFields": "Match_addr,Addr_type",
        "f": "json",
    },
)
data = response.json()

if "error" in data:
    raise SystemExit(f"{data['error']['code']}: {data['error']['message']}")

for candidate in data["candidates"]:
    print(candidate["address"], candidate["score"])
requests>=2.32
const serviceUrl = "https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer";
const accessToken = "YOUR_ACCESS_TOKEN";

const response = await fetch(`${serviceUrl}/findAddressCandidates`, {
  method: "POST",
  headers: { "X-Esri-Authorization": `Bearer ${accessToken}` },
  body: new URLSearchParams({
    singleLine: "380 New York St, Redlands, CA",
    outFields: "Match_addr,Addr_type",
    f: "json",
  }),
});
const data = await response.json();

if (data.error) {
  throw new Error(`${data.error.code}: ${data.error.message}`);
}

for (const candidate of data.candidates) {
  console.log(candidate.address, candidate.score);
}
const serviceUrl = "https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer";
const accessToken = "YOUR_ACCESS_TOKEN";

const params = new URLSearchParams({
  singleLine: "380 New York St, Redlands, CA",
  outFields: "Match_addr,Addr_type",
  f: "json",
  token: accessToken,
});
const response = await fetch(`${serviceUrl}/findAddressCandidates?${params}`);
const data = await response.json();

if (data.error) {
  throw new Error(`${data.error.code}: ${data.error.message}`);
}

for (const candidate of data.candidates) {
  console.log(candidate.address, candidate.score);
}

No result yet. Steps with a captured output show it here, and steps with a request can run it.