These variables are read by the SDK at runtime. You can supply them as OS environment variables, JVM system properties, or (for local development) via a .env file.
HTTP Origin header value. Required only if your JWT was generated with a specific origin claim. Must match the origin claim exactly (for example, https://api.example.com).
The SDK checks the environment variable first, then falls back to the JVM system property of the same name. For example, if APPLE_MAPS_TOKEN is not set as an env var, the SDK reads -DAPPLE_MAPS_TOKEN from system properties.
For local development, you can copy .env-example to .env and set your token there:
cp .env-example .env
Then edit .env:
APPLE_MAPS_TOKEN=your-long-lived-jwt
The Gradle build loads .env into JVM system properties automatically, which is convenient for running integration tests locally without exporting environment variables. The .env file is ignored by git, so your token stays out of version control.
Never commit your .env file or paste your token directly into source code. Treat the authorization token as a secret — anyone who has it can make Apple Maps Server API calls against your quota.
In CI, set APPLE_MAPS_TOKEN as a secret environment variable in your CI provider rather than using a .env file.
The following variables are read by the included CLI tool only. They are not part of the SDK and have no effect when using AppleMaps programmatically in your application.
Variable
Description
APPLE_MAPS_USER_LOCATION
Default location bias for CLI commands, as <latitude>,<longitude> (for example, 37.7796095,-122.4016725).
APPLE_MAPS_USER_LOCATION_QUERY
Natural-language location bias for CLI commands (for example, "San Francisco, CA"). The CLI geocodes this value once per run to produce a userLocation hint. Sets one extra API call.
These provide a convenient default for commands like search and autocomplete when you do not pass --user-location explicitly on the command line.