Data Sources and Tiles

Purpose and Scope

This document explains how Mapbox GL JS manages geographic data sources and the tile system that powers the map rendering process. It covers the various types of data sources supported by the library, how they are configured within the style specification, and the tile-based mechanism used to efficiently load and display geographic data at different zoom levels.

For information about how these data sources are rendered on the map, see Rendering System and Layer Rendering.

Overview of the Data Sources System

Data sources provide the geographic information that is rendered on the map. Mapbox GL JS supports various source types, from vector and raster tiles to GeoJSON data and media sources. Sources are managed by the Style system and are referenced by layers to determine what data to render and how to style it.

100%

Source Types

Mapbox GL JS supports several types of data sources, each with specific capabilities and use cases:

Vector Sources

Vector sources provide vector tile data, a compact representation of geographic data using points, lines, and polygons. Vector tiles are rendered on the client side, allowing for dynamic styling and interaction.

100%

Raster Sources

Raster sources provide raster tile data, which are pre-rendered images typically used for satellite imagery, terrain visualization, or other image-based maps.

100%

GeoJSON Sources

GeoJSON sources allow direct use of GeoJSON data, either inline or from an external URL. These sources are ideal for small to medium-sized datasets and dynamic data.

100%

Image and Video Sources

Image and video sources display georeferenced media on the map, mapped to specific geographic coordinates.

100%

Model Sources

Model sources (experimental) support 3D models for advanced visualizations.

Source Specification in Style

Sources are defined in the style specification and are referenced by layers. Here's how sources are structured within a style:

100%

Common Source Properties

All source types share certain common properties:

Property	Description
type	Required. Identifies the source type (e.g., "vector", "raster")
minzoom	Minimum zoom level for which data is available
maxzoom	Maximum zoom level for which data is available
attribution	Attribution text displayed on the map

Example Source Configurations

Vector Source

"mapbox-streets": {
  "type": "vector",
  "url": "mapbox://mapbox.mapbox-streets-v8",
  "minzoom": 0,
  "maxzoom": 14
}

Raster Source

"satellite": {
  "type": "raster",
  "url": "mapbox://mapbox.satellite",
  "tileSize": 256
}

GeoJSON Source

"points": {
  "type": "geojson",
  "data": {
    "type": "FeatureCollection",
    "features": [
      {
        "type": "Feature",
        "geometry": {
          "type": "Point",
          "coordinates": [-122.4194, 37.7749]
        },
        "properties": {
          "name": "San Francisco"
        }
      }
    ]
  }
}

Image Source

"radar": {
  "type": "image",
  "url": "https://docs.mapbox.com/mapbox-gl-js/assets/radar.gif",
  "coordinates": [
    [-80.425, 46.437],
    [-71.516, 46.437],
    [-71.516, 37.936],
    [-80.425, 37.936]
  ]
}

Tile System

Mapbox GL JS uses a tile-based system to efficiently load and display geographic data at different zoom levels. This approach divides the world into a grid of square tiles, with more detailed tiles available at higher zoom levels.

Tile Coordinates and Scheme

100%

Tile coordinates are represented as {z}/{x}/{y} where:

• z is the zoom level
• x is the column (longitude)
• y is the row (latitude)

The scheme property (xyz or tms) affects the y-direction of tile coordinates.

Zoom Levels and Overzooming

100%

• minzoom: The minimum zoom level at which tile data is available
• maxzoom: The maximum zoom level at which tile data is available
• Overzooming: When viewing the map at zoom levels beyond maxzoom, the system uses data from maxzoom and scales it up

SourceCache and Tile Management

100%

• Source: Abstract base class for all source types
• SourceCache: Manages a collection of tiles for a source
• Tile: Represents a single map tile with its data and state

Sources: Based on system architecture diagram provided in the prompt

Integration with Style and Rendering

Data sources are referenced by layers in the style specification, creating a connection between the data and how it's rendered.

100%

Source-Layer Relationship

Layers reference sources through their source property and, for vector tiles, can specify a source-layer to target specific data within the vector tile.

{
  "id": "water",
  "source": "mapbox-streets",
  "source-layer": "water",
  "type": "fill",
  "paint": {
    "fill-color": "#00ffff"
  }
}

Sources: src/style-spec/reference/v8.json210-220 src/style-layer/fill_style_layer_properties.ts33-49

Dynamic Source Updates

Sources can be dynamically updated after they've been added to the map:

// Update an image source
map.getSource("radar").updateImage({url: newImageUrl});

This allows for creating animated or real-time updated map visualizations.

Conclusion

The data sources and tile system are fundamental components of Mapbox GL JS, providing the geographic data that is visualized on the map. By understanding the different source types and how they interact with the tile system and style specification, developers can effectively manage map data and create rich, interactive visualizations.

For more information on how sources are processed by workers, see Worker Architecture. For details on how sources are used by the rendering system, see Rendering System.