Reference
Data Sources

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:

Review our advanced section on data sources for more information and examples on setting up and using custom data sources.

Raster

A raster tile source.

SDK Support
Javascript
>= 1.0.0
Apple
>= 1.0.0
Android
>= 1.0.0

Options

{
    type: 'raster';
    url: string;
    metadataUrl: string;
    tileSize: number;
    minZoom: number;
    maxZoom: number;
    transformRequest?: (source: RasterTileSource, request: DataSourceRequest) => DataSourceRequest;
}
OptionDescriptionDefault
urlType: string ()URL to the data tiles. If present, {z}, {x} and {y} are replaced with the corresponding tile coorodinate integers.

Custom variables from the values defined in your request object can be included in your URL by using the form {key}, where key is the property name used. You may also include one or more of the following built-in variables:

- {s}: Custom server/host name used to spread tile requests across multiple hosts for faster load times. By default this variable is replaced by an integer in the range 1...4, but you can provide a set of custom values instead, e.g. {s::a-,b-,c-,d-} will use a-, b-, etc).

- {size}: Tile size as defined by tileSize, e.g. 256x256.
metadataUrlType: string ()URL to the data source metadata, if any. When provided, the metadata will be requested and cached on the source before any tile request begins.
tileSizeType: number ()Size of the data tiles.256
minZoomType: number ()Minimum zoom level for which data tiles are available or the minimum zoom level to request tiles for.0
maxZoomType: number ()Maximum zoom level for which data tiles are available or the maximum zoom level to request tiles for.22
transformRequestType: function ()An optional function used to transform the request for data before it is sent.
transformMetadataRequestType: function ()An optional function used to transform the request for metadata required by the data source before it is sent.
transformMetadataType: function ()An optional function used to transform the data source's metadata after it has been loaded from a remote source.

Methods

Vector

A vector tile source in the Mapbox Vector Tile (opens in a new tab) format.

SDK Support
Javascript
>= 1.0.0
Apple
-
Android
-

Options

{
    type: 'vector';
    url: string;
    minZoom: number;
    maxZoom: number;
    transformRequest?: (source: VectorTileSource, request: DataSourceRequest) => DataSourceRequest;
}
OptionDescriptionDefault
urlType: string ()URL to the data tiles. If present, {z}, {x} and {y} are replaced with the corresponding tile coorodinate integers.

Custom variables from the values defined in your request object can be included in your URL by using the form {key}, where key is the property name used. You may also include one or more of the following built-in variables:

- {s}: Custom server/host name used to spread tile requests across multiple hosts for faster load times. By default this variable is replaced by an integer in the range 1...4, but you can provide a set of custom values instead, e.g. {s::a-,b-,c-,d-} will use a-, b-, etc).

- {size}: Tile size as defined by tileSize.
metadataUrlType: string ()URL to the data source metadata, if any. When provided, the metadata will be requested and cached on the source before any tile request begins.
minZoomType: number ()Minimum zoom level for which data tiles are available or the minimum zoom level to request tiles for.0
maxZoomType: number ()Maximum zoom level for which data tiles are available or the maximum zoom level to request tiles for.22
transformRequestType: function ()An optional function used to transform the request for data before it is sent.
transformMetadataRequestType: function ()An optional function used to transform the request for metadata required by the data source before it is sent.
transformMetadataType: function ()An optional function used to transform the data source's metadata after it has been loaded from a remote source.

Methods

GeoJSON

A source containing a variety of geographic data structures in GeoJSON (opens in a new tab) format.

SDK Support
Javascript
>= 1.0.0
Apple
-
Android
-

Options

{
    type: 'geojson';
    data?: string | Record<string, any>;
    url?: string;
    transformRequest?: (source: GeoJSONSource, request: DataSourceRequest) => DataSourceRequest;
    transformGeoJSON?: (source: GeoJSONSource, data: GeoJSONFeatureCollection) => GeoJSONFeatureCollection;
}
OptionDescriptionDefault
dataType: string or object ()The inline GeoJSON object to use for the source.
urlType: string ()The GeoJSON URL template string to use when requesting GeoJSON data.
transformRequestType: function ()An optional function used to transform the request for data before it is sent.
transformMetadataRequestType: function ()An optional function used to transform the request for metadata required by the data source before it is sent.
transformMetadataType: function ()An optional function used to transform the data source's metadata after it has been loaded from a remote source.
transformGeoJSONType: function ()A function that transforms the GeoJSON data when loaded from a remote source before it is added to the source.

Methods

Encoded Raster

A raster tile source whose data is encoded in and sampled from one or more RGBA color bands. This source is used for gridded weather data sets from the MapsGL Raster Tile API.

SDK Support
Javascript
>= 1.0.0
Apple
>= 1.0.0
Android
>= 1.0.0

Options

{
    type: 'encoded';
    url: string;
    metadataUrl: string;
    request: { 
        method: 'GET' | 'POST'; 
        headers: Record<string, string>; 
    };
    minZoom: number;
    maxZoom: number;
    datasets: Array<Partial<Dataset>>;
    transformRequest?: (source: EncodedTileSource, request: DataSourceRequest) => DataSourceRequest;
}
OptionDescriptionDefault
urlType: string ()URL to the data tiles. If present, {z}, {x} and {y} are replaced with the corresponding tile coorodinate integers.

Custom variables from the values defined in your request object can be included in your URL by using the form {key}, where key is the property name used. You may also include one or more of the following built-in variables:

- {s}: Custom server/host name used to spread tile requests across multiple hosts for faster load times. By default this variable is replaced by an integer in the range 1...4, but you can provide a set of custom values instead, e.g. {s::a-,b-,c-,d-} will use a-, b-, etc).

- {size}: Tile size as defined by tileSize.
metadataUrlType: string ()URL to the data source metadata, if any. When provided, the metadata will be requested and cached on the source before any tile request begins.
minZoomType: number ()Minimum zoom level for which data tiles are available or the minimum zoom level to request tiles for.0
maxZoomType: number ()Maximum zoom level for which data tiles are available or the maximum zoom level to request tiles for.22
datasetsType: Array<Dataset> ()
transformRequestType: function ()An optional function used to transform the request for data before it is sent.
transformMetadataRequestType: function ()An optional function used to transform the request for metadata required by the data source before it is sent.
transformMetadataType: function ()An optional function used to transform the data source's metadata after it has been loaded from a remote source.
`Type: ()

Methods

Transformers

Transformers are functions that can be used to transform data requests and responses for a data source. These can be used to modify the request for data before it is sent, or to modify the data after it is received.