Apple Maps Java

https://github.com/williamagh/apple-maps-java
Admin
A lightweight unofficial Java SDK for the Apple Maps Server API that provides server-side geocoding,...
Tokens:12,250
Snippets:103
Trust Score:7.5
License:MIT
Update:9 months ago
Show doc for...
Tokens:
Raw
### Copy .env Example File

Source: https://github.com/williamagh/apple-maps-java/blob/dev/docs/authorization.md

This command copies the example .env file to a new .env file, which is then used to store local development secrets. The .env file is ignored by git to prevent accidental commits of sensitive information.

```bash
cp .env-example .env
```

--------------------------------

### Quick Start: Initialize Apple Maps API and Perform Geocoding

Source: https://github.com/williamagh/apple-maps-java/blob/dev/docs/usage.md

Demonstrates how to initialize the Apple Maps API client by retrieving an API token from environment variables or system properties, and then performs a geocoding request for a given address.

```java
String token = System.getenv("APPLE_MAPS_TOKEN");
if (token == null || token.isBlank()) {
    token = System.getProperty("APPLE_MAPS_TOKEN");
}

AppleMaps api = new AppleMaps(token);

GeocodeInput input = GeocodeInput.builder("Jungfernstieg 1").build();
PlaceResults results = api.geocode(input);
System.out.println(results);
```

--------------------------------

### Configure Apple Maps Token (Environment Variable)

Source: https://github.com/williamagh/apple-maps-java/blob/dev/README.md

This example shows how to set the required Apple Maps authorization token using an environment variable. This token is essential for authenticating requests to the Apple Maps Server API.

```bash
export APPLE_MAPS_TOKEN="your-token"
```

--------------------------------

### Configure Apple Maps Origin (Environment Variable)

Source: https://github.com/williamagh/apple-maps-java/blob/dev/README.md

This example demonstrates setting the optional APPLE_MAPS_ORIGIN environment variable. This is used when the authorization token was generated with a specific 'origin' claim and needs to be sent in the HTTP 'Origin' header.

```bash
export APPLE_MAPS_ORIGIN="https://api.example.com"
```

--------------------------------

### Install Apple Maps Java SDK using Gradle and Maven

Source: https://context7.com/williamagh/apple-maps-java/llms.txt

Instructions for adding the Apple Maps Java SDK dependency to your project using either Gradle or Maven build tools. Ensure you are using Java 17+.

```groovy
// Gradle
dependencies {
    implementation("com.williamcallahan:apple-maps-java:0.1.4")
}
```

```xml
<!-- Maven -->
<dependency>
  <groupId>com.williamcallahan</groupId>
  <artifactId>apple-maps-java</artifactId>
  <version>0.1.4</version>
</dependency>
```

--------------------------------

### Request Travel Time Estimates with ETA API

Source: https://github.com/williamagh/apple-maps-java/blob/dev/docs/usage.md

Shows how to use the ETA API to get estimated travel times from a single origin to multiple destinations, based on current traffic conditions.

```java
RouteLocation origin = RouteLocation.fromLatitudeLongitude(53.551666, 9.9942163);
List<RouteLocation> destinations = List.of(RouteLocation.fromLatitudeLongitude(53.558, 10.0));
EtaResponse response = api.etas(EtaInput.builder(origin, destinations).build());
```

--------------------------------

### Autocomplete for Address and POI Suggestions

Source: https://github.com/williamagh/apple-maps-java/blob/dev/docs/usage.md

This code snippet illustrates how to use the autocomplete API to get a list of potential address or Point of Interest (POI) completions based on a partial user input.

```java
SearchAutocompleteResponse response = api.autocomplete(
    SearchAutocompleteInput.builder("Dorfstr").build()
);
```

--------------------------------

### Get Address and POI Completions with Apple Maps Java API

Source: https://context7.com/williamagh/apple-maps-java/llms.txt

Retrieve a list of address and POI completions for a fuzzy prompt, ideal for typeahead search interfaces. This functionality requires an Apple Maps API token and supports location hints and country filtering. It also allows for resolving completion URLs to get full place details.

```java
import com.williamcallahan.applemaps.AppleMaps;
import com.williamcallahan.applemaps.domain.model.SearchAutocompleteResponse;
import com.williamcallahan.applemaps.domain.model.SearchResponse;
import com.williamcallahan.applemaps.domain.model.UserLocation;
import com.williamcallahan.applemaps.domain.request.SearchAutocompleteInput;
import java.util.List;

AppleMaps api = new AppleMaps(System.getenv("APPLE_MAPS_TOKEN"));

// Basic autocomplete
SearchAutocompleteResponse autocomplete = api.autocomplete(
    SearchAutocompleteInput.builder("Apple Par").build()
);

// With location hint
SearchAutocompleteResponse localAutocomplete = api.autocomplete(
    SearchAutocompleteInput.builder("Dorfstr")
        .userLocation(UserLocation.fromLatitudeLongitude(53.551666, 9.9942163))
        .limitToCountries(List.of("DE"))
        .build()
);

// Access completion results
autocomplete.results().forEach(result -> {
    System.out.println("Display: " + result.displayLines());
    System.out.println("Completion URL: " + result.completionUrl());
});

// Resolve a single completion URL to get full details
SearchResponse resolved = api.resolveCompletionUrl(
    autocomplete.results().get(0).completionUrl()
);

// Resolve all completion URLs in parallel
List<SearchResponse> allResolved = api.resolveCompletionUrls(autocomplete);
allResolved.forEach(searchResponse -> {
    searchResponse.results().forEach(place -> {
        System.out.println("Resolved: " + place.name() + " - " + place.formattedAddressLines());
    });
});
```

--------------------------------

### Use Case: Find Business by Name with Autocomplete and Resolve

Source: https://github.com/williamagh/apple-maps-java/blob/dev/docs/usage.md

Illustrates a use case for finding a business by name using autocomplete for typeahead suggestions and then resolving these suggestions to get detailed place information.

```java
SearchAutocompleteResponse autocomplete = api.autocomplete(
    SearchAutocompleteInput.builder("Stripe").build()
);

List<SearchResponse> resolved = api.resolveCompletionUrls(autocomplete);
```

--------------------------------

### Get Directions using Apple Maps API in Java

Source: https://context7.com/williamagh/apple-maps-java/llms.txt

Requests routes between specified coordinates or addresses using the Apple Maps API. Supports various transport types and route options like avoiding tolls. The output includes route details such as distance and duration, along with step-by-step instructions.

```java
import com.williamcallahan.applemaps.AppleMaps;
import com.williamcallahan.applemaps.domain.model.DirectionsEndpoint;
import com.williamcallahan.applemaps.domain.model.DirectionsResponse;
import com.williamcallahan.applemaps.domain.model.DirectionsAvoid;
import com.williamcallahan.applemaps.domain.model.TransportType;
import com.williamcallahan.applemaps.domain.request.DirectionsInput;
import java.util.List;

AppleMaps api = new AppleMaps(System.getenv("APPLE_MAPS_TOKEN"));

// Directions between coordinates
DirectionsEndpoint origin = DirectionsEndpoint.fromLatitudeLongitude(53.551666, 9.9942163);
DirectionsEndpoint destination = DirectionsEndpoint.fromLatitudeLongitude(53.558, 10.0);

DirectionsResponse response = api.directions(
    DirectionsInput.builder(origin, destination).build()
);

// Directions between addresses
DirectionsEndpoint originAddress = DirectionsEndpoint.fromAddress("880 Harrison St, San Francisco, CA");
DirectionsEndpoint destAddress = DirectionsEndpoint.fromAddress("1 Infinite Loop, Cupertino, CA");

DirectionsResponse addressResponse = api.directions(
    DirectionsInput.builder(originAddress, destAddress)
        .transportType(TransportType.AUTOMOBILE)
        .avoid(List.of(DirectionsAvoid.TOLLS))
        .requestsAlternateRoutes(true)
        .language("en-US")
        .build()
);

// Access route information
response.routes().forEach(route -> {
    System.out.println("Distance: " + route.distanceMeters() + " meters");
    System.out.println("Duration: " + route.expectedTravelTimeSeconds() + " seconds");
    route.steps().forEach(step -> {
        System.out.println("  - " + step.instructions());
    });
});
```

--------------------------------

### Get ETA using Apple Maps API in Java

Source: https://context7.com/williamagh/apple-maps-java/llms.txt

Estimates travel time from a single origin to multiple destinations (up to 10) using the Apple Maps API. Supports specifying transport types like walking. The response provides estimated travel time in seconds and distance in meters for each destination.

