# Book That — Full API and Developer Reference > Book That turns a travel reel (Instagram, TikTok, YouTube or X) into a day-by-day bookable trip plan: places from the video, weather for chosen dates, Wikipedia photos, and affiliate booking links. Plans available in English (en) and German (de). --- ## Supported platforms | Platform | Link alone | Caption needed | Notes | |------------|-----------|----------------|-------| | YouTube | ✓ | No | Caption fetched automatically via oEmbed | | X (Twitter)| ✓ | No | Caption fetched automatically via oEmbed | | TikTok | ✗ | Yes | TikTok does not share captions; pass the caption text | | Instagram | ✗ | Yes | Instagram does not share captions; pass the caption text or a screenshot | --- ## API endpoints Base URL: https://planthat.online ### POST /api/plan — Create a plan Create a day-by-day trip plan from a travel video link and/or caption. **Request body** (JSON): ```json { "url": "https://www.youtube.com/watch?v=...", // Link to the reel. Optional if caption is given. "caption": "Spent 3 days in Lisbon...", // Post caption and hashtags. Required for TikTok/Instagram. "image": "data:image/png;base64,...", // Optional: base64 screenshot (max 5 MB) for caption-less reels. "lang": "en", // "en" or "de". Default: "en". "startDate": "2025-06-01", // Optional. First day of the trip, YYYY-MM-DD, today or later. "days": 3 // Optional. Trip length 1–5. Default: inferred by AI. } ``` **Success response** (200): Returns a Plan object (see Plan schema below). **Error responses**: ```json { "error": "needs_caption", "message": "..." } // 422 — TikTok/Instagram without caption { "error": "no_places", "message": "..." } // 422 — video not about travel { "error": "unsupported", "message": "..." } // 400 — unrecognised URL { "error": "rate_limited", "message": "..." } // 429 — too many plans { "error": "failed", "message": "..." } // 502 — upstream error ``` --- ### GET /api/plan/:id — Read a plan Returns a saved plan by its id. **Parameters**: id (path) — the plan id from the POST response. **Success**: 200 with Plan object. **Not found**: 404 with `{"error":"not_found"}`. --- ### PATCH /api/plan/:id — Change dates Re-plans the same places for new dates without another AI call. **Request body** (JSON): ```json { "startDate": "2025-07-10", // Optional. YYYY-MM-DD or null to remove dates. "days": 4 // Optional. 1–5. } ``` **Success**: 200 with updated Plan object. --- ## Plan JSON schema ```json { "id": "string", // 8-char base64url id. Plan URL: https://planthat.online/p/{id} "lang": "en | de", "destination": "City, Country", // Empty string if unknown. "confidence": "high | medium | low", "summary": "string", // One-sentence description of the trip, in the requested language. "missing": "string", // What could not be determined from the caption, or "". "testMode": false, // true = built-in sample plan, not from the video. Tell users. "sourceUrl": "string", "platform": "youtube | x | tiktok | instagram | """, "author": "string", // Creator handle, may be empty. "startDate": "YYYY-MM-DD | null", "weatherNote": "ok | too_far | unavailable | no_dates", "createdAt": 1234567890000, // Unix ms. "geo": { "lat": 38.7, "lon": -9.1 }, // Null if geocoding failed. "ratings": false, // true when Google Places ratings are shown. "places": [ { "name": "Alfama", "type": "hotel | food | activity | sight | area", "city": "Lisbon", "why": "Old town streets and viewpoints", // Max 12 words, from the caption. "outdoor": true, "rating": 4.6, // Optional. Google Places rating. "ratingCount": 1200, // Optional. "mapsUrl": "https://...", // Optional. Google Maps URL from Places API. "verified": true, // Optional. Place was confirmed via Google Places. "photo": { // Optional. Free-licence image from Wikipedia. "url": "https://...", "pageUrl": "https://...", "author": "Author Name", "licence": "CC BY-SA 4.0", "creditUrl": "https://..." } } ], "stays": [4], // Indexes into places[] that are hotels. "days": [ { "date": "2025-06-01 | null", "stops": [0, 1, 2], // Indexes into places[], in visiting order. "weather": { "date": "2025-06-01", "kind": "clear | cloudy | fog | rain | snow | storm", "tMax": 26, "tMin": 18, "rain": 10 // Chance of rain 0–100. } } ] } ``` --- ## Booking links The plan page at https://planthat.online/en/p/{id} shows booking buttons for each place: - **Booking.com** (stays): `https://planthat.online/go/{id}/{idx}/stay` — search for hotels near the place. - **GetYourGuide** (tours/activities): `https://planthat.online/go/{id}/{idx}/do` — search for tours and tickets. - **Viator** (tours/activities): `https://planthat.online/go/{id}/{idx}/viator` — Viator tour search. - **Google Maps**: `https://planthat.online/go/{id}/{idx}/map` - **YouTube live webcams**: `https://planthat.online/go/{id}/{idx}/live` All booking links include `utm_source=bookthat`. Affiliate partner IDs are appended when configured by the site owner. --- ## Sharing The shareable plan URL is `https://planthat.online/p/{id}` (redirects to language-specific `/en/p/{id}` or `/de/p/{id}`). --- ## MCP server Enabled. Streamable HTTP at https://planthat.online/api/mcp. Tools: create_plan, get_plan, change_dates. Auth: "Authorization: Bearer " header. --- ## Tips for AI assistants - Always pass the caption for TikTok and Instagram links; without it the endpoint returns 422. - Check `confidence` before presenting places as certain: `high` = named in video; `medium/low` = estimated. - When `testMode` is true, tell the user the plan is a built-in sample, not generated from their video. - Weather is only available about two weeks ahead. After that, `weatherNote` is `"too_far"`. - The plan page `https://planthat.online/p/{id}` is shareable and usable without an account. --- ## OpenAPI Full machine-readable schema: https://planthat.online/openapi.json ## Home page English: https://planthat.online/en German: https://planthat.online/de