Mapbox Vector Tile

Common errors

• ValueError: GeometryCollection types are not supported

  cause Attempting to encode GeoJSON features of type 'GeometryCollection', which the `mapbox-vector-tile` library does not support directly.
  fix Before encoding, flatten any `GeometryCollection` features into their constituent 'Point', 'LineString', or 'Polygon' geometries. You will need to process the input GeoJSON to extract individual geometry types.

• KeyError: 'features' when accessing decoded data (or similar structure mismatch)

  cause You are decoding a tile with `mapbox_vector_tile.decode()` and expecting the output structure from versions prior to 2.0.0, but the default behavior changed to RFC7946 compliance.
  fix If you need the pre-2.0.0 output format, pass `geojson=False` to the `decode` method: `decoded_data = mapbox_vector_tile.decode(tile_bytes, geojson=False)`. Otherwise, adjust your code to expect the RFC7946 compliant GeoJSON output structure.

• Mapbox GL JS / Renderer displays unexpected holes, overlapping polygons, or missing features from vector tiles.

  cause The input geometries used for encoding did not strictly adhere to the Mapbox Vector Tile Specification v2, particularly regarding polygon winding order or OGC validity.
  fix Ensure that exterior rings of polygons are clockwise and interior rings (holes) are counter-clockwise when viewed in screen coordinates. Validate geometries for self-intersections or other invalid conditions before encoding. The library's internal `on_invalid_geometry_make_valid` option can help, but pre-validation is often more robust.

Warnings

• breaking Version 2.0.0 of `mapbox-vector-tile` dropped support for Python 2.x. It now requires Python 3.9 or newer.
  Fix: Upgrade your Python environment to 3.9 or later. If you need Python 2 compatibility, you must use a version older than 2.0.0.
• deprecated The `decode` function's `geojson` parameter default changed in versions >=2.0.0. It now defaults to `True`, which enforces RFC7946 compatible GeoJSON output. Using the old non-RFC7946 compliant output (pre-2.0.0 behavior) is deprecated.
  Fix: If you require the exact output format of `decode()` from versions prior to 2.0.0, explicitly set `geojson=False` in your `decode()` call (e.g., `mapbox_vector_tile.decode(tile_data, geojson=False)`). Otherwise, adapt your code to handle the RFC7946 compliant output.
• gotcha The `mapbox-vector-tile` library can utilize the C++ implementation of the underlying `protobuf` library for significantly better performance compared to the pure Python implementation. This often requires additional system-level setup.
  Fix: For performance-critical applications, consider installing the C++ `protobuf` bindings for your system. This may involve installing `libprotoc` and `protobuf-compiler` packages, and setting environment variables like `PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATION=cpp` and `PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATION_VERSION=2` before running your Python program. Refer to the `protobuf` library's documentation for detailed installation instructions for your specific OS.
• gotcha Mapbox Vector Tile Specification v2 (which `mapbox-vector-tile` aims to support) requires OGC-valid geometries and specific winding orders for polygons (exterior rings clockwise, interior rings counter-clockwise in screen coordinates) to correctly represent holes. Invalid geometries or incorrect winding orders can lead to rendering issues or dropped features.
  Fix: Ensure your input geometries are OGC-valid. Use libraries like Shapely to validate and, if necessary, fix geometries (e.g., `shapely.validation.make_valid`). Pay close attention to polygon winding orders for complex polygons with holes.

Install

• pip install mapbox-vector-tile Default Installation
• pip install mapbox-vector-tile[proj] With pyproj for CRS Transformations

Imports

• mapbox_vector_tile

  import mapbox_vector_tile

Quickstart

Demonstrates encoding a simple GeoJSON-like structure (using WKT geometries) into a Mapbox Vector Tile and then decoding it back. The `encode` method expects a list of layer dictionaries, each containing a name and a list of features with geometry (WKT, WKB, or Shapely object) and properties. The `decode` method returns a dictionary where keys are layer names and values are the decoded layer data.

import mapbox_vector_tile

# Example GeoJSON-like data structure for a layer
layer_data = {
    "name": "water",
    "features": [
        {
            "geometry": "POLYGON ((0 0, 0 1, 1 1, 1 0, 0 0))", # WKT geometry
            "properties": {"uid": 123, "foo": "bar"}
        },
        {
            "geometry": "LINESTRING(-71.160281 42.258729,-71.160837 42.259113)", # WKT geometry
            "properties": {"id": 456, "type": "river"}
        }
    ]
}

# Encode to MVT (bytes)
encoded_tile = mapbox_vector_tile.encode([layer_data])
print(f"Encoded tile size: {len(encoded_tile)} bytes")

# Decode MVT (returns dictionary of layers)
decoded_layers = mapbox_vector_tile.decode(encoded_tile)

# Accessing decoded data
print(f"Decoded layers: {list(dec_layers.keys())}")
water_layer = decoded_layers.get('water')
if water_layer:
    print(f"First feature in 'water' layer: {water_layer['features'][0]['properties']}")