# Passport Guestbook

> A 1996-style homepage where your AI agent turns your travel history into a world map at a shareable link. No accounts, no ads, no tracking. A secret Map Key is the key to edit a map.

If a user asks you to "add my travels to Passport Guestbook", this file tells you everything you need.

## Three ways in

- MCP server (Streamable HTTP): https://passportguestbook.com/mcp
  Tools: email_search_guide, suggest_handles, prepare_map, get_my_map, remove_trips, add_note, delete_map
- Web page for people and browser agents: https://passportguestbook.com/new (offers WebMCP tools: fill_trips, read_page_state, suggest_handles)
- REST API: https://passportguestbook.com/openapi.json
- Human-readable FAQ (same rules, more detail): https://passportguestbook.com/faq

## How to help a user

You prepare the list; the user publishes it. Every route ends on https://passportguestbook.com/new, where the user checks the list, adds places email missed with a map picker, and presses Make My Map! themselves.

1. Find their travels. If you can read their email (for example a Gmail connector), and they agree, follow the email search guide (the email_search_guide tool, or the "Searching email" section of https://passportguestbook.com/llms.txt). Reduce each trip to a country and the year they went. Everything else stays on your side: no email text, cities, hotels, booking codes, addresses or companions.
2. Airport layovers do not count. Only include a country if the user actually entered it (passed immigration or left the airport).
3. In chat, ask only what the email can't answer: your uncertain items (possible layovers, trips you couldn't confirm), which places they lived in, and whether to include their home country (usually they lived there). If they mention their citizenship, it can go in citizenships: call it "your US citizenship", never "your passport", and never ask for or handle any passport number. Ask each as a short, concrete question that names the places.
   Don't paste the full list into the chat and don't ask "is this list right?": the review page shows the whole list in a table, where they check and fix it. In chat, give a one-line summary instead, like "Found 29 countries and 124 visits, 2007-2026."
4. Suggest a public handle (never a full real name), for example with suggest_handles. They can change it on the review page.
5. Hand over the list, using the first route that works for you; if one fails or is blocked, go to the next:
   A. You have Passport Guestbook's MCP tools (from https://passportguestbook.com/mcp): call prepare_map. It returns a private review_url.
   B. You can send HTTP POST requests (you run code or shell commands): POST the list to https://passportguestbook.com/api/drafts. It returns a review_url.
   C. You are a browser agent on https://passportguestbook.com/new and the page offers WebMCP tools: call fill_trips.
   D. Everything else, including chat assistants that can read web pages but can't send data to them: write the list as CSV in a code block, exactly in the format below, and tell the user to open https://passportguestbook.com/new and paste it in.
   Then tell the user: "Open this link, add any places email missed with the map picker, check the list, and press Make My Map!" Nothing is published until they do. Never tell them their map exists before they've done that.
6. After they've published: offer notes. "Want to add a GO! or SKIP IT, and a short note, to any of these countries on your map?" Use their words, never your own opinion (MCP: add_note with their Map Key; or they click the pencil next to a country on their own map page).
7. Later, to add more, prepare another list the same way with their Map Key (prepare_map or POST /api/drafts with map_key), or they simply open https://passportguestbook.com/new, where their browser usually remembers their map.

## Format

The CSV for route C, header included:

    country,year,lived
    Japan,2019,
    Thailand,2006,
    Germany,2014,yes
    Mexico,,

Country: English name or ISO 3166-1 alpha-2 code (JP, FR, US...), plus XK for Kosovo. Territories such as Puerto Rico or Hong Kong are allowed and count as "other places" next to the 195 countries.
Year: one per visit, like 2019, or blank when unknown. Years only: no months, no days, no ranges, nothing in the future.
Lived: "yes" (CSV) or true (API) only for places the user lived, not just visited. Leave it blank otherwise.
Nothing else is accepted. The server rejects any extra field, so do not add cities, notes or other columns.
Sending the same country and year again merges instead of duplicating, so resending the whole list is safe. A visit in a different year is a separate line.

## Searching email

How to find every trip in an inbox (Gmail search syntax; adapt for other mail):

