{"id":9095,"library":"mapbox-vector-tile","title":"Mapbox Vector Tile","description":"Mapbox Vector Tile (MVT) is a Python library for encoding and decoding Mapbox Vector Tiles. It is currently at version 2.2.0 and receives active maintenance releases, typically addressing dependency updates and minor improvements. MVTs are an efficient format for tiled vector data, commonly used in web mapping applications for performant rendering.","status":"active","version":"2.2.0","language":"en","source_language":"en","source_url":"https://github.com/tilezen/mapbox-vector-tile","tags":["mapbox","vector-tile","mvt","gis","geospatial","encoding","decoding","protobuf"],"install":[{"cmd":"pip install mapbox-vector-tile","lang":"bash","label":"Default Installation"},{"cmd":"pip install mapbox-vector-tile[proj]","lang":"bash","label":"With pyproj for CRS Transformations"}],"dependencies":[{"reason":"Core dependency for serializing structured data in MVT format.","package":"protobuf","optional":false},{"reason":"Used for geometry operations, particularly for polygon validity and compliance.","package":"pyclipper","optional":false},{"reason":"Used for geometry processing, including optimizations and validity checks.","package":"shapely","optional":false},{"reason":"Optional dependency for Coordinate Reference System (CRS) transformations when encoding or decoding tiles.","package":"pyproj","optional":true}],"imports":[{"symbol":"mapbox_vector_tile","correct":"import mapbox_vector_tile"}],"quickstart":{"code":"import mapbox_vector_tile\n\n# Example GeoJSON-like data structure for a layer\nlayer_data = {\n    \"name\": \"water\",\n    \"features\": [\n        {\n            \"geometry\": \"POLYGON ((0 0, 0 1, 1 1, 1 0, 0 0))\", # WKT geometry\n            \"properties\": {\"uid\": 123, \"foo\": \"bar\"}\n        },\n        {\n            \"geometry\": \"LINESTRING(-71.160281 42.258729,-71.160837 42.259113)\", # WKT geometry\n            \"properties\": {\"id\": 456, \"type\": \"river\"}\n        }\n    ]\n}\n\n# Encode to MVT (bytes)\nencoded_tile = mapbox_vector_tile.encode([layer_data])\nprint(f\"Encoded tile size: {len(encoded_tile)} bytes\")\n\n# Decode MVT (returns dictionary of layers)\ndecoded_layers = mapbox_vector_tile.decode(encoded_tile)\n\n# Accessing decoded data\nprint(f\"Decoded layers: {list(dec_layers.keys())}\")\nwater_layer = decoded_layers.get('water')\nif water_layer:\n    print(f\"First feature in 'water' layer: {water_layer['features'][0]['properties']}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"Version 2.0.0 of `mapbox-vector-tile` dropped support for Python 2.x. It now requires Python 3.9 or newer.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"deprecated","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions, particularly when adhering to MVT spec v2"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"Attempting to encode GeoJSON features of type 'GeometryCollection', which the `mapbox-vector-tile` library does not support directly.","error":"ValueError: GeometryCollection types are not supported"},{"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.","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.","error":"KeyError: 'features' when accessing decoded data (or similar structure mismatch)"},{"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.","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.","error":"Mapbox GL JS / Renderer displays unexpected holes, overlapping polygons, or missing features from vector tiles."}]}