Interface GeoPlacesAsyncClient

All Superinterfaces:
AutoCloseable, AwsClient, SdkAutoCloseable, SdkClient
@Generated("software.amazon.awssdk:codegen") @SdkPublicApi @ThreadSafe public interface GeoPlacesAsyncClient extends AwsClient
Service client for accessing Amazon Location Service Places V2 asynchronously. This can be created using the static builder() method.The asynchronous client performs non-blocking I/O when configured with any SdkAsyncHttpClient supported in the SDK. However, full non-blocking is not guaranteed as the async client may perform blocking calls in some cases such as credentials retrieval and endpoint discovery as part of the async API call.

The Places API enables powerful location search and geocoding capabilities for your applications, offering global coverage with rich, detailed information. Key features include:

  • Forward and reverse geocoding for addresses and coordinates

  • Comprehensive place searches with detailed information, including:

    • Business names and addresses

    • Contact information

    • Hours of operation

    • POI (Points of Interest) categories

    • Food types for restaurants

    • Chain affiliation for relevant businesses

  • Global data coverage with a wide range of POI categories

  • Regular data updates to ensure accuracy and relevance

  • Field Details

  • Method Details

    • autocomplete

      default CompletableFuture<AutocompleteResponse> autocomplete(AutocompleteRequest autocompleteRequest)

      Autocomplete completes potential places and addresses as the user types, based on the partial input. The API enhances the efficiency and accuracy of address by completing query based on a few entered keystrokes. It helps you by completing partial queries with valid address completion. Also, the API supports the filtering of results based on geographic location, country, or specific place types, and can be tailored using optional parameters like language and political views.

      Parameters:
      autocompleteRequest -
      Returns:
      A Java Future containing the result of the Autocomplete operation returned by the service.
      The CompletableFuture returned by this method can be completed exceptionally with the following exceptions. The exception returned is wrapped with CompletionException, so you need to invoke Throwable.getCause() to retrieve the underlying exception.
      • InternalServerException The request processing has failed because of an unknown error, exception or failure.
      • AccessDeniedException You don't have sufficient access to perform this action.
      • ValidationException The input fails to satisfy the constraints specified by an AWS service.
      • ThrottlingException The request was denied due to request throttling.
      • SdkException Base class for all exceptions that can be thrown by the SDK (both service and client). Can be used for catch all scenarios.
      • SdkClientException If any client side error occurs such as an IO related failure, failure to get credentials, etc.
      • GeoPlacesException Base class for all service exceptions. Unknown exceptions will be thrown as an instance of this type.
      See Also:

    • autocomplete

      default CompletableFuture<AutocompleteResponse> autocomplete(Consumer<AutocompleteRequest.Builder> autocompleteRequest)

      Autocomplete completes potential places and addresses as the user types, based on the partial input. The API enhances the efficiency and accuracy of address by completing query based on a few entered keystrokes. It helps you by completing partial queries with valid address completion. Also, the API supports the filtering of results based on geographic location, country, or specific place types, and can be tailored using optional parameters like language and political views.


      This is a convenience which creates an instance of the AutocompleteRequest.Builder avoiding the need to create one manually via AutocompleteRequest.builder()

      Parameters:
      autocompleteRequest - A Consumer that will call methods on AutocompleteRequest.Builder to create a request.
      Returns:
      A Java Future containing the result of the Autocomplete operation returned by the service.
      The CompletableFuture returned by this method can be completed exceptionally with the following exceptions. The exception returned is wrapped with CompletionException, so you need to invoke Throwable.getCause() to retrieve the underlying exception.
      • InternalServerException The request processing has failed because of an unknown error, exception or failure.
      • AccessDeniedException You don't have sufficient access to perform this action.
      • ValidationException The input fails to satisfy the constraints specified by an AWS service.
      • ThrottlingException The request was denied due to request throttling.
      • SdkException Base class for all exceptions that can be thrown by the SDK (both service and client). Can be used for catch all scenarios.
      • SdkClientException If any client side error occurs such as an IO related failure, failure to get credentials, etc.
      • GeoPlacesException Base class for all service exceptions. Unknown exceptions will be thrown as an instance of this type.
      See Also:

    • geocode

      default CompletableFuture<GeocodeResponse> geocode(GeocodeRequest geocodeRequest)

      Geocode converts a textual address or place into geographic coordinates. You can obtain geographic coordinates, address component, and other related information. It supports flexible queries, including free-form text or structured queries with components like street names, postal codes, and regions. The Geocode API can also provide additional features such as time zone information and the inclusion of political views.

      Parameters:
      geocodeRequest -
      Returns:
      A Java Future containing the result of the Geocode operation returned by the service.
      The CompletableFuture returned by this method can be completed exceptionally with the following exceptions. The exception returned is wrapped with CompletionException, so you need to invoke Throwable.getCause() to retrieve the underlying exception.
      • InternalServerException The request processing has failed because of an unknown error, exception or failure.
      • AccessDeniedException You don't have sufficient access to perform this action.
      • ValidationException The input fails to satisfy the constraints specified by an AWS service.
      • ThrottlingException The request was denied due to request throttling.
      • SdkException Base class for all exceptions that can be thrown by the SDK (both service and client). Can be used for catch all scenarios.
      • SdkClientException If any client side error occurs such as an IO related failure, failure to get credentials, etc.
      • GeoPlacesException Base class for all service exceptions. Unknown exceptions will be thrown as an instance of this type.
      See Also:

    • geocode

      default CompletableFuture<GeocodeResponse> geocode(Consumer<GeocodeRequest.Builder> geocodeRequest)

      Geocode converts a textual address or place into geographic coordinates. You can obtain geographic coordinates, address component, and other related information. It supports flexible queries, including free-form text or structured queries with components like street names, postal codes, and regions. The Geocode API can also provide additional features such as time zone information and the inclusion of political views.


      This is a convenience which creates an instance of the GeocodeRequest.Builder avoiding the need to create one manually via GeocodeRequest.builder()

      Parameters:
      geocodeRequest - A Consumer that will call methods on GeocodeRequest.Builder to create a request.
      Returns:
      A Java Future containing the result of the Geocode operation returned by the service.
      The CompletableFuture returned by this method can be completed exceptionally with the following exceptions. The exception returned is wrapped with CompletionException, so you need to invoke Throwable.getCause() to retrieve the underlying exception.
      • InternalServerException The request processing has failed because of an unknown error, exception or failure.
      • AccessDeniedException You don't have sufficient access to perform this action.
      • ValidationException The input fails to satisfy the constraints specified by an AWS service.
      • ThrottlingException The request was denied due to request throttling.
      • SdkException Base class for all exceptions that can be thrown by the SDK (both service and client). Can be used for catch all scenarios.
      • SdkClientException If any client side error occurs such as an IO related failure, failure to get credentials, etc.
      • GeoPlacesException Base class for all service exceptions. Unknown exceptions will be thrown as an instance of this type.
      See Also:

    • getPlace

      default CompletableFuture<GetPlaceResponse> getPlace(GetPlaceRequest getPlaceRequest)

      GetPlace finds a place by its unique ID. A PlaceId is returned by other place operations.

      Parameters:
      getPlaceRequest -
      Returns:
      A Java Future containing the result of the GetPlace operation returned by the service.
      The CompletableFuture returned by this method can be completed exceptionally with the following exceptions. The exception returned is wrapped with CompletionException, so you need to invoke Throwable.getCause() to retrieve the underlying exception.
      • InternalServerException The request processing has failed because of an unknown error, exception or failure.
      • AccessDeniedException You don't have sufficient access to perform this action.
      • ValidationException The input fails to satisfy the constraints specified by an AWS service.
      • ThrottlingException The request was denied due to request throttling.
      • SdkException Base class for all exceptions that can be thrown by the SDK (both service and client). Can be used for catch all scenarios.
      • SdkClientException If any client side error occurs such as an IO related failure, failure to get credentials, etc.
      • GeoPlacesException Base class for all service exceptions. Unknown exceptions will be thrown as an instance of this type.
      See Also:

    • getPlace

      default CompletableFuture<GetPlaceResponse> getPlace(Consumer<GetPlaceRequest.Builder> getPlaceRequest)

      GetPlace finds a place by its unique ID. A PlaceId is returned by other place operations.


      This is a convenience which creates an instance of the GetPlaceRequest.Builder avoiding the need to create one manually via GetPlaceRequest.builder()

      Parameters:
      getPlaceRequest - A Consumer that will call methods on GetPlaceRequest.Builder to create a request.
      Returns:
      A Java Future containing the result of the GetPlace operation returned by the service.
      The CompletableFuture returned by this method can be completed exceptionally with the following exceptions. The exception returned is wrapped with CompletionException, so you need to invoke Throwable.getCause() to retrieve the underlying exception.
      • InternalServerException The request processing has failed because of an unknown error, exception or failure.
      • AccessDeniedException You don't have sufficient access to perform this action.
      • ValidationException The input fails to satisfy the constraints specified by an AWS service.
      • ThrottlingException The request was denied due to request throttling.
      • SdkException Base class for all exceptions that can be thrown by the SDK (both service and client). Can be used for catch all scenarios.
      • SdkClientException If any client side error occurs such as an IO related failure, failure to get credentials, etc.
      • GeoPlacesException Base class for all service exceptions. Unknown exceptions will be thrown as an instance of this type.
      See Also:

    • reverseGeocode

      default CompletableFuture<ReverseGeocodeResponse> reverseGeocode(ReverseGeocodeRequest reverseGeocodeRequest)

      ReverseGeocode converts geographic coordinates into a human-readable address or place. You can obtain address component, and other related information such as place type, category, street information. The Reverse Geocode API supports filtering to on place type so that you can refine result based on your need. Also, The Reverse Geocode API can also provide additional features such as time zone information and the inclusion of political views.

      Parameters:
      reverseGeocodeRequest -
      Returns:
      A Java Future containing the result of the ReverseGeocode operation returned by the service.
      The CompletableFuture returned by this method can be completed exceptionally with the following exceptions. The exception returned is wrapped with CompletionException, so you need to invoke Throwable.getCause() to retrieve the underlying exception.
      • InternalServerException The request processing has failed because of an unknown error, exception or failure.
      • AccessDeniedException You don't have sufficient access to perform this action.
      • ValidationException The input fails to satisfy the constraints specified by an AWS service.
      • ThrottlingException The request was denied due to request throttling.
      • SdkException Base class for all exceptions that can be thrown by the SDK (both service and client). Can be used for catch all scenarios.
      • SdkClientException If any client side error occurs such as an IO related failure, failure to get credentials, etc.
      • GeoPlacesException Base class for all service exceptions. Unknown exceptions will be thrown as an instance of this type.
      See Also:

    • reverseGeocode

      default CompletableFuture<ReverseGeocodeResponse> reverseGeocode(Consumer<ReverseGeocodeRequest.Builder> reverseGeocodeRequest)

      ReverseGeocode converts geographic coordinates into a human-readable address or place. You can obtain address component, and other related information such as place type, category, street information. The Reverse Geocode API supports filtering to on place type so that you can refine result based on your need. Also, The Reverse Geocode API can also provide additional features such as time zone information and the inclusion of political views.


      This is a convenience which creates an instance of the ReverseGeocodeRequest.Builder avoiding the need to create one manually via ReverseGeocodeRequest.builder()

      Parameters:
      reverseGeocodeRequest - A Consumer that will call methods on ReverseGeocodeRequest.Builder to create a request.
      Returns:
      A Java Future containing the result of the ReverseGeocode operation returned by the service.
      The CompletableFuture returned by this method can be completed exceptionally with the following exceptions. The exception returned is wrapped with CompletionException, so you need to invoke Throwable.getCause() to retrieve the underlying exception.
      • InternalServerException The request processing has failed because of an unknown error, exception or failure.
      • AccessDeniedException You don't have sufficient access to perform this action.
      • ValidationException The input fails to satisfy the constraints specified by an AWS service.
      • ThrottlingException The request was denied due to request throttling.
      • SdkException Base class for all exceptions that can be thrown by the SDK (both service and client). Can be used for catch all scenarios.
      • SdkClientException If any client side error occurs such as an IO related failure, failure to get credentials, etc.
      • GeoPlacesException Base class for all service exceptions. Unknown exceptions will be thrown as an instance of this type.
      See Also:

    • searchNearby

      default CompletableFuture<SearchNearbyResponse> searchNearby(SearchNearbyRequest searchNearbyRequest)

      SearchNearby queries for points of interest within a radius from a central coordinates, returning place results with optional filters such as categories, business chains, food types and more. The API returns details such as a place name, address, phone, category, food type, contact, opening hours. Also, the API can return phonemes, time zones and more based on requested parameters.

      Parameters:
      searchNearbyRequest -
      Returns:
      A Java Future containing the result of the SearchNearby operation returned by the service.
      The CompletableFuture returned by this method can be completed exceptionally with the following exceptions. The exception returned is wrapped with CompletionException, so you need to invoke Throwable.getCause() to retrieve the underlying exception.
      • InternalServerException The request processing has failed because of an unknown error, exception or failure.
      • AccessDeniedException You don't have sufficient access to perform this action.
      • ValidationException The input fails to satisfy the constraints specified by an AWS service.
      • ThrottlingException The request was denied due to request throttling.
      • SdkException Base class for all exceptions that can be thrown by the SDK (both service and client). Can be used for catch all scenarios.
      • SdkClientException If any client side error occurs such as an IO related failure, failure to get credentials, etc.
      • GeoPlacesException Base class for all service exceptions. Unknown exceptions will be thrown as an instance of this type.
      See Also:

    • searchNearby

      default CompletableFuture<SearchNearbyResponse> searchNearby(Consumer<SearchNearbyRequest.Builder> searchNearbyRequest)

      SearchNearby queries for points of interest within a radius from a central coordinates, returning place results with optional filters such as categories, business chains, food types and more. The API returns details such as a place name, address, phone, category, food type, contact, opening hours. Also, the API can return phonemes, time zones and more based on requested parameters.


      This is a convenience which creates an instance of the SearchNearbyRequest.Builder avoiding the need to create one manually via SearchNearbyRequest.builder()

      Parameters:
      searchNearbyRequest - A Consumer that will call methods on SearchNearbyRequest.Builder to create a request.
      Returns:
      A Java Future containing the result of the SearchNearby operation returned by the service.
      The CompletableFuture returned by this method can be completed exceptionally with the following exceptions. The exception returned is wrapped with CompletionException, so you need to invoke Throwable.getCause() to retrieve the underlying exception.
      • InternalServerException The request processing has failed because of an unknown error, exception or failure.
      • AccessDeniedException You don't have sufficient access to perform this action.
      • ValidationException The input fails to satisfy the constraints specified by an AWS service.
      • ThrottlingException The request was denied due to request throttling.
      • SdkException Base class for all exceptions that can be thrown by the SDK (both service and client). Can be used for catch all scenarios.
      • SdkClientException If any client side error occurs such as an IO related failure, failure to get credentials, etc.
      • GeoPlacesException Base class for all service exceptions. Unknown exceptions will be thrown as an instance of this type.
      See Also:

    • searchText

      default CompletableFuture<SearchTextResponse> searchText(SearchTextRequest searchTextRequest)

      SearchText searches for geocode and place information. You can then complete a follow-up query suggested from the Suggest API via a query id.

      Parameters:
      searchTextRequest -
      Returns:
      A Java Future containing the result of the SearchText operation returned by the service.
      The CompletableFuture returned by this method can be completed exceptionally with the following exceptions. The exception returned is wrapped with CompletionException, so you need to invoke Throwable.getCause() to retrieve the underlying exception.
      • InternalServerException The request processing has failed because of an unknown error, exception or failure.
      • AccessDeniedException You don't have sufficient access to perform this action.
      • ValidationException The input fails to satisfy the constraints specified by an AWS service.
      • ThrottlingException The request was denied due to request throttling.
      • SdkException Base class for all exceptions that can be thrown by the SDK (both service and client). Can be used for catch all scenarios.
      • SdkClientException If any client side error occurs such as an IO related failure, failure to get credentials, etc.
      • GeoPlacesException Base class for all service exceptions. Unknown exceptions will be thrown as an instance of this type.
      See Also:

    • searchText

      default CompletableFuture<SearchTextResponse> searchText(Consumer<SearchTextRequest.Builder> searchTextRequest)

      SearchText searches for geocode and place information. You can then complete a follow-up query suggested from the Suggest API via a query id.


      This is a convenience which creates an instance of the SearchTextRequest.Builder avoiding the need to create one manually via SearchTextRequest.builder()

      Parameters:
      searchTextRequest - A Consumer that will call methods on SearchTextRequest.Builder to create a request.
      Returns:
      A Java Future containing the result of the SearchText operation returned by the service.
      The CompletableFuture returned by this method can be completed exceptionally with the following exceptions. The exception returned is wrapped with CompletionException, so you need to invoke Throwable.getCause() to retrieve the underlying exception.
      • InternalServerException The request processing has failed because of an unknown error, exception or failure.
      • AccessDeniedException You don't have sufficient access to perform this action.
      • ValidationException The input fails to satisfy the constraints specified by an AWS service.
      • ThrottlingException The request was denied due to request throttling.
      • SdkException Base class for all exceptions that can be thrown by the SDK (both service and client). Can be used for catch all scenarios.
      • SdkClientException If any client side error occurs such as an IO related failure, failure to get credentials, etc.
      • GeoPlacesException Base class for all service exceptions. Unknown exceptions will be thrown as an instance of this type.
      See Also:

    • suggest

      default CompletableFuture<SuggestResponse> suggest(SuggestRequest suggestRequest)

      Suggest provides intelligent predictions or recommendations based on the user's input or context, such as relevant places, points of interest, query terms or search category. It is designed to help users find places or point of interests candidates or identify a follow on query based on incomplete or misspelled queries. It returns a list of possible matches or refinements that can be used to formulate a more accurate query. Users can select the most appropriate suggestion and use it for further searching. The API provides options for filtering results by location and other attributes, and allows for additional features like phonemes and timezones. The response includes refined query terms and detailed place information.

      Parameters:
      suggestRequest -
      Returns:
      A Java Future containing the result of the Suggest operation returned by the service.
      The CompletableFuture returned by this method can be completed exceptionally with the following exceptions. The exception returned is wrapped with CompletionException, so you need to invoke Throwable.getCause() to retrieve the underlying exception.
      • InternalServerException The request processing has failed because of an unknown error, exception or failure.
      • AccessDeniedException You don't have sufficient access to perform this action.
      • ValidationException The input fails to satisfy the constraints specified by an AWS service.
      • ThrottlingException The request was denied due to request throttling.
      • SdkException Base class for all exceptions that can be thrown by the SDK (both service and client). Can be used for catch all scenarios.
      • SdkClientException If any client side error occurs such as an IO related failure, failure to get credentials, etc.
      • GeoPlacesException Base class for all service exceptions. Unknown exceptions will be thrown as an instance of this type.
      See Also:

    • suggest

      default CompletableFuture<SuggestResponse> suggest(Consumer<SuggestRequest.Builder> suggestRequest)

      Suggest provides intelligent predictions or recommendations based on the user's input or context, such as relevant places, points of interest, query terms or search category. It is designed to help users find places or point of interests candidates or identify a follow on query based on incomplete or misspelled queries. It returns a list of possible matches or refinements that can be used to formulate a more accurate query. Users can select the most appropriate suggestion and use it for further searching. The API provides options for filtering results by location and other attributes, and allows for additional features like phonemes and timezones. The response includes refined query terms and detailed place information.


      This is a convenience which creates an instance of the SuggestRequest.Builder avoiding the need to create one manually via SuggestRequest.builder()

      Parameters:
      suggestRequest - A Consumer that will call methods on SuggestRequest.Builder to create a request.
      Returns:
      A Java Future containing the result of the Suggest operation returned by the service.
      The CompletableFuture returned by this method can be completed exceptionally with the following exceptions. The exception returned is wrapped with CompletionException, so you need to invoke Throwable.getCause() to retrieve the underlying exception.
      • InternalServerException The request processing has failed because of an unknown error, exception or failure.
      • AccessDeniedException You don't have sufficient access to perform this action.
      • ValidationException The input fails to satisfy the constraints specified by an AWS service.
      • ThrottlingException The request was denied due to request throttling.
      • SdkException Base class for all exceptions that can be thrown by the SDK (both service and client). Can be used for catch all scenarios.
      • SdkClientException If any client side error occurs such as an IO related failure, failure to get credentials, etc.
      • GeoPlacesException Base class for all service exceptions. Unknown exceptions will be thrown as an instance of this type.
      See Also:

    • serviceClientConfiguration

      default GeoPlacesServiceClientConfiguration serviceClientConfiguration()
      Description copied from interface: SdkClient
      The SDK service client configuration exposes client settings to the user, e.g., ClientOverrideConfiguration
      Specified by:
      serviceClientConfiguration in interface AwsClient
      Specified by:
      serviceClientConfiguration in interface SdkClient
      Returns:
      SdkServiceClientConfiguration

    • create

      static GeoPlacesAsyncClient create()
      Create a GeoPlacesAsyncClient with the region loaded from the DefaultAwsRegionProviderChain and credentials loaded from the DefaultCredentialsProvider.

    • builder

      static GeoPlacesAsyncClientBuilder builder()
      Create a builder that can be used to configure and create a GeoPlacesAsyncClient.