Key concepts

This document provides an overview of how to work with ArcGIS REST JS to build mapping applications. ArcGIS REST JS is library that contains a collection of packages that are framework agnostic. Implementing ArcGIS Rest JS packages allows you to:

Simplify making requests to ArcGIS Online, ArcGIS Enterprise, and ArcGIS Platform location service REST APIs.
Use CDN, NodeJS, or tree-shakeable ES modules.
Work with popular module bundlers like: webpack, Rollup, and Parcel.

Packages

To make requests to services, you reference packages in the library in your application. These packages provide helpers that allow you to make low-level requests, authenticate users, query, geocode, route, and access demographic data.

@esri/arcgis-rest-request : Undperins all other packages, supports low-level requests.
@esri/arcgis-rest-auth : Provides methods to authenticate named users and applications.
@esri/arcgis-rest-feature-layer: Provides functions to query and edit features in hosted feature layers.
@esri/arcgis-rest-geocoding: A geocoding wrapper for @esri/arcgis-rest-js.
@esri/arcgis-rest-routing: A routing and directions wrapper for @esri/arcgis-rest-js.
@esri/arcgis-rest-demographics: To access the GeoEnrichment service.

Referencing libraries

Here is an example of how to reference libraries using different frameworks.

CDN

ES Modules

Node JS

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width">
  <title>ArcGIS REST JS</title>
  <style>
    body {
      font-family: monospace;
      color: white;
    }
    pre {
      overflow: auto;
      padding: 1rem;
    }
    body,pre{
      background: #000000;
    }
  </style>
</head>
<body>
  <pre id="result"></pre>

  <!-- require ArcGIS REST JS libraries from https://unpkg.com -->
  <script src="https://unpkg.com/@esri/arcgis-rest-request@3.0.0/dist/umd/request.umd.js"></script>
  <script src="https://unpkg.com/@esri/arcgis-rest-auth@3.0.0/dist/umd/auth.umd.js"></script>
  <script src="https://unpkg.com/@esri/arcgis-rest-geocoding@3.0.0/dist/umd/geocoding.umd.js"></script>

  <script>
    /* when including ArcGIS REST JS all exports are available
    from the same arcgisRest global */

    const apiKey = "YOUR_API_KEY";

    const authentication = new arcgisRest.ApiKey({
      key: apiKey
    });

    arcgisRest.geocode({
      params: {
        category: 'Coffee shop',
        location: '144.9850916862488,-37.798297645411',
        distance: 2000,
        maxLocations: 20
      },
      outFields: '*',
      authentication
    }).then((response) => {
      console.log("Candidates:", response.candidates);
      document.getElementById("result").textContent = JSON.stringify(response.candidates, null, 2);
    });

  </script>

</body>
</html>

Authentication

ArcGIS REST JS handles both API key and OAuth 2.0 methods of authentication. Visit Security and authentication to learn more about API keys and OAuth 2.0 in the Mapping APIs and location services guide.

API key

If your application needs to access location services, use an API Key from your developer dashboard. When using an API key, make sure that it is properly scoped to the services you are accessing.

Reference the library.
Get an API key from your dashboard.
Set the API key.

import { request } from "@esri/arcgis-rest-request";
import { ApiKey } from "@esri/arcgis-rest-auth";

const apiKey = "YOUR_API_KEY";

const authentication = new arcgisRest.ApiKey({
  key: apiKey
});

To learn more, go to the tutorials.

OAuth 2.0

When your app requires access to Esri secure user content or if you are distributing your app through ArcGIS Marketplace, you should implement OAuth 2.0 to obtain an ArcGIS identity.

The ArcGIS REST JS authentication package includes modules such as UserSession to authenticate users with their ArcGIS Online or ArcGIS Enterprise accounts. Other OAuth 2.0 calls you can use include generating and exchanging tokens.

Reference the library.
Go to your dashboard.
Create or use an existing application.
Get the client ID from your application.
Set the client ID.

import {request} from "@esri/arcgis-rest-request";
import { UserSession } from '@esri/arcgis-rest-auth';
// register your own app to create a unique clientId
const clientId = "abc123"

UserSession.beginOAuth2({
  clientId,
  redirectUri: 'https://yourapp.com/authenticate.html'
})
  .then(session)

Working with location services

ArcGIS location services includes a number of services for geocoding, routing, demographic analysis, and spatial analysis. In ArcGIS REST JS, there are libraries for accessing each of the different services and functionality. To learn more, visit the tutorials.

The typical steps for accessing a service is to:

Reference the appropriate libraries.
Set the API key to authenticate the request.
Define parameters to pass to the service.
Call the service and handle the results.

Geocoding service

import { ApiKey } from "@esri/arcgis-rest-auth";
import { geocode } from "@esri/arcgis-rest-geocoding";

const authentication = new ApiKey({
  key: apiKey
});

geocode({
  address: "1600 Pennsylvania Ave",
  postal: 20500,
  countryCode: "USA",
  authentication
})

To learn more, go to the Search for an address tutorial.

Routing service

import { ApiKey } from "@esri/arcgis-rest-auth";
import { solveRoute } from "@esri/arcgis-rest-routing";

const authentication = new ApiKey({
  key: apiKey
});

solveRoute({
  stops: [
    [-117.195677, 34.056383],
    [-117.918976, 33.812092]
  ],
  authentication
})

To learn more, go to the Find a route and directions tutorial.

Working with hosted feature layers

You can use ArcGIS REST JS to access your own data through services hosted in the ArcGIS Platform. To create hosted layers and services, you can import and publish data using data management tools. Once created, you can access the layers and services using ArcGIS REST JS.

Import your data from a CSV, XLS, GeoJSON, or Shapefile file to create a hosted feature layer. See Import data as a feature layer.
Get the URL for the feature layer. See Access feature layer data.
Make a request to the service to access metadata.

Access hosted feature layer data

After your data is hosted, you can access the metadata with a URL.

arcgisRest.request("https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/Trailheads_Styled/FeatureServer/0", {
  authentication
})

To learn more, go to the Get layer metadata tutorial.

Query and edit hosted feature layer data

With the service URL from a published hosted feature layer, you can make different requests to the service using feature layer helpers to query and edit features.

Query

Use a SQL where clause or spatial queries to access subsets of data in a hosted feature layer.

arcgisRest.queryFeatures({
  url: "https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/LA_County_Parcels/FeatureServer/0",
  where: "UseType = 'Residential'",
  resultRecordCount: 1,
  authentication
})

To learn more, go to the Query a feature layer (SQL) tutorial.

Edit

Add, update, and delete features in a hosted feature layer.

arcgisRest.addFeatures({
      url: featureServiceLayerUrl,
      features: [featureToAdd],
      authentication
    })

To learn more, go to the Edit feature data tutorial.

Resources

Here are some useful resources to help create applications with ArcGIS REST JS and ArcGIS location services:

PreviousIntroduction NextTutorials

DocumentationArcGIS REST JS Guide

Key concepts

Was this page helpful?

Was this page helpful?