# Geocode an address with the ArcGIS REST API

Interactive version: http://www.rauljimenez.info/interactive-code-scroll/showcase/rest-geocode/?variant=curl

Code variant: cURL. Other variants: [Python](http://www.rauljimenez.info/interactive-code-scroll/showcase/rest-geocode/tutorial.python.md), [JavaScript](http://www.rauljimenez.info/interactive-code-scroll/showcase/rest-geocode/tutorial.node.md).

## What you will build

A script that turns an address into coordinates with the [ArcGIS Geocoding service](https://developers.arcgis.com/rest/geocode/find-address-candidates/). 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](https://developers.arcgis.com/documentation/security-and-authentication/api-key-authentication/tutorials/create-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.

- **Access token** (`accessToken`)

```bash title="code/curl/geocode.sh" region="config"
SERVICE_URL="https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer"
ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
```

## 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 (ArcGIS REST's code for a missing, invalid or expired token. The last step shows how this page explains it.).

```bash title="code/curl/geocode.sh" region="request"
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"
```

## Keep the token out of URLs

A token in the query string ends up in browser history, proxy logs and server logs. This second script sends the same parameters as a form body with `POST`, and the token in the `X-Esri-Authorization: Bearer` header, which ArcGIS location services accept instead of the `token` parameter.

Run it: the response is the same, but the request line no longer carries the token.

```bash title="code/curl/geocode-post.sh" region="header-auth"
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"
```

## 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`.

```bash title="code/curl/geocode.sh" region="request"
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"
```

## Final code

### code/curl/geocode.sh

```bash title="code/curl/geocode.sh"
#!/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"
```

### code/curl/geocode-post.sh

```bash title="code/curl/geocode-post.sh"
#!/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"
```