```java
import com.williamcallahan.applemaps.AppleMaps;
import com.williamcallahan.applemaps.domain.model.EtaResponse;
import com.williamcallahan.applemaps.domain.model.RouteLocation;
import com.williamcallahan.applemaps.domain.model.TransportType;
import com.williamcallahan.applemaps.domain.request.EtaInput;
import java.util.List;

AppleMaps api = new AppleMaps(System.getenv("APPLE_MAPS_TOKEN"));

// Define origin and destinations
RouteLocation origin = RouteLocation.fromLatitudeLongitude(53.551666, 9.9942163);
List<RouteLocation> destinations = List.of(
    RouteLocation.fromLatitudeLongitude(53.558, 10.0),
    RouteLocation.fromLatitudeLongitude(53.565, 10.1),
    RouteLocation.fromLatitudeLongitude(53.570, 10.2)
);

// Request ETAs
EtaResponse response = api.etas(
    EtaInput.builder(origin, destinations).build()
);

// With transport type
EtaResponse walkingEta = api.etas(
    EtaInput.builder(origin, destinations)
        .transportType(TransportType.WALKING)
        .build()
);

// Access ETA estimates
response.etas().forEach(eta -> {
    System.out.println("Destination: " + eta.destination());
    System.out.println("Travel time: " + eta.expectedTravelTimeSeconds() + " seconds");
    System.out.println("Distance: " + eta.distanceMeters() + " meters");
});
```

--------------------------------

### Initialize Apple Maps Client in Java

Source: https://context7.com/williamagh/apple-maps-java/llms.txt

Demonstrates how to initialize the AppleMaps client, the main entry point for API operations. It covers basic initialization with a token, including an origin header, and setting a custom timeout. The client implements AutoCloseable for proper resource management.

```java
import com.williamcallahan.applemaps.AppleMaps;
import java.time.Duration;

// Basic initialization with token only
String token = System.getenv("APPLE_MAPS_TOKEN");
AppleMaps api = new AppleMaps(token);

// With origin header (required for some JWT configurations)
String origin = System.getenv("APPLE_MAPS_ORIGIN");
AppleMaps apiWithOrigin = new AppleMaps(token, origin);

// With custom timeout
AppleMaps apiWithTimeout = new AppleMaps(token, Duration.ofSeconds(30), origin);

// Always close when done (implements AutoCloseable)
try (AppleMaps client = new AppleMaps(token)) {
    // Use client
}
```

--------------------------------

### CLI Usage for Apple Maps SDK (Bash)

Source: https://context7.com/williamagh/apple-maps-java/llms.txt

Demonstrates various commands for the Apple Maps SDK's command-line interface, including geocoding, reverse geocoding, search, and autocomplete. It shows how to set the API token and origin as environment variables and pass arguments to the Gradle CLI task.

```bash
# Set token
export APPLE_MAPS_TOKEN="your-token"

# Optional: set origin if required by your JWT
export APPLE_MAPS_ORIGIN="https://api.example.com"

# Geocode
./gradlew cli --args='geocode "880 Harrison St, San Francisco, CA 94107"'
./gradlew cli --args='geocode "880 Harrison St, San Francisco, CA 94107" --json'

# Reverse geocode
./gradlew cli --args='reverse-geocode 37.7796095 -122.4016725'

# Search
./gradlew cli --args='search "coffee"'
./gradlew cli --args='search "Stripe" --limit-to-countries US'

# Autocomplete
./gradlew cli --args='autocomplete "Apple Park"'
./gradlew cli --args='autocomplete "Apple Park" --api-url'

# Resolve completion URL
./gradlew cli --args='resolve "https://maps-api.apple.com/v1/search?..." --json'

# With location bias
export APPLE_MAPS_USER_LOCATION="37.7796095,-122.4016725"
./gradlew cli --args='search "coffee"'

# Or with natural language location (adds one geocode call)
export APPLE_MAPS_USER_LOCATION_QUERY="San Francisco, CA"
./gradlew cli --args='search "coffee"'
```

--------------------------------

### Initialize Apple Maps API Client with Token and Origin

Source: https://github.com/williamagh/apple-maps-java/blob/dev/README.md

Demonstrates how to initialize the Apple Maps API client by retrieving an authentication token and an optional origin from environment variables or system properties. Handles cases where the token or origin might be missing.

