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 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 API version 4.26, 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 scope and permissions available to your application.

There are three kinds of access tokens:

• API key: permanent token that grants your application access to ready-to-use services.
• ArcGIS identity: temporary token generated by OAuth 2.0 that gives your application access to the private content and ready-to-use services that are accessible by an existing ArcGIS user's account. Review the sample Access ArcGIS Online items using OAuth 2.0
• Application credentials: temporary token generated via OAuth 2.0 that can authorize access to ready-to-use services.

Learn more about getting an access token in Security and authentication and the Display a map tutorial.

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_API_KEY";

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 layer service and the variety of basemaps available. Supply one of the enumeration values from the Basemap class designated for ArcGIS Developer accounts like this:

1
2
3
        const map = new Map({
          basemap: "arcgis-topographic" // Basemap layer 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 layer 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_API_KEY";

    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_API_KEY",
            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 ArcGIS identity. Read more at Find routes and directions.

Other services

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