Authenticate a request to the World Geocoding Service

Some ArcGIS Online services run on a credit-based model. You purchase or otherwise acquire credits for your ArcGIS Online organization, and when someone from the organization uses qualifying services, credits are consumed. The number of credits spent depends on the service. See Service Credits Overview for details on which services require credits and, of those that do, how many credits are consumed.

Credits have value, including monetary value, so it's important that your applications protect them and the usernames, passwords, tokens, and so on that are required to get and use credits. To help you handle this task, ArcGIS Online employs OAuth 2.0, an open authentication protocol. You can learn how OAuth 2.0 works within the context of Esri services by reading the Authentication help topics.

When making a REST request to a secured ArcGIS Online service, you need to provide a token with the request. A valid token is a key that is temporarily related to an ArcGIS Online account. The service tries to find an account associated with the token. If it finds one—and the account has the necessary privileges, credits, and so on to perform the operation—it will run the process and return the results to you.

Generate a token

This section steps you through the process of setting up an application login and manually generating tokens through REST requests. Although it is likely you will ultimately use another method to authenticate services in your applications, after learning the steps presented here, you'll be able to construct your own REST requests with valid tokens and test the credit-based ArcGIS Online services.

  1. Go to developers.arcgis.com.
  2. Click Sign In and provide your ArcGIS Online credentials.
  3. Applications inherit privileges from the user account that creates them. To generate a token that can be used with a paid geocoding operation, ensure that your user account has been granted the Geocoding privilege.
  4. Click New Application.
  5. Fill out the form that appears.
  6. Click Create Application.
  7. Click API Access to get the client ID and secret.

    OAuth Credentials
    Now you'll feed this information to a service to generate the token.

  8. Copy the following URL into a browser and replace <YOUR CLIENT ID> and <YOUR CLIENT SECRET> with the information you generated on developers.arcgis.com:

    https://www.arcgis.com/sharing/oauth2/token?client_id=<YOUR CLIENT ID>&grant_type=client_credentials&client_secret=<YOUR CLIENT SECRET>&f=pjson

  9. Press Enter to submit the request.

    The response includes a token (similar to the one highlighted below) and the amount of time, in seconds, you have until the token expires.

    Response including a token
    The token shown here has expired and can't be reused.

  10. A token can be used for all requests to the service until the token expires. By default, a token expires in 2 hours. Add an expiration parameter when requesting a token to receive one that is valid for a shorter or longer period of time. The expiration parameter you pass is in minutes (but the response reports the token's validity in seconds). The maximum lifetime of a token is 14 days; if you specify a longer expiration period, the token returned will still expire in 14 days.

Geocode an address using your token

Now that you have a token, you can make a request to a secured Esri service.

In the next set of steps, you'll use the findAddressCandidates operation to get the coordinates of an address.

Note:

The findAddressCandidates operation works with or without providing a token, but according to the user agreement, anytime you store the results from findAddressCandidates and similar operations, you need to pass in a token to deduct credits for the operation. This example assumes you are saving the results. Learn more by reading Free vs. paid.

Caution:

Any credits consumed by the requests you make here will be deducted from your ArcGIS Online account. You can see how many credits are used by the different services before making a request. The following request locates a single address, which has a nominal cost.

  1. Get the request URL. The following URL was copied from the findAddressCandidates API reference:

    http://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?<PARAMETERS>

  2. When geocoding an address as a line of text and storing results, the find operation requires setting the text parameter to the address you're searching for (380 New York St, Redlands, California, 92373), the forStorage parameter to true, the token parameter to a valid token, and the response format (f). Add those parameters to the request URL.

    http://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?singleLine=380 New York St, Redlands, California, 92373&forStorage=true&token=<YOUR TOKEN>&f=pjson

  3. Optionally, add other valid parameters to the URL. For a complete list of required and optional parameters, see the help for find.
    Note:

    The documentation lists and describes the parameters, but you may want to see the parameters as a JSON response from the service. To do that, submit the following request:

    http://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer?token=<YOUR TOKEN>&f=pjson

  4. Copy the completed URL, paste it in your browser, and press Enter.

    The results are returned as a JSON object.

    JSON object describing the output address

You created an application item in developers.arcgis.com, which provided a client ID and secret. You called the OAuth 2.0 token generation service and passed the ID and secret as parameters to generate a token, which was associated with your account. Finally, you passed the token as a parameter in a service request to find an address.

Following this workflow should help you start exploring the capabilities of the ArcGIS Online services and developing applications. Make sure to review the OAuth 2.0 topics, and choose the best authentication method for your application.