1 | 13

Cloud API documentation

Version 1.4.2, 2023-01-17

1. Introduction

This document is intended to give instructions on how to operate the Govecs GOLD scooter
connector solution based on top of the PrimingCloud platform.

PrimingCloud GmbH – Govecs GOLD solution

 2 | 13

3. API

The base URL for all API calls is:

Demo/Test environment:
https://demo.primingcloud.com/data/integration/Govecs/Scooter/

Production environment:
https://prod.osapiens.cloud/data/integration/Govecs/Scooter/

A postman collection is available at:

https://bitbucket.org/franciscotvsmotor/primingcloud_api/src/master/
This collection contains all the API calls.

PrimingCloud GmbH – Govecs GOLD solution

 3 | 13

Authorization:
Authorization is required, in order to send requests to the API. This has to be done via Basic
authentication, by specifying a username in the format “on.Govecs.<yourname>” and the
password for your tenant given to you.

This authorization can be maintained in a Postman environment:

username/password: Specified the credentials for the tenant (=OU) in the cloud. The
username consists of a prefix on which means that the OU Name should be used to identify
the tenant. “Govecs” is the Priming Cloud Customer in the cloud. “test-Govecs” is the name
of the Govecs tenant (also named OU or Organizational unit). The password is the
password of the OU.
One of the other fields like name/IMEI/VIN/license plate specify should be used to identify a
scooter.

a. API – Tenant-specific calls

Tenant-specific calls are made for the entire tenant. No specific scooter is addressed with
such calls.

PrimingCloud GmbH – Govecs GOLD solution

 4 | 13

API endpoints:

• Poll event queue “/pollEvents”:

Polls the event queue for the entire tenant. Currently, possible events are towing,
malfunction and crash events.
◦ URL parameters:
▪ ackId – Takes the ackID of the last response to acknowledge the previous
receival.

• Lock topcase “/queryStatusUpdates”:

Queries status updates for all scooters of the tenant. The oldest updates newer than
the specified "lastTimestamp" are returned. Multiple updates to one scooter are
consolidated into one change record. Initially, the caller should call with
lastTimestamp=0, which will return the earliest entries. Afterwards, the caller should
use the lastTimestamp from the last call. There might be more data pending than is
being returned, as the response size is limited by the limit parameter.
◦ URL parameters:
▪ limit – The max number of entries to be returned by this call
▪ lastTimestamp – The lastTimestamp from the last call. This will be used as a
offset in the queue.

Status updates are transmitted as follows:

• Teltonika Box keeps an open connection with Priming Cloud, over which
updates are contentiously sent.
• PrimingCloud keeps all records up to two years as “readings” and keeps
the latest state of each scooter. The latest state is made available via the
API calls queryStatusUpdates and queryStatus. Multiple scooter updates
are always aggregated into the latest state.
• A rental backend should poll the queryStatusUpdates API to receive
updates for all its scooters. e.g every few seconds. These calls should be
scheduled in some kind of worker thread, that makes the calls
contentiously.
• The rental backend must persist the updates in its database. Every
record received can be treated as the current state of the scooter.

PrimingCloud GmbH – Govecs GOLD solution

 5 | 13

b. API – Scooter specific calls

Scooter-specific calls are made on a per-scooter basis.

In order to address a specific scooter, any of the following API calls will require one of the
following scooter Ids:
• vin – Vehicle identification number
• imei – IMEI number of the Teltonika box
• lic – License plate number (if set for the scooter)
• name – Internal “Thing” name
• id – Internal “Thing” Id

API endpoints:

• Lock scooter “/lock” / Unlock scooter “/unlock”:

Locks or unlocks a scooter and returns the latest scooter state.
◦ Example response of a scooter being locked:

