Search for content

Protobuf format

Protocol Buffers (Protobuf), originally developed by Google, is a free and open-source cross-platform data format used to serialize structured data (see here).

It is useful in developing applications that communicate with each other over a network or for storing data. 

The method is based on: 

  • An interface description language that describes the data structure (called message), defined in a proto definition file (.proto).

  • An application (protoc) used for:

    • generating a stream of bytes starting from the .proto description

    • parsing a stream of bytes to generate a .proto definition file

Example

You have:

  • a file your.proto, stored into your directory ./protos/

  • principal message: YourMessage

  • binary file: response.protobuf
     

The command to get the de-serialized content form the response.protobuf is:

protoc --decode=YourMessage \--proto_path=./protos \ your.proto < response.protobuf

 

dataprv_traffic_realtime.proto

The protobuf binary files can be handled with the dataprv_traffic_realtime.proto file shown below (see also API Reference>Schemas>ForecastDataMessageProto): 

syntax = "proto3";

import "google/protobuf/timestamp.proto";

package com.ptvgroup.archimedes.dataprv.protobuf.traffic.realtime.output.v1;<br>

option java_package = "com.ptvgroup.archimedes.dataprv.protobuf.traffic.realtime.output.v1";
option java_outer_classname = "DataprvTrafficRealtimeData";
option java_multiple_files = false;

option csharp_namespace = "PTVGroup.Flows.Protos.DataPrv.Traffic.Realtime.Output.V1";

message DataprvTrafficRealtimeDataProto {
  string timezone = 1;
  google.protobuf.Timestamp snapshot_date_time = 2;
  repeated StreetTraffic street_traffic = 3;

  message StreetTraffic {
    reserved 4;

    int32 id = 1;
    int32 from_node_id = 2;
    double speed_kmh = 3;
    int32 probe_count = 5;  // reserved for internal purposes and not reliable.
    string olr_code = 6;
  }
}

 

How to decode a response in protobuf format

The command to be used is based on these elements:

  • protoc-3.15.8-win64\bin\protoc.exe: It is the version of the protoc command
  • com.ptvgroup.archimedes.api.protobuf.network.v1: It is the package path associated to the .proto file definition
  • dataprv_traffic_realtime.proto: It is the .proto file shown above
  • response: It is the API endpoint response in protobuf (binary) format
  • response.json: It is the decoded JSON file, containing the response in readable format

The complete command is:

protoc-3.15.8-win64\bin\protoc.exe --decode=com.ptvgroup.archimedes.api.protobuf.network.v1.Network dataprv_traffic_realtime.proto < response > response.json