Acronyms ¶

Open Telematics API ¶

A project to enable business resiliency for motor freight carriers with tight integrations into Telematics Service Providers (TSPs).

This document is written in API Blueprint format 1A.

The specification is pubished in various forms:

• at github.com/nmfta-repo/nmfta-opentelematics-api

  • apiary.apib – API Blueprint specification
  • otapi.html – standalone documentation rendering of the above

• here, opentelematicsapi.docs.apiary.io, as:

  • Interactive documentation
  • A mock server

• at apimatic/…/nmfta-opentelematics-api as:

  • Exportable API specifications in multiple formats including: Open API 3.0, RESTful API Modeling Language (RAML) 1.0, and Swagger 2.0
  • Downloadable (client) Software Development Kits (SDKs) in .NET and Python

There is also a prototype implementation of version 0.1rc4 of this specificiation available at github.com/nmfta-repo/nmfta-opentelematics-prototype.

Finally, a questionnaire for use by motor freight carriers in assessing the degree to which a TSP provides OTAPI support is also available: Open Telematics Supported Use Cases Questionnaire.xlsx

The Open Telematics API (OTAPI) is intended to make the TSP-Carrier interface the same across multiple TSPs. It is not intended to specify any aspects of the TSP’s connections to their telematics devices. Neither does it imply any changes to the location where data is stored or access controls on the data – the data will still live at the Motor Freight Carrier as-sourced from their accounts at the TSP.

If a telematics system provider (TSP) suddenly goes out of business (have had two examples of this in 2018) any commercial fleet relying on their service will need to find a new provider. Due to the lack of a standardized data format and methods for retrieving telematics logs & data, a commercial fleet manager will have to reintegrate an alternate telematics provider’s data format into their existing system reporting.

This is a standardized API for retrieving telematics logs & data. The API specification exclusively uses JSON for request and response bodies in this version; therefore, relies on serializations of Javacript types in JSON. e.g. lists [], dictionaries {} and the null value null. Each participating TSP would be individually responsible for the necessary translations from their existing formats to this Open Telematics API. Each TSP would continue to be responsible for managing their own cloud infrastructure housing customer data. The Open Telematics API, as an additional interface, will be made available by TSPs to allow their customers ready access to pull data in the standardized format, especially in examples of mixed TSP fleets. The API could grow into Integrated Vehicle Health Maintenance (IVHM) and Conditioned Based Maintenance (CBM) in the future via TSPs Extending this API.

Contributors ¶

This Open Telematics API was made possible through the generous contributions of thought leadership and technical expertise of many collaborators across the heavy vehicle cyber security community, working to push the industry forward and make it more resilient. Though some of our contributors wish to remain anonymous, we are deeply grateful to everyone who has given their time and energy to make this a reality.

Authentication ¶

All requests to Open Telematics API endpoints require authentication.

For this version of the API, v1, all authentication must be performed using Hyper Text Transfer Protocol (HTTP) Basic. e.g.

Authorization: Basic YWRtaW46YWRtaW4=

This authentication method relies entirely on the security protections provided by the Transport Layer Security (TLS) layer; therefore HTTPS is mandatory on all connections and implementors must follow adhere to the security requirements detailed in the Security Requirements for Implementors section below.

TSPs implementing the Open Telematics API must provide a means to create username-password pair credentials and these must be associated with roles (see section Authorization below).

Authorization ¶

TSPs implementing the Open Telematics API must include access controls for all requests. The access controls must restrict authorization of requests to only those roles that are assigned in the Access Controls tables throughout this API specification. The tables will look like the following example:

Each column of the Access Controls tables are the user roles to which users in the TSP’s implementation will be assigned. It must be possible for clients to use usernames for Authentication (see above); these usernames will be assigned to one role and no more than one role each.

The definition of each role is most accurately captured by the total of all the DENY/ALLOW assignments to the role in the Access Controls tables throughout this API specification. The intent of these access controls is to separate privileges so that carriers can limit which clients have access to:

1. streaming feeds of objects as they are added to the TSP

2. any Personally Identifiable Information (PII)

As can be seen in the Access Controls tables in the requests subsections of References that follow, the roles are assigned DENY/ALLOW such that:

Security Manifest ¶

The Open Telematics has been designed with security up-front. Here we capture some National Institute of Standards and Technology (NIST) 800-53 controls which are satisfied by the present design of OTAPI, along with rationale of how each is satisfied. The intent of this section is to give some assurance of security-by-design in the OTAPI.

NIST 800-53 SC-6: Resource Availability / URL size should not exceed 2000 characters

None of the Universal Resource Locators (URLs) in any of the endpoints of OTAPI will exceed a maximum of 220 characters. The longest resource path is /v1.0/drivers/{driverId}/availability_factors/ which would be 104 characters long if a 68 character driverId were used. The endpoints have between 1 and 3 query string parameters, most are dates which are expressed in International Standards Organization (ISO) 8601 format, 24 characters long the others are opaque IDentifiers (IDs) which could be up to 68 characters long. Worst case URL length is 104 + 24 + 24 + 68 (220) characters.

NIST 800-53 SC-6: Resource Availability / HTTP request size should not exceed 1MB limit

All POST, PUT and PATCH methods in the OTAPI are specified with JSON schema blocks over-and-above API Blueprint specifications which include maximum field lengths. The maximum requests size for any of the endpoints in OTAPI is under 4K.

NIST 800-53 SI-10: Information Input Validation / All file references should be indirect

There are no direct file references in OTAPI; all objects are referred to by opaque identifiers and furthermore the data export API returns a URL for dereferencing and not a file.

NIST 800-53 AC-3: Access Enforcement / Considerations: Grant privileges directly to users

The OTAPI is designed for machine to machine communications; as such the privileges for access to OTAPI information is granted to the motor freight carrier backend systems which integrate with OTAPI services. The privileges assigned can be minimized, however – see sections Authentication and Authorization.

NIST 800-53 AC-24: Access Control Decisions / Considerations: Security controls assigned to each request

OTAPI requires valid authorization with each request; see section Authentication.

NIST 800-53 AU-6: Audit Review, Analysis, and Reporting / Considerations: Grant privileges to specific users

OTAPI is designed with segmented privileges and separated user roles so that privileges are granted to specific roles and no more privilege is used than is needed. See section Authorization.

Security Requirements for Implementors ¶

All TSPs that implement an Open Telematics API instance are expected to provide a secure service by default. In what follows we outline some security requirements that are expected in addition to the authentication and access control that is detailed in the sections above.

General Security Requirements ¶

Vendors must maintain a vulnerability response and disclosure program in accordance with established standards such as International Organization of Standards (ISO)/International Electrotechnical Commission (IEC) 29147:2014 (Information technology – Security techniques – Vulnerability Disclosure) and ISO/IEC 30111:2013 (Information technology – Security techniques – Vulnerability Handling Processes).

Vendors should ensure their vulnerability response and disclosure program conforms with the ‘Legal bug bounty’ safe-harbor requirements to protect researchers and encourage the highest-quality participation.

Open Telematics API Server Security Requirements ¶

TLS Configuration

The TLS security for Open Telematics API servers is of paramount importance. All of the confidentiality and integrity protections are relying on this layer. For this reason, Open Telematics API servers must ensure that their HTTPS / TLS configurations are of the highest quality. Following the Qualys SSL Labs Guide is reccomended. The automated tool, also by Qualys SSL Labs, at https://www.ssllabs.com/ssltest/ will report a ‘letter grade’; it is expected that TSPs will have letter grades of ‘A’ or higher according to that tool.

Whitelist HTTP Methods

This API specification (in APIBlueprint) has a complete list of all allowable HTTP methods for each resource/‘end point’ of the Open Telematics API. Open Telematics server implementations should use the list of methods as a whitelist to filter incoming requests before any additional processing.

Rate-limit API Requests

Since every request to the Open Telematics API must be authenticated it is possible to rate-limit Open Telematics API requests per authenticated user. Vendors should implement rate limits on overall API requests per authenticated user, e.g. to avoid one user exhausting server resources of others; however, vendor must not rate-limit any Open Telematics API implementations to rates below what is offered through their other API services for telematics data. Rate-limiting response must be implemented using response 429 and headers as detailed in this document.

Prevent Brute-Forcing

Authentication (for this version of the API) is tied exclusively to HTTP Basic in each request. This means that each and every API endpoint is an opportunity to brute force any of the user credentials. Open Telematics server implementors must enforce a global rate-limit on authentication attempts for each user. Implementors may also want to consider other mitigations against brute-force attacks on credentials; c.f. the Open Web Application Security Project® (OWASP) page on Blocking Brute Force Attacks.

Prevent Server-Error Stacktraces

Open Telematics server implementors must ensure that their software is deployed such that it does not include stack traces in any response; e.g. no stacktraces in a 500 server error response.

Prevent Resource Exhaustion by Slow-posting

Open Telematics server implementors must ensure that, when receiving data from clients, the server implements short- enough timeouts such that exhaustion of the server resources through malicious client ‘slow-posting’ is not possible. For more details, consult this Qualys blog post https://blog.qualys.com/securitylabs/2011/11/02/how-to-protect- against-slow-http-attacks.

Input Sanitization

Open Telematics server implementors must employ input sanitization when ingesting any data, i.e. for the POST, PUT, PATCH methods. This API uses exclusively JSON for data serialization; therefore, at a minimum all input data should be verified as valid JSON before being further processed. Furthermore, this specification includes generated JSON schema for the expected inputs and so additional verification that the input JSON conforms to the expected schema can also be performed before further processing is performed.

Open Telematics API Client Security Requirements ¶

Certificate Pinning

Because the confidentiality of credentials is only protected by TLS in this version, it is very important that all Open Telematics API clients must be configured such that substitution of any TLS certificates results in a failure to establish any connections to the Open Telematics API server.

All clients must implement certificate pinning. i.e. All client implementations will pass the tests, 5.4-5.6, for certificate pinning in the OWASP Mobile Application Security Verification Standard (MASVS).

Working With Dates ¶

When exchanging dates as parameters to API methods or in responses from the API, you must ensure that they are formatted properly as an ISO 8601 string (format yyyy-MM-ddTHH:mm:ss.fffZ). In addition, all dates will have to first be converted to Coordinated Universal Time (UTC) in order to ensure time zone information and daylight savings times are accounted for correctly.

Working with Time-Based Queries ¶

There are many API endpoints which support searches of data based on a time range. In all cases, the time range specified by a pair of start and stop parameters represents an inclusive-exclusive time range. i.e. a time period which includes the moment in time given by start and all times up-to but not including the moment in time given by stop.

The matching performed in all of these searches will be a time-intersection. i.e. the objects will be returned in search results if their associated time periods (however defined) have any intersection with the inclusive-exclusive time range given by the pair of start and stop parameters.

Objects may have multiple time periods associated with them; e.g. events recorded and transmitted by TSPs may have the times at which the event was created, when it was recorded and/or when it was made available by the TSP to the motor freight carrier. Unless otherwise specified, the time period of objects against which matching is performed will be the creation times. Furthermore, implementors are required to ensure that the creation times of any objects are preserved through all data transfers, i.e. that the creation times are not modified after initial recording at the telematics devices in the field.

In the special case of matching against an object with a single time field, instantaneous events the object will be returned if its instantaneous time value is within the inclusive-exclusive time range given by the pair of start and stop parameters.

Working With Locations ¶

When exchanging locations as parameters to API methods or in responses from the API, you must ensure that they are formatted as a latitude+longitude pair (format [-]aaa.aaaaaaa [-]ooo.ooooooo). Positive in the first component, Latitude, indicates North (N) and East (E) in the second component, Longitude.

Note that all locations assigned to objects by the TSP in the OTAPI are done so on a best-effort basis. Different TSPs have different rates of location update, different accuracies and different means of mapping a previously known location into events after the known location (e.g. prediction vs. interpolation). This Open Telematics API specification does not make any specifications about how often, how accurate or any other statements about how geographic locations must be assigned to objects by the TSP.

Working with Feed Follow Queries ¶

There are endpoints of the API which are intended to be polled by clients so that new data (data newer than the previous query) is returned. Theses Feed Follow endpoints are intended to assist in real-time client applications.

In some cases, the clients require that no data is ever missed by following (polling the endpoint); however, due to the nature of telematics systems there can be a high latency between time of creation and time of delivery to the TSP. Hence there is a non-trivial cost associated with providing endpoints that can ensure that no data is missed in following. e.g. the Follow a Feed of Log Events endpoint below.

Unless stated otherwise, all Feed Follow endpoints will be such that no data is missed by following; including cases of very high latency between data creation and delivery. Special exceptions will be noted on the endpoints for the cases where the clients require that they have the newest information and are not concerned with ensuring that no data is missed.

Error States ¶

The common HTTP Response Status Codes are used.

Pagination ¶

Where requests may return large collections and where the collections to be returned are presumed to be static the API will include support for pagination of requests. The scheme for pagination closely follows the pagination scheme of github.

Requests that are paginated will return 50 items by default. The page parameter can be used to access later pages; it defaults to the first page, page 1. A custom number of items can be requested with the count parameter.

The total number of elements available is returned in the X-Total-Count response header.

Server Performance ¶

This API is intended to be integrated into motor freight carriers back end operations systems; therefore, there are performance requirements to be considered as well. The API has been modeled in terms of use cases by the motor freight carriers (see below). Each of these use cases can be considered to be executing concurrently in the motor freight carrier. This has important design implications. For example, if a motor freight carrier has 10,000 trucks and makes requests regarding their location once a minute this would imply 10,000 method invocations per minute with a relatively small return data point. Other methods such as vehicle histories will have larger return data sets and require more server side processing but would not be expected to be called with a high frequency. Given that it is not possible to understand how these methods might be used by motor freight carriers in a final implementation it is difficult to provide concrete performance metric requirements at this stage. Instead, implementors should consider this per-truck scaling and design accordingly. i.e. consider that fleets can have more than 100,000 trucks and that some API endpoints in this specification will be called rapidly (1 request per minute) whereas others will be called infrequently (1 request per day).

This specification does not go into implementation specific design decisions which are up to the individual TSPs since such decisions are heavily dependent on their architecture. It is, however, strongly recommended that the TSPs consider building-in performance features such as request queueing and request rate limiters to provide a stable and robust solution. It is also recommended that the TSPs provide information on the frequency of updates for data feed subscriptions such as the vehicle feed so the consumers can make appropriate design decisions.

Response Size Limits ¶

Considering the volume of data which will be generated by large fleets, there will be cases where pagination is not sufficient to limit the load on the TSP’s OTAPI servers.

The TSPs implementing OTAPI may elect to return an error 413 Request Entity Too Large when clients make queries which would yield a response which is deemed ‘too large.’ The definition of ‘too large’ is intentionally left open so that TSPs can configure different limits for the various endpoints and on a per-customer basis (based on e.g. tiers of service).

Client software must be prepare to receive error 413 and to react by reducing the size of the query or ceasing the query; client may not retry a request when receiving a 413 error. This specification lists the endpoints where clients must be prepared for 413 responses.

Unknown Drivers ¶

For the elements of Open Telematics API which are concerned with Driver log events, or other driver-associated data, there needs to be a concept of an ‘unknown driver’. Indeed this concept is part of the Electronic Logging Devices (ELD) mandate. In Open Telematics API objects: driverID references to the unknown driver is represented by null.

Provider Identifiers ¶

An important use case of the Open Telematics API by motor freight carriers is to run ‘mixed fleets’ where there are more than one TSP’s service integrated concurrently. In such a deployment we can imagine possible issues with duplicated data or conflicts.

To prepare a solution to these problems, this specification includes provisions to identify the source of all data by a ‘Provider ID’. Implementors are required to choose a unique identifier and assign it to all ‘Provider ID’ fields in all data structures where it is included in this specification. We recommend that TSPs use their domain (e.g. api.provider.com) which should be sufficiently unique; however, TSPs can elect to use whatever identifier they like but it should be 1) recognizable as associated with that TSP and 2) remain constant throughout the lifetime of the TSP’s service.

Extending This API ¶

The Open Telematics API is intended to enable motor freight carriers to be able to substitute TSPs (either concurently or as fail-overs). This, of course, means that OTAPI must include only the most common elements of all the TSPs (so- called Lowest Common Denominator).

However, each TSP has their own special value-add and, in some cases, the motor freight carriers would rather have access to this special value-add via OTAPI rather than include parallel integrations with SDKs in their operations. Unique vehicle performance data is a good example of this, where it is more useful embedded with the other events in the TSP stream.

Thus, extensions to the API will be necessary and in preparation for this the data models specified in the current API have been left ‘open’. i.e. the addition of data fields to the definitions of the objects which are returned by OTAPI according to this specification will not cause validation errors by clients which are following the JSON schema in this specification.

Addition of fields to the objects must be done such that it is not possible for the new extension fields to collide with other extensions or with future versions of the API; therefore, all fields added as extensions must be prefixed with x_providerid_ where providerid is the provider ID (see Provider Identifiers for more details).

• Adding additional field/members to the data objects, when the data is needed by a motor freight carrier IS a valid extension to the OTAPI

• Adding additional possible values to enumerations IS NOT a valid extension to the OTAPI

• Adding additional endpoints/methods IS NOT a valid extension to the OTAPI

In cases where enumerations need to be changed and additional endpoints need to be added, this should be approached by changing the OTAPI upstream. Also, ideally, adding fields should also be done by suggesting changes upstream; in this case, an example roadmap of the process might look like: starting with a prefixed field in the TSP extensions then suggesting the useful fields for inclusion and review leading to a new field without a prefix.

Localization ¶

The Open Telematics API is ready to be used in locales other than the United States (English-speakers). To enable display and interpretation of data in languages other English (US, en_US) implementors may provide translations of the descriptions of the enumerated constants in the API.

The localization does not apply to units of measure. Open Telematics API will use International System of Units (SI) with the following exceptions:

• velocities where units of km/h are used

• Log Event objects where units of either miles or kilometres are used (but not both)

The localization also does not apply to arbitrary strings in data objects of the API such as messages for display in vehicles or comment fields.

Requests to Get a Translation GET /v1.0/i18n shall include the request header Accept- Language:. If no request header is present then Accept-Language: en will be assumed.

Open Telematics API implementors choose which languages they will support. If the Accept-Language: request header specifies a language which is unsupported by the Open Telematics API instance, then a 406 (Not Acceptable) response will returned. Implementors must support Accept-Language: en and return a complete mapping – a sample of which is provided below for convenience in the sample response to GET /v1.0/i18n.

Telematics API Use Cases by Motor Freight Carriers ¶

The Open Telematics API is envisioned to be complete enough that motor freight carriers can use these APIs instead of the proprietary TSP APIs – while still connecting-to TSP-hosted servers and hence still using the same provider. In the interest of ensuring that the APIs are useful to their intended users (motor freight carriers) we will capture – and organize – the API by these use cases. Each use case description in the following subsections includes links to the API endpoints upon which the use case relies. The links can be followed to the Reference section for details on the endpoint. It is the intention of the authors that each endpoint is defined to satisfy a use case and no endpoint is introduced without a supporting use case captured here.

Check Provider’s State of Health ¶

Users of telematics that is highly integrated into their operations need assurances of the state of health of the Provider’s services.

The IT and operations staff responsible for system uptime want to query the Open Telematics API provider (TSP) Provider State of Health. They expect to receive either an ‘all-clear’ response indicating that the provider is not aware of any issues with its services at the moment of query or some details describing the contributing factors that have led to less than optimal operation.

To check the current state of health of the service they use

• Check Current State of Health GET /v1.0/health/current

To check the past 30 days worth of states of health they use

• Check Past 30d State of Health GET /v1.0/health/recents

Data Export ¶

Motor freight carriers want to export all data from a TSP on a daily basis. Where ‘all data’ for the purposes of this specification is all the data specified here and does not include any other proprietary data structures designed and employed by the TSP. These data exports could be used by carriers to complete mandatory processes during times of TSP outage or to restore data – although this last potential use is not a use case we aim to support in OTAPI.

To obtain a complete data export (including driver information) they use

• Complete Telematics Export Format GET /v1.0/export/allrecords/status{?dayOf}.

To obtain a data export with vehicle information only (intended to be free of PII) they use

• Vehicle-Only Telematics Export Format GET /v1.0/export/vehiclerecords/status{?dayOf}.

Generate Records of Duty Status for Compliance ¶

Motor freight carriers use telematics systems to maintain Record of Duty Status (RODS) compliance. The TSP to the carrier will supply compliant records directly, without the need for the carrier to use the OTAPI. The carrier may use OTAPI for RODS in the event that compliant records need to be produced when a TSP is no longer available. i.e. as a backup process only; however, to do so will require processing and it is not expected that OTAPI data be ready for compliance as-is. A couple examples; the line data check and file data check values will need to be calculated after the creation of line and files in the process of creating RODS files for compliance; OTAPI will not include these values. Also note that preparing compliance reports is a value added by TSPs; e.g. in at least one case, the ordering used by regulators used truncated timestamps and the higher-resolution available in the TSP RODS information led to events being out-of-order in the view of the regulators without special handling by the TSP. This is an example of the kinds of nuances that are handled by TSPs in their service offering and OTAPI is not meant to replace that service.

Personnel responsible for compliance need to be able to create RODS based on information exported from OTAPI in the event a TSP is no longer available.

See Complete Telematics Export Format GET /v1.0/export/allrecords/status{?dayOf} for more details on the file format which should contain sufficient data for this use case in the array of Log Event objects.

