Amazon Location Service Location Service Places API

openapi: 3.2.0
info:
  title: Amazon Location Service Places API
  version: '2020-11-19'
  description: Generated from AWS's published Smithy model for Amazon Location Service. 6 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: Places
paths:
  /places/v0/indexes/{IndexName}/places/{PlaceId}:
    get:
      operationId: GetPlace
      summary: Get Place
      description: This operation is no longer current and may be deprecated in the future. We recommend you upgrade to the V2 GetPlace operation unless you require Grab data. This version of GetPlace is part of a previous Amazon Location Service Places API (version 1) which has been superseded by a more intuitive, powerful, and complete API (version 2). Version 2 of the GetPlace operation interoperates with the rest of the Places V2 API, while this version does not. If you are using an Amazon Web Services SDK or the Amazon Web Services CLI, note that the Places API version 2 is found under geo-places or geo_places, not under location. Since Grab is not yet fully supported in Places API version 2, we recommend you continue using API version 1 when using Grab. Start your version 2 API journey with the Places V2 API Reference or the Developer Guide. Finds a place by its unique ID. A PlaceId is returned by other search operations. A PlaceId is valid only if all of the following are the same in the original search request and the call to GetPlace. Customer Amazon Web Services account Amazon Web Services Region Data provider specified in the place index resource If your Place index resource is configured
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetPlaceResponse'
        '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/GetPlaceRequest'
      tags:
      - Places
  /places/v0/indexes:
    post:
      operationId: CreatePlaceIndex
      summary: Create Place Index
      description: This operation is no longer current and may be deprecated in the future. We recommend you upgrade to the Places API V2 unless you require Grab data. CreatePlaceIndex is part of a previous Amazon Location Service Places API (version 1) which has been superseded by a more intuitive, powerful, and complete API (version 2). The Places API version 2 has a simplified interface that can be used without creating or managing place index resources. If you are using an Amazon Web Services SDK or the Amazon Web Services CLI, note that the Places API version 2 is found under geo-places or geo_places, not under location. Since Grab is not yet fully supported in Places API version 2, we recommend you continue using API version 1 when using Grab. Start your version 2 API journey with the Places V2 API Reference or the Developer Guide. Creates a place index resource in your Amazon Web Services account. Use a place index resource to geocode addresses and other text queries by using the SearchPlaceIndexForText operation, and reverse geocode coordinates by using the SearchPlaceIndexForPosition operation, and enable autosuggestions by using the SearchPlaceIndexForSuggestions operation. If your applicat
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatePlaceIndexResponse'
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '409':
          description: ConflictException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictException'
        '500':
          description: InternalServerException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '402':
          description: ServiceQuotaExceededException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceQuotaExceededException'
        '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/CreatePlaceIndexRequest'
      tags:
      - Places
  /places/v0/indexes/{IndexName}:
    get:
      operationId: DescribePlaceIndex
      summary: Describe Place Index
      description: This operation is no longer current and may be deprecated in the future. We recommend you upgrade to the Places API V2 unless you require Grab data. DescribePlaceIndex is part of a previous Amazon Location Service Places API (version 1) which has been superseded by a more intuitive, powerful, and complete API (version 2). The Places API version 2 has a simplified interface that can be used without creating or managing place index resources. If you are using an Amazon Web Services SDK or the Amazon Web Services CLI, note that the Places API version 2 is found under geo-places or geo_places, not under location. Since Grab is not yet fully supported in Places API version 2, we recommend you continue using API version 1 when using Grab. Start your version 2 API journey with the Places V2 API Reference or the Developer Guide. Retrieves the place index resource details.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DescribePlaceIndexResponse'
        '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/DescribePlaceIndexRequest'
      tags:
      - Places
    patch:
      operationId: UpdatePlaceIndex
      summary: Update Place Index
      description: This operation is no longer current and may be deprecated in the future. We recommend you upgrade to the Places API V2 unless you require Grab data. UpdatePlaceIndex is part of a previous Amazon Location Service Places API (version 1) which has been superseded by a more intuitive, powerful, and complete API (version 2). The Places API version 2 has a simplified interface that can be used without creating or managing place index resources. If you are using an Amazon Web Services SDK or the Amazon Web Services CLI, note that the Places API version 2 is found under geo-places or geo_places, not under location. Since Grab is not yet fully supported in Places API version 2, we recommend you continue using API version 1 when using Grab. Start your version 2 API journey with the Places V2 API Reference or the Developer Guide. Updates the specified properties of a given place index resource.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdatePlaceIndexResponse'
        '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/UpdatePlaceIndexRequest'
      tags:
      - Places
    delete:
      operationId: DeletePlaceIndex
      summary: Delete Place Index
      description: This operation is no longer current and may be deprecated in the future. We recommend you upgrade to the Places API V2 unless you require Grab data. DeletePlaceIndex is part of a previous Amazon Location Service Places API (version 1) which has been superseded by a more intuitive, powerful, and complete API (version 2). The Places API version 2 has a simplified interface that can be used without creating or managing place index resources. If you are using an Amazon Web Services SDK or the Amazon Web Services CLI, note that the Places API version 2 is found under geo-places or geo_places, not under location. Since Grab is not yet fully supported in Places API version 2, we recommend you continue using API version 1 when using Grab. Start your version 2 API journey with the Places V2 API Reference or the Developer Guide. Deletes a place index resource from your Amazon Web Services account. This operation deletes the resource permanently.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeletePlaceIndexResponse'
        '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/DeletePlaceIndexRequest'
      tags:
      - Places
  /places/v0/list-indexes:
    post:
      operationId: ListPlaceIndexes
      summary: List Place Indexes
      description: This operation is no longer current and may be deprecated in the future. We recommend you upgrade to the Places API V2 unless you require Grab data. ListPlaceIndexes is part of a previous Amazon Location Service Places API (version 1) which has been superseded by a more intuitive, powerful, and complete API (version 2). The Places API version 2 has a simplified interface that can be used without creating or managing place index resources. If you are using an Amazon Web Services SDK or the Amazon Web Services CLI, note that the Places API version 2 is found under geo-places or geo_places, not under location. Since Grab is not yet fully supported in Places API version 2, we recommend you continue using API version 1 when using Grab. Start your version 2 API journey with the Places V2 API Reference or the Developer Guide. Lists place index resources in your Amazon Web Services account.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListPlaceIndexesResponse'
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '500':
          description: InternalServerException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '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/ListPlaceIndexesRequest'
      tags:
      - Places
