An Application programming interface key (API key) is a permanent access token that defines the scope and permission for granting a public-facing application access to ready-to-use services. With ArcGIS REST JS, you use the Api class to set your API key before accessing services.
In this tutorial, you create and configure an API key that enables access to the geocoding and routing services for an application.
Prerequisites
You need an ArcGIS account to create an API key and access location services.
Steps
Create an API key
You can create and configure your API key in the developer dashboard so that it is scoped to access the geocoding and routing services.
-
Go to the API key page in your developer dashboard.
-
On the left, click +New API Key and set the:
- Title:
GeocodingRouting Key - Description
API key configured to access the geocoding and routing services.
- Title:
-
Click Create API key
Configure the API key
If you have an ArcGIS Developer account, by default your key will have access to the free tier of location services. If you have an organization account, by default your key will be scoped to access basemaps and non-stored geocodes.
-
In the Overview page of the API key, locate Location services at the bottom.
-
In the Location services pane, click Configure services. Check the following service cards:
- Basemaps
- Geocoding (not stored)
- Routing
Un-check any other service cards.
-
Click the Configure service(s) button.
-
In the Overview page, click the copy icon to copy your API key to set later.
Create a new pen
- If you are using the CDN libraries, to get started.
Add references
The request package contains request/response processing, authentication helpers, and error handling.
-
Add references to the
request,geocoding, androutingpackages.Use dark colors for code blocks <body> <pre id="result"></pre> <script src="https://unpkg.com/@esri/arcgis-rest-request@4.0.0/dist/bundled/request.umd.js"></script> <script src="https://unpkg.com/@esri/arcgis-rest-geocoding@4.0.0/dist/bundled/geocoding.umd.js"></script> <script src="https://unpkg.com/@esri/arcgis-rest-routing@4.0.0/dist/bundled/routing.umd.js"></script> <script> </script>
Set the API key
-
Create an
apivariable to set your key and anKey authenticationvariable that will call thefrommethod to create an instance ofKey Api.K e y Manager Use dark colors for code blocks <script src="https://unpkg.com/@esri/arcgis-rest-request@4.0.0/dist/bundled/request.umd.js"></script> <script src="https://unpkg.com/@esri/arcgis-rest-geocoding@4.0.0/dist/bundled/geocoding.umd.js"></script> <script src="https://unpkg.com/@esri/arcgis-rest-routing@4.0.0/dist/bundled/routing.umd.js"></script> <script> const apiKey = "YOUR_API_KEY"; const authentication = arcgisRest.ApiKeyManager.fromKey(apiKey);
Find places
Create a function to call the geocoding service to find McDonald's places around a location in Denver.
-
Add a
placevariable to define a search string and astartvariable to define the location to start searching from.Use dark colors for code blocks const apiKey = "YOUR_API_KEY"; const authentication = arcgisRest.ApiKeyManager.fromKey(apiKey); const place = "McDonalds"; const start = [-104.9903, 39.7392]; // Downtown Denver -
Create an async function called
app. In the function, set theplacesvariable to thegeocodeoperation and define the parameters foraddressandlocation. Set themaxto return only one result. SetLocation outto return theFields Place,Name Place_, andaddr Phoneof the restaurant. Lastly, set theauthenticationso the request uses your scoped API keys.Use dark colors for code blocks const apiKey = "YOUR_API_KEY"; const authentication = arcgisRest.ApiKeyManager.fromKey(apiKey); const place = "McDonalds"; const start = [-104.9903, 39.7392]; // Downtown Denver async function app() { const places = await arcgisRest .geocode({ params: { address: place, // Place name to search for location: start, maxLocations: 1 }, outFields: ["PlaceName", "Place_addr", "Phone"], authentication }); -
Display the results for the first result that is returned in the array of
candidatesinplaces. Call theJSON.stringifymethod to return all the properties of thecandidateand insert2white space characters. This will be appended to the text content in theresultsHTML element.Use dark colors for code blocks const places = await arcgisRest .geocode({ params: { address: place, // Place name to search for location: start, maxLocations: 1 }, outFields: ["PlaceName", "Place_addr", "Phone"], authentication }); const candidate = places.candidates[0]; document.getElementById("result").textContent = JSON.stringify(candidate, null, 2); -
Call the
appfunction.Use dark colors for code blocks const candidate = places.candidates[0]; document.getElementById("result").textContent = JSON.stringify(candidate, null, 2); } app(); -
In CodePen, run the application to view the
address,place,Name extent, and other attributes.
Find the route
To generate a route, you need a minimum of a start and an end location. Use the start location (downtown Denver) and the first place result from the geocode operation to get the route and driving directions to the closest McDonald's.
-
In the
appfunction, define anendvariable to the contain the coordinates of the first place (McDonald's) found from the call to the geocoding service.Use dark colors for code blocks const candidate = places.candidates[0]; document.getElementById("result").textContent = JSON.stringify(candidate, null, 2); const end = [candidate.location.x, candidate.location.y]; } app(); -
Call the
solveoperation and define theRoute stopswith thestartandendlocations. Set theauthenticationso the request uses your scoped API key.Use dark colors for code blocks const candidate = places.candidates[0]; document.getElementById("result").textContent = JSON.stringify(candidate, null, 2); const end = [candidate.location.x, candidate.location.y]; const directions = await arcgisRest .solveRoute({ stops: [ start, end ], authentication }); document.getElementById("result").textContent += JSON.stringify(directions, null, 2); } app(); -
Display the path between the two locations set in
directionsby using theJSON.stringifymethod and appending the results in theresultsHTML element.Use dark colors for code blocks const directions = await arcgisRest .solveRoute({ stops: [ start, end ], authentication }); document.getElementById("result").textContent += JSON.stringify(directions, null, 2); -
In CodePen, run the application. You will see the JSON results for the path between the location in downtown Denver and the first McDonald's place that was found.
Result
Below is the response from the service:
[
{
"address": "McDonald's",
"location": {
"x": -104.98814299999998,
"y": 39.741817000000026,
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
}
},
"score": 100,
"attributes": {
"PlaceName": "McDonald's",
"Place_addr": "200 16th St, Denver, Colorado, 80202",
"Phone": "(303) 534-6567"
},
"extent": {
"xmin": -104.98914299999998,
"ymin": 39.74081700000003,
"xmax": -104.98714299999997,
"ymax": 39.742817000000024,
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
}
}
},
{
"messages": [],
What's next?
Learn how to use additional ArcGIS location services in these tutorials: