A modern, type-safe Python client for the Apple Maps Server API.
There's no python library for the Apple Maps API. Maps is super cheap compared to all of the alternatives, so with AI I figured it wouldn't be too hard to build a client library.
The goal of this library is to provide similar functionality to the radar python client. Here's the main goals:
- Automatic JWT Management: Handles signing and periodic refresh of Apple's ES256 tokens.
- Type-Safe: Built with Pydantic models for all API responses, giving you excellent IDE support.
- Resilient: Automatic retries with exponential backoff for transient network and server errors.
- Modern: Uses
httpxfor synchronous requests, with a structure that's ready for future async support.
See examples/full-stack/ for a runnable FastAPI + React/MapKit JS app that demonstrates:
- Minting MapKit JS tokens server-side (
create_mapkit_token) and rendering an interactive map - Address autocomplete via this client, proxied through a small FastAPI API
uv add apple-maps-apiYou'll need your Team ID, Key ID, and the private key from your Apple Developer account.
from apple_maps_api import AppleMapsClient
client = AppleMapsClient(
team_id="YOUR_TEAM_ID",
key_id="YOUR_KEY_ID",
private_key="""-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----"""
)Or load credentials from environment variables:
export APPLE_MAPS_TEAM_ID=...
export APPLE_MAPS_KEY_ID=...
export APPLE_MAPS_P8_KEY=... # PEM or raw base64 DER
# optional: export APPLE_MAPS_ORIGIN=https://example.comAnd then you can source the vars from the env:
from apple_maps_api import AppleMapsClient
client = AppleMapsClient.from_env()MapKit JS needs a signed JWT (not the Server API access token). Use create_mapkit_token():
from apple_maps_api import AppleMapsClient
client = AppleMapsClient.from_env()
# default TTL is 1 hour — fine for production token endpoints
token = client.create_mapkit_token()
# long-lived token for local FE work (e.g. 30 days)
token = client.create_mapkit_token(ttl_seconds=30 * 24 * 60 * 60)
print(token)Paste the printed JWT into MapKit JS / mapkit-react during development so you do not need a backend token endpoint.
Optional domain lock: set origin on the client (or APPLE_MAPS_ORIGIN) so the token only works from that origin (e.g. http://localhost:5173). Omit origin for unrestricted local play.
Do not ship long-lived tokens in production frontend builds — mint short-lived tokens from your server instead (see examples/full-stack/).
Convert an address string to coordinates:
results = client.geocode("1 Apple Park Way, Cupertino, CA")
for place in results.results:
print(f"{place.name}: {place.coordinate.latitude}, {place.coordinate.longitude}")
# place.name => "1 Apple Park Way"
# place.coordinate.latitude => 37.334859
# place.coordinate.longitude => -122.0090403
# place.formattedAddressLines => ["1 Apple Park Way", "Cupertino, CA 95014", "United States"]
# place.structuredAddress.locality => "Cupertino"Convert coordinates back to a structured address:
results = client.reverse_geocode(lat=37.3346, lng=-122.0090)
if results.results:
print(results.results[0].formattedAddressLines)
# place.formattedAddressLines => ["Apple Park", "1 Apple Park Way", "Cupertino, CA 95014", "United States"]
# place.structuredAddress.locality => "Cupertino"
# place.structuredAddress.postCode => "95014"Search for points of interest near a location:
results = client.search("pizza", lat=37.3346, lng=-122.0090)
for place in results.results:
print(f"{place.name} - {place.formattedAddressLines}")
# results.results[0].name => "Pizza My Heart"
# results.results[0].formattedAddressLines => ["19409 Stevens Creek Blvd", "Cupertino, CA 95014", "United States"]
# results.results[1].name => "Mountain Mike's Pizza"
# results.results[2].name => "Pizz'a Chicago"Provide search completions for a partial query and filter by country:
results = client.autocomplete(
"1 Apple Park",
limit_to_countries=["US"],
lat=37.3346,
lng=-122.0090,
)
for completion in results.results:
print(completion.displayLines)
# results.results[0].displayLines => ["1 Apple Park Way", "Cupertino, CA, United States"]
# results.results[1].displayLines => ["1 Apple Hill Dr", "Natick, MA, United States"]
# results.results[0].completionUrl => "/v1/search?q=1%20Apple%20Park%20Way..."Multi-value filters (countries, categories, result types, …) accept a list; a single string still works.
Always pass lat/lng. Autocomplete ranking is heavily biased by location — without it you get scattered results across the country for common street names. For server-side autocomplete, resolve the user's approximate location from their IP:
- Get the client public IP with fastapi-ipware
- Look up lat/lng via observabilitystack/geoip-api (
ghcr.io/observabilitystack/geoip-api:latest)
Search, autocomplete, and geocode share the same location-hint shape:
lat/lng— app-defined search bias (ApplesearchLocation). Prefer nearby results around this map point.user_lat/user_lng— the user's current position (AppleuserLocation). Used for ranking; iflat/lngare omitted, some endpoints may fall back to this.search_region— bounding-box hint as aMapRegion(ApplesearchRegion).search_region_priority—SearchRegionPriority.defaultor.required(or the strings"default"/"required").
from apple_maps_api import MapRegion, SearchRegionPriority
region = MapRegion(
northLatitude=37.5,
eastLongitude=-121.7,
southLatitude=37.1,
westLongitude=-122.5,
)
results = client.search(
"coffee",
lat=37.3346,
lng=-122.0090,
user_lat=37.3317,
user_lng=-122.0307,
search_region=region,
search_region_priority=SearchRegionPriority.required,
categories=["Cafe"],
limit_to_countries=["US"],
)The library includes high-level helpers for common geocoding operations:
from apple_maps_api import geocode_postal_code, geocode_coordinates
# Geocode a postal code
result = geocode_postal_code(client, postal_code="95014", country="US")
# result.lat => 37.2895111
# result.lon => -122.0811912
# result.city => "Cupertino"
# result.state_code => "CA"
# result.postal_code => "95014"
# result.formatted_address => "Cupertino, CA 95014, United States"
# Reverse geocode coordinates
result = geocode_coordinates(client, lat=37.3346, lon=-122.0090)
# result.address1 => "1 Apple Park Way"
# result.postal_code => "95014"
# result.city => "Cupertino"
# result.state_code => "CA"
# result.formatted_address => "Apple Park, 1 Apple Park Way, Cupertino, CA 95014, United States"These examples show the real data shapes returned by the Apple Maps API for common operations.
Note on city names: Apple Maps uses its own administrative boundaries. The
cityfield onGeocodeResultmaps tostructuredAddress.locality, which may differ from the colloquial city name. For example, postal code90210returnscity="Los Angeles"even though the formatted address reads"Beverly Hills"— Beverly Hills is an independent city but Apple Maps assigns it to the LA locality.
result = geocode_postal_code(client, postal_code="10001")
# result.lat => 40.7504876
# result.lon => -74.0025705
# result.city => "New York"
# result.state_code => "NY"
# result.postal_code => "10001"
# result.formatted_address => "New York, NY 10001, United States"result = geocode_postal_code(client, postal_code="90210")
# result.lat => 34.1025226
# result.lon => -118.4167959
# result.city => "Los Angeles" # NOT "Beverly Hills"
# result.state_code => "CA"
# result.postal_code => "90210"
# result.formatted_address => "Beverly Hills, CA 90210, United States"# Times Square, NYC
result = geocode_coordinates(client, lat=40.7589, lon=-73.9851)
# result.address1 => "1552–1568 Broadway"
# result.postal_code => "10036"
# result.city => "New York"
# result.state_code => "NY"
# result.formatted_address => "Times Square, 1552–1568 Broadway, New York, NY 10036, United States"Apple Park, Cupertino CA (37.3346, -122.0090):
place = client.reverse_geocode(lat=37.3346, lng=-122.0090).results[0]
# place.name => "Apple Park"
# place.formattedAddressLines => ["Apple Park", "1 Apple Park Way", "Cupertino, CA 95014", "United States"]
# place.structuredAddress.administrativeArea => "California"
# place.structuredAddress.administrativeAreaCode => "CA"
# place.structuredAddress.subAdministrativeArea => None
# place.structuredAddress.locality => "Cupertino"
# place.structuredAddress.subLocality => None
# place.structuredAddress.fullThoroughfare => "1 Apple Park Way"
# place.structuredAddress.thoroughfare => "Apple Park Way"
# place.structuredAddress.subThoroughfare => "1"
# place.structuredAddress.postCode => "95014"
# place.structuredAddress.areasOfInterest => ["Apple Park"]
# place.structuredAddress.dependentLocalities => NoneTimes Square, NYC (40.7589, -73.9851):
place = client.reverse_geocode(lat=40.7589, lng=-73.9851).results[0]
# place.name => "Times Square"
# place.formattedAddressLines => ["Times Square", "1552–1568 Broadway", "New York, NY 10036", "United States"]
# place.structuredAddress.administrativeArea => "New York"
# place.structuredAddress.administrativeAreaCode => "NY"
# place.structuredAddress.subAdministrativeArea => None
# place.structuredAddress.locality => "New York"
# place.structuredAddress.subLocality => "Manhattan"
# place.structuredAddress.fullThoroughfare => "1552–1568 Broadway"
# place.structuredAddress.thoroughfare => "Broadway"
# place.structuredAddress.subThoroughfare => "1552–1568"
# place.structuredAddress.postCode => "10036"
# place.structuredAddress.areasOfInterest => ["Times Square", "Manhattan"]
# place.structuredAddress.dependentLocalities => ["Broadway", "Times Square", "Theater District", "Midtown Manhattan", "Midtown", "North Hudson"]Beverly Hills, CA (34.1025226, -118.4167959) — note locality vs formatted address mismatch:
place = client.reverse_geocode(lat=34.1025226, lng=-118.4167959).results[0]
# place.name => "1731 N Franklin Canyon Dr"
# place.formattedAddressLines => ["1731 N Franklin Canyon Dr", "Beverly Hills, CA 90210", "United States"]
# place.structuredAddress.administrativeArea => "California"
# place.structuredAddress.administrativeAreaCode => "CA"
# place.structuredAddress.subAdministrativeArea => None
# place.structuredAddress.locality => "Los Angeles" # NOT "Beverly Hills"
# place.structuredAddress.subLocality => "Beverly Crest"
# place.structuredAddress.fullThoroughfare => "1731 N Franklin Canyon Dr"
# place.structuredAddress.thoroughfare => "N Franklin Canyon Dr"
# place.structuredAddress.subThoroughfare => "1731"
# place.structuredAddress.postCode => "90210"
# place.structuredAddress.areasOfInterest => None
# place.structuredAddress.dependentLocalities => ["Beverly Crest"]- fastapi-ipware — client IP extraction for FastAPI (useful for lat/lng hinting via GeoIP)
- mapkit-react — React bindings for MapKit JS (used in the full-stack example)
This project was created from iloveitaly/python-package-template
