Introduction

Fleetsmart's API conforms to the JSON:API standard. This means that it exposes your vehicle tracking data as a graph of resources. This provides a number of benefits for consumers of the API:

• Associated resources can be eagerly loaded to avoid unnecessary requests.
• URIs for lazily loaded associated resources are provided as part of the response to save the client constructing them based on schema.
• A consistent approach to querying, sorting and paginating data, as well as requesting only specific attributes of a resource.

The section on Working with resources describes the how the API is structured to allow you to find the relationships between different resources (for example, to find all the drivers who have driven some particular vehicle).

Consuming the API explains how to make properly authenticated requests.

Resources lists the different types of data exposed by the Fleetsmart API (such as vehicles, drivers and vehicle_locations) in detail, together with the relationships between the different resources.

Working with Resources

Top level structure

curl "www.fleetsmartlive.com/api/vehicles/37766428?include=current_driver"
  -H "X-CLIENT-ID: 1"
  -H "X-API-KEY: ab123.cd3ef4hi5jk67lm8"

An http request like:

{
  "data": {
    "id": "37766428",
    "type": "vehicles",
    "attributes": {
      "name": "Bob's car",
      "vrn": "AB12 CDE",
      "make": "Ford",
      "model": "Focus",
      "year": 2012,
      "fuel_type": "Petrol",
      "odometer_meters": 9876543,
      "tax_date": "2022-06-19T00:00:00+00:00",
      "mot_date": "2022-06-19T00:00:00+00:00",
      "next_service_date": "2022-06-19T00:00:00+00:00",
      "next_inspection_date": "2022-06-19T00:00:00+00:00",
      "icon": "red_car"
    },
    "relationships": {
      "drivers": {
        "links": {
          "related": "/api/drivers?filter[vehicle_id]=37766428"
        }
      },
      "driver_vehicle_assignments": {
        "links": {
          "related": "/api/driver_vehicle_assignments?filter[vehicle_id]=37766428"
        }
      },
      "vehicle_locations": {
        "links": {
          "related": "/api/vehicle_locations?filter[vehicle_id]=37766428"
        }
      },
      "device": {
        "links": {
          "related": "/api/devices?filter[vehicle_id]=37766428"
        }
      },
      "current_driver": {
        "links": {
          "related": "/api/drivers?filter[current_vehicle_id]=37766428"
        },
        "data": {
          "type": "drivers",
          "id": "1019833521"
        }
      }
    }
  },
  "included": [
    {
      "id": "1019833521",
      "type": "drivers",
      "attributes": {
        "name": "John Smith"
      },
      "relationships": {
        "vehicles": {
          "links": {
            "related": "/api/vehicles?filter[driver_id]=1019833521"
          }
        },
        "driver_vehicle_assignments": {
          "links": {
            "related": "/api/driver_vehicle_assignments?filter[driver_id]=1019833521"
          }
        },
        "current_vehicle": {
          "links": {
            "related": "/api/vehicles?filter[current_driver_id]=1019833521"
          }
        }
      }
    }
  ],
  "meta": {
  }
} 

might produce the example of the JSON-API compliant representation of a resource shown on the left.

We note the top-level structure of this object:

• data This holds most of the information of interest in the response, and will be discussed more fully in the next section.
• included This key will only be present if you have requested to eagerly load associated resources. Of the three resources associated to vehicles in this example, only the current_driver was eagerly loaded in this example (by using the query parms ...?include=current_driver in the request). Notice that by including associated resources in the included section, responses do not include redundant duplication of data. This does, however, require you to identify the resources you want by using their type and id.
• meta Can be safely ignored.

Data, attributes and relationships

Any resource's data key is guaranteed to contained the resource's id and type. Most resources will then feature attributes, which will containany properties of interest of the resource. In the example on the right, these attributes include the vehicle's registration plate (vrn), make and model.

A resource may also be related to other resources. In the example shown here, the vehicle can be related to many drivers; vehicle_locations; or to one current_driver. The data key's relationships child will then contain links to these related resources.

Flattening response data

curl "www.fleetsmartlive.com/api/vehicles.json"

returns

{
  "data": [
    {
      "id": "37766428",
      "name": "Bob's car",
      "vrn": "AB12 CDE",
      "make": "Ford",
      "model": "Focus",
      "year": 2012,
      "fuel_type": "Petrol",
      "odometer_meters": 9876543,
      "tax_date": "2022-06-19T00:00:00+00:00",
      "mot_date": "2022-06-19T00:00:00+00:00",
      "next_service_date": "2022-06-19T00:00:00+00:00",
      "next_inspection_date": "2022-06-19T00:00:00+00:00",
      "icon": "red_car.png"
    }, ...
  ]
}

However, some clients might prefer a flatter, more conventional JSON response structure, or the equivalent XML. These response types can be obtained by appending .json or .xml to the request.

Consuming the API

Content Type

As stipulated by the JSON:API specification, requests made against this API should always set the Content-Type header to application/vnd.api+json. This header may be omitted in subsequent examples, but should always be provided in real usage.

