After obtaining a vector tile, you must decode it by using a protobuf schema. Decoding the geographic information that a vector tile stores as points, lines, and polygons, enables your application to use that data for map rendering.
vector_tile.proto is the protobuf schema name parameter that you obtained through the request to the proto endpoint.
Result: A successful server response contains the protobuf schema for you to use to decode vector tiles, as demonstrated in the following example:
//package vector_tile;
package com.mapbox.pb;
option optimize_for = LITE_RUNTIME;
message Tile {// GeomType is described in section 4.3.4 of the specification
enum GeomType {
UNKNOWN = 0;
POINT = 1;
LINESTRING = 2;
POLYGON = 3;
}// Variant type encoding// The use of values is described in section 4.1 of the specification
message Value {// Exactly one of these values must be present in a valid message
optional string string_value = 1;
optional float float_value = 2;
optional double double_value = 3;
optional int64 int_value = 4;
optional uint64 uint_value = 5;
optional sint64 sint_value = 6;
optional bool bool_value = 7;
extensions 8 to max;
}// Features are described in section 4.2 of the specification
message Feature {
optional uint64 id = 1[ default = 0];
// Tags of this feature are encoded as repeated pairs of// integers.// A detailed description of tags is located in sections// 4.2 and 4.4 of the specification
repeated uint32 tags = 2[ packed = true];
// The type of geometry stored in this feature.
optional GeomType type = 3[ default = UNKNOWN ];
// Contains a stream of commands and parameters (vertices).// A detailed description on geometry encoding is located in// section 4.3 of the specification.
repeated uint32 geometry = 4[ packed = true];
}// Layers are described in section 4.1 of the specification
message Layer {// Any compliant implementation must first read the version// number encoded in this message and choose the correct// implementation for this version number before proceeding to// decode other parts of this message.
required uint32 version = 15[ default = 1];
required string name = 1;
// The actual features in this tile.
repeated Feature features = 2;
// Dictionary encoding for keys
repeated string keys = 3;
// Dictionary encoding for values
repeated Value values = 4;
// Although this is an "optional" field it is required by the specification.// See https://github.com/mapbox/vector-tile-spec/issues/47
optional uint32 extent = 5[ default = 4096];
extensions 16 to max;
}
repeated Layer layers = 3;
extensions 16 to 8191;
}
Decode the vector tile
Because the binary files that contain vector tiles are intended to be consumed by map applications, humans are not expected to read those files. However, you might want to inspect the data that the tile contains, for example, for testing or troubleshooting purposes. Therefore, you can use the protobuf schema that you obtained to decode the vector tile into a format that is more readable than the binary format.
Note
The following example uses protoc, which is a command line tool for decoding protobuf-encoded data. For the installation instructions and the full list of available commands, see the protoc documentation.
Save the payload from the response to your proto/{name} request as a .proto file.
Open a command prompt window.
At the command prompt, navigate to the directory that contains the following items:
Vector tile data in the .mvt format
Protobuf schema to decode the tile
At the command prompt, use the protoc tool to decode the tile by entering the following command:
com.mapbox.pb.Tile is a fully qualified top-level message of the OMV or MVT type, as defined in the protobuf schema
vector_tile.proto is the name of the file that contains the schema for decoding the tile
response.mvt is the protobuf-encoded binary file that contains the vector tile data
output.txt is the file to store the decoded data
Result: The decoded data is available for you to view in the output.txt file.
The decoded file is a series of key and value pairs (similar to the JSON format) that represents the geometry information for polygons, points, and lines within the vector tile boundaries, and the associated metadata.
Visualize the tile data
To inspect the visual extent of a vector tile, you can convert the binary .mvt file into a .geojson file, and then place the tile data as a layer on a map.
Convert the binary .mvt file that you obtained earlier to the .geojson format by using the converter tool of your choice.