/search

Search for hotels and offers by various criteria.

Endpoint URL

https://partners.api.vio.com/v1/search

HTTP Method

POST

Headers

Name	Required	Description
X-Partner-Key	Yes	Partner's profile key
Content-Type	Yes	application/json
Accept-Encoding	No	gzip, deflate, br

Request body

The request body contains a search request payload in JSON format.

Name	Required	Type	Description	Example	Default
query	Yes	Query	The way to query hotels.	{ hotelIds: ["123","456"], hotelIdsProvider: "EXP"}
checkIn	No	string	Check in date (YYYY-MM-DD). It must be within 0 and 365 days from today. If not specified, then default dates are picked.	"2023-05-10"
checkOut	No	string	Check out date (YYYY-MM-DD). It must be within 1 and 31 days from the checkIn. If not specified, then default dates are picked.	"2023-05-11"
rooms	Yes	string	See rooms configuration	"2:4,6"	"2"
language	Yes	string	See supported languages	"es"	"en"
currency	Yes	string	See supported currencies	"USD"	"EUR"
anonymousId	No	string	Anonymous user identifier for tracking purposes.	"e0775301-a95a-4b56-a727-9cec40a013af"
userDevice	Yes	string	The type of the user's device: desktop,mobile,tablet. If not specified then API determines it based on the caller's User-Agent header.	"desktop"	"desktop"
userCountry	Yes	string	The 2-char ISO 3166 country code of a user. If not specified then API determines it based on the caller's IP address.	"US"
timeout	No	integer	Maximum time in seconds to process a request. Setting this timeout allows to receive a response without waiting for offers from slow providers, but it also may lead to an incomplete or empty list of offers in a response.	10
hotelAttributes	No	string[]	The list of extra hotel attributes to include in a response: details.	["details"]
filters	No	Filters	Set of filters.	{"guestRating": 9}
pageSize	No	integer	Max number of hotels in a response. Must be between 1 and 20.	1	20
sortField	No	string	Sort criteria: price, guestRating.	"price"
sortOrder	No	string	Sort order: ascending,descending.	"ascending"
label	No	string	Arbitrary string for tracking and reporting.
attributes	No	string[]	The list of extra attributes to include in a response: availableHotelsCount.	["availableHotelsCount"]
optimizeRooms	No	boolean	When enabled, the most cost-effective room combinations will be searched for a given occupancy request (rooms field). For example, for 6 people, it will compare offers across different configurations like one 6-person room ("6"), two 3-person rooms ("3|3"), or three 2-person rooms ("2|2|2"), returning only the best option per hotel. This feature is not enabled by default, reach the support if you are going to use it.	true	false

Query

The endpoint supports several ways to query hotels:

• By hotel IDs
• By hotel names
• By place name
• By place ID
• By IATA code (most relevant closest place is returned)
• By Geo coordinates

The only one parameter must be used in a single request. The hotelIds parameter is only supported if the partner hotel inventory has been mapped to Vio.com hotel database during the onboarding.

Name	Required	Type	Description	Example
hotelIds	No	string[]	The list of hotel IDs. The number of IDs must be between 1 and 50.	["123", "432"]
hotelIdsProvider	No	string	Used to specify the source of the list of Hotel IDs provided in the hotelIds parameter, which affiliate it should be mapped from (Expedia -> EXP, etc).	EXP
hotelNames	No	HotelNamesQuery	Set of parameters to query by hotel names.
place	No	PlaceQuery	Set of parameters to query by place.	{"name": "London"}
placeId	No	string	Place ID.	"158584"
iataCode	No	string	IATA code of an airport.	"AMS"
lat	No	number	Latitude.
lon	No	number	Longitude.
precision	No	string	Used to rank hotels in each precision range equally (for more information see below).	0-100,1000-10000,25000-50000
radius	No	number	Optional radius of nearby search in meters. If not provided, it will be considered as infinite radius. radius will be used only if the lat/lon parameters are provided.	25000

Precision Ranges

Specifies the precision for geographic search results, defined as a string in "from-value" format, where each pair influences how results are grouped by distance for ranking purposes.