Driver Availability ¶

Motor freight carriers need to understand the availability of their drivers – within the current regulatory context of those drivers – so that the carrier can ensure regulatory compliance and, more importantly, driver safety.

Both personnel and semi-automated systems responsible for planning and assigning driver routes want to model the current availability of a Driver. They have

• a Driver object id for a given driver

To calculate the current driver availability they retrieve ‘driver availability factors’ from which the current driver availability can be calculated using

• Get Driver Availability Factors GET /v1.0/drivers/{driverId}/availability_factors/{?startTime,stopTime} for a given Driver object id over a given period of time

To consider also the breaks and exemption rules for driver in those logs (if they operate in regions with specific break rules or waivers) they use

• Get Driver Breaks and Waivers GET /v1.0/drivers/{driverId}/breaks_and_waivers/{?startTime,stopTime} a given Driver object id over a given period of time

In some cases, facilities systems want to set the driver status in cases where they are on-duty but not driving. To do this their systems send duty status changes to the TSP using

• Update Driver Duty Status PATCH /v1.0/drivers/{driverId}/duty_status for a given Driver object id.

Driver Route & Directions Communication ¶

Motor freight carriers update their Driver’s destination and route during their trip. This allows them to react to changing conditions in weather, the needs of regulatory restrictions on hours, optimizing follow-on activities after a trip, etc.

This feature is heavily used but also is commonly offered as an add-on to the TSP service from another party.

Both personnel and semi-automated systems responsible for planning and assigning driver routes want to update the Driver’s destination and route during a trip. They have

• a Driver object id for a given driver

• a Vehicle object id for a given vehicle

• and because they previously created a Vehicle Route POST /v1.0/vehicles/{vehicleId}/routes they have both

  • a Vehicle Route object id and
  • an array of Stop Geographic Details object id.

To confirm that the given driver is still available to complete the route they retrieve the driver availability factors for the time period from the driver’s start of route up until the present by using

• Get Driver Availability Factors GET /v1.0/drivers/{driverId}/availability_factors/{?startTime,stopTime} endpoint for a given Driver object id over a given period of time

To change the route they use

• Update Vehicle Route PUT /v1.0/vehicles/{vehicleId}/routes/{routeId} for a given Vehicle object id and a given Vehicle Route object id

To update details (entry points, notes) of the route stops they use

• Update Stop Geographic Details PATCH /v1.0/stops/{stopId} for a given Stop Geographic Details object id

Driver Route & Directions Start ¶

Motor freight carriers plan destinations and routes for their drivers and inform the drivers of the plan via the in-cab components of a telematics system.

This feature is heavily used but also is commonly offered as an add-on to the TSP service from another party.

Both personnel and semi-automated systems responsible for planning and assigning driver routes want to inform their drivers about their planned route before the driver starts the trip. They have

• a Vehicle object id for a given vehicle

To first check the vehicle for any faults or alarms in the past 24h they use

• Get Vehicle Flagged Events GET /v1.0/vehicles/{vehicleId}/flagged_events/{?startTime,stopTime} for a given Vehicle object id over a given period of time

Assuming the vehicle is good to go, then they send trip start and stop destinations to the driver along with any other instructions (such as which trailers to take) using

• Create a Vehicle Route POST /v1.0/vehicles/{vehicleId}/routes for a given Vehicle object id

A successful creation of a route will yield a Route object id and an array of Stop Geographic Details object id in the response to use in further updates or modifications to the route or stops.

Driver Route and Directions Done ¶

Motor freight carriers receive notifications when Drivers have completed their trip.

This feature is heavily used but also is commonly offered as an add-on to the TSP service from another party.

Both personnel and semi-automated systems responsible for planning and assigning driver routes want to be notified of a completed trip, along with the driver information about duty on the trip. They have

• a Driver object id for a given driver

• and because they previously created a Vehicle Route POST /v1.0/vehicles/{vehicleId}/routes and may have optionally updated the driver’s Route Stop PUT /v1.0/vehicles/{vehicleId}/routes/{routeId} or updated the Stop Geographic Details PATCH /v1.0/stops/{stopId} they hence have both

  • a Vehicle Route object id and
  • a Stop Geographic Details object id.

To react to the route completions in ‘real-time’ they follow a feed using

• Follow Fleet Log Events GET /v1.0/event_logs/feed{?token} for all drivers

They mark trips completed based on matching a Log Event object in the feed which matches a given Driver object id and also has a status indicating that the route is complete.

At the end of trips they also query for any updates on changes to gates, access, repairs etc at the destination using

• Get Stop Geographic Details by its ID GET /v1.0/stops/{id} for a given Stop Geographic Details object id

Dispatch Messaging (by Driver) ¶

Motor freight carriers need to enable their drivers to ‘call-back’ to the dispatch in a timely and safe manner. To do this they often rely on two-way messaging provided by the TSP. The drivers can create and send messages to dispatch at the motor freight carrier by using an interface on their in-cab displays.

Both personnel and semi-automated systems responsible for drivers in the field, “Dispatch”, need to be notified of new messages. To process the incoming messages for Dispatch in ‘real time’ they follow a feed using

• Follow Dispatch Messages GET /v1.0/fleet/dispatchmessages/feed{?token}

Driver Messaging by Geo-Location ¶

Motor freight carriers use telematics systems to message their drivers for various reasons, not the least of which is to notify the drivers of dangerous weather conditions in their area.

Personnel responsible for planning and assigning driver routes want to send messages to drivers in a particular geographic region. They have

• a target geographic area, to which they want to send messages

To determine which vehicles presently lie within the geographic area they get the current location of all fleet vehicles using

• Get Fleet Latest Locations GET /v1.0/fleet/locations/latest{?page,count}

Then, for each Vehicle object id which lies within the geographic area they send it a message using

• Send Message to a Vehicle POST /v1.0/vehicles/{vehicleId}/message for a given Vehicle object id

Driver Messaging by Vehicle ¶

Motor freight carriers also message their drivers by sending messages directly to a vehicle.

Personnel responsible for planning and assigning driver routes want to send a message to a driver’s vehicle. They have

• a Vehicle object id to which they wish to send a message

they send the vehicle a message using

• Send Message to a Vehicle POST /v1.0/vehicles/{vehicleId}/message for a given Vehicle object id

Vehicle Location Time History Processing ¶

Motor freight carriers use telematics fleet Location Time History for multiple ‘fleet dynamics modeling’ use cases such as: Fuel Purchase Prediction, Fuel Consumption Performance Tracking, and Fleet Maintenance Planning. They have

• a target time period, over which they want to perform an analysis of fleet location time history

To perform the analysis on fleet location time history they use

• Get Fleet Location History GET /v1.0/fleet/locations/{?startTime,stopTime,page,count} for a given time period

Human Resources Process: Payroll ¶

Motor freight carriers use telematics systems to assist in payroll processing. This enables efficiencies at scale that are important to modern motor freight carrier operations.

Automated payroll/HR systems want to receive Log Events and convert these into payroll tracking entries.

To do create payroll tracking entries in ‘real-time’ they follow the feed of Log Events using

• Follow Fleet Log Events GET /v1.0/event_logs/feed{?token} for all drivers

