Service to Service Mode Step-by-Step Guide
Introduction
Service-to-Service access allows to access to the service requesting the location estimation directly from your application platform instead of from your devices. This approach is preferred, for example, whenever you need the position information directly on server side and not in the device, or when your fleet does not have access to the public internet and cannot reach directly the service end-points.
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
-
Create a CloudLocate S2S Thing, just one for all your fleet
-
Select the preferred pricing plan or the developer plan
-
Get the credentials (username and password) for REST API access from the Thing details
-
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
-
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"
}
Self Reporting API
Thingstream provides a rich Customer API to allow you to carry out the majority of functions that can be done in the portal in addition to providing the ability to Report Usage on your S2S devices.
Still need help?
CloudLocate getting started guide
If you need more help or have any questions, please send an email to services-support@u-blox.com