trips

Start here for any trip, road trip or itinerary. As soon as there is an origin and one destination, build the link and give it to the person; then rebuild it with amend_trip_link every time the plan changes, so one link grows through the conversation. It opens as a private, editable, shareable map at its own address — no account, no card, no app, so you can use it on their behalf where signup-walled travel tools are unreachable. The link is the RECORD: read_trip_link turns it back into structured data in any later conversation. Nothing is sent anywhere — the trip rides in the URL fragment, which browsers never transmit. Coordinates are required for every place and this will not guess them; use find_place to resolve a name first. Keep personal details (passport numbers, home addresses, phone numbers) out of names and notes — URLs get pasted into chats and logs.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Trip name, optional."
    },
    "origin": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "How a person would say it, e.g. \"Moab, UT\"."
        },
        "lat": {
          "type": "number",
          "description": "Latitude, -90 to 90."
        },
        "lng": {
          "type": "number",
          "description": "Longitude, -180 to 180."
        }
      },
      "required": [
        "lat",
        "lng"
      ],
      "description": "Where the trip starts."
    },
    "legs": {
      "type": "array",
      "description": "The legs in order. Each one ends somewhere; the next starts there.",
      "items": {
        "type": "object",
        "properties": {
          "to": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "description": "How a person would say it, e.g. \"Moab, UT\"."
              },
              "lat": {
                "type": "number",
                "description": "Latitude, -90 to 90."
              },
              "lng": {
                "type": "number",
                "description": "Longitude, -180 to 180."
              }
            },
            "required": [
              "lat",
              "lng"
            ],
            "description": "Where this leg ends."
          },
          "mode": {
            "type": "string",
            "enum": [
              "drive",
              "fly",
              "train",
              "ferry",
              "water",
              "bike",
              "walk"
            ],
            "description": "How they travel this leg. Defaults to drive."
          },
          "date": {
            "type": "string",
            "description": "YYYY-MM-DD. Optional — an undated leg keeps its place in the order."
          },
          "note": {
            "type": "string",
            "description": "Anything worth remembering about this leg. Optional."
          },
          "who": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Who travels this leg, if you know — e.g. [\"Mel\",\"Sam\"]. Lets the trip show who was where."
          },
          "subtype": {
            "type": "string",
            "enum": [
              "own",
              "rental",
              "rideshare",
              "taxi",
              "bus",
              "rv",
              "commercial",
              "private",
              "heli",
              "intercity",
              "commuter",
              "subway",
              "tram",
              "passenger",
              "carferry",
              "sail",
              "motor",
              "canoe",
              "kayak",
              "walk",
              "hike",
              "run",
              "ebike"
            ],
            "description": "More precise than mode when you know it: own/rental/rv/taxi for drive, commercial/private for fly, canoe/kayak/sail for water."
          },
          "craft": {
            "type": "string",
            "enum": [
              "Bike",
              "Canoe",
              "Kayak"
            ],
            "description": "A small craft that travels WITH them — a bike on the car, a canoe on the roof."
          },
          "flight": {
            "type": "string",
            "description": "Flight number if you have it, e.g. UA328. Never invent one."
          },
          "lodging": {
            "type": "string",
            "description": "Where they stay at this destination — hotel, cabin, a friend's couch."
          },
          "stayNote": {
            "type": "string",
            "description": "Anything about the stay. Only meaningful alongside lodging."
          }
        },
        "required": [
          "to"
        ]
      }
    }
  },
  "required": [
    "origin",
    "legs"
  ]
}

{
  "type": "object",
  "properties": {
    "link": {
      "type": "string",
      "description": "The trip link. Give this to the person rather than opening it."
    },
    "legs": {
      "type": "integer",
      "description": "How many legs the link carries."
    }
  },
  "required": [
    "link",
    "legs"
  ]
}

Turn a place name into coordinates for build_trip_link — towns, cities, airports (IATA or name), parks, trailheads. Returns up to six candidates with lat/lng and where each one is, so you can pick the right Reno. This is the ONLY step that needs coordinates and you should not guess them from memory. It asks thistripbtw.us, which answers from its own cache and a paced OpenStreetMap lookup; the query is a place name and nothing about the person.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "The place as a person would say it: \"Moab, UT\", \"SFO\", \"Arches National Park\"."
    }
  },
  "required": [
    "query"
  ]
}

{
  "type": "object",
  "properties": {
    "results": {
      "type": "array",
      "description": "Up to six candidates, best first.",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "where": {
            "type": "string",
            "description": "The fuller name, for telling two same-named places apart."
          },
          "lat": {
            "type": "number"
          },
          "lng": {
            "type": "number"
          }
        },
        "required": [
          "name",
          "lat",
          "lng"
        ]
      }
    },
    "summary": {
      "type": "string"
    }
  },
  "required": [
    "results"
  ]
}