```java
String token = System.getenv("APPLE_MAPS_TOKEN");
if (token == null || token.isBlank()) {
    token = System.getProperty("APPLE_MAPS_TOKEN");
}
if (token == null || token.isBlank()) {
    throw new IllegalStateException("Set APPLE_MAPS_TOKEN (env var) or APPLE_MAPS_TOKEN (system property).");
}

String origin = System.getenv("APPLE_MAPS_ORIGIN");
if (origin == null || origin.isBlank()) {
    origin = System.getProperty("APPLE_MAPS_ORIGIN");
}

AppleMaps api = (origin == null || origin.isBlank())
    ? new AppleMaps(token)
    : new AppleMaps(token, origin);
```

--------------------------------

### Run Integration Tests (Gradle)

Source: https://github.com/williamagh/apple-maps-java/blob/dev/README.md

This command executes the live integration test suite for the Apple Maps Java SDK using Gradle. It requires a valid Apple Maps token to be configured.

```bash
./gradlew testDetail --tests com.williamcallahan.applemaps.AppleMapsIT
```

--------------------------------

### Run Specific Integration Test (Gradle)

Source: https://github.com/williamagh/apple-maps-java/blob/dev/README.md

This command runs a single integration test, specifically 'geocodeHandlesPartialAndFullAddresses', using Gradle. This is useful for targeted testing of geocoding functionality.

```bash
./gradlew testDetail --tests com.williamcallahan.applemaps.AppleMapsIT.geocodeHandlesPartialAndFullAddresses
```

--------------------------------

### Run CLI Query (Gradle)

Source: https://github.com/williamagh/apple-maps-java/blob/dev/README.md

This command demonstrates how to use the SDK's command-line interface (CLI) via Gradle to perform a geocoding query. It requires the 'geocode' command and the address string as arguments.

```bash
./gradlew cli --args='geocode "880 Harrison St, San Francisco, CA 94107"'
```

--------------------------------

### Geocode Address to Coordinates using Java

Source: https://context7.com/williamagh/apple-maps-java/llms.txt

Shows how to use the geocode API to convert a street address into coordinates and a structured address. It supports basic geocoding and advanced options like adding a user location hint, limiting results to specific countries, and specifying the language. The output includes details about the found places.

```java
import com.williamcallahan.applemaps.AppleMaps;
import com.williamcallahan.applemaps.domain.model.PlaceResults;
import com.williamcallahan.applemaps.domain.model.UserLocation;
import com.williamcallahan.applemaps.domain.request.GeocodeInput;
import java.util.List;

AppleMaps api = new AppleMaps(System.getenv("APPLE_MAPS_TOKEN"));

// Basic geocode
PlaceResults results = api.geocode(
    GeocodeInput.builder("880 Harrison St, San Francisco, CA 94107").build()
);

// With location hint for better relevance
PlaceResults resultsWithHint = api.geocode(
    GeocodeInput.builder("123 Main St")
        .userLocation(UserLocation.fromLatitudeLongitude(37.7796095, -122.4016725))
        .limitToCountries(List.of("US"))
        .language("en-US")
        .build()
);

// Access results
results.results().forEach(place -> {
    System.out.println("Name: " + place.name());
    System.out.println("Coordinates: " + place.coordinate().latitude() + ", " + place.coordinate().longitude());
    System.out.println("Address: " + String.join(", ", place.formattedAddressLines()));
    System.out.println("Country: " + place.countryCode());
});

// Example output:
// {
//   "results": [{
//     "name": "880 Harrison St",
//     "coordinate": { "latitude": 37.7796095, "longitude": -122.4016725 },
//     "formattedAddressLines": ["880 Harrison St", "San Francisco, CA 94107", "United States"],
//     "structuredAddress": {
//       "locality": "San Francisco",
//       "postCode": "94107",
//       "thoroughfare": "Harrison St",
//       "subThoroughfare": "880"
//     },
//     "countryCode": "US"
//   }]
// }
```

--------------------------------

### Configure Apple Maps Token (JVM System Property)

Source: https://github.com/williamagh/apple-maps-java/blob/dev/README.md

This snippet illustrates setting the Apple Maps authorization token as a JVM system property. This method is an alternative to environment variables for configuring the SDK.

```bash
java -DAPPLE_MAPS_TOKEN="your-token" -jar your-app.jar
```

--------------------------------

### Place Lookup API

Source: https://context7.com/williamagh/apple-maps-java/llms.txt

