ETERA API Documentation

Search using vector mode - pure semantic similarity search using embeddings.

Best For:

Natural language queries
Conceptual searches
Queries like “quiet place for business meetings” or “romantic anniversary destination”

How it Works:

Query is converted to a vector embedding
k-NN search finds hotels with similar embedding vectors
Results ranked by cosine similarity score

Note: Works best with descriptive, natural language queries rather than keywords.

Request Body Example

1 {
2   "q": "romantic beachside getaway with spa",
3   "stars": 5,
4   "limit": 15
5 }

Search using **vector mode** - pure semantic similarity search using embeddings. **Best For:** - Natural language queries - Conceptual searches - Queries like "quiet place for business meetings" or "romantic anniversary destination" **How it Works:** 1. Query is converted to a vector embedding 2. k-NN search finds hotels with similar embedding vectors 3. Results ranked by cosine similarity score **Note:** Works best with descriptive, natural language queries rather than keywords. ### Request Body Example ```json { "q": "romantic beachside getaway with spa", "stars": 5, "limit": 15 } ```

Request

This endpoint expects an object.

qstringOptional0-500 characters

Search query text (e.g., ‘luxury hotels dubai’, ‘beachfront resort’)

querystringOptional0-500 characters

Alias for 'q' parameter

strategy"hybrid" or "text" or "vector"Optional

Search strategy: ‘text’ (BM25), ‘hybrid’ (text+vector), ‘vector’ (semantic). Omit to use route default.

requestIdstringOptional

Request ID from previous search. Use with page > 1 to fetch cached results.

pagedoubleOptional>=1Defaults to 1

Page number. Use with requestId for subsequent pages.

fetchSizedoubleOptional50-300Defaults to 100

Number of hotels to fetch and cache (50-300). Higher = more pages cached.

limitdoubleOptional1-100Defaults to 20

Results per page (default: 20, ignored when using requestId)

sizedoubleOptional1-100

Alias for 'limit'

offsetdoubleOptional>=0Defaults to 0

Deprecated: Use page instead

latdoubleOptional-90-90

Latitude for geo-search (requires lng)

lngdoubleOptional-180-180

Longitude for geo-search (requires lat)

radiusdoubleOptional1-500Defaults to 50

Search radius in kilometers (1-500, default: 50)

citystringOptional1-200 characters

Filter by city name

countrystringOptionalformat: "^[A-Za-z]{2}$"=2 characters

Filter by country code (ISO 3166-1 alpha-2). Must be a country code present in the index (e.g. AE, US, SA).

regionIddoubleOptional>=0

Filter by region ID (non-negative integer)

starsdoubleOptional1-5

Minimum star rating (1-5)

starRatingdouble or list of doublesOptional

Star rating filter - single number (1-5) or array of up to 10 values. Matches index values.

minStarRatingdoubleOptional1-5

Minimum star rating for range filter

maxStarRatingdoubleOptional1-5

Maximum star rating for range filter

kindlist of stringsOptional

Property types. Allowed: APART-HOTEL, APARTMENT, BNB, BOUTIQUE_AND_DESIGN, CAMPING, CASTLE, COTTAGES_AND_HOUSES, FARM, GLAMPING, GUESTHOUSE, HOSTEL, HOTEL, MINI-HOTEL, RESORT, SANATORIUM, VILLAS_AND_BUNGALOWS. Max 20 values.

hotelChainlist of stringsOptional

Hotel chain names (e.g., [‘Marriott’, ‘Hilton’]). Max 20 values.

familyFriendlybooleanOptional

Filter for family-friendly hotels (only set to true to filter)

petFriendlybooleanOptional

Filter for pet-friendly hotels (only set to true to filter)

businessFriendlybooleanOptional

Filter for business-friendly hotels (only set to true to filter)

wellnessSpabooleanOptional

Filter for hotels with spa/wellness facilities (only set to true to filter)

beachfrontbooleanOptional

Filter for beachfront properties (only set to true to filter)

freeWifibooleanOptional

Filter for hotels with free WiFi

breakfastIncludedbooleanOptional

