Build shareable Apple Maps Guides from a CSV of places — from the command line.
Apple offers no public API to create Maps Guides. But a shared guide is
entirely self-contained in its URL (a protobuf blob — Apple stores nothing
server-side), so we can construct that URL ourselves. Give this tool a list of
places and it produces a maps.apple.com link that opens as a real guide.
your-places.csv ──► resolve each place ──► https://maps.apple.com/guides?user=…
(rich cards or pins) tap on iPhone → opens in Maps → Save
⚠️ This is an unofficial project, not affiliated with or endorsed by Apple. It relies on an undocumented URL format that Apple could change at any time. Great for personal use and tinkering; don't build anything load-bearing on it.
Each place becomes one of two things:
- Rich place card — linked to Apple's POI database (photos, hours, reviews). Requires Apple Maps Server API credentials (Apple Developer Program account).
- Raw pin — just a name + coordinates. No credentials needed; coordinates come from free OpenStreetMap geocoding. Used as a fallback.
You can run in pure raw-pin mode with zero setup, then add credentials later to upgrade to rich cards.
- Node.js ≥ 20.6 (uses the built-in
process.loadEnvFile). Check:node -v. - For rich cards only: an Apple Developer Program account, to create a Maps ID + key and call the Apple Maps Server API. Raw-pin mode needs no account.
git clone https://github.com/ClemannD/apple-maps-guide-bridge.git
cd apple-maps-guide-bridge
npm installnpm run guide -- \
--csv examples/paris-food.csv \
--name "Paris Food" \
--region "Paris, France"It prints a https://maps.apple.com/guides?user=… link. AirDrop or iMessage
it to your iPhone and tap it — it opens in the Maps app, where you tap Save
to add it to My Guides. (Clicking on a Mac opens the web version of Maps.)
To resolve places to real Apple place cards, create a MapKit key. This is a one-time setup in your Apple Developer Program account.
-
Team ID — on the Membership page. A 10-character string.
-
Create a Maps ID (required before the key — the Maps capability has nothing to attach to without it). Go to Identifiers → + → Maps IDs → Continue. Give it a description and an identifier like
maps.com.yourname.guidebridge→ Register. -
Create the key — go to Keys → + → name it → tick Maps → click Configure → select the Maps ID from step 2 → Save → Continue → Register.
-
Download the key — you get
AuthKey_XXXXXXXXXX.p8. You can only download it once. Note the 10-character Key ID shown on the page. -
Configure the project:
mkdir -p secrets mv ~/Downloads/AuthKey_*.p8 secrets/ # gitignored cp .env.example .env
Edit
.env:APPLE_MAPS_TEAM_ID=YOURTEAMID APPLE_MAPS_KEY_ID=YOURKEYID APPLE_MAPS_KEY_PATH=./secrets/AuthKey_YOURKEYID.p8 # or, instead of a file: # APPLE_MAPS_KEY_PEM="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----" -
Run — with
.envpresent, the tool switches to rich mode automatically:npm run guide -- --csv examples/paris-food.csv --name "Paris Food" \ --region "Paris, France" --near "48.8566,2.3522" --country FR \ --note-col "Type,Lunch/dinn"
Anything the Server API can't find automatically falls back to a raw pin, so every locatable row still ends up in the guide.
Quota: 25,000 calls/day/team, shared with MapKit JS. One call per place.
🔒
.env,secrets/, and*.p8are gitignored. Never commit your key.
npm run guide -- --csv <file> --name "<guide title>" [options]
| Option | Description |
|---|---|
--csv <path> |
CSV file with a header row. (required) |
--name "<title>" |
Guide title. (required) |
--region "<text>" |
Appended to every search, e.g. "Paris, France". Strongly recommended. |
--near "<lat,lng>" |
Bias search/geocoding toward this point (a city center). |
--country <ISO2> |
Restrict Server API search to a country, e.g. FR. |
--name-col <header> |
Column holding the place name. Default: auto-detect (name/place/title/…, else first column). |
--note-col <h1,h2> |
Column(s) joined as a raw-pin subtitle. |
--out <path> |
Also write the guide URL to a file. |
--raw |
Force raw pins even if credentials are present. |
--limit <n> |
Only process the first n rows (handy for testing). |
The only requirement is a header row with a column of place names. The tool
reads that one column and ignores the rest. See examples/minimal.csv:
name
Blue Bottle Coffee
Ferry Buildingnpm run guide -- --csv examples/minimal.csv --name "SF Faves" --region "San Francisco, CA"The name column is auto-detected (a header named name/place/title/… or the
first column); override with --name-col. Extra columns are only used if you
point --note-col at them. Location context (--region, --near, --country)
comes from flags, not the CSV — so the same tool works for any city or list.
examples/paris-food.csv shows a richer file with extra columns.
Your data won't be in this exact shape, and that's fine. Two ways to bridge it:
-
Reshape your data to a one-column CSV of names (any spreadsheet exports CSV; delete the other columns). This needs no code changes.
-
Have an AI adjust the tool for your input. Paste
src/cli-guide.tsand a few rows of your data, then ask, for example:"Here's my data
<paste>and this script<paste src/cli-guide.ts>. Modify the script to read my format — my place names are in the<column/field>column. Keep everything else the same."Or to pull names out of messier data:
"Turn this into a CSV with a single
namecolumn, one place per row:<paste your list / JSON / notes>"
npm run decode -- '<any apple maps guide url>' # inspect a guide as JSON
npm run build-json -- <file.json> # build from a JSON place list
npm run typecheck # tsc --noEmitA shared guide link like https://maps.apple/ug/<id> redirects to a
self-contained URL:
https://maps.apple.com/guides?user=<urlencode(base64(Guide))>
The ?user= blob is a protobuf:
message Guide {
string name = 1;
repeated Place place = 2;
}
message Place {
int32 lsp = 1; // constant 9902 for Apple POI references
uint64 appleMapsId = 2; // the place's numeric id ("auid")
string address = 3; // \
Coordinates coords = 4; // } raw pin (name + address + coordinates)
string name = 5; // /
}
message Coordinates { double latitude = 1; double longitude = 2; }Rich cards reference a place by appleMapsId; raw pins carry their own
name/address/coords.
The neat part: the Apple Maps Server API returns a hex Place ID like
I265FBD065AC8F645, while the guide protobuf wants a numeric appleMapsId.
They're the same 64-bit value — the hex ID is just "I" + hex(appleMapsId) —
so we convert with parseInt(id.slice(1), 16) and stay entirely on the
official API. (See src/place-id.ts.)
src/protobuf.ts minimal protobuf wire codec (zero deps, BigInt varints)
src/guide.ts Guide <-> share-URL encode/decode
src/place-id.ts hex Place ID <-> numeric appleMapsId
src/maps.ts Apple Maps Server API client (ES256 JWT, token, search)
src/geocode.ts OpenStreetMap/Nominatim geocoder (raw-pin fallback)
src/csv.ts CSV parser (handles multi-line quoted fields)
src/cli-guide.ts the main command
- Not an Apple API. The URL format is undocumented and may break.
- Opening the guide is user-mediated — the link opens Maps; the user taps Save. There's no way to write directly into someone's guide library.
- Long links. A big guide makes a multi-kilobyte URL (too long for a QR code). AirDrop/Messages is the practical way to get it onto a phone.
- Geocoding uses Nominatim — rate-limited to 1 req/sec and cached locally. Be a good citizen.
- Server API use is subject to Apple's terms.
MIT — see LICENSE.
