Skip to main content
The AppleMaps class is the single entry point for all Apple Maps Server API operations. It implements AutoCloseable, so you can use it in a try-with-resources block to release the underlying HTTP client when you are done. 
try (AppleMaps api = new AppleMaps(System.getenv("APPLE_MAPS_TOKEN"))) {
    PlaceResults results = api.geocode(GeocodeInput.builder("One Apple Park Way, Cupertino").build());
}
For test doubles and custom gateway implementations, AppleMaps delegates to an AppleMapsGateway. See Custom Gateway below.

​
Constructors

public AppleMaps(String authToken)
Creates a client with a 10-second default timeout and no Origin header. This is the simplest constructor for most server-side use cases.
ParameterTypeDescription
authTokenStringLong-lived Apple Maps authorization token (JWT)
public AppleMaps(String authToken, String origin)
Creates a client with a 10-second default timeout and the specified Origin header value. Required when your JWT was issued with an origin claim.
ParameterTypeDescription
authTokenStringLong-lived Apple Maps authorization token (JWT)
originStringValue sent as the HTTP Origin header (for example, https://api.example.com)
public AppleMaps(String authToken, Duration timeout)
Creates a client with a custom request timeout and no Origin header.
ParameterTypeDescription
authTokenStringLong-lived Apple Maps authorization token (JWT)
timeoutDurationPer-request timeout; must not be null
public AppleMaps(String authToken, Duration timeout, String origin)
Creates a client with both a custom timeout and an Origin header.
ParameterTypeDescription
authTokenStringLong-lived Apple Maps authorization token (JWT)
timeoutDurationPer-request timeout; must not be null
originStringValue sent as the HTTP Origin header, or null to omit
public AppleMaps(AppleMapsGateway gateway)
Creates a client backed by a custom AppleMapsGateway implementation. Use this constructor to inject a test stub, mock, or alternative HTTP backend.
ParameterTypeDescription
gatewayAppleMapsGatewayCustom gateway; must not be null

​
Geocoding

geocode

public PlaceResults geocode(GeocodeInput input)
Converts a text address into geographic coordinates. Returns a PlaceResults containing zero or more Place records.See GeocodeInput for all available options.

reverseGeocode (default language)

public PlaceResults reverseGeocode(double latitude, double longitude)
Converts a latitude/longitude coordinate pair into a place address using en-US as the response language.
public PlaceResults reverseGeocode(double latitude, double longitude, String language)
Converts a latitude/longitude coordinate pair into a place address using the specified BCP 47 language tag. If language is null or blank, the SDK falls back to en-US.
ParameterTypeDescription
latitudedoubleLatitude in decimal degrees
longitudedoubleLongitude in decimal degrees
languageStringBCP 47 language tag, or null to use en-US

search

public SearchResponse search(SearchInput input)
Searches for places matching a text query. Returns a SearchResponse with an array of SearchResponsePlace records and an optional display region.See SearchInput for filtering and pagination options.

autocomplete

public SearchAutocompleteResponse autocomplete(SearchAutocompleteInput input)
Returns search suggestions for a partial query. Each suggestion carries a completionUrl that you resolve with resolveCompletionUrl.See SearchAutocompleteInput.

​
Resolving completion URLs

After calling autocomplete, use one of two methods to fetch full search results for each suggestion: 
// Resolve a single completion URL
public SearchResponse resolveCompletionUrl(String completionUrl)

// Resolve all completion URLs from a response (concurrent, same order)
public List<SearchResponse> resolveCompletionUrls(SearchAutocompleteResponse response)

// Resolve from a raw list of AutocompleteResult
public List<SearchResponse> resolveCompletionUrls(List<AutocompleteResult> results)
resolveCompletionUrls fires all requests concurrently using CompletableFuture and returns results in the same order as the input list. Each call counts against your daily quota — see Quota.

​
Routing

directions

public DirectionsResponse directions(DirectionsInput input)
Returns turn-by-turn directions between an origin and a destination. The response includes routes, steps, and step path coordinates.See DirectionsInput.

etas

public EtaResponse etas(EtaInput input)
Returns estimated travel times from one origin to up to 10 destinations. Returns an EtaResponse with one EtaEstimate per destination.See EtaInput.

​
Place Lookup

lookupPlace (default language)

public Place lookupPlace(String placeId)
Fetches a single place by its Apple Maps place identifier using en-US as the response language.

lookupPlace (with language)

public Place lookupPlace(String placeId, String language)
Fetches a single place by ID with a specified BCP 47 language tag. If language is null or blank, falls back to en-US.

lookupPlaces

public PlacesResponse lookupPlaces(PlaceLookupInput input)
Fetches multiple places in a single request. Returns a PlacesResponse with both successful results and per-ID errors.See PlaceLookupInput.

lookupAlternateIds

public AlternateIdsResponse lookupAlternateIds(AlternateIdsInput input)
Resolves alternate place identifiers for one or more place IDs. Returns an AlternateIdsResponse.See AlternateIdsInput.

​
Custom Gateway

AppleMapsGateway is a domain port interface in com.williamcallahan.applemaps.domain.port. You can implement it to provide a test stub, a caching layer, or an alternative HTTP backend: 
import com.williamcallahan.applemaps.domain.port.AppleMapsGateway;

public class StubGateway implements AppleMapsGateway {
    @Override
    public PlaceResults geocode(GeocodeInput input) {
        return new PlaceResults(List.of(/* fixed test data */));
    }
    // implement remaining methods ...
}

AppleMaps api = new AppleMaps(new StubGateway());
The default void close() method on the interface is a no-op, so you only need to override it if your implementation owns closeable resources.