Obtain the protobuf schema to decode vector tiles

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.

• Retrieve the relevant protobuf schema
• Decode the vector tile
• Visualize the tile data
• Next steps

Retrieve the relevant protobuf schema

Retrieve the protobuf schema, which serves as the key for decoding vector tile data from binary into the human-readable form.

1. Get the names of available protobuf schemas by generating a GET request to the proto endpoint. For example:

    curl -X "GET" \
    "https://vector.hereapi.com/v2/vectortiles/proto?apiKey=APIKEY_HERE" \
    -H "accept: application/json"
   

   Result: A successful server response includes the protobuf schema name, as shown in the following example:

    [{"name":"vector_tile.proto", "description":"OMV format"}]
   

2. Retrieve the relevant protobuf schema by generating a GET request to the proto/{name} endpoint, as shown in the following example:

    curl -X "GET" \
    "https://vector.hereapi.com/v2/vectortiles/proto/vector_tile.proto?apiKey=APIKEY_HERE" \
    -H "accept: text/plain"
   

   where:

   • 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.

1. Save the payload from the response to your proto/{name} request as a .proto file.
2. Open a command prompt window.
3. 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
4. At the command prompt, use the protoc tool to decode the tile by entering the following command:

    protoc --decode=com.mapbox.pb.Tile vector_tile.proto < response.mvt >> output.txt
   

   where:
   • 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.

1. Convert the binary .mvt file that you obtained earlier to the .geojson format by using the converter tool of your choice.

   Hint

   For example, you can use the vt2geojson tool.

2. Render the data encoded in the .geojson file on a map. For more information, see Display GeoJSON data.

Result: The following example shows vector tile data in the form of points, polygons, and lines, rendered on a map from a .geojson file:

Next steps

• For more information about requests and responses in the HERE Vector Tile API, see API Reference.
• For more information about how vector data is stored and encoded, see the Vector tile specification.
• For tutorials on how to render maps by using the HERE Vector Tile API, see Examples.
• For the terms and conditions covering this documentation, see the HERE Documentation License.