ArcGIS Location Platform

The ArcGIS Maps SDK for JavaScript provides powerful components and APIs that allow you to utilize location services, data services, and spatial analysis services with ArcGIS Location Platform to create interactive maps and apps.

In this guide, you will learn how to use the ArcGIS Maps SDK for JavaScript with ArcGIS Location Platform.

Bringing data into your application

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 either a web map or the service's corresponding layer type classes. See the documentation on layers for more information on how to use these services in your application.

Using web maps

Web maps are items in a portal that contain properties and settings for a map that can be created and managed in your portal. The JavaScript Maps SDK provides a simple way to access and display these web maps in your application. All the properties and settings configured on the web map will be persisted into your application. This means that if you update the web map in the portal, the changes will be reflected in your application, making it a seamless experience.

To access a web map created in your portal within your JavaScript Maps SDK application, you can either:

• Provide the item ID of the web map in the item-id attribute of the <arcgis-map> component.

1
<arcgis-map item-id="YOUR_WEB_MAP_ID"></arcgis-map>

• Or use the portal item ID to create a new WebMap object then add the web map to the map component in your application.

1
2
3
4
5
6
7
8
9
// Create a new WebMap object using the portal item ID.
const webMap = new WebMap({
  portalItem: {
    id: "YOUR_WEB_MAP_ID",
  },
});
// Set the web map to the map component.
const arcgisMap = document.querySelector("arcgis-map");
arcgisMap.map = webMap;

Using portal items

When a service is created, it is stored in a portal item that can be accessed by the portal item ID. When referencing the 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. 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",
  },
});

Using service URLs

A service can also be consumed by the JavaScript Maps SDK using the corresponding layer class and the service URL. For example, to access a feature layer that references a feature service, you can use the service URL to create a new FeatureLayer object.

1
2
3
4
5
const layer = new FeatureLayer({
  title: "Pool Permits",
  // The URL to the feature service.
  url: "https://sampleserver6.arcgisonline.com/arcgis/rest/services/PoolPermits/FeatureServer/1"
});

This is useful when you want to access a service that is not hosted in your portal or published as a portal item. When using a service URL, you will need to set the properties such as the renderer, popup, etc. in your application.

Data from other sources (non-ArcGIS)

The JavaScript Maps SDK provides classes to work with data from other sources, such as GeoJSON files, CSV files, or OGC data in your application.

See the following sections for more information on how to use these data formats in your application.

• Working with external data sources
• OGC data samples
• GeoJSON data samples
• CSV data samples
• KML data samples

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 and hosted data:

• API key set globally: Set a single API key to access all ArcGIS location services and hosted data configured in your application.
• API key on a specific class: Set 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.

Set an API key globally

Setting an API key globally allows your application to use one key to access secure hosted data and all location services configured in your application. This means every privilege that your application needs should be set on this single API key. For example, if you are using basemap styles, geocoding, routing, and spatial analysis services, the API key will have all the privileges enabled on creation to access these services. An API key can be set globally in your application by defining the esriConfig variable:

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. See the display a map tutorial for an example of how to set an API key globally within your JavaScript Maps SDK application.

Set an API key to access specific ArcGIS services

When setting an API key on a specific class, this key needs to have specific privileges enabled during the creation process to access the 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.

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",
});

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}, for example arcgis/navigation. See the ArcGIS Basemap Styles service documentation 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 globally set API key should be configured when using the basemap styles 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
10
const spanishBasemap = new Basemap({
  style: new BasemapStyle({
    id: "arcgis/human-geography",
    language: "es", // place labels will be displayed in Spanish
  }),
});
const viewElement = document.querySelector("arcgis-map");
viewElement.map = new Map({
  basemap: spanishBasemap,
});

Static basemaps

The JavaScript Maps SDK also supports consuming the ArcGIS Static Basemap Tiles service, which is a location service that provides basemap data as pre-rendered and pre-styled map tiles for the world.

To use the static basemaps, you can create a new TileLayer object with the URL to the static basemap tiles service and add it to the map.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// create the tile layer with the default style
const staticBasemapLayer = new TileLayer({
  url: `https://static-map-tiles-api.arcgis.com/arcgis/rest/services/static-basemap-tiles-service/v1/arcgis/outdoor/static`,
  customParameters: {
    // set the basemap language to French
    language: "fr",
  }
});
// create the basemap with the tile layer and add it to the map
viewElement.map = new Map({
  basemap: new Basemap({
    baseLayers: [staticBasemapLayer]
  })
});

See the Static basemap tiles sample for a complete example of how to use the static basemaps in your application.

Geocoding

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

When using custom Search component/widget parameters or creating a locator, set the 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
10
11
// 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 API key globally 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.

Samples and tutorials with ArcGIS Location Platform

The ArcGIS Maps SDK for JavaScript provides a number of tutorials and samples to help you build powerful mapping applications. To use the tutorials and samples with ArcGIS Location Platform, they may need to be updated to use the location services and API key authentication.

Web maps

If the sample or tutorial is using a web map, the web map will need to be opened in Map Viewer and the basemap updated by using the Basemap tool. See the Switch the basemap documentation on more information. Once the basemap is updated, you can save the web map and use it in your application. An API key should be set globally in your application using the apiKeys.basemapStyles property on esriConfig once the web map is updated to use the basemap styles service. See the Web maps section for more information on how to set a web map in your JavaScript Maps SDK application.

Updating the basemap

If the sample or tutorial is not using a web map and is working directly with layers and basemaps, you will need to make sure to update the basemap to use the basemap styles service. See the Basemaps section for more information on how to use the basemap styles service in your application. An API key should be set globally in your application using the apiKeys.basemapStyles property on esriConfig when using the basemap styles service.

Geocoding and routing

If the sample or tutorial is using a geocoding service or routing service you will need to set the API key on the component/widget or set an API key globally in your application. See the Geocoding and Routing and directions sections for more information on how to set the API key on the component/widget.