Hotels

Search

Structured hotel search over the catalogue. No LLM is involved.

Works without an API key (per-IP rate limit; include_rates is ignored). Key-less results carry a price only when both check_in and check_out are given: the cached all-inclusive total for exactly that stay, when one is available (no live lookup). With a Build (or higher) key, include_rates=true plus check_in/check_out also fetches live rates for those dates.

post/v1/search

Request

  • Base URL: https://api.vistalink.com
  • URL: https://api.vistalink.com/v1/search
  • Auth: one of:
    • none
    • HTTP bearer

Request body

citystring nullable

City to search in, e.g. 'Lisbon'. A search needs city, latitude+longitude, or hotel_name.

countrystring nullable

ISO 3166-1 alpha-2 country code of the city, e.g. 'PT'. Use it for city names that exist in several countries (Paris FR vs Paris US).

areastring nullable

Neighbourhood or landmark within city to search around, e.g. 'Brera' or 'Colosseum' (with city='Milan' / 'Rome'). Results are limited to hotels near it.

latitudenumber nullable

Search centre latitude in decimal degrees, used with longitude (0 = not set).

longitudenumber nullable

Search centre longitude in decimal degrees, used with latitude (0 = not set).

radius_metersinteger nullable

Radius around latitude/longitude in metres (0 = default).

check_instring date nullable

Check-in date, YYYY-MM-DD (today or later). Prices need check_in and check_out.

check_outstring date nullable

Check-out date, YYYY-MM-DD, after check_in.

guestsinteger nullable

Number of adult guests (0 = default of 2).

roomsinteger nullable

Number of rooms (0 = 1). Prices are only quoted for one room.

budget_minnumber nullable

Minimum price per night (request currency)

budget_maxnumber nullable

Maximum price per night (request currency)

daily_budget_minnumber nullable

Synonym of budget_min (per-night floor); wins if both sent

daily_budget_maxnumber nullable

Synonym of budget_max (per-night cap); wins if both sent

currencystring nullable

ISO 4217 currency code for prices, e.g. 'EUR', 'USD', 'GBP'.

amenitiesstring[] nullable

Amenities the hotel must have, e.g. ['wifi', 'pool'].

vibestring[] nullable

What the traveller is looking for, as free-text phrases or tags, e.g. ['boutique design hotel'] or ['romantic', 'quiet'].

hotel_namestring nullable

Hotel name or part of it, e.g. 'Four Seasons'.

limitinteger

Maximum number of results, 1-20 without an API key (1-50 with one). Larger values are reduced to the maximum.

include_ratesboolean

Fetch live rates from booking scraper (adds ~30-45s). Requires an API key; ignored key-less

Example request

{
  "city": "Lisbon",
  "country": "PT",
  "area": "Brera",
  "check_in": "2026-11-01",
  "check_out": "2026-11-03",
  "currency": "EUR",
  "hotel_name": "Four Seasons"
}

Response

Successful Response

totalinteger
fallback_usedboolean
fallback_messagestring nullable
pricing_notestring nullable

Why results carry no (or only some) prices: prices need both check_in and check_out, and are only the all-inclusive total for that stay. Key-less: the cached total for those dates; with a key, include_rates=true also fetches live rates.

notesstring[] nullable

How the request was interpreted, when it was not taken literally: an alias read as its documented name, a city taken from vibe, a country chosen for a city name found in several countries, a reduced limit.

Changes

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