components:
  schemas:
    ResourceNotFoundException:
      type: object
      properties:
        Message:
          type: string
      required:
      - Message
    CreatePlaceIndexResponse:
      type: object
      properties:
        IndexName:
          type: string
          description: The name for the place index resource.
        IndexArn:
          type: string
          description: 'The Amazon Resource Name (ARN) for the place index resource. Used to specify a resource across Amazon Web Services. Format example: arn:aws:geo:region:account-id:place-index/ExamplePlaceIndex'
        CreateTime:
          type: string
          format: date-time
          description: 'The timestamp for when the place index resource was created in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sssZ.'
      required:
      - IndexName
      - IndexArn
      - CreateTime
    ListPlaceIndexesResponse:
      type: object
      properties:
        Entries:
          type: array
          items:
            $ref: '#/components/schemas/ListPlaceIndexesResponseEntry'
          description: Lists the place index resources that exist in your Amazon Web Services account
        NextToken:
          type: string
          description: A pagination token indicating that there are additional pages available. You can use the token in a new request to fetch the next page of results.
      required:
      - Entries
    ServiceQuotaExceededException:
      type: object
      properties:
        Message:
          type: string
          description: A message with the reason for the service quota exceeded exception error.
      required:
      - Message
    UpdatePlaceIndexResponse:
      type: object
      properties:
        IndexName:
          type: string
          description: The name of the updated place index resource.
        IndexArn:
          type: string
          description: 'The Amazon Resource Name (ARN) of the upated place index resource. Used to specify a resource across Amazon Web Services. Format example: arn:aws:geo:region:account-id:place- index/ExamplePlaceIndex'
        UpdateTime:
          type: string
          format: date-time
          description: 'The timestamp for when the place index resource was last updated in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sssZ.'
      required:
      - IndexName
      - IndexArn
      - UpdateTime
    DeletePlaceIndexResponse:
      type: object
      properties: {}
    TimeZone:
      type: object
      properties:
        Name:
          type: string
          description: The name of the time zone, following the IANA time zone standard. For example, America/Los_Angeles.
        Offset:
          type: integer
          description: The time zone's offset, in seconds, from UTC.
      required:
      - Name
    ListPlaceIndexesResponseEntry:
      type: object
      properties:
        IndexName:
          type: string
          description: The name of the place index resource.
        Description:
          type: string
          description: The optional description for the place index resource.
        DataSource:
          type: string
          description: 'The data provider of geospatial data. Values can be one of the following: Esri Grab Here For more information about data providers, see Amazon Location Service data providers.'
        PricingPlan:
          type: string
          description: No longer used. Always returns RequestBasedUsage.
        CreateTime:
          type: string
          format: date-time
          description: 'The timestamp for when the place index resource was created in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sssZ.'
        UpdateTime:
          type: string
          format: date-time
          description: 'The timestamp for when the place index resource was last updated in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sssZ.'
      required:
      - IndexName
      - Description
      - DataSource
      - CreateTime
      - UpdateTime
    GetPlaceRequest:
      type: object
      properties:
        IndexName:
          type: string
          description: The name of the place index resource that you want to use for the search.
        PlaceId:
          type: string
          description: The identifier of the place to find.
        Language:
          type: string
          description: The preferred language used to return results. The value must be a valid BCP 47 language tag, for example, en for English. This setting affects the languages used in the results, but not the results themselves. If no language is specified, or not supported for a particular result, the partner automatically chooses a language for the result. For an example, we'll use the Greek language. You search for a location around Athens, Greece, with the language parameter set to en. The city in the results will most likely be returned as Athens. If you set the language parameter to el, for Greek, then th
        Key:
          type: string
          description: The optional API key to authorize the request.
      required:
      - IndexName
      - PlaceId
    UpdatePlaceIndexRequest:
      type: object
      properties:
        IndexName:
          type: string
          description: The name of the place index resource to update.
        PricingPlan:
          type: string
          description: No longer used. If included, the only allowed value is RequestBasedUsage.
        Description:
          type: string
          description: Updates the description for the place index resource.
        DataSourceConfiguration:
          $ref: '#/components/schemas/DataSourceConfiguration'
      required:
      - IndexName
    DescribePlaceIndexRequest:
      type: object
      properties:
        IndexName:
          type: string
          description: The name of the place index resource.
      required:
      - IndexName
    CreatePlaceIndexRequest:
      type: object
      properties:
        IndexName:
          type: string
          description: 'The name of the place index resource. Requirements: Contain only alphanumeric characters (A–Z, a–z, 0–9), hyphens (-), periods (.), and underscores (_). Must be a unique place index resource name. No spaces allowed. For example, ExamplePlaceIndex.'
        DataSource:
          type: string
          description: 'Specifies the geospatial data provider for the new place index. This field is case-sensitive. Enter the valid values as shown. For example, entering HERE returns an error. Valid values include: Esri – For additional information about Esri''s coverage in your region of interest, see Esri details on geocoding coverage. Grab – Grab provides place index functionality for Southeast Asia. For additional information about GrabMaps'' coverage, see GrabMaps countries and areas covered. Here – For additional information about HERE Technologies'' coverage in your region of interest, see HERE details on goec'
        PricingPlan:
          type: string
          description: No longer used. If included, the only allowed value is RequestBasedUsage.
        Description:
          type: string
          description: The optional description for the place index resource.
        DataSourceConfiguration:
          $ref: '#/components/schemas/DataSourceConfiguration'
        Tags:
          type: object
          additionalProperties:
            type: string
          description: 'Applies one or more tags to the place index resource. A tag is a key-value pair that helps you manage, identify, search, and filter your resources. Format: "key" : "value" Restrictions: Maximum 50 tags per resource. Each tag key must be unique and must have exactly one associated value. Maximum key length: 128 Unicode characters in UTF-8. Maximum value length: 256 Unicode characters in UTF-8. Can use alphanumeric characters (A–Z, a–z, 0–9), and the following characters: + - = . _ : / @ Cannot use "aws:" as a prefix for a key.'
      required:
      - IndexName
      - DataSource
    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
    ConflictException:
      type: object
      properties:
        Message:
          type: string
      required:
      - Message
    ThrottlingException:
      type: object
      properties:
        Message:
          type: string
      required:
      - Message
    ListPlaceIndexesRequest:
      type: object
      properties:
        MaxResults:
          type: integer
          description: 'An optional limit for the maximum number of results returned in a single call. Default value: 100'
        NextToken:
          type: string
          description: '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'
    PlaceGeometry:
      type: object
      properties:
        Point:
          type: array
          items:
            type: number
          description: 'A single point geometry specifies a location for a Place using WGS 84 coordinates: x — Specifies the x coordinate or longitude. y — Specifies the y coordinate or latitude.'
    DataSourceConfiguration:
      type: object
      properties:
        IntendedUse:
          type: string
          description: 'Specifies how the results of an operation will be stored by the caller. Valid values include: SingleUse specifies that the results won''t be stored. Storage specifies that the result can be cached or stored in a database. Default value: SingleUse'
    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
    DeletePlaceIndexRequest:
      type: object
      properties:
        IndexName:
          type: string
          description: The name of the place index resource to be deleted.
      required:
      - IndexName
    DescribePlaceIndexResponse:
      type: object
      properties:
        IndexName:
          type: string
          description: The name of the place index resource being described.
        IndexArn:
          type: string
          description: 'The Amazon Resource Name (ARN) for the place index resource. Used to specify a resource across Amazon Web Services. Format example: arn:aws:geo:region:account-id:place-index/ExamplePlaceIndex'
        PricingPlan:
          type: string
          description: No longer used. Always returns RequestBasedUsage.
        Description:
          type: string
          description: The optional description for the place index resource.
        CreateTime:
          type: string
          format: date-time
          description: 'The timestamp for when the place index resource was created in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sssZ.'
        UpdateTime:
          type: string
          format: date-time
          description: 'The timestamp for when the place index resource was last updated in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sssZ.'
        DataSource:
          type: string
          description: 'The data provider of geospatial data. Values can be one of the following: Esri Grab Here For more information about data providers, see Amazon Location Service data providers.'
        DataSourceConfiguration:
          $ref: '#/components/schemas/DataSourceConfiguration'
        Tags:
          type: object
          additionalProperties:
            type: string
          description: Tags associated with place index resource.
      required:
      - IndexName
      - IndexArn
      - Description
      - CreateTime
      - UpdateTime
      - DataSource
      - DataSourceConfiguration
    GetPlaceResponse:
      type: object
      properties:
        Place:
          $ref: '#/components/schemas/Place'
      required:
      - Place
    Place:
      type: object
      properties:
        Label:
          type: string
          description: The full name and address of the point of interest such as a city, region, or country. For example, 123 Any Street, Any Town, USA.
        Geometry:
          $ref: '#/components/schemas/PlaceGeometry'
        AddressNumber:
          type: string
          description: The numerical portion of an address, such as a building number.
        Street:
          type: string
          description: The name for a street or a road to identify a location. For example, Main Street.
        Neighborhood:
          type: string
          description: The name of a community district. For example, Downtown.
        Municipality:
          type: string
          description: A name for a local area, such as a city or town name. For example, Toronto.
        SubRegion:
          type: string
          description: A county, or an area that's part of a larger region. For example, Metro Vancouver.
        Region:
          type: string
          description: A name for an area or geographical division, such as a province or state name. For example, British Columbia.
        Country:
          type: string
          description: A country/region specified using ISO 3166 3-digit country/region code. For example, CAN.
        PostalCode:
          type: string
          description: A group of numbers and letters in a country-specific format, which accompanies the address for the purpose of identifying a location.
        Interpolated:
          type: boolean
          description: True if the result is interpolated from other known places. False if the Place is a known place. Not returned when the partner does not provide the information. For example, returns False for an address location that is found in the partner data, but returns True if an address does not exist in the partner data and its location is calculated by interpolating between other known addresses.
        TimeZone:
          $ref: '#/components/schemas/TimeZone'
        UnitType:
          type: string
          description: For addresses with a UnitNumber, the type of unit. For example, Apartment. Returned only for a place index that uses Esri as a data provider.
        UnitNumber:
          type: string
          description: For addresses with multiple units, the unit identifier. Can include numbers and letters, for example 3B or Unit 123. Returned only for a place index that uses Esri or Grab as a data provider. Is not returned for SearchPlaceIndexForPosition.
        Categories:
          type: array
          items:
            type: string
          description: The Amazon Location categories that describe this Place. For more information about using categories, including a list of Amazon Location categories, see Categories and filtering, in the Amazon Location Service developer guide.
        SupplementalCategories:
          type: array
          items:
            type: string
          description: Categories from the data provider that describe the Place that are not mapped to any Amazon Location categories.
        SubMunicipality:
          type: string
          description: An area that's part of a larger municipality. For example, Blissville is a submunicipality in the Queen County in New York. This property supported by Esri and OpenData. The Esri property is district, and the OpenData property is borough.
      required:
      - Geometry
  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)