GuidesTutorialsAPI ReferenceContact us

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]!


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 7 days ago