Search hotel rooms by image and text (Beta)
Overview
Beta Feature - Search hotel rooms using visual and text-based queries. Uses image search technology to match your query against room images and find hotels with rooms that match your visual preferences, amenities, or style.
When to Use
- Visual room search - Find rooms based on visual characteristics like “luxury modernist comfort” or “blue accessible bathroom”
- Style-based search - Search for rooms by design style like “art deco hotel room” or “brutalist room”
- Amenity-focused search - Find rooms with specific features like “twin room with a city view” or “room with a skylight”
- Geographic filtering - Limit results to hotels near a specific location using coordinates or Place ID
- City and country filtering - Filter results by city and/or country
What You Get
- Matching hotels - Hotels grouped by hotel ID with rooms that match your query
- Room details - Room name, image URL, and similarity score (rounded to 3 decimals) for each matching room
- Hotel metadata - ID, name, address, city, country, and rating for each hotel
- Geographic filtering - Optionally limit results to a specific area using coordinates or Place ID
- City and country filters - Filter results by city and/or country code
Example Queries
- “luxury modernist comfort”
- “an extremely fun room or art deco hotel room”
- “luxurious accessible bathroom or blue accessible bathroom with walk in shower”
- “twin room with a city view”
- “a room filled with paintings”
- “a hotel room with a skylight”
Geographic Filtering
You can optionally limit search results to a specific geographic area:
- Using coordinates: Provide
latitude,longitude, and optionallyradius(in kilometers, default: 12km) - Using Place ID: Provide
placeId- the place’s location will be automatically fetched and the search will use the place’s viewport boundaries (or the providedradiusif viewport is unavailable) - Using city/country: Provide
cityand/orcountryto filter results by location
Quick Start
Provide a query parameter describing the room you’re looking for. Optionally add geographic filtering with latitude/longitude or placeId to limit results to a specific area.
Note: This is a beta feature and may be subject to changes.
Authorizations
Query Parameters
Search query describing the room you're looking for. Can be visual (e.g., 'luxury modernist comfort', 'blue accessible bathroom'), amenity-based (e.g., 'twin room with a city view'), or style-based (e.g., 'art deco hotel room', 'brutalist room')
Maximum number of results to return (maps to top_k in the API)
x >= 1Place ID. If provided, the search will be limited to hotels within the place's viewport boundaries (or the provided radius if viewport is unavailable). The place's latitude and longitude will be automatically fetched.
Latitude coordinate for geographic filtering. Must be provided together with longitude. Ignored if placeId is provided.
Longitude coordinate for geographic filtering. Must be provided together with latitude. Ignored if placeId is provided.
Search radius in kilometers. Only used when latitude/longitude is provided, or when placeId is provided but the place does not have viewport information. When placeId is provided and viewport is available, the viewport boundaries are used instead of this radius. Default is 12km.
x >= 0Filter results by city name. Can be used alone or together with country.
Filter results by country code (ISO 3166-1 alpha-2 format, e.g., 'FR', 'US'). Can be used alone or together with city.
Response
OK