Escape the Week

List the cities that have published weekends, with their slug, IATA airport code, currency and the twelve monthly season factors (1.0 = shoulder season; higher is dearer). Start here to discover city slugs for every other tool. Paged.

{
  "type": "object",
  "properties": {
    "lang": {
      "description": "Optional BCP 47 tag; name, tagline and description in that language when translated.",
      "type": "string"
    },
    "limit": {
      "default": 100,
      "description": "Max items to return (default 100, max 1000).",
      "maximum": 1000,
      "minimum": 1,
      "type": "integer"
    },
    "offset": {
      "default": 0,
      "description": "Items to skip for paging (default 0).",
      "minimum": 0,
      "type": "integer"
    },
    "status": {
      "description": "Status filter (default published). Use all for every row.",
      "enum": [
        "draft",
        "published",
        "archived",
        "all"
      ],
      "type": "string"
    }
  },
  "required": []
}

Fetch one city by its slug (from list_cities): name, country, region, coordinates, IATA code, currency and the twelve monthly season factors.

{
  "type": "object",
  "properties": {
    "lang": {
      "description": "Optional BCP 47 tag; name, tagline and description in that language when translated.",
      "type": "string"
    },
    "slug": {
      "description": "City slug.",
      "type": "string"
    }
  },
  "required": [
    "slug"
  ]
}

List the personas (the kind of traveller an itinerary is written for, e.g. foodie or collector) with their slug and audience: party_shapes (solo, couple, friends, family, multigen), children (boolean) and pace (relaxed, steady, brisk). Persona slugs are used with city slugs to name an itinerary. Paged.

{
  "type": "object",
  "properties": {
    "lang": {
      "description": "Optional BCP 47 tag; name, tagline and description in that language when translated.",
      "type": "string"
    },
    "limit": {
      "default": 100,
      "description": "Max items to return (default 100, max 1000).",
      "maximum": 1000,
      "minimum": 1,
      "type": "integer"
    },
    "offset": {
      "default": 0,
      "description": "Items to skip for paging (default 0).",
      "minimum": 0,
      "type": "integer"
    },
    "status": {
      "description": "Status filter (default published). Use all for every row.",
      "enum": [
        "draft",
        "published",
        "archived",
        "all"
      ],
      "type": "string"
    }
  },
  "required": []
}

Fetch one persona by its slug (from list_personas), with its audience.

{
  "type": "object",
  "properties": {
    "lang": {
      "description": "Optional BCP 47 tag; name, tagline and description in that language when translated.",
      "type": "string"
    },
    "slug": {
      "description": "Persona slug.",
      "type": "string"
    }
  },
  "required": [
    "slug"
  ]
}

List the origins a trip can start from: slug (pass as origin to the pricing and booking tools), name and IATA airport code. Unpaged.

{
  "type": "object",
  "properties": {},
  "required": []
}

List the budget tiers in display order (cheap, modest, expensive, luxury, ultra). Pass the name as tier.

{
  "type": "object",
  "properties": {},
  "required": []
}

List every price multiplier: for each (tier, dimension) the factor applied to the modest-tier price. Dimensions are sight, culture, dining, lodging, transport and flight.

{
  "type": "object",
  "properties": {},
  "required": []
}

The public index: every published itinerary with its city and persona slugs, title, summary, names, step counts and the sum of its steps' costs in integer cents (currency EUR unless the city says otherwise). Use it to discover which (city, persona) weekends exist.

{
  "type": "object",
  "properties": {
    "lang": {
      "description": "Optional BCP 47 tag; city and persona names in that language when translated.",
      "type": "string"
    }
  },
  "required": []
}

The full published itinerary for one (city, persona): its days and steps with local times (HH:MM), kind, notes, cost_cents per person at the modest tier (integer cents), reserve_days (how many days ahead a hard step must be booked, or null), a fallback, and each step's venue with coordinates and offers. Day 0 is Friday.

{
  "type": "object",
  "properties": {
    "city": {
      "description": "City slug.",
      "type": "string"
    },
    "lang": {
      "description": "Optional BCP 47 tag; collapses every *_i18n map into its field.",
      "type": "string"
    },
    "persona": {
      "description": "Persona slug.",
      "type": "string"
    }
  },
  "required": [
    "city",
    "persona"
  ]
}

The published itinerary as iCalendar text for one weekend (Friday = day 0): one event per step at floating local times, no time zone. friday is a YYYY-MM-DD date.

