SHORTCUT.md

# 📲 Add places from your phone — the iOS Shortcut

Share an Instagram reel from your phone and have the place land on your map
automatically — no copy-paste, no export, no Google account.

## Why a Shortcut (and why you build it yourself)

Instagram blocks requests from cloud servers, so the hosted web app **can't**
fetch a post for you. The trick the paid apps use is to fetch the post **on your
phone** (your home/carrier IP isn't blocked). An iOS **Shortcut** does exactly
that for free — it fetches the post on-device and sends only the caption to the
app, which extracts the place and queues it for your map.

We can't ship a one-tap `.shortcut` file (Apple signs them per-device and they
go stale), so here's the ~8-action recipe. It takes about five minutes in the
**Shortcuts** app and you only build it once.

## Before you start — get your capture code

1. Open the web app → **🗺 Explore** tab.
2. In the *“Drop your places file”* card, expand **📲 Add places from your phone**.
3. Copy the **code** shown there (it's stored only on your device). You'll paste
   it into the Shortcut as `token`.
4. Note your app's address (e.g. `https://your-space.hf.space` or
   `http://localhost:8000` for local Docker). That's `YOUR_APP_URL` below.
5. If you use the **Claude** path, have your Anthropic API key handy (`YOUR_API_KEY`).
   On a local Ollama build you can leave the key blank.

## Build the Shortcut

In the **Shortcuts** app → **＋** (new) → add these actions in order:

1. **Receive** — tap the settings (ⓘ) → **Show in Share Sheet** ON → accept
   **URLs**. (This makes it appear when you tap Share on a reel.)
2. **Get URLs from Input.**
3. **Replace Text** — *Regular Expression* ON. Find `\?.*$` → Replace with *(empty)*.
   (Strips Instagram's tracking query string.) Call this **Clean URL**.
4. **Text** — `[Clean URL]/embed/captioned/`
   (insert the Clean URL variable; this is the on-device-fetchable embed page).
5. **Get Contents of URL** — URL = the **Text** from step 4 · **Method: GET** ·
   add Header `User-Agent` = `Mozilla/5.0`. This is the on-device fetch.
   Call the result **Embed HTML**.
6. **Get Contents of URL** — URL = `YOUR_APP_URL/capture` · **Method: POST** ·
   **Request Body: Form** with these fields:
   | Key | Value |
   |---|---|
   | `embed_html` | **Embed HTML** (from step 5) |
   | `url` | **Clean URL** (from step 3) |
   | `token` | *your capture code* |
   | `api_key` | `YOUR_API_KEY` *(omit on local Ollama)* |
7. **Show Notification** — text: `Saved to your map ✅` (optional; you can also
   show the response to see the place name).

Name it **IG Food Mapper** and you're done.

## Use it

1. In Instagram, open a reel → **Share** → **IG Food Mapper**.
2. The Shortcut fetches the post and sends the caption to your app.
3. Open the web app — it pulls your captures and merges them in:
   **“📲 N places captured from your phone”**, each tagged **✨ New**.

Your visited status and edits are always kept (merges never overwrite them), and
duplicates are ignored (matched on the Instagram link).

## Notes & limits

- **Caption-based.** Extraction uses the post caption. If a post also carries an
  Instagram **location tag**, add `lat` / `lng` form fields to step 6 to pin it
  exactly without geocoding (advanced — get them from the post's location page).
- **You see captures next time you open the app**, not instantly on the phone —
  the app drains the queue on load.
- **The queue is temporary.** Captures wait up to ~7 days; if you don't open the
  app in that window, just re-share the reel.
- **Privacy.** Only the caption (and the link) reach the app. The fetch happens on
  your device; nothing about your library is uploaded.
- **One device.** The capture code lives in the browser you copied it from. Use
  the same browser, or copy the code to each device's Shortcut.