Key concepts

This document provides an overview of how to work with Mapbox GL JS and ArcGIS location services to build mapping applications. The topics include how to work with basemap layers, hosted data layers, location services, and developer tools.

This app shows how to display a basemap layer and use ArcGIS REST JS to access location services.

Working with basemap layers and styles

Basemap layers are vector tile layers with styles for streets, topography, and satllite imagery that you can use in a Mapbox GL JS map. The data format for basemap layers is based on the Mapbox vector tile specification. You can use the default styles provided by the basemap layer service or you can create your own custom styles.

For more background information, visit Basemap layers in the Mapping APIs and location services guide.

Display a basemap style

To access a default basemap layer style, use a url to access the service with an enumeration for the desired style.

Steps

  1. Define an basemap style enumeration.
  2. Define the URL.
  3. Access the basemap layer.
        
1
2
3
4
5
6
7
8
const apiKey = "YOUR_API_KEY";
const basemapEnum = "ArcGIS:Navigation"; // Style enumeration
const map = new mapboxgl.Map({
  container: "map",
  style: `https://basemaps-api.arcgis.com/arcgis/rest/services/styles/${basemapEnum}?type=style&token=${apiKey}`,
  zoom: 12,
  center: [-118.805, 34.027]
});

To learn more, see the Display a map and Change the basemap layer tutorials.

Display a custom basemap style

To access a custom basemap layer style, you first need to create the custom style, and then you use a url to access the service with the item ID for the custom style.

Steps

  1. Create a custom style with the vector tile style editor and get the item ID.
  2. Define an basemap style enumeration.
  3. Define the URL with the enumeration and API key.
  4. Access the basemap layer.
         
1
2
3
4
5
6
7
8
9
const apiKey = "YOUR_API_KEY";
const basemapEnum = "6976148c11bd497d8624206f9ee03e30";  // Item id for custom basemap layer style

const map = new mapboxgl.Map({
  container: "map",
  style: `https://basemaps-api.arcgis.com/arcgis/rest/services/styles/${basemapEnum}?type=style&token=${apiKey}`,
  zoom: 12,
  center: [-118.805, 34.027]
});

To learn more, see the Create a custom basemap style and Display a custom vector tile style tutorials.

Working with hosted data layers

Hosted data layers provide a way to manage and access your own data as data services. You can host data as feature layers, vector tile layers, or image tile layers. Once published, you can use Mapbox GL JS to access the layers and display them in a map.

For more background information, visit Data hosting in the Mapping APIs and location services guide.

Publish and display a feature layer

If you have feature data with a geometry and attributes, you can import and publish it as feature layer in a feature service. To access the data, use a URL to query the feature layer and return the features as GeoJSON. To display the features, you have to style the features on the client. It is important to note however that feature layers can also contain styling information, and this information could be used to help style the layer.

Steps

  1. Import your data from a CSV, XLS, GeoJSON, or Shapefile file to create a hosted feature layer.
  2. Get the URL for the feature layer.
  3. Define a data source to access and query the feature layer.
  4. Display the data in a layer.
               
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
map.addSource("trailheads", {
  type: "geojson",
  data: "https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/Trailheads/FeatureServer/0/query?f=pgeojson&where=1=1",
});

map.addLayer({
  id: "trailheads-circle",
  type: "circle",
  source: "trailheads",
  paint: {
    "circle-color": "hsla(0,0%,0%,0.75)",
    "circle-stroke-width": 1.5,
    "circle-stroke-color": "white",
  }
});

To learn more, go to the Import data as a feature layer and access and Add a feature layer tutorials.

Publish and display a vector tile layer

If you want to access and display your data as vector tile data, you can publish a vector tile layer from a feature layer, and then display it in a map. Vector tile layers closely follow the Mapbox vector tile specification, but there a few important differences:

  • Url endpoints end in /{z}/{y}/{x}.pbf, rather than /{z}/{x}/{y}.pbf.
  • Each style may contain one source.
  • The raster and hillshade layer types are not supported.