{
  "type": "object",
  "properties": {
    "city": {
      "description": "City slug.",
      "type": "string"
    },
    "friday": {
      "description": "Friday of the weekend, YYYY-MM-DD.",
      "type": "string"
    },
    "lang": {
      "description": "Optional BCP 47 tag; titles and notes in that language when translated.",
      "type": "string"
    },
    "persona": {
      "description": "Persona slug.",
      "type": "string"
    }
  },
  "required": [
    "city",
    "persona",
    "friday"
  ]
}

Budget estimate (integer cents) for a published itinerary: activities, lodging, transport and flights for a tier, a month or the year average, and a group.

{
  "type": "object",
  "properties": {
    "city": {
      "description": "City slug from list_cities, e.g. lisbon.",
      "type": "string"
    },
    "friday": {
      "description": "The Friday of the weekend as a YYYY-MM-DD date (it must be a Friday); the weekend runs Friday to Monday. Enables a real fare.",
      "type": "string"
    },
    "lang": {
      "description": "BCP 47 language of the published text, e.g. es (default English).",
      "type": "string"
    },
    "month": {
      "description": "Month of travel, or the twelve-month mean (default).",
      "enum": [
        "1",
        "2",
        "3",
        "4",
        "5",
        "6",
        "7",
        "8",
        "9",
        "10",
        "11",
        "12",
        "year"
      ],
      "type": "string"
    },
    "origin": {
      "description": "Origin slug from list_origins, e.g. barcelona; adds flights.",
      "type": "string"
    },
    "persona": {
      "description": "Persona slug from list_personas, e.g. foodie.",
      "type": "string"
    },
    "tier": {
      "description": "Budget tier, cheapest to most lavish (default modest). Scales every price line.",
      "enum": [
        "cheap",
        "modest",
        "expensive",
        "luxury",
        "ultra"
      ],
      "type": "string"
    },
    "travellers": {
      "description": "Group size, 1-20 (default 2). Prices are for the whole group.",
      "type": "integer"
    }
  },
  "required": [
    "city",
    "persona"
  ]
}

Every published itinerary priced at once (integer cents): total, per person and flights per (city, persona), plus the cheapest persona per city, for a tier, a month or the year average, a group and an optional origin; each estimate carries the persona's party_shapes. Estimates only, no fare lookups; cached for a minute per parameter set.

{
  "type": "object",
  "properties": {
    "friday": {
      "description": "Friday of the weekend, YYYY-MM-DD; echoed, not priced.",
      "type": "string"
    },
    "month": {
      "description": "Month of travel, or the twelve-month mean (default).",
      "enum": [
        "1",
        "2",
        "3",
        "4",
        "5",
        "6",
        "7",
        "8",
        "9",
        "10",
        "11",
        "12",
        "year"
      ],
      "type": "string"
    },
    "origin": {
      "description": "Origin slug; enables flights, travel hours and distance.",
      "type": "string"
    },
    "tier": {
      "description": "Budget tier (default modest).",
      "enum": [
        "cheap",
        "modest",
        "expensive",
        "luxury",
        "ultra"
      ],
      "type": "string"
    },
    "travellers": {
      "description": "Group size, 1-20 (default 2).",
      "type": "integer"
    }
  },
  "required": []
}

Cheapest known return fare per person between two IATA codes for a Friday-to-Monday weekend (cached from Travelpayouts).

{
  "type": "object",
  "properties": {
    "friday": {
      "description": "Friday of the weekend, YYYY-MM-DD.",
      "type": "string"
    },
    "from": {
      "description": "Origin IATA code.",
      "type": "string"
    },
    "to": {
      "description": "Destination IATA code.",
      "type": "string"
    }
  },
  "required": [
    "from",
    "to",
    "friday"
  ]
}

Booking links and checklist for a weekend, ordered by scarcity: first the steps that must be booked ahead (longest lead time first, each with reserve_days, a book_by date YYYY-MM-DD and an easier fallback), then flights, the hotel and the other bookable steps. Book in list order. An item's alternatives [{provider, url}] are other sites that book the same thing (the hotel on Klook beside Booking.com): compare them and book one, not both. For a plan an agent can execute (dates, costs, what to ask the person) use booking_manifest instead.

