Skip to main content
This guide walks you through adding Apple Maps Java to an existing JVM project and making your first geocode call.

​
Prerequisites

  • JDK 17 or later
  • An Apple Developer Program membership
  • A long-lived Apple Maps authorization token — if you don’t have one yet, see Authorization
1

Add the dependency

Add the apple-maps-java artifact to your build file.
dependencies {
    implementation("com.williamcallahan:apple-maps-java:0.1.5")
}
The artifact is published to Maven Central — no extra repository configuration required.
2

Get an authorization token

Apple Maps Java requires a long-lived JWT issued from the Apple Developer portal. You’ll need to:
  1. Create a Maps Identifier in your Apple Developer account.
  2. Generate a private key associated with that identifier.
  3. Use the private key to sign a JWT with the required claims.
For the full token creation walkthrough, see Authorization.
3

Set the APPLE_MAPS_TOKEN environment variable

Export your token as an environment variable before running your application.
export APPLE_MAPS_TOKEN="your-long-lived-jwt"
Alternatively, pass it as a JVM system property:
java -DAPPLE_MAPS_TOKEN="your-long-lived-jwt" -jar your-app.jar
If your JWT was generated with a specific origin claim, also export APPLE_MAPS_ORIGIN with the same origin value (for example https://api.example.com). The SDK sends this as the HTTP Origin header.
4

Initialize the AppleMaps client

Read the token from the environment and construct an AppleMaps instance.
import com.williamcallahan.applemaps.AppleMaps;

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 as an environment variable or JVM system property."
    );
}

AppleMaps api = new AppleMaps(token);
If you also need to pass an origin:
String origin = System.getenv("APPLE_MAPS_ORIGIN");
AppleMaps api = (origin == null || origin.isBlank())
    ? new AppleMaps(token)
    : new AppleMaps(token, origin);
5

Make your first geocode call

Geocode a street address and print the result.
import com.williamcallahan.applemaps.AppleMaps;
import com.williamcallahan.applemaps.domain.model.PlaceResults;
import com.williamcallahan.applemaps.domain.request.GeocodeInput;

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 as an environment variable or JVM 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);

PlaceResults results = api.geocode(
    GeocodeInput.builder("880 Harrison St, San Francisco, CA 94107").build()
);
System.out.println(results);
A successful response looks like this:
{
  "results": [
    {
      "name": "880 Harrison St",
      "coordinate": {
        "latitude": 37.7796095,
        "longitude": -122.4016725
      },
      "formattedAddressLines": [
        "880 Harrison St",
        "San Francisco, CA  94107",
        "United States"
      ],
      "structuredAddress": {
        "administrativeArea": "California",
        "administrativeAreaCode": "CA",
        "locality": "San Francisco",
        "postCode": "94107",
        "subLocality": "Yerba Buena",
        "thoroughfare": "Harrison St",
        "subThoroughfare": "880",
        "fullThoroughfare": "880 Harrison St",
        "dependentLocalities": [
          "Yerba Buena"
        ]
      },
      "countryCode": "US"
    }
  ]
}

​
What’s next

Now that you have a working geocode call, explore the rest of the SDK:

Installation reference

Full installation options including snapshot builds.

Authorization

How to create and configure your Apple Maps token.

Geocoding guide

Geocode, reverse geocode, and understand results.

Search & Autocomplete

Find businesses and POIs with typeahead support.