Standard Data Items

Time Stamps

All date-time values accepted or returned from APIs MUST be specified in the “complete representation” specified by ISO 8601 (section 4.3.2 in the official ISO-8601 spec) and conform to the syntax described in RFC 3339 Section 5.6. Date-time values without a zone designator or offset MUST NOT be used.

• Valid: 1985-04-12T10:15:32Z
• Valid: 1985-04-12T10:15:32+04:00
• Invalid: 1985-04-12T10:15:32 (no time zone designator or offset)

Time Ranges

For a time range, the start of the range is inclusive and the end of the range is exclusive.

In mathematical terms, a range includes time greater than or equal to the start of the range and less than the end of the range (timemin <= t < timemax). For example, a time range of 12:00:00 to 13:00:00 would include items with time stamps of 12:00:00 but would not include items with time stamps of 13:00:00.

The format of date/time ranges conforms to ISO 8601.

For example, a range of 2013-01-14T00:00:00Z/2013-01-15T00:00:00Z includes all times from and including 00:00 on January 14th up to but excluding 00:00 January 15th.

Durations

Durations express an amount of elapsed time. They can be running durations (e.g. “it’s been 32.2 seconds since the job started”) or completed durations (e.g. “it took this long to process the job”). Trimble APIs MUST represent durations as ISO 8601 period strings. Trimble APIs SHOULD use ISO 8601-compatible software libraries to parse period strings to avoid miscalculations associated with timezones and daylight savings.

Examples:

{
   "jobName": "Message Report ETL",
   "jobId": "abcdefgh-ijkl-mnop-qrst-uvwxyz012345",
   "description":"Job ran for one minute.",
   "duration": "PT1M"
}

{
   "antimatterContainmentSystem": {
      "fuelLevel": 47,
      "fieldStrength": 32.6,
      "statusMessage":"Repolarization occurred three years, six months, four days, twelve hours, thirty minutes, and five seconds ago.",
      "timeSinceRepolarization":"P3Y6M4DT12H30M5S"
   }
}

{
   "warrantyPeriod": "P12M",
   "description":"Warranty is valid for 12 months."
}

Timezones

All timezones MUST be identified by Unicode BCP 47 zone IDs (e.g., “altia”). APIs wishing to present display name for timezones MAY use Unicode BCP 47 aliases (e.g., “Europe/Tirane”), but these aliases MUST NOT be used as a primary key for the timezone.

Distances

“Distance” as a stand-alone term is ambiguous. Any data that contains a distance value MUST be disambiguated by doing the following:

• Define what the distance is
• Define what the distance is between (start and end points)

Examples

• distanceOfficeToJob
• distanceOfficeToJobMax (as long as they are in a context where Office and Job are clearly-defined locations)

Nonexamples

• Invalid: “distanceToJob”, “maxDistance” (don’t specify start and end points)

This disambiguation applies to all fields, parameters and values in all APIs.

All distances MUST be represented as floating point numbers.

All distance fields MUST qualify the distance end point of the measurement spatially or temporally (e.g., “distanceToJob”, “odometerCurrent”).

All distance fields MAY omit qualifying the distance start point if it can be inferred from the spatial or temporal context of the record the field is attached to (a vehicle’s current position in the case of “distanceToJob”, or from the time of vehicle manufacture in the case of “odometerCurrent”).

Angles

Angles SHOULD be represented in decimal degrees, following the appropriate (nonexhaustive) origin and turning sense for the angle type:

Angle Type	Origin	Turning Sense
Latitude	Equator	North Latitude is Positive
Longitude	Prime Meridian	East Longitude is Positive
Heading	Survey North	Clockwise is Positive
Bearing	Survey North	Clockwise is Positive
Course	Survey North	Clockwise is Positive

By default, heading, bearing, and course angles refer to degrees on the horizontal plane. Since angles can be used for the vertical plane, APIs requiring them MUST distinguish between the horizontal and vertical planes. For example:

{
   "speed": 112.4,
   "heading": 225.12
}

{
   "speed": 566.7,
   "horizontalBearing": 67.9,
   "verticalBearing": 11.4
}

Countries

Countries MUST be identifed by ISO 3166 alpha-2 country codes. APIs wishing to present display name for countries MAY use ISO 3166 country short names (e.g., “Afghanistan”), but these short names MUST NOT be used as a primary key for the country.

Currencies

World currencies MUST be identified by ISO 4217 currency codes.