Add a feature layer as GeoJSON

Learn how to add features as GeoJSON to a map.

A feature layer is a dataset in a hosted feature service. Each feature layer contains features with a single geometry type (point, line, or polygon), and a set of attributes. You can access and display features by making query requests to the feature service and displaying them in a map.

In this tutorial, you access the Trailheads feature layer to get GeoJSON and display the features as clusters. Working with GeoJSON is often useful for dynamically generated data, but not suitable for large datasets.

Prerequisites

You need an ArcGIS Location Platform or ArcGIS Online account.

Steps

Create a new pen

  1. To get started, either complete the Display a map tutorial or .

Get an access token

You need an access token with the correct privileges to access the resources used in this tutorial.

  1. Go to the Create an API key tutorial and create an API key with the following privilege(s):

    • Privileges
      • Location services > Basemaps
    • Item access
      • Note: If you are using your own custom data layer for this tutorial, you need to grant the API key credentials access to the layer item. Learn more in Item access privileges.
  2. Copy the API key access token to your clipboard when prompted.

  3. In CodePen, update the accessToken variable to use your access token.

    Use dark colors for code blocks
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    const accessToken = "YOUR_ACCESS_TOKEN";
    const basemapEnum = "arcgis/streets";
    const map = new maplibregl.Map({
      container: "map", // the id of the div element
      style: `https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/styles/${basemapEnum}?token=${accessToken}`,
      zoom: 12, // starting zoom
      center: [-118.805, 34.027] // starting location [longitude, latitude]
    });
    

To learn about the other types of authentication available, go to Types of authentication.

Add a load event handler

You need to wait for the map to be completely loaded before adding any layers.

  1. Add an event handler to the map load event.

    Expand
    Use dark colors for code blocks
    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
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
        <script>
          const accessToken = "YOUR_ACCESS_TOKEN";
          const basemapEnum = "arcgis/streets";
          const map = new maplibregl.Map({
            container: "map", // the id of the div element
            style: `https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/styles/${basemapEnum}?token=${accessToken}`,
            zoom: 12, // starting zoom
            center: [-118.805, 34.027] // starting location [longitude, latitude]
          });
    
          map.once("load", () => {
            // This code runs once the base style has finished loading.
    
          });
    
        </script>
    
    Expand

Add a GeoJSON source

To add GeoJSON from a feature service, you need to define a source of type geojson and reference the feature layer. The source tells MapLibre GL JS how to access the data for the layer, but does not visually add it to the map. To get GeoJSON features from a feature layer, you provide a URL to query the feature service and return features in GeoJSON format. Features can then be displayed by adding the source to a layer.

  1. Inside the load event handler, add a source. Set the id to trailheads and type to geojson. Set data to the URL for the trailheads feature layer. Append query?f=pgeojson&where=1=1 to the URL to request all of the features as GeoJSON.

    Expand
    Use dark colors for code blocks
    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
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
          map.once("load", () => {
            // This code runs once the base style has finished loading.
    
            map.addSource("trailheads", {
              type: "geojson",
              data: "https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/Trailheads/FeatureServer/0/query?f=pgeojson&where=1=1",
    
            });
    
          });
    
    Expand

Add a circle layer

A layer in MapLibre GL JS is a visual representation of the data within one source. Use a layer of type circle to display the trailheads.

  1. Use addLayer to add a circle layer with id trailheads-circle. Set source to trailheads to reference the source you just created. Add paint properties to make the circles black.

    Expand
    Use dark colors for code blocks
    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
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
          map.once("load", () => {
            // This code runs once the base style has finished loading.
    
            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",
    
              }
            });
    
          });
    
    Expand
  2. At the top right, click Run to display the basemap with trailheads as black dots.

Use clusters to display points

One benefit of using GeoJSON to load points in MapLibre GL JS is you can use clustering. This technique replaces a number of overlapping points with a single point that represents the cluster. It simplifies the visual appearance of the map by reducing detail, particularly at lower zoom levels.

To enable clustering, you pass additional parameters when defining the source: cluster: true and the optional parameters clusterRadius and clusterMaxZoom.

Points that represent clusters have a cluster property that is set to true. You can use this in your trailheads-circle layer to make those points larger, by using a data-driven expression for circle-radius. You use the case and get expressions for this.

They also have a point_count attribute which contains the number of points in the cluster. You can display this as a text label, using a symbol layer.

  1. Add cluster, clusterRadius and clusterMaxZoom attributes to the definition of the trailheads source.

    Expand
    Use dark colors for code blocks
    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
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
            map.addSource("trailheads", {
              type: "geojson",
              data: "https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/Trailheads/FeatureServer/0/query?f=pgeojson&where=1=1",
    
              cluster: true,
              clusterRadius: 20, // cluster two trailheads if less than 20 pixels apart
              clusterMaxZoom: 14 // display all trailheads individually from zoom 14 up
    
            });
    
    Expand
  2. Make each point larger if it represents a cluster.

    Expand
    Use dark colors for code blocks
    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
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
            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",
    
                "circle-radius": ["case", ["get", "cluster"], 10, 5] // 10 pixels for clusters, 5 pixels otherwise
    
              }
            });
    
    Expand
  3. Add a symbol layer, trailheads-cluster-count. Use the attribute point_count as the value for text-field.

    Expand
    Use dark colors for code blocks
    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
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
              paint: {
                "circle-color": "hsla(0,0%,0%,0.75)",
                "circle-stroke-width": 1.5,
                "circle-stroke-color": "white",
    
                "circle-radius": ["case", ["get", "cluster"], 10, 5] // 10 pixels for clusters, 5 pixels otherwise
    
              }
            });
    
            map.addLayer({
              id: "trailheads-cluster-count",
              type: "symbol",
              source: "trailheads",
              layout: {
                "text-font": ["Arial Bold"],
                "text-field": ["get", "point_count"],
                "text-offset": [0, 0.1] // move the label vertically downwards slightly to improve centering
              },
              paint: {
                "text-color": "white"
              }
            });
    
    Expand

Run the app

In CodePen, run your code to display the map.

The map should display the trailheads as clusters with a number on a large circle. Zoom in to see the clusters split into smaller clusters, and eventually split into single trailhead features.

What's next?

Learn how to use additional ArcGIS location services in these tutorials:

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