Each pair in PrecisionRanges is written as "from-value", where from is the starting distance (in meters) and value defines the precision for that range. For example, "0-100" will group all results starting from 0 meters at a precision of 100 meters, meaning all results within a 0-99 meter radius are ranked equally.

Multiple ranges can be specified as comma-separated pairs, such as "0-100,1000-10000,25000-50000". In this example, results within 0 meters have a precision of 100 meters, so distances from 0-99 are treated equally. Starting from 1000 meters, distances are grouped with a precision of 10000 meters, meaning that any result between 1000 and 10999 (1000 + 9999) meters is ranked equally based on proximity. Similarly, results from 25000 meters are grouped with a precision of 25000 meters, meaning that all distances from 25000 to 49999 meters are treated as equal. This format allows flexible, non-linear precision grouping to optimize geo-ranking by reducing overly precise calculations for distant results.

HotelNamesQuery

Name	Required	Type	Description	Example
names	Yes	string[]	The list of of hotel names. The number of names must be between 1 and 50.	["May Ramblas Hotel", "Vincci Maritimo"]
country	No	string	Country of hotels. Use this parameter to refine the search if there are hotels with the same names in another country. See countries	"Spain"
city	No	string	City of hotels. Use this parameter to refine the search if there are hotels with the same names in another city.	"Barcelona"

If you need to query hotels by names for different cities/countries, you can do it in separate requests.

PlaceQuery

Name	Required	Type	Description	Example
name	Yes	string	Name of the place to query.	"London"
country	No	string	Country of hotels. Use this parameter to refine the search if there are hotels with the same names in another country. See countries	"United Kingdom"

Filters

Name	Required	Type	Description	Example
starRatings	No	integer[]	The list of star ratings. Star rating is a number between 0 and 5.	[4,5]
price	No	PriceFilter	Price filter parameters.	{"min": 200}
guestRating	No	string	Minimum overall guest rating. Guest rating is a number between 0 and 10.	9
propertyTypes	No	integer[]	The list of property type ids. See property types	[0]
notPropertyTypes	No	integer[]	The list of property type ids to exclude. See property types	[5]
themes	No	integer[]	The list of theme ids. See themes	[2]
facilities	No	integer[]	The list of facility ids. See facilities	[299]
freeCancellation	No	boolean	If true, only offers with free cancellation will be returned. If false, only offers without free cancellation will be returned. Omits the filter if not set.	true

PriceFilter

Name	Required	Type	Description	Example
min	No	integer	Minimum total rate in requested currency.	200
max	No	integer	Maximum total rate in requested currency.	400

Dynamic Click Tracking

Click tracking is available using Dynamic Click Tracking

Examples

Searching by hotel names

Bash

curl --request POST 'https://partners.api.vio.com/v1/search' \
--header 'X-Partner-Key: <profile key>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "checkIn": "2023-10-19",
    "checkOut": "2023-10-20",
    "query": {
        "hotelNames": {
            "names": [
                "New York - New York Hotel and Casino",
                "Palms Place Hotel and Spa",
                "The Palazzo at The Venetian"
            ],
            "city": "Las Vegas",
            "country": "United States"
        }
    },
    "rooms": "2",
    "language": "en",
    "currency": "EUR",
    "userCountry": "US",
    "userDevice": "desktop"
}'

Javascript

fetch("https://partners.api.vio.com/v1/search", {
  method: "POST",
  headers: {
    "X-Partner-Key": "partner-profile-key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    checkIn: "2023-10-19",
    checkOut: "2023-10-20",
    query: {
        hotelNames: {
            names: [
                "New York - New York Hotel and Casino",
                "Palms Place Hotel and Spa",
                "The Palazzo at The Venetian"
            ],
            city: "Las Vegas",
            country: "United States"
        }
    },
    rooms: "2",
    language: "en",
    currency: "EUR",
    userCountry: "US",
    userDevice: "desktop",
  }),
})
  .then((response) => response.json())
  .then((data) => console.log(data))
  .catch((error) => console.error(error));

Python

import requests
import json

url = "https://partners.api.vio.com/v1/search"
headers = {"X-Partner-Key": "partner-profile-key", "Content-Type": "application/json"}