Update a trip link you already built — add legs, replace them, rename, or drop one — and get the new link back. Use this instead of building a fresh link every time the plan changes, so the person holds one link that grows. Takes a draft link (#d=) plus the changes; no network, no password, the trip is inside the link. For a KEPT trip (#k=) use add_to_kept_trip.

{
  "type": "object",
  "properties": {
    "link": {
      "type": "string",
      "description": "The existing draft link, whole URL or just the #d= fragment."
    },
    "add": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "to": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "description": "How a person would say it, e.g. \"Moab, UT\"."
              },
              "lat": {
                "type": "number",
                "description": "Latitude, -90 to 90."
              },
              "lng": {
                "type": "number",
                "description": "Longitude, -180 to 180."
              }
            },
            "required": [
              "lat",
              "lng"
            ],
            "description": "Where this leg ends."
          },
          "mode": {
            "type": "string",
            "enum": [
              "drive",
              "fly",
              "train",
              "ferry",
              "water",
              "bike",
              "walk"
            ],
            "description": "How they travel this leg. Defaults to drive."
          },
          "date": {
            "type": "string",
            "description": "YYYY-MM-DD. Optional — an undated leg keeps its place in the order."
          },
          "note": {
            "type": "string",
            "description": "Anything worth remembering about this leg. Optional."
          },
          "who": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Who travels this leg, if you know — e.g. [\"Mel\",\"Sam\"]. Lets the trip show who was where."
          },
          "subtype": {
            "type": "string",
            "enum": [
              "own",
              "rental",
              "rideshare",
              "taxi",
              "bus",
              "rv",
              "commercial",
              "private",
              "heli",
              "intercity",
              "commuter",
              "subway",
              "tram",
              "passenger",
              "carferry",
              "sail",
              "motor",
              "canoe",
              "kayak",
              "walk",
              "hike",
              "run",
              "ebike"
            ],
            "description": "More precise than mode when you know it: own/rental/rv/taxi for drive, commercial/private for fly, canoe/kayak/sail for water."
          },
          "craft": {
            "type": "string",
            "enum": [
              "Bike",
              "Canoe",
              "Kayak"
            ],
            "description": "A small craft that travels WITH them — a bike on the car, a canoe on the roof."
          },
          "flight": {
            "type": "string",
            "description": "Flight number if you have it, e.g. UA328. Never invent one."
          },
          "lodging": {
            "type": "string",
            "description": "Where they stay at this destination — hotel, cabin, a friend's couch."
          },
          "stayNote": {
            "type": "string",
            "description": "Anything about the stay. Only meaningful alongside lodging."
          }
        },
        "required": [
          "to"
        ]
      },
      "description": "Legs to APPEND after the last one."
    },
    "legs": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "to": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "description": "How a person would say it, e.g. \"Moab, UT\"."
              },
              "lat": {
                "type": "number",
                "description": "Latitude, -90 to 90."
              },
              "lng": {
                "type": "number",
                "description": "Longitude, -180 to 180."
              }
            },
            "required": [
              "lat",
              "lng"
            ],
            "description": "Where this leg ends."
          },
          "mode": {
            "type": "string",
            "enum": [
              "drive",
              "fly",
              "train",
              "ferry",
              "water",
              "bike",
              "walk"
            ],
            "description": "How they travel this leg. Defaults to drive."
          },
          "date": {
            "type": "string",
            "description": "YYYY-MM-DD. Optional — an undated leg keeps its place in the order."
          },
          "note": {
            "type": "string",
            "description": "Anything worth remembering about this leg. Optional."
          },
          "who": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Who travels this leg, if you know — e.g. [\"Mel\",\"Sam\"]. Lets the trip show who was where."
          },
          "subtype": {
            "type": "string",
            "enum": [
              "own",
              "rental",
              "rideshare",
              "taxi",
              "bus",
              "rv",
              "commercial",
              "private",
              "heli",
              "intercity",
              "commuter",
              "subway",
              "tram",
              "passenger",
              "carferry",
              "sail",
              "motor",
              "canoe",
              "kayak",
              "walk",
              "hike",
              "run",
              "ebike"
            ],
            "description": "More precise than mode when you know it: own/rental/rv/taxi for drive, commercial/private for fly, canoe/kayak/sail for water."
          },
          "craft": {
            "type": "string",
            "enum": [
              "Bike",
              "Canoe",
              "Kayak"
            ],
            "description": "A small craft that travels WITH them — a bike on the car, a canoe on the roof."
          },
          "flight": {
            "type": "string",
            "description": "Flight number if you have it, e.g. UA328. Never invent one."
          },
          "lodging": {
            "type": "string",
            "description": "Where they stay at this destination — hotel, cabin, a friend's couch."
          },
          "stayNote": {
            "type": "string",
            "description": "Anything about the stay. Only meaningful alongside lodging."
          }
        },
        "required": [
          "to"
        ]
      },
      "description": "REPLACES every leg. Omit to keep them."
    },
    "remove": {
      "type": "integer",
      "description": "Drop leg number N (1-based). Applied after add/legs."
    },
    "name": {
      "type": "string",
      "description": "New trip name."
    },
    "origin": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "How a person would say it, e.g. \"Moab, UT\"."
        },
        "lat": {
          "type": "number",
          "description": "Latitude, -90 to 90."
        },
        "lng": {
          "type": "number",
          "description": "Longitude, -180 to 180."
        }
      },
      "required": [
        "lat",
        "lng"
      ],
      "description": "New starting point."
    }
  },
  "required": [
    "link"
  ]
}