Look up a place by its identifier or perform batch lookups for multiple places.

```APIDOC
## Place Lookup API

### Description
Look up a place by its identifier or perform batch lookups for multiple places.

### Method
GET (for single lookup), POST (for batch lookup, assumed)

### Endpoint
- Single Lookup: `/places/{placeId}` (hypothetical)
- Batch Lookup: `/places/batch` (hypothetical)

### Parameters
#### Path Parameters
- **placeId** (string) - Required - The unique identifier of the place.

#### Query Parameters
- **language** (string) - Optional - The preferred language for the response (e.g., "en-US", "de-DE").

#### Request Body (for Batch Lookup)
- **placeIds** (List<string>) - Required - A list of place identifiers to look up.
- **language** (string) - Optional - The preferred language for the response.

### Request Example
- Single Lookup:
```java
api.lookupPlace("I7AB53F714DE0BD8B", "de-DE");
```
- Batch Lookup:
```java
PlaceLookupInput.builder(List.of("placeIdA", "placeIdB", "placeIdC"))
    .language("en-US")
    .build()
```

### Response
#### Success Response (200)
- **Place** (object) - Details of a single place.
  - **name** (string) - The name of the place.
  - **formattedAddressLines** (List<string>) - The formatted address of the place.
  - **coordinate** (Coordinate) - The geographical coordinates of the place.
    - **latitude** (double) - The latitude.
    - **longitude** (double) - The longitude.
- **PlacesResponse** (object) - Response for batch lookups.
  - **places** (List<Place>) - A list of place details.

#### Response Example
```json
{
  "name": "Example Place",
  "formattedAddressLines": ["123 Main St", "Anytown, CA 90210"],
  "coordinate": {"latitude": 37.7749, "longitude": -122.4194}
}
```
```

--------------------------------

### Initialize Apple Maps SDK with Token and Origin in Java

Source: https://github.com/williamagh/apple-maps-java/blob/dev/docs/authorization.md

This Java code snippet demonstrates how to retrieve the Apple Maps authorization token and origin from environment variables or system properties. It then initializes the AppleMaps SDK with these values. The origin is optional and is used if your JWT has a specific origin claim.

```java
String token = System.getenv("APPLE_MAPS_TOKEN");
String origin = System.getenv("APPLE_MAPS_ORIGIN");
if (token == null || token.isBlank()) {
    token = System.getProperty("APPLE_MAPS_TOKEN");
}
if (origin == null || origin.isBlank()) {
    origin = System.getProperty("APPLE_MAPS_ORIGIN");
}

AppleMaps api = new AppleMaps(token, origin);
```

--------------------------------

### ETA (Estimated Time of Arrival) API

Source: https://context7.com/williamagh/apple-maps-java/llms.txt

Request travel time estimates from one origin to multiple destinations (up to 10).

```APIDOC
## ETA (Estimated Time of Arrival) API

### Description
Request travel time estimates from one origin to multiple destinations (up to 10).

### Method
POST (assumed, as it involves complex input)

### Endpoint
`/etas` (hypothetical endpoint based on usage)

### Parameters
#### Request Body
- **origin** (RouteLocation) - Required - The starting point.
- **destinations** (List<RouteLocation>) - Required - A list of destination points (up to 10).
- **transportType** (TransportType) - Optional - The mode of transport (e.g., AUTOMOBILE, WALKING).

### Request Example
```java
EtaInput.builder(origin, destinations)
    .transportType(TransportType.WALKING)
    .build()
```

### Response
#### Success Response (200)
- **etas** (List<EtaEstimate>) - A list of estimated travel times for each destination.
  - **destination** (RouteLocation) - The destination point.
  - **expectedTravelTimeSeconds** (double) - The estimated travel time in seconds.
  - **distanceMeters** (double) - The distance to the destination in meters.

#### Response Example
```json
{
  "etas": [
    {
      "destination": {"latitude": 53.558, "longitude": 10.0},
      "expectedTravelTimeSeconds": 600.0,
      "distanceMeters": 5000.0
    },
    {
      "destination": {"latitude": 53.565, "longitude": 10.1},
      "expectedTravelTimeSeconds": 900.0,
      "distanceMeters": 8000.0
    }
  ]
}
```
```

--------------------------------

### Look up Place Details using Apple Maps API in Java

Source: https://context7.com/williamagh/apple-maps-java/llms.txt

