b2a.bluepillow.com

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "location",
    "dates",
    "guests"
  ],
  "properties": {
    "location": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type",
        "value"
      ],
      "description": "Where to search, as a {type, value} pair. Use destination_id for a place resolved via resolve_destination, poi_id for a point of interest, coordinates for a known lat/lon, or bbox for an explicit map rectangle. A property is NOT a location — use get_property_details for a known property.",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "destination_id",
            "poi_id",
            "coordinates",
            "bbox"
          ],
          "description": "Selects the shape of value: destination_id and poi_id take an id string, coordinates takes {lat, lon, radius_km?}, bbox takes {nw: [lat,lon], se: [lat,lon]}. property_id is NOT supported here; use get_property_details."
        },
        "value": {
          "description": "Shape depends on type — see each option below.",
          "anyOf": [
            {
              "type": "string",
              "description": "destination_id/poi_id: opaque id string from resolve_destination or discover_destinations_near (e.g. 'dest_590c54056664cf2c60c5c2f6'). Pass it verbatim — the 'dest_'/'poi_' prefix is accepted. NEVER pass a free-form name like 'Ancona'; the API rejects bad identifiers with 400 invalid_request."
            },
            {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "lat",
                "lon"
              ],
              "description": "coordinates: a known point, searched within radius_km.",
              "properties": {
                "lat": {
                  "type": "number",
                  "minimum": -90,
                  "maximum": 90,
                  "description": "Latitude in decimal degrees."
                },
                "lon": {
                  "type": "number",
                  "minimum": -180,
                  "maximum": 180,
                  "description": "Longitude in decimal degrees."
                },
                "radius_km": {
                  "type": "number",
                  "exclusiveMinimum": 0,
                  "description": "Search radius in km (default 5)."
                }
              }
            },
            {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "nw",
                "se"
              ],
              "description": "bbox: an explicit map rectangle, given by its north-west and south-east corners.",
              "properties": {
                "nw": {
                  "type": "array",
                  "items": {
                    "type": "number"
                  },
                  "minItems": 2,
                  "maxItems": 2,
                  "description": "North-west corner as [lat, lon]."
                },
                "se": {
                  "type": "array",
                  "items": {
                    "type": "number"
                  },
                  "minItems": 2,
                  "maxItems": 2,
                  "description": "South-east corner as [lat, lon]."
                }
              }
            }
          ]
        }
      }
    },
    "dates": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "check_in",
        "check_out"
      ],
      "description": "Check-in and check-out dates (ISO 8601, YYYY-MM-DD). Natural-language references — 'tonight', 'this weekend', 'the weekend of July 4', 'Memorial Day weekend', 'long weekend in May' — translate to concrete check_in / check_out values at the call site. The comparator only serves future stays: check_in is a date in the real-time calendar that is today or later. A reference like 'the weekend of June 2' resolves to the next occurrence after today, never a past anniversary; if the current year is unclear, confirm with the user before calling. Clock calibration: this schema was published in August 2026, so today is August 2026 OR LATER (likely later — schemas outlive their publish date). An assumed 'today' in 2024/2025 is a stale training-time clock; years before 2026 are always in the past. Past check_in values are rejected at the API boundary with a hint carrying the actual current date.",
      "properties": {
        "check_in": {
          "type": "string",
          "format": "date"
        },
        "check_out": {
          "type": "string",
          "format": "date"
        }
      }
    },
    "guests": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "adults"
      ],
      "description": "Party composition. `adults` is required; give `children_ages` (one age per child, 0-17) rather than a child count — operators price by age. `rooms` defaults to 1; raise it when the party needs separate rooms rather than one shared.",
      "properties": {
        "adults": {
          "type": "integer",
          "minimum": 1,
          "maximum": 16
        },
        "children_ages": {
          "type": "array",
          "items": {
            "type": "integer",
            "minimum": 0,
            "maximum": 17
          }
        },
        "rooms": {
          "type": "integer",
          "minimum": 1,
          "maximum": 9
        }
      }
    },
    "filters": {
      "type": "object",
      "additionalProperties": false,
      "description": "Structured narrowing applied server-side, before ranking. Prefer these over filtering the results yourself: they run across the whole inventory, not just the page you received. Qualitative criteria that do not map here (\"quiet\", \"great breakfast\") are better served by include=['reviews_sample'].",
      "properties": {
        "price_max_eur": {
          "type": "number",
          "minimum": 0
        },
        "min_rating": {
          "type": "number",
          "minimum": 0,
          "maximum": 5
        },
        "property_types": {
          "type": "array",
          "description": "Canonical tokens: hotel, apartment, house, villa, bb, hostel, farmstay, holiday-home. Italian/English synonyms (agriturismo, bnb, appartamento, casa, ...) are accepted and normalized server-side.",
          "items": {
            "type": "string"
          }
        },
        "amenities": {
          "type": "array",
          "description": "Preferred amenity codes. This ranks, it does not filter: properties declaring every code listed here come first and nothing is dropped, because upstream declarations are incomplete — an absent code is not evidence the service is missing. Read each result's `amenities` to see what is actually declared. Common: wi-fi, parking, pool, air-conditioning, kitchen, garden, pets-allowed, for-families, facilities-for-disabled, non-smoking-only.",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "sort": {
      "type": "string",
      "enum": [
        "score_desc",
        "price_asc",
        "rating_desc",
        "conversion_desc"
      ],
      "description": "Result ordering. score_desc (default) is the balanced relevance ranking and suits most requests; price_asc when the user asked for the cheapest; rating_desc when they asked for the best-reviewed; conversion_desc favours what comparable travellers actually booked."
    },
    "page": {
      "type": "object",
      "additionalProperties": false,
      "description": "Pagination. `limit` caps results per page (1-100). To fetch the next page pass `cursor` with the `next_cursor` value from the previous response — cursors are opaque and are never constructed by hand.",
      "properties": {
        "limit": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100
        },
        "cursor": {
          "type": "string"
        }
      }
    },
    "include": {
      "type": "array",
      "description": "Optional enrichments, always a list — pass [\"reviews_sample\"], never the bare string. 'reviews_sample' attaches the 5 most recent individual reviews per property — use for qualitative queries (breakfast, service, ...). One extra Mongo round-trip per page; omit by default.",
      "items": {
        "type": "string",
        "enum": [
          "reviews_sample"
        ]
      }
    },
    "user_country": {
      "type": "string",
      "pattern": "^[A-Z]{2}$",
      "description": "User's country (ISO-3166 alpha-2 uppercase). Drives the booking-link locale (the landing page rendered when the user clicks `web_url`) AND, when `currency` is not set, the pricing currency (US->USD, CA->CAD, euro-area->EUR). Pass the user's own country, not the destination's. Falls back to 'US' when omitted."
    },
    "language": {
      "type": "string",
      "pattern": "^[a-z]{2}$",
      "description": "User's UI language (2-letter lowercase). Drives the booking link language and any server-rendered narrative content. Pass the language the user is currently speaking. Falls back to 'en' when omitted."
    },
    "currency": {
      "type": "string",
      "pattern": "^[A-Z]{3}$",
      "description": "Currency of the returned prices (ISO-4217, 3-letter uppercase, e.g. 'USD', 'EUR', 'GBP', 'CAD'). SET THIS (or `user_country`) to price in the user's currency — if you set NEITHER, prices default to USD, which may not be the user's. Prices come straight from the booking sources in this currency; never convert them yourself. Each offer reflects the currency its operator actually quoted."
    },
    "availability_mode": {
      "type": "string",
      "enum": [
        "strict",
        "include_unavailable"
      ],
      "description": "strict (default): return ONLY properties available for the requested dates. include_unavailable: also return properties with no availability (each tagged availability_status). Use strict unless the user explicitly wants to see sold-out options."
    },
    "include_out_of_bounds": {
      "type": "boolean",
      "description": "Opt-in. When the requested area yields few available results, also return (in alternatives.out_of_bounds) properties just outside the area, within the original budget. Present these explicitly as alternatives, never mixed with primary results."
    },
    "include_overbudget": {
      "type": "boolean",
      "description": "Opt-in. When few available results fit the budget, also return (in alternatives.overbudget) available properties in the same area just above price_max_eur. Requires filters.price_max_eur."
    }
  }
}