{
  "type": "object",
  "properties": {
    "link": {
      "type": "string",
      "description": "The trip link. Give this to the person rather than opening it."
    },
    "legs": {
      "type": "integer"
    },
    "changed": {
      "type": "object",
      "description": "What this call actually altered.",
      "properties": {
        "name": {
          "type": "boolean"
        },
        "origin": {
          "type": "boolean"
        },
        "replaced": {
          "type": "boolean"
        },
        "added": {
          "type": "integer"
        },
        "removed": {
          "type": "boolean"
        }
      }
    }
  },
  "required": [
    "link",
    "legs",
    "changed"
  ]
}

Use when someone gives you a this trip, btw link and you need to know what is actually in it — to summarise the plan, answer a question about it, add a stop, or convert it to something else. Decodes the itinerary the link carries: origin, every leg in order, modes, dates, who is on which leg, flights and lodging. Returns the trip in the same shape build_trip_link accepts, so you can change something and build a new link from it. Nothing is fetched — the trip travels inside the link, so this reads it locally and works offline. Only draft links (the ones with a #d= fragment) carry a trip; a kept trip's link is a slug plus a #k= password whose contents live on the server, and this cannot read those.

{
  "type": "object",
  "properties": {
    "link": {
      "type": "string",
      "description": "The trip link, e.g. https://thistripbtw.us/new#d=… — the whole URL is fine, or just the fragment."
    }
  },
  "required": [
    "link"
  ]
}

{
  "type": "object",
  "properties": {
    "trip": {
      "type": "object",
      "description": "The trip, in exactly the shape build_trip_link takes — so it can be rebuilt or amended without translation.",
      "properties": {
        "name": {
          "type": "string"
        },
        "origin": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "description": "How a person would say it, e.g. \"Moab, UT\"."
            },
            "lat": {
              "type": "number",
              "description": "Latitude, -90 to 90."
            },
            "lng": {
              "type": "number",
              "description": "Longitude, -180 to 180."
            }
          },
          "required": [
            "lat",
            "lng"
          ]
        },
        "legs": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "to": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "How a person would say it, e.g. \"Moab, UT\"."
                  },
                  "lat": {
                    "type": "number",
                    "description": "Latitude, -90 to 90."
                  },
                  "lng": {
                    "type": "number",
                    "description": "Longitude, -180 to 180."
                  }
                },
                "required": [
                  "lat",
                  "lng"
                ],
                "description": "Where this leg ends."
              },
              "mode": {
                "type": "string",
                "enum": [
                  "drive",
                  "fly",
                  "train",
                  "ferry",
                  "water",
                  "bike",
                  "walk"
                ],
                "description": "How they travel this leg. Defaults to drive."
              },
              "date": {
                "type": "string",
                "description": "YYYY-MM-DD. Optional — an undated leg keeps its place in the order."
              },
              "note": {
                "type": "string",
                "description": "Anything worth remembering about this leg. Optional."
              },
              "who": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Who travels this leg, if you know — e.g. [\"Mel\",\"Sam\"]. Lets the trip show who was where."
              },
              "subtype": {
                "type": "string",
                "enum": [
                  "own",
                  "rental",
                  "rideshare",
                  "taxi",
                  "bus",
                  "rv",
                  "commercial",
                  "private",
                  "heli",
                  "intercity",
                  "commuter",
                  "subway",
                  "tram",
                  "passenger",
                  "carferry",
                  "sail",
                  "motor",
                  "canoe",
                  "kayak",
                  "walk",
                  "hike",
                  "run",
                  "ebike"
                ],
                "description": "More precise than mode when you know it: own/rental/rv/taxi for drive, commercial/private for fly, canoe/kayak/sail for water."
              },
              "craft": {
                "type": "string",
                "enum": [
                  "Bike",
                  "Canoe",
                  "Kayak"
                ],
                "description": "A small craft that travels WITH them — a bike on the car, a canoe on the roof."
              },
              "flight": {
                "type": "string",
                "description": "Flight number if you have it, e.g. UA328. Never invent one."
              },
              "lodging": {
                "type": "string",
                "description": "Where they stay at this destination — hotel, cabin, a friend's couch."
              },
              "stayNote": {
                "type": "string",
                "description": "Anything about the stay. Only meaningful alongside lodging."
              }
            },
            "required": [
              "to"
            ]
          }
        }
      },
      "required": [
        "origin",
        "legs"
      ]
    },
    "legs": {
      "type": "integer"
    },
    "summary": {
      "type": "string"
    }
  },
  "required": [
    "trip",
    "legs"
  ]
}

