Data Extraction APIs

Introduction

This section explains how to extract data from the Gear Studio platform using the HTTP API, such as:

• Alerts: the API allows extracting the definition of all alerts created in the platform, filtering them in different ways.
• Alarms: the API allows extracting all alarms recorded in the platform, historically, filtering them in different ways.
• Endpoint data: the API allows extracting all information associated with endpoints, historically, filtering it in different ways.
• Geozones: the API allows extracting the list of geozones configured for each client, including the list of vehicles contained within them.

Getting Started

Creating an access token

As with any other HTTP integration, it is necessary to create an access token. This page contains more information about managing access tokens. Access tokens allow controlling the access and permissions used for any operation.

Authentication using an access token

In all APIs, the access token can be sent as part of the header, using an Authorization header, as shown below:

Authorization: Bearer {accessToken}

Alternatively, when it is not possible to send the token through the Authorization header, the access token can be sent as part of the URL, through the "accessToken" parameter, as in the following example:

https://gear.cloud.studio/api/v2/alarms?accessToken={accessToken}&clientID=4&maxCount=10

API Execution

To execute the API, review each of the following sections, which contain the related information:

• Extracting alerts.
• Extracting alarms.
• Extracting endpoint data.
• Extracting geozone data.

Reversibility

• The Data Extraction API (/api/v2: alerts, alarms, endpoint data, geozones and the instance map) is read-only. No call changes data on the platform.
• The only documented write is creating persistent access tokens (CreateClientAccessTokenAllIntegrations). It is undone with DeleteClientAccessToken, using the ClientAccessTokenID returned when the token was created, and the token is revoked immediately.
• Retrying the creation with the same Description does not create a second token: it returns a duplicate-description error.
• Revoking a token deletes no data. It only stops granting access.

Errors

When a call fails, the API responds with HTTP status code 500 and a JSON body in this format, whatever the cause of the error (invalid token, missing permission or invalid parameter):

{
    "Exception": {
        "ClassName": "ServiceException",
        "FaultCode": "8001",
        "FaultData": "",
        "Message": "Description of the error"
    }
}

• FaultCode: numeric error code. It is stable across versions and is the field an integration should use to decide what to do.
• Message: human-readable description of the error. Its wording may change and it is returned translated, so integrations should not rely on its text.
• FaultData: additional error data. It is usually empty.

The most common codes are:

Errors 8000, 8001, 8002, 8004, 100000 and 100004 are not solved by retrying the same call: fix the request or the token first.