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:

Parameter	Type	Description
`uuid`	`string`	The UUID of the vehicle for which to retrieve the provided signal.
`signal`	`string`	Identifier of the signal.

Successful response

The successful response will consist of the following:

Parameter	Type	Description
`data`	`object`	The signal representation, different for every supported signal.
`timestamp`	`number`	Unix 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

Parameter	Type	Description
`online`	`boolean`	The 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

Parameter	Type	Description
`latitude`	`number`	The latitude of the position retrieved by a GPS unit.
`longitude`	`number`	The 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

Parameter	Type	Description
`meters`	`number`	The 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

Parameter	Type	Description
`percentage`	`number`	Percentage 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

Parameter	Type	Description
`meters`	`number`	The 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:

Parameter	Type	Description
`uuid`	`string`	TThe UUID of the vehicle for which to retrieve the provided signal.
`signal`	`string`	Identifier of the signal.

Successful response

The successful response will consist of the following:

Parameter	Type	Description
`data`	`object`	The signal representation, different for every supported signal.
`timestamp`	`number`	Unix 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.