Fetches details for a specific place using its identifier or performs batch lookups for multiple places via the Apple Maps API. Supports specifying the desired language for the results. The output includes place name, formatted address, and coordinates.

```java
import com.williamcallahan.applemaps.AppleMaps;
import com.williamcallahan.applemaps.domain.model.Place;
import com.williamcallahan.applemaps.domain.model.PlacesResponse;
import com.williamcallahan.applemaps.domain.request.PlaceLookupInput;
import java.util.List;

AppleMaps api = new AppleMaps(System.getenv("APPLE_MAPS_TOKEN"));

// Single place lookup (defaults to en-US)
Place place = api.lookupPlace("I7AB53F714DE0BD8B");

// With specific language
Place placeInGerman = api.lookupPlace("I7AB53F714DE0BD8B", "de-DE");

// Batch lookup
PlacesResponse places = api.lookupPlaces(
    PlaceLookupInput.builder(List.of("placeIdA", "placeIdB", "placeIdC"))
        .language("en-US")
        .build()
);

// Access place details
System.out.println("Name: " + place.name());
System.out.println("Address: " + String.join(", ", place.formattedAddressLines()));
System.out.println("Coordinates: " + place.coordinate().latitude() + ", " + place.coordinate().longitude());
```

--------------------------------

### Use Case: Find Business by Name and City/Region with Search

Source: https://github.com/williamagh/apple-maps-java/blob/dev/docs/usage.md

Demonstrates how to use the search API when the user provides more context, such as a business name combined with a city or region, to find relevant places.

```java
SearchResponse response = api.search(
    SearchInput.builder("Stripe San Francisco").build()
);
```

--------------------------------

### Add Apple Maps Java SDK Dependency (Maven)

Source: https://github.com/williamagh/apple-maps-java/blob/dev/README.md

This snippet demonstrates how to include the Apple Maps Java SDK in a Maven project's dependencies. This SDK is designed for server-side integration with Apple Maps services.

```xml
<dependency>
  <groupId>com.williamcallahan</groupId>
  <artifactId>apple-maps-java</artifactId>
  <version>0.1.4</version>
</dependency>
```

--------------------------------

### Geocode Startup HQ Address using Apple Maps API

Source: https://github.com/williamagh/apple-maps-java/blob/dev/README.md

Shows how to perform a geocoding request for a specific address (880 Harrison St, San Francisco, CA 94107) using the initialized Apple Maps API client. The result, containing place details, is then printed to the console.

```java
PlaceResults results = api.geocode(GeocodeInput.builder("880 Harrison St, San Francisco, CA 94107").build());
System.out.println(results);
```

--------------------------------

### Use Case: Find Place by Full Street Address with Geocode

Source: https://github.com/williamagh/apple-maps-java/blob/dev/docs/usage.md

Shows how to use the geocode API when a complete street address is already known, converting it into place details.

```java
PlaceResults results = api.geocode(
    GeocodeInput.builder("880 Harrison St, San Francisco, CA 94107").build()
);
```

--------------------------------

### Reverse Geocode Coordinates to Address using Java

Source: https://context7.com/williamagh/apple-maps-java/llms.txt

Explains how to perform reverse geocoding, converting geographic coordinates (latitude and longitude) into a human-readable address. It allows specifying a language for the results and accessing structured address components like city and street.

```java
import com.williamcallahan.applemaps.AppleMaps;
import com.williamcallahan.applemaps.domain.model.PlaceResults;

AppleMaps api = new AppleMaps(System.getenv("APPLE_MAPS_TOKEN"));

// Basic reverse geocode (defaults to en-US)
PlaceResults results = api.reverseGeocode(37.7796095, -122.4016725);

// With specific language
PlaceResults resultsInGerman = api.reverseGeocode(53.551666, 9.9942163, "de-DE");

// Access the address
results.results().forEach(place -> {
    System.out.println("Address: " + String.join(", ", place.formattedAddressLines()));
    if (place.structuredAddress() != null) {
        System.out.println("City: " + place.structuredAddress().locality());
        System.out.println("Street: " + place.structuredAddress().fullThoroughfare());
    }
});
```

--------------------------------

### Directions API

Source: https://context7.com/williamagh/apple-maps-java/llms.txt

Request routes between coordinates or addresses. Supports multiple transport types and route options.

