Migrate to ArcGIS location services

Follow these steps to migrate your existing ArcGIS Maps SDK for JavaScript app to the new location services released with ArcGIS Location Platform.

This information is intended for developers who have an existing app built with the ArcGIS Maps SDK for JavaScript and would like to migrate to using new location services. We recommend you first migrate your app to the latest JavaScript SDK version 4.31, as that will ensure you have the most up to date version of the classes.

If your app was built with ArcGIS API for JavaScript version 3.x, please refer to Migrating from 3.x to 4.x.

Authentication

In order to use any of the new location 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 permanent token that grants your application access to location services and, with an ArcGIS Location Platform account, 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.

Learn more about getting an access token in Security and authentication.

Global API key

If you are using an API key, you can use it in your code as follows:

1
2
3
    require(["esri/config","esri/Map", "esri/views/MapView"], function (esriConfig, Map, MapView) {

        esriConfig.apiKey = "YOUR_ACCESS_TOKEN";

This will set a global API key which will be used to access all ArcGIS location services that are used by your app. You can override this key by setting a key explicitly on layers, widgets, and other classes that use platform services.

Basemaps

Review the basemap styles service and the variety of basemaps available. 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.

1
2
3
        const map = new Map({
          basemap: "arcgis/topographic" // Basemap styles service
        });

If you are instead adding a basemap to the map by creating a new basemap object and referencing the service URL, make sure you use one of the basemaps from the basemap styles service.

Geocoding

If you are already using the search widget with the default parameters, you only need to set the global API key and the widget will use the geocoding service for search.

1
2
3
4
5
6
    esriConfig.apiKey = "YOUR_ACCESS_TOKEN";

    const searchWidget = new Search({
        view: view,
        includeDefaultSources: true
    });

If you are not using the default search widget parameters, or your are creating a locator, set the API key and service URL.

1
2
3
4
5
6
7
8
9
10
11
12
    const searchWidget = new Search({
        view: view,
        includeDefaultSources: false,
        sources: [{
            name: "locator",
            placeholder: "Search for a place...",
            apiKey: "YOUR_ACCESS_TOKEN",
            locator: new Locator({
                url: "https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer"
            })
        }]
    });

Note that if you are using a global API key as described above, you don't need to set the API key directly on the search widget. Learn more about geocoding and search.

Route and directions

All routing and directions APIs and widgets are unchanged. Authentication is required to access these services. However, you now have the ability to use these services with an API key in addition to user authentication. Read more at Find routes and directions.

Other services

Read more at Location services to learn about other services available.