{
"data": {
"ActiveGSMOperator": 26201,
"Angle": 341,
"AxisX": 93,
"AxisY": 0,
"AxisZ": -937,
...
"TotalDistance": 1392,
"Towing": 1,
"TripDistance": 60000,
"VehicleSpeed": 0
},
"dataUpdateSuccess": true,
"lastDataUpdate": 1608482576000,
"scooterLock": {
"isLocked": true,
"wasLocked": false
},
"success": true
}

PrimingCloud GmbH – Govecs GOLD solution

 6 | 13

• Lock topcase “/lockTopcase” / Unlock topcase “/unlockTopcase ”:

Locks or unlocks the top case of a scooter and returns the latest scooter status.
◦ Example response of a top case being locked when it was previously open:

{
"data": {
"ActiveGSMOperator": 26201,
"Angle": 341,
"AxisX": 93,
"AxisY": -15,
...
"TotalDistance": 1392,
"Towing": 1,
"TripDistance": 60000,
"VehicleSpeed": 0
},
"dataUpdateSuccess": true,
"lastDataUpdate": 1608482443000,
"success": true,
"topcaseLock": {
"isLocked": true,
"wasLocked": false
}
}

• Lock Seat “/lockSeat” / Unlock Seat “/unlockSeat ”:

Locks or unlocks the Seat of the vehicle (if supported by the vehicle) and returns the
latest scooter status.
◦ Example response of a seat being locked when it was previously open:

