The SDK ships with a CLI that lets you call every supported Apple Maps Server API operation from your terminal — useful for exploring the API, debugging geocoding results, or scripting location queries.
Prerequisites
Set APPLE_MAPS_TOKEN as an environment variable before running any command. The CLI reads it from the environment (or from a .env file if you use the Gradle integration).
export APPLE_MAPS_TOKEN="your-token-here"
Optionally set APPLE_MAPS_ORIGIN if your JWT has an origin claim that must match the request origin (for example, https://api.example.com).
Running commands
All commands run through Gradle using the cli task. Pass the command and its arguments via --args:
./gradlew cli --args='<command> [args] [flags]'
Commands
geocode
Forward-geocode an address to coordinates and place details.
./gradlew cli --args='geocode "880 Harrison St, San Francisco, CA 94107"'
--json to receive the raw API payload as pretty-printed JSON:
./gradlew cli --args='geocode "880 Harrison St, San Francisco, CA 94107" --json'
| Flag | Description |
|---|
--json | Print the raw API response as pretty JSON instead of the default one-line format |
--lang <bcp47> | Language for results (e.g. en-US, fr-FR). Defaults to en-US |
--user-location <lat> <lon> | Coordinate hint to bias results toward a location |
--limit-to-countries <code> | Comma-separated ISO 3166-1 alpha-2 country codes (e.g. US,CA) |
reverse-geocode
Convert a coordinate pair to a human-readable address.
./gradlew cli --args='reverse-geocode 37.7796095 -122.4016725'
| Flag | Description |
|---|
--json | Print raw API response as pretty JSON |
--lang <bcp47> | Language for results |
search
Search for places by query string.
./gradlew cli --args='search "coffee"'
./gradlew cli --args='search "coffee" --limit-to-countries US'
./gradlew cli --args='search "coffee" --user-location 37.7796095 -122.4016725'
| Flag | Description |
|---|
--json | Print raw API response as pretty JSON |
--lang <bcp47> | Language for results |
--user-location <lat> <lon> | Coordinate hint to bias results |
--limit-to-countries <code> | Comma-separated ISO 3166-1 alpha-2 country codes |
autocomplete
Get completion suggestions for a partial query. By default, each result prints an Apple Maps web URL you can open in a browser.
./gradlew cli --args='autocomplete "Apple Park"'
resolve):
./gradlew cli --args='autocomplete "Apple Park" --api-url'
| Flag | Description |
|---|
--api-url | Print the Apple Maps Server API completion URL instead of the Apple Maps web URL |
--json | Print raw API response as pretty JSON |
--lang <bcp47> | Language for results |
--user-location <lat> <lon> | Coordinate hint to bias results |
--limit-to-countries <code> | Comma-separated ISO 3166-1 alpha-2 country codes |
resolve
Resolve an autocomplete completion URL to full place results.
./gradlew cli --args='resolve "https://maps-api.apple.com/v1/search?..." --json'
| Flag | Description |
|---|
--json | Print raw API response as pretty JSON |
Location bias
For geocode, search, and autocomplete, you can provide a location hint to bias results toward a specific area. There are three ways to do this.
Coordinate env var
Natural-language env var
Inline flag
Set APPLE_MAPS_USER_LOCATION as <latitude>,<longitude>. This applies to all commands in the current shell session without repeating the flag.export APPLE_MAPS_USER_LOCATION="37.7796095,-122.4016725"
./gradlew cli --args='search "coffee"'
Set APPLE_MAPS_USER_LOCATION_QUERY to a plain-text location name. The CLI geocodes it once at startup (one extra API call per run) and uses the first result as the location hint.export APPLE_MAPS_USER_LOCATION_QUERY="San Francisco, CA"
./gradlew cli --args='search "coffee"'
Pass --user-location <lat> <lon> directly on any individual command:./gradlew cli --args='search "coffee" --user-location 37.7796095 -122.4016725'
If both APPLE_MAPS_USER_LOCATION and --user-location are supplied, the inline flag takes precedence. APPLE_MAPS_USER_LOCATION_QUERY is only consulted when no coordinate location has been provided.
<name> — <formatted address lines>
Stripe — 510 Townsend St, San Francisco, CA 94103, United States
--json
The raw API payload is printed as pretty-printed JSON, identical to what the Apple Maps Server API returns.
Autocomplete without --api-url
Each result is printed as:
<display lines> — <Apple Maps web URL>
--api-url to replace the web URL with the Apple Maps Server API completion URL, which you can then pass to resolve.