payload = {
    "checkIn": "2023-10-19",
    "checkOut": "2023-10-20",
    "query": {
        "hotelNames": {
            "names": [
                "New York - New York Hotel and Casino",
                "Palms Place Hotel and Spa",
                "The Palazzo at The Venetian"
            ],
            "city": "Las Vegas",
            "country": "United States"
        }
    }
    "rooms": "2",
    "language": "en",
    "currency": "EUR",
    "userCountry": "US",
    "userDevice": "desktop"
}

response = requests.post(url, headers=headers, data=json.dumps(payload))

print(response.json())

Searching by city name

Bash

curl --request POST 'https://partners.api.vio.com/v1/search' \
--header 'X-Partner-Key: <profile key>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "checkIn": "2023-10-19",
    "checkOut": "2023-10-20",
    "query": {
        "place": {
            "name": "London"
        }
    },
    "hotelAttributes": ["details"],
    "rooms": "2",
    "language": "en",
    "currency": "EUR",
    "userCountry": "GB",
    "userDevice": "mobile"
}'

Searching by city name with price filter and sorting

This request searches for hotels in London with total price (including taxes) between 200 EUR and 400 EUR. Results are sorted by price from lower to higher. The timeout parameter sets the maximum execution time to 6 seconds.

Bash

curl --request POST 'https://partners.api.vio.com/v1/search' \
--header 'X-Partner-Key: <profile key>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "checkIn": "2023-10-19",
    "checkOut": "2023-10-20",
    "query": {
        "place": {
            "name": "London"
        }
    },
    "hotelAttributes": ["details"],
    "rooms": "2",
    "language": "en",
    "currency": "EUR",
    "userCountry": "GB",
    "userDevice": "mobile",
    "sortField": "price",
    "sortOrder": "ascending",
    "filters": {
        "price": {
            "min": 200,
            "max": 400
        }
    },
    "timeout": 6
}'

Response

The response payload has the following fields:

Field	Required	Type	Description
hotels	Yes	Hotel[]	The list of hotels.
failedToMap	No	string[]	The list of hotels that the API failed to map to a Vio.com hotel.
place	No	Place	Requested place if queried by place or placeId.
stay	No	Stay	Requested stay.
availableHotelsCount	No	integer	An approximate count of available hotels. For popular places, it's close to the real number of available hotels. For unpopular places it could be much less. Available for place searches if "availableHotelsCount" value is specified in the "attributes" request parameter.

Hotel

Field	Required	Type	Description
id	No	string	Hotel ID if queried by hotel IDs.
requestedName	No	string	Hotel name if queried by hotel names.
details	No	HotelDetails	Hotel details. Available if the "details" value is specified in the hotelAttributes request parameter.
offers	Yes	Offer[]	The list of offers.
anchorRate	No	Rate	Strike through price.

Example:

{
  "requestedName": "Leonardo Hotel Amsterdam Rembrandtpark",
  "offers": [...]
}

HotelDetails

Field	Required	Type	Description
name	Yes	string	Name of the hotel.
location	Yes	Geolocation	Geolocation of the hotel.
address	Yes	string	Address of the hotel.
starRating	No	integer	Star rating from 0 to 5.
images	No	string[]	The list of hotel images.
distanceFromCityCentre	No	integer	Distance from city centre in meters.
guestRatings	No	GuestRating	Guest ratings per category.
cityName	No	string	City name.
reviewCount	No	integer	Review count.
vioUrl	Yes	string	URL of the hotel on Vio website.
facilities	No	integer[]	The list of hotel facility ids.

GuestRating

Field	Required	Type
cleanliness	No	number
dining	No	number
facilities	No	number
location	No	number
overall	No	number
pricing	No	number
rooms	No	number
service	No	number

Example:

{
    "name": "Leonardo Hotel Amsterdam Rembrandtpark",
    "location": {
        "lat": 52.368132,
        "lon": 4.844
    },
    "address": "Staalmeesterslaan 410",
    "starRating": 4,
    "images": [
        "https://....jpg"
    ],
    "distanceFromCityCentre": 3435
}

Geolocation

Field	Required	Type	Description
lat	Yes	number	Latitude in degrees.
lon	Yes	number	Longitude in degrees.

Example:

{
    "lat": 52.368132,
    "lon": 4.844
}

