:doc:`LocationService <../../location>` / Client / search_place_index_for_position

*******************************
search_place_index_for_position
*******************************



.. py:method:: LocationService.Client.search_place_index_for_position(**kwargs)

  

  

  .. warning::

    

    This operation is no longer current and may be deprecated in the future. We recommend you upgrade to `ReverseGeocode </location/latest/APIReference/API_geoplaces_ReverseGeocode.html>`__ or `SearchNearby </location/latest/APIReference/API_geoplaces_SearchNearby.html>`__ unless you require Grab data.

     

    
    * ``SearchPlaceIndexForPosition`` 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 version 2 ``ReverseGeocode`` operation gives better results in the address reverse-geocoding use case, while the version 2 ``SearchNearby`` operation gives better results when searching for businesses and points of interest near a specific location.
     
    * 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.
    

    

   

  Reverse geocodes a given coordinate and returns a legible address. Allows you to search for Places or points of interest near a given position.

  

  

  See also: `AWS API Documentation <https://docs.aws.amazon.com/goto/WebAPI/location-2020-11-19/SearchPlaceIndexForPosition>`_  


  **Request Syntax**
  ::

    response = client.search_place_index_for_position(
        IndexName='string',
        Position=[
            123.0,
        ],
        MaxResults=123,
        Language='string',
        Key='string'
    )
    
  :type IndexName: string
  :param IndexName: **[REQUIRED]** 

    The name of the place index resource you want to use for the search.

    

  
  :type Position: list
  :param Position: **[REQUIRED]** 

    Specifies the longitude and latitude of the position to query.

     

    This parameter must contain a pair of numbers. The first number represents the X coordinate, or longitude; the second number represents the Y coordinate, or latitude.

     

    For example, ``[-123.1174, 49.2847]`` represents a position with longitude ``-123.1174`` and latitude ``49.2847``.

    

  
    - *(float) --* 

    

  :type MaxResults: integer
  :param MaxResults: 

    An optional parameter. The maximum number of results returned per request.

     

    Default value: ``50``

    

  
  :type Language: string
  :param Language: 

    The preferred language used to return results. The value must be a valid `BCP 47 <https://tools.ietf.org/search/bcp47>`__ 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 the ``city`` in the results will more likely be returned as ``Αθήνα``.

     

    If the data provider does not have a value for Greek, the result will be in a language that the provider does support.

    

  
  :type Key: string
  :param Key: 

    The optional `API key <https://docs.aws.amazon.com/location/previous/developerguide/using-apikeys.html>`__ to authorize the request.

    

  
  
  :rtype: dict
  :returns: 
    
    **Response Syntax**

    
    ::

      {
          'Summary': {
              'Position': [
                  123.0,
              ],
              'MaxResults': 123,
              'DataSource': 'string',
              'Language': 'string'
          },
          'Results': [
              {
                  'Place': {
                      'Label': 'string',
                      'Geometry': {
                          'Point': [
                              123.0,
                          ]
                      },
                      'AddressNumber': 'string',
                      'Street': 'string',
                      'Neighborhood': 'string',
                      'Municipality': 'string',
                      'SubRegion': 'string',
                      'Region': 'string',
                      'Country': 'string',
                      'PostalCode': 'string',
                      'Interpolated': True|False,
                      'TimeZone': {
                          'Name': 'string',
                          'Offset': 123
                      },
                      'UnitType': 'string',
                      'UnitNumber': 'string',
                      'Categories': [
                          'string',
                      ],
                      'SupplementalCategories': [
                          'string',
                      ],
                      'SubMunicipality': 'string'
                  },
                  'Distance': 123.0,
                  'PlaceId': 'string'
              },
          ]
      }
      
    **Response Structure**

    

    - *(dict) --* 
      

      - **Summary** *(dict) --* 

        Contains a summary of the request. Echoes the input values for ``Position``, ``Language``, ``MaxResults``, and the ``DataSource`` of the place index.

        
        

        - **Position** *(list) --* 

          The position specified in the request.

          
          

          - *(float) --* 
      
        

        - **MaxResults** *(integer) --* 

          Contains the optional result count limit that is specified in the request.

           

          Default value: ``50``

          
        

        - **DataSource** *(string) --* 

          The geospatial data provider attached to the place index resource specified in the request. Values can be one of the following:

           

          
          * Esri
           
          * Grab
           
          * Here
          

           

          For more information about data providers, see `Amazon Location Service data providers <https://docs.aws.amazon.com/location/previous/developerguide/what-is-data-provider.html>`__.

          
        

        - **Language** *(string) --* 

          The preferred language used to return results. Matches the language in the request. The value is a valid `BCP 47 <https://tools.ietf.org/search/bcp47>`__ language tag, for example, ``en`` for English.

          
    
      

      - **Results** *(list) --* 

        Returns a list of Places closest to the specified position. Each result contains additional information about the Places returned.

        
        

        - *(dict) --* 

          Contains a search result from a position search query that is run on a place index resource.

          
          

          - **Place** *(dict) --* 

            Details about the search result, such as its address and position.

            
            

            - **Label** *(string) --* 

              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** *(dict) --* 

              Places uses a point geometry to specify a location or a Place.

              
              

              - **Point** *(list) --* 

                A single point geometry specifies a location for a Place using `WGS 84 <https://gisgeography.com/wgs84-world-geodetic-system/>`__ coordinates:

                 

                
                * *x* — Specifies the x coordinate or longitude.
                 
                * *y* — Specifies the y coordinate or latitude.
                

                
                

                - *(float) --* 
            
          
            

            - **AddressNumber** *(string) --* 

              The numerical portion of an address, such as a building number.

              
            

            - **Street** *(string) --* 

              The name for a street or a road to identify a location. For example, ``Main Street``.

              
            

            - **Neighborhood** *(string) --* 

              The name of a community district. For example, ``Downtown``.

              
            

            - **Municipality** *(string) --* 

              A name for a local area, such as a city or town name. For example, ``Toronto``.

              
            

            - **SubRegion** *(string) --* 

              A county, or an area that's part of a larger region. For example, ``Metro Vancouver``.

              
            

            - **Region** *(string) --* 

              A name for an area or geographical division, such as a province or state name. For example, ``British Columbia``.

              
            

            - **Country** *(string) --* 

              A country/region specified using `ISO 3166 <https://www.iso.org/iso-3166-country-codes.html>`__ 3-digit country/region code. For example, ``CAN``.

              
            

            - **PostalCode** *(string) --* 

              A group of numbers and letters in a country-specific format, which accompanies the address for the purpose of identifying a location.

              
            

            - **Interpolated** *(boolean) --* 

              ``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** *(dict) --* 

              The time zone in which the ``Place`` is located. Returned only when using HERE or Grab as the selected partner.

              
              

              - **Name** *(string) --* 

                The name of the time zone, following the `IANA time zone standard <https://www.iana.org/time-zones>`__. For example, ``America/Los_Angeles``.

                
              

              - **Offset** *(integer) --* 

                The time zone's offset, in seconds, from UTC.

                
          
            

            - **UnitType** *(string) --* 

              For addresses with a ``UnitNumber``, the type of unit. For example, ``Apartment``.

               

              .. note::

                

                Returned only for a place index that uses Esri as a data provider.

                

              
            

            - **UnitNumber** *(string) --* 

              For addresses with multiple units, the unit identifier. Can include numbers and letters, for example ``3B`` or ``Unit 123``.

               

              .. note::

                

                Returned only for a place index that uses Esri or Grab as a data provider. Is not returned for ``SearchPlaceIndexForPosition``.

                

              
            

            - **Categories** *(list) --* 

              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 <https://docs.aws.amazon.com/location/previous/developerguide/category-filtering.html>`__, in the *Amazon Location Service developer guide*.

              
              

              - *(string) --* 
          
            

            - **SupplementalCategories** *(list) --* 

              Categories from the data provider that describe the Place that are not mapped to any Amazon Location categories.

              
              

              - *(string) --* 
          
            

            - **SubMunicipality** *(string) --* 

              An area that's part of a larger municipality. For example, ``Blissville`` is a submunicipality in the Queen County in New York.

               

              .. note::

                

                This property supported by Esri and OpenData. The Esri property is ``district``, and the OpenData property is ``borough``.

                

              
        
          

          - **Distance** *(float) --* 

            The distance in meters of a great-circle arc between the query position and the result.

             

            .. note::

              

              A great-circle arc is the shortest path on a sphere, in this case the Earth. This returns the shortest distance between two locations.

              

            
          

          - **PlaceId** *(string) --* 

            The unique identifier of the place. You can use this with the ``GetPlace`` operation to find the place again later.

             

            .. note::

              

              For ``SearchPlaceIndexForPosition`` operations, the ``PlaceId`` is returned only by place indexes that use HERE or Grab as a data provider.

              

            
      
    
  
  **Exceptions**
  
  *   :py:class:`LocationService.Client.exceptions.InternalServerException`

  
  *   :py:class:`LocationService.Client.exceptions.ResourceNotFoundException`

  
  *   :py:class:`LocationService.Client.exceptions.AccessDeniedException`

  
  *   :py:class:`LocationService.Client.exceptions.ValidationException`

  
  *   :py:class:`LocationService.Client.exceptions.ThrottlingException`

  