SBG Systems - Qinertia Cloud REST API (1.0 - BETA)

Download OpenAPI specification:Download

Introduction

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.

API Description

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.

HTTP methods

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.

HTTP status codes

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.

Status Code Description
200 OK Indicates that request has succeeded.
400 Bad Request The request could not be understood by the server due to incorrect syntax.
401 Unauthorized The request requires user authentication information.
403 Forbidden The client does not have access rights to the content. Unlike 401, the client’s identity is known to the server.
404 Not Found The server can not find the requested resource.
409 Conflict Unable to comply due to a conflict with the current state of the target resource.
422 Unprocessable Entity The client has provided invalid input parameters.
500 Internal Server Error The server encountered an unexpected condition which prevented it from fulfilling the request.

200 (OK)

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 (Bad Request)

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.

401 (Unauthorized)

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.

403 (Forbidden)

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.

404 (Not Found)

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.

409 (Conflict)

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.

422 (Unprocessable Entity)

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 (Internal Server Error)

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.

Getting started guide

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.

Authentication

AuthToken

To consume Qinertia Cloud public API, you need to create an API key on My SBG.

Requests must be made using a temporary access token. Which is generated after after completing an API key OpenID authentication.

All authentication details and a curl request will be provided to you after creating an API key or regenerating its secret.

Projects

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.

List projects

List all Qinertia Cloud API projects for a specific organization.

Authorizations:
AuthToken (qinertia-cloud:user)
path Parameters
organizationId
required
string <uuid>
Example: 6720f040-7dbc-40c4-be32-1bead64e5515

Organziation ID

Responses

Request samples

# URL request example using curl tool
# with all mandatory and optional path parameters

curl --location --request GET 'https://qinertia-api.sbg-systems.com/api/v1/organizations/40bfe492-5a81-4050-9086-d8880080ecc1/projects'

Response samples

Content type
application/json
[
]

Create project

Create a new empty Qinertia Cloud API project in an organization.

Authorizations:
AuthToken (qinertia-cloud:user)
path Parameters
organizationId
required
string <uuid>
Example: 6720f040-7dbc-40c4-be32-1bead64e5515

Organziation ID

Request Body schema: application/json

This body is used to create a project.

region
required
string (projectRegion)
Enum: "eu-west-3" "us-west-1" "ap-northeast-1" "ap-southeast-2"

Region where your processing files are stored.

Array of objects (metadataList)

List of metadata.

Responses

Request samples

Content type
application/json
{
}

Response samples

Content type
application/json
{