Partilhar via

Azure Maps SDK Search client library for Java - version 2.0.0-beta.2

  • Artigo

Azure Maps SDK Search client library for Java.

This package contains the Azure Maps SDK Search client library which contains Azure Maps Search APIs. For documentation on how to use this package, please see Azure Maps Search SDK for Java.

Source code | API reference documentation | REST API documentation | Product documentation | Samples

Documentation

Various documentation is available to help you get started

Getting started

Prerequisites

Adding the package to your product

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-maps-search</artifactId>
    <version>2.0.0-beta.2</version>
</dependency>

Azure Maps Libraries require a TokenCredential implementation for authentication and an HttpClient implementation for HTTP client.

Azure Identity package and Azure Core Netty HTTP package provide the default implementation.

Authentication

There are 3 ways to authenticate the client: Shared key authentication, Microsoft Entra ID authentication, and shared access signature (SAS) authentication.

By default, Microsoft Entra ID token authentication depends on correct configuration of the following environment variables.

  • AZURE_CLIENT_ID for Azure client ID.
  • AZURE_TENANT_ID for Azure tenant ID.
  • AZURE_CLIENT_SECRET or AZURE_CLIENT_CERTIFICATE_PATH for client secret or client certificate.

In addition, Azure subscription ID can be configured via environment variable AZURE_SUBSCRIPTION_ID.

With above configuration, azure client can be authenticated by following code:

// 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
MapsSearchClient client = builder.buildClient();

The sample code assumes global Azure. Please change AzureEnvironment.AZURE variable if otherwise.

For SAS-based authentication, please refer to [AccountsListSasSamples.java][https://github.com/Azure/azure-sdk-for-java/tree/azure-maps-search_2.0.0-beta.2/sdk/maps/azure-resourcemanager-maps/src/samples/java/com/azure/resourcemanager/maps/generated/AccountsListSasSamples.java].

See Authentication for more options.

Key concepts

See API design for general introduction on design and key concepts on Azure Management Libraries.

Examples

Get Polygons

System.out.println("Get Polygons:");
GeoPosition coordinates = new GeoPosition(-122.204141, 47.61256);

Boundary result = client.getPolygons(coordinates, null, BoundaryResultTypeEnum.LOCALITY, ResolutionEnum.SMALL);

//with response
Response<Boundary> response = client.getPolygonsWithResponse(coordinates, null, BoundaryResultTypeEnum.LOCALITY, ResolutionEnum.SMALL, Context.NONE);

Get Geocoding

System.out.println("Get Geocoding:");

//simple
client.getGeocoding(new BaseSearchOptions().setQuery("1 Microsoft Way, Redmond, WA 98052"));

//with multiple options
GeocodingResponse result = client.getGeocoding(
    new BaseSearchOptions().setCoordinates(new GeoPosition(-74.011454, 40.706270)).setTop(5));

// with response
ResponseBase<SearchesGetGeocodingHeaders, GeocodingResponse> response = client.getGeocodingWithBaseResponse(
    new BaseSearchOptions().setCoordinates(new GeoPosition(-74.011454, 40.706270)).setTop(5), null);

// with response no custom header
Response<GeocodingResponse> responseNoHeader = client.getGeocodingNoCustomHeaderWithResponse(
    new BaseSearchOptions().setCoordinates(new GeoPosition(-74.011454, 40.706270)).setTop(5), null);

Get Geocoding Batch

System.out.println("Get Geocoding Batch:");

//with multiple items
GeocodingBatchRequestBody body = new GeocodingBatchRequestBody();
GeocodingBatchRequestItem addressLineItem = new GeocodingBatchRequestItem();
addressLineItem.setAddressLine("400 Broad St");
GeocodingBatchRequestItem queryItem = new GeocodingBatchRequestItem();
queryItem.setQuery("15171 NE 24th St, Redmond, WA 98052, United States");
body.setBatchItems(Arrays.asList(addressLineItem, queryItem));

GeocodingBatchResponse result = client.getGeocodingBatch(body);

// with response
Response<GeocodingBatchResponse> response = client.getGeocodingBatchWithResponse(body, Context.NONE);

Get Reverse Geocoding

System.out.println("Get Reverse Geocoding:");

GeoPosition coordinates = new GeoPosition(-122.34255, 47.0);
GeocodingResponse result = client.getReverseGeocoding(coordinates, Arrays.asList(ReverseGeocodingResultTypeEnum.ADDRESS), null);

//with response
Response<GeocodingResponse> response = client.getReverseGeocodingWithResponse(coordinates, Arrays.asList(ReverseGeocodingResultTypeEnum.ADDRESS), null, Context.NONE);

Get Reverse Geocoding Batch

System.out.println("Get Reverse Geocoding Batch:");

//with multiple items
ReverseGeocodingBatchRequestBody body = new ReverseGeocodingBatchRequestBody();
ReverseGeocodingBatchRequestItem item1 = new ReverseGeocodingBatchRequestItem();
ReverseGeocodingBatchRequestItem item2 = new ReverseGeocodingBatchRequestItem();
item1.setCoordinates(new GeoPosition(-122.34255, 47.0));
item2.setCoordinates(new GeoPosition(-122.34255, 47.0));
body.setBatchItems(Arrays.asList(item1, item2));

GeocodingBatchResponse result = client.getReverseGeocodingBatch(body);

// with response
Response<GeocodingBatchResponse> response = client.getReverseGeocodingBatchWithResponse(body, Context.NONE);

Troubleshooting

When you interact with the Azure Maps Services, errors returned by the Maps service correspond to the same HTTP status codes returned for REST API requests.

For example, if you search with an invalid coordinate, a error is returned, indicating "Bad Request".400

Next steps

Several Azure Maps Search Java SDK samples are available to you in the SDK's GitHub repository. Azure Maps Search Samples

Contributing

For details on contributing to this repository, see the contributing guide.

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request

Impressions