Travel tools for AI agents: plan and edit real trips, search stays and tours, import travel videos.
Maintain this server? Claim it
Call this server's tools from your browser. Nothing to install.
Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.
Tool list from our last check. Connect live to refresh it.
Put something on a trip as stops. source says what: stops (plain stops you describe in stops), saved_places (library places with their pins, photos and links; by savedPlaceIds, folderName, or importId for everything an import found), search_result (one option from search_stays, search_activities or search_places by resultId + optionId), flight (a fare from search_flights by searchId + offerId), train (a fare from search_trains by searchId + journeyId), receipt (a booking confirmation as text or base64 image/PDF; parsed, filed on the trip, and the matching stop marked booked). Say which day with dayIndex or date; a stay defaults to its check-in date, a flight or train to its departure day. These are plans, not bookings: the traveler books through each stop's bookingUrl. Returns data plus display.resultId; call display_card to show it. presentation (optional) shapes what is shown without changing the action: compact or full layout, and only the limit, ids or sections this tool advertises.
stops = plain stops described in `stops`; saved_places = library places by savedPlaceIds, folderName or importId, with pins, photos and links intact; search_result = one search option by resultId + optionId; flight = a search_flights fare by searchId + offerId; train = a search_trains fare by searchId + journeyId; receipt = a booking confirmation (text, or contentType + data) filed on the trip
(source=receipt) Raw base64 bytes of the image or PDF, no data URL prefix
The day's calendar date (YYYY-MM-DD) instead of dayIndex
(source=search_result) What the option is, for legacy object callers. stay = a search_stays property. activity = a search_activities product. place = a search_places result's itemDraft. Restored from resultId when you pass one.
(source=receipt) The confirmation text; omit when sending image/PDF bytes
Start time at the destination, HH:MM (a stay's check-in time; saved_places: the first place of each day)
(source=stops) Each stop names its day with dayIndex or date
(source=search_result) Stays: travelers sharing the room
(source=search_result) The option/offer object (or, for kind 'place', the itemDraft), unchanged
(source=receipt) Link the confirmation to this stop and mark it booked
(source=search_result) Stays: required
(source=flight) The fare's id from that search
(source=search_result) Stays: required
0-based day for the stop (stops carry their own); or give date instead
(source=saved_places) Everything an import found; the import's own day hints place each stop
Exact propertyId (stay), productId (activity), or id (place) from that search reply
The search reply's display.resultId; account-bound and retained for 30 minutes
(source=flight, train) The searchId returned by search_flights or search_trains
(source=train) The journey's id from that search
(source=saved_places) Every place in this library folder
(source=receipt) Type of the base64 bytes in data
(source=saved_places) Place ids from list_library
(source=saved_places) Deal the places out across the trip's days in order instead of one day
The server marks this tool as destructive. Running it may delete or overwrite data on the server or in any account you connected with your headers.
Put something on a trip as stops. source says what: stops (plain stops you describe in stops), saved_places (library places with their pins, photos and links; by savedPlaceIds, folderName, or importId for everything an import found), search_result (one option from search_stays, search_activities or search_places by resultId + optionId), flight (a fare from search_flights by searchId + offerId), train (a fare from search_trains by searchId + journeyId), receipt (a booking confirmation as text or base64 image/PDF; parsed, filed on the trip, and the matching stop marked booked). Say which day with dayIndex or date; a stay defaults to its check-in date, a flight or train to its departure day. These are plans, not bookings: the traveler books through each stop's bookingUrl. Returns data plus display.resultId; call display_card to show it. presentation (optional) shapes what is shown without changing the action: compact or full layout, and only the limit, ids or sections this tool advertises.
| Argument | Type | Description |
|---|---|---|
| data | string | (source=receipt) Raw base64 bytes of the image or PDF, no data URL prefix |
| date | any | The day's calendar date (YYYY-MM-DD) instead of dayIndex |
| kind | string | (source=search_result) What the option is, for legacy object callers. stay = a search_stays property. activity = a search_activities product. place = a search_places result's itemDraft. Restored from resultId when you pass one. |
| text | string | (source=receipt) The confirmation text; omit when sending image/PDF bytes |
| time | any | Start time at the destination, HH:MM (a stay's check-in time; saved_places: the first place of each day) |
| stops | array | (source=stops) Each stop names its day with dayIndex or date |
| guests | any | (source=search_result) Stays: travelers sharing the room |
| option | object | (source=search_result) The option/offer object (or, for kind 'place', the itemDraft), unchanged |
| source* | string | stops = plain stops described in `stops`; saved_places = library places by savedPlaceIds, folderName or importId, with pins, photos and links intact; search_result = one search option by resultId + optionId; flight = a search_flights fare by searchId + offerId; train = a search_trains fare by searchId + journeyId; receipt = a booking confirmation (text, or contentType + data) filed on the trip |
| stopId | string | (source=receipt) Link the confirmation to this stop and mark it booked |
| tripId* | string | |
| checkIn | any | (source=search_result) Stays: required |
| offerId | string | (source=flight) The fare's id from that search |
| checkOut | any | (source=search_result) Stays: required |
| dayIndex | any | 0-based day for the stop (stops carry their own); or give date instead |
| importId | string | (source=saved_places) Everything an import found; the import's own day hints place each stop |
| optionId | string | Exact propertyId (stay), productId (activity), or id (place) from that search reply |
| resultId | string | The search reply's display.resultId; account-bound and retained for 30 minutes |
| searchId | string | (source=flight, train) The searchId returned by search_flights or search_trains |
| journeyId | string | (source=train) The journey's id from that search |
| folderName | string | (source=saved_places) Every place in this library folder |
| contentType | string | (source=receipt) Type of the base64 bytes in data |
| presentation | object | |
| savedPlaceIds | array | (source=saved_places) Place ids from list_library |
| spreadAcrossDays | boolean | (source=saved_places) Deal the places out across the trip's days in order instead of one day |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"tripId",
"source"
],
"properties": {
"data": {
"type": "string",
"maxLength": 8000000,
"description": "(source=receipt) Raw base64 bytes of the image or PDF, no data URL prefix"
},
"date": {
"anyOf": [
{
"$ref": "#/properties/stops/items/properties/date"
},
{
"type": "null"
}
],
"description": "The day's calendar date (YYYY-MM-DD) instead of dayIndex"
},
"kind": {
"enum": [
"stay",
"activity",
"place"
],
"type": "string",
"description": "(source=search_result) What the option is, for legacy object callers. stay = a search_stays property. activity = a search_activities product. place = a search_places result's itemDraft. Restored from resultId when you pass one."
},
"text": {
"type": "string",
"maxLength": 20000,
"description": "(source=receipt) The confirmation text; omit when sending image/PDF bytes"
},
"time": {
"anyOf": [
{
"$ref": "#/properties/stops/items/properties/time"
},
{
"type": "null"
}
],
"description": "Start time at the destination, HH:MM (a stay's check-in time; saved_places: the first place of each day)"
},
"stops": {
"type": "array",
"items": {
"type": "object",
"required": [
"type",
"title"
],
"properties": {
"lat": {
"type": "number",
"maximum": 90,
"minimum": -90
},
"lng": {
"type": "number",
"maximum": 180,
"minimum": -180
},
"cost": {
"type": "number",
"minimum": 0,
"description": "Estimated cost per person, MAJOR units (120 = $120)"
},
"date": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"description": "…or the day's calendar date"
},
"time": {
"type": "string",
"pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
"description": "Start time at the destination, 24h HH:MM"
},
"type": {
"enum": [
"flight",
"train",
"transport",
"stay",
"activity",
"food",
"note"
],
"type": "string",
"description": "flight | train | transport | stay | activity | food | note"
},
"title": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "Name of the place or plan, e.g. 'Senso-ji Temple'"
},
"origin": {
"type": "string",
"pattern": "^[A-Za-z]{3}$",
"description": "Flights only: departure airport IATA code (e.g. 'JFK'); gives the stop a live fare search link"
},
"address": {
"type": "string",
"maxLength": 400
},
"endTime": {
"$ref": "#/properties/stops/items/properties/time"
},
"dayIndex": {
"type": "integer",
"maximum": 59,
"minimum": 0,
"description": "0-based day"
},
"description": {
"type": "string",
"maxLength": 2000,
"description": "Why it's worth it, tips, context"
},
"destination": {
"type": "string",
"pattern": "^[A-Za-z]{3}$",
"description": "Flights only: arrival airport IATA code (e.g. 'LIS')"
},
"costCurrency": {
"type": "string",
"maxLength": 3,
"minLength": 3,
"description": "ISO code for cost; defaults to the trip currency"
},
"locationName": {
"type": "string",
"maxLength": 200,
"description": "Neighborhood/area, e.g. 'Asakusa'"
}
},
"additionalProperties": false
},
"maxItems": 90,
"description": "(source=stops) Each stop names its day with dayIndex or date"
},
"guests": {
"anyOf": [
{
"type": "integer",
"maximum": 10,
"minimum": 1
},
{
"type": "null"
}
],
"description": "(source=search_result) Stays: travelers sharing the room"
},
"option": {
"type": "object",
"description": "(source=search_result) The option/offer object (or, for kind 'place', the itemDraft), unchanged",
"additionalProperties": {}
},
"source": {
"enum": [
"stops",
"saved_places",
"search_result",
"flight",
"train",
"receipt"
],
"type": "string",
"description": "stops = plain stops described in `stops`; saved_places = library places by savedPlaceIds, folderName or importId, with pins, photos and links intact; search_result = one search option by resultId + optionId; flight = a search_flights fare by searchId + offerId; train = a search_trains fare by searchId + journeyId; receipt = a booking confirmation (text, or contentType + data) filed on the trip"
},
"stopId": {
"type": "string",
"format": "uuid",
"description": "(source=receipt) Link the confirmation to this stop and mark it booked"
},
"tripId": {
"type": "string",
"format": "uuid"
},
"checkIn": {
"anyOf": [
{
"$ref": "#/properties/stops/items/properties/date"
},
{
"type": "null"
}
],
"description": "(source=search_result) Stays: required"
},
"offerId": {
"type": "string",
"description": "(source=flight) The fare's id from that search"
},
"checkOut": {
"anyOf": [
{
"$ref": "#/properties/stops/items/properties/date"
},
{
"type": "null"
}
],
"description": "(source=search_result) Stays: required"
},
"dayIndex": {
"anyOf": [
{
"type": "integer",
"maximum": 59,
"minimum": 0
},
{
"type": "null"
}
],
"description": "0-based day for the stop (stops carry their own); or give date instead"
},
"importId": {
"type": "string",
"format": "uuid",
"description": "(source=saved_places) Everything an import found; the import's own day hints place each stop"
},
"optionId": {
"type": "string",
"maxLength": 300,
"minLength": 1,
"description": "Exact propertyId (stay), productId (activity), or id (place) from that search reply"
},
"resultId": {
"type": "string",
"format": "uuid",
"description": "The search reply's display.resultId; account-bound and retained for 30 minutes"
},
"searchId": {
"type": "string",
"description": "(source=flight, train) The searchId returned by search_flights or search_trains"
},
"journeyId": {
"type": "string",
"description": "(source=train) The journey's id from that search"
},
"folderName": {
"type": "string",
"maxLength": 80,
"minLength": 1,
"description": "(source=saved_places) Every place in this library folder"
},
"contentType": {
"enum": [
"image/jpeg",
"image/png",
"image/webp",
"application/pdf"
],
"type": "string",
"description": "(source=receipt) Type of the base64 bytes in data"
},
"presentation": {
"type": "object",
"properties": {
"layout": {
"enum": [
"compact",
"full"
],
"type": "string",
"description": "Compact cards or the full view; keeps booking, add and error actions available."
}
},
"additionalProperties": false
},
"savedPlaceIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"maxItems": 40,
"description": "(source=saved_places) Place ids from list_library"
},
"spreadAcrossDays": {
"type": "boolean",
"description": "(source=saved_places) Deal the places out across the trip's days in order instead of one day"
}
},
"additionalProperties": false
}Save a travel plan as a Dreamfare trip the traveler can open, edit with their crew, and book. Pass the full day-by-day plan in one call via days; stops are enriched shortly after creation (photos, map pins, booking links). Use plan_trip instead when the traveler wants Dreamfare's planner to build the days. To copy a trip, pass copyFromPublicationId (a trip from explore_trips; keeps the creator's credit) or copyFromTripId (one of the traveler's own) and no days. Before planning a destination, check list_library for the traveler's saves there and ask whether to include them (add_to_trip source=saved_places keeps their pins and links). Returns the trip and its URL; always give the traveler that URL. Returns data plus display.resultId; call display_card to show it. presentation (optional) shapes what is shown without changing the action: compact or full layout, and only the limit, ids or sections this tool advertises.
| Argument | Type | Description |
|---|---|---|
| days | array | Day-by-day plan; day 1 falls on startDate when dates are set |
| rooms | integer | |
| title | string | Required unless copying |
| adults | integer | Adults travelling; wins over partySize |
| endDate | any | |
| currency | string | Trip budgeting currency; defaults to the traveler's home currency, then USD |
| partySize | integer |
Delete a trip the traveler owns (also unpublishes it from Explore). Requires echoing the exact trip title as confirmTitle; only call this after the traveler explicitly asks to delete the trip. Returns data plus display.resultId; call display_card to show it.
| Argument | Type | Description |
|---|---|---|
| tripId* | string | |
| confirmTitle* | string | The trip's exact title, as confirmation |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"tripId",
"confirmTitle"
],
"properties": {
"tripId": {
"type": "string",
"format": "uuid"
},
"confirmTitle": {
"type": "string",
"description": "The trip's exact title, as confirmation"
}
},
"additionalProperties": false
}Show a Dreamfare card to the traveler: a trip's itinerary (tripId) or the details of an earlier result (resultId, from that tool's display.resultId). Call it once, after the requested work is done or when the traveler asks to see something; never after every intermediate call. It reads a saved snapshot retained for 30 minutes and never repeats a search, edit, import, message or charge. If a snapshot has expired, use a non-charging lookup to retain a new result; never repeat a trip/account edit, import or charge merely to display it. This is the only tool that opens a visual; every other tool returns data. presentation (optional) shapes what is shown without changing the action: compact or full layout, and only the limit, ids or sections this tool advertises.
| Argument | Type | Description |
|---|---|---|
| tripId | string | Show this trip's itinerary |
| resultId | string | Show an earlier result by its display.resultId; never invent this id |
| presentation | object |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"tripId": {
"type": "string",
"format": "uuid",
"description": "Show this trip's itinerary"
},
"resultId": {
"type": "string",
"format": "uuid",
"description": "Show an earlier result by its display.resultId; never invent this id"
},
"presentation": {
"type": "object",
"properties": {
"layout": {
"enum": [
"compact",
"full"
],
"type": "string",
"description": "Compact cards or the full view; keeps booking, add and error actions available."
},
"sections": {
"type": "array",
"items": {
"enum": [
"itinerary",
"budget",
"packing",
"tips",
"photos",
"highlights",
"facts",
"features",
"location",
"reviews",
"offers",
"verdict",
"table"
],
"type": "string"
},
"maxItems": 13,
"minItems": 1,
"description": "Show only these optional sections. Identity and essential actions remain available; omit to keep the full view."
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}Change what the traveler has saved, in one call: save a place, delete places, move places into a folder or out to unsorted, rename a place, create, rename or delete folders, and add or remove travel tips. Save a place when the traveler wants it remembered without putting it on a trip yet; put library places on a trip with add_to_trip source=saved_places. Ids and folder names come from list_library. Deleting a folder keeps its places as unsorted. Returns the places shelf, plus savedPlace and tips for the parts that ran. Returns data plus display.resultId; call display_card to show it. presentation (optional) shapes what is shown without changing the action: compact or full layout, and only the limit, ids or sections this tool advertises.
| Argument | Type | Description |
|---|---|---|
| move | array | Move places: folderName null means unsorted, and a new name creates the folder. |
| rename | array | Give saved places new titles. |
| addTips | array | Tips to write into the notebook. Leave areaName out for advice that travels everywhere. |
| savePlace | object | Remember one place. Saving a title already in the library is a no-op. |
| removeTips | array | Tip ids to delete (list_library with kind tips). |
| showFolder | string | Which folder the returned shelf shows. |
Every change to an existing trip in one batched call. Structural actions: update_trip (details and notes), update_stop / remove_stop / move_stop (by stopId from get_trip), add_day / update_day / remove_day (by 0-based dayIndex). Side actions: packing (the packing list), mark_booked (record a booking the traveler made), vote_stop (crew votes), refresh_stay_prices (re-quote partner-priced stays). Stage actions, at most one per call and run last: finalize locks the trip for sharing and booking, reopen unlocks it, publish puts a finalized trip on a public link and Explore, unpublish takes it off. Omitted fields keep their value; null clears. A finalized trip rejects structural edits, so reopen it in its own call first. remove_stop and remove_day delete data. Returns data plus display.resultId; call display_card to show it. presentation (optional) shapes what is shown without changing the action: compact or full layout, and only the limit, ids or sections this tool advertises.
| Argument | Type | Description |
|---|---|---|
| tripId* | string | |
| actions* | array | |
| presentation | object |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"tripId",
"actions"
],
"properties": {
"tripId": {
"type": "string",
"format": "uuid"
},
"actions": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"required": [
"action"
],
"properties": {
"notes": {
"anyOf": [
{
"type": "string",
"maxLength": 20000
},
{
"type": "null"
}
],
"description": "The trip notebook; null clears"
},
"rooms": {
"type": "integer",
"maximum": 8,
"minimum": 1,
"description": "Hotel rooms to search for"
},
"title": {
"type": "string",
"maxLength": 120,
"minLength": 1
},
"action": {
"type": "string",
"const": "update_trip",
"description": "Change trip details; omitted fields keep their value, null clears"
},
"adults": {
"type": "integer",
"maximum": 20,
"minimum": 1,
"description": "Adults travelling; partySize becomes adults + children"
},
"status": {
"enum": [
"draft",
"planned",
"booked",
"completed"
],
"type": "string",
"description": "draft | planned | booked | completed (owner only)"
},
"endDate": {
"$ref": "#/properties/actions/items/anyOf/0/properties/startDate"
},
"currency": {
"type": "string",
"maxLength": 3,
"minLength": 3
},
"partySize": {
"type": "integer",
"maximum": 20,
"minimum": 1
},
"startDate": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"description": "Days shift with the trip"
},
"cabinClass": {
"anyOf": [
{
"enum": [
"economy",
"premium_economy",
"business",
"first"
],
"type": "string"
},
{
"type": "null"
}
],
"description": "Cabin that flight searches open in; null means economy"
},
"description": {
"type": "string",
"maxLength": 2000
},
"childrenAges": {
"type": "array",
"items": {
"type": "integer",
"maximum": 17,
"minimum": 0
},
"maxItems": 12,
"description": "One age per child travelling; partner booking links pre-fill from these"
},
"coverImageUrl": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
],
"description": "Cover photo URL (a stop's imageUrl works); null goes back to the automatic cover"
},
"bookingDeadline": {
"anyOf": [
{
"$ref": "#/properties/actions/items/anyOf/0/properties/startDate"
},
{
"type": "null"
}
],
"description": "Book-by date: the crew is reminded a week out, the day before and on the day while stays or flights are unbooked; null clears"
},
"destinationName": {
"type": "string",
"maxLength": 120
},
"destinationCountryCode": {
"type": "string",
"maxLength": 2,
"minLength": 2
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"stopId"
],
"properties": {
"lat": {
"anyOf": [
{
"type": "number",
"maximum": 90,
"minimum": -90
},
{
"type": "null"
}
]
},
"lng": {
"anyOf": [
{
"type": "number",
"maximum": 180,
"minimum": -180
},
{
"type": "null"
}
]
},
"cost": {
"anyOf": [
{
"type": "number",
"minimum": 0
},
{
"type": "null"
}
],
"description": "MAJOR units; null clears"
},
"time": {
"anyOf": [
{
"type": "string",
"pattern": "^([01]\\d|2[0-3]):[0-5]\\d$"
},
{
"type": "null"
}
],
"description": "HH:MM; null clears the time"
},
"type": {
"enum": [
"flight",
"train",
"transport",
"stay",
"activity",
"food",
"note"
],
"type": "string"
},
"title": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"action": {
"type": "string",
"const": "update_stop",
"description": "Change one stop by stopId"
},
"stopId": {
"type": "string",
"format": "uuid"
},
"address": {
"anyOf": [
{
"type": "string",
"maxLength": 400
},
{
"type": "null"
}
]
},
"endTime": {
"anyOf": [
{
"$ref": "#/properties/actions/items/anyOf/1/properties/time/anyOf/0"
},
{
"type": "null"
}
]
},
"description": {
"anyOf": [
{
"type": "string",
"maxLength": 2000
},
{
"type": "null"
}
]
},
"costCurrency": {
"$ref": "#/properties/actions/items/anyOf/0/properties/currency"
},
"locationName": {
"anyOf": [
{
"type": "string",
"maxLength": 200
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"stopId"
],
"properties": {
"action": {
"type": "string",
"const": "remove_stop",
"description": "Delete one stop"
},
"stopId": {
"type": "string",
"format": "uuid"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"stopId",
"toDayIndex"
],
"properties": {
"action": {
"type": "string",
"const": "move_stop",
"description": "Move a stop to another day"
},
"stopId": {
"type": "string",
"format": "uuid"
},
"position": {
"type": "integer",
"minimum": 0,
"description": "0-based position in the day; omit = end"
},
"toDayIndex": {
"type": "integer",
"maximum": 59,
"minimum": 0
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action"
],
"properties": {
"date": {
"$ref": "#/properties/actions/items/anyOf/0/properties/startDate"
},
"title": {
"type": "string",
"maxLength": 200
},
"action": {
"type": "string",
"const": "add_day",
"description": "Append a day"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"dayIndex"
],
"properties": {
"date": {
"anyOf": [
{
"$ref": "#/properties/actions/items/anyOf/0/properties/startDate"
},
{
"type": "null"
}
]
},
"notes": {
"anyOf": [
{
"type": "string",
"maxLength": 2000
},
{
"type": "null"
}
]
},
"title": {
"anyOf": [
{
"type": "string",
"maxLength": 200
},
{
"type": "null"
}
]
},
"action": {
"type": "string",
"const": "update_day",
"description": "Change a day's title, date or notes"
},
"dayIndex": {
"$ref": "#/properties/actions/items/anyOf/3/properties/toDayIndex"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"dayIndex"
],
"properties": {
"action": {
"type": "string",
"const": "remove_day",
"description": "Delete a day and its stops"
},
"dayIndex": {
"$ref": "#/properties/actions/items/anyOf/3/properties/toDayIndex"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action"
],
"properties": {
"add": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string",
"maxLength": 120,
"minLength": 1
},
{
"type": "object",
"required": [
"label"
],
"properties": {
"label": {
"type": "string",
"maxLength": 120,
"minLength": 1
},
"personal": {
"type": "boolean",
"default": false
}
},
"additionalProperties": false
}
]
},
"maxItems": 40,
"description": "Labels to add: plain strings, or {label, personal} for an item only this traveler sees"
},
"check": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"maxItems": 60,
"description": "Item ids to tick"
},
"action": {
"type": "string",
"const": "packing",
"description": "Edit the packing list: add labels, tick, untick or remove item ids from get_trip"
},
"remove": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"maxItems": 60,
"description": "Item ids to delete"
},
"uncheck": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"maxItems": 60,
"description": "Item ids to untick"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"stopId"
],
"properties": {
"action": {
"type": "string",
"const": "mark_booked",
"description": "Record that the traveler booked a stop, on the partner site or elsewhere; a booking made through the stop's bookingUrl opens its commission credit"
},
"stopId": {
"type": "string",
"format": "uuid"
},
"travelers": {
"type": "integer",
"maximum": 16,
"minimum": 1,
"description": "How many travelers the booking covers (group trips)"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"stopId",
"value"
],
"properties": {
"value": {
"enum": [
1,
-1,
0
],
"type": "number",
"description": "1 = thumbs up, -1 = thumbs down, 0 = take the vote back"
},
"action": {
"type": "string",
"const": "vote_stop",
"description": "Vote on a stop the crew is deciding about"
},
"stopId": {
"type": "string",
"format": "uuid"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action"
],
"properties": {
"action": {
"type": "string",
"const": "refresh_stay_prices",
"description": "Re-quote every upcoming partner-priced stay against live rates and report what moved; at most once per stay per day"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action"
],
"properties": {
"action": {
"type": "string",
"const": "finalize",
"description": "Lock the trip for sharing and booking (owner only); a finalized trip rejects edits until reopened"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action"
],
"properties": {
"action": {
"type": "string",
"const": "reopen",
"description": "Unlock a finalized trip for editing (owner only); unpublish first if it is public"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action"
],
"properties": {
"tags": {
"type": "array",
"items": {
"type": "string",
"maxLength": 40,
"minLength": 1
},
"maxItems": 10
},
"title": {
"type": "string",
"maxLength": 120,
"description": "Public title; defaults to the trip's"
},
"action": {
"type": "string",
"const": "publish",
"description": "Publish a finalized trip to a public link and Explore, or republish it after edits (owner only); bookings from the public copy earn the author"
},
"summary": {
"type": "string",
"maxLength": 2000
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action"
],
"properties": {
"action": {
"type": "string",
"const": "unpublish",
"description": "Take the trip off its public link and Explore (owner only)"
}
},
"additionalProperties": false
}
]
},
"maxItems": 50,
"minItems": 1
},
"presentation": {
"type": "object",
"properties": {
"layout": {
"enum": [
"compact",
"full"
],
"type": "string",
"description": "Compact cards or the full view; keeps booking, add and error actions available."
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}Trips other travelers published on Dreamfare, by destination and free text: real itineraries with stops, photos and creator credit. Give the traveler their own editable copy with create_trip copyFromPublicationId. Use it for inspiration and for how locals actually route a city, not for live prices. Continue the same search with nextOffset. Retains an account-bound result for 30 minutes for later display; does not copy, publish or change a trip. Returns data plus display.resultId; call display_card to show it. presentation (optional) shapes what is shown without changing the action: compact or full layout, and only the limit, ids or sections this tool advertises.
| Argument | Type | Description |
|---|---|---|
| q | string | Words in the title or summary. |
| sort | string | popular: most liked, saved and copied first. newest: most recently published first. |
| limit | integer | How many trips to return. |
| offset | integer | Skip this many trips. Pass the nextOffset from the previous call. |
| destination | string | City, region or country the trip goes to. |
| presentation | object |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"q": {
"type": "string",
"maxLength": 80,
"minLength": 1,
"description": "Words in the title or summary."
},
"sort": {
"enum": [
"popular",
"newest"
],
"type": "string",
"default": "popular",
"description": "popular: most liked, saved and copied first. newest: most recently published first."
},
"limit": {
"type": "integer",
"default": 8,
"maximum": 12,
"minimum": 1,
"description": "How many trips to return."
},
"offset": {
"type": "integer",
"default": 0,
"maximum": 1000,
"minimum": 0,
"description": "Skip this many trips. Pass the nextOffset from the previous call."
},
"destination": {
"type": "string",
"maxLength": 80,
"minLength": 2,
"description": "City, region or country the trip goes to."
},
"presentation": {
"type": "object",
"properties": {
"ids": {
"type": "array",
"items": {
"type": "string",
"maxLength": 300,
"minLength": 1
},
"maxItems": 20,
"minItems": 1,
"description": "Show exactly these publicationId values from the retrieved results, in this order. Missing or duplicate IDs fail; do not combine with a smaller presentation.limit."
},
"limit": {
"type": "integer",
"maximum": 20,
"minimum": 1,
"description": "Show at most this many of the retrieved results. Use the tool's search limit to retrieve a larger candidate pool."
},
"layout": {
"enum": [
"compact",
"full"
],
"type": "string",
"description": "Compact cards or the full view; keeps booking, add and error actions available."
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}The traveler's Dreamfare account snapshot: profile, membership tier, Stardust credits, and wallet balance (commission earned through tracked bookings). Reading also initializes or reconciles membership and credit allowance records: expired membership can end, the monthly credit period can roll, and the grant can change with the tier. This does not spend credits, purchase travel, or change the wallet balance. Returns data plus display.resultId; call display_card to show it. presentation (optional) shapes what is shown without changing the action: compact or full layout, and only the limit, ids or sections this tool advertises.
| Argument | Type | Description |
|---|---|---|
| presentation | object |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"presentation": {
"type": "object",
"properties": {
"layout": {
"enum": [
"compact",
"full"
],
"type": "string",
"description": "Compact cards or the full view; keeps booking, add and error actions available."
},
"sections": {
"type": "array",
"items": {
"enum": [
"preferences",
"credits"
],
"type": "string"
},
"maxItems": 2,
"minItems": 1,
"description": "Show only these optional sections. Identity and essential actions remain available; omit to keep the full view."
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}Read a trip, or list the traveler's trips (own and shared, newest first) when tripId is omitted. A trip comes back with its days and stops (stopIds for edit_trip), the packing list, tips for the destination, the sharing state, and per-stop booking links; bookings made through a stop's bookingUrl earn the traveler commission back. include adds essentials (tracked partner links for an eSIM, rental cars and transfers), crew (members, roles, open invites), receipts (filed booking confirmations) and chat (the crew chat, newest last; chatBefore pages back). Read silently while planning; show the plan with display_card. Retains an account-bound result for 30 minutes for later display; does not edit the trip, mark chat read or make a booking. Returns data plus display.resultId; call display_card to show it.
| Argument | Type | Description |
|---|---|---|
| tripId | string | Omit to list the traveler's trips instead |
| include | array | Extra sections to fold in: essentials = tracked eSIM, rental-car and transfer links for the destination; crew = owner, collaborators with roles, and open invites; receipts = booking confirmations filed on the trip; chat = the crew chat's latest messages, including polls |
| chatLimit | integer | With include chat: how many messages |
| chatBefore | string | With include chat: only messages before this ISO timestamp, to page further back |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"tripId": {
"type": "string",
"format": "uuid",
"description": "Omit to list the traveler's trips instead"
},
"include": {
"type": "array",
"items": {
"enum": [
"essentials",
"crew",
"receipts",
"chat"
],
"type": "string"
},
"maxItems": 4,
"description": "Extra sections to fold in: essentials = tracked eSIM, rental-car and transfer links for the destination; crew = owner, collaborators with roles, and open invites; receipts = booking confirmations filed on the trip; chat = the crew chat's latest messages, including polls"
},
"chatLimit": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "With include chat: how many messages"
},
"chatBefore": {
"type": "string",
"format": "date-time",
"description": "With include chat: only messages before this ISO timestamp, to page further back"
}
},
"additionalProperties": false
}Pull the real places and travel tips out of something the traveler shares and save them to their library. source url reads a TikTok, Instagram, YouTube, Facebook, Reddit, blog or other travel page on the Dreamfare server, subject to the source being reachable. source text reads words they pasted. source file reads a screenshot or travel PDF. Runs in the background: poll list_library with the returned importId until status is done or failed, about 20 to 90 seconds. Every place and tip is saved with its source, so list_library finds them later. Once done, add them to a trip with add_to_trip source=saved_places (importId keeps the pins, photos and tips) or plan days around them with plan_trip. General travel tips are advice, not stops. Costs Stardust credits exactly like importing in the app, and a failed import refunds them. Identical input within 10 minutes returns the same importId without another charge, including a failed job. Poll that job instead of starting it again. Use a new operationId only when the traveler explicitly asks for a fresh extraction; keep it unchanged when retrying. Returns data plus display.resultId; call display_card to show it. presentation (optional) shapes what is shown without changing the action: compact or full layout, and only the limit, ids or sections this tool advertises.
| Argument | Type | Description |
|---|---|---|
| url | string | (source=url) The video, post or blog address, exactly as shared. |
| data | string | (source=file) Raw base64 bytes, no data URL prefix. |
| text | string | (source=text) The pasted text, verbatim. At least 40 characters. |
| source* | string |
Read what the traveler has saved: their places with folders, their travel-tips notebook, and the results of an import. Topic/area search can refresh missing or expired venue photos from public place providers without changing the saved entries. Pass importId to follow an import started by import_places: while status is neither done nor failed, call again after about 15 seconds. Pass query or area to search places and tips together, with the source each one came from. Pass folderName, type or sort to browse the places shelf itself, and offset with the returned nextOffset to continue. Tips are advice, never itinerary stops. Put library places on a trip with add_to_trip source=saved_places (by savedPlaceIds, folderName or importId), or plan days around them with plan_trip. Retains an account-bound result for 30 minutes for later display; does not start an import, spend credits or change library entries. Returns data plus display.resultId; call display_card to show it. presentation (optional) shapes what is shown without changing the action: compact or full layout, and only the limit, ids or sections this tool advertises.
| Argument | Type | Description |
|---|---|---|
| area | string | Destination to scope the answer to, such as 'Lisbon'. General tips come with it. |
| kind | string | What to read. all: saved places and tips together. places: saved places only. tips: the tips notebook only. |
| sort | string | Places only. newest: most recently saved first. oldest: earliest saved first. name: alphabetical by title. |
| type | string | Places only. all: everything saved. places: individual places. areas: whole-city or region entries, which are destinations rather than stops. |
| limit |
Everything that changes who is on a trip, plus the crew chat, in one call: invite someone, change a member's role, remove a member, leave the trip, revoke an open invite, and post a message. Read the crew and the chat first with get_trip include crew and include chat: collaboratorId, invite ids and member userIds all come from there. Anyone who can edit the trip may invite and post, only the owner may set roles, remove members or revoke invites, and any member other than the owner may leave. An emailed invite leaves Dreamfare. Returns the crew, plus invite and posted for the parts that ran. Returns data plus display.resultId; call display_card to show it. presentation (optional) shapes what is shown without changing the action: compact or full layout, and only the limit, ids or sections this tool advertises.
| Argument | Type | Description |
|---|---|---|
| post | object | Say something to the crew in the trip's chat. |
| leave | boolean | Remove yourself from the trip. The owner cannot leave; delete the trip instead. |
| invite | object | Create an invite link. With no email, the returned link is what to share. |
| remove | array | Owner only: collaboratorIds to take off the trip. |
| tripId* | string | The trip whose crew is changing. |
| setRole | array | Owner only: change what these members may do. |
Build a complete day-by-day trip in one call with Dreamfare's own planner: real venues with their opening hours, a stay, activities from partner inventory, the traveler's saved places woven in, pins, photos and booking links, all stitched server-side in about 10 seconds. Prefer it for 'plan me N days in X'. Use create_trip when the traveler dictated the stops themselves. The traveler's saved places at the destination count even when they do not mention them: pass savedPlaceIds or folderName for the ones they want in, or includeSavedPlaces (true = all of them, false = none). Leave all three out and, when they have saves there, the call returns them unbuilt and uncharged so you can ask first. Costs Stardust credits like planning in the app, and get_profile shows the balance. Give the traveler the trip URL. Returns data plus display.resultId; call display_card to show it. presentation (optional) shapes what is shown without changing the action: compact or full layout, and only the limit, ids or sections this tool advertises.
| Argument | Type | Description |
|---|---|---|
| brief* | string | What the traveler wants, in their words: pace, interests, budget, must-sees, dietary needs |
| title | string | Trip title; defaults to the destination. |
| endDate | any | |
| currency | string | ISO currency code for the trip's prices; defaults to the traveler's home currency. |
| logistics | object | Already-booked stays and flights; the planner keeps these fixed and plans around them. |
Research options from an earlier search: one in depth, or two to five side by side. Pass resultId (that search reply's display.resultId) with optionIds. One id returns everything known about that option: photos, an editorial summary and what reviewers say, key facts (stars, guest score, capacity, cancellation and instant-book policies, duration, languages, meeting point, inclusions, itinerary, opening hours, price level, phone, website), features, the exact location, and prices per booking site for stays plus tours and tickets at landmarks. Two to five ids return one table: price, rating and reviews, distance, duration, cancellation and features, with the best cell in each row marked and verdict naming the winners. Use it when the traveler asks about one option ('tell me more', 'is it near', 'what's included', 'can I cancel', 'is it open Sunday'), when they are weighing a few ('which of these', 'A or B', 'the cheapest that is still well rated'), and before recommending one. Every option is researched fresh, so the answer is exact rather than a summary of the search screen. Stays: pass checkIn, checkOut and guests so prices cover the traveler's dates. Legacy callers without a resultId can echo search objects in option or options, pass a search_places placeId as id, or a name with destination. Attach what the traveler picks with add_to_trip source 'search_result', reusing the same resultId and optionId. Retains an account-bound research result for 30 minutes for later display. Does not reserve, purchase or spend credits. Returns data plus display.resultId; call display_card to show it. presentation (optional) shapes what is shown without changing the action: compact or full layout, and only the limit, ids or sections this tool advertises.
| Argument | Type | Description |
|---|---|---|
| id | string | A search_places result's placeId (kind 'place') |
| date | any | Activities: the day the traveler has in mind |
| kind | string |
Search bookable activities, tours and experiences for a destination. Say what kind with q ('food tour', 'sunset cruise', 'day trip to Sintra') and narrow with category, flags, tags, duration or minRating. Default order is partner relevance: for a budget or a 'cheaper' ask set maxPrice or minPrice and sort cheapest instead of repeating the search, and read priceRange for what was found. Each result carries tags, flags and a short description. Plain activity stops added with add_to_trip source 'stops' are matched to partners automatically, so search here only when the traveler wants options. Research one, or weigh two to five, with research_options using this reply's display.resultId and each productId; attach the pick with add_to_trip source 'search_result'. Retains an account-bound result for 30 minutes for later display, research or attachment. Does not purchase or spend credits. Returns data plus display.resultId; call display_card to show it. presentation (optional) shapes what is shown without changing the action: compact or full layout, and only the limit, ids or sections this tool advertises.
| Argument | Type | Description |
|---|---|---|
| q | string | What kind of experience, in the traveler's words: 'food tour', 'sunset cruise', 'kayaking' |
| date | string | |
| name | string | ONE specific product the traveler named ('Devour Lisbon food tour'): found on its own terms and leads the list. A kind of experience is q |
| near | string | A landmark, neighborhood or hotel inside the destination to search around: products with a known meeting point stay within 5 km (or maxDistanceKm) and report distanceMeters, nearest first |
| sort | string |
Search Trip.com rental cars for an airport pickup and drop-off, with exact local dates and times, the driver's age and the licence's issuing country. Ask for a missing age or licence country; never guess either. Trip.com quotes a 30 to 60 driver-age band for that range, while supplier eligibility uses the real age. Returned prices are rental totals, not daily rates, and deposits sit outside them. Links open a search the traveler completes: they confirm the vehicle, the policies and the final price there. There is no in-app booking, and a failed source never means no cars exist. Retains an account-bound result for 30 minutes for later display. Does not reserve a car or spend credits. Returns data plus display.resultId; call display_card to show it. presentation (optional) shapes what is shown without changing the action: compact or full layout, and only the limit, ids or sections this tool advertises.
| Argument | Type | Description |
|---|---|---|
| currency | string | |
| minSeats | integer | Keep only cars with at least this many seats |
| driverAge* | integer | The driver's actual age; ask, never guess |
| pickupDate* | string | |
| pickupTime* | string | Local pickup time, HH:MM |
| dropoffDate* | any | |
Search and compare real flights for a route and dates, or re-read an earlier board. A fresh search starts a server-side provider search job and retains its board; it does not book or purchase a flight. origin and destination take an IATA airport or metro code, or a plain city or airport name that is resolved here; when several cities match or none does, the reply is an error carrying candidates, so ask the traveler and search again with a code. Pass searchId to filter, sort or re-read a board without another scrape; a partial board can gain fares when read again. Every fare carries the quote of each site that answered. Never imply a site that did not answer was searched. Returned amounts, minTotalAmount and maxTotalAmount are whole-party integer minor units; maxTotal and minTotal take normal currency units and priceBasis says whether they mean the party or a seat. Lead with the per-seat price and its seats multiplier when the party buys more than one seat, then name the whole-party total once. Clock filters are local to each departure or arrival airport. For a deadline such as home by Sunday evening resolve the exact date and use returnArriveBy; arriveBy is the outbound equivalent. bookingUrl opens the exact itinerary on bookOn, itineraryUrl is that provider's own page, sourceUrl is research evidence only. Attach a fare with add_to_trip source 'flight', this searchId and the fare's offerId. Prices are indicative until the traveler books. Returns data plus display.resultId; call display_card to show it.
| Argument | Type | Description |
|---|---|---|
| sort | any | best = balanced price, time and connections (default) | cheapest = lowest whole-party fare | fastest = shortest elapsed journey | fewest_stops = fewest connections |
| cabin | string | economy = the standard cabin | premium_economy = the extra-legroom cabin | business = lie-flat or wide seat | first = the top cabin |
| limit | any | Maximum fares to return, in requested sort order. Use 1 for one flight or 3 for three; default 3. Return fewer only when fewer are available. Maximum 60. |
Find real venues for a destination: restaurants, activities, hotels, landmarks and shopping, with ratings, pins and photos, from partner inventory plus cached Google Places. Use it to ground a plan in real places. For hotels pass checkIn and checkOut, or use search_stays: without them prices cover a sample window a month out and the reply says so in pricedWindow, and a hotel added to a day is re-dated and re-quoted. Narrow with openNow or openAt, priceLevels, minRating, and near with radiusKm. minRating reads each source's own scale: hotels run 0 to 10, Google places and tours 0 to 5. Research a result, or weigh two to five, with research_options using this reply's display.resultId and the result's id; attach the pick with add_to_trip source 'search_result', which keeps its pin, photo and any partner bookability. Retains an account-bound result for 30 minutes for later display, research or attachment. Does not save library entries, edit trips or spend credits. Returns data plus display.resultId; call display_card to show it. presentation (optional) shapes what is shown without changing the action: compact or full layout, and only the limit, ids or sections this tool advertises.
| Argument | Type | Description |
|---|---|---|
| q | string | Refinement, e.g. 'ramen', 'sunset cruise' |
| kind* | string | activity = tours and experiences | hotel = places to stay | restaurant = places to eat | shopping = shops and markets | landmark = sights and attractions |
| near | string | A landmark or neighborhood inside the region to search around |
| sort | string | best = relevance (default) | cheapest = lowest price first | rating = best rated first |
| limit |
Search stays for a city and exact dates. Prices include taxes and fees for the quoted accommodation, and guests is the party sharing it, not a room count. Use budget {amount, currency, basis:'per_night'} or maxNightlyAmount in integer minor units (USD 15000 is $150), and sort cheapest when the traveler wants cheaper. Set constraintMode strict for real requirements; prefer allows labeled alternatives. near searches around a landmark, name finds one named property, and keywords matches style words in listing names. For hotels near food, galleries or other interests pass interests: each one is resolved to real places at the destination and matched by verified straight-line distance. Never call that distance a walking time, and claim no match without verified places. Property type is inferred from listing evidence, not certified by the supplier. No matches and a provider failure are different answers; never invent a matching quote. Research a property with research_options using this reply's display.resultId and the property's propertyId, attach it with add_to_trip source 'search_result', and present the returned bookingUrl for booking. Retains an account-bound result for 30 minutes for later display, research or attachment. Does not reserve, book or spend credits. Returns data plus display.resultId; call display_card to show it. presentation (optional) shapes what is shown without changing the action: compact or full layout, and only the limit, ids or sections this tool advertises.
| Argument | Type | Description |
|---|---|---|
| name | any | One specific named hotel; a style such as boutique belongs in keywords |
| near | any | Landmark or neighborhood inside destination; strict mode uses a 5 km radius unless maxDistanceKm is supplied |
| sort | any | best = provider relevance (default) | cheapest = lowest nightly price | rating = best guest score first | distance = closest to near or the city center first |
Search real dated train fares for a route, or re-read an earlier search. Results carry departures, arrivals, operators, durations and changes. Prices cover the requested adults, and returnOptions are separate one-way quotes. Pass searchId alone to filter or sort a search without asking the sellers again; pass searchId with journeyId for one fare's stored details. Start a fresh search when the route, date, currency or passenger count changes. A source failure does not mean no trains run. Never substitute a promotional from-price, a seller search page or a generic listing for an individual fare. Attach a fare with add_to_trip source 'train', this searchId and the unchanged journeyId. Stores fresh quotes under searchId for later refinement or attachment and retains an account-bound display result for 30 minutes. Does not reserve a seat, issue tickets or spend credits. Returns data plus display.resultId; call display_card to show it. presentation (optional) shapes what is shown without changing the action: compact or full layout, and only the limit, ids or sections this tool advertises.
| Argument | Type | Description |
|---|---|---|
| sort | string | cheapest = lowest whole-party fare (default) | fastest = shortest journey | earliest = first departure |
| limit | integer | |
| origin | string | Where the journey starts, as a city or station name. Rail has no universal station codes. Omit only when refining with searchId. |
| currency | string | |
| searchId | string | Refine an earlier search instead of asking the sellers again: the searchId it returned. Route, date, currency and passengers stay fixed. |
Update profile fields: display name, bio, home currency, nationality, and the visited-countries list. Omitted fields keep their value. visitedCountries replaces the whole list, so read get_profile first when adding to it. Returns data plus display.resultId; call display_card to show it. presentation (optional) shapes what is shown without changing the action: compact or full layout, and only the limit, ids or sections this tool advertises.
| Argument | Type | Description |
|---|---|---|
| bio | any | Short profile blurb; null clears it. |
| displayName | string | The name other travelers see. |
| nationality | any | ISO alpha-2 country code of the passport; null clears it. |
| homeCurrency | string | ISO currency code new trips and prices default to. |
| presentation | object | |
| visitedCountries | array | ISO alpha-2 codes of every country visited; replaces the whole list. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"bio": {
"anyOf": [
{
"type": "string",
"maxLength": 400
},
{
"type": "null"
}
],
"description": "Short profile blurb; null clears it."
},
"displayName": {
"type": "string",
"maxLength": 60,
"minLength": 1,
"description": "The name other travelers see."
},
"nationality": {
"anyOf": [
{
"type": "string",
"maxLength": 2,
"minLength": 2
},
{
"type": "null"
}
],
"description": "ISO alpha-2 country code of the passport; null clears it."
},
"homeCurrency": {
"type": "string",
"maxLength": 3,
"minLength": 3,
"description": "ISO currency code new trips and prices default to."
},
"presentation": {
"type": "object",
"properties": {
"layout": {
"enum": [
"compact",
"full"
],
"type": "string",
"description": "Compact cards or the full view; keeps booking, add and error actions available."
}
},
"additionalProperties": false
},
"visitedCountries": {
"type": "array",
"items": {
"type": "string",
"maxLength": 2,
"minLength": 2
},
"maxItems": 300,
"description": "ISO alpha-2 codes of every country visited; replaces the whole list."
}
},
"additionalProperties": false
}| startDate | string |
| cabinClass | any |
| description | string |
| childrenAges | array | One age per child travelling |
| presentation | object |
| copyFromTripId | string | Duplicate one of the traveler's own trips |
| destinationName | string | City or region, e.g. 'Tokyo' |
| copyFromPublicationId | string | Copy a published trip (publicationId from explore_trips) into the traveler's account |
| destinationCountryCode | string | ISO 3166-1 alpha-2 |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"days": {
"type": "array",
"items": {
"type": "object",
"properties": {
"stops": {
"type": "array",
"items": {
"type": "object",
"required": [
"type",
"title"
],
"properties": {
"lat": {
"type": "number",
"maximum": 90,
"minimum": -90
},
"lng": {
"type": "number",
"maximum": 180,
"minimum": -180
},
"cost": {
"type": "number",
"minimum": 0,
"description": "Estimated cost per person, MAJOR units (120 = $120)"
},
"time": {
"type": "string",
"pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
"description": "Start time at the destination, 24h HH:MM"
},
"type": {
"enum": [
"flight",
"train",
"transport",
"stay",
"activity",
"food",
"note"
],
"type": "string",
"description": "flight | train | transport | stay | activity | food | note"
},
"title": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "Name of the place or plan, e.g. 'Senso-ji Temple'"
},
"origin": {
"type": "string",
"pattern": "^[A-Za-z]{3}$",
"description": "Flights only: departure airport IATA code (e.g. 'JFK'); gives the stop a live fare search link"
},
"address": {
"type": "string",
"maxLength": 400
},
"endTime": {
"$ref": "#/properties/days/items/properties/stops/items/properties/time"
},
"description": {
"type": "string",
"maxLength": 2000,
"description": "Why it's worth it, tips, context"
},
"destination": {
"type": "string",
"pattern": "^[A-Za-z]{3}$",
"description": "Flights only: arrival airport IATA code (e.g. 'LIS')"
},
"costCurrency": {
"$ref": "#/properties/currency",
"description": "ISO code for cost; defaults to the trip currency"
},
"locationName": {
"type": "string",
"maxLength": 200,
"description": "Neighborhood/area, e.g. 'Asakusa'"
}
},
"additionalProperties": false
},
"default": [],
"maxItems": 20
},
"title": {
"type": "string",
"maxLength": 200,
"description": "Theme, e.g. 'Old town + food tour'"
}
},
"additionalProperties": false
},
"maxItems": 30,
"description": "Day-by-day plan; day 1 falls on startDate when dates are set"
},
"rooms": {
"type": "integer",
"maximum": 8,
"minimum": 1
},
"title": {
"type": "string",
"maxLength": 120,
"minLength": 1,
"description": "Required unless copying"
},
"adults": {
"type": "integer",
"maximum": 20,
"minimum": 1,
"description": "Adults travelling; wins over partySize"
},
"endDate": {
"$ref": "#/properties/startDate"
},
"currency": {
"type": "string",
"maxLength": 3,
"minLength": 3,
"description": "Trip budgeting currency; defaults to the traveler's home currency, then USD"
},
"partySize": {
"type": "integer",
"maximum": 20,
"minimum": 1
},
"startDate": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$"
},
"cabinClass": {
"anyOf": [
{
"enum": [
"economy",
"premium_economy",
"business",
"first"
],
"type": "string"
},
{
"type": "null"
}
]
},
"description": {
"type": "string",
"maxLength": 2000
},
"childrenAges": {
"type": "array",
"items": {
"type": "integer",
"maximum": 17,
"minimum": 0
},
"maxItems": 12,
"description": "One age per child travelling"
},
"presentation": {
"type": "object",
"properties": {
"layout": {
"enum": [
"compact",
"full"
],
"type": "string",
"description": "Compact cards or the full view; keeps booking, add and error actions available."
}
},
"additionalProperties": false
},
"copyFromTripId": {
"type": "string",
"format": "uuid",
"description": "Duplicate one of the traveler's own trips"
},
"destinationName": {
"type": "string",
"maxLength": 120,
"description": "City or region, e.g. 'Tokyo'"
},
"copyFromPublicationId": {
"type": "string",
"format": "uuid",
"description": "Copy a published trip (publicationId from explore_trips) into the traveler's account"
},
"destinationCountryCode": {
"type": "string",
"maxLength": 2,
"minLength": 2,
"description": "ISO 3166-1 alpha-2"
}
},
"additionalProperties": false
}| deletePlaces |
| array |
| Saved place ids to delete from the library. |
| presentation | object |
| createFolders | array | Folder names to create; an existing name is left alone. |
| deleteFolders | array | Delete folders by name; their places survive as unsorted. |
| renameFolders | array | Rename folders by name. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"move": {
"type": "array",
"items": {
"type": "object",
"required": [
"placeId",
"folderName"
],
"properties": {
"placeId": {
"type": "string",
"format": "uuid"
},
"folderName": {
"anyOf": [
{
"type": "string",
"maxLength": 60
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
"maxItems": 50,
"description": "Move places: folderName null means unsorted, and a new name creates the folder."
},
"rename": {
"type": "array",
"items": {
"type": "object",
"required": [
"placeId",
"title"
],
"properties": {
"title": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"placeId": {
"type": "string",
"format": "uuid"
}
},
"additionalProperties": false
},
"maxItems": 50,
"description": "Give saved places new titles."
},
"addTips": {
"type": "array",
"items": {
"type": "object",
"required": [
"body"
],
"properties": {
"body": {
"type": "string",
"maxLength": 500,
"minLength": 1,
"description": "The advice itself, in one or two sentences."
},
"areaName": {
"type": "string",
"maxLength": 120,
"minLength": 1,
"description": "Scope it to this place so it resurfaces when a trip goes there."
},
"areaCountryCode": {
"type": "string",
"maxLength": 2,
"minLength": 2,
"description": "ISO alpha-2 country code of areaName."
}
},
"additionalProperties": false
},
"maxItems": 30,
"description": "Tips to write into the notebook. Leave areaName out for advice that travels everywhere."
},
"savePlace": {
"type": "object",
"required": [
"place"
],
"properties": {
"place": {
"type": "object",
"required": [
"type",
"title"
],
"properties": {
"lat": {
"type": "number",
"maximum": 90,
"minimum": -90
},
"lng": {
"type": "number",
"maximum": 180,
"minimum": -180
},
"cost": {
"type": "number",
"minimum": 0,
"description": "Estimated cost per person, MAJOR units (120 = $120)"
},
"time": {
"type": "string",
"pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
"description": "Start time at the destination, 24h HH:MM"
},
"type": {
"enum": [
"flight",
"train",
"transport",
"stay",
"activity",
"food",
"note"
],
"type": "string",
"description": "flight | train | transport | stay | activity | food | note"
},
"title": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "Name of the place or plan, e.g. 'Senso-ji Temple'"
},
"origin": {
"type": "string",
"pattern": "^[A-Za-z]{3}$",
"description": "Flights only: departure airport IATA code (e.g. 'JFK'); gives the stop a live fare search link"
},
"address": {
"type": "string",
"maxLength": 400
},
"endTime": {
"$ref": "#/properties/savePlace/properties/place/properties/time"
},
"description": {
"type": "string",
"maxLength": 2000,
"description": "Why it's worth it, tips, context"
},
"destination": {
"type": "string",
"pattern": "^[A-Za-z]{3}$",
"description": "Flights only: arrival airport IATA code (e.g. 'LIS')"
},
"costCurrency": {
"type": "string",
"maxLength": 3,
"minLength": 3,
"description": "ISO code for cost; defaults to the trip currency"
},
"locationName": {
"type": "string",
"maxLength": 200,
"description": "Neighborhood/area, e.g. 'Asakusa'"
}
},
"additionalProperties": false
},
"subtitle": {
"type": "string",
"maxLength": 200,
"description": "One line of context, such as 'Lisbon · viewpoint'."
},
"folderName": {
"type": "string",
"maxLength": 60,
"minLength": 1,
"description": "File it here; the folder is created when it is new."
}
},
"description": "Remember one place. Saving a title already in the library is a no-op.",
"additionalProperties": false
},
"removeTips": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"maxItems": 60,
"description": "Tip ids to delete (list_library with kind tips)."
},
"showFolder": {
"type": "string",
"maxLength": 60,
"description": "Which folder the returned shelf shows."
},
"deletePlaces": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"maxItems": 50,
"description": "Saved place ids to delete from the library."
},
"presentation": {
"type": "object",
"properties": {
"layout": {
"enum": [
"compact",
"full"
],
"type": "string",
"description": "Compact cards or the full view; keeps booking, add and error actions available."
}
},
"additionalProperties": false
},
"createFolders": {
"type": "array",
"items": {
"type": "string",
"maxLength": 60,
"minLength": 1
},
"maxItems": 20,
"description": "Folder names to create; an existing name is left alone."
},
"deleteFolders": {
"type": "array",
"items": {
"type": "string",
"maxLength": 60,
"minLength": 1
},
"maxItems": 20,
"description": "Delete folders by name; their places survive as unsorted."
},
"renameFolders": {
"type": "array",
"items": {
"type": "object",
"required": [
"from",
"to"
],
"properties": {
"to": {
"type": "string",
"maxLength": 60,
"minLength": 1
},
"from": {
"type": "string",
"maxLength": 60,
"minLength": 1
}
},
"additionalProperties": false
},
"maxItems": 20,
"description": "Rename folders by name."
}
},
"additionalProperties": false
}| Where the places come from. url: a link the traveler shared. text: words they pasted. file: a screenshot or PDF they supplied. |
| contentType | string | (source=file) The bytes' media type. image/jpeg, image/png, image/webp and image/heic are screenshots or photos; application/pdf is a travel document. |
| operationId | string | Normally omit. Only for an explicitly requested fresh extraction of the same input within 10 minutes: choose a new operation ID once, then reuse it for retries. Different input is always a separate import. |
| presentation | object |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"source"
],
"properties": {
"url": {
"type": "string",
"format": "uri",
"maxLength": 500,
"description": "(source=url) The video, post or blog address, exactly as shared."
},
"data": {
"type": "string",
"maxLength": 8000000,
"minLength": 64,
"description": "(source=file) Raw base64 bytes, no data URL prefix."
},
"text": {
"type": "string",
"maxLength": 20000,
"minLength": 40,
"description": "(source=text) The pasted text, verbatim. At least 40 characters."
},
"source": {
"enum": [
"url",
"text",
"file"
],
"type": "string",
"description": "Where the places come from. url: a link the traveler shared. text: words they pasted. file: a screenshot or PDF they supplied."
},
"contentType": {
"enum": [
"image/jpeg",
"image/png",
"image/webp",
"image/heic",
"application/pdf"
],
"type": "string",
"description": "(source=file) The bytes' media type. image/jpeg, image/png, image/webp and image/heic are screenshots or photos; application/pdf is a travel document."
},
"operationId": {
"type": "string",
"maxLength": 100,
"minLength": 1,
"description": "Normally omit. Only for an explicitly requested fresh extraction of the same input within 10 minutes: choose a new operation ID once, then reuse it for retries. Different input is always a separate import."
},
"presentation": {
"type": "object",
"properties": {
"layout": {
"enum": [
"compact",
"full"
],
"type": "string",
"description": "Compact cards or the full view; keeps booking, add and error actions available."
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}| integer |
| How many entries to return. Searches return at most 8; the shelf defaults to 40. |
| query | string | Words to look for in saved places and tips, such as 'airport train'. |
| offset | integer | Skip this many entries. Pass the nextOffset from the previous call. |
| importId | string | Follow this import: its status and every place and tip it extracted. |
| folderName | string | Places only: one folder's places; 'unsorted' means places in no folder. Keeps the answer on the places shelf even with a query. |
| presentation | object |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"area": {
"type": "string",
"maxLength": 120,
"minLength": 1,
"description": "Destination to scope the answer to, such as 'Lisbon'. General tips come with it."
},
"kind": {
"enum": [
"all",
"places",
"tips"
],
"type": "string",
"default": "all",
"description": "What to read. all: saved places and tips together. places: saved places only. tips: the tips notebook only."
},
"sort": {
"enum": [
"newest",
"oldest",
"name"
],
"type": "string",
"default": "newest",
"description": "Places only. newest: most recently saved first. oldest: earliest saved first. name: alphabetical by title."
},
"type": {
"enum": [
"all",
"places",
"areas"
],
"type": "string",
"default": "all",
"description": "Places only. all: everything saved. places: individual places. areas: whole-city or region entries, which are destinations rather than stops."
},
"limit": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "How many entries to return. Searches return at most 8; the shelf defaults to 40."
},
"query": {
"type": "string",
"maxLength": 120,
"minLength": 1,
"description": "Words to look for in saved places and tips, such as 'airport train'."
},
"offset": {
"type": "integer",
"maximum": 5000,
"minimum": 0,
"description": "Skip this many entries. Pass the nextOffset from the previous call."
},
"importId": {
"type": "string",
"format": "uuid",
"description": "Follow this import: its status and every place and tip it extracted."
},
"folderName": {
"type": "string",
"maxLength": 60,
"minLength": 1,
"description": "Places only: one folder's places; 'unsorted' means places in no folder. Keeps the answer on the places shelf even with a query."
},
"presentation": {
"type": "object",
"properties": {
"ids": {
"type": "array",
"items": {
"type": "string",
"maxLength": 300,
"minLength": 1
},
"maxItems": 20,
"minItems": 1,
"description": "Show exactly these id values from the retrieved results, in this order. Missing or duplicate IDs fail; do not combine with a smaller presentation.limit."
},
"limit": {
"type": "integer",
"maximum": 20,
"minimum": 1,
"description": "Show at most this many of the retrieved results. Use the tool's search limit to retrieve a larger candidate pool."
},
"layout": {
"enum": [
"compact",
"full"
],
"type": "string",
"description": "Compact cards or the full view; keeps booking, add and error actions available."
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}| presentation | object |
| revokeInvites | array | Owner only: invite ids to kill, so the links stop working. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"tripId"
],
"properties": {
"post": {
"type": "object",
"required": [
"text"
],
"properties": {
"text": {
"type": "string",
"maxLength": 4000,
"minLength": 1,
"description": "The message. Starting it with @dreamfare summons the in-app planner into the thread."
},
"mentionIds": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 20,
"description": "Member userIds to mention, so they get notified."
}
},
"description": "Say something to the crew in the trip's chat.",
"additionalProperties": false
},
"leave": {
"type": "boolean",
"description": "Remove yourself from the trip. The owner cannot leave; delete the trip instead."
},
"invite": {
"type": "object",
"properties": {
"role": {
"enum": [
"viewer",
"editor"
],
"type": "string",
"default": "editor",
"description": "What the invite grants. editor: plans with the traveler. viewer: only looks."
},
"email": {
"type": "string",
"format": "email",
"description": "Email the invite to this address; they must sign in with it to accept."
},
"maxUses": {
"type": "integer",
"maximum": 1000,
"minimum": 1,
"description": "Link invites: how many people may use it."
},
"expiresInDays": {
"type": "integer",
"maximum": 90,
"minimum": 1,
"description": "Let the link stop working after this many days."
}
},
"description": "Create an invite link. With no email, the returned link is what to share.",
"additionalProperties": false
},
"remove": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"maxItems": 20,
"description": "Owner only: collaboratorIds to take off the trip."
},
"tripId": {
"type": "string",
"format": "uuid",
"description": "The trip whose crew is changing."
},
"setRole": {
"type": "array",
"items": {
"type": "object",
"required": [
"collaboratorId",
"role"
],
"properties": {
"role": {
"enum": [
"viewer",
"editor"
],
"type": "string",
"description": "editor: plans with the traveler. viewer: only looks."
},
"collaboratorId": {
"type": "string",
"format": "uuid"
}
},
"additionalProperties": false
},
"maxItems": 20,
"description": "Owner only: change what these members may do."
},
"presentation": {
"type": "object",
"properties": {
"layout": {
"enum": [
"compact",
"full"
],
"type": "string",
"description": "Compact cards or the full view; keeps booking, add and error actions available."
}
},
"additionalProperties": false
},
"revokeInvites": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"maxItems": 20,
"description": "Owner only: invite ids to kill, so the links stop working."
}
},
"additionalProperties": false
}| partySize | integer | How many people travel; sizes the stay and the costs. |
| startDate | string |
| folderName | string | Weave in every place from this saved-places folder (max 20) |
| durationDays | integer | Number of itinerary days, even without calendar dates. With one date, derives the other; with both dates, must equal their inclusive span. Default 4 when dates do not determine duration. |
| presentation | object |
| savedPlaceIds | array | Saved places to weave into the days; ids come from list_library. |
| destinationName* | string | City or region, e.g. 'Lisbon' |
| includeSavedPlaces | boolean | The traveler's answer about their saved places at the destination: true weaves in all of them (max 20), false leaves them out. Omit it before you've asked. |
| destinationCountryCode | string | ISO alpha-2 country code of the destination. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"destinationName",
"brief"
],
"properties": {
"brief": {
"type": "string",
"maxLength": 2000,
"minLength": 3,
"description": "What the traveler wants, in their words: pace, interests, budget, must-sees, dietary needs"
},
"title": {
"type": "string",
"maxLength": 120,
"minLength": 1,
"description": "Trip title; defaults to the destination."
},
"endDate": {
"$ref": "#/properties/startDate"
},
"currency": {
"type": "string",
"maxLength": 3,
"minLength": 3,
"description": "ISO currency code for the trip's prices; defaults to the traveler's home currency."
},
"logistics": {
"type": "object",
"properties": {
"stay": {
"$ref": "#/properties/logistics/properties/stays/items"
},
"stays": {
"type": "array",
"items": {
"type": "object",
"required": [
"kind"
],
"properties": {
"area": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"kind": {
"enum": [
"hotel",
"rental",
"friends"
],
"type": "string"
},
"name": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"address": {
"type": "string",
"maxLength": 400,
"minLength": 1
},
"checkIn": {
"$ref": "#/properties/startDate"
},
"checkOut": {
"$ref": "#/properties/startDate"
}
},
"additionalProperties": false
},
"maxItems": 6
},
"flights": {
"type": "object",
"properties": {
"inbound": {
"type": "string",
"maxLength": 20,
"minLength": 2
},
"outbound": {
"type": "string",
"maxLength": 20,
"minLength": 2
}
},
"additionalProperties": false
},
"flightLegs": {
"type": "array",
"items": {
"type": "object",
"required": [
"number",
"leg"
],
"properties": {
"leg": {
"enum": [
"outbound",
"inbound"
],
"type": "string"
},
"date": {
"$ref": "#/properties/startDate"
},
"number": {
"type": "string",
"maxLength": 20,
"minLength": 2
},
"carrier": {
"type": "string",
"pattern": "^[A-Za-z0-9]{2,3}$"
}
},
"additionalProperties": false
},
"maxItems": 8
}
},
"description": "Already-booked stays and flights; the planner keeps these fixed and plans around them.",
"additionalProperties": false
},
"partySize": {
"type": "integer",
"maximum": 20,
"minimum": 1,
"description": "How many people travel; sizes the stay and the costs."
},
"startDate": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$"
},
"folderName": {
"type": "string",
"maxLength": 80,
"description": "Weave in every place from this saved-places folder (max 20)"
},
"durationDays": {
"type": "integer",
"maximum": 14,
"minimum": 1,
"description": "Number of itinerary days, even without calendar dates. With one date, derives the other; with both dates, must equal their inclusive span. Default 4 when dates do not determine duration."
},
"presentation": {
"type": "object",
"properties": {
"layout": {
"enum": [
"compact",
"full"
],
"type": "string",
"description": "Compact cards or the full view; keeps booking, add and error actions available."
}
},
"additionalProperties": false
},
"savedPlaceIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"maxItems": 20,
"description": "Saved places to weave into the days; ids come from list_library."
},
"destinationName": {
"type": "string",
"maxLength": 120,
"minLength": 2,
"description": "City or region, e.g. 'Lisbon'"
},
"includeSavedPlaces": {
"type": "boolean",
"description": "The traveler's answer about their saved places at the destination: true weaves in all of them (max 20), false leaves them out. Omit it before you've asked."
},
"destinationCountryCode": {
"type": "string",
"maxLength": 2,
"minLength": 2,
"description": "ISO alpha-2 country code of the destination."
}
},
"additionalProperties": false
}| What the options are, for legacy object callers. stay = a property from search_stays | activity = a product from search_activities | place = a restaurant, shop, landmark or Google-listed hotel from search_places. Restored from resultId when you pass one. |
| name | string | Look up by name when there is no object: 'Time Out Market' |
| near | string | The landmark or neighborhood the search was anchored on, so distances read 'from Alfama' |
| guests | integer | Stays: travelers sharing the room |
| option | object | Legacy single-option research: the search result echoed unchanged |
| checkIn | string | Stays: the traveler's check-in date, so prices cover their nights |
| options | array | Legacy comparison: two to five search results of one kind, echoed unchanged |
| checkOut | any | Stays: the traveler's check-out date |
| criteria | array | Comparison only: compare these rows, in this order, with no duplicates. Stays take nightly (per-night price), total (whole-stay price), stars, rating, reviews, distance, sleeps, cancellation, features. Activities take perPerson (per-person price), rating, reviews, duration, category, languages, cancellation, distance, features. Places take rating, reviews, priceLevel, openNow, hoursToday, distance, features. Rows that do not apply come back in unavailableCriteria. |
| currency | string | ISO pricing currency; defaults to the traveler's home currency |
| resultId | string | The search reply's display.resultId; account-bound and retained for 30 minutes |
| optionIds | array | Exact IDs from that search reply (propertyId for a stay, productId for an activity, id for a place), in the order to research. One id returns the full detail; two to five return a comparison in this order. Needs resultId, and must not be combined with option/options/id/name. |
| destination | string | City the options are in; anchors name lookups and distances |
| presentation | object |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"id": {
"type": "string",
"description": "A search_places result's placeId (kind 'place')"
},
"date": {
"$ref": "#/properties/checkIn",
"description": "Activities: the day the traveler has in mind"
},
"kind": {
"enum": [
"stay",
"activity",
"place"
],
"type": "string",
"description": "What the options are, for legacy object callers. stay = a property from search_stays | activity = a product from search_activities | place = a restaurant, shop, landmark or Google-listed hotel from search_places. Restored from resultId when you pass one."
},
"name": {
"type": "string",
"maxLength": 120,
"minLength": 2,
"description": "Look up by name when there is no object: 'Time Out Market'"
},
"near": {
"type": "string",
"maxLength": 80,
"minLength": 2,
"description": "The landmark or neighborhood the search was anchored on, so distances read 'from Alfama'"
},
"guests": {
"type": "integer",
"maximum": 10,
"minimum": 1,
"description": "Stays: travelers sharing the room"
},
"option": {
"type": "object",
"description": "Legacy single-option research: the search result echoed unchanged",
"additionalProperties": {}
},
"checkIn": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"description": "Stays: the traveler's check-in date, so prices cover their nights"
},
"options": {
"type": "array",
"items": {
"$ref": "#/properties/option"
},
"maxItems": 5,
"minItems": 2,
"description": "Legacy comparison: two to five search results of one kind, echoed unchanged"
},
"checkOut": {
"$ref": "#/properties/checkIn",
"description": "Stays: the traveler's check-out date"
},
"criteria": {
"type": "array",
"items": {
"enum": [
"nightly",
"total",
"stars",
"rating",
"reviews",
"distance",
"sleeps",
"cancellation",
"features",
"perPerson",
"duration",
"category",
"languages",
"priceLevel",
"openNow",
"hoursToday"
],
"type": "string"
},
"maxItems": 16,
"minItems": 1,
"description": "Comparison only: compare these rows, in this order, with no duplicates. Stays take nightly (per-night price), total (whole-stay price), stars, rating, reviews, distance, sleeps, cancellation, features. Activities take perPerson (per-person price), rating, reviews, duration, category, languages, cancellation, distance, features. Places take rating, reviews, priceLevel, openNow, hoursToday, distance, features. Rows that do not apply come back in unavailableCriteria."
},
"currency": {
"type": "string",
"maxLength": 3,
"minLength": 3,
"description": "ISO pricing currency; defaults to the traveler's home currency"
},
"resultId": {
"type": "string",
"format": "uuid",
"description": "The search reply's display.resultId; account-bound and retained for 30 minutes"
},
"optionIds": {
"type": "array",
"items": {
"type": "string",
"maxLength": 300,
"minLength": 1
},
"maxItems": 5,
"minItems": 1,
"description": "Exact IDs from that search reply (propertyId for a stay, productId for an activity, id for a place), in the order to research. One id returns the full detail; two to five return a comparison in this order. Needs resultId, and must not be combined with option/options/id/name."
},
"destination": {
"type": "string",
"maxLength": 80,
"minLength": 2,
"description": "City the options are in; anchors name lookups and distances"
},
"presentation": {
"type": "object",
"properties": {
"layout": {
"enum": [
"compact",
"full"
],
"type": "string",
"description": "Compact cards or the full view; keeps booking, add and error actions available."
},
"sections": {
"type": "array",
"items": {
"enum": [
"photos",
"highlights",
"facts",
"features",
"location",
"reviews",
"offers",
"verdict",
"table"
],
"type": "string"
},
"maxItems": 9,
"minItems": 1,
"description": "Show only these optional sections. Identity and essential actions remain available; omit to keep the full view."
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}| best = partner relevance (default) | cheapest = lowest per-person price | rating = best reviewed first | duration = shortest first |
| tags | array | Partner tag words EVERY kept product must carry: 'kid' / 'family', 'wheelchair', 'small group', 'private', 'romantic', 'sunset', 'night', 'luxury', 'self-guided', 'audio guide', 'hop-on hop-off'. For who-it-is-for asks, instead of stuffing q |
| flags | array | Every kept product must carry all of these. free_cancellation = cancellable for a refund | skip_the_line = priority entry | private_tour = your party only | likely_to_sell_out = limited availability |
| limit | integer |
| offset | integer | 'Show me more': skip this many products (12 per page) instead of repeating the same search |
| category | string | Keep only products whose partner tags match ('Food & Drink', 'Day Trips', 'Museums', 'Walking Tours') |
| currency | string |
| fallback | string | What to do when nothing matches. cheapest = return the cheapest available, labeled as alternatives (default) | none = keep the filters strict and return nothing |
| maxPrice | number | Per-person price ceiling, MAJOR units of the pricing currency (50 = $50) |
| minPrice | number | Per-person price floor, major units |
| minRating | number | Traveler-rating floor, 0–5 |
| timeOfDay | string | Keeps products whose listed start times fall in that window; products with no listed time stay. morning = before noon | afternoon = noon to 17:00 | evening = after 17:00 |
| minReviews | integer | 'Well reviewed' / 'popular': ignore products with fewer reviews than this (300 is a solid bar) |
| destination* | string |
| presentation | object |
| maxDistanceKm | number | Drop products whose meeting point is farther than this from `near` |
| maxDurationMinutes | integer | 'Under 3 hours' = 180 |
| minDurationMinutes | integer |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"destination"
],
"properties": {
"q": {
"type": "string",
"maxLength": 80,
"minLength": 1,
"description": "What kind of experience, in the traveler's words: 'food tour', 'sunset cruise', 'kayaking'"
},
"date": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$"
},
"name": {
"type": "string",
"maxLength": 120,
"minLength": 2,
"description": "ONE specific product the traveler named ('Devour Lisbon food tour'): found on its own terms and leads the list. A kind of experience is q"
},
"near": {
"type": "string",
"maxLength": 80,
"minLength": 2,
"description": "A landmark, neighborhood or hotel inside the destination to search around: products with a known meeting point stay within 5 km (or maxDistanceKm) and report distanceMeters, nearest first"
},
"sort": {
"enum": [
"best",
"cheapest",
"rating",
"duration"
],
"type": "string",
"default": "best",
"description": "best = partner relevance (default) | cheapest = lowest per-person price | rating = best reviewed first | duration = shortest first"
},
"tags": {
"type": "array",
"items": {
"type": "string",
"maxLength": 40,
"minLength": 2
},
"maxItems": 5,
"description": "Partner tag words EVERY kept product must carry: 'kid' / 'family', 'wheelchair', 'small group', 'private', 'romantic', 'sunset', 'night', 'luxury', 'self-guided', 'audio guide', 'hop-on hop-off'. For who-it-is-for asks, instead of stuffing q"
},
"flags": {
"type": "array",
"items": {
"enum": [
"free_cancellation",
"skip_the_line",
"private_tour",
"likely_to_sell_out"
],
"type": "string"
},
"maxItems": 4,
"description": "Every kept product must carry all of these. free_cancellation = cancellable for a refund | skip_the_line = priority entry | private_tour = your party only | likely_to_sell_out = limited availability"
},
"limit": {
"type": "integer",
"default": 8,
"maximum": 20,
"minimum": 1
},
"offset": {
"type": "integer",
"minimum": 0,
"description": "'Show me more': skip this many products (12 per page) instead of repeating the same search"
},
"category": {
"type": "string",
"maxLength": 60,
"minLength": 2,
"description": "Keep only products whose partner tags match ('Food & Drink', 'Day Trips', 'Museums', 'Walking Tours')"
},
"currency": {
"type": "string",
"maxLength": 3,
"minLength": 3
},
"fallback": {
"enum": [
"cheapest",
"none"
],
"type": "string",
"default": "cheapest",
"description": "What to do when nothing matches. cheapest = return the cheapest available, labeled as alternatives (default) | none = keep the filters strict and return nothing"
},
"maxPrice": {
"type": "number",
"minimum": 0,
"description": "Per-person price ceiling, MAJOR units of the pricing currency (50 = $50)"
},
"minPrice": {
"type": "number",
"minimum": 0,
"description": "Per-person price floor, major units"
},
"minRating": {
"type": "number",
"maximum": 5,
"minimum": 0,
"description": "Traveler-rating floor, 0–5"
},
"timeOfDay": {
"enum": [
"morning",
"afternoon",
"evening"
],
"type": "string",
"description": "Keeps products whose listed start times fall in that window; products with no listed time stay. morning = before noon | afternoon = noon to 17:00 | evening = after 17:00"
},
"minReviews": {
"type": "integer",
"minimum": 0,
"description": "'Well reviewed' / 'popular': ignore products with fewer reviews than this (300 is a solid bar)"
},
"destination": {
"type": "string",
"minLength": 2
},
"presentation": {
"type": "object",
"properties": {
"ids": {
"type": "array",
"items": {
"type": "string",
"maxLength": 300,
"minLength": 1
},
"maxItems": 20,
"minItems": 1,
"description": "Show exactly these productId values from the retrieved results, in this order. Missing or duplicate IDs fail; do not combine with a smaller presentation.limit."
},
"limit": {
"type": "integer",
"maximum": 20,
"minimum": 1,
"description": "Show at most this many of the retrieved results. Use the tool's search limit to retrieve a larger candidate pool."
},
"layout": {
"enum": [
"compact",
"full"
],
"type": "string",
"description": "Compact cards or the full view; keeps booking, add and error actions available."
}
},
"additionalProperties": false
},
"maxDistanceKm": {
"type": "number",
"maximum": 100,
"minimum": 0.1,
"description": "Drop products whose meeting point is farther than this from `near`"
},
"maxDurationMinutes": {
"type": "integer",
"minimum": 15,
"description": "'Under 3 hours' = 180"
},
"minDurationMinutes": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": false
}| dropoffTime* |
| string |
| Local drop-off time, HH:MM |
| presentation | object |
| transmission | string | automatic = self-shifting gearbox | manual = stick shift |
| pickupAirport* | string | Pickup airport, exact IATA code. Resolve a city name with search_flights first. |
| dropoffAirport | string | Drop-off airport IATA code; defaults to the pickup airport |
| licenseCountry* | string | The driving licence's issuing country, ISO2; ask, never guess |
| maxTotalAmount | integer | Rental-total ceiling in integer minor units of currency |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"pickupAirport",
"pickupDate",
"pickupTime",
"dropoffDate",
"dropoffTime",
"driverAge",
"licenseCountry"
],
"properties": {
"currency": {
"type": "string",
"default": "USD",
"maxLength": 3,
"minLength": 3
},
"minSeats": {
"type": "integer",
"maximum": 9,
"minimum": 1,
"description": "Keep only cars with at least this many seats"
},
"driverAge": {
"type": "integer",
"maximum": 99,
"minimum": 18,
"description": "The driver's actual age; ask, never guess"
},
"pickupDate": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$"
},
"pickupTime": {
"type": "string",
"pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
"description": "Local pickup time, HH:MM"
},
"dropoffDate": {
"$ref": "#/properties/pickupDate"
},
"dropoffTime": {
"type": "string",
"pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
"description": "Local drop-off time, HH:MM"
},
"presentation": {
"type": "object",
"properties": {
"layout": {
"enum": [
"compact",
"full"
],
"type": "string",
"description": "Compact cards or the full view; keeps booking, add and error actions available."
}
},
"additionalProperties": false
},
"transmission": {
"enum": [
"automatic",
"manual"
],
"type": "string",
"description": "automatic = self-shifting gearbox | manual = stick shift"
},
"pickupAirport": {
"type": "string",
"pattern": "^[A-Z]{3}$",
"description": "Pickup airport, exact IATA code. Resolve a city name with search_flights first."
},
"dropoffAirport": {
"type": "string",
"pattern": "^[A-Z]{3}$",
"description": "Drop-off airport IATA code; defaults to the pickup airport"
},
"licenseCountry": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "The driving licence's issuing country, ISO2; ask, never guess"
},
"maxTotalAmount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Rental-total ceiling in integer minor units of currency"
}
},
"additionalProperties": false
}| origin | string | Where the flight starts: an IATA airport or metro code (LHR, LON), or a city or airport name resolved here ('Lisbon' becomes LIS). Omit only when refining with searchId. |
| infants | any | Infants under 2; at most one per adult |
| airlines | any | Only these IATA carrier codes on every segment |
| arriveBy | string | Absolute outbound arrival deadline YYYY-MM-DDTHH:MM in the arrival airport local calendar |
| cabinBag | any | Only fares including a cabin bag |
| children | any | Children aged 2 to 11 |
| currency | string | ISO pricing currency; defaults to the traveler's home currency |
| maxStops | any | Maximum connections in EACH direction; 0 means nonstop |
| maxTotal | any | Fare ceiling in normal currency units; priceBasis defaults to total |
| minTotal | any | Fare floor in normal currency units; priceBasis defaults to total |
| searchId | string | Refine an earlier board instead of scraping again: the searchId that search returned, retained for about 90 minutes. Route, dates, party, cabin and currency stay as they were; filters and sort narrow what was retained. |
| checkedBag | any | Only fares including a checked bag |
| departDate | string | Outbound date, YYYY-MM-DD, within 330 days. Omit only when refining with searchId. |
| passengers | integer | Adults; default 1 |
| priceBasis | string | Reads minTotal and maxTotal only. total = the whole party's fare (default) | per_person = the budget is per adult or child seat, infant costs still included |
| returnDate | any | YYYY-MM-DD for the return; omit for one way |
| arriveAfter | any | HH:MM local at the outbound destination |
| departAfter | any | HH:MM local at the outbound origin |
| destination | string | Where it lands: an IATA airport or metro code, or a city or airport name. Omit only when refining with searchId. |
| arriveBefore | any | HH:MM local at the outbound destination |
| departBefore | any | HH:MM local at the outbound origin |
| presentation | object |
| maxTotalAmount | integer | Whole-party fare ceiling in integer MINOR units, regardless of priceBasis |
| minTotalAmount | integer | Whole-party fare floor in integer MINOR units, regardless of priceBasis |
| noSelfTransfer | any | Hide separate-ticket itineraries |
| returnArriveBy | any | Absolute home arrival deadline YYYY-MM-DDTHH:MM in the home airport local calendar; requires returnDate. Use for home by Sunday evening instead of a clock-only filter. |
| excludedAirlines | array | Exclude these IATA carrier codes from every segment |
| maxLayoverMinutes | integer | Maximum ground time at EVERY connection; nonstop fares remain eligible |
| minLayoverMinutes | integer | Minimum ground time at EVERY connection; nonstop fares remain eligible |
| returnArriveAfter | any | HH:MM local at the return destination; requires returnDate |
| returnDepartAfter | any | HH:MM local at the return origin; requires returnDate |
| maxDurationMinutes | integer | Maximum elapsed journey duration in EACH direction, including connections |
| returnArriveBefore | any | HH:MM local at the return destination; requires returnDate |
| returnDepartBefore | any | HH:MM local at the return origin; requires returnDate |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"sort": {
"anyOf": [
{
"anyOf": [
{
"not": {}
},
{
"enum": [
"best",
"cheapest",
"fastest",
"fewest_stops"
],
"type": "string"
}
]
},
{
"type": "null"
}
],
"description": "best = balanced price, time and connections (default) | cheapest = lowest whole-party fare | fastest = shortest elapsed journey | fewest_stops = fewest connections"
},
"cabin": {
"enum": [
"economy",
"premium_economy",
"business",
"first"
],
"type": "string",
"default": "economy",
"description": "economy = the standard cabin | premium_economy = the extra-legroom cabin | business = lie-flat or wide seat | first = the top cabin"
},
"limit": {
"anyOf": [
{
"type": "integer",
"maximum": 60,
"minimum": 1
},
{
"type": "null"
}
],
"default": 3,
"description": "Maximum fares to return, in requested sort order. Use 1 for one flight or 3 for three; default 3. Return fewer only when fewer are available. Maximum 60."
},
"origin": {
"type": "string",
"maxLength": 60,
"minLength": 2,
"description": "Where the flight starts: an IATA airport or metro code (LHR, LON), or a city or airport name resolved here ('Lisbon' becomes LIS). Omit only when refining with searchId."
},
"infants": {
"anyOf": [
{
"anyOf": [
{
"not": {}
},
{
"type": "integer",
"maximum": 4,
"minimum": 0
}
]
},
{
"type": "null"
}
],
"description": "Infants under 2; at most one per adult"
},
"airlines": {
"anyOf": [
{
"anyOf": [
{
"not": {}
},
{
"type": "array",
"items": {
"type": "string",
"maxLength": 2,
"minLength": 2
},
"maxItems": 10
}
]
},
{
"type": "null"
}
],
"description": "Only these IATA carrier codes on every segment"
},
"arriveBy": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}T([01]\\d|2[0-3]):[0-5]\\d$",
"description": "Absolute outbound arrival deadline YYYY-MM-DDTHH:MM in the arrival airport local calendar"
},
"cabinBag": {
"anyOf": [
{
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"const": "1"
}
]
},
{
"type": "null"
}
],
"description": "Only fares including a cabin bag"
},
"children": {
"anyOf": [
{
"anyOf": [
{
"not": {}
},
{
"type": "integer",
"maximum": 8,
"minimum": 0
}
]
},
{
"type": "null"
}
],
"description": "Children aged 2 to 11"
},
"currency": {
"type": "string",
"maxLength": 3,
"minLength": 3,
"description": "ISO pricing currency; defaults to the traveler's home currency"
},
"maxStops": {
"anyOf": [
{
"anyOf": [
{
"not": {}
},
{
"type": "integer",
"maximum": 3,
"minimum": 0
}
]
},
{
"type": "null"
}
],
"description": "Maximum connections in EACH direction; 0 means nonstop"
},
"maxTotal": {
"anyOf": [
{
"type": "number",
"minimum": 0
},
{
"type": "null"
}
],
"description": "Fare ceiling in normal currency units; priceBasis defaults to total"
},
"minTotal": {
"anyOf": [
{
"type": "number",
"minimum": 0
},
{
"type": "null"
}
],
"description": "Fare floor in normal currency units; priceBasis defaults to total"
},
"searchId": {
"type": "string",
"pattern": "^[a-f0-9]{16,64}$",
"description": "Refine an earlier board instead of scraping again: the searchId that search returned, retained for about 90 minutes. Route, dates, party, cabin and currency stay as they were; filters and sort narrow what was retained."
},
"checkedBag": {
"$ref": "#/properties/cabinBag",
"description": "Only fares including a checked bag"
},
"departDate": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"description": "Outbound date, YYYY-MM-DD, within 330 days. Omit only when refining with searchId."
},
"passengers": {
"type": "integer",
"default": 1,
"maximum": 9,
"minimum": 1,
"description": "Adults; default 1"
},
"priceBasis": {
"enum": [
"total",
"per_person"
],
"type": "string",
"default": "total",
"description": "Reads minTotal and maxTotal only. total = the whole party's fare (default) | per_person = the budget is per adult or child seat, infant costs still included"
},
"returnDate": {
"anyOf": [
{
"anyOf": [
{
"not": {}
},
{
"$ref": "#/properties/departDate"
}
]
},
{
"type": "null"
}
],
"description": "YYYY-MM-DD for the return; omit for one way"
},
"arriveAfter": {
"$ref": "#/properties/departAfter/anyOf/0/anyOf/1",
"description": "HH:MM local at the outbound destination"
},
"departAfter": {
"anyOf": [
{
"anyOf": [
{
"not": {}
},
{
"type": "string",
"pattern": "^([01]\\d|2[0-3]):[0-5]\\d$"
}
]
},
{
"type": "null"
}
],
"description": "HH:MM local at the outbound origin"
},
"destination": {
"type": "string",
"maxLength": 60,
"minLength": 2,
"description": "Where it lands: an IATA airport or metro code, or a city or airport name. Omit only when refining with searchId."
},
"arriveBefore": {
"anyOf": [
{
"anyOf": [
{
"not": {}
},
{
"$ref": "#/properties/departAfter/anyOf/0/anyOf/1"
}
]
},
{
"type": "null"
}
],
"description": "HH:MM local at the outbound destination"
},
"departBefore": {
"anyOf": [
{
"anyOf": [
{
"not": {}
},
{
"$ref": "#/properties/departAfter/anyOf/0/anyOf/1"
}
]
},
{
"type": "null"
}
],
"description": "HH:MM local at the outbound origin"
},
"presentation": {
"type": "object",
"properties": {
"ids": {
"type": "array",
"items": {
"type": "string",
"maxLength": 300,
"minLength": 1
},
"maxItems": 20,
"minItems": 1,
"description": "Exact returned offerId values, in the order to display and compare. Refine with search_flights and the original searchId. Missing or duplicate IDs fail."
},
"limit": {
"type": "integer",
"maximum": 20,
"minimum": 1,
"description": "Displayed fares: use 1 for one or 3 for three. Overrides the legacy result limit; never pads missing fares."
},
"layout": {
"enum": [
"compact",
"full"
],
"type": "string"
},
"sections": {
"type": "array",
"items": {
"enum": [
"summary",
"comparison",
"details",
"quotes",
"calendar"
],
"type": "string"
},
"maxItems": 5,
"minItems": 1,
"description": "Optional sections to show. Flight identity, price, booking and add actions remain available."
}
},
"additionalProperties": false
},
"maxTotalAmount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Whole-party fare ceiling in integer MINOR units, regardless of priceBasis"
},
"minTotalAmount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Whole-party fare floor in integer MINOR units, regardless of priceBasis"
},
"noSelfTransfer": {
"$ref": "#/properties/cabinBag",
"description": "Hide separate-ticket itineraries"
},
"returnArriveBy": {
"$ref": "#/properties/arriveBy",
"description": "Absolute home arrival deadline YYYY-MM-DDTHH:MM in the home airport local calendar; requires returnDate. Use for home by Sunday evening instead of a clock-only filter."
},
"excludedAirlines": {
"type": "array",
"items": {
"type": "string",
"maxLength": 2,
"minLength": 2
},
"maxItems": 10,
"description": "Exclude these IATA carrier codes from every segment"
},
"maxLayoverMinutes": {
"type": "integer",
"maximum": 2880,
"minimum": 0,
"description": "Maximum ground time at EVERY connection; nonstop fares remain eligible"
},
"minLayoverMinutes": {
"type": "integer",
"maximum": 2880,
"minimum": 0,
"description": "Minimum ground time at EVERY connection; nonstop fares remain eligible"
},
"returnArriveAfter": {
"$ref": "#/properties/departAfter/anyOf/0/anyOf/1",
"description": "HH:MM local at the return destination; requires returnDate"
},
"returnDepartAfter": {
"$ref": "#/properties/departAfter/anyOf/0/anyOf/1",
"description": "HH:MM local at the return origin; requires returnDate"
},
"maxDurationMinutes": {
"type": "integer",
"maximum": 10080,
"minimum": 1,
"description": "Maximum elapsed journey duration in EACH direction, including connections"
},
"returnArriveBefore": {
"$ref": "#/properties/departAfter/anyOf/0/anyOf/1",
"description": "HH:MM local at the return destination; requires returnDate"
},
"returnDepartBefore": {
"$ref": "#/properties/departAfter/anyOf/0/anyOf/1",
"description": "HH:MM local at the return origin; requires returnDate"
}
},
"additionalProperties": false
}| integer |
| Maximum results to return, including one or three. A provider page can contain fewer. |
| guests | integer |
| offset | integer | Continue with the previous reply's nextOffset; keep the same query and filters. |
| openAt | string | Only places open at this local time, 'YYYY-MM-DDTHH:MM' (needs listed hours) |
| region* | string | City or region, e.g. 'Lisbon' |
| checkIn | string | Hotels: price a concrete window |
| openNow | boolean | Restaurants/shops/landmarks: only places open right now |
| category | string | Activities: partner tag to keep ('Food & Drink') |
| checkOut | any |
| currency | string |
| radiusKm | number | How far around `near` to look (default 3 km) |
| maxBudget | number | Price ceiling in MAJOR units of currency: per night for hotels, per person for activities. Unknown prices follow includeUnpriced. |
| minBudget | number | Price floor in the same currency and basis as maxBudget. |
| minRating | number | Rating floor: Google/tours 0–5, hotels 0–10 |
| priceLevels | array | Google price levels to keep: 0 free, 1 $, 2 $$, 3 $$$, 4 $$$$ |
| presentation | object |
| includeUnpriced | boolean | Keep results with no known price (most restaurants and landmarks). Set false for a shortlist that must have a verifiable price. |
| freeCancellation | boolean | Hotels and activities: free cancellation only |
| maxDurationMinutes | integer | Activities: length ceiling |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"region",
"kind"
],
"properties": {
"q": {
"type": "string",
"maxLength": 80,
"minLength": 1,
"description": "Refinement, e.g. 'ramen', 'sunset cruise'"
},
"kind": {
"enum": [
"activity",
"hotel",
"restaurant",
"shopping",
"landmark"
],
"type": "string",
"description": "activity = tours and experiences | hotel = places to stay | restaurant = places to eat | shopping = shops and markets | landmark = sights and attractions"
},
"near": {
"type": "string",
"maxLength": 80,
"minLength": 2,
"description": "A landmark or neighborhood inside the region to search around"
},
"sort": {
"enum": [
"best",
"cheapest",
"rating"
],
"type": "string",
"description": "best = relevance (default) | cheapest = lowest price first | rating = best rated first"
},
"limit": {
"type": "integer",
"default": 8,
"maximum": 20,
"minimum": 1,
"description": "Maximum results to return, including one or three. A provider page can contain fewer."
},
"guests": {
"type": "integer",
"maximum": 10,
"minimum": 1
},
"offset": {
"type": "integer",
"default": 0,
"maximum": 96,
"minimum": 0,
"description": "Continue with the previous reply's nextOffset; keep the same query and filters."
},
"openAt": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}T([01]\\d|2[0-3]):[0-5]\\d$",
"description": "Only places open at this local time, 'YYYY-MM-DDTHH:MM' (needs listed hours)"
},
"region": {
"type": "string",
"maxLength": 80,
"minLength": 2,
"description": "City or region, e.g. 'Lisbon'"
},
"checkIn": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"description": "Hotels: price a concrete window"
},
"openNow": {
"type": "boolean",
"description": "Restaurants/shops/landmarks: only places open right now"
},
"category": {
"type": "string",
"maxLength": 60,
"minLength": 2,
"description": "Activities: partner tag to keep ('Food & Drink')"
},
"checkOut": {
"$ref": "#/properties/checkIn"
},
"currency": {
"type": "string",
"maxLength": 3,
"minLength": 3
},
"radiusKm": {
"type": "number",
"maximum": 50,
"minimum": 0.2,
"description": "How far around `near` to look (default 3 km)"
},
"maxBudget": {
"type": "number",
"minimum": 0,
"description": "Price ceiling in MAJOR units of currency: per night for hotels, per person for activities. Unknown prices follow includeUnpriced."
},
"minBudget": {
"type": "number",
"minimum": 0,
"description": "Price floor in the same currency and basis as maxBudget."
},
"minRating": {
"type": "number",
"maximum": 10,
"minimum": 0,
"description": "Rating floor: Google/tours 0–5, hotels 0–10"
},
"priceLevels": {
"type": "array",
"items": {
"type": "integer",
"maximum": 4,
"minimum": 0
},
"maxItems": 5,
"minItems": 1,
"description": "Google price levels to keep: 0 free, 1 $, 2 $$, 3 $$$, 4 $$$$"
},
"presentation": {
"type": "object",
"properties": {
"ids": {
"type": "array",
"items": {
"type": "string",
"maxLength": 300,
"minLength": 1
},
"maxItems": 20,
"minItems": 1,
"description": "Show exactly these id values from the retrieved results, in this order. Missing or duplicate IDs fail; do not combine with a smaller presentation.limit."
},
"limit": {
"type": "integer",
"maximum": 20,
"minimum": 1,
"description": "Show at most this many of the retrieved results. Use the tool's search limit to retrieve a larger candidate pool."
},
"layout": {
"enum": [
"compact",
"full"
],
"type": "string",
"description": "Compact cards or the full view; keeps booking, add and error actions available."
}
},
"additionalProperties": false
},
"includeUnpriced": {
"type": "boolean",
"default": true,
"description": "Keep results with no known price (most restaurants and landmarks). Set false for a shortlist that must have a verifiable price."
},
"freeCancellation": {
"type": "boolean",
"description": "Hotels and activities: free cancellation only"
},
"maxDurationMinutes": {
"type": "integer",
"minimum": 15,
"description": "Activities: length ceiling"
}
},
"additionalProperties": false
}| limit | any | Maximum results after filtering and sorting, default 8 |
| budget | any | Nightly ceiling for the quoted accommodation, including taxes/fees. Integer MINOR units: USD 15000 = $150. Do not combine with maxNightlyAmount. |
| guests | any | Travelers sharing the quoted accommodation, 1–10; default 2 |
| tripId | any | Price against this trip: its currency is used when `currency` is omitted. |
| checkIn* | string | Check-in calendar date, YYYY-MM-DD |
| checkOut* | any | Check-out calendar date, YYYY-MM-DD; must be after checkIn |
| currency | any | ISO pricing currency. A bound in-app trip supplies its currency; MCP and the account assistant default to home currency, then USD. |
| fallback | any | Legacy alias for constraintMode. none = strict | cheapest = prefer. Do not set both. |
| keywords | any | Up to five style words matched against listing names; any one matches |
| minStars | any | Hotel-star floor, 1–5 |
| interests | any | Traveler interests such as food, art galleries, or quiet parks. Resolves real places and keeps hotels within maxDistanceKm (default 5 km) of a verified place for EACH interest. Do not put interests in listing-name keywords. |
| minGuests | any | Minimum verified sleeping capacity; never relaxed |
| minRating | any | Guest-score floor on the 0–10 scale |
| maxNightly | any | Deprecated: nightly ceiling in MAJOR currency units (150 = $150). Prefer budget or maxNightlyAmount; never combine them. |
| minNightly | any | Deprecated: nightly floor in MAJOR currency units. Prefer minNightlyAmount; never combine them. |
| minReviews | any | Minimum number of guest reviews |
| destination* | string | City or town, e.g. Kyoto; use a town within a large region |
| minBedrooms | any | Minimum bedrooms; never relaxed |
| presentation | object |
| propertyType | any | hotel (including family suites), rental, or hostel; inferred from listing evidence |
| maxDistanceKm | any | Maximum distance from near or the city center, in kilometers |
| unknownPolicy | any | Property type only. exclude = drop listings whose type is unproven | include_labeled = keep them, labeled (the default). Price, capacity, cancellation and distance always need evidence. |
| constraintMode | any | strict = every filter is a requirement, nothing is relaxed | prefer = labeled alternatives are allowed when nothing matches exactly (the default) |
| freeCancellation | boolean | null | Require supplier-confirmed free cancellation; this requirement is never relaxed |
| maxNightlyAmount | any | Nightly ceiling in integer MINOR units of currency; alternatively use budget |
| minNightlyAmount | any | Nightly floor in integer MINOR units of currency |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"destination",
"checkIn",
"checkOut"
],
"properties": {
"name": {
"anyOf": [
{
"type": "string",
"maxLength": 120,
"minLength": 2
},
{
"type": "null"
}
],
"description": "One specific named hotel; a style such as boutique belongs in keywords"
},
"near": {
"anyOf": [
{
"anyOf": [
{
"not": {}
},
{
"type": "string",
"maxLength": 80,
"minLength": 2
}
]
},
{
"type": "null"
}
],
"description": "Landmark or neighborhood inside destination; strict mode uses a 5 km radius unless maxDistanceKm is supplied"
},
"sort": {
"anyOf": [
{
"enum": [
"best",
"cheapest",
"rating",
"distance"
],
"type": "string"
},
{
"type": "null"
}
],
"description": "best = provider relevance (default) | cheapest = lowest nightly price | rating = best guest score first | distance = closest to near or the city center first"
},
"limit": {
"anyOf": [
{
"type": "integer",
"maximum": 20,
"minimum": 1
},
{
"type": "null"
}
],
"description": "Maximum results after filtering and sorting, default 8"
},
"budget": {
"anyOf": [
{
"type": "object",
"required": [
"amount",
"currency",
"basis"
],
"properties": {
"basis": {
"type": "string",
"const": "per_night"
},
"amount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"currency": {
"$ref": "#/properties/currency/anyOf/0"
}
},
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Nightly ceiling for the quoted accommodation, including taxes/fees. Integer MINOR units: USD 15000 = $150. Do not combine with maxNightlyAmount."
},
"guests": {
"anyOf": [
{
"type": "integer",
"maximum": 10,
"minimum": 1
},
{
"type": "null"
}
],
"description": "Travelers sharing the quoted accommodation, 1–10; default 2"
},
"tripId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"description": "Price against this trip: its currency is used when `currency` is omitted."
},
"checkIn": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"description": "Check-in calendar date, YYYY-MM-DD"
},
"checkOut": {
"$ref": "#/properties/checkIn",
"description": "Check-out calendar date, YYYY-MM-DD; must be after checkIn"
},
"currency": {
"anyOf": [
{
"type": "string",
"pattern": "^[A-Za-z]{3}$"
},
{
"type": "null"
}
],
"description": "ISO pricing currency. A bound in-app trip supplies its currency; MCP and the account assistant default to home currency, then USD."
},
"fallback": {
"anyOf": [
{
"enum": [
"cheapest",
"none"
],
"type": "string"
},
{
"type": "null"
}
],
"description": "Legacy alias for constraintMode. none = strict | cheapest = prefer. Do not set both."
},
"keywords": {
"anyOf": [
{
"anyOf": [
{
"not": {}
},
{
"type": "array",
"items": {
"type": "string",
"maxLength": 40,
"minLength": 2
},
"maxItems": 5
}
]
},
{
"type": "null"
}
],
"description": "Up to five style words matched against listing names; any one matches"
},
"minStars": {
"anyOf": [
{
"anyOf": [
{
"not": {}
},
{
"type": "integer",
"maximum": 5,
"minimum": 1
}
]
},
{
"type": "null"
}
],
"description": "Hotel-star floor, 1–5"
},
"interests": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"maxLength": 80,
"minLength": 2
},
"maxItems": 3,
"minItems": 1
},
{
"type": "null"
}
],
"description": "Traveler interests such as food, art galleries, or quiet parks. Resolves real places and keeps hotels within maxDistanceKm (default 5 km) of a verified place for EACH interest. Do not put interests in listing-name keywords."
},
"minGuests": {
"anyOf": [
{
"anyOf": [
{
"not": {}
},
{
"type": "integer",
"maximum": 16,
"minimum": 1
}
]
},
{
"type": "null"
}
],
"description": "Minimum verified sleeping capacity; never relaxed"
},
"minRating": {
"anyOf": [
{
"anyOf": [
{
"not": {}
},
{
"type": "number",
"maximum": 10,
"minimum": 0
}
]
},
{
"type": "null"
}
],
"description": "Guest-score floor on the 0–10 scale"
},
"maxNightly": {
"anyOf": [
{
"type": "number",
"minimum": 0
},
{
"type": "null"
}
],
"description": "Deprecated: nightly ceiling in MAJOR currency units (150 = $150). Prefer budget or maxNightlyAmount; never combine them."
},
"minNightly": {
"anyOf": [
{
"type": "number",
"minimum": 0
},
{
"type": "null"
}
],
"description": "Deprecated: nightly floor in MAJOR currency units. Prefer minNightlyAmount; never combine them."
},
"minReviews": {
"anyOf": [
{
"anyOf": [
{
"not": {}
},
{
"type": "integer",
"minimum": 0
}
]
},
{
"type": "null"
}
],
"description": "Minimum number of guest reviews"
},
"destination": {
"type": "string",
"maxLength": 120,
"minLength": 2,
"description": "City or town, e.g. Kyoto; use a town within a large region"
},
"minBedrooms": {
"anyOf": [
{
"anyOf": [
{
"not": {}
},
{
"type": "integer",
"maximum": 10,
"minimum": 1
}
]
},
{
"type": "null"
}
],
"description": "Minimum bedrooms; never relaxed"
},
"presentation": {
"type": "object",
"properties": {
"ids": {
"type": "array",
"items": {
"type": "string",
"maxLength": 300,
"minLength": 1
},
"maxItems": 20,
"minItems": 1,
"description": "Show exactly these propertyId values from the retrieved results, in this order. Missing or duplicate IDs fail; do not combine with a smaller presentation.limit."
},
"limit": {
"type": "integer",
"maximum": 20,
"minimum": 1,
"description": "Show at most this many of the retrieved results. Use the tool's search limit to retrieve a larger candidate pool."
},
"layout": {
"enum": [
"compact",
"full"
],
"type": "string",
"description": "Compact cards or the full view; keeps booking, add and error actions available."
}
},
"additionalProperties": false
},
"propertyType": {
"anyOf": [
{
"anyOf": [
{
"not": {}
},
{
"enum": [
"hotel",
"rental",
"hostel"
],
"type": "string"
}
]
},
{
"type": "null"
}
],
"description": "hotel (including family suites), rental, or hostel; inferred from listing evidence"
},
"maxDistanceKm": {
"anyOf": [
{
"anyOf": [
{
"not": {}
},
{
"type": "number",
"maximum": 50,
"minimum": 0.1
}
]
},
{
"type": "null"
}
],
"description": "Maximum distance from near or the city center, in kilometers"
},
"unknownPolicy": {
"anyOf": [
{
"enum": [
"exclude",
"include_labeled"
],
"type": "string"
},
{
"type": "null"
}
],
"description": "Property type only. exclude = drop listings whose type is unproven | include_labeled = keep them, labeled (the default). Price, capacity, cancellation and distance always need evidence."
},
"constraintMode": {
"anyOf": [
{
"enum": [
"strict",
"prefer"
],
"type": "string"
},
{
"type": "null"
}
],
"description": "strict = every filter is a requirement, nothing is relaxed | prefer = labeled alternatives are allowed when nothing matches exactly (the default)"
},
"freeCancellation": {
"type": [
"boolean",
"null"
],
"description": "Require supplier-confirmed free cancellation; this requirement is never relaxed"
},
"maxNightlyAmount": {
"anyOf": [
{
"$ref": "#/properties/budget/anyOf/0/properties/amount"
},
{
"type": "null"
}
],
"description": "Nightly ceiling in integer MINOR units of currency; alternatively use budget"
},
"minNightlyAmount": {
"anyOf": [
{
"$ref": "#/properties/budget/anyOf/0/properties/amount"
},
{
"type": "null"
}
],
"description": "Nightly floor in integer MINOR units of currency"
}
},
"additionalProperties": false
}| journeyId | string | With searchId: return the stored details of that one fare, exactly as it was quoted. |
| departDate | string | Outbound travel date, YYYY-MM-DD. Omit only when refining with searchId. |
| maxChanges | integer | Most changes of train allowed on a journey; 0 means direct |
| passengers | integer | Adult travelers; adult quotes never cover children |
| returnDate | any | Explicit return travel date. Omit for one way; never repeat the outbound date. |
| departAfter | string | Earliest outbound departure, HH:MM local, including the time it takes to reach the station |
| destination | string | Where it ends, as a city or station name. Omit only when refining with searchId. |
| departBefore | string | Latest outbound departure, HH:MM local |
| presentation | object |
| maxTotalAmount | integer | Whole-party one-way fare ceiling in integer minor units |
| returnDepartAfter | string | Earliest return departure, HH:MM local; needs returnDate |
| maxDurationMinutes | integer | Longest acceptable journey, in minutes |
| returnDepartBefore | any | Latest return departure, HH:MM local; needs returnDate |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"sort": {
"enum": [
"cheapest",
"fastest",
"earliest"
],
"type": "string",
"default": "cheapest",
"description": "cheapest = lowest whole-party fare (default) | fastest = shortest journey | earliest = first departure"
},
"limit": {
"type": "integer",
"default": 6,
"maximum": 20,
"minimum": 1
},
"origin": {
"type": "string",
"maxLength": 160,
"minLength": 2,
"description": "Where the journey starts, as a city or station name. Rail has no universal station codes. Omit only when refining with searchId."
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$"
},
"searchId": {
"type": "string",
"description": "Refine an earlier search instead of asking the sellers again: the searchId it returned. Route, date, currency and passengers stay fixed."
},
"journeyId": {
"type": "string",
"description": "With searchId: return the stored details of that one fare, exactly as it was quoted."
},
"departDate": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"description": "Outbound travel date, YYYY-MM-DD. Omit only when refining with searchId."
},
"maxChanges": {
"type": "integer",
"maximum": 8,
"minimum": 0,
"description": "Most changes of train allowed on a journey; 0 means direct"
},
"passengers": {
"type": "integer",
"default": 1,
"maximum": 9,
"minimum": 1,
"description": "Adult travelers; adult quotes never cover children"
},
"returnDate": {
"$ref": "#/properties/departDate",
"description": "Explicit return travel date. Omit for one way; never repeat the outbound date."
},
"departAfter": {
"type": "string",
"pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
"description": "Earliest outbound departure, HH:MM local, including the time it takes to reach the station"
},
"destination": {
"type": "string",
"maxLength": 160,
"minLength": 2,
"description": "Where it ends, as a city or station name. Omit only when refining with searchId."
},
"departBefore": {
"type": "string",
"pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
"description": "Latest outbound departure, HH:MM local"
},
"presentation": {
"type": "object",
"properties": {
"layout": {
"enum": [
"compact",
"full"
],
"type": "string",
"description": "Compact cards or the full view; keeps booking, add and error actions available."
}
},
"additionalProperties": false
},
"maxTotalAmount": {
"type": "integer",
"minimum": 0,
"description": "Whole-party one-way fare ceiling in integer minor units"
},
"returnDepartAfter": {
"type": "string",
"pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
"description": "Earliest return departure, HH:MM local; needs returnDate"
},
"maxDurationMinutes": {
"type": "integer",
"description": "Longest acceptable journey, in minutes",
"exclusiveMinimum": 0
},
"returnDepartBefore": {
"$ref": "#/properties/returnDepartAfter",
"description": "Latest return departure, HH:MM local; needs returnDate"
}
},
"additionalProperties": false
}