```APIDOC
## Directions API

### Description
Request routes between coordinates or addresses. Supports multiple transport types and route options.

### Method
POST (assumed, as it involves complex input)

### Endpoint
`/directions` (hypothetical endpoint based on usage)

### Parameters
#### Request Body
- **origin** (DirectionsEndpoint) - Required - The starting point for the route.
- **destination** (DirectionsEndpoint) - Required - The ending point for the route.
- **transportType** (TransportType) - Optional - The mode of transport (e.g., AUTOMOBILE, WALKING, CYCLING).
- **avoid** (List<DirectionsAvoid>) - Optional - A list of route options to avoid (e.g., TOLLS, HIGHWAYS).
- **requestsAlternateRoutes** (boolean) - Optional - Whether to request alternate routes.
- **language** (string) - Optional - The preferred language for the response (e.g., "en-US").

### Request Example
```java
DirectionsInput.builder(origin, destination)
    .transportType(TransportType.AUTOMOBILE)
    .avoid(List.of(DirectionsAvoid.TOLLS))
    .requestsAlternateRoutes(true)
    .language("en-US")
    .build()
```

### Response
#### Success Response (200)
- **routes** (List<Route>) - A list of possible routes.
  - **distanceMeters** (double) - The distance of the route in meters.
  - **expectedTravelTimeSeconds** (double) - The estimated travel time in seconds.
  - **steps** (List<Step>) - A list of turn-by-turn navigation steps.
    - **instructions** (string) - Instructions for the step.

#### Response Example
```json
{
  "routes": [
    {
      "distanceMeters": 10000.0,
      "expectedTravelTimeSeconds": 1200.0,
      "steps": [
        { "instructions": "Turn left onto Main St" },
        { "instructions": "Continue on Highway 101" }
      ]
    }
  ]
}
```
```

--------------------------------

### Look Up Place by Identifier

Source: https://github.com/williamagh/apple-maps-java/blob/dev/docs/usage.md

Demonstrates how to retrieve detailed information about a specific place using its unique place identifier. It also shows how to perform a batch lookup for multiple place IDs.

```java
Place place = api.lookupPlace("placeId");
PlacesResponse places = api.lookupPlaces(PlaceLookupInput.builder(List.of("placeIdA", "placeIdB")).build());
```

--------------------------------

### Search for Places (Addresses or POIs)

Source: https://github.com/williamagh/apple-maps-java/blob/dev/docs/usage.md

Shows how to use the search API to find specific places, which can include addresses or Points of Interest (POIs), based on a query string.

```java
SearchResponse response = api.search(
    SearchInput.builder("coffee").build()
);
```

--------------------------------

### Perform Place Searches with Apple Maps Java API

Source: https://context7.com/williamagh/apple-maps-java/llms.txt

Search for places including addresses and points of interest (POIs). This method is better suited for fuzzy queries than geocoding. It requires an Apple Maps API token for initialization and can accept various filters such as user location, country limits, POI categories, result types, language, and pagination.

```java
import com.williamcallahan.applemaps.AppleMaps;
import com.williamcallahan.applemaps.domain.model.SearchResponse;
import com.williamcallahan.applemaps.domain.model.UserLocation;
import com.williamcallahan.applemaps.domain.model.PoiCategory;
import com.williamcallahan.applemaps.domain.model.SearchResultType;
import com.williamcallahan.applemaps.domain.request.SearchInput;
import java.util.List;

AppleMaps api = new AppleMaps(System.getenv("APPLE_MAPS_TOKEN"));

// Basic search
SearchResponse response = api.search(
    SearchInput.builder("coffee").build()
);

// Search with location hint and filters
SearchResponse filteredResponse = api.search(
    SearchInput.builder("coffee shops")
        .userLocation(UserLocation.fromLatitudeLongitude(37.7796095, -122.4016725))
        .limitToCountries(List.of("US"))
        .includePoiCategories(List.of(PoiCategory.CAFE, PoiCategory.RESTAURANT))
        .resultTypeFilter(List.of(SearchResultType.POI))
        .language("en-US")
        .enablePagination(true)
        .build()
);

// Search for a business
SearchResponse businessSearch = api.search(
    SearchInput.builder("Stripe San Francisco")
        .userLocation(UserLocation.fromLatitudeLongitude(37.7796095, -122.4016725))
        .build()
);

// Access results
response.results().forEach(place -> {
    System.out.println("Name: " + place.name());
    System.out.println("Category: " + place.poiCategory());
    System.out.println("Address: " + String.join(", ", place.formattedAddressLines()));
});
```