Steps

  1. Import your data from a CSV, XLS, GeoJSON, or Shapefile file to create a hosted feature layer.
  2. Style the feature layer using ArcGIS Online.
  3. Create a vector tile service by publishing the feature layer as a vector tile layer.
  4. Get the URL.
  5. Access and display the vector tile layer in your application.
                
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
map.addSource("parcels", {
  type: "vector",
  tiles: ["https://vectortileservices3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/Santa_Monica_Mountains_Parcels_VTL/VectorTileServer/tile/{z}/{y}/{x}.pbf"]
});

map.addLayer({
  id: "parcels-fill",
  type: "fill",
  source: "parcels",
  "source-layer": "Santa_Monica_Mountains_Parcels",
  paint: {
    "fill-color": "hsl(200, 80%, 50%)",
    "fill-opacity": 0.5,
    "fill-outline-color": "white"
  }
});

To learn more, go to the Publish a vector tile layer and access and Add a vector tile layer tutorials.

Working with location services

The easiest way to access ArcGIS location services with Mapbox GL JS is with ArcGIS REST JS. This is a JavaScript library that you can use to authenticate, access, and make requests to services. You can learn more about the library in the API reference or in the tutorials in the ArcGIS REST JS guide.

Access the geocoding service

To access the geocoding service, you need to reference the ArcGIS REST JS libraries and then call the service with the desired parameters.

Steps

  1. Reference the ArcGIS REST JS libraries.
  2. Define the parameters.
  3. Call the service.
                     
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
const authentication = new arcgisRest.ApiKey({
  key: "YOUR_API_KEY"
});

arcgisRest
  .geocode({
    singleLine: query,
    authentication,
    params: {
      location: map.getCenter().toArray().join(","), // center of map as longitude,latitude
      outFields: "*" // return all fields
    }
  })
  .then((response) => {
    const result = response.candidates[0];
    const lngLat = [result.location.x, result.location.y];
    new mapboxgl.Popup()
      .setLngLat(lngLat)
      .setHTML(result.attributes.LongLabel)
      .addTo(map);
  });

Learn more in the Search for an address tutorial.

Access the routing service

To access the routing service, you need to reference the ArcGIS REST JS libraries and then call the service with the desired parameters.

Steps

  1. Reference the ArcGIS REST JS libraries.
  2. Define the parameters.
  3. Call the service.
              
1
2
3
4
5
6
7
8
9
10
11
12
13
14
const authentication = new arcgisRest.ApiKey({
  key: "YOUR_API_KEY"
});

arcgisRest
  .solveRoute({
    stops: [startCoords, endCoords],
    endpoint: "https://route-api.arcgis.com/arcgis/rest/services/World/Route/NAServer/Route_World/solve",
    authentication
  })
  .then((response) => {
    map.getSource("route").setData(response.routes.geoJson);
  })
}

Learn more in the Find a route and directions tutorial.

Access the GeoEnrichment service

To access the GeoEnrichment service, you need to reference the ArcGIS REST JS libraries and then call the service with the desired parameters.

Steps

  1. Reference the ArcGIS REST JS libraries.
  2. Define the parameters.
  3. Call the service.
                               
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
const authentication = new arcgisRest.ApiKey({
  key: "YOUR_API_KEY"
});

const response = await arcgisRest.queryDemographicData({
  studyAreas: [
    {
      geometry: {
        x: e.lngLat.lng,
        y: e.lngLat.lat
      }
    }
  ],
  authentication: authentication
});

let message;
const featureSet = response.results[0].value.FeatureSet;
if (featureSet.length > 0 && featureSet[0].features.length > 0) {
  const attributes = featureSet[0].features[0].attributes;
  message =
    `<b>Data for a 1 mile search radius</b>` +
    [
      `Population: ${attributes.TOTPOP.toLocaleString()}`,
      `Males: ${attributes.TOTMALES.toLocaleString()}`,
      `Females: ${attributes.TOTFEMALES.toLocaleString()}`,
      `Average household size: ${attributes.AVGHHSZ}`
    ].join("<br>");
} else {
  message = "Data not available for this location.";
}

Learn more in the Query demographic data tutorial.

Developer tools

There are ArcGIS developer tools and services with similar capabilities to Mapbox tools and services. In many cases, you can mix and match services from the two platforms: for instance, displaying results from the geocoding service on a Mapbox GL JS map. Below are some of the tools and services that can be used in place of its Mapbox counterpart:

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.