Search luxury properties

Natural language property search across 300+ luxury resorts. Supports structured constraints (dates, budget, guests) alongside free-text queries. Returns ranked results with match explanations.

post/search

Request

  • Base URL: https://api.tellandgo.com/api/v1/agent
  • URL: https://api.tellandgo.com/api/v1/agent/search
  • Auth: API key in header X-API-Key

Request body

querystring required

Natural language search query

residencystring required

Required ISO 3166-1 alpha-2 citizenship/residency code. Passed to live supplier searches as residency.

session_idstring
limitinteger
offsetinteger
client_defaultsstring[]

Names of request fields the CALLING CLIENT filled with its own defaults rather than values the end user stated. Only the listed tokens are recognized; unknown tokens are ignored. The response's effective_request reports those fields with source "default" and lists them in assumptions so the agent can disclose them.

Example request

{
  "query": "Overwater villa in the Maldives for a honeymoon in March",
  "residency": "US",
  "constraints": {
    "destination": "Maldives"
  }
}

Response

Search results

successboolean
status'results' | 'partial_results' | 'no_match' | 'filtered_empty' | 'needs_input' | 'supplier_degraded'

Machine-readable outcome, additive next to success (whose semantics are unchanged). Deterministic precedence, first match wins: (1) no_match when zero catalogue matches; (2) partial_results when the page has properties and live pricing timed out; (3) results when the page has properties; (4) filtered_empty when the page is empty because budget/no-live-rate filters removed every candidate; (5) supplier_degraded when the page is empty and the live-pricing stage timed out; (6) needs_input when the page is empty, unexplained by filters or degradation, and a refine question is attached; (7) no_match as the fallback (e.g. paging past the last page).

results_notestring

Present when post-pricing filters removed results or live pricing degraded. Read before concluding "no availability" — it distinguishes a filter miss from missing inventory.

pricing_status'partial'

Live pricing hit its internal deadline; shown results are catalogue matches (per-entry pricing.status="deadline_exceeded"). Use the quote endpoint for firm prices.

booking_urlstring uri

Changes

No recorded changes to this operation across all 1 revision of this API.