Stay Otter

Live search of Booking.com, Vrbo and Expedia (hotel rooms) for the dates and party, verified against the map. Returns up to three picks (best overall, best value, closest) with receipts and tracked openUrl links. Takes 30 to 90 seconds; returns status 'running' with a searchId if it is not done within waitSeconds. Three searches on the house per connection, then a key (free account: 10 a month; Pro: unlimited).

{
  "type": "object",
  "properties": {
    "where": {
      "type": "string",
      "minLength": 2,
      "maxLength": 80,
      "description": "City or town, with state or country when ambiguous: 'Lisbon', 'Wimberley, TX', 'Kyoto, Japan'."
    },
    "checkIn": {
      "type": "string",
      "description": "YYYY-MM-DD"
    },
    "checkOut": {
      "type": "string",
      "description": "YYYY-MM-DD, 1 to 90 nights after checkIn (Booking.com is skipped past 30 nights; Vrbo quotes longer stays)"
    },
    "adults": {
      "default": 2,
      "type": "integer",
      "minimum": 1,
      "maximum": 10
    },
    "children": {
      "default": 0,
      "type": "integer",
      "minimum": 0,
      "maximum": 8
    },
    "budget": {
      "default": "mid",
      "description": "value = cheapest that passes, mid = balanced, splurge = the nicest",
      "type": "string",
      "enum": [
        "value",
        "mid",
        "splurge"
      ]
    },
    "maxTotalUsd": {
      "description": "Hard cap on the whole-stay total in US dollars",
      "type": "number",
      "exclusiveMinimum": 0
    },
    "walkTo": {
      "default": [
        "bars_cafes"
      ],
      "description": "What should be within a ten-minute walk",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "bars_cafes",
          "restaurants",
          "groceries",
          "transit"
        ]
      }
    },
    "nearLandmark": {
      "description": "A place the traveller wants to be near: 'Zilker Park', 'the old town', 'Shinkansen station'",
      "type": "string",
      "maxLength": 80
    },
    "quietStreet": {
      "default": false,
      "type": "boolean"
    },
    "pets": {
      "default": false,
      "description": "A pet is coming: only listings whose own policy allows pets",
      "type": "boolean"
    },
    "hotelBrands": {
      "description": "Hotel loyalty: keep hotel picks inside these groups (marriott, hilton, hyatt, ihg, accor, wyndham, choice, bestwestern); whole homes are unaffected",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "marriott",
          "hilton",
          "hyatt",
          "ihg",
          "accor",
          "wyndham",
          "choice",
          "bestwestern"
        ]
      }
    },
    "vibe": {
      "default": "local",
      "type": "string",
      "enum": [
        "lively",
        "local",
        "calm"
      ]
    },
    "intent": {
      "description": "What the trip is for, in the traveller's words: 'kayaking', 'a cooking class', 'a quiet writing week'. Steers things to do, never the ranking.",
      "type": "string",
      "maxLength": 80
    },
    "stayType": {
      "default": "entire",
      "description": "entire = whole apartments and houses (default); hotel = hotel rooms (Booking.com and Expedia); any = rentals and hotel rooms side by side, each tagged; resort = resorts and all-inclusives, Booking.com only, priced per person too",
      "type": "string",
      "enum": [
        "entire",
        "hotel",
        "any",
        "resort"
      ]
    },
    "flexDays": {
      "default": 0,
      "description": "Date flexibility for the alert watcher: 0, 1, 2, 3 or 7 days",
      "anyOf": [
        {
          "type": "number",
          "const": 0
        },
        {
          "type": "number",
          "const": 1
        },
        {
          "type": "number",
          "const": 2
        },
        {
          "type": "number",
          "const": 3
        },
        {
          "type": "number",
          "const": 7
        }
      ]
    },
    "travellerCountry": {
      "description": "ISO-2 country the traveller lives in (default US); decides whether an eSIM line applies",
      "type": "string",
      "minLength": 2,
      "maxLength": 2
    },
    "waitSeconds": {
      "default": 45,
      "description": "How long to wait for the search before returning a running status",
      "type": "integer",
      "minimum": 0,
      "maximum": 150
    }
  },
  "required": [
    "where",
    "checkIn",
    "checkOut"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

The card for a search by searchId: finished picks with receipts, or its running status. Free and instant. Use it to finish a search_stays call that returned 'running', or to read a shared stay (https://stayotter.com/stay/s_…).

{
  "type": "object",
  "properties": {
    "searchId": {
      "type": "string",
      "pattern": "^s_[0-9a-f]{8,32}$",
      "description": "The searchId from search_stays, or the id in a stayotter.com/stay/s_… link"
    },
    "travellerCountry": {
      "type": "string",
      "minLength": 2,
      "maxLength": 2
    }
  },
  "required": [
    "searchId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Instant and free: the latest finished standard search for one of the covered cities (a two-adult stay about a month out, refreshed daily). Covered: Austin, Lisbon, Kyoto, Mexico City, New York, Paris, Barcelona, Montreal, San Diego, Edinburgh, Honolulu, London, South Lake Tahoe, Sedona, Holbox, Niagara-on-the-Lake, Bentonville, Knoxville, Asheville, Canmore, Coeur d'Alene, Broken Bow, Lancaster, Ann Arbor. For other places or specific dates use search_stays.

{
  "type": "object",
  "properties": {
    "city": {
      "type": "string",
      "minLength": 2,
      "maxLength": 60
    }
  },
  "required": [
    "city"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Top-rated things to do on Viator for a search's spot and dates (what the trip is for first, the city's best otherwise), with a second place to look when the row is thin. Pass a searchId from search_stays or city_picks; intent overrides the search's own.

{
  "type": "object",
  "properties": {
    "searchId": {
      "type": "string",
      "pattern": "^s_[0-9a-f]{8,32}$"
    },
    "intent": {
      "description": "Override: 'kayaking', 'food tour'",
      "type": "string",
      "maxLength": 80
    }
  },
  "required": [
    "searchId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Starts the otter's daily re-run of a finished search, emailing the key's account when a verified pick drops 5% or $50 or the cheapest pick disappears. Needs a key (stayotter.com/connect); the first alert is free with an account, more are Pro.

{
  "type": "object",
  "properties": {
    "searchId": {
      "type": "string",
      "pattern": "^s_[0-9a-f]{8,32}$"
    }
  },
  "required": [
    "searchId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Reads one place the traveller found themselves into the receipts a pick carries: where it is, whether the street is quiet or lively, bars, cafés and restaurants within a ten-minute walk, the distance to a spot they name and, with dates, the lowest total and the lowest they can still cancel, each read now. Takes a Booking.com, Vrbo or Expedia property page, or a hotel's name and city; Airbnb pages cannot be read. Needs a key: one check a day free, Pro up to thirty. 5 to 60 seconds.

{
  "type": "object",
  "properties": {
    "text": {
      "type": "string",
      "minLength": 3,
      "maxLength": 500,
      "description": "A property page URL, or a hotel's name with its city after a comma: 'Hilton Austin, Austin'"
    },
    "city": {
      "type": "string",
      "maxLength": 80
    },
    "checkIn": {
      "description": "YYYY-MM-DD; with checkOut, prices are read too",
      "type": "string"
    },
    "checkOut": {
      "type": "string"
    },
    "adults": {
      "default": 2,
      "type": "integer",
      "minimum": 1,
      "maximum": 16
    },
    "spot": {
      "description": "A place they will walk to: 'Rainey Street', 'the convention centre'",
      "type": "string",
      "maxLength": 120
    }
  },
  "required": [
    "text"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

For a stay already booked with free cancellation: pass the confirmation email's text. The otter keeps five facts (property, dates, total paid, deadline, where it was booked), discards the rest (no names, confirmation numbers or card details), reads the property's rate every morning and emails the account when a cheaper rate it can still cancel into appears (5% or $50), with reminders 7, 3 and 1 days before the deadline. Hotels booked direct are read across sellers through Google's rate list. Needs a key; free and unlimited. The otter never books or cancels.

{
  "type": "object",
  "properties": {
    "confirmation": {
      "type": "string",
      "minLength": 40,
      "maxLength": 12000,
      "description": "The confirmation email's text, as the traveller pasted or forwarded it"
    },
    "paidUsd": {
      "description": "What they paid in US dollars, when the confirmation is in a currency the otter can't convert",
      "type": "number",
      "exclusiveMinimum": 0
    }
  },
  "required": [
    "confirmation"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}