furthermore – if they operate in regions with specific break rules or waivers are applicable – they use

• Get Driver Breaks and Waivers GET /v1.0/drivers/{driverId}/breaks_and_waivers/{?startTime,stopTime} for each Driver object id in the feed for the times of interest to the payroll tracking entries

In some cases, facilities systems want to set the driver status in cases where they are on-duty but not driving. To do this their systems send data to the TSPs using

• Update Driver Duty Status PATCH /v1.0/drivers/{driverId}/duty_status endpoint for a given Driver object id.

and the duty status changes are reflected in the Follow Fleet Log Events GET /v1.0/event_logs/feed{?token} endpoint.

To associate their Driver’s with metadata for use by the TSP (e.g. the region of governance for duty breaks and exemptions) they use

• Update Driver Info PATCH /v1.0/drivers/{driverId} for a given Driver object id.

Human Resources Process: Accident Report ¶

Motor freight carriers use telematics systems to monitor their fleets for accidents.

Semi-automated systems want to receive notification of any accidents in their fleet and handle accident reports internally according to their own processes.

To do respond to accidents in ‘real-time’ they follow the feed of Log Events using

• Follow Fleet Log Events GET /v1.0/event_logs/feed{?token} for all drivers

Carrier Custom Business Intelligence ¶

Motor freight carriers use telematics systems for multiple, custom, business intelligence purposes where the overall health of their fleet is considered and fed into their own proprietary models.

Automated and semi-automated analysis and reporting systems want to get the overall fleet health status for a particular time period.

To process the fleet state over a target time period they use

• Get Fleet Vehicle Info GET /v1.0/fleet/infos/{?startTime,stopTime} for a given time period

To process and respond to fleet status in ‘real-time’ they follow a feed using

• Follow Fleet Vehicle Info GET /v1.0/fleet/infos/feed{?token} for all vehicles

To follow-up with queries of the hi-resolution time history of the fleet for a given time period they use

• Get Fleet Location History GET /v1.0/fleet/locations/{?startTime,stopTime,page,count} for a given time period.

Compliance and Safety Monitoring ¶

Motor freight carriers use telematics systems to monitor compliance and safety for their operations.

Personnel responsible for safety and compliance want to review the safety and compliance of their drivers. They have:

• a Driver object id for a given driver

• a time period of interest

To obtain the information necessary to review for safety and compliance they use

• Get Driver Performance Summaries GET /v1.0/drivers/{driverId}/performance_summaries/{?startTime,stopTime} for a given Driver object id and for a given time period

To create, delete and modify driver login credentials that the drivers will use in the field and to which the Driver Performance Summary objects are associate they use

• Update Driver TSP Portal Account PATCH /v1.0/drivers/{driverId}/driverportaluser for a given Driver object id

In-Field Maintenance & Repair ¶

Motor freight carriers use telematics systems to plan (and react to) maintenance needs of their fleets.

Automated back-end systems at the motor freight carrier want to be notified of any vehicle issues requiring maintenance.

To determine which events require maintenance in ‘real-time’ they follow a feed using

• Follow Fleet Fault Code Events GET /v1.0/fleet/faults/feed{?token} for all fleet vehicles

To dispatch assistance to the location of a given Vehicle object id – in the event that an issue requiring maintenance must be resolved in the field – they obtain the most recent vehicle location using

• Get Vehicle Location History GET /v1.0/vehicles/{vehicleId}/locations/{?startTime,stopTime} for a given Vehicle object id over the most recent time period

Machine-Readable Data Quality ¶

Motor freight carriers rely on data quality properties of the service provided by TSPs and need to be able to adapt their back-end systems depending on the various data quality properties of a given TSP’s service.

To determine what the expected data qualities of the service are, they use

• Get Data Qualities Statement GET /v1.0/dataquality.

Estimating Received Data Quality ¶

Motor freight carriers need to estimate certain data quality properties of their service for a given time period.

To gain these estimates they post-process either the complete or vehicle only records for the given time period from

• Complete Telematics Export Format GET /v1.0/export/allrecords/status{?dayOf} OR

• Vehicle-Only Telematics Export Format GET /v1.0/export/vehiclerecords/status{?dayOf}

For example, estimates of received data latency can be obtained by processing downloads from either of the above and summarizing the difference between the created timestamps and server timestamps.

Monitor Vehicle Status Events ¶

Motor freight carriers need access to raw J1939 vehicle frames for various custom fleet management tasks. To process the raw frames in ‘real-time’ they follow a feed using

• Follow Fleet Status Events GET /v1.0/fleet/statusevents/feed{?token} for all fleet vehicles.

NB: These vehicle status events are largely raw J1939 data. Open Telematics API makes no requirements on how the TSP determines what raw frames to send via this interface. It is expected that the motor freight carrier and the TSP configure/agree-to the set of raw data via some other mechanism.

Furthermore, truck leasing companies need to have access to this raw vehicle status data via single-purpose accounts at the motor freight carrier’s TSP. i.e. the truck leasing company does not require access to any other information so the account has a single role and no further permissions. For this, the leasing companies also use

• Follow Fleet Status Events GET /v1.0/fleet/statusevents/feed{?token} for all fleet vehicles.

Monitor Fleet Battery Status ¶

Motor freight carriers need to monitor the battery voltage of their fleet of vehicles.

To monitor these battery voltages in ‘real time’ they follow a feed using

• Follow Fleet Performance Events GET /v1.0/fleet/performanceevents/feed{?token} for all fleet vehicles

Alternatively, the motor freight carriers may follow a feed using

• Follow Fleet Status Events GET /v1.0/fleet/statusevents/feed{?token} for all fleet vehicles.

However, the latter may require special configuration for allowing the appropriate raw Controller Area Network (CAN) frames to be sent via the Follow Fleet Status Events GET /v1.0/fleet/statusevents/feed{?token} endpoint. Furthermore, the Follow Fleet Status Events GET /v1.0/fleet/statusevents/feed{?token} endpoint may not produce data in as many ignition states as Follow Fleet Performance Events GET /v1.0/fleet/performanceevents/feed{?token} and the Follow Fleet Performance Events GET /v1.0/fleet/performanceevents/feed{?token} may offer higher resolution on battery voltage than Follow Fleet Status Events GET /v1.0/fleet/statusevents/feed{?token}.

Authorization: Basic YWRtaW46YWRtaW4=

{
  "stops": [
    {
      "stopName": "pickup place 101",
      "stopAddress": "13 Sycamore Ave",
      "stopLocation": "37.4224764 -122.0842499",
      "stopDeadline": "2019-04-05T02:04:16Z"
    }
  ],
  "startName": "start place 202",
  "startAddress": "11 Elm Street",
  "startLocation": "37.4224764 -122.0842499",
  "routeAddInstructions": "take trailers XXX and YYY"
}

Content-Type: application/json

{
  "routeId": "c6d2ff2e69c212d4eb9d64b629a46689",
  "stopIds": [
    "b4655ce13cb3e137013d852bd7d687ae",
    "ccddb6244c28fdb9bfa726cc3e34a0eb"
  ]
}

Content-Type: text/plain

Error: vehicleId Not Found

WWW-Authenticate: Basic realm="protected"

Authentication Required

Retry-After: {implementation-defined}

Too Many Requests

Authorization: Basic YWRtaW46YWRtaW4=

