Asset Tracking GRPC Streaming API (Python) Follow

This version of the Tag Tracker was released recently. This guide will help you getting started using the new API. This document uses Python, but there is a Go Example as well.

1. Download the track.proto file attached to this doc. This will give you our model definitions and allow you to generate models and gRPC calls in your language of choice.
2. track.proto imports some common Google protobufs, so you'll need to clone the grpc-gateway repo and make sure it's in your import path. You may also need to install the Python modules gcloud, google-api-python-client, grpcio and protobuf; this is typically done via Pip or another package manager.
3. Follow the Python Quick Start Guide to get gPRC running in a virtual environment on your machine. For example, you'll need to run something similar to the following script:

   python -m grpc_tools.protoc -I. -I$(GOPATH)/src/github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis --python_out=./output --grpc_python_out=./output track.proto

   You should now see the generated files track_pb2.py and track_pb2_grpc.py in your output folder. These are required for the "import track_pb2" and "import track_pb2_grpc" lines in the examples below.
4. Create an Application Token for the Meridian Location you want to access.
5. Select the correct hostname for your region:
   Europe: tags-eu-direct.meridianapps.com
   All others: tags-direct.meridianapps.com
6. Now, let's look at an example on how to grab all assets in a single pull:

   import logging
   import grpc
   import track_pb2
   import track_pb2_grpc
   
   def run():
       location_id = "<your Meridian Location ID>"
       token = "<your Meridian Application Token>"
       host = "<your selected hostname from step 4>"
       port = 50051
   
       # Authenticate with the token
       credentials = grpc.ssl_channel_credentials(root_certificates=None)
       token_auth = grpc.metadata_call_credentials(
           lambda context, callback: callback((("authorization", 'Token ' + token),), None))
       credentials = grpc.composite_channel_credentials(credentials, token_auth)
   
       # Connect to the Channel
       channel = grpc.secure_channel('{}:{}'.format(host, port), credentials)
       stub = track_pb2_grpc.TrackingStub(channel)
       
       # Build the request and get all the asset tags
       request = track_pb2.AllAssetRequest(location_id=location_id)
       response = stub.GetAllAssets(request)
   
   if __name__ == '__main__':
       logging.basicConfig()
       run()

7. Now let's look at an example on how to dial up to an ongoing tracking stream:

   from __future__ import print_function
   import logging
   
   import grpc
   
   import track_pb2
   import track_pb2_grpc
   
   def run():
   
       # Authentication details
       location_id = "your location id"
       token = "your access token"
       host = "your host choice from step 4"
       port = 50051
   
       # Authenticate with the cert and token
       credentials = grpc.ssl_channel_credentials(root_certificates=None)
       token_auth = grpc.metadata_call_credentials(
           lambda context, callback: callback((("authorization", 'Token ' + token),), None))
       credentials = grpc.composite_channel_credentials(credentials, token_auth)
   
       # Connect
       with grpc.secure_channel('{}:{}'.format(host, port), credentials) as channel:
           stub = track_pb2_grpc.TrackingStub(channel)
   
           # Define what type of response you want
           request_type = track_pb2.AssetRequest(
               resource_type = track_pb2.AssetRequest.LOCATION,
               location_id = location_id
           )
   
           # Start streaming
           request = track_pb2.AssetRequestList(asset_requests=[request_type])
           for response in stub.TrackAssets(request):
               print(response)
   
   if __name__ == '__main__':
       logging.basicConfig()
       run()

8. To track a single tag, use the code from step 7 with this request_type instead:

   request_type = track_pb2.AssetRequest(
       resource_type = track_pb2.AssetRequest.TAG,
       location_id = location_id,
       resource_ids = ["your MAC address"]
   )

9. For more specifics on how to scope requests, or how to subscribe, consult the attached protobuf, track.proto. 

Note: Unlike the previous tag-tracking, we now handle all subscriptions in our first request, meaning there are no subsequent changes to be made to a running stream. If you would like to unsubscribe to a certain floor, location, etc, you will want to disconnect and send a new request.

To see the JSON output of these APIs, or further details on the REST endpoint, visit our Tag Tracker sandbox: https://tags.meridianapps.com/docs/track

The previous version of the proto file, track_legacy.proto, did not include latitude and longitude values and is included here purely for historical reasons.