CloudLocate Service-to-Service access using REST API

Prerequisites

To use the service you need

•  at least one of the  following  hardware: 

  • a u-blox GNSS receiver (generation M8 or M9 or M10) and/or

  • a Wi-Fi  module and/or (u-blox or third-party)  and/or

  • a Cellular module  (u-blox or third-party)

• the access to Thingstream service delivery platform

• the knowledge and tools about how to send an API request

Procedure overview

The mains steps of this procedure are

1. Create a CloudLocate S2S Thing, just one for all your fleet

2. Select the preferred pricing plan or the developer plan

3. Get the credentials (username and password) for REST API access from the Thing details

4. Setup your application platform to receive the RAW measurements from the device, used for location estimation. You can send the RAW measurement from the device to your cloud application platform using your preferred protocol and format

5. Send the RAW measurements  in the JSON specified format using the API and get the location back

Here below an extensive explanation for each step

Create a CloudLocate S2S Thing

The first step is to create a CloudLocate S2S things that provides you all the required parameters for the API:

• username and password

• service endpoint

The Thing let also you to:

• modify the pricing plan

• deactivate/ reactivate the access

• monitor the usage of the service

• and look at the the events

Sign-in into the Thingstream portal and select the Location Things item from the Location Services section. Click the button to create a new Location Thing and browse to the CloudLocate section from where you can select the wizard to create CloudLocate S2S Thing.  

During the creation steps you are suggested to assign a price plan. If you skip this step the Thing will not be automatically activated and cannot be used. When you are ready to assign a plan, open the Thing panel and assign the preferred one.

Note: the service endpoint and the credentials for the REST API are specified in the details panel of the just created CloudLocate S2S thing.

Send a measurement and get a position

The service supports a JSON formatted request containing information of GNSS raw data, and/or cellular tower scan and/or Wi-Fi measurements. The format of the request is mentioned in API specification document available at https://clapi.services.u-blox.com/.

The Getting Started Guide has provided the instructions about how to generate the service payload.  Once you have received the JSON payload on your cloud application server, to obtain a position you shall send the API

https://{endpoint}/v1/unipos/s2s/location/get 

specifying:

• the endpoint 

• username and password 

and appending the JSON payload as body of the request.

Both can be retrieved in the credential section of your just created CloudLocate S2S thing as shown in the following picture. As initial test it is suggested to use the sample payload provided in the Getting Started guide and verify that you can receive a resposnse with the estimated position. For  very initial test purpose it is also suggested:

•  to  try with the smaller service payload containing only one data type

• to invalidate one source of the complete payload, by adding for example strange characters to the data and check the behaviour and how changes the LocationSource paramenter

Remind to set:

• 'basic authentication' as authentication scheme

• 'application/json' as API content type

Sample API response

A succesfull location response provides the position estimation as long as the date and time of the request, a copy of the RequestId if provided in input, and a LocationSource that indicates which source (Cellular, Wi-Fi or GNSS) have been used for the provided estimation.

{

    "Location": {

        "Lat": 51.496268,

        "Lon": -0.0949408,

        "Unc68": 27.0

    },

    "DateTime": "2023-09-14T13:02:01",

    "RequestId": "82cb34c9-88c9",

    "LocationSource": "WiFi"

}