{
  "stops": [
    {
      "stopName": "pickup place 101",
      "stopAddress": "13 Sycamore Ave",
      "stopLocation": "37.4224764 -122.0842499",
      "stopDeadline": "2019-04-05T02:04:16Z"
    }
  ]
}

Content-Type: application/json

{
  "routeId": "c6d2ff2e69c212d4eb9d64b629a46689",
  "stopIds": [
    "b4655ce13cb3e137013d852bd7d687ae",
    "ccddb6244c28fdb9bfa726cc3e34a0eb"
  ]
}

Content-Type: text/plain

Error: vehicleId or routeId Not Found

WWW-Authenticate: Basic realm="protected"

Authentication Required

Retry-After: {implementation-defined}

Too Many Requests

Authorization: Basic YWRtaW46YWRtaW4=

{
  "comment": "Hello, world!",
  "location": "37.4224764 -122.0842499",
  "entryArea": [
    "Hello, world!"
  ]
}

Content-Type: application/json

{
  "stopId": "b4655ce13cb3e137013d852bd7d687ae"
}

Content-Type: text/plain

Error: stopId Not Found

WWW-Authenticate: Basic realm="protected"

Authentication Required

Retry-After: {implementation-defined}

Too Many Requests

Authorization: Basic YWRtaW46YWRtaW4=

{
  "subject": "Hello, world!",
  "message": "Hello, world!"
}

Content-Type: application/json

{
  "messageReceiptId": "FC5E038D38A57032085441E7FE7010B0"
}

Content-Type: text/plain

Error: vehicleId not found

WWW-Authenticate: Basic realm="protected"

Authentication Required

Retry-After: {implementation-defined}

Too Many Requests

Authorization: Basic YWRtaW46YWRtaW4=

Content-Type: application/json

{
  "data": [
    {
      "id": "C4CA4238A0B923820DCC509A6F75849B",
      "providerId": "api.provider.com",
      "serverTime": "2019-04-05T02:04:16Z",
      "eventStart": "2019-04-05T02:04:16Z",
      "eventEnd": "2019-04-05T02:04:16Z",
      "vehicleId": "21232F297A57A5A743894A0E4A801FC3",
      "eventComment": "event type XXXX, (other details)",
      "thresholds": {
        "suddenThreshold": 3.13,
        "collisionThreshold": 12.2
      },
      "trigger": "FLAGGEDTYPE_ROLL_STABILITY",
      "gpsSpeed": 1,
      "gpsHeading": 1,
      "gpsQuality": "Hello, world!",
      "ecmSpeed": 1,
      "engineRPM": 1,
      "accelerationPercent": 0,
      "seatBelts": true,
      "cruiseStatus": {
        "ccSwitch": false,
        "ccSetSwitch": false,
        "ccCoastSwitch": false,
        "ccClutchSwitch": false,
        "ccCruiseSwitch": false,
        "ccResumeSwitch": false,
        "ccAccelerationSwitch": false,
        "ccBrakeSwitch": false,
        "ccSpeed": 1
      },
      "parkingBrake": false,
      "ignitionStatus": "Hello, world!",
      "forwardVehicleSpeed": 1,
      "forwardVehicleDistance": 100,
      "forwardVehicleElapsed": 2,
      "odometer": 1
    }
  ]
}

Content-Type: text/plain

Error: startTime or stopTime parameters invalid

Content-Type: text/plain

Error: vehicleId Not Found

WWW-Authenticate: Basic realm="protected"

Authentication Required

Requested entity is too large

Retry-After: {implementation-defined}

Too Many Requests

Authorization: Basic YWRtaW46YWRtaW4=

Content-Type: application/json

{
  "data": [
    {
      "id": "C4CA4238A0B923820DCC509A6F75849B",
      "providerId": "api.provider.com",
      "serverTime": "2019-04-05T02:04:16Z",
      "vehicleId": "21232F297A57A5A743894A0E4A801FC3",
      "dateTime": "2019-04-05T02:04:16Z",
      "location": "37.4224764 -122.0842499"
    }
  ],
  "timeResolution": "TIMERESOLUTION_MAX"
}

Content-Type: text/plain

Error: startTime or stopTime parameters invalid

Content-Type: text/plain

Error: vehicleId Not Found

WWW-Authenticate: Basic realm="protected"

Authentication Required

Requested entity is too large

Retry-After: {implementation-defined}

Too Many Requests

Authorization: Basic YWRtaW46YWRtaW4=

Content-Type: application/json

{
  "token": "Hello, world!",
  "feed": [
    {
      "id": "C4CA4238A0B923820DCC509A6F75849B",
      "providerId": "api.provider.com",
      "annotations": [
        {
          "providerId": "api.provider.com",
          "userId": {
            "userType": "USERTYPE_DRIVER",
            "userId": "63A9F0EA7BB98050796B649E85481845",
            "firstName": "John",
            "lastName": "Doe"
          },
          "comment": "note: something noteworthy",
          "dateTime": "2019-04-05T02:04:16Z"
        }
      ],
      "coDrivers": [
        "A87FF679A2F3E71D9181A67B7542122C",
        "E4DA3B7FBBCE2345D7772B0674A318D5"
      ],
      "vehicleId": "21232F297A57A5A743894A0E4A801FC3",
      "userId": {
        "userType": "USERTYPE_DRIVER",
        "userId": "63A9F0EA7BB98050796B649E85481845",
        "firstName": "John",
        "lastName": "Doe"
      },
      "distanceSinceLastValidCoordinates": 17,
      "distanceUnits": "DISTANCEUNITS_MILES",
      "deviceDateTime": "2019-04-05T02:04:16Z",
      "serverDateTime": "2019-04-05T02:04:16Z",
      "eventDateTime": "2019-04-05T02:04:16Z",
      "editDateTime": "2019-04-05T02:04:16Z",
      "odometer": 283940.23,
      "engineHours": 2323.4,
      "location": {
        "latitude": 37.4224764,
        "longitude": -122.0842499,
        "identifiedPlace": "New York",
        "identifiedState": "NY",
        "distanceFromIdentifiedPlace": 5000,
        "directionFromIdentifiedPlace": "NNE"
      },
      "reducedLocationAccuracy": false,
      "origin": "ORIGIN_AUTOMATIC",
      "shipments": [
        "AB123",
        "ZY789"
      ],
      "trailers": [
        "Trailer 1",
        "T2"
      ],
      "parentId": "D6AB4B1A2E51C28CB32BFE8982D42259",
      "sequenceId": 23,
      "eventRecordStatus": "STATE_ACTIVE",
      "eventType": "EVENTTYPE_DUTY_OFF",
      "requestedEditUser": {
        "userType": "USERTYPE_DRIVER",
        "userId": "63A9F0EA7BB98050796B649E85481845",
        "firstName": "John",
        "lastName": "Doe"
      },
      "certificationCount": 1,
      "verifyDateTime": "Hello, world!",
      "multidayBasis": 0,
      "comment": "fake Log Event for testing",
      "eventDataChecksum": "Hello, world!"
    }
  ]
}

Content-Type: text/plain

Error: token parameter invalid

WWW-Authenticate: Basic realm="protected"

Authentication Required

Retry-After: {implementation-defined}

Too Many Requests

Authorization: Basic YWRtaW46YWRtaW4=

