Qinertia Cloud API is a professional and highly accurate GNSS/INS post processing solution.

Qinertia is able to post-process RAW GNSS data to deliver centimeter-level positions. Several GNSS post processing modes are available such as single base station, Virtual Base Stations (VBS) and world wide Precise Point Positioning (PPP).

Qinertia is also capable of post processing IMU data to produce highly accurate and reliable position, velocity and attitude data even in harsh GNSS conditions. The solution is able to process SBG Systems INS as well as any GNSS receiver or third party IMU.

Qinertia Cloud API is an ideal solution to create complex but automated post processing workflows such as Lidar point cloud generation, photogrammetry geo-tagging and large survey jobs.

Qinertia Cloud API is accessed using a simple REST API and standard Qinertia CLI JSON processing files.

To use Qinertia Cloud API, you need a MySBG account, be an organization administrator with available processing credits.

The REST API is used to:

• create/view/delete projects
• get Amazon S3 links to upload data
• list/start/cancel/monitor processing
• monitor processing progress using webhooks
• download generated exports/reports from S3

To ease integration with other services, most endpoints offer an optional metadata dictionary to store user defined data.

This API implements standard REST API HTTP methods as detailed below:

• The GET method is used to retrieve a representation of a resource. If successful, GET returns a representation in JSON and an HTTP response code of 200 (OK). In an error case, it most often returns a 404 (NOT FOUND) or 400 (BAD REQUEST). The GET method never modify any resource or state on the server.
• The POST method is used to create a new resource and/or to execute actions. On successful update or action, a HTTP status code 200 (OK) is returned with a JSON body detailing the operation status. In case of error the corresponding HTTP status code is returned such as 400 (Bad Request).
• The PATCH method is used to update an existing resource. On successful update or action, a HTTP status code 200 (OK) is returned with a JSON body detailing the operation status. In case of error the corresponding HTTP status code is returned such as 400 (Bad Request).
• The DEL method is used to delete an existing resource.

This API uses standard HTTP status codes to report either a success or a failure. A success is only reported by the status code 200 and the response body always contains the requested resource or the result of an action using JSON.

All other status codes are used to report an error and the response body always contains a JSON detailing the error.

The table below list all HTTP response status codes used by the API.

It indicates that the REST API successfully carried out whatever action the client requested.

The 200 response includes always a response body. The information returned with the response is dependent on the method used in the request, for example:

• GET an entity corresponding to the requested resource is sent in the response;
• POST/PATCH/DEL an entity describing or containing the result of the action;

400 is the generic client-side error status, used when no other 4xx error code is appropriate. Errors can be like malformed request syntax, invalid request message format, or deceptive request routing etc.

The client SHOULD NOT repeat the request without modifications.

A 401 error response indicates that the client tried to operate on a protected resource without providing the proper authorization. The Authorization header is missing, doesn't start with "Bearer ", the access token is invalid or expired. More details will be provided to you in the response.

The client MAY repeat the request with a suitable authorization token in the HTTP header.

A 403 error response indicates that the client’s request is formed correctly, but the REST API refuses to honor it, i.e., the user does not have the necessary permissions for the resource. A 403 response is not a case of an invalid access token; that would be 401 (“Unauthorized”).

Authentication will not help, and the request SHOULD NOT be repeated. Unlike a 401 Unauthorized response, authenticating will make no difference.

The 404 error status code indicates that the REST API can’t map the client’s URI to a resource but may be available in the future. Subsequent requests by the client are permissible.

No indication is given of whether the condition is temporary or permanent. This status code is commonly used when the server does not wish to reveal exactly why the request has been refused, or when no other response is applicable.

A 409 status code indicates that the request is in conflict with the current state of the target resource. However, the user might be able to resolve the conflict and resubmmit the request.

This status code is returned when the requested resource is not in the expected state, or the result of processing the request would create a conflict within the resource.

Example: A user would like to start a processing on a project that already has an ongoing processing.

The 422 response status code indicates that the server understands the content type of the request entity, and the syntax of the request entity is correct, but it was unable to process the contained instructions. It's probably due to invalid input parameters such as in invalid enum value.

The client SHOULD NOT repeat the request without modifications.

