GetDevicePositionHistoryCommand

Suggest an Edit

Retrieves the device position history from a tracker resource within a specified range of time.

Device positions are deleted after 30 days.

Example Syntax

Use a bare-bones client and the command you need to make an API call.

import { LocationClient, GetDevicePositionHistoryCommand } from "@aws-sdk/client-location"; // ES Modules import
// const { LocationClient, GetDevicePositionHistoryCommand } = require("@aws-sdk/client-location"); // CommonJS import
const client = new LocationClient(config);
const input = { // GetDevicePositionHistoryRequest
  TrackerName: "STRING_VALUE", // required
  DeviceId: "STRING_VALUE", // required
  NextToken: "STRING_VALUE",
  StartTimeInclusive: new Date("TIMESTAMP"),
  EndTimeExclusive: new Date("TIMESTAMP"),
  MaxResults: Number("int"),
};
const command = new GetDevicePositionHistoryCommand(input);
const response = await client.send(command);
// { // GetDevicePositionHistoryResponse
//   DevicePositions: [ // DevicePositionList // required
//     { // DevicePosition
//       DeviceId: "STRING_VALUE",
//       SampleTime: new Date("TIMESTAMP"), // required
//       ReceivedTime: new Date("TIMESTAMP"), // required
//       Position: [ // Position // required
//         Number("double"),
//       ],
//       Accuracy: { // PositionalAccuracy
//         Horizontal: Number("double"), // required
//       },
//       PositionProperties: { // PositionPropertyMap
//         "<keys>": "STRING_VALUE",
//       },
//     },
//   ],
//   NextToken: "STRING_VALUE",
// };

GetDevicePositionHistoryCommand Input

See GetDevicePositionHistoryCommandInput for more details

Parameter
Type
Description
DeviceId
Required
string | undefined

The device whose position history you want to retrieve.

TrackerName
Required
string | undefined

The tracker resource receiving the request for the device position history.

EndTimeExclusive
Date | undefined

Specify the end time for the position history in ISO 8601  format: YYYY-MM-DDThh:mm:ss.sssZ. By default, the value will be the time that the request is made.

Requirement:

  • The time specified for EndTimeExclusive must be after the time for StartTimeInclusive.

MaxResults
number | undefined

An optional limit for the number of device positions returned in a single call.

Default value: 100

NextToken
string | undefined

The pagination token specifying which page of results to return in the response. If no token is provided, the default page is the first page.

Default value: null

StartTimeInclusive
Date | undefined

Specify the start time for the position history in ISO 8601  format: YYYY-MM-DDThh:mm:ss.sssZ. By default, the value will be 24 hours prior to the time that the request is made.

Requirement:

  • The time specified for StartTimeInclusive must be before EndTimeExclusive.

GetDevicePositionHistoryCommand Output

See GetDevicePositionHistoryCommandOutput for details

Parameter
Type
Description
$metadata
Required
ResponseMetadata
Metadata pertaining to this request.
DevicePositions
Required
DevicePosition[] | undefined

Contains the position history details for the requested device.

NextToken
string | undefined

A pagination token indicating there are additional pages available. You can use the token in a following request to fetch the next set of results.

Throws

Name
Fault
Details
AccessDeniedException
client

The request was denied because of insufficient access or permissions. Check with an administrator to verify your permissions.

InternalServerException
server

The request has failed to process because of an unknown server error, exception, or failure.

ResourceNotFoundException
client

The resource that you've entered was not found in your AWS account.

ThrottlingException
client

The request was denied because of request throttling.

ValidationException
client

The input failed to meet the constraints specified by the AWS service.

LocationServiceException
Base exception class for all service exceptions from Location service.