Contact
Terms of use
MetaTrak for developers
MetaTrak platform provides multiple API tools and resources that enable you to harness the power of MetaTrak platform and telematic data.
Here is described what is possible to get with the different APIs that are available on the platform, and how to access and obtain the information to develop the services and applications.
We regularly update and improve the experience and products available on the platform. These improvements make it important for you to stay informed, so you do not miss any updates.
The base path that the requests are made to has the following format: /{version}/{endpoint} where version is a mandatory part of the path indicating an API version and endpoint is one of the available methods.
Latest MetaTrak API version is 1.7 and need to be passed in URL as /v1_7/ .
The actual response is given by the server in the body section. The formats used are XML or JSON and described for each method. In case of an error, the server returns an error code and corresponding message.
The number of requests per second and total requests quantity are limited on a per company basis. When any of limits is exceeded corresponding error code will be returned.
Custom error codes are used to inform the client about the way the request was processed.
200 OK HTTP code will be returned for successful requests and error code and error message from response body must be handled by client.
401 Unauthorized HTTP code will be returned in case of wrong API user credenitals or expired JWT token usage.
403 Forbidden HTTP code will be returned if API user has no permission to access the requested resource.
Two different Authentication methods are accepted by MetaTrak API. Choosing one or another depends from method and purpose of the API client.
The preferable and most secure way of authentication is JWT tokens.
JWT token can be used instead of the traditional approach of creating a session in the server or using the plain login and password to access the API.
When the user successfully logs in using its credentials using special Authentication endpoint, a JSON Web Token will be returned and must be saved locally (typically in local or session storage, but cookies can also be used).
If the client passes a valid JWT assertion the server will generate an access_token valid for making calls to the application and pass it back to the client:
{"access_token":"eyJhbGci......yu5CSpyHI" ,"expires_in":1800}
When the client wants to access a protected route or resource, the user agent should send the JWT in the Authorization header using the Bearer schema. The content of the header might look like the following:
Authorization: Bearer eyJhbGci......yu5CSpyHI
This is a stateless authentication mechanism as the user state is never saved in server memory. The server's protected routes will check for a valid JWT in the Authorization header, and if it is present, the user will be allowed to access protected resources. As JWTs are self-contained, all the necessary information is there.
An API key is a code used to identify and authenticate an application or user. It can be used instead of administrator's credentials. You can contact your service provider or MetaTrak team to gather an API key.
The information maintained by the MetaTrak system is structured in a hierarchy of objects, as shown in the following figure:
MetaTrak platform manages a number of TSP (TSP – telematic services provider).
TSP is a partner who distributes MetaTrak services or builds own services based on MetaTrak API and MetaTrak platform and provides it to own clients. Besides hierarchy shown on the diagram TSP has some pre-created platform infrastructure like:
Some useful information about TSP and hierarchy can be retrived using References API.
Accounts are objects that group all the information of a TSP's customers. Account can be private or company. Company account can be additionally marked as fleet account. Under Account hierarchy are Contract and Driver.
Contract are probably the most important piece of the MetaTrak system.
Contract contains information about telematic device - on-board-unit (OBU) and about the vehicle where the device is installed. Each contract has a list of attributes (such as contract owner or expiry date). Creation of contract is 1st step to activate the telematic device and start to collect data.
When registered contract starts the billing and get the expiration date. While activated contract with all the functionality is available via API. To manage contracts please refer to Contracts section of API. Here can be found how to register, edit, block and renew the contracts or get contracts data.
Contract Modes are system objects to extend and manage different functionalities of OBU. List of system available modes is described in /contracts/modes method. Modes are divided to system (enabling and disabling automatically to manage some system actions, like OBU FOTA or activation) and user (can be enabled and disabled by user to manage different functions).
Vehicles is entity under the contract and groups all the data related to the vehicle where the telematic device is installed. These data are Trips, Statistics, Crashes, Refuelings, Tracks, Reports, POIs & Geofences and Events.
Trip is data period between ignition on and ignition off event detected by OBU and contains the trip information such as navigation data and driving behavior events. Navigation data includes the position, the speed and the azimuth of the vehicle at specific moments and besides the Trips are also available as part of Track.
Track represent the positions and all the information that is sampled, recorded and transmitted by a vehicle in time and used to recreate the trajectory of a vehicle in a specified interval of time.
Crash data provides information about crash events detected by OBU or manually inserted crash with possibility to reconstruct the accident.
Refueling represents data about refueling imported to the platform and associated to corresponding vehicle or driver. Refuelings are used in fuel efficiency and score calculations.
During the contract lifetime platform accumulates vehicle Statistics. Statistics is a set of data which can be related to dedicated statistics period (which can be multiple) or whole contract's period. Period's statistics is updating during the period's and saved when the period's end while the total statistics always updating while the contract is active.
Point of interest (POI) is a pair of latitude and longitude with a certain tolerance (delta) around this central point. POIs are in fact small rounds used to easily identify and name places on map. Geofence is array of pairs of latitude, longitude and in fact is polygon which define a geographical area. They are used for area-related Reports and geofence Events.
Event is custom condition which must be controlled by the MetaTrak platform. It can be POI & Geofence, Idling, Speeding or Parking events. Each event consists of event threshold (the condition to check) and notification section (how the platform should react on event).
Reports together with Scheduler is platform engine for generation and scheduling of pre-defined reports.
Telematic device or OBU is main data supplier for the contract and has some own functionalities to work with.
OBU generates events that are stored on the server and can be used to tell the behavior of the driver, to identify problems with the vehicle's device or to simply keep an eye on the vehicle.
Anomaly shows the device's deviation from the normal behavior. Platform is handling GPS fix anomalies, trips anomalies, data lack anomalies etc. Anomalies should be managed and analyzed by customer.
Commands are required to talk to device and configure its functions and required behavior.
Driver is the unique system object meaning the person with an access to the vehicle (Contract). Drivers can be created during the Contract registration. There could be added several Drivers for same vehicle (Contract). Drivers can be automatically identified by system via IDTag (physical tag read by telematic unit) or assigned to vehicles manually. A vehicle can be driven by only one driver at a certain moment.
System manage for Drivers similar data as for Contracts: Statistics, Trip, Crash, Refueling.
Postman is a REST client that allows us to make requests to APIs inside of a user interface. This can be helpful when you are working with a new endpoint.
First, you'll need to download Postman.
Then open the MetaTrak API documentation of Contracts management. Find a method GET /contracts in Information section.
Now you can create the request to get the contract information.
Open Postman. You'll see something like this:
Choose "Create a request" option from "Start something new section" and Postman will open the new request tab. Here you'll construct your request.
Firstly, you need to add the API URL – it consists of API Base URL and method's endpoint. Base URL is always written in the top of API documentation page:
So, base URL is api.metatrak.it/v1_7.
Then add the endpoint. Endpoint is specified for each method:
Here the endpoint is /contracts.
So, the target API URL for you will be api.metatrak.it/v1_7/contracts. Go to Postman and write it in the request URL field:
Before you can press the blue "Send" button you need to adjust authentication settings and requests parameters.
Open again the API documentation to check the description of parameters required to execute the request. Parameters are divided into mandatory, conditionally mandatory and optional. Mandatory parameters are written in bold and marked with asterisk symbol. Conditionally mandatory parameters usually depend on each other and description always state how to use it:
In the example above must be used any of stated parameters to execute request.
Optional parameters usually required to extend API functionality like manage response or use pagination.
So, checking the documentation you'll see that mandatory parameters for /contracts are login and password.
Add them to Postman and specify the values as your real API credentials.
As optional parameter let's choose contractid to specify the contract which data we want to get and datablocks to regulate the data sections in the response. Let's request general contract information, vehicle information, country and language information and telematic device details.
Finally, Postman parameters will look like:
You can see that the parameters you specified collected by Postman into the request URL. Next time you can add or change it directly there into the URL.
Click blue "Send" button.
Now you should see something that looks like the following XML:
<?xml version="1.0" encoding="utf-8"?>
<root>
<errorcode>0</errorcode>
<message>OK</message>
<contracts>
<contract>
<accountid>63917</accountid>
<contractid>150507</contractid>
<imei>11223344444</imei>
<common>
<contractid>150507</contractid>
<externalcontractid />
<operator>Meta System SPA</operator>
<agentgroup />
<agent />
<product>Demo_product</product>
<rate>Demo Tracker Rate</rate>
</common>
<vehicle>
<cartype />
<carvendor />
<carmodel />
<carmodelversion></carmodelversion>
<regcode></regcode>
<vin></vin>
<productionyear></productionyear>
<startingmileage></startingmileage>
<color />
</vehicle>
<localization>
<language>UnitedStatesEnglish</language>
<country />
<city />
</localization>
<device>
<boxpartno>Meta T30 (MS_ABT06280)</boxpartno>
<name>ET268KX</name>
<imei>11223344444</imei>
<serialnumber>11223344444</serialnumber>
<obutype>META Super GPB</obutype>
<authkey />
</device>
</contract>
</contracts>
</root>
You've now made your first request. Congratulations!
To make your next request, check MetaTrak API documentation portal to learn more about MetaTrak API functionality.
What's next?
If you click on the button in Postman that says "Code", you can turn the request we just created into the language of your choosing such as Python, Node or Ruby to help you get started. Postman has great documentation that might be helpful.