Content-Type: application/json
X-Total-Count: {+totalCount}

{
  "data": [
    {
      "id": "C4CA4238A0B923820DCC509A6F75849B",
      "providerId": "api.provider.com",
      "serverTime": "2019-04-05T02:04:16Z",
      "vehicleId": "21232F297A57A5A743894A0E4A801FC3",
      "dateTime": "2019-04-05T02:04:16Z",
      "location": "37.4224764 -122.0842499"
    }
  ],
  "timeResolution": "TIMERESOLUTION_MAX"
}

Content-Type: text/plain

Error: page or count parameters invalid

WWW-Authenticate: Basic realm="protected"

Authentication Required

Retry-After: {implementation-defined}

Too Many Requests

Authorization: Basic YWRtaW46YWRtaW4=

Content-Type: application/json
X-Total-Count: {+totalCount}

{
  "data": [
    {
      "id": "C4CA4238A0B923820DCC509A6F75849B",
      "providerId": "api.provider.com",
      "serverTime": "2019-04-05T02:04:16Z",
      "vehicleId": "21232F297A57A5A743894A0E4A801FC3",
      "dateTime": "2019-04-05T02:04:16Z",
      "location": "37.4224764 -122.0842499"
    }
  ],
  "timeResolution": "TIMERESOLUTION_MAX"
}

Content-Type: text/plain

Error: startTime, stopTime, page or count parameters invalid

WWW-Authenticate: Basic realm="protected"

Authentication Required

Requested entity is too large

Retry-After: {implementation-defined}

Too Many Requests

Authorization: Basic YWRtaW46YWRtaW4=

Content-Type: application/json

{
  "coarseVehicleLocationTimeHistories": {
    "data": [
      {
        "id": "C4CA4238A0B923820DCC509A6F75849B",
        "providerId": "api.provider.com",
        "serverTime": "2019-04-05T02:04:16Z",
        "vehicleId": "21232F297A57A5A743894A0E4A801FC3",
        "dateTime": "2019-04-05T02:04:16Z",
        "location": "37.4224764 -122.0842499"
      }
    ],
    "timeResolution": "TIMERESOLUTION_NOT_MAX"
  },
  "flaggedVehicleFaultEvents": [
    {
      "id": "C4CA4238A0B923820DCC509A6F75849B",
      "providerId": "api.provider.com",
      "serverTime": "2019-04-05T02:04:16Z",
      "vehicleId": "21232F297A57A5A743894A0E4A801FC3",
      "location": "37.4224764 -122.0842499",
      "eventComment": "event type XXXX, (other details)",
      "triggeredDate": "2019-04-05T02:04:16Z",
      "clearedDate": "2019-04-05T02:04:16Z",
      "faultType": "FAULT_TYPE_J1708",
      "j1708Fault": {
        "failureModeIdentifier": 0,
        "messageIdentifier": 0,
        "parameterOrSubsystemIdType": "PIDORSID_PID",
        "faultCodeParameterorSubsystemId": 0
      },
      "j1939Fault": {
        "sourceAddress": 0,
        "failureModeIdentifier": 0,
        "suspectParameterNumber": 0,
        "occurences": 0
      },
      "obdIIFault": {
        "controllerCode": 0,
        "diagnosticCode": 0,
        "failureType": 0
      },
      "urgentFlag": false,
      "odometer": 0,
      "engineRpm": 0,
      "ecmSpeed": 0,
      "cruiseStatus": {
        "ccSwitch": false,
        "ccSetSwitch": false,
        "ccCoastSwitch": false,
        "ccClutchSwitch": false,
        "ccCruiseSwitch": false,
        "ccResumeSwitch": false,
        "ccAccelerationSwitch": false,
        "ccBrakeSwitch": false,
        "ccSpeed": 1
      },
      "ignitionStatus": "",
      "gpsQuality": "",
      "clearType": "CLEARTYPE_BYSYSTEMS"
    }
  ],
  "vehiclePerformanceEvents": [
    {
      "id": "C4CA4238A0B923820DCC509A6F75849B",
      "providerId": "api.provider.com",
      "serverTime": "2019-04-05T02:04:16Z",
      "eventStart": "2019-04-05T02:04:16Z",
      "eventEnd": "2019-04-05T02:04:16Z",
      "vehicleId": "21232F297A57A5A743894A0E4A801FC3",
      "eventComment": "performance event type XXXX, (other details)",
      "hours": 6.28,
      "thresholds": {
        "activeFrom": "2019-04-05T02:04:16Z",
        "activeTo": "2019-04-05T02:04:16Z",
        "rpmOverValue": 0,
        "overSpeedValue": 0,
        "excessSpeedValue": 0,
        "longIdleValue": 300,
        "hiThrottleValue": 0
      },
      "odometerStart": 0,
      "odometerEnd": 0,
      "engineTime": 0,
      "movingTime": 0,
      "startFuel": 0,
      "endFuel": 0,
      "brakeApplications": 0,
      "engineLoadStopped": 0,
      "engineLoadMoving": 0,
      "headlightTime": 0,
      "speedGovernorValue": 0,
      "batteryVoltage": 0,
      "overRpmTime": 0,
      "overSpeedTime": 0,
      "excessSpeedTime": 0,
      "longIdleTime": 0,
      "shortIdleTime": 0,
      "shortIdleCount": 0,
      "longIdleFuel": 0,
      "shortIdleFuel": 0,
      "cruiseEvents": 0,
      "cruiseTime": 0,
      "cruiseFuel": 0,
      "cruiseDistance": 0,
      "topGearValue": 0,
      "topGearTime": 0,
      "topGearFuel": 0,
      "topGearDistance": 0,
      "ptoFuel": 0,
      "ptoTime": 0,
      "seatBeltTime": 0,
      "particulateFilterStatus": "`FILTERSTATUS_REGEN_NEEDED'",
      "exhaustFluidLevel": 0,
      "overspeedLowThrottle": 0,
      "overspeedHiThrottle": 0,
      "overrpmLowThrottle": 0,
      "overrpmHiThrottle": 0,
      "lkaActive": false,
      "lkaDisable": false,
      "ldwActive": false,
      "ldwDisable": false
    }
  ],
  "vehicleFaultCodeEvents": [
    {
      "id": "C4CA4238A0B923820DCC509A6F75849B",
      "providerId": "api.provider.com",
      "serverTime": "2019-04-05T02:04:16Z",
      "vehicleId": "21232F297A57A5A743894A0E4A801FC3",
      "location": "37.4224764 -122.0842499",
      "eventComment": "event type XXXX, (other details)",
      "triggeredDate": "2019-04-05T02:04:16Z",
      "clearedDate": "2019-04-05T02:04:16Z",
      "faultType": "FAULT_TYPE_J1708",
      "j1708Fault": {
        "failureModeIdentifier": 0,
        "messageIdentifier": 0,
        "parameterOrSubsystemIdType": "PIDORSID_PID",
        "faultCodeParameterorSubsystemId": 0
      },
      "j1939Fault": {
        "sourceAddress": 0,
        "failureModeIdentifier": 0,
        "suspectParameterNumber": 0,
        "occurences": 0
      },
      "obdIIFault": {
        "controllerCode": 0,
        "diagnosticCode": 0,
        "failureType": 0
      },
      "urgentFlag": false,
      "odometer": 0,
      "engineRpm": 0,
      "ecmSpeed": 0,
      "cruiseStatus": {
        "ccSwitch": false,
        "ccSetSwitch": false,
        "ccCoastSwitch": false,
        "ccClutchSwitch": false,
        "ccCruiseSwitch": false,
        "ccResumeSwitch": false,
        "ccAccelerationSwitch": false,
        "ccBrakeSwitch": false,
        "ccSpeed": 1
      },
      "ignitionStatus": "",
      "gpsQuality": "",
      "clearType": "CLEARTYPE_BYSYSTEMS"
    }
  ]
}

