openapi: 3.2.0 info: version: 2.6.11 title: HERE Tracking Events API description: 'HERE Tracking is a cloud product designed to address location tracking problems for a wide range of Location IoT industry verticals. HERE Tracking also includes end-user mobile and web applications that can be used to demonstrate the product.' license: name: HERE Documentation License url: https://legal.here.com/en-gb/terms/documentation-license servers: - url: https://tracking.hereapi.com/ - url: https://tracking.api.here.com/ tags: - description: 'The Events service manages device and shipment events. An event is created every time an associated rule or geofence is triggered by a device ingestion. A geofence event is created every time a device enters or exits an associated geofence. A sensor event is created when sensor data reported by a device triggers a sensor rule. A rule event (such as dwelling, detention, utilization, stock and online rule) is created when a device behaviour triggers a rule.' name: Events paths: /events/v3/health: get: summary: Gets service health security: [] responses: '200': description: 'OK The service is performing as expected ' content: application/json: schema: type: object properties: message: type: string description: Health status example: message: healthy '500': description: 'Service unavailable The service is not performing as expected ' tags: - Events operationId: getEventsV3Health x-operation-id-source: derived /events/v3/version: get: summary: Gets service version security: [] responses: '200': description: 'Success ' content: application/json: schema: description: "OK\nService returns its current version number\nschema:\n type: object\n properties:\n \"service-name\":\n type: string\n description: Version of service\n example:\n servicename: \"1.0.0\"\n" '500': description: 'Service unavailable The service is not performing as expected ' tags: - Events operationId: getEventsV3Version x-operation-id-source: derived /events/v3: parameters: - in: header name: X-Request-Id schema: type: string format: uuid description: 'ID used for correlating requests within HERE Tracking. Used for logging and error reporting. Must be a valid UUIDv4. ' required: false - name: projectId schema: type: string minLength: 1 maxLength: 50 description: 'Project ID. Any HERE Tracking user must be a member of a Tracking project. The project ID can be implicitly resolved if the user calling the API is a member of a single project. If the user is a member of multiple projects, the `projectId` query parameter needs to be specified explicitly. ' in: query required: false get: summary: Gets event history description: 'Gets all events for all devices and shipments of the project. The results are listed in descending order based on the timestamp. An event is uniquely identified by `trackingId`-`ruleId`-`timestamp` key, with an exception of dwelling and stock rule events. Dwelling events also need `geofenceId` to be specified, whereas for stock events `trackingId` is not applicable. A time range can be defined with `before` and `after` timestamps. The response will contain an array of events that were recorded within the range. The default value for `before` parameter is the current time, and for the `after` parameter it is one day in the past from the current time. The `after` parameter value is not allowed to be earlier than two weeks in the past from the `before` timestamp, otherwise an error is returned. If the request is supplied with `eventSource` query parameter, the response will contain events generated by the defined source only. If the request is supplied with `eventType` query parameter, the response will contain events of the specified type only. If the request is supplied with `ruleId` query parameter, the response will only contain events for the specified rule ID. If the request is supplied with `initialState` query parameter, the response will contain events having the specified initial state. All the aforementioned query parameters can be combined together.' tags: - Events security: - UserToken: [] - ClientToken: [] parameters: - name: before description: 'Milliseconds elapsed since 1 January 1970 00:00:00 UTC. The accepted range is from 1 to the current time. ' in: query required: false schema: type: number minimum: 1 - name: after description: 'Milliseconds elapsed since 1 January 1970 00:00:00 UTC. The accepted range is from 0 to the current time. ' in: query required: false schema: type: number minimum: 0 - name: eventSource in: query required: false schema: oneOf: - description: 'The event source rule type. ' type: string enum: - acceleration - attach - battery - detention - dwelling - geofence - humidity - online - pressure - shipmentEtaChange - shipmentSchedule - stock - tamper - temperature - utilization - type: array items: description: 'The event source rule type. ' type: string enum: - acceleration - attach - battery - detention - dwelling - geofence - humidity - online - pressure - shipmentEtaChange - shipmentSchedule - stock - tamper - temperature - utilization - name: eventType in: query required: false schema: oneOf: - description: 'Type of the event. An event is created every time an associated rule or geofence is triggered by a device ingestion. The event type depends on the data the device sends. Sensors that report numerical data (such as battery, humidity, pressure and temperature sensors), generate an event when the reported sensor reading of the device goes in or out of range, which is configured in the rule. This produces events of BELOW_RANGE, IN_RANGE and ABOVE_RANGE types. Sensors that report boolean data (such as attach and tamper sensors), generate events when the device transitions from one state to another, either from `false` to `true` or vice versa. This produces events of FALSE_TO_TRUE and TRUE_TO_FALSE types. The same event types are also generated by the online rule when the device state changes from `offline` (when the device has stopped ingesting data) to `online` (when the device data ingestion has resumed) or vice versa. The acceleration sensor generates events whenever the reported sensor reading crosses the acceleration threshold (for example, when the device was dropped). This produces events of the type EVENT. Such events are stateless. Events of INSIDE_GEOFENCE and OUTSIDE_GEOFENCE types are generated when the device enters or exits a geofence associated with the device. Events of DWELLING_STARTED type are generated when the device has stayed inside an associated geofence for longer than the threshold duration. DWELLING_ENDED type events are generated when dwelling of the device has ended. Events of DETENTION_STARTED type are generated when the device has been stationary for longer than the threshold duration, regardless whether the device is inside or outside of any geofence. DETENTION_ENDED type events will be generated when the device starts moving again. Events of UNUTILIZED type are generated when the device has been stationary for longer than the threshold duration. UTILIZED type events are generated when the device starts moving again after having been stationary. Events of OVERSTOCK, NORMAL_VOLUME and UNDERSTOCK types are generated when the number of assets inside a geofence crosses the `minVolume` and `maxVolume` thresholds of an associated stock rule. Event of SHIPMENT_ESTIMATE_CHANGED is generated when the estimated departure (ETD) or arrival (ETA) times deviate from the original estimates more than the defined threshold. Events of SHIPMENT_EARLY, SHIPMENT_ON_TIME and SHIPMENT_DELAYED types are generated when a shipment is too early, on time or delayed. ' type: string enum: - BELOW_RANGE - IN_RANGE - ABOVE_RANGE - FALSE_TO_TRUE - TRUE_TO_FALSE - EVENT - INSIDE_GEOFENCE - OUTSIDE_GEOFENCE - OVERSTOCK - NORMAL_VOLUME - UNDERSTOCK - DWELLING_STARTED - DWELLING_ENDED - DETENTION_STARTED - DETENTION_ENDED - UTILIZED - UNUTILIZED - SHIPMENT_EARLY - SHIPMENT_ON_TIME - SHIPMENT_DELAYED - SHIPMENT_ESTIMATE_CHANGED - type: array items: description: 'Type of the event. An event is created every time an associated rule or geofence is triggered by a device ingestion. The event type depends on the data the device sends. Sensors that report numerical data (such as battery, humidity, pressure and temperature sensors), generate an event when the reported sensor reading of the device goes in or out of range, which is configured in the rule. This produces events of BELOW_RANGE, IN_RANGE and ABOVE_RANGE types. Sensors that report boolean data (such as attach and tamper sensors), generate events when the device transitions from one state to another, either from `false` to `true` or vice versa. This produces events of FALSE_TO_TRUE and TRUE_TO_FALSE types. The same event types are also generated by the online rule when the device state changes from `offline` (when the device has stopped ingesting data) to `online` (when the device data ingestion has resumed) or vice versa. The acceleration sensor generates events whenever the reported sensor reading crosses the acceleration threshold (for example, when the device was dropped). This produces events of the type EVENT. Such events are stateless. Events of INSIDE_GEOFENCE and OUTSIDE_GEOFENCE types are generated when the device enters or exits a geofence associated with the device. Events of DWELLING_STARTED type are generated when the device has stayed inside an associated geofence for longer than the threshold duration. DWELLING_ENDED type events are generated when dwelling of the device has ended. Events of DETENTION_STARTED type are generated when the device has been stationary for longer than the threshold duration, regardless whether the device is inside or outside of any geofence. DETENTION_ENDED type events will be generated when the device starts moving again. Events of UNUTILIZED type are generated when the device has been stationary for longer than the threshold duration. UTILIZED type events are generated when the device starts moving again after having been stationary. Events of OVERSTOCK, NORMAL_VOLUME and UNDERSTOCK types are generated when the number of assets inside a geofence crosses the `minVolume` and `maxVolume` thresholds of an associated stock rule. Event of SHIPMENT_ESTIMATE_CHANGED is generated when the estimated departure (ETD) or arrival (ETA) times deviate from the original estimates more than the defined threshold. Events of SHIPMENT_EARLY, SHIPMENT_ON_TIME and SHIPMENT_DELAYED types are generated when a shipment is too early, on time or delayed. ' type: string enum: - BELOW_RANGE - IN_RANGE - ABOVE_RANGE - FALSE_TO_TRUE - TRUE_TO_FALSE - EVENT - INSIDE_GEOFENCE - OUTSIDE_GEOFENCE - OVERSTOCK - NORMAL_VOLUME - UNDERSTOCK - DWELLING_STARTED - DWELLING_ENDED - DETENTION_STARTED - DETENTION_ENDED - UTILIZED - UNUTILIZED - SHIPMENT_EARLY - SHIPMENT_ON_TIME - SHIPMENT_DELAYED - SHIPMENT_ESTIMATE_CHANGED - name: ruleId in: query required: false schema: oneOf: - type: string format: uuid description: 'ID of the rule or geofence. Must be a valid UUIDv4. ' - type: array items: type: string format: uuid description: 'ID of the rule or geofence. Must be a valid UUIDv4. ' - name: initialState in: query required: false schema: 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 - name: pageToken description: A token from the previously returned response to retrieve the specified page. schema: type: string in: query required: false - name: count description: The number of items to return per page. schema: type: integer minimum: 1 maximum: 1000 default: 1000 in: query required: false - name: appId description: Application identifier. Used together with an external ID to identify a virtual device. schema: type: string minLength: 8 in: query required: false responses: '200': description: 'Successful The events were successfully retrieved. ' content: application/json: schema: allOf: - type: object properties: pageToken: type: string description: A token that can be used to retrieve the next page of the response. count: type: integer minimum: 0 maximum: 1000 default: 1000 description: The number of items in the response. - type: object properties: data: type: array items: oneOf: - title: Boolean event description: 'Events generated by online rule or by sensors that report boolean data (attach, tamper). ' allOf: - properties: 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. Alternatively, a valid `shipmentId` may be used. timestamp: type: integer description: Milliseconds elapsed since 1 January 1970 00:00:00 UTC. minimum: 2 maximum: 4102448400000 ruleId: type: string format: uuid description: 'Must be a valid UUIDv4. ' 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 - initialState - 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 - eventType - title: Range event description: 'Events generated by sensor that report numerical data (battery, humidity, pressure and temperature). ' allOf: - properties: 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. Alternatively, a valid `shipmentId` may be used. timestamp: type: integer description: Milliseconds elapsed since 1 January 1970 00:00:00 UTC. minimum: 2 maximum: 4102448400000 ruleId: type: string format: uuid description: 'Must be a valid UUIDv4. ' 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 - initialState - 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 - eventType - title: Generic event description: 'Events generated by sensor that report numerical data but only when a specific event occurs (eg. the device was dropped) ' allOf: - properties: 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. Alternatively, a valid `shipmentId` may be used. timestamp: type: integer description: Milliseconds elapsed since 1 January 1970 00:00:00 UTC. minimum: 2 maximum: 4102448400000 ruleId: type: string format: uuid description: 'Must be a valid UUIDv4. ' 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 - initialState - properties: eventSource: description: 'The event source: acceleration rule ' type: string enum: - acceleration eventType: type: string enum: - EVENT required: - eventSource - eventType - title: Geofence event description: 'Events generated by device crossing the geofence border. ' allOf: - properties: 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. Alternatively, a valid `shipmentId` may be used. timestamp: type: integer description: Milliseconds elapsed since 1 January 1970 00:00:00 UTC. minimum: 2 maximum: 4102448400000 ruleId: type: string format: uuid description: 'Must be a valid UUIDv4. ' 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 - initialState - properties: eventSource: description: 'The event source: geofence rule ' type: string enum: - geofence eventType: type: string enum: - INSIDE_GEOFENCE - OUTSIDE_GEOFENCE version: description: Geofence version type: integer required: - eventSource - eventType - 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: - properties: timestamp: type: integer description: Milliseconds elapsed since 1 January 1970 00:00:00 UTC. minimum: 2 maximum: 4102448400000 ruleId: type: string format: uuid description: 'Must be a valid UUIDv4. ' 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: - timestamp - ruleId - eventSource - eventType - type: object properties: 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: - initialState - title: Dwelling event description: 'Events generated by a device that has dwelled inside a geofence for longer than specified threshold duration ' allOf: - properties: 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. Alternatively, a valid `shipmentId` may be used. timestamp: type: integer description: Milliseconds elapsed since 1 January 1970 00:00:00 UTC. minimum: 2 maximum: 4102448400000 ruleId: type: string format: uuid description: 'Must be a valid UUIDv4. ' 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 - initialState - 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 - geofenceId - title: Detention event description: 'Events generated when a device has been stationary for longer than the specified threshold duration. ' allOf: - properties: 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. Alternatively, a valid `shipmentId` may be used. timestamp: type: integer description: Milliseconds elapsed since 1 January 1970 00:00:00 UTC. minimum: 2 maximum: 4102448400000 ruleId: type: string format: uuid description: 'Must be a valid UUIDv4. ' 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 - initialState - properties: eventSource: description: 'The event source: detention rule ' type: string enum: - detention eventType: type: string enum: - DETENTION_STARTED - DETENTION_ENDED required: - eventSource - eventType - 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: - properties: 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. Alternatively, a valid `shipmentId` may be used. timestamp: type: integer description: Milliseconds elapsed since 1 January 1970 00:00:00 UTC. minimum: 2 maximum: 4102448400000 ruleId: type: string format: uuid description: 'Must be a valid UUIDv4. ' 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 - initialState - properties: eventSource: description: 'The event source: utilization rule ' type: string enum: - utilization eventType: type: string enum: - UTILIZED - UNUTILIZED required: - eventSource - eventType - title: Shipment ETA change event description: 'Events generated by a shipment whose calculated ETD or ETA has changed ' allOf: - properties: 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. Alternatively, a valid `shipmentId` may be used. timestamp: type: integer description: Milliseconds elapsed since 1 January 1970 00:00:00 UTC. minimum: 2 maximum: 4102448400000 ruleId: type: string format: uuid description: 'Must be a valid UUIDv4. ' 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 - initialState - type: object properties: eventSource: type: string enum: - shipmentEtaChange eventType: type: string enum: - SHIPMENT_ESTIMATE_CHANGED extOrderId: description: Unique identifier for identifying the shipment in external systems type: string maxLength: 50 extSegmentId: description: Unique identifier for identifying the segment in external systems type: string maxLength: 50 segmentId: description: 'An ID of the segment where the ETD/ETA change was detected ' 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: Status of the segment. type: string enum: - pending - ongoing - completed - cancelled segmentOrigin: description: Segment origin location 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 cloud type: string minLength: 1 maxLength: 100 required: - id segmentDestination: description: Segment destination location 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 cloud type: string minLength: 1 maxLength: 100 required: - id shipmentEtd: description: Estimated time of departure of the shipment type: string format: date-time shipmentEta: description: Estimated time of arrival of the shipment type: string format: date-time 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 etaModelVersion: description: 'ML model version used for ETA calculation. Present only when ML model is used. ' type: string maxLength: 50 example: 2.3.1 segmentEtaChanges: type: array items: type: object properties: 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}$ segmentOrigin: description: Segment origin location 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 cloud type: string minLength: 1 maxLength: 100 required: - id segmentDestination: description: Segment destination location 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 cloud type: string minLength: 1 maxLength: 100 required: - id segmentEtd: description: Estimated time of departure of the segment type: string format: date-time segmentEta: description: Estimated time of arrival of the segment 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 required: - segmentId required: - eventSource - eventType - segmentId - segmentStatus - title: Shipment schedule event description: 'Events generated by a shipment that is ahead or delayed from its preplanned schedule ' allOf: - properties: 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. Alternatively, a valid `shipmentId` may be used. timestamp: type: integer description: Milliseconds elapsed since 1 January 1970 00:00:00 UTC. minimum: 2 maximum: 4102448400000 ruleId: type: string format: uuid description: 'Must be a valid UUIDv4. ' 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 - initialState - type: object properties: eventSource: type: string enum: - shipmentSchedule eventType: type: string enum: - SHIPMENT_EARLY - SHIPMENT_ON_TIME - SHIPMENT_DELAYED extOrderId: description: Unique identifier for identifying the shipment in external systems type: string maxLength: 50 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: Status of the segment. type: string enum: - pending - ongoing - completed - cancelled required: - eventSource - eventType - segmentId - segmentStatus example: count: 1 pageToken: 2lkjfdaoiekllldko=sdflkjdfasdi34 data: - trackingId: HERE-6da0f871-b4eb-4800-90e6-4bae86a788d6 eventSource: attach timestamp: 1499258057036 eventType: TRUE_TO_FALSE ruleId: e2f651ee-f196-4fa3-bf88-894dc131dea3 initialState: false '400': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Bad request code: 400 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The request object is in an incorrect format or has values that are invalid or out of range. details: hereErrorCode: 400306 description: 'Bad request The request object is in an incorrect format or has values that are invalid or out of range. If available, further error details are provided in the response body. ' '401': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Unauthorized code: 401 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The provided credentials are not valid. details: hereErrorCode: 401306 description: 'Unauthorized The request did not provide correct authentication details ' '403': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Forbidden code: 403 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The account does not have the correct privileges. details: hereErrorCode: 403306 description: 'Forbidden The account does not have the correct privileges ' '404': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Not Found code: 404 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The specified resource was not found. details: hereErrorCode: 404306 description: 'Not Found The specified resource was not found ' operationId: getEventsV3 x-operation-id-source: derived /events/v3/{trackingId}: parameters: - in: header name: X-Request-Id schema: type: string format: uuid description: 'ID used for correlating requests within HERE Tracking. Used for logging and error reporting. Must be a valid UUIDv4. ' required: false get: summary: Gets event history for a device or a shipment description: 'Gets all events for a device or a shipment. A device is identified by the `trackingId`. For shipments, `shipmentId` can be used as a `trackingId`. The results are listed in descending order based on the timestamp. An event is uniquely identified by `trackingId`-`ruleId`-`timestamp` key, with an exception of dwelling and stock rule events. Dwelling events also need `geofenceId` to be specified, whereas for stock events `trackingId` is not applicable. A single event can be fetched using `ruleId`, `before` and `after` query parameters. A time range can be defined with `before` and `after` timestamps. The response will contain an array of events that were recorded within the range. The default value for `before` parameter is the current time, and for the `after` parameter it is one day in the past from the current time. The `after` parameter value is not allowed to be earlier than two weeks in the past from the `before` timestamp, otherwise an error is returned. If the request is supplied with `eventSource` query parameter, the response will contain events generated by the defined source only. If the request is supplied with `eventType` query parameter, the response will contain events of the specified type only. If the request is supplied with `ruleId` query parameter, the response will only contain events for the specified rule ID. If the request is supplied with `initialState` query parameter, the response will contain events having the specified initial state. All the aforementioned query parameters can be combined together.' tags: - Events security: - UserToken: [] - ClientToken: [] parameters: - name: trackingId in: path schema: 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. Alternatively, a valid `shipmentId` may be used. required: true - name: before description: 'Milliseconds elapsed since 1 January 1970 00:00:00 UTC. The accepted range is from 1 to the current time. ' in: query required: false schema: type: number minimum: 1 - name: after description: 'Milliseconds elapsed since 1 January 1970 00:00:00 UTC. The accepted range is from 0 to the current time. ' in: query required: false schema: type: number minimum: 0 - name: eventSource in: query required: false schema: oneOf: - description: 'The event source rule type. ' type: string enum: - acceleration - attach - battery - detention - dwelling - geofence - humidity - online - pressure - shipmentEtaChange - shipmentSchedule - stock - tamper - temperature - utilization - type: array items: description: 'The event source rule type. ' type: string enum: - acceleration - attach - battery - detention - dwelling - geofence - humidity - online - pressure - shipmentEtaChange - shipmentSchedule - stock - tamper - temperature - utilization - name: eventType in: query required: false schema: oneOf: - description: 'Type of the event. An event is created every time an associated rule or geofence is triggered by a device ingestion. The event type depends on the data the device sends. Sensors that report numerical data (such as battery, humidity, pressure and temperature sensors), generate an event when the reported sensor reading of the device goes in or out of range, which is configured in the rule. This produces events of BELOW_RANGE, IN_RANGE and ABOVE_RANGE types. Sensors that report boolean data (such as attach and tamper sensors), generate events when the device transitions from one state to another, either from `false` to `true` or vice versa. This produces events of FALSE_TO_TRUE and TRUE_TO_FALSE types. The same event types are also generated by the online rule when the device state changes from `offline` (when the device has stopped ingesting data) to `online` (when the device data ingestion has resumed) or vice versa. The acceleration sensor generates events whenever the reported sensor reading crosses the acceleration threshold (for example, when the device was dropped). This produces events of the type EVENT. Such events are stateless. Events of INSIDE_GEOFENCE and OUTSIDE_GEOFENCE types are generated when the device enters or exits a geofence associated with the device. Events of DWELLING_STARTED type are generated when the device has stayed inside an associated geofence for longer than the threshold duration. DWELLING_ENDED type events are generated when dwelling of the device has ended. Events of DETENTION_STARTED type are generated when the device has been stationary for longer than the threshold duration, regardless whether the device is inside or outside of any geofence. DETENTION_ENDED type events will be generated when the device starts moving again. Events of UNUTILIZED type are generated when the device has been stationary for longer than the threshold duration. UTILIZED type events are generated when the device starts moving again after having been stationary. Events of OVERSTOCK, NORMAL_VOLUME and UNDERSTOCK types are generated when the number of assets inside a geofence crosses the `minVolume` and `maxVolume` thresholds of an associated stock rule. Event of SHIPMENT_ESTIMATE_CHANGED is generated when the estimated departure (ETD) or arrival (ETA) times deviate from the original estimates more than the defined threshold. Events of SHIPMENT_EARLY, SHIPMENT_ON_TIME and SHIPMENT_DELAYED types are generated when a shipment is too early, on time or delayed. ' type: string enum: - BELOW_RANGE - IN_RANGE - ABOVE_RANGE - FALSE_TO_TRUE - TRUE_TO_FALSE - EVENT - INSIDE_GEOFENCE - OUTSIDE_GEOFENCE - OVERSTOCK - NORMAL_VOLUME - UNDERSTOCK - DWELLING_STARTED - DWELLING_ENDED - DETENTION_STARTED - DETENTION_ENDED - UTILIZED - UNUTILIZED - SHIPMENT_EARLY - SHIPMENT_ON_TIME - SHIPMENT_DELAYED - SHIPMENT_ESTIMATE_CHANGED - type: array items: description: 'Type of the event. An event is created every time an associated rule or geofence is triggered by a device ingestion. The event type depends on the data the device sends. Sensors that report numerical data (such as battery, humidity, pressure and temperature sensors), generate an event when the reported sensor reading of the device goes in or out of range, which is configured in the rule. This produces events of BELOW_RANGE, IN_RANGE and ABOVE_RANGE types. Sensors that report boolean data (such as attach and tamper sensors), generate events when the device transitions from one state to another, either from `false` to `true` or vice versa. This produces events of FALSE_TO_TRUE and TRUE_TO_FALSE types. The same event types are also generated by the online rule when the device state changes from `offline` (when the device has stopped ingesting data) to `online` (when the device data ingestion has resumed) or vice versa. The acceleration sensor generates events whenever the reported sensor reading crosses the acceleration threshold (for example, when the device was dropped). This produces events of the type EVENT. Such events are stateless. Events of INSIDE_GEOFENCE and OUTSIDE_GEOFENCE types are generated when the device enters or exits a geofence associated with the device. Events of DWELLING_STARTED type are generated when the device has stayed inside an associated geofence for longer than the threshold duration. DWELLING_ENDED type events are generated when dwelling of the device has ended. Events of DETENTION_STARTED type are generated when the device has been stationary for longer than the threshold duration, regardless whether the device is inside or outside of any geofence. DETENTION_ENDED type events will be generated when the device starts moving again. Events of UNUTILIZED type are generated when the device has been stationary for longer than the threshold duration. UTILIZED type events are generated when the device starts moving again after having been stationary. Events of OVERSTOCK, NORMAL_VOLUME and UNDERSTOCK types are generated when the number of assets inside a geofence crosses the `minVolume` and `maxVolume` thresholds of an associated stock rule. Event of SHIPMENT_ESTIMATE_CHANGED is generated when the estimated departure (ETD) or arrival (ETA) times deviate from the original estimates more than the defined threshold. Events of SHIPMENT_EARLY, SHIPMENT_ON_TIME and SHIPMENT_DELAYED types are generated when a shipment is too early, on time or delayed. ' type: string enum: - BELOW_RANGE - IN_RANGE - ABOVE_RANGE - FALSE_TO_TRUE - TRUE_TO_FALSE - EVENT - INSIDE_GEOFENCE - OUTSIDE_GEOFENCE - OVERSTOCK - NORMAL_VOLUME - UNDERSTOCK - DWELLING_STARTED - DWELLING_ENDED - DETENTION_STARTED - DETENTION_ENDED - UTILIZED - UNUTILIZED - SHIPMENT_EARLY - SHIPMENT_ON_TIME - SHIPMENT_DELAYED - SHIPMENT_ESTIMATE_CHANGED - name: ruleId in: query required: false schema: oneOf: - type: string format: uuid description: 'ID of the rule or geofence. Must be a valid UUIDv4. ' - type: array items: type: string format: uuid description: 'ID of the rule or geofence. Must be a valid UUIDv4. ' - name: initialState in: query required: false schema: 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 - name: pageToken description: A token from the previously returned response to retrieve the specified page. schema: type: string in: query required: false - name: count description: The number of items to return per page. schema: type: integer minimum: 1 maximum: 1000 default: 1000 in: query required: false - name: appId description: Application identifier. Used together with an external ID to identify a virtual device. schema: type: string minLength: 8 in: query required: false responses: '200': description: 'Successful The events were successfully retrieved. ' content: application/json: schema: allOf: - type: object properties: pageToken: type: string description: A token that can be used to retrieve the next page of the response. count: type: integer minimum: 0 maximum: 1000 default: 1000 description: The number of items in the response. - type: object properties: data: type: array items: oneOf: - title: Boolean event description: 'Events generated by online rule or by sensors that report boolean data (attach, tamper). ' allOf: - properties: 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. Alternatively, a valid `shipmentId` may be used. timestamp: type: integer description: Milliseconds elapsed since 1 January 1970 00:00:00 UTC. minimum: 2 maximum: 4102448400000 ruleId: type: string format: uuid description: 'Must be a valid UUIDv4. ' 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 - initialState - 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 - eventType - title: Range event description: 'Events generated by sensor that report numerical data (battery, humidity, pressure and temperature). ' allOf: - properties: 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. Alternatively, a valid `shipmentId` may be used. timestamp: type: integer description: Milliseconds elapsed since 1 January 1970 00:00:00 UTC. minimum: 2 maximum: 4102448400000 ruleId: type: string format: uuid description: 'Must be a valid UUIDv4. ' 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 - initialState - 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 - eventType - title: Generic event description: 'Events generated by sensor that report numerical data but only when a specific event occurs (eg. the device was dropped) ' allOf: - properties: 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. Alternatively, a valid `shipmentId` may be used. timestamp: type: integer description: Milliseconds elapsed since 1 January 1970 00:00:00 UTC. minimum: 2 maximum: 4102448400000 ruleId: type: string format: uuid description: 'Must be a valid UUIDv4. ' 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 - initialState - properties: eventSource: description: 'The event source: acceleration rule ' type: string enum: - acceleration eventType: type: string enum: - EVENT required: - eventSource - eventType - title: Geofence event description: 'Events generated by device crossing the geofence border. ' allOf: - properties: 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. Alternatively, a valid `shipmentId` may be used. timestamp: type: integer description: Milliseconds elapsed since 1 January 1970 00:00:00 UTC. minimum: 2 maximum: 4102448400000 ruleId: type: string format: uuid description: 'Must be a valid UUIDv4. ' 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 - initialState - properties: eventSource: description: 'The event source: geofence rule ' type: string enum: - geofence eventType: type: string enum: - INSIDE_GEOFENCE - OUTSIDE_GEOFENCE version: description: Geofence version type: integer required: - eventSource - eventType - 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: - properties: timestamp: type: integer description: Milliseconds elapsed since 1 January 1970 00:00:00 UTC. minimum: 2 maximum: 4102448400000 ruleId: type: string format: uuid description: 'Must be a valid UUIDv4. ' 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: - timestamp - ruleId - eventSource - eventType - type: object properties: 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: - initialState - title: Dwelling event description: 'Events generated by a device that has dwelled inside a geofence for longer than specified threshold duration ' allOf: - properties: 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. Alternatively, a valid `shipmentId` may be used. timestamp: type: integer description: Milliseconds elapsed since 1 January 1970 00:00:00 UTC. minimum: 2 maximum: 4102448400000 ruleId: type: string format: uuid description: 'Must be a valid UUIDv4. ' 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 - initialState - 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 - geofenceId - title: Detention event description: 'Events generated when a device has been stationary for longer than the specified threshold duration. ' allOf: - properties: 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. Alternatively, a valid `shipmentId` may be used. timestamp: type: integer description: Milliseconds elapsed since 1 January 1970 00:00:00 UTC. minimum: 2 maximum: 4102448400000 ruleId: type: string format: uuid description: 'Must be a valid UUIDv4. ' 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 - initialState - properties: eventSource: description: 'The event source: detention rule ' type: string enum: - detention eventType: type: string enum: - DETENTION_STARTED - DETENTION_ENDED required: - eventSource - eventType - 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: - properties: 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. Alternatively, a valid `shipmentId` may be used. timestamp: type: integer description: Milliseconds elapsed since 1 January 1970 00:00:00 UTC. minimum: 2 maximum: 4102448400000 ruleId: type: string format: uuid description: 'Must be a valid UUIDv4. ' 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 - initialState - properties: eventSource: description: 'The event source: utilization rule ' type: string enum: - utilization eventType: type: string enum: - UTILIZED - UNUTILIZED required: - eventSource - eventType - title: Shipment ETA change event description: 'Events generated by a shipment whose calculated ETD or ETA has changed ' allOf: - properties: 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. Alternatively, a valid `shipmentId` may be used. timestamp: type: integer description: Milliseconds elapsed since 1 January 1970 00:00:00 UTC. minimum: 2 maximum: 4102448400000 ruleId: type: string format: uuid description: 'Must be a valid UUIDv4. ' 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 - initialState - type: object properties: eventSource: type: string enum: - shipmentEtaChange eventType: type: string enum: - SHIPMENT_ESTIMATE_CHANGED extOrderId: description: Unique identifier for identifying the shipment in external systems type: string maxLength: 50 extSegmentId: description: Unique identifier for identifying the segment in external systems type: string maxLength: 50 segmentId: description: 'An ID of the segment where the ETD/ETA change was detected ' 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: Status of the segment. type: string enum: - pending - ongoing - completed - cancelled segmentOrigin: description: Segment origin location 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 cloud type: string minLength: 1 maxLength: 100 required: - id segmentDestination: description: Segment destination location 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 cloud type: string minLength: 1 maxLength: 100 required: - id shipmentEtd: description: Estimated time of departure of the shipment type: string format: date-time shipmentEta: description: Estimated time of arrival of the shipment type: string format: date-time 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 etaModelVersion: description: 'ML model version used for ETA calculation. Present only when ML model is used. ' type: string maxLength: 50 example: 2.3.1 segmentEtaChanges: type: array items: type: object properties: 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}$ segmentOrigin: description: Segment origin location 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 cloud type: string minLength: 1 maxLength: 100 required: - id segmentDestination: description: Segment destination location 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 cloud type: string minLength: 1 maxLength: 100 required: - id segmentEtd: description: Estimated time of departure of the segment type: string format: date-time segmentEta: description: Estimated time of arrival of the segment 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 required: - segmentId required: - eventSource - eventType - segmentId - segmentStatus - title: Shipment schedule event description: 'Events generated by a shipment that is ahead or delayed from its preplanned schedule ' allOf: - properties: 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. Alternatively, a valid `shipmentId` may be used. timestamp: type: integer description: Milliseconds elapsed since 1 January 1970 00:00:00 UTC. minimum: 2 maximum: 4102448400000 ruleId: type: string format: uuid description: 'Must be a valid UUIDv4. ' 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 - initialState - type: object properties: eventSource: type: string enum: - shipmentSchedule eventType: type: string enum: - SHIPMENT_EARLY - SHIPMENT_ON_TIME - SHIPMENT_DELAYED extOrderId: description: Unique identifier for identifying the shipment in external systems type: string maxLength: 50 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: Status of the segment. type: string enum: - pending - ongoing - completed - cancelled required: - eventSource - eventType - segmentId - segmentStatus example: count: 1 pageToken: 2lkjfdaoiekllldko=sdflkjdfasdi34 data: - trackingId: HERE-6da0f871-b4eb-4800-90e6-4bae86a788d6 eventSource: attach timestamp: 1499258057036 eventType: TRUE_TO_FALSE ruleId: e2f651ee-f196-4fa3-bf88-894dc131dea3 initialState: false '400': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Bad request code: 400 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The request object is in an incorrect format or has values that are invalid or out of range. details: hereErrorCode: 400306 description: 'Bad request The request object is in an incorrect format or has values that are invalid or out of range. If available, further error details are provided in the response body. ' '401': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Unauthorized code: 401 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The provided credentials are not valid. details: hereErrorCode: 401306 description: 'Unauthorized The request did not provide correct authentication details ' '403': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Forbidden code: 403 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The account does not have the correct privileges. details: hereErrorCode: 403306 description: 'Forbidden The account does not have the correct privileges ' '404': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Not Found code: 404 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The specified resource was not found. details: hereErrorCode: 404306 description: 'Not Found The specified resource was not found ' operationId: getEventsV3ByTrackingId x-operation-id-source: derived /events/v3/statuses: parameters: - in: header name: X-Request-Id schema: type: string format: uuid description: 'ID used for correlating requests within HERE Tracking. Used for logging and error reporting. Must be a valid UUIDv4. ' required: false - name: projectId schema: type: string minLength: 1 maxLength: 50 description: 'Project ID. Any HERE Tracking user must be a member of a Tracking project. The project ID can be implicitly resolved if the user calling the API is a member of a single project. If the user is a member of multiple projects, the `projectId` query parameter needs to be specified explicitly. ' in: query required: false get: summary: Gets the event statuses description: 'Gets all events statuses for all devices and shipments of the project. An event status of a device is the most recent event of any rule or geofence the device is associated with. The same applies for shipments. The response contains a list of event status objects and each object has the following properties: * `trackingId` or `shipmentId`: a device ID or a shipment ID * `ruleId`: an associated rule or geofence ID * `eventSource`: the rule type * `eventType`: an event type of the latest event of the rule (same as the "event state") * `timestamp`: a time since when the device has been in this event state * `initialState`: initial state status for the event The array is sorted by the following fields in the following order: `trackingId`, `eventSource`, `timestamp`, `ruleId`, `geofenceId`. A time range can be defined with `before` and `after` timestamps. The response will contain event statuses that were recorded within the range. If the request is supplied with `eventSource` query parameter, the response results will be limited to the specified rule types only. If the request is supplied with `ruleId` query parameter, the response results will be limited to the specified rule IDs only. If the request is supplied with `trackingId` query parameter, the response results will be limited to the specified devices only. Also `shipmentId` can be used as a `trackingId`. If the request is supplied with `eventType` query parameter, the response results will be limited to the specified type only. If the request is supplied with `geofenceId` query parameter, it will only affect dwelling event statuses filtering, limiting the results to the specified geofence only. Other event types are not affected by this setting. Note that for the event statuses of geofence type, the `ruleId` is the `geofenceId`. If the request is supplied with `shipments` query parameter, the response results will be limited either to shipments (`shipments`=`true`) or devices (`shipments`=`false`) only. Otherwise, if `shipments` query parameter is not specified, response results will include both devices and shipments. If the request is supplied with `initialState` query parameter, the response will contain events having the specified initial state. All the aforementioned query parameters can be combined together.' tags: - Events security: - UserToken: [] - ClientToken: [] parameters: - name: eventSource in: query required: false schema: oneOf: - description: 'The event source rule type. ' type: string enum: - acceleration - attach - battery - detention - dwelling - geofence - humidity - online - pressure - shipmentEtaChange - shipmentSchedule - stock - tamper - temperature - utilization - type: array items: description: 'The event source rule type. ' type: string enum: - acceleration - attach - battery - detention - dwelling - geofence - humidity - online - pressure - shipmentEtaChange - shipmentSchedule - stock - tamper - temperature - utilization - name: eventType in: query required: false schema: oneOf: - description: 'Type of the event. An event is created every time an associated rule or geofence is triggered by a device ingestion. The event type depends on the data the device sends. Sensors that report numerical data (such as battery, humidity, pressure and temperature sensors), generate an event when the reported sensor reading of the device goes in or out of range, which is configured in the rule. This produces events of BELOW_RANGE, IN_RANGE and ABOVE_RANGE types. Sensors that report boolean data (such as attach and tamper sensors), generate events when the device transitions from one state to another, either from `false` to `true` or vice versa. This produces events of FALSE_TO_TRUE and TRUE_TO_FALSE types. The same event types are also generated by the online rule when the device state changes from `offline` (when the device has stopped ingesting data) to `online` (when the device data ingestion has resumed) or vice versa. The acceleration sensor generates events whenever the reported sensor reading crosses the acceleration threshold (for example, when the device was dropped). This produces events of the type EVENT. Such events are stateless. Events of INSIDE_GEOFENCE and OUTSIDE_GEOFENCE types are generated when the device enters or exits a geofence associated with the device. Events of DWELLING_STARTED type are generated when the device has stayed inside an associated geofence for longer than the threshold duration. DWELLING_ENDED type events are generated when dwelling of the device has ended. Events of DETENTION_STARTED type are generated when the device has been stationary for longer than the threshold duration, regardless whether the device is inside or outside of any geofence. DETENTION_ENDED type events will be generated when the device starts moving again. Events of UNUTILIZED type are generated when the device has been stationary for longer than the threshold duration. UTILIZED type events are generated when the device starts moving again after having been stationary. Events of OVERSTOCK, NORMAL_VOLUME and UNDERSTOCK types are generated when the number of assets inside a geofence crosses the `minVolume` and `maxVolume` thresholds of an associated stock rule. Event of SHIPMENT_ESTIMATE_CHANGED is generated when the estimated departure (ETD) or arrival (ETA) times deviate from the original estimates more than the defined threshold. Events of SHIPMENT_EARLY, SHIPMENT_ON_TIME and SHIPMENT_DELAYED types are generated when a shipment is too early, on time or delayed. ' type: string enum: - BELOW_RANGE - IN_RANGE - ABOVE_RANGE - FALSE_TO_TRUE - TRUE_TO_FALSE - EVENT - INSIDE_GEOFENCE - OUTSIDE_GEOFENCE - OVERSTOCK - NORMAL_VOLUME - UNDERSTOCK - DWELLING_STARTED - DWELLING_ENDED - DETENTION_STARTED - DETENTION_ENDED - UTILIZED - UNUTILIZED - SHIPMENT_EARLY - SHIPMENT_ON_TIME - SHIPMENT_DELAYED - SHIPMENT_ESTIMATE_CHANGED - type: array items: description: 'Type of the event. An event is created every time an associated rule or geofence is triggered by a device ingestion. The event type depends on the data the device sends. Sensors that report numerical data (such as battery, humidity, pressure and temperature sensors), generate an event when the reported sensor reading of the device goes in or out of range, which is configured in the rule. This produces events of BELOW_RANGE, IN_RANGE and ABOVE_RANGE types. Sensors that report boolean data (such as attach and tamper sensors), generate events when the device transitions from one state to another, either from `false` to `true` or vice versa. This produces events of FALSE_TO_TRUE and TRUE_TO_FALSE types. The same event types are also generated by the online rule when the device state changes from `offline` (when the device has stopped ingesting data) to `online` (when the device data ingestion has resumed) or vice versa. The acceleration sensor generates events whenever the reported sensor reading crosses the acceleration threshold (for example, when the device was dropped). This produces events of the type EVENT. Such events are stateless. Events of INSIDE_GEOFENCE and OUTSIDE_GEOFENCE types are generated when the device enters or exits a geofence associated with the device. Events of DWELLING_STARTED type are generated when the device has stayed inside an associated geofence for longer than the threshold duration. DWELLING_ENDED type events are generated when dwelling of the device has ended. Events of DETENTION_STARTED type are generated when the device has been stationary for longer than the threshold duration, regardless whether the device is inside or outside of any geofence. DETENTION_ENDED type events will be generated when the device starts moving again. Events of UNUTILIZED type are generated when the device has been stationary for longer than the threshold duration. UTILIZED type events are generated when the device starts moving again after having been stationary. Events of OVERSTOCK, NORMAL_VOLUME and UNDERSTOCK types are generated when the number of assets inside a geofence crosses the `minVolume` and `maxVolume` thresholds of an associated stock rule. Event of SHIPMENT_ESTIMATE_CHANGED is generated when the estimated departure (ETD) or arrival (ETA) times deviate from the original estimates more than the defined threshold. Events of SHIPMENT_EARLY, SHIPMENT_ON_TIME and SHIPMENT_DELAYED types are generated when a shipment is too early, on time or delayed. ' type: string enum: - BELOW_RANGE - IN_RANGE - ABOVE_RANGE - FALSE_TO_TRUE - TRUE_TO_FALSE - EVENT - INSIDE_GEOFENCE - OUTSIDE_GEOFENCE - OVERSTOCK - NORMAL_VOLUME - UNDERSTOCK - DWELLING_STARTED - DWELLING_ENDED - DETENTION_STARTED - DETENTION_ENDED - UTILIZED - UNUTILIZED - SHIPMENT_EARLY - SHIPMENT_ON_TIME - SHIPMENT_DELAYED - SHIPMENT_ESTIMATE_CHANGED - name: trackingId in: query required: false schema: oneOf: - 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. Alternatively, a valid `shipmentId` may be used. - type: array items: 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. Alternatively, a valid `shipmentId` may be used. - name: ruleId in: query required: false schema: oneOf: - type: string format: uuid description: 'ID of the rule or geofence. Must be a valid UUIDv4. ' - type: array items: type: string format: uuid description: 'ID of the rule or geofence. Must be a valid UUIDv4. ' - name: geofenceId in: query required: false schema: oneOf: - type: string format: uuid description: 'ID of the geofence. Must be a valid UUIDv4. This filter can be used to filter results related to dwelling event source. ' - type: array items: type: string format: uuid description: 'ID of the geofence. Must be a valid UUIDv4. This filter can be used to filter results related to dwelling event source. ' - name: initialState in: query required: false schema: 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 - name: shipments in: query required: false schema: type: boolean description: 'If `true`, the results will be limited to shipment event statuses only. If `false`, the results will be limited to device event statuses only. If not specified, the results will include both device and shipments event statuses. ' - name: before description: 'Milliseconds elapsed since 1 January 1970 00:00:00 UTC. The accepted range is from 1 to the current time. ' in: query required: false schema: type: number minimum: 1 - name: after description: 'Milliseconds elapsed since 1 January 1970 00:00:00 UTC. The accepted range is from 0 to the current time. ' in: query required: false schema: type: number minimum: 0 - name: pageToken description: A token from the previously returned response to retrieve the specified page. schema: type: string in: query required: false - name: count description: The number of items to return per page. schema: type: integer minimum: 1 maximum: 1000 default: 1000 in: query required: false - name: appId description: Application identifier. Used together with an external ID to identify a virtual device. schema: type: string minLength: 8 in: query required: false responses: '200': description: 'Successful The events were successfully retrieved. ' content: application/json: schema: allOf: - type: object properties: pageToken: type: string description: A token that can be used to retrieve the next page of the response. count: type: integer minimum: 0 maximum: 1000 default: 1000 description: The number of items in the response. - type: object properties: data: type: array items: oneOf: - title: Boolean event description: 'Events generated by online rule or by sensors that report boolean data (attach, tamper). ' allOf: - properties: 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. Alternatively, a valid `shipmentId` may be used. timestamp: type: integer description: Milliseconds elapsed since 1 January 1970 00:00:00 UTC. minimum: 2 maximum: 4102448400000 ruleId: type: string format: uuid description: 'Must be a valid UUIDv4. ' 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 - initialState - 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 - eventType - title: Range event description: 'Events generated by sensor that report numerical data (battery, humidity, pressure and temperature). ' allOf: - properties: 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. Alternatively, a valid `shipmentId` may be used. timestamp: type: integer description: Milliseconds elapsed since 1 January 1970 00:00:00 UTC. minimum: 2 maximum: 4102448400000 ruleId: type: string format: uuid description: 'Must be a valid UUIDv4. ' 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 - initialState - 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 - eventType - title: Generic event description: 'Events generated by sensor that report numerical data but only when a specific event occurs (eg. the device was dropped) ' allOf: - properties: 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. Alternatively, a valid `shipmentId` may be used. timestamp: type: integer description: Milliseconds elapsed since 1 January 1970 00:00:00 UTC. minimum: 2 maximum: 4102448400000 ruleId: type: string format: uuid description: 'Must be a valid UUIDv4. ' 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 - initialState - properties: eventSource: description: 'The event source: acceleration rule ' type: string enum: - acceleration eventType: type: string enum: - EVENT required: - eventSource - eventType - title: Geofence event description: 'Events generated by device crossing the geofence border. ' allOf: - properties: 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. Alternatively, a valid `shipmentId` may be used. timestamp: type: integer description: Milliseconds elapsed since 1 January 1970 00:00:00 UTC. minimum: 2 maximum: 4102448400000 ruleId: type: string format: uuid description: 'Must be a valid UUIDv4. ' 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 - initialState - properties: eventSource: description: 'The event source: geofence rule ' type: string enum: - geofence eventType: type: string enum: - INSIDE_GEOFENCE - OUTSIDE_GEOFENCE version: description: Geofence version type: integer required: - eventSource - eventType - 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: - properties: timestamp: type: integer description: Milliseconds elapsed since 1 January 1970 00:00:00 UTC. minimum: 2 maximum: 4102448400000 ruleId: type: string format: uuid description: 'Must be a valid UUIDv4. ' 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: - timestamp - ruleId - eventSource - eventType - type: object properties: 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: - initialState - title: Dwelling event description: 'Events generated by a device that has dwelled inside a geofence for longer than specified threshold duration ' allOf: - properties: 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. Alternatively, a valid `shipmentId` may be used. timestamp: type: integer description: Milliseconds elapsed since 1 January 1970 00:00:00 UTC. minimum: 2 maximum: 4102448400000 ruleId: type: string format: uuid description: 'Must be a valid UUIDv4. ' 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 - initialState - 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 - geofenceId - title: Detention event description: 'Events generated when a device has been stationary for longer than the specified threshold duration. ' allOf: - properties: 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. Alternatively, a valid `shipmentId` may be used. timestamp: type: integer description: Milliseconds elapsed since 1 January 1970 00:00:00 UTC. minimum: 2 maximum: 4102448400000 ruleId: type: string format: uuid description: 'Must be a valid UUIDv4. ' 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 - initialState - properties: eventSource: description: 'The event source: detention rule ' type: string enum: - detention eventType: type: string enum: - DETENTION_STARTED - DETENTION_ENDED required: - eventSource - eventType - 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: - properties: 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. Alternatively, a valid `shipmentId` may be used. timestamp: type: integer description: Milliseconds elapsed since 1 January 1970 00:00:00 UTC. minimum: 2 maximum: 4102448400000 ruleId: type: string format: uuid description: 'Must be a valid UUIDv4. ' 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 - initialState - properties: eventSource: description: 'The event source: utilization rule ' type: string enum: - utilization eventType: type: string enum: - UTILIZED - UNUTILIZED required: - eventSource - eventType - title: Shipment ETA change event description: 'Events generated by a shipment whose calculated ETD or ETA has changed ' allOf: - properties: 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. Alternatively, a valid `shipmentId` may be used. timestamp: type: integer description: Milliseconds elapsed since 1 January 1970 00:00:00 UTC. minimum: 2 maximum: 4102448400000 ruleId: type: string format: uuid description: 'Must be a valid UUIDv4. ' 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 - initialState - type: object properties: eventSource: type: string enum: - shipmentEtaChange eventType: type: string enum: - SHIPMENT_ESTIMATE_CHANGED extOrderId: description: Unique identifier for identifying the shipment in external systems type: string maxLength: 50 extSegmentId: description: Unique identifier for identifying the segment in external systems type: string maxLength: 50 segmentId: description: 'An ID of the segment where the ETD/ETA change was detected ' 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: Status of the segment. type: string enum: - pending - ongoing - completed - cancelled segmentOrigin: description: Segment origin location 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 cloud type: string minLength: 1 maxLength: 100 required: - id segmentDestination: description: Segment destination location 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 cloud type: string minLength: 1 maxLength: 100 required: - id shipmentEtd: description: Estimated time of departure of the shipment type: string format: date-time shipmentEta: description: Estimated time of arrival of the shipment type: string format: date-time 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 etaModelVersion: description: 'ML model version used for ETA calculation. Present only when ML model is used. ' type: string maxLength: 50 example: 2.3.1 segmentEtaChanges: type: array items: type: object properties: 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}$ segmentOrigin: description: Segment origin location 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 cloud type: string minLength: 1 maxLength: 100 required: - id segmentDestination: description: Segment destination location 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 cloud type: string minLength: 1 maxLength: 100 required: - id segmentEtd: description: Estimated time of departure of the segment type: string format: date-time segmentEta: description: Estimated time of arrival of the segment 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 required: - segmentId required: - eventSource - eventType - segmentId - segmentStatus - title: Shipment schedule event description: 'Events generated by a shipment that is ahead or delayed from its preplanned schedule ' allOf: - properties: 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. Alternatively, a valid `shipmentId` may be used. timestamp: type: integer description: Milliseconds elapsed since 1 January 1970 00:00:00 UTC. minimum: 2 maximum: 4102448400000 ruleId: type: string format: uuid description: 'Must be a valid UUIDv4. ' 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 - initialState - type: object properties: eventSource: type: string enum: - shipmentSchedule eventType: type: string enum: - SHIPMENT_EARLY - SHIPMENT_ON_TIME - SHIPMENT_DELAYED extOrderId: description: Unique identifier for identifying the shipment in external systems type: string maxLength: 50 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: Status of the segment. type: string enum: - pending - ongoing - completed - cancelled required: - eventSource - eventType - segmentId - segmentStatus example: count: 1 pageToken: 2lkjfdaoiekllldko=sdflkjdfasdi34 data: - trackingId: HERE-6da0f871-b4eb-4800-90e6-4bae86a788d6 eventSource: attach timestamp: 1499258057036 eventType: TRUE_TO_FALSE ruleId: e2f651ee-f196-4fa3-bf88-894dc131dea3 initialState: false '400': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Bad request code: 400 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The request object is in an incorrect format or has values that are invalid or out of range. details: hereErrorCode: 400306 description: 'Bad request The request object is in an incorrect format or has values that are invalid or out of range. If available, further error details are provided in the response body. ' '401': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Unauthorized code: 401 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The provided credentials are not valid. details: hereErrorCode: 401306 description: 'Unauthorized The request did not provide correct authentication details ' '403': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Forbidden code: 403 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The account does not have the correct privileges. details: hereErrorCode: 403306 description: 'Forbidden The account does not have the correct privileges ' '404': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Not Found code: 404 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The specified resource was not found. details: hereErrorCode: 404306 description: 'Not Found The specified resource was not found ' operationId: getEventsV3Statuses x-operation-id-source: derived /events/v3/statuses/deviceCounts: parameters: - in: header name: X-Request-Id schema: type: string format: uuid description: 'ID used for correlating requests within HERE Tracking. Used for logging and error reporting. Must be a valid UUIDv4. ' required: false - name: projectId schema: type: string minLength: 1 maxLength: 50 description: 'Project ID. Any HERE Tracking user must be a member of a Tracking project. The project ID can be implicitly resolved if the user calling the API is a member of a single project. If the user is a member of multiple projects, the `projectId` query parameter needs to be specified explicitly. ' in: query required: false get: summary: Gets the number of devices and shipments in each event state description: 'This API call counts the number of devices and shipments that are currently in the different event states per rule or per event source (that is per rule type). An event state of a device is the event type of the most recent device event. It indicates a state the device is currently in, in relation to a rule the device is associated with. For example, the event state can be either `INSIDE_GEOFENCE` or `OUTSIDE_GEOFENCE` in case the event source is `geofence`; or `BELOW_RANGE`, `IN_RANGE` or `ABOVE_RANGE` in case the event source is `battery` rule. A device can be in several different event states at the same time when it has more than one rule associated with it. For example, a device can be at the same time in `INSIDE_GEOFENCE` and `ABOVE_RANGE` event states. The same applies for shipments. The `groupBy` query parameter defines how the results are grouped. The default value for the `groupBy` parameter is `ruleId`. The response contains a list of objects, one per each rule, that are associated to at least one device or shipment of the project. Each object has the following properties: * `ruleId`: a rule ID * `eventSource`: the rule type * every distinct event state (applicable for the rule type) and the number of devices in this state * `total`: the total number of devices associated to the rule When the `groupBy` parameter value is `eventSource`, the response contains a list of objects, one per event source (that is per each rule type), that are associated to at least one device or shipment of the project. Each object has the following properties: * `eventSource`: a rule type * every distinct event state (applicable for the rule type) and the number of devices in this state. One device is counted only once per `eventType` state, but in case a single device is associated to multiple rules of the same type, it will be counted separately for each event state. * `total`: the total number of devices associated to the rule type. A single device is counted only once. For example, a device A is associated to 2 geofences and is inside one and outside the other. A device B is associated to 3 geofences and is outside all of them. With the request query parameter set as `groupBy`=`eventSource`, the response body will contain the following result item: ``` { "eventSource": "geofence", "INSIDE_GEOFENCE": 1, "OUTSIDE_GEOFENCE": 2, "total": 2 }. ``` If the request is supplied with `eventSource` query parameter, the response results will be limited to the specified rule types only. If the request is supplied with `ruleId` query parameter, the response results will be limited to the specified rule IDs only. If the request is supplied with `trackingId` query parameter, the response results will be limited to the specified devices only. Also `shipmentId` can be used as a `trackingId`. If the request is supplied with `geofenceId` query parameter, it will only affect dwelling event statuses filtering, limiting the results to the specified geofence only. Other event types are not affected by this setting. Note that for the event statuses of geofence type, the `ruleId` is the `geofenceId`. If the request is supplied with `shipments` query parameter, the response results will be limited either to shipments (`shipments`=`true`) or devices (`shipments`=`false`) only. Otherwise, if `shipments` query parameter is not specified, response results will include both devices and shipments. All the aforementioned query parameters can be combined together.' tags: - Events security: - UserToken: [] - ClientToken: [] parameters: - name: groupBy in: query schema: description: 'Define whether the number of devices and shipments in each event state is calculated per rule ID or per rule type. ' type: string enum: - ruleId - eventSource default: ruleId - name: eventSource in: query required: false schema: oneOf: - description: 'Source of the event. ' type: string enum: - attach - battery - geofence - humidity - pressure - tamper - temperature - acceleration - dwelling - detention - utilization - online - shipmentEtaChange - shipmentSchedule - type: array items: description: 'Source of the event. ' type: string enum: - attach - battery - geofence - humidity - pressure - tamper - temperature - acceleration - dwelling - detention - utilization - online - shipmentEtaChange - shipmentSchedule - name: trackingId in: query required: false schema: oneOf: - 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. Alternatively, a valid `shipmentId` may be used. - type: array items: 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. Alternatively, a valid `shipmentId` may be used. - name: ruleId in: query required: false schema: oneOf: - type: string format: uuid description: 'ID of the rule or geofence. Must be a valid UUIDv4. ' - type: array items: type: string format: uuid description: 'ID of the rule or geofence. Must be a valid UUIDv4. ' - name: geofenceId in: query required: false schema: oneOf: - type: string format: uuid description: 'ID of the geofence. Must be a valid UUIDv4. This filter can be used to filter results related to dwelling event source. ' - type: array items: type: string format: uuid description: 'ID of the geofence. Must be a valid UUIDv4. This filter can be used to filter results related to dwelling event source. ' - name: shipments in: query required: false schema: type: boolean description: 'If `true`, the results will be limited to shipment event statuses only. If `false`, the results will be limited to device event statuses only. If not specified, the results will include both device and shipments event statuses. ' - name: pageToken description: A token from the previously returned response to retrieve the specified page. schema: type: string in: query required: false - name: count description: The number of items to return per page. schema: type: integer minimum: 1 maximum: 1000 default: 1000 in: query required: false - name: appId description: Application identifier. Used together with an external ID to identify a virtual device. schema: type: string minLength: 8 in: query required: false responses: '200': description: 'Successful ' content: application/json: schema: allOf: - type: object properties: pageToken: type: string description: A token that can be used to retrieve the next page of the response. count: type: integer minimum: 0 maximum: 1000 default: 1000 description: The number of items in the response. - type: object properties: data: type: array items: oneOf: - title: attach, tamper, online allOf: - type: object properties: eventSource: type: string enum: - attach - tamper - online TRUE_TO_FALSE: type: number description: 'Number of devices currently in this event state. ' FALSE_TO_TRUE: type: number description: 'Number of devices currently in this event state. ' required: - eventSource - TRUE_TO_FALSE - FALSE_TO_TRUE - properties: total: type: number description: Number of devices associated to the respective rule or rules. ruleId: type: string format: uuid description: 'Must be a valid UUIDv4. ' required: - total - title: battery, humidity, pressure, temperature allOf: - type: object properties: eventSource: type: string enum: - battery - humidity - pressure - temperature BELOW_RANGE: type: number description: 'Number of devices currently in this event state. ' IN_RANGE: type: number description: 'Number of devices currently in this event state. ' ABOVE_RANGE: type: number description: 'Number of devices currently in this event state. ' required: - eventSource - BELOW_RANGE - IN_RANGE - ABOVE_RANGE - properties: total: type: number description: Number of devices associated to the respective rule or rules. ruleId: type: string format: uuid description: 'Must be a valid UUIDv4. ' required: - total - title: acceleration allOf: - type: object properties: eventSource: type: string enum: - acceleration EVENT: type: number description: 'Number of devices currently in this event state. ' required: - eventSource - EVENT - properties: total: type: number description: Number of devices associated to the respective rule or rules. ruleId: type: string format: uuid description: 'Must be a valid UUIDv4. ' required: - total - title: geofence allOf: - type: object properties: eventSource: type: string enum: - geofence INSIDE_GEOFENCE: type: number description: 'Number of devices currently in this event state. ' OUTSIDE_GEOFENCE: type: number description: 'Number of devices currently in this event state. ' required: - eventSource - INSIDE_GEOFENCE - OUTSIDE_GEOFENCE - properties: total: type: number description: Number of devices associated to the respective rule or rules. ruleId: type: string format: uuid description: 'Must be a valid UUIDv4. ' required: - total - title: dwelling allOf: - type: object properties: eventSource: type: string enum: - dwelling DWELLING_STARTED: type: number description: 'Number of devices currently in this event state. ' DWELLING_ENDED: type: number description: 'Number of devices currently in this event state. ' required: - eventSource - DWELLING_STARTED - DWELLING_ENDED - properties: total: type: number description: Number of devices associated to the respective rule or rules. ruleId: type: string format: uuid description: 'Must be a valid UUIDv4. ' required: - total - title: detention allOf: - type: object properties: eventSource: type: string enum: - detention DETENTION_STARTED: type: number description: 'Number of devices currently in this event state. ' DETENTION_ENDED: type: number description: 'Number of devices currently in this event state. ' required: - eventSource - DETENTION_STARTED - DETENTION_ENDED - properties: total: type: number description: Number of devices associated to the respective rule or rules. ruleId: type: string format: uuid description: 'Must be a valid UUIDv4. ' required: - total - title: utilization allOf: - type: object properties: eventSource: type: string enum: - utilization UTILIZED: type: number description: 'Number of devices currently in this event state. ' UNUTILIZED: type: number description: 'Number of devices currently in this event state. ' required: - eventSource - UTILIZED - UNUTILIZED - properties: total: type: number description: Number of devices associated to the respective rule or rules. ruleId: type: string format: uuid description: 'Must be a valid UUIDv4. ' required: - total - title: shipmentSchedule allOf: - type: object properties: eventSource: type: string enum: - shipmentSchedule SHIPMENT_EARLY: type: number description: 'Number of devices currently in this event state. ' SHIPMENT_ON_TIME: type: number description: 'Number of devices currently in this event state. ' SHIPMENT_DELAYED: type: number description: 'Number of devices currently in this event state. ' required: - eventSource - SHIPMENT_EARLY - SHIPMENT_ON_TIME - SHIPMENT_DELAYED - properties: total: type: number description: Number of devices associated to the respective rule or rules. ruleId: type: string format: uuid description: 'Must be a valid UUIDv4. ' required: - total - title: shipmentEtaChange allOf: - type: object properties: eventSource: type: string enum: - shipmentEtaChange SHIPMENT_ESTIMATE_CHANGED: type: number description: 'Number of devices currently in this event state. ' required: - eventSource - SHIPMENT_ESTIMATE_CHANGED - properties: total: type: number description: Number of devices associated to the respective rule or rules. ruleId: type: string format: uuid description: 'Must be a valid UUIDv4. ' required: - total example: count: 3 pageToken: sakuh8342jhe83290US87sdjhAS8we data: - ruleId: e2f651ee-f196-4fa3-bf88-894dc131dea3 eventSource: attach FALSE_TO_TRUE: 4 TRUE_TO_FALSE: 1 total: 5 - ruleId: 4e74ad36-7dd3-459a-ace4-f8a7f1c6085d eventSource: battery BELOW_RANGE: 1 IN_RANGE: 4 ABOVE_RANGE: 0 total: 5 - ruleId: 018eedc7-1b16-4233-80b1-2b13a307b4aa eventSource: dwelling DWELLING_STARTED: 2 DWELLING_ENDED: 5 total: 5 '400': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Bad request code: 400 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The request object is in an incorrect format or has values that are invalid or out of range. details: hereErrorCode: 400306 description: 'Bad request The request object is in an incorrect format or has values that are invalid or out of range. If available, further error details are provided in the response body. ' '401': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Unauthorized code: 401 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The provided credentials are not valid. details: hereErrorCode: 401306 description: 'Unauthorized The request did not provide correct authentication details ' '403': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Forbidden code: 403 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The account does not have the correct privileges. details: hereErrorCode: 403306 description: 'Forbidden The account does not have the correct privileges ' '404': content: application/json: schema: type: object properties: error: type: string description: An HTTP error description code: type: integer description: An HTTP status code message: type: string description: Descriptive text that explains the error id: type: string format: uuid description: An error ID that allows you to trace the error details details: description: An optional object containing more information about the error required: - error - code - id example: error: Not Found code: 404 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The specified resource was not found. details: hereErrorCode: 404306 description: 'Not Found The specified resource was not found ' operationId: getEventsV3StatusesDeviceCounts x-operation-id-source: derived components: securitySchemes: ApiKey: type: apiKey in: query name: apiKey description: 'A key generated specifically to authenticate API requests. For more information on how to get an API key, see the [Identity & Access Management Developer Guide](https://www.here.com/docs/bundle/identity-and-access-management-developer-guide/page/README.html). ' Bearer: type: http scheme: bearer bearerFormat: JWT description: "A token obtained from a separate endpoint using client credentials and an OAuth 1.0a HMAC-SHA256 signed request.\n\nUsers are authenticated using an OAuth 1.0 bearer token obtained using the `/users/v2/login` endpoint.\n\nDevices are authenticated using an OAuth 1.0 bearer token obtained using the `/v2/token` endpoint.\n\n**Make a request using the bearer token for authentication**\n\nMake a request with an `Authorization` header containing the obtained bearer token.\n\nExample:\n\n```\n Authorization: Bearer h1.yxPIksZ0ViLq77f1Nh-9cg.NVgGBZVlCU8G7kjV_...\n```\n\n> **Note:** For the available authentication options, see the [Identity & Access Management Guide](https://www.here.com/docs/bundle/identity-and-access-management-developer-guide/page/README.html).\n" UserToken: type: http scheme: bearer bearerFormat: JWT description: "This token is obtained using user's realm, username and password and then further scoped to a specific project.\n\nFirst obtain access token from [/users/v2/login endpoint](#tag/Users/paths/~1users~1v2~1login/post).\nThen use [/users/v2/tokenExchange endpoint](#tag/Users/paths/~1users~1v2~1tokenExchange/post) to convert\nyour user access token into a project-scoped user access token.\n\nOnce done, make a request with an `Authorization` header containing the scoped access token.\n\nExample:\n\n```\n Authorization: Bearer h1.xikjhDyJsE17VLhPXiu.fm3WsNOunstXH78RvU8_...\n```\n" ClientToken: type: http scheme: bearer bearerFormat: JWT description: "This token is obtained using application's OAuth 2.0 credentials (key + secret) and then scoped to a specific project.\n\nFollow [instructions here](https://www.here.com/docs/bundle/identity-and-access-management-developer-guide/page/topics/plat-token.html)\nto create your application credentials and obtain the token using OLP CLI. With an exception\nthat when getting the token you need to provide also project's HRN value:\n\n```\n olp api token get --scope {PROJECT_HRN}\n```\n\nOnce done, make a request with an `Authorization` header containing the scoped access token.\n\nExample:\n\n```\n Authorization: Bearer h1.PGEVzQmaoW5pyBYUlWu.SQoSCF7qpToEFMHgSlJ_...\n```\n" DeviceToken: type: http scheme: bearer bearerFormat: JWT description: 'This access token is obtained from [/v2/token endpoint](#tag/Ingestion/paths/~1v2~1token/post) using a signed request. > **Note:** Only a small subset of our endpoints support this token type and is only useful for hardware devices. > You probably won''t need this. ' signedRequest: type: http scheme: oauth description: "HERE Tracking requires that you sign your requests for tokens. The signature method uses the OAuth 1.0 standard. For more information on this standard, see the [OAuth Core 1.0](https://oauth.net/core/1.0/) specification.\n\n> **Note:** You must create a new signature for each token request to HERE Tracking. Signatures can only be used once.\n\n**Create the Signature Base String**\n\nThe first step in creating a signature is to create the signature base string. This string contains the parameters to use when generating the signature.\n\n*1. To begin, make sure you have the information listed in the following table.*\n\n| Parameter | Description |\n| ------------------------ | -----------------------------------------|\n| oauth\\_consumer\\_key | The device ID for which you want to generate a token. |\n| oauth\\_signature\\_method | Always use \"HMAC-SHA256\". |\n| oauth\\_timestamp | The number of seconds since the Unix epoch at the point the request is generated. This must be within 10 seconds of the timestamp returned by the `/v2/timestamp` endpoint. |\n| oauth\\_nonce | A unique string for this signature. The string cannot have been used in a previous signature. Each token generation request to HERE Tracking must have a unique signature, and the value in this parameter is what is used to ensure the signature is unique. |\n| oauth\\_version | Always use \"1.0\". |\n\n*2. Combine these values into a single string by following these steps:*\n\n 1. URL encode every key and value.\n 2. Sort the list of key-value pairs alphabetically by key.\n 3. Concatenate each key/value pair, separating each with an ampersand character (\"&\").\n\nThe result is a parameter string that looks like this (line breaks are added for legibility):\n\n ```\n oauth_consumer_key=47164fb0-b7b3-49e8-891b-650270b82cf2\n &oauth_nonce=LIIpk4\n &oauth_signature_method=HMAC-SHA256\n &oauth_timestamp=1513634609\n &oauth_version=1.0\n ```\n\n*3. Combine the HTTP method, base URL, and parameter string into a single string called the \"base string\". This will be the string from which the signature is generated. The base string is in this format:*\n\n ```\n POST&https://tracking.api.here.com/v2/token&\n ```\n\n The base string consists of:\n\n 1. The HTTP method in caps (POST) followed by an ampersand (\"&\")\n 2. The URL of the HERE Tracking token endpoint followed by an ampersand (\"&\")\n 3. The URL-encoded parameter string.\n\n For example (line breaks are added for legibility):\n\n ```\n POST\n &https%3A%2F%2Ftracking.api.here.com%2Fv2%2Ftoken\n &oauth_consumer_key%3D47164fb0-b7b3-49e8-891b-650270b82cf2%26\n oauth_nonce%3DLIIpk4%26oauth_signature_method%3DHMAC-SHA256%26\n oauth_timestamp%3D1513634609%26oauth_version%3D1.0\n ```\n\n > **Note:** The URL-encoded base string should contain exactly two ampersands (\"&\").\n\n**Create the signature**\n\nThe signing key used to sign the base string is the `deviceSecret` followed by an ampersand (\"&\").\n\nCreate the signature by passing the signature base string and the signing key to the `HMAC-SHA256` hashing algorithm and converting the result to a `base64` string. Then, use the signature to request a token.\n\n**Request the token**\n\nMake a `POST` request to this endpoint with an `Authorization` header constructed from the above parameters and the generated signature.\n\nExample:\n\n```\n Authorization: OAuth oauth_consumer_key=\"47164fb0-b7b3-49e8-891b-650270b82cf2\",\n oauth_signature_method=\"HMAC-SHA256\",\n oauth_timestamp=\"1513634609\",\n oauth_nonce=\"LIIpk4\",\n oauth_version=\"1.0\",\n oauth_signature=\"pQ9EJX14L736B%2Br7uZl4yQlO6Xw%3D\"\n```\n" externalDocs: description: The Developer guide and Release notes are available here. url: https://www.here.com/docs/bundle/tracking-api-developer-guide