Amazon Location Service Location Service Positions API

openapi: 3.2.0
info:
  title: Amazon Location Service Positions API
  version: '2020-11-19'
  description: Generated from AWS's published Smithy model for Amazon Location Service. 3 operation(s).
  contact:
    name: Amazon Web Services
    url: https://aws.amazon.com/contact-us/
  license:
    name: Apache 2.0
    identifier: Apache-2.0
    url: https://github.com/aws/api-models-aws/blob/main/LICENSE
servers:
- url: https://geo.{region}.amazonaws.com
  variables:
    region:
      default: us-east-1
security:
- sigv4: []
tags:
- name: Positions
paths:
  /geofencing/v0/collections/{CollectionName}/positions:
    post:
      operationId: BatchEvaluateGeofences
      summary: Batch Evaluate Geofences
      description: 'Evaluates device positions against the geofence geometries from a given geofence collection. This operation always returns an empty response because geofences are asynchronously evaluated. The evaluation determines if the device has entered or exited a geofenced area, and then publishes one of the following events to Amazon EventBridge: ENTER if Amazon Location determines that the tracked device has entered a geofenced area. EXIT if Amazon Location determines that the tracked device has exited a geofenced area. The last geofence that a device was observed within is tracked for 30 days after the most recent device position update. Geofence evaluation uses the given device position. It does not account for the optional Accuracy of a DevicePositionUpdate. The DeviceID is used as a string to represent the device. You do not need to have a Tracker associated with the DeviceID.'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchEvaluateGeofencesResponse'
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '500':
          description: InternalServerException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '429':
          description: ThrottlingException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThrottlingException'
        '400':
          description: ValidationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchEvaluateGeofencesRequest'
      tags:
      - Positions
  /tracking/v0/trackers/{TrackerName}/devices/{DeviceId}/positions/latest:
    get:
      operationId: GetDevicePosition
      summary: Get Device Position
      description: Retrieves a device's most recent position according to its sample time. Device positions are deleted after 30 days.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetDevicePositionResponse'
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '500':
          description: InternalServerException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '429':
          description: ThrottlingException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThrottlingException'
        '400':
          description: ValidationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetDevicePositionRequest'
      tags:
      - Positions
  /tracking/v0/trackers/{TrackerName}/positions/verify:
    post:
      operationId: VerifyDevicePosition
      summary: Verify Device Position
      description: Verifies the integrity of the device's position by determining if it was reported behind a proxy, and by comparing it to an inferred position estimated based on the device's state. The Location Integrity SDK provides enhanced features related to device verification, and it is available for use by request. To get access to the SDK, contact Sales Support.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyDevicePositionResponse'
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '500':
          description: InternalServerException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '429':
          description: ThrottlingException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThrottlingException'
        '400':
          description: ValidationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyDevicePositionRequest'
      tags:
      - Positions
