ArcGIS Location Platform

You can access location services, data services, and spatial analysis services with ArcGIS Location Platform. These services include: geocoding, routing, and spatial analysis. The ArcGIS Maps SDK for JavaScript provides a set of APIs that allow you to access these services and create interactive maps and apps. In this guide, you will learn how to use the ArcGIS Maps SDK for JavaScript with ArcGIS Location Platform.

Hosting data services

Data hosting, also referred to as data publishing, is the process of securely storing, managing, and accessing your geographic data in ArcGIS as a data service. ArcGIS Location Platform allows you to host and manage your data using data management tools to create services such as feature services, vector tile services, and map tile services. Each of these services can be consumed in a JavaScript Maps SDK application using their corresponding layer type classes. See the documentation on layers for more information on how to use these services in your application.

When a service is created, it is stored in a portal item that can be accessed by the portal item ID. This portal item can be managed and shared within the portal. See how to work with data services for the steps to create manage, and access data services.

These portal items allow you to easily create layers that you can add to maps in your application. For example, to access a feature layer that references a feature service, you can use the portal item ID to create a new FeatureLayer object.

1
2
3
4
5
const layer = new FeatureLayer({
    portalItem: {
        id: "YOUR_PORTAL_ITEM_ID"
    }
});

When referencing the feature layer as a portal item, all properties such as the renderer, popup, etc. are set on the portal item and will be persisted into your application. This means that if you update the layer properties in the portal, the changes will be reflected in your application making it a seamless experience. Adding your data service by referencing the portal item is best practice when working with data services in the JavaScript Maps SDK.

Authentication

In order to use ArcGIS services, you must provide authentication with an access token. Access tokens define the privileges and permissions available to your application.

There are three types of authentication that can be used to obtain an access token:

• API key authentication: This creates a long-lived token that grants your application access to location services and private content.
• User authentication (formerly ArcGIS identity): This generates a short-lived token via OAuth 2.0, authorizing your application to access location services, content, and resources on behalf of a logged in ArcGIS user.
• App authentication: This generates a short-lived token via OAuth 2.0, authorizing your application to access location services on your behalf.

The most common way to authenticate is with an API key when using ArcGIS Location Platform.

API keys

There are two ways to configure an API key for your app to access location services:

• Global API key: This sets a global API key that will be used to access all ArcGIS location services and hosted data that your app uses.
• Fine-grained API key: This sets an API key for a specific service or component/widget.

For a better understanding on which type of API key would be best for your application and which classes and components/widgets support API keys, see the authentication and secure resources guide.

Global API key

A global API key will have all the privileges needed to access hosted data and every location service your application uses. For example, if you are using basemap styles, geocoding, routing, and spatial analysis services, the global API key will have all the privileges enabled on creation to access these services. If you are working with a global API key, you can set it in your code as follows:

1
2
3
4
5
6
<!-- The esriConfig variable must be defined before adding the other esri libraries -->
<script>
var esriConfig = {
    apiKey: "YOUR_ACCESS_TOKEN"
};
</script>

You can override this key by setting a key explicitly on layers, components/widgets, and other classes that use platform services by using fine-grained API keys. See the display a map tutorial for an example of how to set a global API key within your JavaScript Maps SDK application.

Fine-grained API key

A fine-grained API key has specific privileges enabled during the creation process to access specific services. For example, if you are using an API to access private data, you will have to configure your API key to access that data during the creation process. If using a fine-grained API key, you can set it on the class that uses the service.

For example, to set an API key on a private layer that was configured with your API key:

1
2
3
4
5
6
const layer = new FeatureLayer({
    portalItem: {
        id: "YOUR_PORTAL_ITEM_ID"
    },
    apiKey: "YOUR_ACCESS_TOKEN"
});

It is best practice to use a fine-grained API key since this limits the number of privileges on each key and prevents misuse. See the API key authentication best practices for more details.

ArcGIS Location Services

The following location services are available with ArcGIS Location Platform. The subtopics explain how these services can be utilized with the ArcGIS Maps SDK for JavaScript to create location-aware applications.

Basemaps

The basemap styles service is a location service that provides basemap styles and data for the extent of the world. The service also supports displaying localized language place labels, places, and worldviews. Review the basemap styles service and the variety of basemaps available for use in your applications. These basemaps can be created from a string in the form of {provider}/{style}, where provider is "arcgis" or "osm". See ArcGIS basemap styles and OSM basemap styles for the full list of available styles.

To set a basemap in your app, you can use the basemap attribute on the map component. Note that a global API key should be set when using the basemap location service.

1
<arcgis-map basemap="arcgis/topographic"></arcgis-map>

You can also add a basemap to the map by creating a new Basemap object using the BasemapStyle class, which supports basemaps from the basemap styles service.

1
2
3
4
5
6
7
8
9
const spanishBasemap = new Basemap({
    style: new BasemapStyle({
        id: "arcgis/human-geography",
        language: "es" // place labels will be displayed in Spanish
    })
});
arcgisMap.map = new Map({
    basemap: spanishBasemap
});

See the Basemap class for more details.

Geocoding

The geocoding service is a location service that can search for addresses, place addresses, and businesses. The Search component and Search widget are the primary way to access the geocoding service. Set the global API key to use the default geocoding service when using Search.

When using custom Search component/widget parameters or creating a locator, set the fine-grained API key and service URL.

1
2
3
<arcgis-map item-id="45b3b2fb35e94ab09381d0caa0da5946">
    <arcgis-search position="top-right"></arcgis-search>
</arcgis-map>

1
2
3
4
5
6
7
8
9
// Get the search component.
const searchComponent = document.querySelector("arcgis-search");
// Set the component search sources with the locator service and API key.
searchComponent.sources = [{
    name: "Location services geocoding service",
    placeholder: "Search for a place...",
    apiKey: "YOUR_ACCESS_TOKEN",
    url: "https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer"
}];

Routing and directions

The routing service is a location service that can find routes, directions, and perform advanced analyses on street networks. The Directions component and Directions widget are the primary way to access the routing service. Directions uses the same logic as Search when setting an API key. To use the routing service, you can either set the global API key or set the API key on the component/widget:

1
2
3
<arcgis-map item-id="45b3b2fb35e94ab09381d0caa0da5946">
    <arcgis-directions position="top-right"></arcgis-directions>
</arcgis-map>

1
2
3
// Get the directions component and set the API key.
const directionsComponent =  document.querySelector("arcgis-directions");
directionsComponent.apiKey = "YOUR_ACCESS_TOKEN";

Places

The places service is a location service that can search for places, such as restaurants, hotels, and parks. The places API is the primary way to access the place finding service. See the find nearby places and details tutorial for an example of how to use the place finding location service with the JavaScript Maps SDK.

GeoEnrichment

The GeoEnrichment service is a location service that finds demographic data and local facts for locations around the world. To work with the GeoEnrichment service, you can utilize ArcGIS REST JS alongside the JavaScript Maps SDK. See the get demographic data tutorial for an example of how to integrate the ArcGIS REST JS with the JavaScript Maps SDK to use the GeoEnrichment service.

Tutorials

There are a number of tutorials available to help you get started with ArcGIS Location Platform in your ArcGIS Maps SDK for JavaScript applications.