1. Go year by year. Search results are capped, so one broad search misses older trips. Search each year separately, from this year back to the oldest email, using ranges like after:2019/01/01 before:2020/01/01, and page through all results.
   Be fast: run the years in parallel (several searches at once, or split the years across helpers if you can), start each year with ONE combined search joining the terms below with OR, and add narrower searches only for busy years. Read subjects and snippets first; they usually name the destination. Open a full email only when the snippet doesn't settle it. Years with no hits need nothing more.
2. The terms to cover each year:
   - Booking sites: from:(expedia OR booking.com OR airbnb OR agoda OR hotels.com OR trip.com OR priceline OR kayak OR orbitz OR traveloka OR hostelworld OR vrbo)
   - Airlines: subject:(itinerary OR "e-ticket" OR eticket OR "booking confirmation" OR "flight confirmation" OR "boarding pass" OR "check in" OR "your trip"), plus from: airline names and words like airways, airlines, air
   - Hotels: from:(marriott OR hilton OR hyatt OR ihg OR accor OR radisson OR wyndham OR "best western"), or subject:(reservation OR "your stay")
   - Trains, ferries, buses, cars: eurostar, trainline, rail, ferry, flixbus, hertz, avis, sixt, europcar, rentalcars
   - Entry documents: evisa OR "e-visa" OR "electronic travel authorization" OR ETA OR "arrival card" OR "visa approval" OR immigration
   - Phrases used only for international flights: "proof of citizenship" OR "passport details" OR "advance passenger information" OR APIS
   - Tours and activities abroad: getyourguide, viator, klook
3. Read the user's own sent mail too (in:sent): "I'm in", "landed in", "arrived in", "see you in", "back from", "on my way to". Trips booked by employers, travel agents or friends often show up only there.
4. Check forwarded bookings: an itinerary forwarded by a colleague or travel agent often names the user as the passenger.
5. Look for living abroad: lease, tenancy, rental agreement, utility bill, residence permit, work permit, moving, relocation, new bank account. Mark those countries as lived.
6. For each candidate trip, confirm:
   - The passenger or guest is the user. Bookings for family or friends don't count unless the user went too.
   - It wasn't cancelled or refunded (search the hotel or flight for "cancel" or "refund"). A rebooked trip counts once.
   - It isn't a layover: a connection where the user stayed airside doesn't count. An overnight stop, a hotel, or an onward land trip does.
   - It isn't marketing: fare deals, "trips you might like", newsletters and abandoned carts are not trips.
7. Use the destination (airport code, hotel city) for the country, and the arrival date for the year.
8. Note when the mailbox starts. Anything older can only come from the user: that's what the "anywhere else?" list is for.

## Privacy

The site stores only: the handle, countries with a year per visit, an optional wishlist and citizenship (which countries, never any document details), and a hash of the Map Key. It never connects to anyone's email. Visits from the current year show as "recently" without the year, so a public map never reveals that someone is away from home right now.

## Full example (REST, route B)

Prepare a list for the user to review:

    curl -X POST https://passportguestbook.com/api/drafts \
      -H 'content-type: application/json' \
      -d '{
        "display_name": "JetsettingJason",
        "trips": [
          { "country": "TH", "year": "2006" },
          { "country": "JP", "year": "2019" },
          { "country": "DE", "year": "2014", "lived": true },
          { "country": "MX" }
        ]
      }'

Response:

    {
      "review_url": "https://passportguestbook.com/new?draft=k3x9q2m7v4p8tw",
      "countries": ["Germany", "Japan", "Mexico", "Thailand"],
      "adding_to": null,
      "note": "Nothing is published yet. Give the user the review_url..."
    }

Give the user the review_url. To add to an existing map later, send "map_key" with the same request. Read a map with POST https://passportguestbook.com/api/my-map {"map_key": "..."}. Remove visits with POST https://passportguestbook.com/api/trips/remove. Add the user's own GO!/SKIP and a note with POST https://passportguestbook.com/api/note.
Errors come back as {"error": "..."} with HTTP 400.