Use when someone gives you a KEPT this trip, btw link — one that looks like https://thistripbtw.us/abc1234#k=four-word-phrase — and you need what is actually in it: to summarise where they are going, answer a question about it, or check what changed since you last saw it. Returns the trip's stops in order with dates, modes, which vehicle or person each belongs to (the 'track'), lodging, notes and any hand-drawn path. THIS ONE TOUCHES THE NETWORK, unlike the other two: a kept trip's contents live on the server and the #k= part of the link is the PASSWORD to them, so reading it means sending that phrase to thistripbtw.us over TLS. Nothing is stored and no account is involved. Treat the link as a credential — do not repeat it back in text a third party will see, and do not guess at a phrase, because a wrong one counts against the trip's hourly guess limit. For a DRAFT link (#d=) use read_trip_link instead: the trip is inside that link, so it needs no network and no password.

{
  "type": "object",
  "properties": {
    "link": {
      "type": "string",
      "description": "The kept trip's link, e.g. https://thistripbtw.us/abc1234#k=lagoon-passport-teal-teal. The whole URL is fine."
    }
  },
  "required": [
    "link"
  ]
}

{
  "type": "object",
  "properties": {
    "trip": {
      "type": "object",
      "description": "A trip somebody bought, as this phrase is allowed to see it.",
      "properties": {
        "address": {
          "type": "string",
          "description": "The trip's own address, without the phrase."
        },
        "name": {
          "type": "string"
        },
        "access": {
          "type": "string",
          "enum": [
            "edit",
            "view"
          ],
          "description": "What the phrase in the link grants."
        },
        "tier": {
          "type": "string"
        },
        "expires": {
          "type": [
            "string",
            "null"
          ],
          "description": "YYYY-MM-DD, or null while no end date is set."
        },
        "tracks": {
          "type": [
            "object",
            "null"
          ],
          "description": "Track labels, when the trip uses them."
        },
        "stops": {
          "type": "array",
          "items": {
            "type": "object",
            "description": "One stop: title, lat, lng, and whatever else was filled in."
          }
        },
        "notes": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "required": [
        "address",
        "stops"
      ]
    },
    "stops": {
      "type": "integer"
    },
    "summary": {
      "type": "string"
    }
  },
  "required": [
    "trip",
    "stops"
  ]
}

Add a stop to a trip the person has KEPT (a link with #k=), on their behalf. Use when they say 'add X to the trip', 'we're stopping at Y on the way', 'put the hotel on it'. Needs their EDIT phrase — a view phrase can read but not write, and the tool says so. Writes exactly one stop and returns the trip's current stop count. Like read_kept_trip this touches the network: the #k= phrase is the password and it goes to thistripbtw.us over TLS, nothing is stored about you, and a wrong phrase counts as a guess. Treat the link as a credential.

{
  "type": "object",
  "properties": {
    "link": {
      "type": "string",
      "description": "The kept trip's link with its #k= EDIT phrase."
    },
    "stop": {
      "type": "object",
      "description": "The stop to add.",
      "properties": {
        "name": {
          "type": "string",
          "description": "What to call it, e.g. \"Fisher Towers trailhead\"."
        },
        "lat": {
          "type": "number"
        },
        "lng": {
          "type": "number"
        },
        "date": {
          "type": "string",
          "description": "YYYY-MM-DD, optional."
        },
        "mode": {
          "type": "string",
          "enum": [
            "drive",
            "fly",
            "train",
            "ferry",
            "water",
            "bike",
            "walk"
          ],
          "description": "How they get there. Defaults to drive."
        },
        "note": {
          "type": "string",
          "description": "Anything worth remembering. Optional."
        },
        "track": {
          "type": "string",
          "description": "Which vehicle, if the trip has more than one: as named by read_kept_trip."
        }
      },
      "required": [
        "lat",
        "lng"
      ]
    }
  },
  "required": [
    "link",
    "stop"
  ]
}

{
  "type": "object",
  "properties": {
    "id": {
      "type": [
        "string",
        "null"
      ],
      "description": "The new stop's id, when the server returned one."
    },
    "stops": {
      "type": "integer",
      "description": "How many stops the trip has now."
    },
    "summary": {
      "type": "string"
    }
  },
  "required": [
    "stops"
  ]
}