openapi: 3.2.0 info: version: 2.6.11 title: HERE Tracking Locations 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 Locations service creates and manages locations. Locations are geographical points of interest users may store in HERE Tracking. Locations are used as building blocks for shipments.' name: Locations paths: /locations/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: - Locations operationId: getLocationsV4Health x-operation-id-source: derived /locations/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: - Locations operationId: getLocationsV4Version x-operation-id-source: derived /locations/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 location description: 'Creates a new location. A location consists of latitude/longitude coordinate pair and/or geofenceId. A name, description, and address of the location may be provided.' security: - UserToken: [] - ClientToken: [] requestBody: content: application/json: schema: type: object description: Body for creating a location. properties: name: description: Name of the location. type: string maxLength: 50 description: description: Description of the location. type: string maxLength: 1000 location: description: 'Location coordinates. If optional `geofenceId` is given, the coordinates from the geofence will be used and location coordinates are ignored. ' type: object properties: lat: description: Latitude in WGS-84 format, decimal representation ranging from -90 to 90. type: number minimum: -90 maximum: 90 lng: description: Longitude in WGS-84 format, decimal representation ranging from -180 to 180. type: number minimum: -180 maximum: 180 required: - lat - lng address: description: Location address. type: object properties: street: description: Street address type: string maxLength: 100 city: description: City type: string maxLength: 100 postalCode: description: Postal code type: string maxLength: 10 state: description: State type: string maxLength: 100 country: description: Country type: string maxLength: 100 geofenceId: description: Optional geofence ID associated with the location. A geofence with the specified ID must exist. type: string format: uuid externalLocationId: description: External location ID in external cloud type: string minLength: 1 maxLength: 100 metadata: description: 'Metadata JSON object may contain additional customer specific information ' type: object enableEta: description: 'Controls ETA calculation behavior for this location. - always: ETA calculation enabled for both origin and destination - never: ETA calculation disabled for both origin and destination - origin: ETA calculation enabled only when used as segment origin - destination: ETA calculation enabled only when used as segment destination Useful for locations where arrival/departure time is unpredictable. ' type: string enum: - always - never - origin - destination default: always additionalProperties: false anyOf: - required: - location - required: - geofenceId example: name: Rostock Port description: Rostock Port Hafenbecken C location: lat: 54.155147 lng: 12.12204 geofenceId: 57713e50-194e-4803-8ca6-1e794e916094 responses: '201': description: 'Created. The location has been successfully created. ' content: application/json: schema: type: object properties: locationId: description: Location ID type: string pattern: ^LOC-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ required: - locationId '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: - Locations operationId: postLocationsV4 x-operation-id-source: derived get: summary: Gets all locations description: Gets all locations of the project. parameters: - 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: pageToken description: A token from the previously returned response to retrieve the specified page. schema: type: string in: query required: false - name: geofenceId description: Filter the results by `geofenceId` schema: description: Geofence ID type: string format: uuid in: query required: false - name: name description: 'Filter locations 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: '*office*' - name: street description: 'Filter locations by street address. 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: '*street*' - name: city description: 'Filter locations by city. 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: '*city*' - name: postalCode description: 'Filter locations by postal code. 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: '*100*' - name: state description: 'Filter locations by state. 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: New* - name: country description: 'Filter locations by country. 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: '*land*' - name: locationId description: 'Filter locations by locationId. 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: LOC-* - name: externalLocationId description: 'Filter locations by external location id. 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. ' in: query schema: description: External location ID in external cloud type: string minLength: 1 maxLength: 100 - name: enableEta description: Filter locations by enableEta value schema: type: string enum: - always - never - origin - destination in: query required: false example: never - name: sort description: 'A paramater to specify field to sort by and order. The following format can be used: ''name:asc'' sort by name in ascending order, ''steet:desc'' sort by street in descending order. Allowed fields to sort by: locationId, name, street, city, postalCode, state, country. ' schema: oneOf: - type: string pattern: ^(locationId|name|street|city|postalCode|state|country):(asc|desc)$ - type: array items: type: string pattern: ^(locationId|name|street|city|postalCode|state|country):(asc|desc)$ in: query required: false example: name:asc security: - UserToken: [] - ClientToken: [] responses: '200': description: 'Response body contains an array of location objects, count indicating the number of returned items, limit indicating the requested maximum amount of records to be returned and pageToken for the next page 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: type: object description: Location object body. properties: locationId: description: Location ID type: string pattern: ^LOC-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ externalLocationId: description: External location ID in external cloud type: string minLength: 1 maxLength: 100 name: description: Name of the location. type: string maxLength: 50 description: description: Description of the location. type: string maxLength: 1000 location: description: Location coordinates. type: object properties: lat: description: Latitude in WGS-84 format, decimal representation ranging from -90 to 90. type: number minimum: -90 maximum: 90 lng: description: Longitude in WGS-84 format, decimal representation ranging from -180 to 180. type: number minimum: -180 maximum: 180 required: - lat - lng address: description: Location address. type: object properties: street: description: Street address type: string maxLength: 100 city: description: City type: string maxLength: 100 postalCode: description: Postal code type: string maxLength: 10 state: description: State type: string maxLength: 100 country: description: Country type: string maxLength: 100 geofenceId: description: Geofence ID type: string format: uuid version: description: Location version type: integer createdAt: description: Timestamp indicating when this location has been created type: string format: date-time updatedAt: description: Timestamp indicating when this location has been updated type: string format: date-time metadata: description: 'Metadata JSON object may contain additional customer specific information ' type: object enableEta: description: 'Controls ETA calculation behavior for this location. - always: ETA calculation enabled for both origin and destination - never: ETA calculation disabled for both origin and destination - origin: ETA calculation enabled only when used as segment origin - destination: ETA calculation enabled only when used as segment destination Useful for locations where arrival/departure time is unpredictable. ' type: string enum: - always - never - origin - destination default: always required: - locationId additionalProperties: false example: locationId: LOC-61a3fba0-cb44-405f-816c-c2aec73a1add name: Rostock Port description: Rostock Port Hafenbecken C location: lat: 54.155147 lng: 12.12204 geofenceId: 57713e50-194e-4803-8ca6-1e794e916094 total: type: integer description: Total number of locations for query required: - limit - count - items additionalProperties: 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 ' tags: - Locations operationId: getLocationsV4 x-operation-id-source: derived delete: summary: Deletes all locations description: 'Deletes all locations 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.' 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: '204': description: 'Successful (no content). All locations 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: - Locations operationId: deleteLocationsV4 x-operation-id-source: derived /locations/v4/{locationId}: parameters: - name: locationId description: Location ID schema: 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}$ in: path required: true get: summary: Gets a location details description: Gets details of the location `locationId`. security: - UserToken: [] - ClientToken: [] responses: '200': description: 'Success. The location information was returned ' content: application/json: schema: type: object description: Location object body. properties: locationId: description: Location ID type: string pattern: ^LOC-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ externalLocationId: description: External location ID in external cloud type: string minLength: 1 maxLength: 100 name: description: Name of the location. type: string maxLength: 50 description: description: Description of the location. type: string maxLength: 1000 location: description: Location coordinates. type: object properties: lat: description: Latitude in WGS-84 format, decimal representation ranging from -90 to 90. type: number minimum: -90 maximum: 90 lng: description: Longitude in WGS-84 format, decimal representation ranging from -180 to 180. type: number minimum: -180 maximum: 180 required: - lat - lng address: description: Location address. type: object properties: street: description: Street address type: string maxLength: 100 city: description: City type: string maxLength: 100 postalCode: description: Postal code type: string maxLength: 10 state: description: State type: string maxLength: 100 country: description: Country type: string maxLength: 100 geofenceId: description: Geofence ID type: string format: uuid version: description: Location version type: integer createdAt: description: Timestamp indicating when this location has been created type: string format: date-time updatedAt: description: Timestamp indicating when this location has been updated type: string format: date-time metadata: description: 'Metadata JSON object may contain additional customer specific information ' type: object enableEta: description: 'Controls ETA calculation behavior for this location. - always: ETA calculation enabled for both origin and destination - never: ETA calculation disabled for both origin and destination - origin: ETA calculation enabled only when used as segment origin - destination: ETA calculation enabled only when used as segment destination Useful for locations where arrival/departure time is unpredictable. ' type: string enum: - always - never - origin - destination default: always required: - locationId additionalProperties: false example: locationId: LOC-61a3fba0-cb44-405f-816c-c2aec73a1add name: Rostock Port description: Rostock Port Hafenbecken C location: lat: 54.155147 lng: 12.12204 geofenceId: 57713e50-194e-4803-8ca6-1e794e916094 '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: - Locations operationId: getLocationsV4ByLocationId x-operation-id-source: derived put: summary: Updates a location details description: 'Updates the location `locationId` details. A location consists of latitude/longitude coordinate pair and/or geofenceId. A name, description, and address of the location may be provided. The old location definition will be replaced, meaning that full location body should be provided. After a successful update, the response provides the updated location details.' security: - UserToken: [] - ClientToken: [] requestBody: content: application/json: schema: type: object description: Body for creating a location. properties: name: description: Name of the location. type: string maxLength: 50 description: description: Description of the location. type: string maxLength: 1000 location: description: 'Location coordinates. If optional `geofenceId` is given, the coordinates from the geofence will be used and location coordinates are ignored. ' type: object properties: lat: description: Latitude in WGS-84 format, decimal representation ranging from -90 to 90. type: number minimum: -90 maximum: 90 lng: description: Longitude in WGS-84 format, decimal representation ranging from -180 to 180. type: number minimum: -180 maximum: 180 required: - lat - lng address: description: Location address. type: object properties: street: description: Street address type: string maxLength: 100 city: description: City type: string maxLength: 100 postalCode: description: Postal code type: string maxLength: 10 state: description: State type: string maxLength: 100 country: description: Country type: string maxLength: 100 geofenceId: description: Optional geofence ID associated with the location. A geofence with the specified ID must exist. type: string format: uuid externalLocationId: description: External location ID in external cloud type: string minLength: 1 maxLength: 100 metadata: description: 'Metadata JSON object may contain additional customer specific information ' type: object enableEta: description: 'Controls ETA calculation behavior for this location. - always: ETA calculation enabled for both origin and destination - never: ETA calculation disabled for both origin and destination - origin: ETA calculation enabled only when used as segment origin - destination: ETA calculation enabled only when used as segment destination Useful for locations where arrival/departure time is unpredictable. ' type: string enum: - always - never - origin - destination default: always additionalProperties: false anyOf: - required: - location - required: - geofenceId example: name: Rostock Port description: Rostock Port Hafenbecken C location: lat: 54.155147 lng: 12.12204 geofenceId: 57713e50-194e-4803-8ca6-1e794e916094 responses: '200': description: 'Success. The location information was updated ' content: application/json: schema: type: object description: Location object body. properties: locationId: description: Location ID type: string pattern: ^LOC-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ externalLocationId: description: External location ID in external cloud type: string minLength: 1 maxLength: 100 name: description: Name of the location. type: string maxLength: 50 description: description: Description of the location. type: string maxLength: 1000 location: description: Location coordinates. type: object properties: lat: description: Latitude in WGS-84 format, decimal representation ranging from -90 to 90. type: number minimum: -90 maximum: 90 lng: description: Longitude in WGS-84 format, decimal representation ranging from -180 to 180. type: number minimum: -180 maximum: 180 required: - lat - lng address: description: Location address. type: object properties: street: description: Street address type: string maxLength: 100 city: description: City type: string maxLength: 100 postalCode: description: Postal code type: string maxLength: 10 state: description: State type: string maxLength: 100 country: description: Country type: string maxLength: 100 geofenceId: description: Geofence ID type: string format: uuid version: description: Location version type: integer createdAt: description: Timestamp indicating when this location has been created type: string format: date-time updatedAt: description: Timestamp indicating when this location has been updated type: string format: date-time metadata: description: 'Metadata JSON object may contain additional customer specific information ' type: object enableEta: description: 'Controls ETA calculation behavior for this location. - always: ETA calculation enabled for both origin and destination - never: ETA calculation disabled for both origin and destination - origin: ETA calculation enabled only when used as segment origin - destination: ETA calculation enabled only when used as segment destination Useful for locations where arrival/departure time is unpredictable. ' type: string enum: - always - never - origin - destination default: always required: - locationId additionalProperties: false example: locationId: LOC-61a3fba0-cb44-405f-816c-c2aec73a1add name: Rostock Port description: Rostock Port Hafenbecken C location: lat: 54.155147 lng: 12.12204 geofenceId: 57713e50-194e-4803-8ca6-1e794e916094 '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: - Locations operationId: putLocationsV4ByLocationId x-operation-id-source: derived delete: summary: Deletes a location description: 'Deletes the location `locationId`. ***NOTE***: A location can not be deleted if the location is referred by any shipment.' security: - UserToken: [] - ClientToken: [] responses: '204': description: 'Successful (no content). The location 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: - Locations operationId: deleteLocationsV4ByLocationId 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