--------------------------------

### Add Apple Maps Java SDK Dependency (Gradle)

Source: https://github.com/williamagh/apple-maps-java/blob/dev/README.md

This snippet shows how to add the Apple Maps Java SDK as a dependency in a Gradle project. It requires Java 17+ and is used for server-side map functionalities.

```groovy
dependencies {
    implementation("com.williamcallahan:apple-maps-java:0.1.4")
}
```

--------------------------------

### Improve Search Relevance with User Location Hint

Source: https://github.com/williamagh/apple-maps-java/blob/dev/docs/usage.md

Illustrates how to enhance search result quality for name-only queries by providing a geographical hint, such as the user's current location, to the search API.

```java
SearchResponse response = api.search(
    SearchInput.builder("Stripe")
        .userLocation(UserLocation.fromLatitudeLongitude(37.7796095, -122.4016725))
        .build()
);
```

--------------------------------

### Set Apple Maps Environment Variables for Local Development

Source: https://github.com/williamagh/apple-maps-java/blob/dev/docs/authorization.md

These commands set environment variables for your Apple Maps token and origin. The origin is optional and required only if your JWT has a specific origin claim. This is a common practice for configuring applications during local development.

```bash
export APPLE_MAPS_TOKEN="your-token"
export APPLE_MAPS_ORIGIN="https://api.example.com" # Required if your JWT has a specific origin
```

--------------------------------

### Reverse Geocode Coordinates to Structured Address

Source: https://github.com/williamagh/apple-maps-java/blob/dev/docs/usage.md

Demonstrates how to perform a reverse geocoding operation, transforming geographical coordinates (latitude and longitude) into a structured address.

```java
PlaceResults results = api.reverseGeocode(53.551666, 9.9942163);
```

--------------------------------

### Resolve Alternate IDs for Places (Java)

Source: https://context7.com/williamagh/apple-maps-java/llms.txt

Resolves alternate identifiers for given place IDs. This is useful for cross-referencing places across different systems. It takes a list of place IDs as input and returns a response containing the original ID and its associated alternate IDs.

```java
import com.williamcallahan.applemaps.AppleMaps;
import com.williamcallahan.applemaps.domain.model.AlternateIdsResponse;
import com.williamcallahan.applemaps.domain.request.AlternateIdsInput;
import java.util.List;

AppleMaps api = new AppleMaps(System.getenv("APPLE_MAPS_TOKEN"));

// Look up alternate IDs
AlternateIdsResponse response = api.lookupAlternateIds(
    AlternateIdsInput.builder(List.of("placeIdA", "placeIdB")).build()
);

// Access alternate IDs
response.results().forEach(entry -> {
    System.out.println("Original ID: " + entry.id());
    entry.alternateIds().forEach(altId -> {
        System.out.println("  Alternate: " + altId);
    });
});
```

--------------------------------

### Request Routes Between Coordinates with Directions API

Source: https://github.com/williamagh/apple-maps-java/blob/dev/docs/usage.md

Demonstrates how to request driving directions or routes between two specified geographical points (origin and destination) using latitude and longitude.

```java
DirectionsEndpoint origin = DirectionsEndpoint.fromLatitudeLongitude(53.551666, 9.9942163);
DirectionsEndpoint destination = DirectionsEndpoint.fromLatitudeLongitude(53.558, 10.0);
DirectionsResponse response = api.directions(DirectionsInput.builder(origin, destination).build());
```

--------------------------------

### Geocode Address to Coordinates and Structured Address

Source: https://github.com/williamagh/apple-maps-java/blob/dev/docs/usage.md

This snippet shows how to use the geocode API to convert a street address into geographical coordinates and a structured address format.

```java
PlaceResults results = api.geocode(
    GeocodeInput.builder("Jungfernstieg 1").build()
);
```

--------------------------------

### Resolve Alternate Identifiers for Places

Source: https://github.com/williamagh/apple-maps-java/blob/dev/docs/usage.md

This snippet shows how to use the API to resolve various alternate identifiers associated with places, potentially mapping them to standard Apple Maps place IDs.

```java
AlternateIdsResponse response = api.lookupAlternateIds(
    AlternateIdsInput.builder(List.of("idA", "idB")).build()
);
```
Tokens:
Raw