Schema
baseEvent
baseEvent
components:
schemas:
baseEvent:
title: Base event
description: |
Common properties for events.
properties:
trackingId:
description: |
This is a unique ID associated with the device data in HERE Tracking.
The `trackingId` gets assigned to a device when the device is claimed by a user.
For events associated with shipment the `trackingId` contains shipment ID.
type: string
minLength: 1
maxLength: 50
timestamp:
description: |
Event time. Milliseconds elapsed since 1 January 1970 00:00:00 UTC.
type: integer
minimum: 2
maximum: 4102448400000
ruleId:
description: |
UUIDv4 which identifies the rule which triggers the event.
type: string
format: uuid
initialState:
description: |
Events with the `initialState` property set as `true` are generated when the rule is
evaluated for the first time. It indicates the fact that this is the initial evaluation
state, which would serve as a starting point for the subsequent rule evaluations.
The rest of the rule events would represent a transition of a device or a shipment or
a geofence from one state to another and their `initialState` property will be set to `false`.
type: boolean
required:
- trackingId
- timestamp
- ruleId
- initialStatebooleanSensorEvent
booleanSensorEvent
openapi: 3.0.0
info:
version: 1.0.0
title: Boolean sensor event
description: |
Definition for the booleanSensorEvent.
paths: {}
components:
schemas:
booleanSensorEvent:
title: Boolean event
description: |
Events generated by online rule or by sensors that report boolean data (attach, tamper).
allOf:
- $ref: 'baseEvent.yml#/components/schemas/baseEvent'
- $ref: '#/components/schemas/booleanProperties'
booleanProperties:
properties:
eventSource:
description: |
The event source rule type.
type: string
enum:
- attach
- tamper
- online
eventType:
type: string
enum:
- FALSE_TO_TRUE
- TRUE_TO_FALSE
required:
- eventSource
- eventTypedetentionEvent
detentionEvent
openapi: 3.0.0
info:
version: 1.0.0
title: Detention event
description: |
Definition for the detentionEvent.
paths: {}
components:
schemas:
detentionEvent:
title: Detention event
description: |
Events generated when a device has been stationary for longer than the specified
threshold duration.
allOf:
- $ref: 'baseEvent.yml#/components/schemas/baseEvent'
- $ref: '#/components/schemas/detentionProperties'
detentionProperties:
properties:
eventSource:
description: |
The event source: detention rule
type: string
enum:
- detention
eventType:
type: string
enum:
- DETENTION_STARTED
- DETENTION_ENDED
required:
- eventSource
- eventTypedwellingEvent
dwellingEvent
openapi: 3.0.0
info:
version: 1.0.0
title: Dwelling event
description: |
Definition for the dwellingEvent.
paths: {}
components:
schemas:
dwellingEvent:
title: Dwelling event
description: |
Events generated by a device that has dwelled inside a geofence for longer than specified
threshold duration
allOf:
- $ref: 'baseEvent.yml#/components/schemas/baseEvent'
- $ref: '#/components/schemas/dwellingProperties'
dwellingProperties:
properties:
eventSource:
type: string
description: |
The event source: dwelling rule
enum:
- dwelling
eventType:
type: string
enum:
- DWELLING_STARTED
- DWELLING_ENDED
geofenceId:
description: |
An ID of a geofence that triggered the dwelling event
type: string
format: uuid
required:
- eventSource
- eventType
- geofenceIdgeofenceEvent
TITLE_GOES_HERE
openapi: 3.0.0
info:
version: 1.0.0
title: Geofence event
description: |
Definition for the geofenceEvent.
paths: {}
components:
schemas:
geofenceEvent:
title: Geofence event
description: |
Events generated by device crossing the geofence border.
allOf:
- $ref: 'baseEvent.yml#/components/schemas/baseEvent'
- $ref: '#/components/schemas/geofenceProperties'
geofenceProperties:
type: object
properties:
eventSource:
description: |
The event source: geofence rule
type: string
enum:
- geofence
eventType:
type: string
enum:
- INSIDE_GEOFENCE
- OUTSIDE_GEOFENCE
required:
- eventSource
- eventTypeinputStreamIngestion
inputStreamIngestion
openapi: 3.0.0
info:
version: 1.0.0
title: Input stream ingestion
description: |
Definition for messages sent to input streams.
paths: {}
components:
schemas:
inputStreamIngestion:
description: Input stream ingestion object
type: object
additionalProperties: false
required:
- requestId
- type
- version
- data
properties:
requestId:
type: string
format: uuid
description: |
ID used for tracing requests. Used for logging and error reporting.
Must be a valid UUIDv4.
type:
description: Type of the input data, identifies the used data format.
type: string
enum:
- event
- telemetry
version:
description: Data format version.
type: string
enum:
- '1.0'
data:
oneOf:
- $ref: '#/components/schemas/eventDataArray'
- $ref: '#/components/schemas/telemetryData'
eventDataArray:
type: array
items:
$ref: '#/components/schemas/eventData'
maxItems: 100
eventData:
oneOf:
- $ref: '#/components/schemas/inputStreamLocationEvent'
inputStreamLocationEvent:
title: External location event from input stream
type: object
additionalProperties: false
required:
- timestamp
- eventSource
- eventType
- shipment
- location
properties:
timestamp:
description: Time when the shipment entered/exited the location.
type: string
format: date-time
eventSource:
description: The event source type.
type: string
enum:
- location
eventType:
description: Type of the event.
type: string
enum:
- enter
- exit
shipment:
description: Shipment which entered/exited the location.
oneOf:
- type: object
properties:
id:
description: Shipment ID
type: string
pattern: '^SHP-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$'
- type: object
properties:
extId:
description: Unique identifier for identifying the shipment in external systems
type: string
maxLength: 50
segment:
description: Segment for which the location is associated to.
oneOf:
- type: object
properties:
id:
description: Segment ID
type: string
pattern: '^SEG-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$'
- type: object
properties:
extId:
description: External segment ID
type: string
maxLength: 50
location:
description: Location for the event.
oneOf:
- type: object
properties:
id:
description: Location ID
type: string
pattern: '^LOC-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$'
- type: object
properties:
extId:
description: External location ID in external service
type: string
minLength: 1
maxLength: 100
metadata:
description: Metadata object may contain additional customer specific information.
type: object
telemetryData:
type: objectlocationEvent
locationEvent
openapi: 3.0.0
info:
version: 1.0.0
title: Location event
description: |
Definition for the locationEvent.
paths: {}
components:
schemas:
locationEvent:
title: Location event
description: |
Events generated by shipment entering or exiting a location.
allOf:
- $ref: 'baseEvent.yml#/components/schemas/baseEvent'
- $ref: '#/components/schemas/locationEventProperties'
locationEventProperties:
type: object
properties:
eventSource:
description: |
The event source rule type.
type: string
enum:
- location
eventType:
type: string
enum:
- enter
- exit
trigger:
description: |
Tells if the event is triggered externally (via input stream) or internally.
type: string
enum:
- external
- internal
extOrderId:
description: Unique identifier for identifying the shipment in external systems
type: string
maxLength: 50
segmentIndex:
description: Segment index (starting from 0)
type: integer
minimum: 0
segmentId:
description: Segment ID
type: string
pattern: '^SEG-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$'
extSegmentId:
description: External segment ID
type: string
maxLength: 50
locationId:
description: Location ID
type: string
pattern: '^LOC-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$'
extLocationId:
description: External location ID in external service
type: string
minLength: 1
maxLength: 100
metadata:
description: Metadata object may contain additional customer specific information.
type: object
required:
- eventSource
- eventType
- trigger
- locationIdoutputStreamEvents
outputStreamEvents
openapi: 3.0.0
info:
version: 1.0.0
title: Output stream events
description: |
Definition for events sent to output streams. The definition is in outputStreamEvents.
paths: {}
components:
schemas:
outputStreamEvents:
title: Output stream events
description: Output stream events object
type: object
additionalProperties: false
required:
- type
- version
- events
- correlationId
properties:
type:
description: Type of the input data, identifies the used data format.
type: string
enum:
- events
version:
description: Data format version.
type: string
enum:
- '1.0'
events:
type: array
items:
oneOf:
- $ref: 'booleanSensorEvent.yml#/components/schemas/booleanSensorEvent'
- $ref: 'rangeSensorEvent.yml#/components/schemas/rangeSensorEvent'
- $ref: 'valueSensorEvent.yml#/components/schemas/valueSensorEvent'
- $ref: 'geofenceEvent.yml#/components/schemas/geofenceEvent'
- $ref: 'locationEvent.yml#/components/schemas/locationEvent'
- $ref: 'stockEvent.yml#/components/schemas/stockEvent'
- $ref: 'dwellingEvent.yml#/components/schemas/dwellingEvent'
- $ref: 'detentionEvent.yml#/components/schemas/detentionEvent'
- $ref: 'utilizationEvent.yml#/components/schemas/utilizationEvent'
- $ref: 'shipmentEtaChangeEvent.yml#/components/schemas/shipmentEtaChangeEvent'
- $ref: 'shipmentScheduleEvent.yml#/components/schemas/shipmentScheduleEvent'
- $ref: 'shipmentStateChangeEvent.yml#/components/schemas/shipmentStateChangeEvent'
correlationId:
type: string
formt: uuid
description: |
ID used for correlating requests within HERE Tracking.
Used for logging and error reporting.
Must be a valid UUIDv4.
outputStreamTraces
outputStreamTraces
openapi: 3.0.0
info:
version: 1.0.0
title: Output stream traces
description: >-
Definition for traces sent to output streams. The definition is in
outputStreamTraces.
components:
schemas:
outputStreamTraces:
description: Output stream traces object
type: object
additionalProperties: false
required:
- type
- version
- traces
- trackingId
- correlationId
properties:
type:
description: Type of the output data, identifies the used data format.
type: string
enum:
- traces
version:
description: Data format version.
type: string
enum:
- '1.0'
traces:
type: array
items:
description: A trace sample reported by the device.
type: object
properties:
payload:
type: object
description: |
A free format JSON object.
The maximum size is 1000B.
position:
type: object
description: The device location
properties:
accuracy:
description: >-
Uncertainty circle radius in meters (degree of confidence
according to the 'confidence' parameter).
type: number
minimum: 0
alt:
description: >-
Altitude in meters (referenced to the WGS-84 ellipsoid)
negative or positive.
type: number
altaccuracy:
description: >-
Uncertainty of the altitude estimate in meters (degree of
confidence according to the 'confidence' parameter).
type: number
minimum: 0
confidence:
description: >-
Confidence level in percent for the accuracy/uncertainty.
If not specified, the default is 68 (this corresponds to a
68% probability that the true position is within the
accuracy/uncertainty radius of the position; the higher
the number, the greater the confidence level).
type: integer
minimum: 50
maximum: 95
heading:
description: >-
GPS/GNSS heading in degrees, clockwise from true north.
You must specify a value for this item when you specify a
value for speed.
type: integer
minimum: 0
maximum: 359
floor:
description: The building where the measurements were taken
type: object
required:
- id
- name
- level
properties:
level:
description: The floor in the building in integer format
type: number
minimum: -999
maximum: 999
id:
description: The building id
type: string
minimum: 1
maximum: 100
name:
description: The building name
type: string
minimum: 1
maximum: 255
lat:
description: >-
Latitude in WGS-84 format, decimal representation ranging
from -90 to 90.
type: number
minimum: -90
maximum: 90
lng:
description: >-
Longitude in WGS-84 format, decimal representation ranging
from -180 to 180.
type: number
minimum: -180
maximum: 180
satellitecount:
description: >-
Number of GPS/GNSS satellites used for the calculation of
the position fix. ('gnss' position type only)
type: integer
minimum: 1
maximum: 50
speed:
description: >-
GPS/GNSS speed of the device (m/s). One must specify a
value for this item when one specifies a value for
heading.
type: integer
minimum: 0
type:
description: >-
Position type, 'gnss' (satellite based), 'cell' or 'wlan'
(network based)
type: string
wlancount:
description: >-
The total number of observed WLAN APs in the scan used for
producing the position. ('wlan' position type only)
type: integer
minimum: 1
maximum: 254
timestamp:
description: Timestamp of the position
type: integer
minimum: 2
maximum: 4102448400000
required:
- lat
- lng
- accuracy
system:
type: object
properties:
computed:
description: >-
Values computed by HERE Tracking based on other data
available.
properties:
moving:
description: >
Asset is considered moving if the positions of two
consecutive trace points differ more
than the combined positioning accuracy + 100 meters.
type: boolean
outlier:
description: >
Indicates that HERE Tracking detected position to be a
possible outlier.
type: object
properties:
reason:
description: >-
Reason why position was considered to be an
outlier.
type: string
correctedPosition:
description: HERE Tracking estimate of more correct position.
type: object
properties:
accuracy:
description: >-
Uncertainty circle radius in meters (degree of
confidence according to the 'confidence'
parameter).
type: number
minimum: 0
lat:
description: >-
Latitude in WGS-84 format, decimal
representation ranging from -90 to 90.
type: number
minimum: -90
maximum: 90
lng:
description: >-
Longitude in WGS-84 format, decimal
representation ranging from -180 to 180.
type: number
minimum: -180
maximum: 180
timestamp:
type: integer
description: >-
Milliseconds elapsed since 1 January 1970
00:00:00 UTC.
minimum: 2
maximum: 4102448400000
required:
- accuracy
- lat
- lng
required:
- reason
phoneNumber:
type: string
pattern: ^\+[1-9]\d{1,14}$
description: >
The phone number of the device's SIM card in the
international E.164 format. All the country codes should
be prefixed a with "+" instead of "00".
example: '+491234567890'
imsi:
type: string
pattern: ^[0-9]{1,15}$
description: |
The IMSI of the device's SIM card.
example: '123456789012345'
iccid:
type: string
minLength: 18
maxLength: 22
description: SIM card integrated circuit card identifier (ICCID)
client:
description: |
Information about the client device.
type: object
properties:
manufacturer:
description: Manufacturer of the device (hardware)
type: string
minLength: 2
maxLength: 50
model:
description: Model of the device (hardware)
type: string
minLength: 1
maxLength: 50
firmware:
description: Device firmware version information
type: string
minLength: 1
maxLength: 150
name:
description: Name of the client software accessing the HERE API
type: string
minLength: 3
maxLength: 50
version:
description: >-
Version of the client software in format X.Y.Z, where
X [0..255] is a major, Y [0..255] is a minor, and Z
[0..65535] is a build version number. Increase the
version/build number for each release of the client.
type: string
minLength: 3
maxLength: 60
platform:
description: >-
Software platform information of the device, for
example operating system name and version.
type: string
minLength: 3
maxLength: 50
modules:
description: Software information of all updateable chips.
type: array
maxItems: 10
items:
description: Software information of an updateable chip.
type: object
properties:
manufacturer:
type: string
description: Manufacturer name
minLength: 2
maxLength: 50
model:
type: string
description: Model or chip name
minLength: 1
maxLength: 50
firmwareVersion:
type: string
description: Installed firmware version
minLength: 3
maxLength: 60
diskquota:
description: Available disk quota in kilobytes.
type: number
minimum: 0
diagnosticscode:
description: Device diagnostics code.
type: number
homenetwork:
description: >-
Information about subscriber home network - 3GPP
MCC+MNC or 3GPP2 SID+NID. Dual-SIM devices can provide
information on both subscriptions.
type: array
maxItems: 2
items:
description: >-
Network information. Either MCC + MNC or SID + NID
attribute pair is required.
type: object
properties:
mcc:
description: Mobile Country Code
type: integer
minimum: 200
maximum: 999
mnc:
description: Mobile Network Code
type: integer
minimum: 0
maximum: 999
sid:
description: System Id, SID
type: integer
minimum: 1
maximum: 32767
nid:
description: Network Id, NID
type: integer
minimum: 0
maximum: 65535
hasAttachSensor:
type: boolean
description: >-
True if a device has a sensor to detect if the device
is attached to or detached from an object.
hasNoBattery:
type: boolean
description: False if a device has a battery.
hasHumiditySensor:
type: boolean
description: True if a device has a sensor to measure humidity.
hasPressureSensor:
type: boolean
description: True if a device has a sensor to measure pressure.
hasTamperSensor:
type: boolean
description: >-
True if a device has a sensor to detect if device is
disassembled.
hasTemperatureSensor:
type: boolean
description: True if a device has a sensor to measure temperature.
hasAccelerometerSensor:
type: boolean
description: True if a device has a sensor to measure acceleration.
accelerometerSensorRange:
description: >
Specifies the range of measurable acceleration,
representation
unit g (9.8 m/s^2). If more than one accelerometer is
available,
each element in the list will represent individual
accelerometer.
Each value represents a single "+/-" range.
For example, value 2 means that sensor is capable to
measure
acceleration within the range of [-2 g, +2 g].
type: array
maxItems: 5
items:
type: integer
minimum: -1000
maximum: 1000
example:
manufacturer: Samsung
model: SM-G930F
firmware: heroltexx...
name: HERE Tracker
version: 1.6.1
platform: Android
diskquota: 256
diagnosticscode: 0
homenetwork: []
hasAttachSensor: true
hasNoBattery: false
hasHumiditySensor: true
hasPressureSensor: true
hasTamperSensor: true
hasTemperatureSensor: true
hasAccelerometerSensor: true
accelerometerSensorRange:
- 2
stateVersion:
description: >
The version of the state of a device. This should be
incremented only by HERE Tracking.
type: integer
minimum: 0
reportedSensorData:
description: |
The last known device sensor data reported by the device.
type: object
properties:
accelerationG:
type: number
description: A g-force value of acceleration.
minimum: -100
maximum: 100
deviceIsAttached:
type: boolean
description: True if device is attached to an object.
deviceIsStationary:
type: boolean
description: True if device hasn't detected movement.
batteryIsCharging:
type: boolean
description: True if device battery is charging.
batteryLevel:
type: integer
description: A value of percentage battery level.
minimum: 0
maximum: 100
pressureHpa:
type: number
description: A value of pressure in hectopascal.
minimum: 300
maximum: 1500
relativeHumidity:
type: number
description: A value of relative humidity in percent.
minimum: 0
maximum: 100
deviceIsTampered:
type: boolean
description: True if device is tampered.
temperatureC:
type: number
description: A value of temperature in celcius.
minimum: -70
maximum: 100
tiltDegree:
type: number
description: A value of tilt in degrees.
mode:
description: >
Tracker mode status of the device.
When a tracker is in normal mode, it can send telemetry
and, for
example, use its GNSS receiver if it has one.
A tracker switches into flight mode once it detects that
it's in an
airplane, and leaves that mode once the airplane lands.
Transport mode has to be triggered by the user, and it's
used,
for example, during shipping from continent to another.
Sleep mode is used when a tracker is stored in a
warehouse, and
it's triggered by entering or leaving some defined
geofence.
Power save mode can be enabled with
`system.powerSave.sendMs`
property in the desired shadow and when enabled the device
enters
power save mode when the device is not moving.
type: string
enum:
- unknown
- normal
- flight
- transport
- sleep
- powerSave
description: >
Contains device-reported sensor data and device configuration
settings.
`stateVersion` property contains the version of the last
known `desired` state seen by the device.
timestamp:
description: >
Milliseconds elapsed since 1 January 1970 00:00:00 UTC.
Specifies the time the device telemetry measurements were
taken.
type: integer
minimum: 2
maximum: 4102448400000
serverTimestamp:
description: >
Milliseconds elapsed since 1 January 1970 00:00:00 UTC.
This describes when the measurements were processed by the
backend.
maximum: 4102448400000
minimum: 2
type: integer
trackingDisabled:
type: array
description: >
Array containing the properties that were removed from the
original device data as per disableTracking property in the
device shadow. `position` refers to all positioning data and
`sensors` to all reported sensor data.
items:
type: string
enum:
- position
- sensors
- bt
- country
- gsm
- wcdma
- tdscdma
- lte
- cdma
- wlan
- gps
- accelerationG
- deviceIsAttached
- deviceIsStationary
- batteryIsCharging
- batteryLevel
- pressureHpa
- relativeHumidity
- deviceIsTampered
- temperatureC
- tiltDegree
trackingId:
type: string
minLength: 1
maxLength: 50
description: >-
This is a unique ID associated with the device data in HERE Tracking.
The `trackingId` gets assigned to a device when the device is claimed by a user.
correlationId:
type: string
format: uuid
description: >
ID used for correlating requests within HERE Tracking. Used for
logging and error reporting.
Must be a valid UUIDv4.rangeSensorEvent
rangeSensorEvent
openapi: 3.0.0
info:
version: 1.0.0
title: Range sensor event
description: |
Definition for the rangeSensorEvent.
paths: {}
components:
schemas:
rangeSensorEvent:
title: Range sensor event
description: |
Events generated by sensor that report numerical data (battery, humidity,
pressure and temperature).
allOf:
- $ref: 'baseEvent.yml#/components/schemas/baseEvent'
- $ref: '#/components/schemas/rangeProperties'
rangeProperties:
properties:
eventSource:
description: |
The event source rule type.
type: string
enum:
- battery
- humidity
- pressure
- temperature
eventType:
type: string
enum:
- BELOW_RANGE
- IN_RANGE
- ABOVE_RANGE
required:
- eventSource
- eventTypeshipmentEtaChangeEvent
shipmentEtaChangeEvent
openapi: 3.0.0
info:
version: 1.0.0
title: Shipment ETA change event
description: |
Definition for the shipmentEtaChangeEvent.
paths: {}
components:
schemas:
shipmentEtaChangeEvent:
title: Shipment ETA change event
description: |
Events generated by a shipment whose calculated ETD or ETA has changed
allOf:
- $ref: 'baseEvent.yml#/components/schemas/baseEvent'
- $ref: '#/components/schemas/shipmentEtaChangeProperties'
shipmentEtaChangeProperties:
type: object
properties:
eventSource:
type: string
enum:
- shipmentEtaChange
eventType:
type: string
enum:
- SHIPMENT_ESTIMATE_CHANGED
extOrderId:
$ref: '#/components/schemas/shipmentExtOrderId'
extSegmentId:
$ref: '#/components/schemas/extSegmentId'
segmentId:
$ref: '#/components/schemas/segmentId'
segmentStatus:
$ref: '#/components/schemas/segmentStatus'
segmentOrigin:
description: Segment origin location
$ref: '#/components/schemas/locationIds'
segmentDestination:
description: Segment destination location
$ref: '#/components/schemas/locationIds'
shipmentEtd:
description: Estimated time of departure of the shipment
$ref: '#/components/schemas/dateV4'
shipmentEta:
description: Estimated time of arrival of the shipment
$ref: '#/components/schemas/dateV4'
etaType:
$ref: '#/components/schemas/etaType'
etaModelVersion:
$ref: '#/components/schemas/etaModelVersion'
segmentEtaChanges:
type: array
items:
type: object
properties:
extSegmentId:
$ref: '#/components/schemas/extSegmentId'
segmentId:
$ref: '#/components/schemas/segmentId'
segmentOrigin:
description: Segment origin location
$ref: '#/components/schemas/locationIds'
segmentDestination:
description: Segment destination location
$ref: '#/components/schemas/locationIds'
segmentEtd:
description: Estimated time of departure of the segment
$ref: '#/components/schemas/dateV4'
segmentEta:
description: Estimated time of arrival of the segment
$ref: '#/components/schemas/dateV4'
etaModelVersion:
$ref: '#/components/schemas/etaModelVersion'
required:
- segmentId
required:
- eventSource
- eventType
- segmentId
- segmentStatus
dateV4:
type: string
format: date-time
etaModelVersion:
description: |
ML model version used for ETA calculation. Present only when ML model is used.
type: string
maxLength: 50
example: "2.3.1"
etaType:
description: |
Type of the ETA value: static ETA values are calculated for pending
state shipments, dynamic ETA values for ongoing state shipments.
type: string
enum:
- dynamic
- static
extSegmentId:
description: External segment ID
type: string
maxLength: 50
locationIds:
description: Location IDs
type: object
properties:
id:
description: Location ID
type: string
pattern: '^LOC-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$'
extId:
description: External location ID in external service
type: string
minLength: 1
maxLength: 100
required:
- id
segmentId:
description: Segment ID
type: string
pattern: '^SEG-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$'
segmentStatus:
description: Segment status
type: string
enum:
- pending
- ongoing
- completed
- cancelled
shipmentExtOrderId:
description: Unique identifier for identifying the shipment in external systems
type: string
maxLength: 50shipmentScheduleEvent
shipmentScheduleEvent
openapi: 3.0.0
info:
version: 1.0.0
title: Shipment schedule event
description: |
Definition for the shipmentScheduleEvent.
paths: {}
components:
schemas:
shipmentScheduleEvent:
title: Shipment schedule event
description: |
Events generated by a shipment that is ahead or delayed from its preplanned schedule
allOf:
- $ref: 'baseEvent.yml#/components/schemas/baseEvent'
- $ref: '#/components/schemas/shipmentScheduleProperties'
shipmentScheduleProperties:
type: object
properties:
eventSource:
type: string
enum:
- shipmentSchedule
eventType:
type: string
enum:
- SHIPMENT_EARLY
- SHIPMENT_ON_TIME
- SHIPMENT_DELAYED
extOrderId:
$ref: '#/components/schemas/shipmentExtOrderId'
extSegmentId:
$ref: '#/components/schemas/extSegmentId'
segmentId:
$ref: '#/components/schemas/segmentId'
segmentStatus:
$ref: '#/components/schemas/segmentStatus'
required:
- eventSource
- eventType
- segmentId
- segmentStatus
extSegmentId:
description: Unique identifier for identifying the segment in external systems
type: string
maxLength: 50
segmentId:
description: Segment ID
type: string
pattern: '^SEG-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$'
segmentStatus:
description: Segment status
type: string
enum:
- pending
- ongoing
- completed
- cancelled
shipmentExtOrderId:
description: Unique identifier for identifying the shipment in external systems
type: string
maxLength: 50shipmentStateChangeEvent
shipmentStateChangeEvent
openapi: 3.0.0
info:
version: 1.0.0
title: Shipment state change event
description: |
Definition for the shipmentStateChangeEvent. This event is not available
from Tracking REST APIs, but only from the events output stream.
Even though this event is not available from the REST APIs, the event
structure follows the same format as the other events so that all events
published to output stream have the same common properties from `baseEvent`.
These events are published for shipment/segment status changes and also
for shipment/segment content changes. Events contain only the changed
properties and those properties which are needed to identify the changed
shipment/segment.
These events are NOT published for the shipment/segment ETA estimate changes.
There is a separate shipmentEtaChange event for that purpose.
paths: {}
components:
schemas:
shipmentStateChangeEvent:
title: Shipment state change event
description: |
Events generated when shipment status or other shipment data changes.
allOf:
- $ref: '#/components/schemas/baseEvent'
- $ref: '#/components/schemas/shipmentStateChangeProperties'
baseEvent:
# These properties are common for all events, but descriptions here
# are specific to shipment state change event.
properties:
trackingId:
description: Shipment ID
type: string
pattern: '^SHP-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$'
timestamp:
type: integer
description: Change time. Milliseconds elapsed since 1 January 1970 00:00:00 UTC.
minimum: 2
maximum: 4102448400000
ruleId:
type: string
format: uuid
description: |
UUIDv4 which identifies the rule which triggers the event.
For shipment state change events this has value `00000000-0000-4000-8000-000000000001`.
initialState:
description: Always false for the shipment state change event.
type: boolean
required:
- trackingId
- timestamp
- ruleId
- initialState
shipmentStateChangeProperties:
type: object
properties:
eventSource:
type: string
enum:
- shipmentStateChange
eventType:
type: string
enum:
- SHIPMENT_CREATED
- SHIPMENT_DELETED
- SHIPMENT_UPDATED
extOrderId:
description: Unique identifier for identifying the shipment in external systems
type: string
maxLength: 50
changeReason:
description: Reason why the event was triggered
allOf:
- $ref: '#/components/schemas/shipmentChangeReason'
changes:
description: Shipment and segment changes
allOf:
- $ref: '#/components/schemas/shipmentChangeData'
required:
- eventSource
- eventType
- changeReason
shipmentChangeReason:
description: Reason for a shipment or segment state change.
type: string
enum:
- apiShipmentCreate # manual, shipment created with API
- apiShipmentCreateFromPlan # manual, shipment created with API from plan
- apiShipmentDelete # manual, shipment deleted with API
- apiShipmentIngest # manual, shipment ingested with API
- apiShipmentUpdate # manual, shipment updated with API
- apiShipmentUpdateTracker # manual, shipment tracker updated with API
- apiSegmentUpdate # manual, segment updated with API
- geofenceEvent # automated, state change because of geofence event
- locationEvent # automated, state change because of location event
- shipmentExpired # scheduled, shipment expired
- shipmentOngoingTooLong # scheduled, shipment has been ongoing too long
- shipmentPendingAutoStart # scheduled, shipment has not started within given autostart interval
shipmentChangeData:
type: object
properties:
name:
description: Name of the shipment
type: string
maxLength: 50
description:
description: Description of the shipment
type: string
maxLength: 1000
autoStart:
description: |
A boolean parameter defining whether the shipment starts upon exiting the first origin
location.
type: boolean
subShipment:
description: Flag telling if shipment is a subShipment.
type: boolean
status:
description: Status of the shipment.
allOf:
- $ref: '#/components/schemas/shipmentSegmentStatus'
createdAt:
description: Timestamp indicating when the shipment has been created
allOf:
- $ref: '#/components/schemas/dateV4'
startedAt:
description: Timestamp indicating when the shipment started
allOf:
- $ref: '#/components/schemas/dateV4'
endedAt:
description: Timestamp indicating when the shipment ended
allOf:
- $ref: '#/components/schemas/dateV4'
providedEtd:
description: User provided ETD for the shipment
allOf:
- $ref: '#/components/schemas/dateV4'
providedEta:
description: User provided ETA for the shipment
allOf:
- $ref: '#/components/schemas/dateV4'
calculatedEtd:
description: Calculated ETD for the segment
allOf:
- $ref: '#/components/schemas/dateV4'
calculatedEta:
description: Calculated ETA for the segment
allOf:
- $ref: '#/components/schemas/dateV4'
ruleIds:
description: Array of `ruleId`s to associate with the shipment
type: array
items:
type: string
format: uuid
description: Must be a valid UUIDv4.
maxItems: 10
shipmentPlanId:
description: A shipment plan's id that the shipment was generated from.
type: string
pattern: '^SHPP-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$'
segments:
description: Array containing the segment details
type: array
items:
description: Segment details
type: object
properties:
extSegmentId:
description: External segment ID
type: string
maxLength: 50
segmentId:
description: Segment ID
type: string
pattern: '^SEG-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$'
segmentIndex:
description: Segment index (starting from 0)
type: integer
minimum: 0
name:
description: Name of the segment
type: string
maxLength: 50
description:
description: Description of the segment
type: string
maxLength: 1000
status:
description: Status of the segment.
allOf:
- $ref: '#/components/schemas/shipmentSegmentStatus'
transportMode:
description: Transport mode of the segment
type: string
enum:
- car
- truck
- sea
- air
- barge
- rail
- railTruck
- truckRail
- bargeTruck
- truckBarge
- undefined
trackingId:
type: string
minLength: 1
maxLength: 50
description:
This is a unique ID associated with the device data in HERE Tracking.
The `trackingId` gets assigned to a device when the device is claimed by a user.
origin:
description: Origin location of this segment
allOf:
- $ref: '#/components/schemas/locationIds'
destination:
description: Destination location of this segment
allOf:
- $ref: '#/components/schemas/locationIds'
startedAt:
description: Timestamp indicating when this segment started
allOf:
- $ref: '#/components/schemas/dateV4'
endedAt:
description: Timestamp indicating when this segment ended
allOf:
- $ref: '#/components/schemas/dateV4'
providedEtd:
description: User provided ETD for the segment
allOf:
- $ref: '#/components/schemas/dateV4'
providedEta:
description: User provided ETA for the segment
allOf:
- $ref: '#/components/schemas/dateV4'
calculatedEtd:
description: Calculated ETD for the segment
allOf:
- $ref: '#/components/schemas/dateV4'
calculatedEta:
description: Calculated ETA for the segment
allOf:
- $ref: '#/components/schemas/dateV4'
shipmentSegmentStatus:
description: Shipment/segment status
type: string
enum:
- pending
- ongoing
- completed
- cancelled
dateV4:
type: string
format: date-time
locationIds:
description: Location IDs
type: object
properties:
id:
description: Location ID
type: string
pattern: '^LOC-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$'
extId:
description: External location ID in external service
type: string
minLength: 1
maxLength: 100
required:
- idstockEvent
stockEvent
openapi: 3.0.0
info:
version: 1.0.0
title: Stock event
description: |
Definition for the stockEvent.
paths: {}
components:
schemas:
stockEvent:
title: Stock event
description: |
Events generated by the number of assets inside a geofence over a maximum stock volume,
or between a minimum stock volume and a maximum stock volume, or under a minimum stock
volume.
allOf:
- type: object
properties:
timestamp:
description: |
Event time. Milliseconds elapsed since 1 January 1970 00:00:00 UTC.
type: integer
minimum: 2
maximum: 4102448400000
ruleId:
description: |
UUIDv4 which identifies the rule which triggers the event.
type: string
format: uuid
initialState:
description: |
Events with the `initialState` property set as `true` are generated when the rule is
evaluated for the first time. It indicates the fact that this is the initial evaluation
state, which would serve as a starting point for the subsequent rule evaluations.
The rest of the rule events would represent a transition of a device or a shipment or
a geofence from one state to another and their `initialState` property will be set to `false`.
type: boolean
required:
- timestamp
- ruleId
- initialState
- $ref: '#/components/schemas/stockProperties'
stockProperties:
properties:
eventSource:
description: |
The event source: stock rule
type: string
enum:
- stock
eventType:
description: |
The "OVERSTOCK" type - Events are triggered when the number of assets
is over a maximum stock volume.
The "UNDERSTOCK" type - Events are triggered when the number of assets
is under a minimum stock volume.
The "NORMAL_VOLUME" type - Events are triggered when the number of assets
is between the minimum stock volume and the maximum stock volume.
type: string
enum:
- OVERSTOCK
- NORMAL_VOLUME
- UNDERSTOCK
required:
- eventSource
- eventTypeutilizationEvent
utilizationEvent
openapi: 3.0.0
info:
version: 1.0.0
title: Utilization event
description: |
Definition for the utilizationEvent.
paths: {}
components:
schemas:
utilizationEvent:
title: Utilization event
description: |
The UTILIZED event is generated when a device starts moving,
and the UNUTILIZED event is generated when the device has been stationary
for longer than the specified threshold duration.
allOf:
- $ref: 'baseEvent.yml#/components/schemas/baseEvent'
- $ref: '#/components/schemas/utilizationProperties'
utilizationProperties:
properties:
eventSource:
description: |
The event source: utilization rule
type: string
enum:
- utilization
eventType:
type: string
enum:
- UTILIZED
- UNUTILIZED
required:
- eventSource
- eventTypevalueSensorEvent
valueSensorEvent
openapi: 3.0.0
info:
version: 1.0.0
title: Value sensor event
description: |
Definition for the valueSensorEvent.
paths: {}
components:
schemas:
valueSensorEvent:
title: Value sensor event
description: |
Events generated by sensor that report numerical data but only when a specific
event occurs (eg. the device was dropped)
allOf:
- $ref: 'baseEvent.yml#/components/schemas/baseEvent'
- $ref: '#/components/schemas/valueProperties'
valueProperties:
properties:
eventSource:
description: |
The event source: acceleration rule
type: string
enum:
- acceleration
eventType:
type: string
enum:
- EVENT
required:
- eventSource
- eventTypeUpdated 21 days ago