{
  "type": "object",
  "properties": {
    "city": {
      "description": "City slug from list_cities, e.g. lisbon.",
      "type": "string"
    },
    "friday": {
      "description": "The Friday of the weekend as a YYYY-MM-DD date (it must be a Friday); the weekend runs Friday to Monday. Enables a real fare.",
      "type": "string"
    },
    "lang": {
      "description": "BCP 47 language of the published text, e.g. es (default English).",
      "type": "string"
    },
    "origin": {
      "description": "Origin slug from list_origins, e.g. barcelona; adds flights.",
      "type": "string"
    },
    "persona": {
      "description": "Persona slug from list_personas, e.g. foodie.",
      "type": "string"
    },
    "tier": {
      "description": "Budget tier, cheapest to most lavish (default modest). Scales every price line.",
      "enum": [
        "cheap",
        "modest",
        "expensive",
        "luxury",
        "ultra"
      ],
      "type": "string"
    },
    "travellers": {
      "description": "Group size, 1-20 (default 2). Prices are for the whole group.",
      "type": "integer"
    }
  },
  "required": [
    "city",
    "persona",
    "friday"
  ]
}

Everything an agent needs to book one weekend, in the order to book it. Returns items (flights, hotel and bookable steps; scarcest first) each with kind, title, when (date YYYY-MM-DD and local time HH:MM), the affiliate-tracked partner url with dates, party size and time prefilled where the partner supports it, provider, estimated_cost {cents, currency} for the whole party, reserve_days, book_by (YYYY-MM-DD), fallback and alternatives [{provider, url}]: other sites that book the same item (the hotel on Klook beside Booking.com), to compare, booking one of them, never both; plus needs_from_user (traveller names, contact, payment approval), a sequence_note, the total estimate in integer cents, cancellation_advice and a disclosure that the links are affiliate links. Escape the Week never takes payment: open each url in a browser and have the person approve every payment on the partner's site. Prices are estimates, not quotes.

{
  "type": "object",
  "properties": {
    "city": {
      "description": "City slug from list_cities, e.g. lisbon.",
      "type": "string"
    },
    "friday": {
      "description": "The Friday of the weekend as a YYYY-MM-DD date (it must be a Friday); the weekend runs Friday to Monday. Enables a real fare.",
      "type": "string"
    },
    "lang": {
      "description": "BCP 47 language of the published text, e.g. es (default English).",
      "type": "string"
    },
    "origin": {
      "description": "Origin slug from list_origins, e.g. barcelona; adds flights.",
      "type": "string"
    },
    "party": {
      "description": "Who is travelling, to check the persona fits (optional); never changes a price.",
      "enum": [
        "solo",
        "couple",
        "friends",
        "family",
        "multigen"
      ],
      "type": "string"
    },
    "persona": {
      "description": "Persona slug from list_personas, e.g. foodie.",
      "type": "string"
    },
    "tier": {
      "description": "Budget tier, cheapest to most lavish (default modest). Scales every price line.",
      "enum": [
        "cheap",
        "modest",
        "expensive",
        "luxury",
        "ultra"
      ],
      "type": "string"
    },
    "travellers": {
      "description": "Group size, 1-20 (default 2). Prices are for the whole group.",
      "type": "integer"
    }
  },
  "required": [
    "city",
    "persona",
    "friday"
  ]
}

Send a tip about a city: a place to add, a closed place, somewhere nearly impossible to book, or a wrong fact. Public. A tip is never published; an editor reviews it first. Rate limited per sender.

{
  "type": "object",
  "properties": {
    "body": {
      "description": "The tip, 10 to 1000 characters.",
      "type": "string"
    },
    "city": {
      "description": "City slug.",
      "type": "string"
    },
    "contact": {
      "description": "How to reach the sender, at most 200 characters (optional).",
      "type": "string"
    },
    "kind": {
      "description": "What the tip is.",
      "enum": [
        "add",
        "closed",
        "hard_to_book",
        "wrong_info",
        "other"
      ],
      "type": "string"
    },
    "locale": {
      "description": "Language the tip is written in, a BCP 47 tag (default en).",
      "type": "string"
    },
    "persona": {
      "description": "Persona slug the tip is about, if any.",
      "type": "string"
    },
    "step_ref": {
      "description": "What the tip is about: '<day index>/<step index>' of the itinerary, or a venue id.",
      "type": "string"
    }
  },
  "required": [
    "city",
    "kind",
    "body"
  ]
}