Offer

Name	Required	Type	Description
rate	Yes	Rate	Object that contains details about the price of the Offer.
currency	Yes	string	The currency applied to every rate in the offer. Currency is a 3 letter string following ISO 4217.
package	Yes	Package	An object containing the attributes related to benefits that come with the offer.
provider	Yes	Provider	The provider distributing this offer, not necessarily the same as the provider selling the offer.
cancellationPenalties	Yes	CancellationPenalties[]	Offers cancellation penalties.
roomName	Yes	string	Room name of the offer.
room	No	Room	Room details of the offer. This object is disabled by default, contact your account manager to enable it.
url	Yes	string	The URL that redirects a user to book or view more details about this offer.

Room

Name	Required	Type	Description
name	Yes	string	Room name.
type	No	string	Room type.
layout	No	Layout	Room layout details.
amenities	No	string[]	An array of strings with the amenities of the room.
images	No	string[]	Room images URLs.

Layout

Name	Required	Type	Description
area	No	number	Surface area of this room in square meters.
bedroomCount	No	integer	Number of bedrooms.
bathroomCount	No	integer	Number of bathrooms.
bedrooms	No	Bedroom[]	Available bedroom configurations.

Bedroom

Name	Required	Type	Description
name	No	string	Name of bedroom.
description	No	string	Bedroom description.
bedConfigurations	No	BedConfiguration[]	How beds are configured in the bedroom.

BedConfiguration

Name	Required	Type	Description
name	No	string	Name of the bed.
description	No	string	Description of the bed.
size	Yes	string	Size of the bed.
count	Yes	integer	Number of beds.
type	No	string	Type of the bed.

Provider

Information about the provider of the offer.

Name	Required	Type	Description
name	Yes	string	Provider's name in english.
logoUrl	Yes	string	Provider logo url.

Example:

{
  "name": "Vio.com",
  "logoUrl": "https://i.fih.io/provider/svg/fht.svg"
}

CancellationPenalties

Name	Required	Type	Description
start	Yes	string	Date and time when the penalty starts to apply.
end	Yes	string	Date and time when the penalty stops to apply.
amount	Yes	string	Fixed amount of the penalty.
currency	Yes	string	Currency of the fixed amount.

Example:

{
  "start": "2023-04-13T23:59:00.000-08:00",
  "end": "2023-04-20T23:59:00.000-08:00",
  "amount": "325.25",
  "currency": "EUR"
}

Package

An object describing conditions and complimentary benefits of the offer.

Name	Required	Type	Description
amenities	Yes	string[]	An array of strings (enums) with the amenities of the offer. See package amenities.
canPayLater	Yes	boolean	Indicates if the user can be charged later for the offer.

Example:

{
  "amenities": ["breakfast", "internetIncluded"],
  "canPayLater": false
}

Rate

An object that contains the offer price breakdown. All prices are specified per room.

Name	Required	Type	Description
base	Yes	number	The rate exclusive of any taxes and hotel fees.
hotelFees	Yes	number	The sum of all mandatory taxes and fees that the customer will need to pay at the hotel. For example, a resort fee.
taxes	Yes	number	Value added tax (VAT).

Example:

{
  "base": 120,
  "hotelFees": 14,
  "taxes": 23
}

Place

Field	Required	Type	Description
id	Yes	string	Place ID.
name	Yes	string	Place name.
address	Yes	string	Place address from the requested place to its country.
vioUrl	Yes	string	URL of the place on Vio website.

Example:

{
  "id": "158584",
  "name": "London",
  "address": "London, England, United Kingdom"
}

Stay

Field	Required	Type	Description
checkIn	Yes	string	Check in date (YYYY-MM-DD) which was used in search.
checkOut	Yes	string	Check out date (YYYY-MM-DD) which was used in search.

Example:

{
  "checkIn": "2023-05-21",
  "checkOut": "2023-05-22"
}

Live demos

Multiple Hotel Offers Search

This is an example of how the /search endpoint can be used to create an offer comparison list per each queried hotel.

Single Hotel Offers Search

This is an example of how the /search endpoint can be used to create an offer comparison list for one specific hotel, showing deal details such as meals, cancellation policy and pay now/later.