Filter for hotels with breakfast included

petsAllowedbooleanOptional

Filter for hotels that allow pets

parkingAvailablebooleanOptional

Filter for hotels with parking available

freeParkingbooleanOptional

Filter for hotels with free parking

shuttleAvailablebooleanOptional

Filter for hotels with airport shuttle

childrenAllowedbooleanOptional

Filter for hotels that allow children

internetIncludedbooleanOptional

Filter for hotels with internet included

parkingIncludedbooleanOptional

Filter for hotels with parking included in rate

featureslist of stringsOptional

Filter by feature slugs (e.g. free_wifi, pool_outdoor). Values must exist in features.json. Max 50.

poiTypesNearbylist of stringsOptional

Filter by nearby POI types (e.g., [‘restaurant’, ‘beach’]). Max 30 values.

poiNamesNearbylist of stringsOptional

Filter by specific nearby POI names (e.g., [‘Burj Khalifa’, ‘Dubai Mall’]). Max 30 values.

excludeClosedbooleanOptionalDefaults to true

Exclude closed hotels (default: true)

providerHiddoubleOptional>=0

Filter by provider HID (non-negative integer)

providerIdstringOptional1-100 characters

Filter by provider ID (string)

sortBy"relevance" or "star_rating" or "name" or "distance" or "updated_at"Optional

Sort field: relevance, star_rating, name, distance, updated_at

sortOrder"asc" or "desc"Optional

Sort order: asc or desc

includeAggregationsbooleanOptionalDefaults to false

Include aggregations/facets in response

boostByQualitybooleanOptionalDefaults to false

Enable quality-based re-ranking. Boosts results by rating_global and star_rating. Useful for ranking by hotel quality while maintaining relevance.

qualityRatingWeightdoubleOptional0-1Defaults to 0.7

Weight for guest rating (rating_global) in quality scoring (0-1). Default: 0.7. Higher values prioritize guest ratings over star ratings.

qualityStarsWeightdoubleOptional0-1Defaults to 0.3

Weight for star rating in quality scoring (0-1). Default: 0.3. Higher values prioritize hotel stars over guest ratings.

checkInstringOptionalformat: "^\d{4}-\d{2}-\d{2}$"

Check-in date (YYYY-MM-DD). Required for real-time pricing.

checkOutstringOptionalformat: "^\d{4}-\d{2}-\d{2}$"

Check-out date (YYYY-MM-DD). Required for real-time pricing.

adultsdoubleOptional1-10Defaults to 2

Number of adults (1-10)

childrendoubleOptional0-4Defaults to 0

Number of children (0-4)

childAgeslist of doublesOptional

Ages of children (0-17 each). Array length should match ‘children’ count.

roomsdoubleOptional1-5Defaults to 1

Number of rooms (1-5)

currencystringOptionalformat: "^[A-Z]{3}$"=3 charactersDefaults to AED

Currency code for prices (ISO 4217, 3 letters)

Response

Search response with hotels and pagination support

successboolean

Whether the search was successful

datalist of any

Array of hotel results (20 per page)

metadataobject

errorstring or null

Error message if search failed

requestIdstring or null

Request ID for pagination. Use with page parameter for next pages.

searchMetadataobject or null

1	{
2	"success": true,
3	"data": [
4	null
5	],
6	"metadata": {
7	"total": 120,
8	"page": 1,
9	"limit": 20,
10	"totalPages": 6,
11	"filters": null,
12	"executionTime": 85,
13	"strategy": "vector",
14	"hasMore": true,
15	"cached": false
16	},
17	"error": "",
18	"requestId": "req_9f8b7c6d5e4a3b2c1d0e",
19	"searchMetadata": {
20	"query": "romantic beachside getaway with spa",
21	"mode": "vector",
22	"opensearchTook": 75,
23	"fetchedCount": 120
24	}
25	}

1	{
2	"q": "romantic beachside getaway with spa",
3	"stars": 5,
4	"limit": 15
5	}

1	curl -X POST https://api.etera.dev/hotel/search/v2/search/vector \
2	-H "Content-Type: application/json" \
3	-d '{}'