-
Notifications
You must be signed in to change notification settings - Fork 6
/
apiary.apib
4374 lines (3131 loc) · 215 KB
/
apiary.apib
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
FORMAT: 1A
# Open Telematics API
## Acronyms
| | |
|-------|---------------------------------------------------------|
| TSPs | Telematics Service Providers |
| RAML | RESTful API Modeling Language |
| SDKs | Software Development Kits |
| OTAPI | Open Telematics API |
| IVHM | Integrated Vehicle Health Maintenance |
| CBM | Condition Based Maintenance |
| HTTP | Hyper Text Transfer Protocol |
| TLS | Transport Layer Security |
| HR | Human Resources |
| PII | Personally Identifiable Information |
| NIST | National Institute of Standards and Technology |
| URLs | Universal Resource Locators |
| ISO | International Standards Organization |
| IDs | IDentifiers |
| JSON | JavaScript Object Notation |
| IEC | International Electrotechnical Commission |
| OWASP | Open Web Application Security Project® |
| MASVS | OWASP Mobile Application Security Verification Standard |
| UTC | Coordinated Universal Time |
| ELD | Electronic Logging Devices |
| SI | International System of Units |
| RODS | Record of Duty Status |
| CAN | Controller Area Network |
| YM | Yard Move |
| PC | Personal Conveyance |
| GPS | Global Positioning System |
| ECU | Electronic Control Unit |
| SAE | Society of Automotive Engineers |
| SPN | Suspect Parameter Number |
| RPM | revolutions per minute |
| DEF | Diesel Exhaust Fluid |
| FMI | Fault Mode Indicator |
| MID | Message InDicator |
| PID | Parameter IDentifier |
| SID | System IDentifier |
| SA | Source Address |
| OBDII | On Board Diagnostics |
| CMV | Commercial Motor Vehicle |
| VIN | Vehicle Identifiaction Number |
| ECMs | Engine Control Modules |
| MSON | Markdown Syntax Object Notation |
# 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](https://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md).
The specification is pubished in various forms:
* at [github.com/nmfta-repo/nmfta-opentelematics-api](https://github.com/nmfta-repo/nmfta-opentelematics-api)
* [`apiary.apib`](https://github.com/nmfta-repo/nmfta-opentelematics-api/blob/master/apiary.apib) -- API Blueprint specification
* [`otapi.html`](http://htmlpreview.github.io/?https://github.com/nmfta-repo/nmfta-opentelematics-api/blob/master/otapi.html) -- standalone documentation rendering of the above
* here, [opentelematicsapi.docs.apiary.io](https://opentelematicsapi.docs.apiary.io), as:
* Interactive documentation
* A mock server
* at [apimatic/.../nmfta-opentelematics-api](https://www.apimatic.io/apidocs/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](https://github.com/nmfta-repo/nmfta-opentelematics-api/releases/tag/proto-0.1rc4) of this specificiation available at [github.com/nmfta-repo/nmfta-opentelematics-prototype](https://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](https://raw.githubusercontent.com/nmfta-repo/nmfta-opentelematics-api/master/Open%20Telematics%20Supported%20Use%20Cases%20Questionnaire.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](#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.
| **Fleet Managers** | **Telematics Providers** | **Independents** |
|:-------------------------:|:------------------------:|:---------------------------------------------------------------:|
| Bill Brown, SEFL | Samsara Networks, Inc. | Altaz Valani, Security Compass |
| Penske Truck Leasing | Geotab | Andrew Smith, ISE Inc. |
| Old Dominion Freight Lines| Omnitracs | Dr. Jeremy Daily, UTulsa |
| | Derek Held, Zonar Systems| |
       
# Authentication
<a id="authentication"></a>
**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.
```http
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](#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](#authorization) below).
# Authorization
<a id="authorization"></a>
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:
|Role: |Vehicle Query|Vehicle Follow|Driver Query|Driver Follow|Driver Dispatch|Driver Duty |Human Resources (HR) |Safety & Compliance (S&C) |Admin |
|-------|-------------|--------------|------------|-------------|---------------|------------|------------|------------|------------|
|Access:|`DENY/ALLOW` |`DENY/ALLOW` |`DENY/ALLOW`|`DENY/ALLOW` |`DENY/ALLOW` |`DENY/ALLOW`|`DENY/ALLOW`|`DENY/ALLOW`|`DENY/ALLOW`|
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:
| Role | Intent of assignments in the **Access Controls** tables |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| *Vehicle Query* | role has access only to vehicle collections queries and cannot access any PII |
| *Vehicle Follow* | role has access to vehicle streaming feeds and queries and cannot access any PII |
| *Driver Query* | role has access only to driver and vehicle collections queries (can access PII) |
| *Driver Follow* | role has access to driver and vehicle streaming feeds and queries (can access PII) |
| *Driver Dispatch* | role is allowed to update route info and send messages to drivers |
| *Driver Duty* | role is allowed to externaly trigger driver duty status (e.g. *Send Duty Status Changes to the TSP*) |
| *HR* | role is allowed to perform HR use cases and update Driver information |
| *S&C* | role is allowed to perform Safety and Compliance use cases and to update TSP portal user account username, password and enable/disable |
| *Admin* | role has all privileges. Intended for testing and development; should not be used in production. |
# 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](#authentication) and [Authorization](#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](#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](#authorization).
# Security Requirements for Implementors
<a id="security_requirements_for_implementors"></a>
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](https://github.com/EdOverflow/legal-bug-bounty)
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](https://github.com/ssllabs/research/wiki/SSL-and-TLS-Deployment-Best-Practices) is reccomended. The automated
tool, also by Qualys SSL Labs, at [https://www.ssllabs.com/ssltest/](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](https://www.owasp.org/index.php/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)](https://www.owasp.org/index.php/OWASP_Mobile_Security_Testing_Guide).
# Working With Dates
<a id="working_with_dates"></a>
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](https://github.com/for-GET/know-your-http-well/blob/master/status-codes.md) 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](https://developer.github.com/v3/#pagination).
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
<a id="provider_identifiers"></a>
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
<a id="extending_this_api"></a>
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](#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](#log_event_object) 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`](#get_a_translation_table) 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`](#get_a_translation_table).
# 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`](#check_current_state_of_health)
To check the past 30 days worth of states of health they use
* [Check Past 30d State of Health `GET /v1.0/health/recents`](#check_past_30d_state_of_health)
## 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}`](#complete_telematics_export_format).
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}`](#vehicle_only_telematics_export_format).
## 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}`](#complete_telematics_export_format) for more details on the file format
which should contain sufficient data for this use case in the array of [Log Event objects](#log_event_object).
## 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](#driver_object) 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}`](#get_driver_availability_factors) for a given [Driver object id](#driver_object) 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}`](#get_driver_breaks_and_waivers) a given [Driver object id](#driver_object) 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`](#update_driver_duty_status) for a given [Driver object id](#driver_object).
## 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](#driver_object) for a given driver
* a [Vehicle object id](#vehicle_object) for a given vehicle
* and because they previously [created a *Vehicle Route* `POST /v1.0/vehicles/{vehicleId}/routes`](#create_a_vehicle_route) they have both
* a *Vehicle Route object id* and
* an array of [Stop Geographic Details object id](#stop_geographic_details_object).
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}`](#get_driver_availability_factors) endpoint for a given [Driver object id](#driver_object) over a given period of time
To change the route they use
* [Update Vehicle Route `PUT /v1.0/vehicles/{vehicleId}/routes/{routeId}`](#update_vehicle_route) for a given [Vehicle object id](#vehicle_object) 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}`](#update_stop_geographic_details) for a given [Stop Geographic Details object id](#stop_geographic_details_object)
## 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](#vehicle_object) 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}`](#get_vehicle_flagged_events) for a given [Vehicle object id](#vehicle_object) 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`](#create_a_vehicle_route) for a given [Vehicle object id](#vehicle_object)
A successful creation of a route will yield a *Route object id* and an array of [Stop Geographic Details object id](#stop_geographic_details_object) 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](#driver_object) for a given driver
* and because they previously [created a *Vehicle Route* `POST /v1.0/vehicles/{vehicleId}/routes`](#create_a_vehicle_route) and may have optionally
[updated the driver's Route Stop `PUT /v1.0/vehicles/{vehicleId}/routes/{routeId}`](#update_vehicle_route) or [updated the *Stop Geographic Details* `PATCH /v1.0/stops/{stopId}`](#update_stop_geographic_details)
they hence have both
* a *Vehicle Route object id* and
* a [Stop Geographic Details object id](#stop_geographic_details_object).
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}`](#follow_fleet_log_events) for all drivers
They mark trips completed based on matching a [Log Event object](#log_event_object) in the feed which matches a given
[Driver object id](#driver_object) 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}`](#get_a_stop_geographic_details_by_its_id) for a given [Stop Geographic Details object id](#stop_geographic_details_object)
## 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}`](#follow_dispatch_messages)
## 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}`](#get_fleet_latest_locations)
Then, for each [Vehicle object id](#vehicle_object) which lies within the geographic area they send it a message using
* [Send Message to a Vehicle `POST /v1.0/vehicles/{vehicleId}/message`](#send_message_to_a_vehicle) for a given [Vehicle object id](#vehicle_object)
## 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](#vehicle_object) 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`](#send_message_to_a_vehicle) for a given [Vehicle object id](#vehicle_object)
## 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}`](#get_fleet_location_history) 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](#log_event_object) using
* [Follow Fleet Log Events `GET /v1.0/event_logs/feed{?token}`](#follow_fleet_log_events) 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}`](#get_driver_breaks_and_waivers) for each [Driver object id](#driver_object) 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`](#update_driver_duty_status) endpoint for a given [Driver object id](#driver_object).
and the duty status changes are reflected in the [Follow Fleet Log Events `GET /v1.0/event_logs/feed{?token}`](#follow_fleet_log_events) 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}`](#update_driver_info) for a given [Driver object id](#driver_object).
## 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](#log_event_object) using
* [Follow Fleet Log Events `GET /v1.0/event_logs/feed{?token}`](#follow_fleet_log_events) 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}`](#get_fleet_vehicle_info) 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}`](#follow_fleet_vehicle_info) 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}`](#get_fleet_location_history) 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](#driver_object) 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}`](#get_driver_performance_summaries) for a given [Driver object id](#driver_object) 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](#driver_performance_summary_object) are associate they use
* [Update Driver TSP Portal Account `PATCH /v1.0/drivers/{driverId}/driverportaluser`](#update_driver_tsp_portal_account) for a given [Driver object id](#driver_object)
## 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}`](#follow_fleet_fault_code_events) for all fleet vehicles
To dispatch assistance to the location of a given [Vehicle object id](#vehicle_object) -- 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}`](#get_vehicle_location_history) for a given [Vehicle object id](#vehicle_object) 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`](#get_data_qualities_statement).
## 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}`](#complete_telematics_export_format) OR
* [Vehicle-Only Telematics Export Format `GET /v1.0/export/vehiclerecords/status{?dayOf}`](#vehicle_only_telematics_export_format)
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}`](#follow_fleet_status_events) 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}`](#follow_fleet_status_events) 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}`](#follow_fleet_performance_events) 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}`](#follow_fleet_status_events) 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}`](#follow_fleet_status_events) endpoint. Furthermore, the [Follow Fleet Status Events `GET /v1.0/fleet/statusevents/feed{?token}`](#follow_fleet_status_events)
endpoint may not produce data in as many ignition states as [Follow Fleet Performance Events `GET /v1.0/fleet/performanceevents/feed{?token}`](#follow_fleet_performance_events)
and the [Follow Fleet Performance Events `GET /v1.0/fleet/performanceevents/feed{?token}`](#follow_fleet_performance_events) may offer higher resolution on battery
voltage than [Follow Fleet Status Events `GET /v1.0/fleet/statusevents/feed{?token}`](#follow_fleet_status_events).
## Data Structures
### Open Telematics Data Model Objects (object)
All the objects that follow are forward definitions of the data object types used in the API.
Note 1: due to the way the apiary documentation renderer works, this section will not be visible when rendered there.
See the *Open Telematics Data Model* for a section designed to be rendered in apiary.
Note 2: And this object definition exists just to tell you about that limitation.
Note 3: Also, any descriptions put on these data structures will not get rendered properly, so consult the *Open
Telematics Data Model* for object descriptions as well.
### User Identifier (object)
+ userType : `USERTYPE_DRIVER` (required, enum[string]) - is this user a driver or other type of user
+ Members
+ `USERTYPE_DRIVER` - this user is a driver; the `userId` field is a `driverId`
+ `USERTYPE_SUPPORT` - this user is support personnel; the `userId` field is an opaque identifier which is proprietary to the TSP
+ userId : `63A9F0EA7BB98050796B649E85481845` (required, string) - The id of the driver who created this log.
+ firstName : `John` (string) - user first name
+ lastName : `Doe` (string) - user last name
### Annotation Log (object)
+ providerId : `api.provider.com` (required, string) - The unique 'Provider ID' of the TSP.
+ userId (required, User Identifier) - The id of the driver or support personnel that created this log.
+ comment : `note: something noteworthy` (required, string) - The annotation text associated with the log.
+ dateTime : `2019-04-05T02:04:16Z` (required, string) - Date and time for this annotation log
### Compliance Location (object)
+ latitude : 37.4224764 (required, number) - the latitude of this location
+ longitude : `-122.0842499` (required, number) - the longitude of this location
+ identifiedPlace : `New York` (string) - place name of the identified geo-location
+ identifiedState : `NY` (string) - state/province abbreviate of identified geo-location
+ distanceFromIdentifiedPlace : `5000` (number) - distance from the identified geo-location, in units given by the `distanceUnits` field
+ directionFromIdentifiedPlace : `NNE` (string) - cardinal direction from the identified geo-location
### Log Event (object)
+ id : `C4CA4238A0B923820DCC509A6F75849B` (required, string) - The unique identifier for the specific Entity object in the system.
+ providerId : `api.provider.com` (required, string) - The unique 'Provider ID' of the TSP.
+ annotations (array[Annotation Log], fixed-type) - The list of AnnotationLog(s) which are associated with this log.
+ coDrivers : `A87FF679A2F3E71D9181A67B7542122C`, `E4DA3B7FBBCE2345D7772B0674A318D5` (array[string], fixed-type) - The list of the co-driver User(s) for this log; may only be populated in day end log events
+ vehicleId : `21232F297A57A5A743894A0E4A801FC3` (required, string) - The vehicle id associated with this log.
+ userId (required, User Identifier) - The id of the driver or support personnel who created this log.
+ distanceSinceLastValidCoordinates : 17.0 (required, number) - The distance traveled since the last valid latitude, longitude pair the ELD measured with required accuracy in the ELD mandate, in units given by the `distanceUnits` field. TSPs may provide distance in miles or in kilometres but are not required to provide both.
+ distanceUnits : `DISTANCEUNITS_MILES` (required, enum[string]) - The units of distance used to record the `distanceSinceLastValidCoordinates` field and all other distances in the Log Event object. Units are specified in the Log Events so that the `eventDataChecksum` field can be unchangde from the value reported by a telematics device.
+ Members
+ `DISTANCEUNITS_MILES` - distance measured in miles (mi)
+ `DISTANCEUNITS_KILOMETRES` - distance measured in kilometres (km)
+ deviceDateTime : `2019-04-05T02:04:16Z` (string) - Date and time from the telematics device ; will be omitted for objects not originating on a telematics device
+ serverDateTime : `2019-04-05T02:04:16Z` (required, string) - Date and time when this object was received at the TSP
+ eventDateTime : `2019-04-05T02:04:16Z` (required, string) - the date and time of this log event; e.g. the time when a duty status change occurs
+ editDateTime : `2019-04-05T02:04:16Z` (string) - The date and time this log event was edited. If the log has not been edited, this will not be set.
+ odometer : 283940.23 (number) - The odometer reading of the vehicle at the time of the log, in m.
+ engineHours : 2323.4 (number) - The total operational hours of the vehicle's engine since its inception at the time of the log.
+ location (required, Compliance Location) - An object with the location information for the log data, more details than lat/long for compliance purposes
+ reducedLocationAccuracy : false (required, boolean) - A flag (True or False) indicating if there was reduced location accuracy at the time of this event.
+ origin : `ORIGIN_AUTOMATIC` (required, enum[string]) - The Origin from where this log originated.
+ Members
+ `ORIGIN_AUTOMATIC` - Automatic recorded by device
+ `ORIGIN_MANUAL` - Manual entry by driver.
+ `ORIGIN_OTHERUSER` - Other authenticated user.
+ `ORIGIN_UNASSIGNED` - Unassigned driver.
+ shipments : `AB123`, `ZY789` (array[string], fixed-type) - The list of IDs or document numbers for shipments being transported at the time of the log. Required, if available, for engine powerup or engine shutdown logs.
+ trailers : `Trailer 1`, `T2` (array[string], fixed-type) - The list of trailer IDs attached to the vehicle at the time of the log. Required, if available, for engine powerup or engine shutdown logs.
+ parentId : `D6AB4B1A2E51C28CB32BFE8982D42259` (string) - The Id of the parent Log Event. Used when a Log Event is edited. When returning history, this field will be populated.
+ sequenceId : 23 (required, number) - The sequence number, which is used to generate the sequence ID.
+ eventRecordStatus : `STATE_ACTIVE` (required, enum[string]) - The State of the Log Event record.
+ Members
+ `STATE_ACTIVE` - The log is active and has been accepted by the driver.
+ `STATE_INACTIVE` - The log is inactive. It has been removed or it is the modification history of a log.
+ `STATE_REJECTED` - The log is a rejected edit request from another user.
+ `STATE_REQUESTED` - The log is a pending edit request from another user.
+ eventType : `EVENTTYPE_DUTY_OFF` (required, enum[string]) - The type of the Log Event, representing the driver's duty status and other states. When combined with the `reducedLocationAccuracy` field can be used to create event codes and subcodes for compliance.
+ Members
+ `EVENTTYPE_DUTY_OFF` - Off-duty status.
+ `EVENTTYPE_DUTY_OFF_WT` - Wait time oil well driver status.
+ `EVENTTYPE_DUTY_SB` - Sleeper berth status.
+ `EVENTTYPE_DUTY_D` - Drive status.
+ `EVENTTYPE_DUTY_ON` - On-duty status.
+ `EVENTTYPE_INDICATION_PC` - Personal conveyance driver status.
+ `EVENTTYPE_INDICATION_YM` - Yard move driver status.
+ `EVENTTYPE_INDICATION_NONE` - Cleared indication (e.g. no Yard Move (YM) or Personal Conveyance (PC) or any other indication)
+ `EVENTTYPE_ENGINE_POWERUP` - Engine power up record.
+ `EVENTTYPE_ENGINE_SHUTDOWN` - Engine shutdown record.
+ `EVENTTYPE_INTERMEDIATE` - Intermediate Log Event.
+ `EVENTTYPE_DRIVER_LOGIN` - User login record.
+ `EVENTTYPE_DRIVER_LOGOFF` - User logout record.
+ `EVENTTYPE_MALFUNCTION_POWERCOMPLIANCE` - Engine power status engages ELD within 1 minute.
+ `EVENTTYPE_MALFUNCTION_ENGINESYNCCOMPLIANCE` - Occurs when engine information (power, motion, distance, and hours) cannot be obtained by ELD.
+ `EVENTTYPE_MALFUNCTION_TIMINGCOMPLIANCE` - When ELD date and time exceeds 10 minute offset from UTC.
+ `EVENTTYPE_MALFUNCTION_POSITIONINGCOMPLIANCE` - ELD continually fails to acquire valid position measurement.
+ `EVENTTYPE_MALFUNCTION_DATARECORDINGCOMPLIANCE` - Storage capacity is reached, or missing data elements exist.
+ `EVENTTYPE_MALFUNCTION_DATATRANSFERCOMPLIANCE` - Transfer of data fails to complete.
+ `EVENTTYPE_MALFUNCTION_OTHERCOMPLIANCE` - Other instances of Malfunction.
+ `EVENTTYPE_MALFUNCTION_NONE` - Clear previous instances of Malfunction.
+ `EVENTTYPE_DIAGNOSTIC_POWERDATA` - Power data diagnostic event
+ `EVENTTYPE_DIAGNOSTIC_ENGINESYNCDATA` - Engine synchronization data diagnostic
+ `EVENTTYPE_DIAGNOSTIC_MISSINGELEMENT` - Missing data elements.
+ `EVENTTYPE_DIAGNOSTIC_DATATRANSFERDATA` - Data transfer data diagnostic event
+ `EVENTTYPE_DIAGNOSTIC_UNIDENTIFIEDDRIVINGRECORDS` - More than 30 minutes of driving with unidentified driving.
+ `EVENTTYPE_DIAGNOSTIC_OTHER` - Other identified diagnostic event
+ `EVENTTYPE_DIAGNOSTIC_NONE` - Clear previous instance of Diagnostic
+ `EVENTTYPE_CERTIFICATION` - Driver certification event, can be multiple -- see `certificationCount`
+ `EVENTTYPE_DEVICE_CONNECTED` - System log for device power connection.
+ `EVENTTYPE_DEVICE_DISCONNECTED` - System log for device power disconnection.
+ `EVENTTYPE_EXEMPTION_OFFDUTYDEFERRAL` - Exemption off duty deferral.
+ `EVENTTYPE_EXEMPTION_ADVERSEWEATHER` - Adverse weather and driving conditions exemption.
+ `EVENTTYPE_EXEMPTION_16H` - Exemption 16 hour.
+ requestedEditUser (User Identifier) - The ID of the non-driver, authenticated user that requested an edit to this log (i.e. has USERTYPE_SUPPORT set).
+ certificationCount (number) - a certification count asssociated with driver certification (`EVENTTYPE_CERTIFICATION`) events -- serialized into ELD Event Code, see ELD 7.20
+ verifyDateTime (string) - The date and time the log was verified. If the log is unverified, this will not be set. This is the same as log certification. This will be the last certification date.
+ multidayBasis : 0 (number) - Multiday basis (7 or 8) used by the motor carrier to compute cumulative duty hours
+ comment : `fake Log Event for testing` (string) - A textual field that may be populated with information pertaining to the creation of an ELD output file
+ eventDataChecksum (required, string) - The hexidecimal value result of a bitwise exclusive OR(XOR) operation using Table 3 of the ELD mandate
### Stop Geographic Details (object)
+ id : `C4CA4238A0B923820DCC509A6F75849B` (required, string) - The unique identifier for the specific Entity object in the system.
+ providerId : `api.provider.com` (required, string) - The unique 'Provider ID' of the TSP.
+ serverTime : `2019-04-05T02:04:16Z` (required, string) - Date and time when this object was received at the TSP
+ stopName : `pickup place 101` (required, string) - a name for this location
+ address : `13 Sycamore Ave` (string) - an optional street address
+ comment (string) - an optional comment
+ location : ` 37.4224764 -122.0842499` (required, string) - the location of the delivery date at this stop
+ entryArea (array[string], fixed-type) - optional geographic location polygon detailing the entryway area for this stop
### Vehicle Location Time (object)
+ id : `C4CA4238A0B923820DCC509A6F75849B` (required, string) - The unique identifier for the specific Entity object in the system.
+ providerId : `api.provider.com` (required, string) - The unique 'Provider ID' of the TSP.
+ serverTime : `2019-04-05T02:04:16Z` (required, string) - Date and time when this object was received at the TSP
+ vehicleId : `21232F297A57A5A743894A0E4A801FC3` (required, string) - The vehicle id associated with this Location Time
+ dateTime : `2019-04-05T02:04:16Z` (required, string) - time
+ location : ` 37.4224764 -122.0842499` (required, string) - location
### Vehicle Location Time History (object)
+ data (required, array[Vehicle Location Time], fixed-type) - array of Location Times representing the vehicle's location over time.
+ timeResolution : `TIMERESOLUTION_MAX` (required, enum[string], fixed) - a status variable to indicate if this time history has a higher available resolution at the TSP
+ Members
+ `TIMERESOLUTION_MAX` - This is at the highest available time resolution
+ `TIMERESOLUTION_NOT_MAX` - This is not at the highest available time resolution