Package com.azure.maps.search

Class MapsSearchAsyncClient

java.lang.Object
com.azure.maps.search.MapsSearchAsyncClient
public final class MapsSearchAsyncClient extends Object
Initializes a new instance of the asynchronous SearchClient type. Creating an async client using a AzureKeyCredential: 
 // Authenticates using subscription key
 AzureKeyCredential keyCredential = new AzureKeyCredential(System.getenv("SUBSCRIPTION_KEY"));

 // Creates a builder
 MapsSearchClientBuilder builder = new MapsSearchClientBuilder();
 builder.credential(keyCredential);
 builder.httpLogOptions(new HttpLogOptions().setLogLevel(HttpLogDetailLevel.BODY_AND_HEADERS));

 // Builds the client
 MapsSearchAsyncClient client = builder.buildAsyncClient();
Creating an async client using a TokenCredential: 
 // Authenticates using Azure AD building a default credential
 // This will look for AZURE_CLIENT_ID, AZURE_TENANT_ID, and AZURE_CLIENT_SECRET env variables
 DefaultAzureCredential tokenCredential = new DefaultAzureCredentialBuilder().build();

 // Creates a builder
 MapsSearchClientBuilder builder = new MapsSearchClientBuilder();
 builder.credential(tokenCredential);
 builder.mapsClientId(System.getenv("MAPS_CLIENT_ID"));
 builder.httpLogOptions(new HttpLogOptions().setLogLevel(HttpLogDetailLevel.BODY_AND_HEADERS));

 // Builds a client
 MapsSearchAsyncClient client = builder.buildAsyncClient();

  • Method Details

    • getPolygons

      public Mono<Boundary> getPolygons(com.azure.core.models.GeoPosition coordinates, String view, BoundaryResultTypeEnum resultType, ResolutionEnum resolution)
      Use to get polygon data of a geographical area shape such as a city or a country region. The `Get Polygon` API is an HTTP `GET` request that supplies polygon data of a geographical area outline such as a city or a country region.
      Parameters:
      coordinates - A point on the earth specified as a longitude and latitude. Example: &coordinates=lon,lat.
      view - A string that represents an [ISO 3166-1 Alpha-2 region/country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). This will alter Geopolitical disputed borders and labels to align with the specified user region. By default, the View parameter is set to “Auto” even if you haven’t defined it in the request. Please refer to [Supported Views](https://aka.ms/AzureMapsLocalizationViews) for details and to see the available Views.
      resultType - The geopolitical concept to return a boundary for. If not specified, the default is `countryRegion` result type.
      resolution - Resolution determines the amount of points to send back. If not specified, the default is medium resolution.
      Returns:
      `GeoJSON GeocodingFeature` object that describe the boundaries of a geographical area.
      Throws:
      IllegalArgumentException - thrown if parameters fail the validation.
      com.azure.core.exception.HttpResponseException - thrown if the request is rejected by server.
      RuntimeException - all other wrapped checked exceptions if the request fails to be sent.

    • getPolygonsWithResponse

      public Mono<com.azure.core.http.rest.Response<Boundary>> getPolygonsWithResponse(com.azure.core.models.GeoPosition coordinates, String view, BoundaryResultTypeEnum resultType, ResolutionEnum resolution, com.azure.core.util.Context context)
      Use to get polygon data of a geographical area shape such as a city or a country region. The `Get Polygon` API is an HTTP `GET` request that supplies polygon data of a geographical area outline such as a city or a country region.
      Parameters:
      coordinates - A point on the earth specified as a longitude and latitude. Example: &coordinates=lon,lat.
      view - A string that represents an [ISO 3166-1 Alpha-2 region/country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). This will alter Geopolitical disputed borders and labels to align with the specified user region. By default, the View parameter is set to “Auto” even if you haven’t defined it in the request. Please refer to [Supported Views](https://aka.ms/AzureMapsLocalizationViews) for details and to see the available Views.
      resultType - The geopolitical concept to return a boundary for. If not specified, the default is `countryRegion` result type.
      resolution - Resolution determines the amount of points to send back. If not specified, the default is medium resolution.
      context - The context to associate with this operation.
      Returns:
      Boundary object that describe the boundaries of a geographical area along with Response on successful completion of Mono.
      Throws:
      IllegalArgumentException - thrown if parameters fail the validation.
      com.azure.core.exception.HttpResponseException - thrown if the request is rejected by server.
      RuntimeException - all other wrapped checked exceptions if the request fails to be sent.

    • getGeocoding

      public Mono<GeocodingResponse> getGeocoding(BaseSearchOptions options)
      Use to get longitude and latitude coordinates of a street address or name of a place. The `Get Geocoding` API is an HTTP `GET` request that returns the longitude and latitude coordinates of the location being searched. In many cases, the complete search service might be too much, for instance if you are only interested in traditional geocoding. Search can also be accessed for address look up exclusively. The geocoding is performed by hitting the geocoding endpoint with just the address or partial address in question. The geocoding search index will be queried for everything above the street level data. No Point of Interest (POIs) will be returned. Note that the geocoder is very tolerant of typos and incomplete addresses. It will also handle everything from exact street addresses or street or intersections as well as higher level geographies such as city centers, counties and states. The response also returns detailed address properties such as street, postal code, municipality, and country/region information.
      Parameters:
      options - base search options. **If query is given, should not use this parameter.**.
      Returns:
      this object is returned from a successful Geocoding call on successful completion of Mono.
      Throws:
      IllegalArgumentException - thrown if parameters fail the validation.
      com.azure.core.exception.HttpResponseException - thrown if the request is rejected by server.
      RuntimeException - all other wrapped checked exceptions if the request fails to be sent.

    • getGeocodingNoCustomHeaderWithResponse

      public Mono<com.azure.core.http.rest.Response<GeocodingResponse>> getGeocodingNoCustomHeaderWithResponse(BaseSearchOptions options)
      Use to get longitude and latitude coordinates of a street address or name of a place. The `Get Geocoding` API is an HTTP `GET` request that returns the longitude and latitude coordinates of the location being searched. In many cases, the complete search service might be too much, for instance if you are only interested in traditional geocoding. Search can also be accessed for address look up exclusively. The geocoding is performed by hitting the geocoding endpoint with just the address or partial address in question. The geocoding search index will be queried for everything above the street level data. No Point of Interest (POIs) will be returned. Note that the geocoder is very tolerant of typos and incomplete addresses. It will also handle everything from exact street addresses or street or intersections as well as higher level geographies such as city centers, counties and states. The response also returns detailed address properties such as street, postal code, municipality, and country/region information.
      Parameters:
      options - Base Search options. **If query is given, should not use this parameter.**.
      Returns:
      this object is returned from a successful Geocoding call along with Response on successful completion of Mono.
      Throws:
      IllegalArgumentException - thrown if parameters fail the validation.
      com.azure.core.exception.HttpResponseException - thrown if the request is rejected by server.
      RuntimeException - all other wrapped checked exceptions if the request fails to be sent.

    • getGeocodingWithBaseResponse

      public Mono<com.azure.core.http.rest.ResponseBase<com.azure.maps.search.implementation.models.SearchesGetGeocodingHeaders,GeocodingResponse>> getGeocodingWithBaseResponse(BaseSearchOptions options)
      Use to get longitude and latitude coordinates of a street address or name of a place. The `Get Geocoding` API is an HTTP `GET` request that returns the longitude and latitude coordinates of the location being searched. In many cases, the complete search service might be too much, for instance if you are only interested in traditional geocoding. Search can also be accessed for address look up exclusively. The geocoding is performed by hitting the geocoding endpoint with just the address or partial address in question. The geocoding search index will be queried for everything above the street level data. No Point of Interest (POIs) will be returned. Note that the geocoder is very tolerant of typos and incomplete addresses. It will also handle everything from exact street addresses or street or intersections as well as higher level geographies such as city centers, counties and states. The response also returns detailed address properties such as street, postal code, municipality, and country/region information.
      Parameters:
      options - base search options. **If query is given, should not use this parameter.**.
      Returns:
      this object is returned from a successful Geocoding call along with ResponseBase on successful completion of Mono.
      Throws:
      IllegalArgumentException - thrown if parameters fail the validation.
      com.azure.core.exception.HttpResponseException - thrown if the request is rejected by server.
      RuntimeException - all other wrapped checked exceptions if the request fails to be sent.

    • getGeocodingBatch

      public Mono<GeocodingBatchResponse> getGeocodingBatch(GeocodingBatchRequestBody body)
      Use to send a batch of queries to the [Geocoding](/rest/api/maps/search/get-geocoding) API in a single request. The `Get Geocoding Batch` API is an HTTP `POST` request that sends batches of up to **100** queries to the [Geocoding](/rest/api/maps/search/get-geocoding) API in a single request. ### Submit Synchronous Batch Request The Synchronous API is recommended for lightweight batch requests. When the service receives a request, it will respond as soon as the batch items are calculated and there will be no possibility to retrieve the results later. The Synchronous API will return a timeout error (a 408 response) if the request takes longer than 60 seconds. The number of batch items is limited to **100** for this API. ``` POST https://atlas.microsoft.com/geocode:batch?api-version=2023-06-01 ``` ### POST Body for Batch Request To send the _geocoding_ queries you will use a `POST` request where the request body will contain the `batchItems` array in `json` format and the `Content-Type` header will be set to `application/json`. Here's a sample request body containing 2 _geocoding_ queries: ``` { "batchItems": [ { "addressLine": "One, Microsoft Way, Redmond, WA 98052", "top": 2 }, { "addressLine": "Pike Pl", "adminDistrict": "WA", "locality": "Seattle", "top": 3 } ] } ``` A _geocoding_ batchItem object can accept any of the supported _geocoding_ [URI parameters](/rest/api/maps/search/get-geocoding#uri-parameters). The batch should contain at least **1** query. ### Batch Response Model The batch response contains a `summary` component that indicates the `totalRequests` that were part of the original batch request and `successfulRequests` i.e. queries which were executed successfully. The batch response also includes a `batchItems` array which contains a response for each and every query in the batch request. The `batchItems` will contain the results in the exact same order the original queries were sent in the batch request. Each item is of one of the following types: - [`GeocodingResponse`](/rest/api/maps/search/get-geocoding#geocodingresponse) - If the query completed successfully. - `Error` - If the query failed. The response will contain a `code` and a `message` in this case.
      Parameters:
      body - The list of address geocoding queries/requests to process. The list can contain a max of 100 queries and must contain at least 1 query.
      Returns:
      this object is returned from a successful Geocoding Batch service call on successful completion of Mono.
      Throws:
      IllegalArgumentException - thrown if parameters fail the validation.
      com.azure.core.exception.HttpResponseException - thrown if the request is rejected by server.
      RuntimeException - all other wrapped checked exceptions if the request fails to be sent.

    • getGeocodingBatchWithResponse

      public Mono<com.azure.core.http.rest.Response<GeocodingBatchResponse>> getGeocodingBatchWithResponse(GeocodingBatchRequestBody body)
      Use to send a batch of queries to the [Geocoding](/rest/api/maps/search/get-geocoding) API in a single request. The `Get Geocoding Batch` API is an HTTP `POST` request that sends batches of up to **100** queries to the [Geocoding](/rest/api/maps/search/get-geocoding) API in a single request. ### Submit Synchronous Batch Request The Synchronous API is recommended for lightweight batch requests. When the service receives a request, it will respond as soon as the batch items are calculated and there will be no possibility to retrieve the results later. The Synchronous API will return a timeout error (a 408 response) if the request takes longer than 60 seconds. The number of batch items is limited to **100** for this API. ``` POST https://atlas.microsoft.com/geocode:batch?api-version=2023-06-01 ``` ### POST Body for Batch Request To send the _geocoding_ queries you will use a `POST` request where the request body will contain the `batchItems` array in `json` format and the `Content-Type` header will be set to `application/json`. Here's a sample request body containing 2 _geocoding_ queries: ``` { "batchItems": [ { "addressLine": "One, Microsoft Way, Redmond, WA 98052", "top": 2 }, { "addressLine": "Pike Pl", "adminDistrict": "WA", "locality": "Seattle", "top": 3 } ] } ``` A _geocoding_ batchItem object can accept any of the supported _geocoding_ [URI parameters](/rest/api/maps/search/get-geocoding#uri-parameters). The batch should contain at least **1** query. ### Batch Response Model The batch response contains a `summary` component that indicates the `totalRequests` that were part of the original batch request and `successfulRequests` i.e. queries which were executed successfully. The batch response also includes a `batchItems` array which contains a response for each and every query in the batch request. The `batchItems` will contain the results in the exact same order the original queries were sent in the batch request. Each item is of one of the following types: - [`GeocodingResponse`](/rest/api/maps/search/get-geocoding#geocodingresponse) - If the query completed successfully. - `Error` - If the query failed. The response will contain a `code` and a `message` in this case.
      Parameters:
      body - The list of address geocoding queries/requests to process. The list can contain a max of 100 queries and must contain at least 1 query.
      Returns:
      this object is returned from a successful Geocoding Batch service call along with Response on successful completion of Mono.
      Throws:
      IllegalArgumentException - thrown if parameters fail the validation.
      com.azure.core.exception.HttpResponseException - thrown if the request is rejected by server.
      RuntimeException - all other wrapped checked exceptions if the request fails to be sent.

    • getReverseGeocoding

      public Mono<GeocodingResponse> getReverseGeocoding(com.azure.core.models.GeoPosition coordinates, List<com.azure.maps.search.implementation.models.ReverseGeocodingResultTypeEnum> resultTypes, String view)
      Use to get a street address and location info from longitude and latitude coordinates. The `Get Reverse Geocoding` API is an HTTP `GET` request used to translate a coordinate (example: 37.786505, -122.3862) into a human understandable street address. Useful in tracking applications where you receive a GPS feed from the device or asset and wish to know the address associated with the coordinates. This endpoint will return address information for a given coordinate.
      Parameters:
      coordinates - The coordinates of the location that you want to reverse geocode. Example: &coordinates=lon,lat.
      resultTypes - Specify entity types that you want in the response. Only the types you specify will be returned. If the point cannot be mapped to the entity types you specify, no location information is returned in the response. Default value is all possible entities. A comma separated list of entity types selected from the following options. - Address - Neighborhood - PopulatedPlace - Postcode1 - AdminDivision1 - AdminDivision2 - CountryRegion These entity types are ordered from the most specific entity to the least specific entity. When entities of more than one entity type are found, only the most specific entity is returned. For example, if you specify Address and AdminDistrict1 as entity types and entities were found for both types, only the Address entity information is returned in the response.
      view - A string that represents an [ISO 3166-1 Alpha-2 region/country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). This will alter Geopolitical disputed borders and labels to align with the specified user region. By default, the View parameter is set to “Auto” even if you haven’t defined it in the request. Please refer to [Supported Views](https://aka.ms/AzureMapsLocalizationViews) for details and to see the available Views.
      Returns:
      this object is returned from a successful Geocoding call on successful completion of Mono.
      Throws:
      IllegalArgumentException - thrown if parameters fail the validation.
      com.azure.core.exception.HttpResponseException - thrown if the request is rejected by server.
      RuntimeException - all other wrapped checked exceptions if the request fails to be sent.

    • getReverseGeocodingWithResponse

      public Mono<com.azure.core.http.rest.Response<GeocodingResponse>> getReverseGeocodingWithResponse(com.azure.core.models.GeoPosition coordinates, List<com.azure.maps.search.implementation.models.ReverseGeocodingResultTypeEnum> resultTypes, String view)
      Use to get a street address and location info from longitude and latitude coordinates. The `Get Reverse Geocoding` API is an HTTP `GET` request used to translate a coordinate (example: 37.786505, -122.3862) into a human understandable street address. Useful in tracking applications where you receive a GPS feed from the device or asset and wish to know the address associated with the coordinates. This endpoint will return address information for a given coordinate.
      Parameters:
      coordinates - The coordinates of the location that you want to reverse geocode. Example: &coordinates=lon,lat.
      resultTypes - Specify entity types that you want in the response. Only the types you specify will be returned. If the point cannot be mapped to the entity types you specify, no location information is returned in the response. Default value is all possible entities. A comma separated list of entity types selected from the following options. - Address - Neighborhood - PopulatedPlace - Postcode1 - AdminDivision1 - AdminDivision2 - CountryRegion These entity types are ordered from the most specific entity to the least specific entity. When entities of more than one entity type are found, only the most specific entity is returned. For example, if you specify Address and AdminDistrict1 as entity types and entities were found for both types, only the Address entity information is returned in the response.
      view - A string that represents an [ISO 3166-1 Alpha-2 region/country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). This will alter Geopolitical disputed borders and labels to align with the specified user region. By default, the View parameter is set to “Auto” even if you haven’t defined it in the request. Please refer to [Supported Views](https://aka.ms/AzureMapsLocalizationViews) for details and to see the available Views.
      Returns:
      this object is returned from a successful Geocoding call along with Response on successful completion of Mono.
      Throws:
      IllegalArgumentException - thrown if parameters fail the validation.
      com.azure.core.exception.HttpResponseException - thrown if the request is rejected by server.
      RuntimeException - all other wrapped checked exceptions if the request fails to be sent.

    • getReverseGeocodingBatch

      public Mono<GeocodingBatchResponse> getReverseGeocodingBatch(ReverseGeocodingBatchRequestBody reverseGeocodingBatchRequestBody)
      Use to send a batch of queries to the [Reverse Geocoding](/rest/api/maps/search/get-reverse-geocoding) API in a single request. The `Get Reverse Geocoding Batch` API is an HTTP `POST` request that sends batches of up to **100** queries to [Reverse Geocoding](/rest/api/maps/search/get-reverse-geocoding) API using a single request. ### Submit Synchronous Batch Request The Synchronous API is recommended for lightweight batch requests. When the service receives a request, it will respond as soon as the batch items are calculated and there will be no possibility to retrieve the results later. The Synchronous API will return a timeout error (a 408 response) if the request takes longer than 60 seconds. The number of batch items is limited to **100** for this API. ``` POST https://atlas.microsoft.com/reverseGeocode:batch?api-version=2023-06-01 ``` ### POST Body for Batch Request To send the _reverse geocoding_ queries you will use a `POST` request where the request body will contain the `batchItems` array in `json` format and the `Content-Type` header will be set to `application/json`. Here's a sample request body containing 2 _reverse geocoding_ queries: ``` { "batchItems": [ { "coordinates": [-122.128275, 47.639429], "resultTypes": ["Address", "PopulatedPlace"] }, { "coordinates": [-122.341979399674, 47.6095253501216] } ] } ``` A _reverse geocoding_ batchItem object can accept any of the supported _reverse geocoding_ [URI parameters](/rest/api/maps/search/get-reverse-geocoding#uri-parameters). The batch should contain at least **1** query. ### Batch Response Model The batch response contains a `summary` component that indicates the `totalRequests` that were part of the original batch request and `successfulRequests` i.e. queries which were executed successfully. The batch response also includes a `batchItems` array which contains a response for each and every query in the batch request. The `batchItems` will contain the results in the exact same order the original queries were sent in the batch request. Each item is of one of the following types: - [`GeocodingResponse`](/rest/api/maps/search/get-reverse-geocoding#geocodingresponse) - If the query completed successfully. - `Error` - If the query failed. The response will contain a `code` and a `message` in this case.
      Parameters:
      reverseGeocodingBatchRequestBody - The list of reverse geocoding queries/requests to process. The list can contain a max of 100 queries and must contain at least 1 query.
      Returns:
      this object is returned from a successful Geocoding Batch service call on successful completion of Mono.
      Throws:
      IllegalArgumentException - thrown if parameters fail the validation.
      com.azure.core.exception.HttpResponseException - thrown if the request is rejected by server.
      RuntimeException - all other wrapped checked exceptions if the request fails to be sent.

    • getReverseGeocodingBatchWithResponse

      public Mono<com.azure.core.http.rest.Response<GeocodingBatchResponse>> getReverseGeocodingBatchWithResponse(ReverseGeocodingBatchRequestBody reverseGeocodingBatchRequestBody)
      Use to send a batch of queries to the [Reverse Geocoding](/rest/api/maps/search/get-reverse-geocoding) API in a single request. The `Get Reverse Geocoding Batch` API is an HTTP `POST` request that sends batches of up to **100** queries to [Reverse Geocoding](/rest/api/maps/search/get-reverse-geocoding) API using a single request. ### Submit Synchronous Batch Request The Synchronous API is recommended for lightweight batch requests. When the service receives a request, it will respond as soon as the batch items are calculated and there will be no possibility to retrieve the results later. The Synchronous API will return a timeout error (a 408 response) if the request takes longer than 60 seconds. The number of batch items is limited to **100** for this API. ``` POST https://atlas.microsoft.com/reverseGeocode:batch?api-version=2023-06-01 ``` ### POST Body for Batch Request To send the _reverse geocoding_ queries you will use a `POST` request where the request body will contain the `batchItems` array in `json` format and the `Content-Type` header will be set to `application/json`. Here's a sample request body containing 2 _reverse geocoding_ queries: ``` { "batchItems": [ { "coordinates": [-122.128275, 47.639429], "resultTypes": ["Address", "PopulatedPlace"] }, { "coordinates": [-122.341979399674, 47.6095253501216] } ] } ``` A _reverse geocoding_ batchItem object can accept any of the supported _reverse geocoding_ [URI parameters](/rest/api/maps/search/get-reverse-geocoding#uri-parameters). The batch should contain at least **1** query. ### Batch Response Model The batch response contains a `summary` component that indicates the `totalRequests` that were part of the original batch request and `successfulRequests` i.e. queries which were executed successfully. The batch response also includes a `batchItems` array which contains a response for each and every query in the batch request. The `batchItems` will contain the results in the exact same order the original queries were sent in the batch request. Each item is of one of the following types: - [`GeocodingResponse`](/rest/api/maps/search/get-reverse-geocoding#geocodingresponse) - If the query completed successfully. - `Error` - If the query failed. The response will contain a `code` and a `message` in this case.
      Parameters:
      reverseGeocodingBatchRequestBody - The list of reverse geocoding queries/requests to process. The list can contain a max of 100 queries and must contain at least 1 query.
      Returns:
      this object is returned from a successful Geocoding Batch service call along with Response on successful completion of Mono.
      Throws:
      IllegalArgumentException - thrown if parameters fail the validation.
      com.azure.core.exception.HttpResponseException - thrown if the request is rejected by server.
      RuntimeException - all other wrapped checked exceptions if the request fails to be sent.