openapi: 3.2.0 info: version: 2.6.11 title: HERE Tracking Shipments 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 Shipments service manages shipments. name: Shipments paths: /shipments/v4/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: - Shipments operationId: getShipmentsV4Health x-operation-id-source: derived /shipments/v4/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: - Shipments operationId: getShipmentsV4Version x-operation-id-source: derived /shipments/v4: 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 post: summary: Creates a shipment description: 'Creates a new shipment. A shipment consists of segments each representing a part of the logistics journey. A segment spans from a location to another and each segment may be assigned a different tracking device. The segments of the shipment must form a continuous chain of locations, that is the origin of a segment must match the destination of a previous segment.' security: - UserToken: [] - ClientToken: [] requestBody: content: application/json: schema: type: object title: From new description: Body for creating a shipment properties: name: description: Name of the shipment type: string maxLength: 50 description: description: Description of the shipment type: string maxLength: 1000 extOrderId: description: Unique identifier for identifying the shipment in external systems type: string maxLength: 50 autoStart: default: true description: 'A boolean parameter defining whether the shipment starts upon exiting the first origin location. ' type: boolean subShipment: default: false description: Flag telling if shipment is a subShipment. type: boolean ruleIds: description: Array of `ruleId`s to associate with the shipment type: array items: type: string format: uuid description: 'Must be a valid UUIDv4. ' maxItems: 10 segments: description: 'Array of objects each defining the origin and destination of the segment. The maximum number of segments in a shipment can have stricter project specific limits than the maximum value documented here. ' type: array minItems: 1 maxItems: 100 items: description: A segment of a shipment. type: object properties: name: description: Name of the segment type: string maxLength: 50 description: description: Description of the segment type: string maxLength: 1000 transportMode: description: Transport mode of the segment type: string enum: - car - truck - sea - air - barge - rail - railTruck - truckRail - bargeTruck - truckBarge - undefined extSegmentId: description: Unique identifier for identifying the segment in external systems type: string maxLength: 50 trackingId: description: ID of the tracking device that produces data for this segment type: string minLength: 1 maxLength: 50 origin: description: Origin location of this segment 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}$ destination: description: Destination location of this segment 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}$ providedEtd: description: ETD for the segment type: string format: date-time providedEta: description: ETA for the segment type: string format: date-time metadata: type: object description: 'Metadata JSON object ' example: priority: high required: - transportMode - origin - destination additionalProperties: false example: name: Truck transport description: From factory to port transportMode: truck trackingId: HERE-540bb24b-0d57-4f8c-aeaf-6c91cd0aff8d origin: LOC-54531862-f87a-4b70-99a4-0e8224a56be4 destination: LOC-7b6b15cc-2307-4875-9f66-99deb5227e92 providedEtd: description: ETD for the shipment type: string format: date-time providedEta: description: ETA for the shipment type: string format: date-time metadata: type: object description: 'Metadata JSON object ' example: priority: high required: - segments additionalProperties: false example: name: From Portugal to Panama description: A shipment consisting of four segments autoStart: true subShipment: false ruleIds: - 712dde2c-20e6-4903-82f1-0beb0dd9e4bd - 6d1da24b-5187-42ab-9eb5-1e43c61b6bae segments: - name: Truck transport description: From factory to port transportMode: truck trackingId: HERE-540bb24b-0d57-4f8c-aeaf-6c91cd0aff8d origin: LOC-54531862-f87a-4b70-99a4-0e8224a56be4 destination: LOC-7b6b15cc-2307-4875-9f66-99deb5227e92 - name: Marine transport description: From port to another port transportMode: sea trackingId: VRTR-8b9fd950-ce19-4aaf-98d5-840a76652658 origin: LOC-7b6b15cc-2307-4875-9f66-99deb5227e92 destination: LOC-a2dc2c70-cc3e-4fa5-ac77-4c63558e7f97 - name: Truck transport description: From port to storage transportMode: truck trackingId: HERE-540bb24b-0d57-4f8c-aeaf-6c91cd0aff8d origin: LOC-a2dc2c70-cc3e-4fa5-ac77-4c63558e7f97 destination: LOC-733deb91-efa3-41b6-9003-92845866b511 responses: '201': description: 'Created. The shipment has been successfully created. ' content: application/json: schema: type: object properties: shipmentId: description: Shipment ID type: string pattern: ^SHP-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ required: - shipmentId additionalProperties: false example: shipmentId: SHP-d306beb9-e110-450e-9f81-3db9de1ac001 '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 ' '413': 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: Payload Too Large code: 413 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The request size exceeds the maximum size limit for payloads. details: hereErrorCode: 413306 description: 'Payload Too Large The request size exceeds the maximum size limit for payloads. ' tags: - Shipments operationId: postShipmentsV4 x-operation-id-source: derived get: deprecated: true summary: Gets all shipments description: Gets all shipments of the project. parameters: - name: pageToken description: A token from the previously returned response to retrieve the specified page. schema: type: string in: query required: false - name: limit description: The number of items to return per page schema: type: integer minimum: 1 maximum: 100 default: 100 in: query required: false - name: status description: Filter the results by shipment status schema: type: string enum: - pending - ongoing - completed - cancelled in: query required: false - name: startedBefore description: Return only shipments that started before the specified timestamp schema: type: string format: date-time in: query required: false - name: startedAfter description: Return only shipments that started after the specified timestamp schema: type: string format: date-time in: query required: false - name: endedBefore description: Return only shipments that ended before the specified timestamp schema: type: string format: date-time in: query required: false - name: endedAfter description: Return only shipments that ended after the specified timestamp schema: type: string format: date-time in: query required: false - name: name description: 'Filter shipments by name. Matching is case-insensitive if wildcards are used, otherwise case-sensitive. The following wildcards can be used: ''*'' matches any number of any characters, ''?'' matches any single character. ' schema: type: string in: query required: false example: '*portugal*' - name: shipmentId description: 'Filter shipments by `shipmentId` Matching is case-insensitive if wildcards are used, otherwise case-sensitive. The following wildcards can be used: ''*'' matches any number of any characters, ''?'' matches any single character. ' schema: type: string in: query required: false - name: extOrderId description: 'Filter shipments by `extOrderId` Matching is case-insensitive if wildcards are used, otherwise case-sensitive. The following wildcards can be used: ''*'' matches any number of any characters, ''?'' matches any single character. ' schema: type: string in: query required: false - name: isSubShipment description: Returns only shipments marked as subShipments schema: type: boolean in: query required: false - name: createdBefore description: Return only shipments that have been created before specified timestamp schema: type: string format: date-time in: query required: false - name: createdAfter description: Return only shipments that have been created after specified timestamp schema: type: string format: date-time in: query required: false - name: sort description: 'A parameter to specify field to sort by and order. The following format can be used: ''name:asc'' sort by name in ascending order, ''shipmentId:desc'' sort by shipmentId in descending order. Allowed fields to sort by: shipmentId, extOrderId, name, status, startedAt, createdAt, endedAt, providedEtd, providedEta, calculatedEtd, calculatedEta. ' schema: oneOf: - type: string pattern: ^(shipmentId|extOrderId|name|status|startedAt|createdAt|endedAt|providedEtd|providedEta|calculatedEtd|calculatedEta):(asc|desc)$ - type: array items: type: string pattern: ^(shipmentId|extOrderId|name|status|startedAt|createdAt|endedAt|providedEtd|providedEta|calculatedEtd|calculatedEta):(asc|desc)$ in: query required: false example: name:asc security: - UserToken: [] - ClientToken: [] responses: '200': description: 'Response body contains an array of shipment objects, `count` indicates the number of returned items, `limit` indicates the requested maximum amount of records to be returned and `pageToken` is the next page token if available. ' content: application/json: schema: type: object properties: limit: description: Maximum number of items as specified in request type: integer minimum: 1 maximum: 100 count: description: Number of items returned in the response type: integer minimum: 0 maximum: 100 nextPageToken: description: Token to fetch the next page (if exists) type: string items: type: array items: description: Shipment details type: object properties: shipmentId: description: Shipment ID type: string pattern: ^SHP-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ name: description: Name of the shipment type: string maxLength: 50 description: description: Description of the shipment type: string maxLength: 1000 extOrderId: description: Unique identifier for identifying the shipment in external systems type: string maxLength: 50 autoStart: description: 'A boolean parameter defining whether the shipment starts upon exiting the first origin location. ' type: boolean subShipment: description: Flag telling if shipment is a subShipment. type: boolean status: description: Status of the shipment type: string enum: - pending - ongoing - completed - cancelled startedAt: type: string format: date-time description: Timestamp indicating when the shipment started createdAt: type: string format: date-time description: Timestamp indicating when the shipment has been created endedAt: type: string format: date-time description: Timestamp indicating when the shipment ended providedEtd: type: string format: date-time description: User provided ETD for the shipment providedEta: type: string format: date-time description: User provided ETA for the shipment calculatedEtd: type: string format: date-time description: Calculated ETD for the shipment calculatedEta: type: string format: date-time description: Calculated ETA for the shipment etaCalculatedAt: type: string format: date-time description: Timestamp indicating when ETA was calculated ruleIds: description: Array of `ruleId`s to associate with the shipment type: array items: type: string format: uuid description: 'Must be a valid UUIDv4. ' maxItems: 10 segments: description: Array containing the segment details type: array items: description: Segment details type: object properties: 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}$ name: description: Name of the segment type: string maxLength: 50 description: description: Description of the segment type: string maxLength: 1000 status: description: Status of the segment type: string enum: - pending - ongoing - completed - cancelled transportMode: description: Transport mode of the segment type: string enum: - car - truck - sea - air - barge - rail - railTruck - truckRail - bargeTruck - truckBarge - undefined extSegmentId: description: Unique identifier for identifying the segment in external systems type: string maxLength: 50 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. origin: description: Origin location of this segment 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}$ destination: description: Destination location of this segment 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}$ startedAt: type: string format: date-time description: Timestamp indicating when this segment started endedAt: type: string format: date-time description: Timestamp indicating when this segment ended createdAt: type: string format: date-time description: Timestamp indicating when this segment created providedEtd: type: string format: date-time description: User provided ETD for the segment providedEta: type: string format: date-time description: User provided ETA for the segment calculatedEtd: type: string format: date-time description: Calculated ETD for the segment calculatedEta: type: string format: date-time description: Calculated ETA for the segment etaCalculatedAt: type: string format: date-time description: Timestamp indicating when ETA was calculated metadata: type: object description: 'Metadata JSON object ' example: priority: high additionalProperties: false example: segmentId: SEG-156986fa-1ed9-42ab-a022-9ac1a70ae137 name: Truck transport description: From factory to port status: pending transportMode: truck trackingId: HERE-540bb24b-0d57-4f8c-aeaf-6c91cd0aff8d origin: LOC-54531862-f87a-4b70-99a4-0e8224a56be4 destination: LOC-7b6b15cc-2307-4875-9f66-99deb5227e92 startedAt: '2020-05-27T11:40:01Z' endedAt: '2020-05-27T11:40:01Z' metadata: type: object description: 'Metadata JSON object ' example: priority: high required: - shipmentId - autoStart - status - segments additionalProperties: false example: shipmentId: SHP-d306beb9-e110-450e-9f81-3db9de1ac001 name: From Portugal to Panama description: A shipment consisting of one segment autoStart: true subShipment: false status: pending ruleIds: - 712dde2c-20e6-4903-82f1-0beb0dd9e4bd - 6d1da24b-5187-42ab-9eb5-1e43c61b6bae segments: - segmentId: SEG-156986fa-1ed9-42ab-a022-9ac1a70ae137 name: Truck transport description: From factory to port status: pending transportMode: truck trackingId: HERE-540bb24b-0d57-4f8c-aeaf-6c91cd0aff8d origin: LOC-54531862-f87a-4b70-99a4-0e8224a56be4 destination: LOC-7b6b15cc-2307-4875-9f66-99deb5227e92 startedAt: '2020-05-27T11:40:01Z' endedAt: '2020-05-27T11:40:01Z' total: type: integer description: Total number of shipments for query required: - limit - count - items additionalProperties: false example: limit: 100 count: 1 items: - shipmentId: SHP-d306beb9-e110-450e-9f81-3db9de1ac001 name: From Portugal to Panama description: A shipment consisting of one segment autoStart: true subShipment: false status: pending segments: - segmentId: SEG-156986fa-1ed9-42ab-a022-9ac1a70ae137 name: Truck transport description: From factory to port status: pending transportMode: truck trackingId: HERE-540bb24b-0d57-4f8c-aeaf-6c91cd0aff8d origin: LOC-54531862-f87a-4b70-99a4-0e8224a56be4 destination: LOC-7b6b15cc-2307-4875-9f66-99deb5227e92 startedAt: '2020-05-27T11:40:01Z' endedAt: '2020-05-27T11:40:01Z' '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 ' tags: - Shipments operationId: getShipmentsV4 x-operation-id-source: derived delete: summary: Deletes all shipments description: 'Deletes all the shipments of the project. Note that one needs to supply an HTTP header `x-confirm` with the value `true` to force the deletion. If the header is not provided, the request will fail. If the project has many shipments, deleting them all can take a while. This operation returns 202 as long as the shipments deletion is in progress and 204 after all shipments have been deleted.' parameters: - schema: type: string enum: - 'true' in: header name: x-confirm required: true description: 'A safety measure that prevents one from accidentally deleting data. To confirm that all entries should be deleted, set the value to `true`. ' security: - UserToken: [] - ClientToken: [] responses: '202': description: 'Accepted Shipments deletion is in progress. ' '204': description: 'Successful (no content). All shipments were successfully deleted. ' '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 ' tags: - Shipments operationId: deleteShipmentsV4 x-operation-id-source: derived /shipments/v4/{shipmentId}: parameters: - name: shipmentId schema: description: Shipment ID type: string pattern: ^SHP-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ in: path required: true get: summary: Gets a shipment details description: Gets details of a specific shipment identified by the `shipmentId`. security: - UserToken: [] - ClientToken: [] responses: '200': description: 'Success. The shipment information was returned ' content: application/json: schema: description: Shipment details type: object properties: shipmentId: description: Shipment ID type: string pattern: ^SHP-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ name: description: Name of the shipment type: string maxLength: 50 description: description: Description of the shipment type: string maxLength: 1000 extOrderId: description: Unique identifier for identifying the shipment in external systems type: string maxLength: 50 autoStart: description: 'A boolean parameter defining whether the shipment starts upon exiting the first origin location. ' type: boolean subShipment: description: Flag telling if shipment is a subShipment. type: boolean status: description: Status of the shipment type: string enum: - pending - ongoing - completed - cancelled startedAt: type: string format: date-time description: Timestamp indicating when the shipment started createdAt: type: string format: date-time description: Timestamp indicating when the shipment has been created endedAt: type: string format: date-time description: Timestamp indicating when the shipment ended providedEtd: type: string format: date-time description: User provided ETD for the shipment providedEta: type: string format: date-time description: User provided ETA for the shipment calculatedEtd: type: string format: date-time description: Calculated ETD for the shipment calculatedEta: type: string format: date-time description: Calculated ETA for the shipment etaCalculatedAt: type: string format: date-time description: Timestamp indicating when ETA was calculated ruleIds: description: Array of `ruleId`s to associate with the shipment type: array items: type: string format: uuid description: 'Must be a valid UUIDv4. ' maxItems: 10 segments: description: Array containing the segment details type: array items: description: Segment details type: object properties: 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}$ name: description: Name of the segment type: string maxLength: 50 description: description: Description of the segment type: string maxLength: 1000 status: description: Status of the segment type: string enum: - pending - ongoing - completed - cancelled transportMode: description: Transport mode of the segment type: string enum: - car - truck - sea - air - barge - rail - railTruck - truckRail - bargeTruck - truckBarge - undefined extSegmentId: description: Unique identifier for identifying the segment in external systems type: string maxLength: 50 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. origin: description: Origin location of this segment 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}$ destination: description: Destination location of this segment 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}$ startedAt: type: string format: date-time description: Timestamp indicating when this segment started endedAt: type: string format: date-time description: Timestamp indicating when this segment ended createdAt: type: string format: date-time description: Timestamp indicating when this segment created providedEtd: type: string format: date-time description: User provided ETD for the segment providedEta: type: string format: date-time description: User provided ETA for the segment calculatedEtd: type: string format: date-time description: Calculated ETD for the segment calculatedEta: type: string format: date-time description: Calculated ETA for the segment etaCalculatedAt: type: string format: date-time description: Timestamp indicating when ETA was calculated metadata: type: object description: 'Metadata JSON object ' example: priority: high additionalProperties: false example: segmentId: SEG-156986fa-1ed9-42ab-a022-9ac1a70ae137 name: Truck transport description: From factory to port status: pending transportMode: truck trackingId: HERE-540bb24b-0d57-4f8c-aeaf-6c91cd0aff8d origin: LOC-54531862-f87a-4b70-99a4-0e8224a56be4 destination: LOC-7b6b15cc-2307-4875-9f66-99deb5227e92 startedAt: '2020-05-27T11:40:01Z' endedAt: '2020-05-27T11:40:01Z' metadata: type: object description: 'Metadata JSON object ' example: priority: high required: - shipmentId - autoStart - status - segments additionalProperties: false example: shipmentId: SHP-d306beb9-e110-450e-9f81-3db9de1ac001 name: From Portugal to Panama description: A shipment consisting of one segment autoStart: true subShipment: false status: pending ruleIds: - 712dde2c-20e6-4903-82f1-0beb0dd9e4bd - 6d1da24b-5187-42ab-9eb5-1e43c61b6bae segments: - segmentId: SEG-156986fa-1ed9-42ab-a022-9ac1a70ae137 name: Truck transport description: From factory to port status: pending transportMode: truck trackingId: HERE-540bb24b-0d57-4f8c-aeaf-6c91cd0aff8d origin: LOC-54531862-f87a-4b70-99a4-0e8224a56be4 destination: LOC-7b6b15cc-2307-4875-9f66-99deb5227e92 startedAt: '2020-05-27T11:40:01Z' endedAt: '2020-05-27T11:40:01Z' '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 ' tags: - Shipments operationId: getShipmentsV4ByShipmentId x-operation-id-source: derived patch: summary: Updates a shipment details description: 'Updates details of a shipment identified by the `shipmentId`. This is a partial update, meaning that only the provided fields will be updated, except when updating segments, the whole segments will be replaced fully. Changing the status of the shipment affects the statuses of the segments. The following status changes are allowed: * `pending` → `ongoing` * changes the status of the first segment to `ongoing` * `pending` → `cancelled` * changes the status of `ongoing` and all `pending` segments to `cancelled` * `ongoing` → `cancelled` * cancels the current `ongoing` segment and all the succeeding segments * `ongoing` → `completed` * completes the current `ongoing` segment and cancels all the succeeding segments ***Note***: `segments` and `autoStart` can be updated via this API call only if the shipment is in `pending` state. The "Tracker only" variant of the request updates the given tracking device to all `ongoing` and `pending` state segments of the shipment, so it allows to make tracker association both for `ongoing` and `pending` state shipments.' security: - UserToken: [] - ClientToken: [] requestBody: content: application/json: schema: type: object oneOf: - description: Body for updating a shipment title: Full shipment type: object properties: name: description: Name of the shipment type: string maxLength: 50 description: description: Description of the shipment type: string maxLength: 1000 extOrderId: description: Unique identifier for identifying the shipment in external systems type: string maxLength: 50 autoStart: description: 'A boolean parameter defining whether the shipment starts upon exiting the first origin location. ' type: boolean subShipment: description: Flag telling if shipment is a subShipment. type: boolean status: description: Status of the shipment type: string enum: - pending - ongoing - completed - cancelled ruleIds: description: Array of `ruleId`s to associate with the shipment type: array items: type: string format: uuid description: 'Must be a valid UUIDv4. ' maxItems: 10 segments: description: 'Array of objects each defining the origin and destination of the segment. The maximum number of segments in a shipment can have stricter project specific limits than the maximum value documented here. ' type: array minItems: 1 maxItems: 100 items: description: A segment of a shipment. type: object properties: name: description: Name of the segment type: string maxLength: 50 description: description: Description of the segment type: string maxLength: 1000 transportMode: description: Transport mode of the segment type: string enum: - car - truck - sea - air - barge - rail - railTruck - truckRail - bargeTruck - truckBarge - undefined extSegmentId: description: Unique identifier for identifying the segment in external systems type: string maxLength: 50 trackingId: description: ID of the tracking device that produces data for this segment type: string minLength: 1 maxLength: 50 origin: description: Origin location of this segment 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}$ destination: description: Destination location of this segment 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}$ providedEtd: description: ETD for the segment type: string format: date-time providedEta: description: ETA for the segment type: string format: date-time metadata: type: object description: 'Metadata JSON object ' example: priority: high required: - transportMode - origin - destination additionalProperties: false example: name: Truck transport description: From factory to port transportMode: truck trackingId: HERE-540bb24b-0d57-4f8c-aeaf-6c91cd0aff8d origin: LOC-54531862-f87a-4b70-99a4-0e8224a56be4 destination: LOC-7b6b15cc-2307-4875-9f66-99deb5227e92 providedEtd: type: string format: date-time description: ETD for the shipment providedEta: type: string format: date-time description: ETA for the shipment metadata: type: object description: 'Metadata JSON object ' example: priority: high additionalProperties: false - description: Body for updating the tracker used in the shipment title: Tracker only type: object properties: trackingId: description: ID of the tracking device that produces data for the shipment type: string minLength: 1 maxLength: 50 additionalProperties: false responses: '204': description: 'Successful (no content) The shipment information was updated ' '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 ' '413': 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: Payload Too Large code: 413 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The request size exceeds the maximum size limit for payloads. details: hereErrorCode: 413306 description: 'Payload Too Large The request size exceeds the maximum size limit for payloads. ' tags: - Shipments operationId: patchShipmentsV4ByShipmentId x-operation-id-source: derived delete: summary: Deletes a shipment description: 'Deletes a shipment identified by the `shipmentId`. All the data related to the shipment (such as events, associations) will be removed.' security: - UserToken: [] - ClientToken: [] responses: '204': description: 'Successful (no content). The shipment was successfully deleted. ' '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 ' tags: - Shipments operationId: deleteShipmentsV4ByShipmentId x-operation-id-source: derived /shipments/v4/{shipmentId}/{segmentId}: parameters: - name: shipmentId schema: description: Shipment ID type: string pattern: ^SHP-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ in: path required: true - name: segmentId schema: 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}$ in: path required: true get: summary: Gets a segment details description: Gets details of a segment identified by the `segmentId`. security: - UserToken: [] - ClientToken: [] responses: '200': description: 'Success. The segment information was returned ' content: application/json: schema: description: Segment details type: object properties: 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}$ name: description: Name of the segment type: string maxLength: 50 description: description: Description of the segment type: string maxLength: 1000 status: description: Status of the segment type: string enum: - pending - ongoing - completed - cancelled transportMode: description: Transport mode of the segment type: string enum: - car - truck - sea - air - barge - rail - railTruck - truckRail - bargeTruck - truckBarge - undefined extSegmentId: description: Unique identifier for identifying the segment in external systems type: string maxLength: 50 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. origin: description: Origin location of this segment 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}$ destination: description: Destination location of this segment 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}$ startedAt: type: string format: date-time description: Timestamp indicating when this segment started endedAt: type: string format: date-time description: Timestamp indicating when this segment ended createdAt: type: string format: date-time description: Timestamp indicating when this segment created providedEtd: type: string format: date-time description: User provided ETD for the segment providedEta: type: string format: date-time description: User provided ETA for the segment calculatedEtd: type: string format: date-time description: Calculated ETD for the segment calculatedEta: type: string format: date-time description: Calculated ETA for the segment etaCalculatedAt: type: string format: date-time description: Timestamp indicating when ETA was calculated metadata: type: object description: 'Metadata JSON object ' example: priority: high additionalProperties: false example: segmentId: SEG-156986fa-1ed9-42ab-a022-9ac1a70ae137 name: Truck transport description: From factory to port status: pending transportMode: truck trackingId: HERE-540bb24b-0d57-4f8c-aeaf-6c91cd0aff8d origin: LOC-54531862-f87a-4b70-99a4-0e8224a56be4 destination: LOC-7b6b15cc-2307-4875-9f66-99deb5227e92 startedAt: '2020-05-27T11:40:01Z' endedAt: '2020-05-27T11:40:01Z' '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 ' tags: - Shipments operationId: getShipmentsV4ByShipmentIdBySegmentId x-operation-id-source: derived patch: summary: Updates a segment details description: 'Updates details of a segment identified by the `segmentId`. This is a partial update, meaning that only the provided fields will be updated. Changing the status of a segment affects the statuses of other segments in the shipment. The following status changes are allowed: * `pending` → `ongoing` * changes previous `pending` segments to `cancelled` * changes previous `ongoing` segment to `completed` (only for the immediate predecessor of this segment) * changes previous `ongoing` segment to `cancelled` (for segments that are not immediate predecessors of this segment) * previous segments in `cancelled` or `completed` states are not affected * `pending` || `ongoing` → `cancelled` * no changes for other segments * `ongoing` → `completed` * next segment with status `pending` is changed to `ongoing` ***Note***: `trackingId` can be updated through this API call only if the segment is in `pending` state.' security: - UserToken: [] - ClientToken: [] requestBody: content: application/json: schema: description: A segment of a shipment. type: object properties: name: description: Name of the segment type: string maxLength: 50 description: description: Description of the segment type: string maxLength: 1000 transportMode: description: Transport mode of the segment type: string enum: - car - truck - sea - air - barge - rail - railTruck - truckRail - bargeTruck - truckBarge - undefined status: description: Status of the segment type: string enum: - pending - ongoing - completed - cancelled extSegmentId: description: Unique identifier for identifying the segment in external systems type: string maxLength: 50 trackingId: description: ID of the tracking device that produces data for the segment type: string minLength: 1 maxLength: 50 providedEtd: type: string format: date-time description: ETD for the segment providedEta: type: string format: date-time description: ETA for the segment metadata: type: object description: 'Metadata JSON object ' example: priority: high additionalProperties: false example: name: Truck transport description: From factory to port transportMode: truck trackingId: HERE-540bb24b-0d57-4f8c-aeaf-6c91cd0aff8d responses: '204': description: 'Successful (no content) The segment information was updated ' '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 ' '413': 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: Payload Too Large code: 413 id: 5771b3d4-95ae-4959-ac63-fbaa3d5d06ee-lds2 message: The request size exceeds the maximum size limit for payloads. details: hereErrorCode: 413306 description: 'Payload Too Large The request size exceeds the maximum size limit for payloads. ' tags: - Shipments operationId: patchShipmentsV4ByShipmentIdBySegmentId x-operation-id-source: derived /shipments/v4/{trackingId}/segments: 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 get: summary: Gets segments assigned to a device description: Gets all segments that are assigned to the device with `trackingId` or `shipmentId`. parameters: - name: pageToken description: A token from the previously returned response to retrieve the specified page. schema: type: string in: query required: false - name: limit description: The number of items to return per page schema: type: integer minimum: 1 maximum: 100 default: 100 in: query required: false - name: status description: Filter the results by segment status schema: type: string enum: - pending - ongoing - completed - cancelled in: query required: false security: - UserToken: [] - ClientToken: [] - DeviceToken: [] responses: '200': description: 'Success. The segment information was returned ' content: application/json: schema: type: object properties: limit: description: Maximum number of items as specified in request type: integer minimum: 1 maximum: 100 count: description: Number of items returned in the response type: integer minimum: 0 maximum: 100 nextPageToken: description: Token to fetch the next page (if exists) type: string items: type: array items: description: Segment details with shipmentId type: object properties: shipmentId: description: Shipment ID type: string pattern: ^SHP-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ extOrderId: description: Unique identifier for identifying the shipment 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}$ name: description: Name of the segment type: string maxLength: 50 description: description: Description of the segment type: string maxLength: 1000 status: description: Status of the segment type: string enum: - pending - ongoing - completed - cancelled transportMode: description: Transport mode of the segment type: string enum: - car - truck - sea - air - barge - rail - railTruck - truckRail - bargeTruck - truckBarge - undefined extSegmentId: description: Unique identifier for identifying the segment in external systems type: string maxLength: 50 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. origin: description: Origin location of this segment 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}$ destination: description: Destination location of this segment 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}$ startedAt: type: string format: date-time description: Timestamp indicating when this segment started endedAt: type: string format: date-time description: Timestamp indicating when this segment ended createdAt: type: string format: date-time description: Timestamp indicating when this segment created providedEtd: type: string format: date-time description: User provided ETD for the segment providedEta: type: string format: date-time description: User provided ETA for the segment calculatedEtd: type: string format: date-time description: Calculated ETD for the segment calculatedEta: type: string format: date-time description: Calculated ETA for the segment etaCalculatedAt: type: string format: date-time description: Timestamp indicating when ETA was calculated metadata: type: object description: 'Metadata JSON object ' example: priority: high '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 ' tags: - Shipments operationId: getShipmentsV4ByTrackingIdSegments 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