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.

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-beta.1

Options

{
    type: 'raster';
    url: string;
    metadataUrl: string;
    tileSize: number;
    minZoom: number;
    maxZoom: number;
    transformRequest?: (source: RasterTileSource, request: DataSourceRequest) => DataSourceRequest;
}

Option	Description	Default
`url`	Type: `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`.
`metadataUrl`	Type: `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.
`tileSize`	Type: `number` ()Size of the data tiles.	`256`
`minZoom`	Type: `number` ()Minimum zoom level for which data tiles are available or the minimum zoom level to request tiles for.	`0`
`maxZoom`	Type: `number` ()Maximum zoom level for which data tiles are available or the maximum zoom level to request tiles for.	`22`
`transformRequest`	Type: `function` ()An optional function used to transform the request for data before it is sent.
`transformMetadataRequest`	Type: `function` ()An optional function used to transform the request for metadata required by the data source before it is sent.
`transformMetadata`	Type: `function` ()An optional function used to transform the data source's metadata after it has been loaded from a remote source.

Methods

setTileUrl(url: string)

getTileUrl(coord: TileCoord, params?: Record<string, any>): string

hasTile(coord: TileCoord): boolean)

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;
}

Option	Description	Default
`url`	Type: `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`.
`metadataUrl`	Type: `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.
`minZoom`	Type: `number` ()Minimum zoom level for which data tiles are available or the minimum zoom level to request tiles for.	`0`
`maxZoom`	Type: `number` ()Maximum zoom level for which data tiles are available or the maximum zoom level to request tiles for.	`22`
`transformRequest`	Type: `function` ()An optional function used to transform the request for data before it is sent.
`transformMetadataRequest`	Type: `function` ()An optional function used to transform the request for metadata required by the data source before it is sent.
`transformMetadata`	Type: `function` ()An optional function used to transform the data source's metadata after it has been loaded from a remote source.

Methods

setTileUrl(url: string)

getTileUrl(coord: TileCoord, params?: Record<string, any>): string

hasTile(coord: TileCoord): boolean)

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;
}

Option	Description	Default
`data`	Type: `string` or `object` ()The inline GeoJSON object to use for the source.
`url`	Type: `string` ()The GeoJSON URL template string to use when requesting GeoJSON data.
`transformRequest`	Type: `function` ()An optional function used to transform the request for data before it is sent.
`transformMetadataRequest`	Type: `function` ()An optional function used to transform the request for metadata required by the data source before it is sent.
`transformMetadata`	Type: `function` ()An optional function used to transform the data source's metadata after it has been loaded from a remote source.
`transformGeoJSON`	Type: `function` ()A function that transforms the GeoJSON data when loaded from a remote source before it is added to the source.

Methods

setUrl(url: string)

setData(data: GeoJSON)

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-beta.1

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;
}

Option	Description	Default
`url`	Type: `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`.
`metadataUrl`	Type: `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.
`minZoom`	Type: `number` ()Minimum zoom level for which data tiles are available or the minimum zoom level to request tiles for.	`0`
`maxZoom`	Type: `number` ()Maximum zoom level for which data tiles are available or the maximum zoom level to request tiles for.	`22`
`datasets`	Type: `Array<Dataset>` ()
`transformRequest`	Type: `function` ()An optional function used to transform the request for data before it is sent.
`transformMetadataRequest`	Type: `function` ()An optional function used to transform the request for metadata required by the data source before it is sent.
`transformMetadata`	Type: `function` ()An optional function used to transform the data source's metadata after it has been loaded from a remote source.
`	Type: ()

Methods

getMetadataForBand(band: string): any

getDataRange(band: SampleChannel): { min: number; max: number; }

setTileUrl(url: string)

getTileUrl(coord: TileCoord, params?: Record<string, any>): string

hasTile(coord: TileCoord): boolean)

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.

transformRequest?: (source: DataSource, request: DataSourceRequest) => DataSourceRequest;

transformMetadataRequest?: (source: DataSource, options: UrlRequestOptions) => UrlRequestOptions;

transformMetadata?: (source: DataSource, data: Record<string, any>, options?: SourceMetadataTransformOptions) => Partial<SourceMetadataSchema>;

transformGeoJSON?: (source: GeoJSONSource, data: GeoJSONFeatureCollection) => GeoJSONFeatureCollection;

Map Controller Layers