Authentication

curl "www.fleetsmartlive.com/api/vehicles"
  -H "X-CLIENT-ID: 1"
  -H "X-API-KEY: ab123.cd3ef4hi5jk67lm8"
  -H "Content-Type: application/vnd.api+json"

Make sure to replace these values with your real client id and API key.

Fleetsmart uses a Client-ID and API key pair to allow access to the API. Because of the sensitive nature of the data that can be exposed, we treat our API keys with the same precautions as our passwords.

You can register a new Fleetsmart API key within the main Fleetsmart app in Admin > Manage API Keys. This window also shows you your customer ID. This number should be provided as the value of the X-CLIENT-ID header, as shown in the example on the right.

Fleetsmart expects for the API key to be included in all API requests to the server in a header that looks like the following:

Throttling

To prevent the API from being overwhelmed by an excessive volume of requests, our servers throttle/limit any extreme volume of requests. Each client is limited to a maximum of one request per second. If this rate limit is exceeded the server will return 429 [Too Many Requests].

URI structure

# Get all vehicles on your account
curl "www.fleetsmartlive.com/api/vehicles"

# Get vehicle with id=1 
curl "www.fleetsmartlive.com/api/vehicles/1"

All resources expose routes to GET index and show actions of conventional RESTful resources.

As the API is meant to provide a convenient means of extracting data returned by our tracking devices, we do not currently provide routes for uploading or editing most of the data we make available via the API. Currently the only exception to this is that a full set of RESTful verbs are available for the management of Points of Interest.

CREATE payload

  "data": {
    "type": "poi",
    "attributes": {
     "name": "important customer",
      "postcode": "A12 3BC",
      "radius": "123"
    }
  }

UPDATE payload

"data": {
  "id": 12345,
  "type": "poi",
  "attributes": {
     "name": "important customer",
      "postcode": "A12 3BC",
      "radius": "123"
    }
}

Payloads that modify resources must be encoded as JSON.

Defining queries

The API supports a number of operations to refine your request for data through the use of query params in the URL.

Filtering

# Get all vehicles of model 'Transit' 
curl "www.fleetsmartlive.com/api/vehicles?filter[model]=transit"

# Get all locations for the vehicle with id=1 since 2020-01-31 00:00:00
curl "www.fleetsmartlive.com/api/vehicle_locations?filter[date_time][gt]=2019-01-31T00:00:00.000Z&filter[vehicle_id]=1"

You can filter resources by their attributes, or by attributes on their related resources.

Sorting

# Order responses alphabetically by registration
curl "www.fleetsmartlive.com/api/vehicles?sort=vrn"

Results can be sorted by attributes where it makes sense to do so such as alphabetically or chronologically.

Pagination

curl "www.fleetsmartlive.com/api/vehicles?page[size]=30"

By default requests are limited to 20 resources at a time. This option can be changed with the size parameter.

# Return the second page of 20 vehicles
curl "www.fleetsmartlive.com/api/vehicles?page[number]=2"

Successive pages can be requested with the page option.

Resources

Devices

curl "http://www.fleetsmartlive.com/api/devices"

The tracking device installed in a vehicle.

Attributes

Resources

Drivers

curl "http://www.fleetsmartlive.com/api/drivers"

Describes a driver registered on the system.

Attributes

Filters

curl "http://www.fleetsmartlive.com/api/drivers?current=true"

Driver Vehicle Assignments

curl "http://www.fleetsmartlive.com/api/driver_vehicle_assignments"

Represents a period of time in which a driver is assigned to a vehicle. Note that the meaning of this time varies depending on how DVAs are managed. If drivers are assigned to vehicles manually via the Fleetsmart UI, then this time might represent a period of months or years. If drivers fob in and out of vehicles, however, it might represent a single journey.

Attributes

Harsh Events

curl "http://www.fleetsmartlive.com/api/harsh_events"

An event triggered in response to the detection of rapid change in speed or direction.

Attributes

Relationships

IO Events

curl "http://www.fleetsmartlive.com/api/io_events"

An event triggered by a change in the inputs monitored by the device, such as the ignition.

Attributes

Relationships

Live Views

curl "http://www.fleetsmartlive.com/api/live_views"

Contextual information and metadata about the last information received from a device.

Attributes

Relationships

POI Events

curl "http://www.fleetsmartlive.com/api/poi_events"

Describes when a vehicle enters and leaves the designated geofence for a Point Of Interest (POI). This resource actually has no attributes of its own, but instead defines a relationship between four other resources:

Relationships

Points of Interest

curl "http://www.fleetsmartlive.com/api/pois"

A geofence describing a point of interest to the customer, such as a depot or a customer address.

Attributes

Relationships

Vehicle Locations

curl "http://www.fleetsmartlive.com/api/vehicle_locations"

Contains the key information associated with any instace of a vehicle reporting tracking data.

Attributes

Relationships

Vehicles

curl "http://www.fleetsmartlive.com/api/vehicles"

Information about a customer's vehicle.

Attributes

Relationships