{
"data": {
"ActiveGSMOperator": 26201,
"Angle": 341,
"AxisX": 93,
"AxisY": -15,
...
"TotalDistance": 1392,
"Towing": 1,
"TripDistance": 60000,
"VehicleSpeed": 0
},
"dataUpdateSuccess": true,
"lastDataUpdate": 1608482443000,
"success": true,
“seatLock": {
"success": true,
"wasLocked": false
PrimingCloud GmbH – Govecs GOLD solution
 7 | 13

• Drive Train Command Seat “/DriveTrainCommands”:

Change the status of the vehicle’s drive train (if supported by the vehicle) and returns
the latest scooter status.

Parameters:

one of thefollowing scooter Ids:

• vin – Vehicle identification number
• imei – IMEI number of the Teltonika box
• lic – License plate number (if set for the scooter)
• name – Internal “Thing” name
• id – Internal “Thing” Id
Additional mandatory parameter: CommandID

Different states of the drivetrain (CommandID):

• Drive train state 0 – OFF -Scooter turned OFF
• Drive train state 1 – Passive – Drive train passively turned ON (just the cockpit can be
powered up)
• Drive train state 2 – Actuators active – Actuators can be activated or deactivated in this
state (top case, blinkers, horn, etc.)
• Drive train state 3 – Fully active – With Drive train active state and the unlock
immobilizer command the scooter will request the driver to press the push button and
once the push button is pressed the scooter is ready to drive
• Drive train state 4 – Immobilizer alarm – This is the alarm mode in the Flex 2.0, once
when the scooter enters this state the horn will be activated for 1 sec, the blinkers will
be activated, and the motor will be locked. The scooter can enter this state by sending
a command from the cloud or the Teltonika will push the scooter to this state if any
towing event is noted when the initial state of the scooter is at a locked state.

◦ Example response of a drivetrain being activated when it was previously inactive:

{
"drivetrain": {
"response": "Govecs Drive Train State:3",
"success": true
},
"success": true
}

PrimingCloud GmbH – Govecs GOLD solution

 8 | 13

• Trigger lights on “/triggerLights” / Trigger lights off “/triggerLightsOff”:

Turn on/off the lights of the vehicle (if supported by the vehicle) and return the latest
scooter status.
◦ Example response of lights being turned on when it was previously turned off:

{
"lights": {
"response": "Govecs hazard activated",
"success": true
},
"success": true
}

• Activate vehicle horn on “/triggerHorn”:

Make the scooter horn sound (if supported by the vehicle) and return the latest scooter
status.
◦ Example response of horn being activated:

{
"horn": {
"response": "Govecs horn activated",
"success": true
},
"success": true
}

PrimingCloud GmbH – Govecs GOLD solution

 9 | 13

• Query scooter cloud status “/queryStatus”:

Query the status of a single scooter. By default, this method returns only the status
available in the cloud. If a thresholdSeconds is specified, then also the scooter itself
is queried for updates, if the status in the cloud is older than the specified threshold.
◦ URL parameters:
▪ thresholdSeconds – The number of seconds in which the status in the cloud
can be updated, before the scooter is queried for an update.
◦ Example response:
{
"data": {
"ActiveGSMOperator": 26201,
"Angle": 342,
"AxisX": 93,
"AxisY": 0,
"AxisZ": -937,
...
"TopcaseLocked": false,
"TotalDistance": 1392,
"Towing": 1,
"TripDistance": 60000,
"VehicleSpeed": 0
},
"isOnline": true,
"lastDataUpdate": 1608482154000
}

PrimingCloud GmbH – Govecs GOLD solution

 10 | 13

• Query status updates for all scooters within the tenant “/queryStatusUpdates”:
◦ URL parameters:
▪ limit – Allows specifying a response size limit in number of entries.
Reasonable size would be 500.
▪ lastTimestamp – Caller should specify the lastTimestamp with what it got from
the last call of queryStatusUpdates. This is used to get advance in the queue.
◦ Example response with responses from two scooters:
{
"data": [
{
"data": {
"ActiveGSMOperator": 26201,
"Angle": 342,
"AxisX": 93,
"AxisY": 0,
...
"TopcaseClosed": 0,
"TopcaseLocked": false,
"TotalDistance": 1392,
"Towing": 1,
"TripDistance": 60000,
"VehicleSpeed": 0
},
"id": 1435489215,
"imei": "359633102780124",
"name": "GOLD_NO_4",
"timestamp": 1608481997546
},
{
"data": {
"ActiveGSMOperator": 26201,
"Angle": 342,
"AxisX": 93,
"AxisY": 0,
...
"TopcaseClosed": 0,
"TopcaseLocked": false,
"TotalDistance": 1392,
"Towing": 1,
"TripDistance": 60000,
"VehicleSpeed": 0
},
"id": 1435589218,
"imei": "459933101780122",
"name": "GOLD_NO_2",
"timestamp": 1608481997547
},
],
"lastTimestamp": 1608481997547
}

PrimingCloud GmbH – Govecs GOLD solution

 11 | 13

Response success/error handling:

At first the response status code should be checked to be a 200 status code. Any 4xx or 5xx
HTTP response status code mean the errors not processed successfully.
If the status code was 200, then the JSON response can be parsed.

The response JSON may contain further application level error information, e.g.:
{

"error": "Unexpected error: Could not find scooter: imei= / name=undefined / id=undefined / lic=",
"success": false
}
The presence of a success=false and a “error” field should be checked too. The error field
may contain information about the kind of error.

Some of the API calls may contain further success status information in the JSON body.
These Api specific response fields should be checked too:
• lock/unlock scooter
◦ success – Specifies the the lock/unlock operation was successful.
◦ scooterLock.isLocked – Specifies if the scooter is now locked.
◦ scooterLock.wasLocked - Specifies if the scooter was locked before the command
was sent.
◦ dataUpdateSuccess – Specifies if the latest state of the scooter was retrieved
from the scooter.
• lock/unlock topcase
◦ success – Specifies the the lock/unlock operation was successful.
◦ topcaseLock.isLocked – Specifies if the topcase is now locked
◦ topcaseLock.wasLocked - Specifies if the topcase was locked before the
command was sent.
◦ dataUpdateSuccess – Specifies if the latest state of the scooter was retrieved
from the scooter.
• QueryStatus
◦ dataUpdateSuccess – Specifies if the latest state of the scooter was retrieved
from the scooter.

PrimingCloud GmbH – Govecs GOLD solution