Mapmatch documentation

Introduction

The MapMatch service compute the following things based on input from GPS-device-equipped vehicles:

  • exactly what route the vehicle takes
  • based on the current HU-GO BK Terms of Service, what kind of data the BK has to provide

After registering a vehicle to the service, MapMatch accepts GPS points recorded and signed by the vehicle's OBU (track points), and sends relevant data service events through Webhook (ticketing, jump, etc.)

Using MapMatch

To use the MapMatch WebAPI, an API-key and an AppId identifier is required. These must be provided in the 'X-MapMatch-ApiKey' and 'X-MapMatch-AppId' headers of every request.

The complete documentation of the WebApi can be found here: WebApi documentation.

Start tracking

Every vehicle using the MapMatch service needs to register first. Registration is done through the /api/MatchingSession POST HTTP-call. In case of a successful registration, the response will contain the parameters of the registered session. The id field identifies the matching session, this can be used to identify the vehicle, and is the sessionId parameter of later calls.

Sending track points

After registering the vehicle, GPS track points can be sent with the /api/Track POST HTTP-call. Multiple track points can be sent with a single call. Furthermore, the API provides capabilities to send track points of multiple vehicles in a single POST, but we suggest keeping to one vehicle per request for clarity. The maximum number of track points that can be sent with a single POST is 400 per vehicle, but for optimal results we suggest requests with circa 100 points. Not buffering track data on the client's side is a good practice, the more recent a sent data is, the better. The points which received a non-error response at least once are considered correctly recorded points. (see: Error handling). It is important to record every track point correctly at least once. Track points have to follow each other in a chronological order. Time is to be given in UTC UNIX time. The MapMatch server ignores track points further than 15 minutes from its own clock in the future. This restriction is in place to prevent faulty onboard units from corrupting future track logs. Further information regarding the correct use of the API can be found in the Error handling section.

Using Webhooks

After receiving track data, MapMatch records the received points and starts working in the background. To accept vehicle events, the sender must register a Webhook into the MapMatch system. The Webhook must be an API on the client's side which can accept HTTP requests, saves received events and provides the appropriate responses. Webhook documentation can be found here: Webhook documentation

Error handling

In normal cases, sending a track point closes with the 201 HTTP response code, but in some extreme cases, repeating the request is needed. Possible HTTP codes:

  • 202: Not every vehicle's data could be processed. Based on the contents of the response, re-sending is needed.
  • 400: Incorrect request format.
  • 500 or 501: Internal server error. Repeat request after at least 1 minute.

In addition to the HTTP codes 201 and 202, the response contains a code field for every vehicle. Possible values are:

  • 0: no error;
  • 1: temporary error, the vehicle's data can be re-sent immediately;
  • 2 or 3: incorrect or missing sessionId or equipmentId;
  • 4: track point congestion. Needs to be investigated uniquely, please report it to us. We advise to stop sending track data for this vehicle until the error is corrected;
  • 5: the vehicle is in maintenance mode for error correction. Before repeating the request, a waiting time of ~1 minute is advised.