Content-Type: text/plain

Error: startTime or stopTime parameters invalid

WWW-Authenticate: Basic realm="protected"

Authentication Required

Requested entity is too large

Retry-After: {implementation-defined}

Too Many Requests

Authorization: Basic YWRtaW46YWRtaW4=

Content-Type: application/json

{
  "token": "",
  "feed": {
    "coarseVehicleLocationTimeHistories": {
      "data": [
        {
          "id": "C4CA4238A0B923820DCC509A6F75849B",
          "providerId": "api.provider.com",
          "serverTime": "2019-04-05T02:04:16Z",
          "vehicleId": "21232F297A57A5A743894A0E4A801FC3",
          "dateTime": "2019-04-05T02:04:16Z",
          "location": "37.4224764 -122.0842499"
        }
      ],
      "timeResolution": "TIMERESOLUTION_NOT_MAX"
    },
    "flaggedVehicleFaultEvents": [
      {
        "id": "C4CA4238A0B923820DCC509A6F75849B",
        "providerId": "api.provider.com",
        "serverTime": "2019-04-05T02:04:16Z",
        "vehicleId": "21232F297A57A5A743894A0E4A801FC3",
        "location": "37.4224764 -122.0842499",
        "eventComment": "event type XXXX, (other details)",
        "triggeredDate": "2019-04-05T02:04:16Z",
        "clearedDate": "2019-04-05T02:04:16Z",
        "faultType": "FAULT_TYPE_J1708",
        "j1708Fault": {
          "failureModeIdentifier": 0,
          "messageIdentifier": 0,
          "parameterOrSubsystemIdType": "PIDORSID_PID",
          "faultCodeParameterorSubsystemId": 0
        },
        "j1939Fault": {
          "sourceAddress": 0,
          "failureModeIdentifier": 0,
          "suspectParameterNumber": 0,
          "occurences": 0
        },
        "obdIIFault": {
          "controllerCode": 0,
          "diagnosticCode": 0,
          "failureType": 0
        },
        "urgentFlag": false,
        "odometer": 0,
        "engineRpm": 0,
        "ecmSpeed": 0,
        "cruiseStatus": {
          "ccSwitch": false,
          "ccSetSwitch": false,
          "ccCoastSwitch": false,
          "ccClutchSwitch": false,
          "ccCruiseSwitch": false,
          "ccResumeSwitch": false,
          "ccAccelerationSwitch": false,
          "ccBrakeSwitch": false,
          "ccSpeed": 1
        },
        "ignitionStatus": "",
        "gpsQuality": "",
        "clearType": "CLEARTYPE_BYSYSTEMS"
      }
    ],
    "vehiclePerformanceEvents": [
      {
        "id": "C4CA4238A0B923820DCC509A6F75849B",
        "providerId": "api.provider.com",
        "serverTime": "2019-04-05T02:04:16Z",
        "eventStart": "2019-04-05T02:04:16Z",
        "eventEnd": "2019-04-05T02:04:16Z",
        "vehicleId": "21232F297A57A5A743894A0E4A801FC3",
        "eventComment": "performance event type XXXX, (other details)",
        "hours": 6.28,
        "thresholds": {
          "activeFrom": "2019-04-05T02:04:16Z",
          "activeTo": "2019-04-05T02:04:16Z",
          "rpmOverValue": 0,
          "overSpeedValue": 0,
          "excessSpeedValue": 0,
          "longIdleValue": 300,
          "hiThrottleValue": 0
        },
        "odometerStart": 0,
        "odometerEnd": 0,
        "engineTime": 0,
        "movingTime": 0,
        "startFuel": 0,
        "endFuel": 0,
        "brakeApplications": 0,
        "engineLoadStopped": 0,
        "engineLoadMoving": 0,
        "headlightTime": 0,
        "speedGovernorValue": 0,
        "batteryVoltage": 0,
        "overRpmTime": 0,
        "overSpeedTime": 0,
        "excessSpeedTime": 0,
        "longIdleTime": 0,
        "shortIdleTime": 0,
        "shortIdleCount": 0,
        "longIdleFuel": 0,
        "shortIdleFuel": 0,
        "cruiseEvents": 0,
        "cruiseTime": 0,
        "cruiseFuel": 0,
        "cruiseDistance": 0,
        "topGearValue": 0,
        "topGearTime": 0,
        "topGearFuel": 0,
        "topGearDistance": 0,
        "ptoFuel": 0,
        "ptoTime": 0,
        "seatBeltTime": 0,
        "particulateFilterStatus": "`FILTERSTATUS_REGEN_NEEDED'",
        "exhaustFluidLevel": 0,
        "overspeedLowThrottle": 0,
        "overspeedHiThrottle": 0,
        "overrpmLowThrottle": 0,
        "overrpmHiThrottle": 0,
        "lkaActive": false,
        "lkaDisable": false,
        "ldwActive": false,
        "ldwDisable": false
      }
    ],
    "vehicleFaultCodeEvents": [
      {
        "id": "C4CA4238A0B923820DCC509A6F75849B",
        "providerId": "api.provider.com",
        "serverTime": "2019-04-05T02:04:16Z",
        "vehicleId": "21232F297A57A5A743894A0E4A801FC3",
        "location": "37.4224764 -122.0842499",
        "eventComment": "event type XXXX, (other details)",
        "triggeredDate": "2019-04-05T02:04:16Z",
        "clearedDate": "2019-04-05T02:04:16Z",
        "faultType": "FAULT_TYPE_J1708",
        "j1708Fault": {
          "failureModeIdentifier": 0,
          "messageIdentifier": 0,
          "parameterOrSubsystemIdType": "PIDORSID_PID",
          "faultCodeParameterorSubsystemId": 0
        },
        "j1939Fault": {
          "sourceAddress": 0,
          "failureModeIdentifier": 0,
          "suspectParameterNumber": 0,
          "occurences": 0
        },
        "obdIIFault": {
          "controllerCode": 0,
          "diagnosticCode": 0,
          "failureType": 0
        },
        "urgentFlag": false,
        "odometer": 0,
        "engineRpm": 0,
        "ecmSpeed": 0,
        "cruiseStatus": {
          "ccSwitch": false,
          "ccSetSwitch": false,
          "ccCoastSwitch": false,
          "ccClutchSwitch": false,
          "ccCruiseSwitch": false,
          "ccResumeSwitch": false,
          "ccAccelerationSwitch": false,
          "ccBrakeSwitch": false,
          "ccSpeed": 1
        },
        "ignitionStatus": "",
        "gpsQuality": "",
        "clearType": "CLEARTYPE_BYSYSTEMS"
      }
    ]
  }
}