#Backend functionality

#Introduction

Welcome to the Mertrack API documentation. This guide is designed to help developers integrate third-party
solutions with the Mertrack platform. Here, you will find comprehensive information on API calls, workflows, and best practices.

#Overview

The Mertrack API provides a set of RESTful endpoints that allow you to interact with various entities such as geofences, rules, objects, and more. The API calls for CRUD and other operations with these entities follow a consistent naming convention, making it easier to understand and use.

#Standard Workflow

To give you a clear idea of how to work with the Mertrack API, let's go through a standard workflow using a common example – requesting track points data.

1. Determine the URL to API calls:

   • The base URL for every API call is https://api.mergroup.be.

2. Obtain hash of an API key:

   • Authenticate and obtain a user key via the authentication call.

3. Get objects lists with tracker/list:

   • Example API call:

   Copy

   $ curl -X POST 'https://api.mergroup.be/tracker/list' \
       -H 'Content-Type: application/json' \
       -d '{
             "hash": "your_api_key_hash"
           }'

4. Get track lists with track/list:

   • Example API call:

   Copy

   $ curl -X POST 'https://api.mergroup.be/track/list' \
       -H 'Content-Type: application/json' \
       -d '{
             "hash": "your_api_key_hash",
             "tracker_id": 12345
           }'

5. Get the track itself with track/read:

   • Example API call:

   Copy

   $ curl -X POST 'https://api.mergroup.be/track/read' \
       -H 'Content-Type: application/json' \
       -d '{
             "hash": "your_api_key_hash",
             "track_id": 67890
           }'

#API Base URL

All API calls share a single base URL:

• Mertrack platform: https://api.mergroup.be

For example, a user/auth call is made against https://api.mergroup.be/user/auth.

#API Calls Format

API calls follow a consistent notation:
/resource/sub_resource/action(parameter1, parameter2, [parameter3])

Parameters can be passed in different ways:

• HTTP POST application/json: Recommended
• HTTP POST application/x-www-form-urlencoded: Parameters in the request body
• HTTP GET: Not recommended, should be used only for idempotent requests with small parameter size

#Examples

HTTP POST application/json

$ curl -X POST 'https://api.mergroup.be/resource/sub_resource/action' \
    -H 'Content-Type: application/json' \
    -d '{"param1": "value1", "hash": "a6aa75587e5c59c32d347da438505fc3"}'

HTTP POST application/x-www-form-urlencoded

$ curl -X POST 'https://api.mergroup.be/resource/sub_resource/action' \
    -d 'param1=value' \
    -d 'hash=a6aa75587e5c59c32d347da438505fc3'

HTTP GET

$ curl 'https://api.mergroup.be/resource/sub_resource/action?param1=value1&hash=a6aa75587e5c59c32d347da438505fc3'

#Request and Response Format

To make an API call, send a POST request to:https://api.mergroup.be/resource/action/

The response will be given with application/json content type, even for errors. Response fields and object structure are specific to the API call.

#Ensuring Compatibility

Our API evolves over time, and new methods and JSON object fields are added. We strive to maintain backward compatibility with legacy API clients. However, you must ensure that any unsupported JSON object fields by your app are ignored, and that your application can handle new JSON fields without breaking. Also, to reduce response size, JSON fields that are NULL are omitted. Your JSON parser should handle missing JSON fields as if they were NULL.

#Authorization and Access Levels

Unless otherwise noted, every API call requires a valid API Key hash. This hash can be passed in one of the following ways:

1. As a hash parameter of the request body (root-level property for application/json).

2. As a hash parameter of the HTTP query string.

3. As a value of the HTTP header Authorization in the following form:

   Copy

   Authorization: NVX SessionHashValue

#Data Types

#String Validation Rules

This validation ensures that the provided string adheres to specific content rules. The rules may vary depending on the particular field being validated. The string is checked for the following criteria:

• Empty strings or null values: may be allowed or restricted depending on the specific field.
• Character types:
  • Regular spaces are always allowed (Unicode category "Zs").
  • Other whitespace characters (tabs, line breaks, etc.): may be allowed or restricted depending on the specific field.
  • Control characters (category "Cc" except whitespace characters): not allowed.
  • Private Use characters (category "Co"): not allowed.
  • Surrogate characters (category "Cs"): not allowed.
  • Characters requiring more than 3 bytes in UTF-8 encoding (e.g., some emojis): may be allowed or restricted depending on the specific field.
  • All other characters are allowed.
• Strings consisting entirely of whitespace may be considered invalid for some fields.

#Date/Time Formats

Date/time type can be represented with the following formats:

• yyyy-MM-dd HH:mm:ss format (in user's timezone), default
• [ISO 8601] yyyy-MM-dd'T'HH:mm:ssZZ

To use ISO 8601 date/time format, pass true to:

1. iso_datetime parameter of the request body (root-level property for application/json).
2. iso_datetime parameter of the HTTP query string.
3. HTTP header NVX-ISO-DateTime.

#Example

JSON request body parameter

$ curl -X POST 'https://api.mergroup.be/resource/sub_resource/action' \
    -H 'Content-Type: application/json' \
    -d '{"iso_datetime": true, "hash": "a6aa75587e5c59c32d347da438505fc3"}'

Form request parameter

$ curl -X POST 'https://api.mergroup.be/resource/sub_resource/action' \
    -d 'iso_datetime=true' \
    -d 'hash=a6aa75587e5c59c32d347da438505fc3'

HTTP Header

$ curl -X POST 'https://api.mergroup.be/resource/sub_resource/action' \
    -H 'Content-Type: application/json' \
    -H 'NVX-ISO-DateTime: true' \
    -d '{"hash": "a6aa75587e5c59c32d347da438505fc3"}'

#Response Example with Fixed Offset Date/Time

{
  "success": true,
  "user_time": "2014-07-09T07:50:58+05:00",
  "list": [
    {
      "type": "odometer",
      "value": 100500.1,
      "update_time": "2014-03-06T13:57:00+05:00"
    }
  ]
}

#Response Example with UTC Date/Time

{
  "success": true,
  "user_time": "2014-07-09T02:50:58Z",
  "list": [
    {
      "type": "odometer",
      "value": 100500.1,
      "update_time": "2014-03-06T17:57:00Z"
    }
  ]
}

#Next Steps

• Authentication: Learn how to authenticate and obtain a user key
• Errors: Understand how to handle errors in the Mertrack API