500 is the generic REST API error response. Most web frameworks automatically respond with this response status code whenever they execute some request handler code that raises an exception.

A 500 error is never the client’s fault, and therefore, it is reasonable for the client to retry the same request that triggered this response and hope to get a different response.

The API response is the generic error message, given when an unexpected condition was encountered and no more specific message is suitable.

This API has been designed to be as easy to use as possible and a dedicated GitHub repository contains code samples.

You should also read the online Qinertia Documentation and other SBG Systems Support Center resources.

Please also visit MySBG to create/manage your account and monitor/buy online prepaid credits.

The projects endpoints are used to create and manage processing projects.

You can create a new processing project, update, delete or even archive it.
At any time, you can list your organization's projects and get a specific project information.

Once a project is created, you can request Amazon S3 URLs to upload (POST) data to process (GNSS, IMU, etc) and resources (Export profiles, Report templates, etc).

Finally, when a project has been successfully processed, you can request the list of files that have been generated to download them.

These endpoints are used to manage processing jobs on a project.

Qinertia Cloud API lets you process several times the same project if needed.
It can be helpful if you would like to change some processing settings without re-uploading the dataset.

Once you have created a project, you should start a processing and provide the JSON processing settings file. At any time, you can check a processing status/progress and easily list any error that may have occurred.

However, SBG Systems recommends using webhooks to monitor processing progress/status rather than continuously polling the processing information.

Register webhooks to be notified when a processing status or progress is updated.

Qinertia Cloud API relies on webhooks to easily notify another service when a processing status changes.
A webhook is simply an external URL that is called by SBG Systems cloud services to notify an event.

For example, you can register a webhook to issue a POST request on your service when a processing is completed.

Notifications Service

The webhook API is provided by a dedicated SBG Systems notification service and not directly by Qinertia Cloud API service. The webhook endpoints should be issued on https://notification-api.sbg-systems.com/api/v1 domain.

Webhooks scope

Webhooks are registered for an organization. If you have several ongoing processings, the webhook will be triggered for each processing status/progress updated.
You should check the received payload to identify which processing/project has issued the event.

HTTP endpoint (url)

Before you can install a webhook, you should create, on your service, a dedicated endpoint (URL) that accepts POST requests.

1. Identify the events you want to monitor
2. Create an endpoint on your server, it must accept POST requests
3. Make sure it is accessible from the outside
4. Create the webhook endpoint

Your endpoint must respond a 2XX status code within 5 seconds to be considered valid. You should respond before executing business logic to avoid a webhook timeout and retry.

Retry policy

If your endpoint was unavailable (connection timeout, invalid status code...) when the webhook was sent, it will be resent later.

The notification service will try, up to 10 times, to resend the missed event with an exponential backoff. These 10 attempts will take place over approximately 3 days. After that, the endpoint will be considered as defective and will be automatically disabled.

You can fetch the missed webhooks using this endpoint.

Secure webhooks (optional):

You can secure webhook calls and make sure the POST request has been issued by SBG Systems service.

In the webhook's HTTP request you will find 2 headers:

• Sbg-Timestamp
• Sbg-Signature

The timestamp is when the webhook has been sent. Make sure it is not too old and consistent with your server time.

The signature is generated using the Hash-based message authentication code (HMAC) protocol. You should compute a HMAC hash and compare it to the Sbg-Signature one to confirm POST request authenticity.

The HMAC is computed using the POST request timestamp and raw content body: HMAC(Sbg-Timestamp + "." + body)
The HMAC secret has been generated during the webhook endpoint creation and a sha256 algorithm is used.

Please find below a JavaScript code snippet to implement the HMAC computation:

  const signature = crypto
    .createHmac('sha256', secret)
    .update(timestamp + '.' + rawBody, 'utf8')
    .digest('hex')

Qinertia Cloud API uses Amazon S3 services to store input and output data.

The user should upload the data to Amazon S3 before starting a processing job. The processing results and log files will also be stored on Amazon S3.

Uploading files is done in two steps:

• request URLs from Qinertia Cloud API to POST file content to
• then POST content to Amazon S3 with these URLs

Downloading results and logs is straightforward:

• request Qinertia Cloud API an array of all generated files
• download each file using the returned URLs