Skip to content

About

Build shareable Apple Maps Guides from a CSV of places, from the command line.

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

12 Commits

Folders and files

Repository files navigation

apple-maps-guide-bridge

Build shareable Apple Maps Guides from a CSV of places — from the command line.

A "Paris Food" guide with 63 places generated by this tool, shown in Apple Maps

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.


What you get

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.


Prerequisites

  • 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.

Install

git clone https://github.com/ClemannD/apple-maps-guide-bridge.git
cd apple-maps-guide-bridge
npm install

Quick start (no API key — raw pins)

npm 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.)


Rich cards setup (Apple Maps Server API)

To resolve places to real Apple place cards, create a MapKit key. This is a one-time setup in your Apple Developer Program account.

  1. Team ID — on the Membership page. A 10-character string.

  2. 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.

  3. Create the key — go to Keys → + → name it → tick Maps → click Configure → select the Maps ID from step 2 → Save → Continue → Register.

  4. Download the key — you get AuthKey_XXXXXXXXXX.p8. You can only download it once. Note the 10-character Key ID shown on the page.

  5. 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-----"
    
  6. Run — with .env present, 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 *.p8 are gitignored. Never commit your key.


Usage

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).

CSV format

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 Building
npm 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.

Adapting it to your data

Your data won't be in this exact shape, and that's fine. Two ways to bridge it:

  1. Reshape your data to a one-column CSV of names (any spreadsheet exports CSV; delete the other columns). This needs no code changes.

  2. Have an AI adjust the tool for your input. Paste src/cli-guide.ts and 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 name column, one place per row: <paste your list / JSON / notes>"

Other commands

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 --noEmit

How it works

A 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.)

Project layout

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

Limitations & etiquette

  • 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.

License

MIT — see LICENSE.

About

Build shareable Apple Maps Guides from a CSV of places, from the command line.

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages