Custom Data Sources

Data sources are responsible for loading and providing the necessary data for a map layer. Since data sources are created and cached apart from their associated layer(s), a single data source can be used to render one or more layers with different styles. A layer must be associated with a data source in order for it to be rendered to the map.

The following data sources are supported:

raster: A raster tile source.
vector: A vector tile source in the Mapbox Vector Tile (opens in a new tab) format.
geojson: A GeoJSON (opens in a new tab) source that contains a variety of geographic data structures.
encoded: A raster tile source whose data is encoded in and sampled from one or more RGBA color bands.

Adding Data Sources

In order to render data layers on your map, you must first add the necessary data source that corresponds to the type of data you want to render.

For instance, you want to render a vector tile source, such as our weather alerts (opens in a new tab) dataset. You would first need to configure and add the source to the map controller:

controller.addSource('alerts', {
    type: 'vector',
    url: 'https://maps{s}.aerisapi.com/[CLIENT_ID]_[CLIENT_SECRET]/alerts/{z}/{x}/{y}/0.pbf'
});

The above source configuration provides the data source type, vector in this case because we're using vector tiles, and the url template string to use when requesting individual tiles. We also assign it a custom identifier as the first argument to addSource, which we're just setting to alerts in this example.

If your dataset only contained data tiles within a certain zoom range or you wanted to limit data requests, you can also provide that information in your configuration as well:

controller.addSource('alerts', {
    type: 'vector',
    url: 'https://maps{s}.aerisapi.com/[CLIENT_ID]_[CLIENT_SECRET]/alerts/{z}/{x}/{y}/0.pbf',
    minZoom: 4,
    maxZoom: 8
});

Then if your application needs to update the tile URL template used for tile requests at a later time, you can use the setTileUrl method on your source instance:

// 'source' is the instance returned by `addSource` above
source.setTileUrl('https://maps{s}.aerisapi.com/[CLIENT_ID]_[CLIENT_SECRET]/alerts/{z}/{x}/{y}/202205061110.pbf');
 
// or, use 'getSource' on your map controller to get the source instance and update its tile url
controller.getSource('alerts').setTileUrl('https://maps{s}.aerisapi.com/[CLIENT_ID]_[CLIENT_SECRET]/alerts/{z}/{x}/{y}/202205061110.pbf');

Raster, vector and encoded data sources all work similar to the example above. If you want to render GeoJSON data, then its data source is configured slightly differently since we're not working with map tiles.

For instance, you can configure a GeoJSON source to request data from a remote URL, such as earthquake (opens in a new tab) data from our Weather API (opens in a new tab) and its geojson response format:

controller.addSource('earthquakes', {
    type: 'geojson',
    data: 'https://data.api.xweather.com/earthquakes/search?query=mag:1&limit=200&format=geojson&client_id=[CLIENT_ID]&client_secret=[CLIENT_SECRET]'
});

Or, you can set the static data directly:

controller.addSource('earthquakes', {
    type: 'geojson',
    data: {
        "type": "FeatureCollection",
        "features": [{
            "type": "Feature",
            "geometry": {
                "type": "Point",
                "coordinates": [
                    -117.7805,
                    38.1714
                ]
            },
            "properties": {
                "report": {
                    "id": "nn00838438",
                    "timestamp": 1651863279,
                    "dateTimeISO": "2022-05-06T11:54:39-07:00",
                    "updatedTimestamp": 1651863515,
                    "updatedDateTimeISO": "2022-05-06T11:58:35-07:00",
                    "mag": 1.7,
                    "type": "mini",
                    "depthKM": 1.7,
                    "depthMI": 1.06,
                    "region": "37 km SE of Mina, Nevada",
                    "location": "37 km SE of Mina, Nevada"
                },
                "loc": {
                    "long": -117.7805,
                    "lat": 38.1714
                }
            }
        }, {
            "type": "Feature",
            "geometry": {
                "type": "Point",
                "coordinates": [
                    -155.38716125488,
                    19.248332977295
                ]
            },
            "properties": {
                "report": {
                    "id": "hv73004612",
                    "timestamp": 1651863228,
                    "dateTimeISO": "2022-05-06T08:53:48-10:00",
                    "updatedTimestamp": 1651863409,
                    "updatedDateTimeISO": "2022-05-06T08:56:49-10:00",
                    "mag": 1.83000004,
                    "type": "mini",
                    "depthKM": 32.25,
                    "depthMI": 20.04,
                    "region": "10 km ENE of Pāhala, Hawaii",
                    "location": "10 km ENE of Pāhala, Hawaii"
                },
                "loc": {
                    "long": -155.38716125488,
                    "lat": 19.248332977295
                }
            }
        }]
    }
});

And similar to tile-related data sources, you can also update either the GeoJSON url or data on your source after it has been added to your map as needed:

// update the remote GeoJSON url
source.setUrl('https://data.api.xweather.com/earthquakes/search?query=mag:1&limit=200&from=-7days&to=now&format=geojson&client_id=[CLIENT_ID]&client_secret=[CLIENT_SECRET]');
 
// or, update the source data directly
controller.getSource('earthquakes').setData({
    "type": "FeatureCollection",
    "features": [{
        "type": "Feature",
        "geometry": {
            "type": "Point",
            "coordinates": [
                -117.7805,
                38.1714
            ]
        },
        "properties": {
            "report": {
                "id": "nn00838438",
                "timestamp": 1651863279,
                "dateTimeISO": "2022-05-06T11:54:39-07:00",
                "updatedTimestamp": 1651863515,
                "updatedDateTimeISO": "2022-05-06T11:58:35-07:00",
                "mag": 1.7,
                "type": "mini",
                "depthKM": 1.7,
                "depthMI": 1.06,
                "region": "37 km SE of Mina, Nevada",
                "location": "37 km SE of Mina, Nevada"
            },
            "loc": {
                "long": -117.7805,
                "lat": 38.1714
            }
        }
    }]
});

With your data sources configured and added to the map controller, you can now add your associated layers to render that data on your map. Refer to our getting started documentation on layers for more information about the supported layers, render styles and their configuration.

Determining Layers Using a Source

If you need to know which map layers, if any, are currently associated with a particular data source on your map, you can use the consumingLayers property on that source. This property will return an array of objects containing information about which layers are consuming and rendering the data from that source. Referencing this property may be useful to determine when performing cleanup and removing unused data sources from your map.

Each layer in the array will contain a metadata object in the form:

{
    layerId: string;
    sourceLayerId: string;
    sourceLayerType: string;
    type: string;
}

Option	Description	Default
`layerId`	Type: ()The layer identifier consuming the source.
`sourceLayerId`	Type: ()For `vector` tile sources, the source data layer associated with the layer.
`sourceLayerType`	Type: ()For `vector` tile sources, the geometry type from the data associated with the layer.
`type`	Type: ()The layer renderer style type.

Removing Data Sources

Removing a data source from your map controller is simple, just provide the identifier you assigned the source when it was added to the map:

controller.removeSource('alerts');

If the source exists on the map, then it will be removed and perform any necessary cache and object disposal.

Advanced Usage Custom Layers