components:
  schemas:
    LteNetworkMeasurements:
      type: object
      properties:
        Earfcn:
          type: integer
          description: E-UTRA (Evolved Universal Terrestrial Radio Access) absolute radio frequency channel number (EARFCN).
        CellId:
          type: integer
          description: E-UTRAN Cell Identifier (ECI).
        Pci:
          type: integer
          description: Physical Cell ID (PCI).
        Rsrp:
          type: integer
          description: Signal power of the reference signal received, measured in dBm (decibel-milliwatts).
        Rsrq:
          type: number
          description: Signal quality of the reference Signal received, measured in decibels (dB).
      required:
      - Earfcn
      - CellId
      - Pci
    BatchEvaluateGeofencesError:
      type: object
      properties:
        DeviceId:
          type: string
          description: The device associated with the position evaluation error.
        SampleTime:
          type: string
          format: date-time
          description: 'Specifies a timestamp for when the error occurred in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sssZ'
        Error:
          $ref: '#/components/schemas/BatchItemError'
      required:
      - DeviceId
      - SampleTime
      - Error
    LteLocalId:
      type: object
      properties:
        Earfcn:
          type: integer
          description: E-UTRA (Evolved Universal Terrestrial Radio Access) absolute radio frequency channel number (EARFCN).
        Pci:
          type: integer
          description: Physical Cell ID (PCI).
      required:
      - Earfcn
      - Pci
    BatchItemError:
      type: object
      properties:
        Code:
          type: string
          description: The error code associated with the batch request error.
        Message:
          type: string
          description: A message with the reason for the batch request error.
    VerifyDevicePositionRequest:
      type: object
      properties:
        TrackerName:
          type: string
          description: The name of the tracker resource to be associated with verification request.
        DeviceState:
          $ref: '#/components/schemas/DeviceState'
        DistanceUnit:
          type: string
          description: 'The distance unit for the verification request. Default Value: Kilometers'
      required:
      - TrackerName
      - DeviceState
    ResourceNotFoundException:
      type: object
      properties:
        Message:
          type: string
      required:
      - Message
    LteCellDetails:
      type: object
      properties:
        CellId:
          type: integer
          description: The E-UTRAN Cell Identifier (ECI).
        Mcc:
          type: integer
          description: The Mobile Country Code (MCC).
        Mnc:
          type: integer
          description: The Mobile Network Code (MNC)
        LocalId:
          $ref: '#/components/schemas/LteLocalId'
        NetworkMeasurements:
          type: array
          items:
            $ref: '#/components/schemas/LteNetworkMeasurements'
          description: The network measurements.
        TimingAdvance:
          type: integer
          description: Timing Advance (TA).
        NrCapable:
          type: boolean
          description: Indicates whether the LTE object is capable of supporting NR (new radio).
        Rsrp:
          type: integer
          description: Signal power of the reference signal received, measured in decibel-milliwatts (dBm).
        Rsrq:
          type: number
          description: Signal quality of the reference Signal received, measured in decibels (dB).
        Tac:
          type: integer
          description: LTE Tracking Area Code (TAC).
      required:
      - CellId
      - Mcc
      - Mnc
    ValidationExceptionField:
      type: object
      properties:
        Name:
          type: string
          description: The field name where the invalid entry was detected.
        Message:
          type: string
          description: A message with the reason for the validation exception error.
      required:
      - Name
      - Message
    ThrottlingException:
      type: object
      properties:
        Message:
          type: string
      required:
      - Message
    PositionalAccuracy:
      type: object
      properties:
        Horizontal:
          type: number
          description: Estimated maximum distance, in meters, between the measured position and the true position of a device, along the Earth's surface.
      required:
      - Horizontal
    GetDevicePositionRequest:
      type: object
      properties:
        TrackerName:
          type: string
          description: The tracker resource receiving the position update.
        DeviceId:
          type: string
          description: The device whose position you want to retrieve.
      required:
      - TrackerName
      - DeviceId
    VerifyDevicePositionResponse:
      type: object
      properties:
        InferredState:
          $ref: '#/components/schemas/InferredState'
        DeviceId:
          type: string
          description: The device identifier.
        SampleTime:
          type: string
          format: date-time
          description: 'The timestamp at which the device''s position was determined. Uses ISO 8601 format: YYYY-MM-DDThh:mm:ss.sssZ.'
        ReceivedTime:
          type: string
          format: date-time
          description: 'The timestamp for when the tracker resource received the device position in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sssZ.'
        DistanceUnit:
          type: string
          description: The distance unit for the verification response.
      required:
      - InferredState
      - DeviceId
      - SampleTime
      - ReceivedTime
      - DistanceUnit
    DeviceState:
      type: object
      properties:
        DeviceId:
          type: string
          description: The device identifier.
        SampleTime:
          type: string
          format: date-time
          description: 'The timestamp at which the device''s position was determined. Uses ISO 8601 format: YYYY-MM-DDThh:mm:ss.sssZ.'
        Position:
          type: array
          items:
            type: number
          description: The last known device position.
        Accuracy:
          $ref: '#/components/schemas/PositionalAccuracy'
        Ipv4Address:
          type: string
          description: The device's Ipv4 address.
        WiFiAccessPoints:
          type: array
          items:
            $ref: '#/components/schemas/WiFiAccessPoint'
          description: The Wi-Fi access points the device is using.
        CellSignals:
          $ref: '#/components/schemas/CellSignals'
      required:
      - DeviceId
      - SampleTime
      - Position
    GetDevicePositionResponse:
      type: object
      properties:
        DeviceId:
          type: string
          description: The device whose position you retrieved.
        SampleTime:
          type: string
          format: date-time
          description: 'The timestamp at which the device''s position was determined. Uses ISO 8601 format: YYYY-MM-DDThh:mm:ss.sssZ.'
        ReceivedTime:
          type: string
          format: date-time
          description: 'The timestamp for when the tracker resource received the device position. Uses ISO 8601 format: YYYY-MM-DDThh:mm:ss.sssZ.'
        Position:
          type: array
          items:
            type: number
          description: The last known device position.
        Accuracy:
          $ref: '#/components/schemas/PositionalAccuracy'
        PositionProperties:
          type: object
          additionalProperties:
            type: string
          description: The properties associated with the position.
      required:
      - SampleTime
      - ReceivedTime
      - Position
    InferredState:
      type: object
      properties:
        Position:
          type: array
          items:
            type: number
          description: The device position inferred by the provided position, IP address, cellular signals, and Wi-Fi- access points.
        Accuracy:
          $ref: '#/components/schemas/PositionalAccuracy'
        DeviationDistance:
          type: number
          description: The distance between the inferred position and the device's self-reported position.
        ProxyDetected:
          type: boolean
          description: Indicates if a proxy was used.
      required:
      - ProxyDetected
    InternalServerException:
      type: object
      properties:
        Message:
          type: string
      required:
      - Message
    AccessDeniedException:
      type: object
      properties:
        Message:
          type: string
      required:
      - Message
    ValidationException:
      type: object
      properties:
        Message:
          type: string
        Reason:
          type: string
          description: A message with the reason for the validation exception error.
        FieldList:
          type: array
          items:
            $ref: '#/components/schemas/ValidationExceptionField'
          description: The field where the invalid entry was detected.
      required:
      - Message
      - Reason
      - FieldList
    BatchEvaluateGeofencesResponse:
      type: object
      properties:
        Errors:
          type: array
          items:
            $ref: '#/components/schemas/BatchEvaluateGeofencesError'
          description: Contains error details for each device that failed to evaluate its position against the given geofence collection.
      required:
      - Errors
    DevicePositionUpdate:
      type: object
      properties:
        DeviceId:
          type: string
          description: The device associated to the position update.
        SampleTime:
          type: string
          format: date-time
          description: 'The timestamp at which the device''s position was determined. Uses ISO 8601 format: YYYY-MM-DDThh:mm:ss.sssZ'
        Position:
          type: array
          items:
            type: number
          description: 'The latest device position defined in WGS 84 format: [X or longitude, Y or latitude].'
        Accuracy:
          $ref: '#/components/schemas/PositionalAccuracy'
        PositionProperties:
          type: object
          additionalProperties:
            type: string
          description: 'Associates one of more properties with the position update. A property is a key-value pair stored with the position update and added to any geofence event the update may trigger. Format: "key" : "value"'
      required:
      - DeviceId
      - SampleTime
      - Position
    CellSignals:
      type: object
      properties:
        LteCellDetails:
          type: array
          items:
            $ref: '#/components/schemas/LteCellDetails'
          description: Information about the Long-Term Evolution (LTE) network the device is connected to.
      required:
      - LteCellDetails
    BatchEvaluateGeofencesRequest:
      type: object
      properties:
        CollectionName:
          type: string
          description: The geofence collection used in evaluating the position of devices against its geofences.
        DevicePositionUpdates:
          type: array
          items:
            $ref: '#/components/schemas/DevicePositionUpdate'
          description: Contains device details for each device to be evaluated against the given geofence collection.
      required:
      - CollectionName
      - DevicePositionUpdates
    WiFiAccessPoint:
      type: object
      properties:
        MacAddress:
          type: string
          description: Medium access control address (Mac).
        Rss:
          type: integer
          description: Received signal strength (dBm) of the WLAN measurement data.
      required:
      - MacAddress
      - Rss
  securitySchemes:
    sigv4:
      type: apiKey
      in: header
      name: Authorization
      description: AWS Signature Version 4. The Authorization header carries an AWS4-HMAC-SHA256 signature over the canonical request, with X-Amz-Date (and X-Amz-Security-Token for temporary credentials). Not a bearer token.
      x-aws-sigv4:
        signingName: geo
x-provenance:
  method: harvested
  publisher: Amazon Web Services
  source: https://raw.githubusercontent.com/aws/api-models-aws/582e55931c45b944739742a2c1620b6026dd2d13/models/location/service/2020-11-19/location-2020-11-19.json
  note: converted by smithy-to-openapi.py from AWS's Smithy model (roadmap#1001)