HomeGuidesAPI Reference
Guides

Signals

The system provides the last signal value sent by a vehicle.

You can receive every last vehicle's signals through an API call.

Each vehicle exposes different signals in the form of values associated with a timestamp.


Generic Signals

2hire defines five generic signals on every compatible vehicle.

We choose those five signals to compose our generic set because we consider them essential to monitor a vehicle.

Retrieve a generic signal

GET
/api/v1/vehicle/:uuid/signal/generic/:signal
Requires authorization

Request

The url parameters should consist of the following:

ParameterTypeDescription
uuidstringThe UUID of the vehicle for which to retrieve the provided signal.
signalstringIdentifier of the signal.

Successful response

The successful response will consist of the following:

ParameterTypeDescription
dataobjectThe signal representation, different for every supported signal.
timestampnumberUnix timestamp in milliseconds representing the instant in time when the value was received.
{
  "data": {
      "parameter": value
  },
  "timestamp": value
}

Error Response

The error responses are detailed in the Errors guide.


Online


You'll be able to know that the vehicle is currently connected to the network and when that information changed.

GET
/api/v1/vehicle/:uuid/signal/generic/online
ParameterTypeDescription
onlinebooleanThe vehicle's connectivity status. Returns true if the the vehicle is ready to respond in the next five minutes, false otherwise.
{
    "data": {
        "online": true
    },
    "timestamp": 1488700800000
  }

🚧

Warning

The online signal has specific behaviour, it is sent every time the status changes and every 15 minutes if it doesn't.


Position


You'll be able to geolocate a vehicle.

GET
/api/v1/vehicle/:uuid/signal/generic/position
ParameterTypeDescription
latitudenumberThe latitude of the position retrieved by a GPS unit.
longitudenumberThe longitude of the position retrieved by a GPS unit.
{
    "data": {
        "latitude": 41.91344,
        "longitude": 12.50113, 
    },
    "timestamp": 1488700800000
  }

🚧

Warning

The position signal has specific behaviour, it is saved only when it changes above the fifth decimal place (included).


Distance covered


You'll be able to know how far the vehicle has travelled overall. The value is expressed in meters.

GET
/api/v1/vehicle/:uuid/signal/generic/distance_covered
ParameterTypeDescription
metersnumberThe distance covered by the vehicle in its entire life. Expressed in meters with resolution in hundreds of meters.
{
    "data": {
        "meters": 154000
    },
    "timestamp": 1488700800000
  }

Autonomy percentage


You'll be able to know a vehicle's fuel level regardless of fuel type (electric or other).

GET
/api/v1/vehicle/:uuid/signal/generic/autonomy_percentage
ParameterTypeDescription
percentagenumberPercentage representing the currently available autonomy as provided by the vehicle.
{
    "data": {
        "percentage": 99
    },
    "timestamp": 1488700800000
  }

Autonomy meters


You'll be able to know how far the vehicle can move.

GET
/api/v1/vehicle/:uuid/signal/generic/autonomy_meters
ParameterTypeDescription
metersnumberThe distance that the vehicle can cover as provided by the vehicle.
{
    "data": {
        "meters": 34500
    },
    "timestamp": 1488700800000
  }

Specific signals

A set of specific signals based on a vehicle's configuration.

You'll need 2hire support to use them.

e.g. Car: external temperature (°C)

📘

Didn't find what you were looking for?

Are you looking for a specific parameter for your unique use case?
Contact us at [email protected]!


📘

Specific signals for the 2hire device

A list of specific signals and behaviours of our device is available here

Retrieve a specific signal

GET
/api/v1/vehicle/:uuid/signal/specific/:signal
Requires authorization

Request

The url parameters should consist of the following:

ParameterTypeDescription
uuidstringTThe UUID of the vehicle for which to retrieve the provided signal.
signalstringIdentifier of the signal.

Successful response

The successful response will consist of the following:

ParameterTypeDescription
dataobjectThe signal representation, different for every supported signal.
timestampnumberUnix timestamp in milliseconds representing the instant in time the value was received.
{
  "data": {
      "parameter": value
  },
  "timestamp": value
}

Error Response

The error responses are detailed in the Errors guide.


📘

Info

If you want to test the contents of this guide, please refer to our testing environment.

Updated 5 months ago