{"openapi":"3.0.3","info":{"title":"ETERA Hotel Search API","description":"\n# Hotel Search & Discovery Engine\n\nIntelligent hotel search powered by OpenSearch with real-time ETG pricing integration.\n\n## Quick Start\n\n### Search Hotels\n```bash\n# Hybrid search (recommended)\nGET /v2/search?q=luxury hotels dubai\n\n# With real-time pricing\nGET /v2/search?q=dubai&checkIn=2026-03-01&checkOut=2026-03-05&adults=2\n```\n\n## Search Strategies\n\n| Strategy | Best For | Endpoint |\n|----------|----------|----------|\n| **Hybrid** | General queries | `/v2/search` or `/v2/search/hybrid` |\n| **Text** | Exact matches | `/v2/search/text` |\n| **Vector** | Natural language | `/v2/search/vector` |\n\n## Authentication\nNo authentication required for search endpoints.\n\n## Rate Limits\nRecommended: max 10 requests/second per client.\n          ","version":"2.0.0","contact":{"name":"ETERA API Support","email":"support@etera.dev"}},"tags":[{"name":"V2 Search","description":"Primary hotel search endpoints with hybrid/text/vector strategies and real-time pricing"},{"name":"Analytics","description":"Search statistics and performance metrics"},{"name":"MCP Tools","description":"Model Context Protocol tools for AI integrations"},{"name":"Health","description":"Service health and status endpoints"}],"servers":[{"url":"http://localhost:3000","description":"Local Development"},{"url":"https://api-dev.etera.dev/hotel","description":"Development Server"}],"paths":{"/mcp/tools":{"get":{"operationId":"getMcpTools","tags":["MCP Tools"],"summary":"List Available MCP Tools","description":"\nGet all available MCP tools for AI/LLM integration.\n\n### Response\nReturns array of tools with:\n- `name`: Tool identifier\n- `description`: What the tool does\n- `inputSchema`: JSON Schema for parameters\n- `outputSchema`: Expected response format\n\n### Use Case\nAI assistants can discover available search capabilities\nand understand how to call them.\n      ","responses":{"200":{}}}},"/mcp/tools/{tool}":{"get":{"operationId":"getMcpToolsByTool","tags":["MCP Tools"],"summary":"Get Tool Schema","description":"\nGet detailed schema for a specific MCP tool.\n\n### Parameters\n- `tool`: Tool name (path parameter)\n\n### Response\nFull tool definition including:\n- Input parameters with types and descriptions\n- Required vs optional fields\n- Example values\n- Output format\n      ","parameters":[{"schema":{"type":"string"},"in":"path","name":"tool","required":true}],"responses":{"200":{}}}},"/mcp/execute/{tool}":{"post":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"tool","required":true}],"operationId":"postMcpExecuteByTool","tags":["MCP Tools"],"summary":"Execute MCP Tool","description":"\nExecute a specific MCP tool with provided parameters.\n\n### Parameters\n- `tool`: Tool name (path parameter)\n\n### Request Body\nTool-specific parameters as JSON object.\nRefer to tool schema for required parameters.\n\n### Example\n```bash\nPOST /mcp/execute/search_hotels\nContent-Type: application/json\n\n{\n  \"query\": \"luxury hotels in dubai\",\n  \"limit\": 10\n}\n```\n      ","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","patternProperties":{"^(.*)$":{}}}},"multipart/form-data":{"schema":{"type":"object","patternProperties":{"^(.*)$":{}}}},"text/plain":{"schema":{"type":"object","patternProperties":{"^(.*)$":{}}}}}},"responses":{"200":{}}}},"/mcp/health":{"get":{"operationId":"getMcpHealth","tags":["Health"],"summary":"MCP Health Check","description":"Check if MCP module is healthy and responsive.","responses":{"200":{}}}},"/v2/search":{"post":{"parameters":[],"responses":{"200":{"description":"Search response with hotels and pagination support","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"description":"Whether the search was successful","type":"boolean"},"data":{"description":"Array of hotel results (20 per page)","type":"array","items":{}},"error":{"description":"Error message if search failed","type":"string"},"requestId":{"description":"Request ID for pagination. Use with page parameter for next pages.","type":"string"},"metadata":{"type":"object","properties":{"total":{"description":"Total number of matching hotels","type":"number"},"page":{"description":"Current page number","type":"number"},"limit":{"description":"Results per page (20)","type":"number"},"totalPages":{"description":"Total number of pages available","type":"number"},"hasMore":{"description":"Whether more results are available","type":"boolean"},"cached":{"description":"Whether results came from cache","type":"boolean"},"filters":{"description":"Applied filters"},"executionTime":{"description":"Search execution time in ms","type":"number"},"strategy":{"description":"Search strategy used","type":"string"}},"required":["total","page","limit","totalPages","filters","executionTime","strategy"]},"searchMetadata":{"type":"object","properties":{"query":{"type":"string"},"mode":{"type":"string"},"opensearchTook":{"type":"number"},"embeddingMs":{"description":"Time in ms spent generating query embedding (vector/hybrid)","type":"number"},"fetchedCount":{"description":"Total hotels fetched and cached","type":"number"}}}},"required":["success","data","metadata"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"success":{"description":"Whether the search was successful","type":"boolean"},"data":{"description":"Array of hotel results (20 per page)","type":"array","items":{}},"error":{"description":"Error message if search failed","type":"string"},"requestId":{"description":"Request ID for pagination. Use with page parameter for next pages.","type":"string"},"metadata":{"type":"object","properties":{"total":{"description":"Total number of matching hotels","type":"number"},"page":{"description":"Current page number","type":"number"},"limit":{"description":"Results per page (20)","type":"number"},"totalPages":{"description":"Total number of pages available","type":"number"},"hasMore":{"description":"Whether more results are available","type":"boolean"},"cached":{"description":"Whether results came from cache","type":"boolean"},"filters":{"description":"Applied filters"},"executionTime":{"description":"Search execution time in ms","type":"number"},"strategy":{"description":"Search strategy used","type":"string"}},"required":["total","page","limit","totalPages","filters","executionTime","strategy"]},"searchMetadata":{"type":"object","properties":{"query":{"type":"string"},"mode":{"type":"string"},"opensearchTook":{"type":"number"},"embeddingMs":{"description":"Time in ms spent generating query embedding (vector/hybrid)","type":"number"},"fetchedCount":{"description":"Total hotels fetched and cached","type":"number"}}}},"required":["success","data","metadata"]}},"text/plain":{"schema":{"type":"object","properties":{"success":{"description":"Whether the search was successful","type":"boolean"},"data":{"description":"Array of hotel results (20 per page)","type":"array","items":{}},"error":{"description":"Error message if search failed","type":"string"},"requestId":{"description":"Request ID for pagination. Use with page parameter for next pages.","type":"string"},"metadata":{"type":"object","properties":{"total":{"description":"Total number of matching hotels","type":"number"},"page":{"description":"Current page number","type":"number"},"limit":{"description":"Results per page (20)","type":"number"},"totalPages":{"description":"Total number of pages available","type":"number"},"hasMore":{"description":"Whether more results are available","type":"boolean"},"cached":{"description":"Whether results came from cache","type":"boolean"},"filters":{"description":"Applied filters"},"executionTime":{"description":"Search execution time in ms","type":"number"},"strategy":{"description":"Search strategy used","type":"string"}},"required":["total","page","limit","totalPages","filters","executionTime","strategy"]},"searchMetadata":{"type":"object","properties":{"query":{"type":"string"},"mode":{"type":"string"},"opensearchTook":{"type":"number"},"embeddingMs":{"description":"Time in ms spent generating query embedding (vector/hybrid)","type":"number"},"fetchedCount":{"description":"Total hotels fetched and cached","type":"number"}}}},"required":["success","data","metadata"]}}}}},"operationId":"postV2Search","tags":["V2 Search"],"summary":"Search Hotels","description":"\nSearch hotels with flexible strategy selection and built-in pagination.\n\n**How it works:**\n1. First request fetches 100 hotels, gets ETG pricing, caches results\n2. Returns first 20 results with a `requestId`\n3. Use `requestId` + `page` for subsequent pages (instant from cache)\n\n**Default Strategy:** hybrid (BM25 + vector — best overall results). Falls back to text automatically if the embedding service is unavailable.\n\n**Override Strategy:** Pass `strategy: \"text\"` for pure BM25, or `strategy: \"vector\"` for semantic-only search.\n\n**Real-time Pricing:** Add `checkIn` and `checkOut` to get live rates from ETG.\n\n### Initial Search\n```json\n{\n  \"q\": \"luxury beach resort\",\n  \"city\": \"Dubai\",\n  \"checkIn\": \"2026-03-01\",\n  \"checkOut\": \"2026-03-05\",\n  \"adults\": 2\n}\n```\n\n### Pagination (page 2+)\n```json\n{\n  \"requestId\": \"uuid-from-first-response\",\n  \"page\": 2\n}\n```\n        ","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"q":{"minLength":0,"maxLength":500,"description":"Search query text (e.g., 'luxury hotels dubai', 'beachfront resort')","examples":["luxury hotels dubai","family friendly resort"],"type":"string"},"query":{"minLength":0,"maxLength":500,"description":"Alias for 'q' parameter","type":"string"},"strategy":{"description":"Search strategy: 'text' (BM25), 'hybrid' (text+vector), 'vector' (semantic). Omit to use route default.","anyOf":[{"const":"hybrid","type":"string"},{"const":"text","type":"string"},{"const":"vector","type":"string"}]},"requestId":{"description":"Request ID from previous search. Use with page > 1 to fetch cached results.","type":"string"},"page":{"minimum":1,"default":1,"description":"Page number. Use with requestId for subsequent pages.","type":"number"},"fetchSize":{"minimum":50,"maximum":300,"default":100,"description":"Number of hotels to fetch and cache (50-300). Higher = more pages cached.","type":"number"},"limit":{"minimum":1,"maximum":100,"default":20,"description":"Results per page (default: 20, ignored when using requestId)","type":"number"},"size":{"minimum":1,"maximum":100,"description":"Alias for 'limit'","type":"number"},"offset":{"minimum":0,"default":0,"description":"Deprecated: Use page instead","type":"number"},"lat":{"minimum":-90,"maximum":90,"description":"Latitude for geo-search (requires lng)","examples":[25.2048],"type":"number"},"lng":{"minimum":-180,"maximum":180,"description":"Longitude for geo-search (requires lat)","examples":[55.2708],"type":"number"},"radius":{"minimum":1,"maximum":500000,"description":"Search radius in meters (1-500000, default: 50000)","default":50000,"examples":[1000,10000,50000],"type":"number"},"city":{"minLength":1,"maxLength":200,"description":"Filter by city name","examples":["Dubai","Abu Dhabi"],"type":"string"},"country":{"minLength":2,"maxLength":2,"pattern":"^[A-Za-z]{2}$","description":"Filter by country code (ISO 3166-1 alpha-2). Must be a country code present in the index (e.g. AE, US, SA).","examples":["AE","SA","US"],"type":"string"},"regionId":{"minimum":0,"description":"Filter by region ID (non-negative integer)","type":"number"},"stars":{"minimum":1,"maximum":5,"description":"Minimum star rating (1-5)","type":"number"},"starRating":{"description":"Star rating filter - single number (1-5) or array of up to 10 values. Matches index values.","examples":[[4,5]],"anyOf":[{"minimum":1,"maximum":5,"type":"number"},{"maxItems":10,"type":"array","items":{"minimum":1,"maximum":5,"type":"number"}}]},"minStarRating":{"minimum":1,"maximum":5,"description":"Minimum star rating for range filter","type":"number"},"maxStarRating":{"minimum":1,"maximum":5,"description":"Maximum star rating for range filter","type":"number"},"kind":{"maxItems":20,"description":"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.","examples":[["HOTEL","RESORT"]],"type":"array","items":{"minLength":1,"maxLength":100,"type":"string"}},"hotelChain":{"maxItems":20,"description":"Hotel chain names (e.g., ['Marriott', 'Hilton']). Max 20 values.","type":"array","items":{"minLength":1,"maxLength":150,"type":"string"}},"familyFriendly":{"description":"Filter for family-friendly hotels (only set to true to filter)","type":"boolean"},"petFriendly":{"description":"Filter for pet-friendly hotels (only set to true to filter)","type":"boolean"},"businessFriendly":{"description":"Filter for business-friendly hotels (only set to true to filter)","type":"boolean"},"wellnessSpa":{"description":"Filter for hotels with spa/wellness facilities (only set to true to filter)","type":"boolean"},"beachfront":{"description":"Filter for beachfront properties (only set to true to filter)","type":"boolean"},"freeWifi":{"description":"Filter for hotels with free WiFi","type":"boolean"},"breakfastIncluded":{"description":"Filter for hotels with breakfast included","type":"boolean"},"petsAllowed":{"description":"Filter for hotels that allow pets","type":"boolean"},"parkingAvailable":{"description":"Filter for hotels with parking available","type":"boolean"},"freeParking":{"description":"Filter for hotels with free parking","type":"boolean"},"shuttleAvailable":{"description":"Filter for hotels with airport shuttle","type":"boolean"},"childrenAllowed":{"description":"Filter for hotels that allow children","type":"boolean"},"internetIncluded":{"description":"Filter for hotels with internet included","type":"boolean"},"parkingIncluded":{"description":"Filter for hotels with parking included in rate","type":"boolean"},"features":{"maxItems":50,"description":"Filter by feature slugs (e.g. free_wifi, pool_outdoor). Values must exist in features.json. Max 50.","type":"array","items":{"minLength":1,"maxLength":80,"type":"string"}},"preferFeatures":{"maxItems":20,"description":"Feature slugs for soft-boost scoring. Hotels matching more features rank higher, but those with fewer still appear. Max 20.","type":"array","items":{"minLength":1,"maxLength":80,"type":"string"}},"filterMode":{"description":"Filter mode for amenity/boolean filters. 'strict' (default): hard AND — only hotels matching ALL filters. 'prefer': soft boost — amenity filters become scoring signals; hotels matching more rank higher, but results never disappear.","default":"strict","anyOf":[{"const":"strict","type":"string"},{"const":"prefer","type":"string"}]},"poiTypesNearby":{"maxItems":30,"description":"Filter by nearby POI types (e.g., ['restaurant', 'beach']). Max 30 values.","type":"array","items":{"minLength":1,"maxLength":100,"type":"string"}},"poiNamesNearby":{"maxItems":30,"description":"Filter by specific nearby POI names (e.g., ['Burj Khalifa', 'Dubai Mall']). Max 30 values.","type":"array","items":{"minLength":1,"maxLength":200,"type":"string"}},"excludeClosed":{"description":"Exclude closed hotels (default: true)","default":true,"type":"boolean"},"providerHid":{"minimum":0,"description":"Filter by provider HID (non-negative integer)","type":"number"},"providerId":{"minLength":1,"maxLength":100,"description":"Filter by provider ID (string)","type":"string"},"sortBy":{"description":"Sort field: relevance, star_rating, name, distance, updated_at","default":"relevance","anyOf":[{"const":"relevance","type":"string"},{"const":"star_rating","type":"string"},{"const":"name","type":"string"},{"const":"distance","type":"string"},{"const":"updated_at","type":"string"}]},"sortOrder":{"description":"Sort order: asc or desc","default":"desc","anyOf":[{"const":"asc","type":"string"},{"const":"desc","type":"string"}]},"includeAggregations":{"description":"Include aggregations/facets in response","default":false,"type":"boolean"},"boostByQuality":{"description":"Enable quality-based re-ranking. Boosts results by rating_global and star_rating. Useful for ranking by hotel quality while maintaining relevance.","default":false,"type":"boolean"},"qualityRatingWeight":{"minimum":0,"maximum":1,"description":"Weight for guest rating (rating_global) in quality scoring (0-1). Default: 0.7. Higher values prioritize guest ratings over star ratings.","default":0.7,"type":"number"},"qualityStarsWeight":{"minimum":0,"maximum":1,"description":"Weight for star rating in quality scoring (0-1). Default: 0.3. Higher values prioritize hotel stars over guest ratings.","default":0.3,"type":"number"},"checkIn":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Check-in date (YYYY-MM-DD). Required for real-time pricing.","examples":["2026-03-01"],"type":"string"},"checkOut":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Check-out date (YYYY-MM-DD). Required for real-time pricing.","examples":["2026-03-05"],"type":"string"},"adults":{"minimum":1,"maximum":10,"default":2,"description":"Number of adults (1-10)","type":"number"},"children":{"minimum":0,"maximum":4,"default":0,"description":"Number of children (0-4)","type":"number"},"childAges":{"description":"Ages of children (0-17 each). Array length should match 'children' count.","examples":[[5,10]],"type":"array","items":{"minimum":0,"maximum":17,"type":"number"}},"rooms":{"minimum":1,"maximum":5,"default":1,"description":"Number of rooms (1-5)","type":"number"},"currency":{"minLength":3,"maxLength":3,"pattern":"^[A-Z]{3}$","default":"AED","description":"Currency code for prices (ISO 4217, 3 letters)","examples":["AED","USD","EUR"],"type":"string"}},"additionalProperties":false}},"multipart/form-data":{"schema":{"type":"object","properties":{"q":{"minLength":0,"maxLength":500,"description":"Search query text (e.g., 'luxury hotels dubai', 'beachfront resort')","examples":["luxury hotels dubai","family friendly resort"],"type":"string"},"query":{"minLength":0,"maxLength":500,"description":"Alias for 'q' parameter","type":"string"},"strategy":{"description":"Search strategy: 'text' (BM25), 'hybrid' (text+vector), 'vector' (semantic). Omit to use route default.","anyOf":[{"const":"hybrid","type":"string"},{"const":"text","type":"string"},{"const":"vector","type":"string"}]},"requestId":{"description":"Request ID from previous search. Use with page > 1 to fetch cached results.","type":"string"},"page":{"minimum":1,"default":1,"description":"Page number. Use with requestId for subsequent pages.","type":"number"},"fetchSize":{"minimum":50,"maximum":300,"default":100,"description":"Number of hotels to fetch and cache (50-300). Higher = more pages cached.","type":"number"},"limit":{"minimum":1,"maximum":100,"default":20,"description":"Results per page (default: 20, ignored when using requestId)","type":"number"},"size":{"minimum":1,"maximum":100,"description":"Alias for 'limit'","type":"number"},"offset":{"minimum":0,"default":0,"description":"Deprecated: Use page instead","type":"number"},"lat":{"minimum":-90,"maximum":90,"description":"Latitude for geo-search (requires lng)","examples":[25.2048],"type":"number"},"lng":{"minimum":-180,"maximum":180,"description":"Longitude for geo-search (requires lat)","examples":[55.2708],"type":"number"},"radius":{"minimum":1,"maximum":500000,"description":"Search radius in meters (1-500000, default: 50000)","default":50000,"examples":[1000,10000,50000],"type":"number"},"city":{"minLength":1,"maxLength":200,"description":"Filter by city name","examples":["Dubai","Abu Dhabi"],"type":"string"},"country":{"minLength":2,"maxLength":2,"pattern":"^[A-Za-z]{2}$","description":"Filter by country code (ISO 3166-1 alpha-2). Must be a country code present in the index (e.g. AE, US, SA).","examples":["AE","SA","US"],"type":"string"},"regionId":{"minimum":0,"description":"Filter by region ID (non-negative integer)","type":"number"},"stars":{"minimum":1,"maximum":5,"description":"Minimum star rating (1-5)","type":"number"},"starRating":{"description":"Star rating filter - single number (1-5) or array of up to 10 values. Matches index values.","examples":[[4,5]],"anyOf":[{"minimum":1,"maximum":5,"type":"number"},{"maxItems":10,"type":"array","items":{"minimum":1,"maximum":5,"type":"number"}}]},"minStarRating":{"minimum":1,"maximum":5,"description":"Minimum star rating for range filter","type":"number"},"maxStarRating":{"minimum":1,"maximum":5,"description":"Maximum star rating for range filter","type":"number"},"kind":{"maxItems":20,"description":"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.","examples":[["HOTEL","RESORT"]],"type":"array","items":{"minLength":1,"maxLength":100,"type":"string"}},"hotelChain":{"maxItems":20,"description":"Hotel chain names (e.g., ['Marriott', 'Hilton']). Max 20 values.","type":"array","items":{"minLength":1,"maxLength":150,"type":"string"}},"familyFriendly":{"description":"Filter for family-friendly hotels (only set to true to filter)","type":"boolean"},"petFriendly":{"description":"Filter for pet-friendly hotels (only set to true to filter)","type":"boolean"},"businessFriendly":{"description":"Filter for business-friendly hotels (only set to true to filter)","type":"boolean"},"wellnessSpa":{"description":"Filter for hotels with spa/wellness facilities (only set to true to filter)","type":"boolean"},"beachfront":{"description":"Filter for beachfront properties (only set to true to filter)","type":"boolean"},"freeWifi":{"description":"Filter for hotels with free WiFi","type":"boolean"},"breakfastIncluded":{"description":"Filter for hotels with breakfast included","type":"boolean"},"petsAllowed":{"description":"Filter for hotels that allow pets","type":"boolean"},"parkingAvailable":{"description":"Filter for hotels with parking available","type":"boolean"},"freeParking":{"description":"Filter for hotels with free parking","type":"boolean"},"shuttleAvailable":{"description":"Filter for hotels with airport shuttle","type":"boolean"},"childrenAllowed":{"description":"Filter for hotels that allow children","type":"boolean"},"internetIncluded":{"description":"Filter for hotels with internet included","type":"boolean"},"parkingIncluded":{"description":"Filter for hotels with parking included in rate","type":"boolean"},"features":{"maxItems":50,"description":"Filter by feature slugs (e.g. free_wifi, pool_outdoor). Values must exist in features.json. Max 50.","type":"array","items":{"minLength":1,"maxLength":80,"type":"string"}},"preferFeatures":{"maxItems":20,"description":"Feature slugs for soft-boost scoring. Hotels matching more features rank higher, but those with fewer still appear. Max 20.","type":"array","items":{"minLength":1,"maxLength":80,"type":"string"}},"filterMode":{"description":"Filter mode for amenity/boolean filters. 'strict' (default): hard AND — only hotels matching ALL filters. 'prefer': soft boost — amenity filters become scoring signals; hotels matching more rank higher, but results never disappear.","default":"strict","anyOf":[{"const":"strict","type":"string"},{"const":"prefer","type":"string"}]},"poiTypesNearby":{"maxItems":30,"description":"Filter by nearby POI types (e.g., ['restaurant', 'beach']). Max 30 values.","type":"array","items":{"minLength":1,"maxLength":100,"type":"string"}},"poiNamesNearby":{"maxItems":30,"description":"Filter by specific nearby POI names (e.g., ['Burj Khalifa', 'Dubai Mall']). Max 30 values.","type":"array","items":{"minLength":1,"maxLength":200,"type":"string"}},"excludeClosed":{"description":"Exclude closed hotels (default: true)","default":true,"type":"boolean"},"providerHid":{"minimum":0,"description":"Filter by provider HID (non-negative integer)","type":"number"},"providerId":{"minLength":1,"maxLength":100,"description":"Filter by provider ID (string)","type":"string"},"sortBy":{"description":"Sort field: relevance, star_rating, name, distance, updated_at","default":"relevance","anyOf":[{"const":"relevance","type":"string"},{"const":"star_rating","type":"string"},{"const":"name","type":"string"},{"const":"distance","type":"string"},{"const":"updated_at","type":"string"}]},"sortOrder":{"description":"Sort order: asc or desc","default":"desc","anyOf":[{"const":"asc","type":"string"},{"const":"desc","type":"string"}]},"includeAggregations":{"description":"Include aggregations/facets in response","default":false,"type":"boolean"},"boostByQuality":{"description":"Enable quality-based re-ranking. Boosts results by rating_global and star_rating. Useful for ranking by hotel quality while maintaining relevance.","default":false,"type":"boolean"},"qualityRatingWeight":{"minimum":0,"maximum":1,"description":"Weight for guest rating (rating_global) in quality scoring (0-1). Default: 0.7. Higher values prioritize guest ratings over star ratings.","default":0.7,"type":"number"},"qualityStarsWeight":{"minimum":0,"maximum":1,"description":"Weight for star rating in quality scoring (0-1). Default: 0.3. Higher values prioritize hotel stars over guest ratings.","default":0.3,"type":"number"},"checkIn":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Check-in date (YYYY-MM-DD). Required for real-time pricing.","examples":["2026-03-01"],"type":"string"},"checkOut":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Check-out date (YYYY-MM-DD). Required for real-time pricing.","examples":["2026-03-05"],"type":"string"},"adults":{"minimum":1,"maximum":10,"default":2,"description":"Number of adults (1-10)","type":"number"},"children":{"minimum":0,"maximum":4,"default":0,"description":"Number of children (0-4)","type":"number"},"childAges":{"description":"Ages of children (0-17 each). Array length should match 'children' count.","examples":[[5,10]],"type":"array","items":{"minimum":0,"maximum":17,"type":"number"}},"rooms":{"minimum":1,"maximum":5,"default":1,"description":"Number of rooms (1-5)","type":"number"},"currency":{"minLength":3,"maxLength":3,"pattern":"^[A-Z]{3}$","default":"AED","description":"Currency code for prices (ISO 4217, 3 letters)","examples":["AED","USD","EUR"],"type":"string"}},"additionalProperties":false}},"text/plain":{"schema":{"type":"object","properties":{"q":{"minLength":0,"maxLength":500,"description":"Search query text (e.g., 'luxury hotels dubai', 'beachfront resort')","examples":["luxury hotels dubai","family friendly resort"],"type":"string"},"query":{"minLength":0,"maxLength":500,"description":"Alias for 'q' parameter","type":"string"},"strategy":{"description":"Search strategy: 'text' (BM25), 'hybrid' (text+vector), 'vector' (semantic). Omit to use route default.","anyOf":[{"const":"hybrid","type":"string"},{"const":"text","type":"string"},{"const":"vector","type":"string"}]},"requestId":{"description":"Request ID from previous search. Use with page > 1 to fetch cached results.","type":"string"},"page":{"minimum":1,"default":1,"description":"Page number. Use with requestId for subsequent pages.","type":"number"},"fetchSize":{"minimum":50,"maximum":300,"default":100,"description":"Number of hotels to fetch and cache (50-300). Higher = more pages cached.","type":"number"},"limit":{"minimum":1,"maximum":100,"default":20,"description":"Results per page (default: 20, ignored when using requestId)","type":"number"},"size":{"minimum":1,"maximum":100,"description":"Alias for 'limit'","type":"number"},"offset":{"minimum":0,"default":0,"description":"Deprecated: Use page instead","type":"number"},"lat":{"minimum":-90,"maximum":90,"description":"Latitude for geo-search (requires lng)","examples":[25.2048],"type":"number"},"lng":{"minimum":-180,"maximum":180,"description":"Longitude for geo-search (requires lat)","examples":[55.2708],"type":"number"},"radius":{"minimum":1,"maximum":500000,"description":"Search radius in meters (1-500000, default: 50000)","default":50000,"examples":[1000,10000,50000],"type":"number"},"city":{"minLength":1,"maxLength":200,"description":"Filter by city name","examples":["Dubai","Abu Dhabi"],"type":"string"},"country":{"minLength":2,"maxLength":2,"pattern":"^[A-Za-z]{2}$","description":"Filter by country code (ISO 3166-1 alpha-2). Must be a country code present in the index (e.g. AE, US, SA).","examples":["AE","SA","US"],"type":"string"},"regionId":{"minimum":0,"description":"Filter by region ID (non-negative integer)","type":"number"},"stars":{"minimum":1,"maximum":5,"description":"Minimum star rating (1-5)","type":"number"},"starRating":{"description":"Star rating filter - single number (1-5) or array of up to 10 values. Matches index values.","examples":[[4,5]],"anyOf":[{"minimum":1,"maximum":5,"type":"number"},{"maxItems":10,"type":"array","items":{"minimum":1,"maximum":5,"type":"number"}}]},"minStarRating":{"minimum":1,"maximum":5,"description":"Minimum star rating for range filter","type":"number"},"maxStarRating":{"minimum":1,"maximum":5,"description":"Maximum star rating for range filter","type":"number"},"kind":{"maxItems":20,"description":"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.","examples":[["HOTEL","RESORT"]],"type":"array","items":{"minLength":1,"maxLength":100,"type":"string"}},"hotelChain":{"maxItems":20,"description":"Hotel chain names (e.g., ['Marriott', 'Hilton']). Max 20 values.","type":"array","items":{"minLength":1,"maxLength":150,"type":"string"}},"familyFriendly":{"description":"Filter for family-friendly hotels (only set to true to filter)","type":"boolean"},"petFriendly":{"description":"Filter for pet-friendly hotels (only set to true to filter)","type":"boolean"},"businessFriendly":{"description":"Filter for business-friendly hotels (only set to true to filter)","type":"boolean"},"wellnessSpa":{"description":"Filter for hotels with spa/wellness facilities (only set to true to filter)","type":"boolean"},"beachfront":{"description":"Filter for beachfront properties (only set to true to filter)","type":"boolean"},"freeWifi":{"description":"Filter for hotels with free WiFi","type":"boolean"},"breakfastIncluded":{"description":"Filter for hotels with breakfast included","type":"boolean"},"petsAllowed":{"description":"Filter for hotels that allow pets","type":"boolean"},"parkingAvailable":{"description":"Filter for hotels with parking available","type":"boolean"},"freeParking":{"description":"Filter for hotels with free parking","type":"boolean"},"shuttleAvailable":{"description":"Filter for hotels with airport shuttle","type":"boolean"},"childrenAllowed":{"description":"Filter for hotels that allow children","type":"boolean"},"internetIncluded":{"description":"Filter for hotels with internet included","type":"boolean"},"parkingIncluded":{"description":"Filter for hotels with parking included in rate","type":"boolean"},"features":{"maxItems":50,"description":"Filter by feature slugs (e.g. free_wifi, pool_outdoor). Values must exist in features.json. Max 50.","type":"array","items":{"minLength":1,"maxLength":80,"type":"string"}},"preferFeatures":{"maxItems":20,"description":"Feature slugs for soft-boost scoring. Hotels matching more features rank higher, but those with fewer still appear. Max 20.","type":"array","items":{"minLength":1,"maxLength":80,"type":"string"}},"filterMode":{"description":"Filter mode for amenity/boolean filters. 'strict' (default): hard AND — only hotels matching ALL filters. 'prefer': soft boost — amenity filters become scoring signals; hotels matching more rank higher, but results never disappear.","default":"strict","anyOf":[{"const":"strict","type":"string"},{"const":"prefer","type":"string"}]},"poiTypesNearby":{"maxItems":30,"description":"Filter by nearby POI types (e.g., ['restaurant', 'beach']). Max 30 values.","type":"array","items":{"minLength":1,"maxLength":100,"type":"string"}},"poiNamesNearby":{"maxItems":30,"description":"Filter by specific nearby POI names (e.g., ['Burj Khalifa', 'Dubai Mall']). Max 30 values.","type":"array","items":{"minLength":1,"maxLength":200,"type":"string"}},"excludeClosed":{"description":"Exclude closed hotels (default: true)","default":true,"type":"boolean"},"providerHid":{"minimum":0,"description":"Filter by provider HID (non-negative integer)","type":"number"},"providerId":{"minLength":1,"maxLength":100,"description":"Filter by provider ID (string)","type":"string"},"sortBy":{"description":"Sort field: relevance, star_rating, name, distance, updated_at","default":"relevance","anyOf":[{"const":"relevance","type":"string"},{"const":"star_rating","type":"string"},{"const":"name","type":"string"},{"const":"distance","type":"string"},{"const":"updated_at","type":"string"}]},"sortOrder":{"description":"Sort order: asc or desc","default":"desc","anyOf":[{"const":"asc","type":"string"},{"const":"desc","type":"string"}]},"includeAggregations":{"description":"Include aggregations/facets in response","default":false,"type":"boolean"},"boostByQuality":{"description":"Enable quality-based re-ranking. Boosts results by rating_global and star_rating. Useful for ranking by hotel quality while maintaining relevance.","default":false,"type":"boolean"},"qualityRatingWeight":{"minimum":0,"maximum":1,"description":"Weight for guest rating (rating_global) in quality scoring (0-1). Default: 0.7. Higher values prioritize guest ratings over star ratings.","default":0.7,"type":"number"},"qualityStarsWeight":{"minimum":0,"maximum":1,"description":"Weight for star rating in quality scoring (0-1). Default: 0.3. Higher values prioritize hotel stars over guest ratings.","default":0.3,"type":"number"},"checkIn":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Check-in date (YYYY-MM-DD). Required for real-time pricing.","examples":["2026-03-01"],"type":"string"},"checkOut":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Check-out date (YYYY-MM-DD). Required for real-time pricing.","examples":["2026-03-05"],"type":"string"},"adults":{"minimum":1,"maximum":10,"default":2,"description":"Number of adults (1-10)","type":"number"},"children":{"minimum":0,"maximum":4,"default":0,"description":"Number of children (0-4)","type":"number"},"childAges":{"description":"Ages of children (0-17 each). Array length should match 'children' count.","examples":[[5,10]],"type":"array","items":{"minimum":0,"maximum":17,"type":"number"}},"rooms":{"minimum":1,"maximum":5,"default":1,"description":"Number of rooms (1-5)","type":"number"},"currency":{"minLength":3,"maxLength":3,"pattern":"^[A-Z]{3}$","default":"AED","description":"Currency code for prices (ISO 4217, 3 letters)","examples":["AED","USD","EUR"],"type":"string"}},"additionalProperties":false}}}}}},"/v2/search/hybrid":{"post":{"parameters":[],"responses":{"200":{"description":"Search response with hotels and pagination support","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"description":"Whether the search was successful","type":"boolean"},"data":{"description":"Array of hotel results (20 per page)","type":"array","items":{}},"error":{"description":"Error message if search failed","type":"string"},"requestId":{"description":"Request ID for pagination. Use with page parameter for next pages.","type":"string"},"metadata":{"type":"object","properties":{"total":{"description":"Total number of matching hotels","type":"number"},"page":{"description":"Current page number","type":"number"},"limit":{"description":"Results per page (20)","type":"number"},"totalPages":{"description":"Total number of pages available","type":"number"},"hasMore":{"description":"Whether more results are available","type":"boolean"},"cached":{"description":"Whether results came from cache","type":"boolean"},"filters":{"description":"Applied filters"},"executionTime":{"description":"Search execution time in ms","type":"number"},"strategy":{"description":"Search strategy used","type":"string"}},"required":["total","page","limit","totalPages","filters","executionTime","strategy"]},"searchMetadata":{"type":"object","properties":{"query":{"type":"string"},"mode":{"type":"string"},"opensearchTook":{"type":"number"},"embeddingMs":{"description":"Time in ms spent generating query embedding (vector/hybrid)","type":"number"},"fetchedCount":{"description":"Total hotels fetched and cached","type":"number"}}}},"required":["success","data","metadata"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"success":{"description":"Whether the search was successful","type":"boolean"},"data":{"description":"Array of hotel results (20 per page)","type":"array","items":{}},"error":{"description":"Error message if search failed","type":"string"},"requestId":{"description":"Request ID for pagination. Use with page parameter for next pages.","type":"string"},"metadata":{"type":"object","properties":{"total":{"description":"Total number of matching hotels","type":"number"},"page":{"description":"Current page number","type":"number"},"limit":{"description":"Results per page (20)","type":"number"},"totalPages":{"description":"Total number of pages available","type":"number"},"hasMore":{"description":"Whether more results are available","type":"boolean"},"cached":{"description":"Whether results came from cache","type":"boolean"},"filters":{"description":"Applied filters"},"executionTime":{"description":"Search execution time in ms","type":"number"},"strategy":{"description":"Search strategy used","type":"string"}},"required":["total","page","limit","totalPages","filters","executionTime","strategy"]},"searchMetadata":{"type":"object","properties":{"query":{"type":"string"},"mode":{"type":"string"},"opensearchTook":{"type":"number"},"embeddingMs":{"description":"Time in ms spent generating query embedding (vector/hybrid)","type":"number"},"fetchedCount":{"description":"Total hotels fetched and cached","type":"number"}}}},"required":["success","data","metadata"]}},"text/plain":{"schema":{"type":"object","properties":{"success":{"description":"Whether the search was successful","type":"boolean"},"data":{"description":"Array of hotel results (20 per page)","type":"array","items":{}},"error":{"description":"Error message if search failed","type":"string"},"requestId":{"description":"Request ID for pagination. Use with page parameter for next pages.","type":"string"},"metadata":{"type":"object","properties":{"total":{"description":"Total number of matching hotels","type":"number"},"page":{"description":"Current page number","type":"number"},"limit":{"description":"Results per page (20)","type":"number"},"totalPages":{"description":"Total number of pages available","type":"number"},"hasMore":{"description":"Whether more results are available","type":"boolean"},"cached":{"description":"Whether results came from cache","type":"boolean"},"filters":{"description":"Applied filters"},"executionTime":{"description":"Search execution time in ms","type":"number"},"strategy":{"description":"Search strategy used","type":"string"}},"required":["total","page","limit","totalPages","filters","executionTime","strategy"]},"searchMetadata":{"type":"object","properties":{"query":{"type":"string"},"mode":{"type":"string"},"opensearchTook":{"type":"number"},"embeddingMs":{"description":"Time in ms spent generating query embedding (vector/hybrid)","type":"number"},"fetchedCount":{"description":"Total hotels fetched and cached","type":"number"}}}},"required":["success","data","metadata"]}}}}},"operationId":"postV2SearchHybrid","tags":["V2 Search"],"summary":"Hybrid Search","description":"\nSearch using **hybrid mode** - combines BM25 text matching with vector semantic similarity.\n\n**Best For:**\n- General search queries\n- When you want both exact matches and semantic understanding\n- Queries like \"family friendly beach hotel\" or \"romantic getaway dubai\"\n\n**How it Works:**\n1. Text search finds keyword matches (BM25)\n2. Vector search finds semantically similar results\n3. Results are merged using Reciprocal Rank Fusion (RRF)\n\n### Request Body Example\n```json\n{\n  \"q\": \"family friendly beach hotel\",\n  \"city\": \"Dubai\",\n  \"familyFriendly\": true,\n  \"limit\": 20\n}\n```\n        ","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"q":{"minLength":0,"maxLength":500,"description":"Search query text (e.g., 'luxury hotels dubai', 'beachfront resort')","examples":["luxury hotels dubai","family friendly resort"],"type":"string"},"query":{"minLength":0,"maxLength":500,"description":"Alias for 'q' parameter","type":"string"},"strategy":{"description":"Search strategy: 'text' (BM25), 'hybrid' (text+vector), 'vector' (semantic). Omit to use route default.","anyOf":[{"const":"hybrid","type":"string"},{"const":"text","type":"string"},{"const":"vector","type":"string"}]},"requestId":{"description":"Request ID from previous search. Use with page > 1 to fetch cached results.","type":"string"},"page":{"minimum":1,"default":1,"description":"Page number. Use with requestId for subsequent pages.","type":"number"},"fetchSize":{"minimum":50,"maximum":300,"default":100,"description":"Number of hotels to fetch and cache (50-300). Higher = more pages cached.","type":"number"},"limit":{"minimum":1,"maximum":100,"default":20,"description":"Results per page (default: 20, ignored when using requestId)","type":"number"},"size":{"minimum":1,"maximum":100,"description":"Alias for 'limit'","type":"number"},"offset":{"minimum":0,"default":0,"description":"Deprecated: Use page instead","type":"number"},"lat":{"minimum":-90,"maximum":90,"description":"Latitude for geo-search (requires lng)","examples":[25.2048],"type":"number"},"lng":{"minimum":-180,"maximum":180,"description":"Longitude for geo-search (requires lat)","examples":[55.2708],"type":"number"},"radius":{"minimum":1,"maximum":500000,"description":"Search radius in meters (1-500000, default: 50000)","default":50000,"examples":[1000,10000,50000],"type":"number"},"city":{"minLength":1,"maxLength":200,"description":"Filter by city name","examples":["Dubai","Abu Dhabi"],"type":"string"},"country":{"minLength":2,"maxLength":2,"pattern":"^[A-Za-z]{2}$","description":"Filter by country code (ISO 3166-1 alpha-2). Must be a country code present in the index (e.g. AE, US, SA).","examples":["AE","SA","US"],"type":"string"},"regionId":{"minimum":0,"description":"Filter by region ID (non-negative integer)","type":"number"},"stars":{"minimum":1,"maximum":5,"description":"Minimum star rating (1-5)","type":"number"},"starRating":{"description":"Star rating filter - single number (1-5) or array of up to 10 values. Matches index values.","examples":[[4,5]],"anyOf":[{"minimum":1,"maximum":5,"type":"number"},{"maxItems":10,"type":"array","items":{"minimum":1,"maximum":5,"type":"number"}}]},"minStarRating":{"minimum":1,"maximum":5,"description":"Minimum star rating for range filter","type":"number"},"maxStarRating":{"minimum":1,"maximum":5,"description":"Maximum star rating for range filter","type":"number"},"kind":{"maxItems":20,"description":"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.","examples":[["HOTEL","RESORT"]],"type":"array","items":{"minLength":1,"maxLength":100,"type":"string"}},"hotelChain":{"maxItems":20,"description":"Hotel chain names (e.g., ['Marriott', 'Hilton']). Max 20 values.","type":"array","items":{"minLength":1,"maxLength":150,"type":"string"}},"familyFriendly":{"description":"Filter for family-friendly hotels (only set to true to filter)","type":"boolean"},"petFriendly":{"description":"Filter for pet-friendly hotels (only set to true to filter)","type":"boolean"},"businessFriendly":{"description":"Filter for business-friendly hotels (only set to true to filter)","type":"boolean"},"wellnessSpa":{"description":"Filter for hotels with spa/wellness facilities (only set to true to filter)","type":"boolean"},"beachfront":{"description":"Filter for beachfront properties (only set to true to filter)","type":"boolean"},"freeWifi":{"description":"Filter for hotels with free WiFi","type":"boolean"},"breakfastIncluded":{"description":"Filter for hotels with breakfast included","type":"boolean"},"petsAllowed":{"description":"Filter for hotels that allow pets","type":"boolean"},"parkingAvailable":{"description":"Filter for hotels with parking available","type":"boolean"},"freeParking":{"description":"Filter for hotels with free parking","type":"boolean"},"shuttleAvailable":{"description":"Filter for hotels with airport shuttle","type":"boolean"},"childrenAllowed":{"description":"Filter for hotels that allow children","type":"boolean"},"internetIncluded":{"description":"Filter for hotels with internet included","type":"boolean"},"parkingIncluded":{"description":"Filter for hotels with parking included in rate","type":"boolean"},"features":{"maxItems":50,"description":"Filter by feature slugs (e.g. free_wifi, pool_outdoor). Values must exist in features.json. Max 50.","type":"array","items":{"minLength":1,"maxLength":80,"type":"string"}},"preferFeatures":{"maxItems":20,"description":"Feature slugs for soft-boost scoring. Hotels matching more features rank higher, but those with fewer still appear. Max 20.","type":"array","items":{"minLength":1,"maxLength":80,"type":"string"}},"filterMode":{"description":"Filter mode for amenity/boolean filters. 'strict' (default): hard AND — only hotels matching ALL filters. 'prefer': soft boost — amenity filters become scoring signals; hotels matching more rank higher, but results never disappear.","default":"strict","anyOf":[{"const":"strict","type":"string"},{"const":"prefer","type":"string"}]},"poiTypesNearby":{"maxItems":30,"description":"Filter by nearby POI types (e.g., ['restaurant', 'beach']). Max 30 values.","type":"array","items":{"minLength":1,"maxLength":100,"type":"string"}},"poiNamesNearby":{"maxItems":30,"description":"Filter by specific nearby POI names (e.g., ['Burj Khalifa', 'Dubai Mall']). Max 30 values.","type":"array","items":{"minLength":1,"maxLength":200,"type":"string"}},"excludeClosed":{"description":"Exclude closed hotels (default: true)","default":true,"type":"boolean"},"providerHid":{"minimum":0,"description":"Filter by provider HID (non-negative integer)","type":"number"},"providerId":{"minLength":1,"maxLength":100,"description":"Filter by provider ID (string)","type":"string"},"sortBy":{"description":"Sort field: relevance, star_rating, name, distance, updated_at","default":"relevance","anyOf":[{"const":"relevance","type":"string"},{"const":"star_rating","type":"string"},{"const":"name","type":"string"},{"const":"distance","type":"string"},{"const":"updated_at","type":"string"}]},"sortOrder":{"description":"Sort order: asc or desc","default":"desc","anyOf":[{"const":"asc","type":"string"},{"const":"desc","type":"string"}]},"includeAggregations":{"description":"Include aggregations/facets in response","default":false,"type":"boolean"},"boostByQuality":{"description":"Enable quality-based re-ranking. Boosts results by rating_global and star_rating. Useful for ranking by hotel quality while maintaining relevance.","default":false,"type":"boolean"},"qualityRatingWeight":{"minimum":0,"maximum":1,"description":"Weight for guest rating (rating_global) in quality scoring (0-1). Default: 0.7. Higher values prioritize guest ratings over star ratings.","default":0.7,"type":"number"},"qualityStarsWeight":{"minimum":0,"maximum":1,"description":"Weight for star rating in quality scoring (0-1). Default: 0.3. Higher values prioritize hotel stars over guest ratings.","default":0.3,"type":"number"},"checkIn":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Check-in date (YYYY-MM-DD). Required for real-time pricing.","examples":["2026-03-01"],"type":"string"},"checkOut":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Check-out date (YYYY-MM-DD). Required for real-time pricing.","examples":["2026-03-05"],"type":"string"},"adults":{"minimum":1,"maximum":10,"default":2,"description":"Number of adults (1-10)","type":"number"},"children":{"minimum":0,"maximum":4,"default":0,"description":"Number of children (0-4)","type":"number"},"childAges":{"description":"Ages of children (0-17 each). Array length should match 'children' count.","examples":[[5,10]],"type":"array","items":{"minimum":0,"maximum":17,"type":"number"}},"rooms":{"minimum":1,"maximum":5,"default":1,"description":"Number of rooms (1-5)","type":"number"},"currency":{"minLength":3,"maxLength":3,"pattern":"^[A-Z]{3}$","default":"AED","description":"Currency code for prices (ISO 4217, 3 letters)","examples":["AED","USD","EUR"],"type":"string"}},"additionalProperties":false}},"multipart/form-data":{"schema":{"type":"object","properties":{"q":{"minLength":0,"maxLength":500,"description":"Search query text (e.g., 'luxury hotels dubai', 'beachfront resort')","examples":["luxury hotels dubai","family friendly resort"],"type":"string"},"query":{"minLength":0,"maxLength":500,"description":"Alias for 'q' parameter","type":"string"},"strategy":{"description":"Search strategy: 'text' (BM25), 'hybrid' (text+vector), 'vector' (semantic). Omit to use route default.","anyOf":[{"const":"hybrid","type":"string"},{"const":"text","type":"string"},{"const":"vector","type":"string"}]},"requestId":{"description":"Request ID from previous search. Use with page > 1 to fetch cached results.","type":"string"},"page":{"minimum":1,"default":1,"description":"Page number. Use with requestId for subsequent pages.","type":"number"},"fetchSize":{"minimum":50,"maximum":300,"default":100,"description":"Number of hotels to fetch and cache (50-300). Higher = more pages cached.","type":"number"},"limit":{"minimum":1,"maximum":100,"default":20,"description":"Results per page (default: 20, ignored when using requestId)","type":"number"},"size":{"minimum":1,"maximum":100,"description":"Alias for 'limit'","type":"number"},"offset":{"minimum":0,"default":0,"description":"Deprecated: Use page instead","type":"number"},"lat":{"minimum":-90,"maximum":90,"description":"Latitude for geo-search (requires lng)","examples":[25.2048],"type":"number"},"lng":{"minimum":-180,"maximum":180,"description":"Longitude for geo-search (requires lat)","examples":[55.2708],"type":"number"},"radius":{"minimum":1,"maximum":500000,"description":"Search radius in meters (1-500000, default: 50000)","default":50000,"examples":[1000,10000,50000],"type":"number"},"city":{"minLength":1,"maxLength":200,"description":"Filter by city name","examples":["Dubai","Abu Dhabi"],"type":"string"},"country":{"minLength":2,"maxLength":2,"pattern":"^[A-Za-z]{2}$","description":"Filter by country code (ISO 3166-1 alpha-2). Must be a country code present in the index (e.g. AE, US, SA).","examples":["AE","SA","US"],"type":"string"},"regionId":{"minimum":0,"description":"Filter by region ID (non-negative integer)","type":"number"},"stars":{"minimum":1,"maximum":5,"description":"Minimum star rating (1-5)","type":"number"},"starRating":{"description":"Star rating filter - single number (1-5) or array of up to 10 values. Matches index values.","examples":[[4,5]],"anyOf":[{"minimum":1,"maximum":5,"type":"number"},{"maxItems":10,"type":"array","items":{"minimum":1,"maximum":5,"type":"number"}}]},"minStarRating":{"minimum":1,"maximum":5,"description":"Minimum star rating for range filter","type":"number"},"maxStarRating":{"minimum":1,"maximum":5,"description":"Maximum star rating for range filter","type":"number"},"kind":{"maxItems":20,"description":"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.","examples":[["HOTEL","RESORT"]],"type":"array","items":{"minLength":1,"maxLength":100,"type":"string"}},"hotelChain":{"maxItems":20,"description":"Hotel chain names (e.g., ['Marriott', 'Hilton']). Max 20 values.","type":"array","items":{"minLength":1,"maxLength":150,"type":"string"}},"familyFriendly":{"description":"Filter for family-friendly hotels (only set to true to filter)","type":"boolean"},"petFriendly":{"description":"Filter for pet-friendly hotels (only set to true to filter)","type":"boolean"},"businessFriendly":{"description":"Filter for business-friendly hotels (only set to true to filter)","type":"boolean"},"wellnessSpa":{"description":"Filter for hotels with spa/wellness facilities (only set to true to filter)","type":"boolean"},"beachfront":{"description":"Filter for beachfront properties (only set to true to filter)","type":"boolean"},"freeWifi":{"description":"Filter for hotels with free WiFi","type":"boolean"},"breakfastIncluded":{"description":"Filter for hotels with breakfast included","type":"boolean"},"petsAllowed":{"description":"Filter for hotels that allow pets","type":"boolean"},"parkingAvailable":{"description":"Filter for hotels with parking available","type":"boolean"},"freeParking":{"description":"Filter for hotels with free parking","type":"boolean"},"shuttleAvailable":{"description":"Filter for hotels with airport shuttle","type":"boolean"},"childrenAllowed":{"description":"Filter for hotels that allow children","type":"boolean"},"internetIncluded":{"description":"Filter for hotels with internet included","type":"boolean"},"parkingIncluded":{"description":"Filter for hotels with parking included in rate","type":"boolean"},"features":{"maxItems":50,"description":"Filter by feature slugs (e.g. free_wifi, pool_outdoor). Values must exist in features.json. Max 50.","type":"array","items":{"minLength":1,"maxLength":80,"type":"string"}},"preferFeatures":{"maxItems":20,"description":"Feature slugs for soft-boost scoring. Hotels matching more features rank higher, but those with fewer still appear. Max 20.","type":"array","items":{"minLength":1,"maxLength":80,"type":"string"}},"filterMode":{"description":"Filter mode for amenity/boolean filters. 'strict' (default): hard AND — only hotels matching ALL filters. 'prefer': soft boost — amenity filters become scoring signals; hotels matching more rank higher, but results never disappear.","default":"strict","anyOf":[{"const":"strict","type":"string"},{"const":"prefer","type":"string"}]},"poiTypesNearby":{"maxItems":30,"description":"Filter by nearby POI types (e.g., ['restaurant', 'beach']). Max 30 values.","type":"array","items":{"minLength":1,"maxLength":100,"type":"string"}},"poiNamesNearby":{"maxItems":30,"description":"Filter by specific nearby POI names (e.g., ['Burj Khalifa', 'Dubai Mall']). Max 30 values.","type":"array","items":{"minLength":1,"maxLength":200,"type":"string"}},"excludeClosed":{"description":"Exclude closed hotels (default: true)","default":true,"type":"boolean"},"providerHid":{"minimum":0,"description":"Filter by provider HID (non-negative integer)","type":"number"},"providerId":{"minLength":1,"maxLength":100,"description":"Filter by provider ID (string)","type":"string"},"sortBy":{"description":"Sort field: relevance, star_rating, name, distance, updated_at","default":"relevance","anyOf":[{"const":"relevance","type":"string"},{"const":"star_rating","type":"string"},{"const":"name","type":"string"},{"const":"distance","type":"string"},{"const":"updated_at","type":"string"}]},"sortOrder":{"description":"Sort order: asc or desc","default":"desc","anyOf":[{"const":"asc","type":"string"},{"const":"desc","type":"string"}]},"includeAggregations":{"description":"Include aggregations/facets in response","default":false,"type":"boolean"},"boostByQuality":{"description":"Enable quality-based re-ranking. Boosts results by rating_global and star_rating. Useful for ranking by hotel quality while maintaining relevance.","default":false,"type":"boolean"},"qualityRatingWeight":{"minimum":0,"maximum":1,"description":"Weight for guest rating (rating_global) in quality scoring (0-1). Default: 0.7. Higher values prioritize guest ratings over star ratings.","default":0.7,"type":"number"},"qualityStarsWeight":{"minimum":0,"maximum":1,"description":"Weight for star rating in quality scoring (0-1). Default: 0.3. Higher values prioritize hotel stars over guest ratings.","default":0.3,"type":"number"},"checkIn":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Check-in date (YYYY-MM-DD). Required for real-time pricing.","examples":["2026-03-01"],"type":"string"},"checkOut":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Check-out date (YYYY-MM-DD). Required for real-time pricing.","examples":["2026-03-05"],"type":"string"},"adults":{"minimum":1,"maximum":10,"default":2,"description":"Number of adults (1-10)","type":"number"},"children":{"minimum":0,"maximum":4,"default":0,"description":"Number of children (0-4)","type":"number"},"childAges":{"description":"Ages of children (0-17 each). Array length should match 'children' count.","examples":[[5,10]],"type":"array","items":{"minimum":0,"maximum":17,"type":"number"}},"rooms":{"minimum":1,"maximum":5,"default":1,"description":"Number of rooms (1-5)","type":"number"},"currency":{"minLength":3,"maxLength":3,"pattern":"^[A-Z]{3}$","default":"AED","description":"Currency code for prices (ISO 4217, 3 letters)","examples":["AED","USD","EUR"],"type":"string"}},"additionalProperties":false}},"text/plain":{"schema":{"type":"object","properties":{"q":{"minLength":0,"maxLength":500,"description":"Search query text (e.g., 'luxury hotels dubai', 'beachfront resort')","examples":["luxury hotels dubai","family friendly resort"],"type":"string"},"query":{"minLength":0,"maxLength":500,"description":"Alias for 'q' parameter","type":"string"},"strategy":{"description":"Search strategy: 'text' (BM25), 'hybrid' (text+vector), 'vector' (semantic). Omit to use route default.","anyOf":[{"const":"hybrid","type":"string"},{"const":"text","type":"string"},{"const":"vector","type":"string"}]},"requestId":{"description":"Request ID from previous search. Use with page > 1 to fetch cached results.","type":"string"},"page":{"minimum":1,"default":1,"description":"Page number. Use with requestId for subsequent pages.","type":"number"},"fetchSize":{"minimum":50,"maximum":300,"default":100,"description":"Number of hotels to fetch and cache (50-300). Higher = more pages cached.","type":"number"},"limit":{"minimum":1,"maximum":100,"default":20,"description":"Results per page (default: 20, ignored when using requestId)","type":"number"},"size":{"minimum":1,"maximum":100,"description":"Alias for 'limit'","type":"number"},"offset":{"minimum":0,"default":0,"description":"Deprecated: Use page instead","type":"number"},"lat":{"minimum":-90,"maximum":90,"description":"Latitude for geo-search (requires lng)","examples":[25.2048],"type":"number"},"lng":{"minimum":-180,"maximum":180,"description":"Longitude for geo-search (requires lat)","examples":[55.2708],"type":"number"},"radius":{"minimum":1,"maximum":500000,"description":"Search radius in meters (1-500000, default: 50000)","default":50000,"examples":[1000,10000,50000],"type":"number"},"city":{"minLength":1,"maxLength":200,"description":"Filter by city name","examples":["Dubai","Abu Dhabi"],"type":"string"},"country":{"minLength":2,"maxLength":2,"pattern":"^[A-Za-z]{2}$","description":"Filter by country code (ISO 3166-1 alpha-2). Must be a country code present in the index (e.g. AE, US, SA).","examples":["AE","SA","US"],"type":"string"},"regionId":{"minimum":0,"description":"Filter by region ID (non-negative integer)","type":"number"},"stars":{"minimum":1,"maximum":5,"description":"Minimum star rating (1-5)","type":"number"},"starRating":{"description":"Star rating filter - single number (1-5) or array of up to 10 values. Matches index values.","examples":[[4,5]],"anyOf":[{"minimum":1,"maximum":5,"type":"number"},{"maxItems":10,"type":"array","items":{"minimum":1,"maximum":5,"type":"number"}}]},"minStarRating":{"minimum":1,"maximum":5,"description":"Minimum star rating for range filter","type":"number"},"maxStarRating":{"minimum":1,"maximum":5,"description":"Maximum star rating for range filter","type":"number"},"kind":{"maxItems":20,"description":"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.","examples":[["HOTEL","RESORT"]],"type":"array","items":{"minLength":1,"maxLength":100,"type":"string"}},"hotelChain":{"maxItems":20,"description":"Hotel chain names (e.g., ['Marriott', 'Hilton']). Max 20 values.","type":"array","items":{"minLength":1,"maxLength":150,"type":"string"}},"familyFriendly":{"description":"Filter for family-friendly hotels (only set to true to filter)","type":"boolean"},"petFriendly":{"description":"Filter for pet-friendly hotels (only set to true to filter)","type":"boolean"},"businessFriendly":{"description":"Filter for business-friendly hotels (only set to true to filter)","type":"boolean"},"wellnessSpa":{"description":"Filter for hotels with spa/wellness facilities (only set to true to filter)","type":"boolean"},"beachfront":{"description":"Filter for beachfront properties (only set to true to filter)","type":"boolean"},"freeWifi":{"description":"Filter for hotels with free WiFi","type":"boolean"},"breakfastIncluded":{"description":"Filter for hotels with breakfast included","type":"boolean"},"petsAllowed":{"description":"Filter for hotels that allow pets","type":"boolean"},"parkingAvailable":{"description":"Filter for hotels with parking available","type":"boolean"},"freeParking":{"description":"Filter for hotels with free parking","type":"boolean"},"shuttleAvailable":{"description":"Filter for hotels with airport shuttle","type":"boolean"},"childrenAllowed":{"description":"Filter for hotels that allow children","type":"boolean"},"internetIncluded":{"description":"Filter for hotels with internet included","type":"boolean"},"parkingIncluded":{"description":"Filter for hotels with parking included in rate","type":"boolean"},"features":{"maxItems":50,"description":"Filter by feature slugs (e.g. free_wifi, pool_outdoor). Values must exist in features.json. Max 50.","type":"array","items":{"minLength":1,"maxLength":80,"type":"string"}},"preferFeatures":{"maxItems":20,"description":"Feature slugs for soft-boost scoring. Hotels matching more features rank higher, but those with fewer still appear. Max 20.","type":"array","items":{"minLength":1,"maxLength":80,"type":"string"}},"filterMode":{"description":"Filter mode for amenity/boolean filters. 'strict' (default): hard AND — only hotels matching ALL filters. 'prefer': soft boost — amenity filters become scoring signals; hotels matching more rank higher, but results never disappear.","default":"strict","anyOf":[{"const":"strict","type":"string"},{"const":"prefer","type":"string"}]},"poiTypesNearby":{"maxItems":30,"description":"Filter by nearby POI types (e.g., ['restaurant', 'beach']). Max 30 values.","type":"array","items":{"minLength":1,"maxLength":100,"type":"string"}},"poiNamesNearby":{"maxItems":30,"description":"Filter by specific nearby POI names (e.g., ['Burj Khalifa', 'Dubai Mall']). Max 30 values.","type":"array","items":{"minLength":1,"maxLength":200,"type":"string"}},"excludeClosed":{"description":"Exclude closed hotels (default: true)","default":true,"type":"boolean"},"providerHid":{"minimum":0,"description":"Filter by provider HID (non-negative integer)","type":"number"},"providerId":{"minLength":1,"maxLength":100,"description":"Filter by provider ID (string)","type":"string"},"sortBy":{"description":"Sort field: relevance, star_rating, name, distance, updated_at","default":"relevance","anyOf":[{"const":"relevance","type":"string"},{"const":"star_rating","type":"string"},{"const":"name","type":"string"},{"const":"distance","type":"string"},{"const":"updated_at","type":"string"}]},"sortOrder":{"description":"Sort order: asc or desc","default":"desc","anyOf":[{"const":"asc","type":"string"},{"const":"desc","type":"string"}]},"includeAggregations":{"description":"Include aggregations/facets in response","default":false,"type":"boolean"},"boostByQuality":{"description":"Enable quality-based re-ranking. Boosts results by rating_global and star_rating. Useful for ranking by hotel quality while maintaining relevance.","default":false,"type":"boolean"},"qualityRatingWeight":{"minimum":0,"maximum":1,"description":"Weight for guest rating (rating_global) in quality scoring (0-1). Default: 0.7. Higher values prioritize guest ratings over star ratings.","default":0.7,"type":"number"},"qualityStarsWeight":{"minimum":0,"maximum":1,"description":"Weight for star rating in quality scoring (0-1). Default: 0.3. Higher values prioritize hotel stars over guest ratings.","default":0.3,"type":"number"},"checkIn":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Check-in date (YYYY-MM-DD). Required for real-time pricing.","examples":["2026-03-01"],"type":"string"},"checkOut":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Check-out date (YYYY-MM-DD). Required for real-time pricing.","examples":["2026-03-05"],"type":"string"},"adults":{"minimum":1,"maximum":10,"default":2,"description":"Number of adults (1-10)","type":"number"},"children":{"minimum":0,"maximum":4,"default":0,"description":"Number of children (0-4)","type":"number"},"childAges":{"description":"Ages of children (0-17 each). Array length should match 'children' count.","examples":[[5,10]],"type":"array","items":{"minimum":0,"maximum":17,"type":"number"}},"rooms":{"minimum":1,"maximum":5,"default":1,"description":"Number of rooms (1-5)","type":"number"},"currency":{"minLength":3,"maxLength":3,"pattern":"^[A-Z]{3}$","default":"AED","description":"Currency code for prices (ISO 4217, 3 letters)","examples":["AED","USD","EUR"],"type":"string"}},"additionalProperties":false}}}}}},"/v2/search/vector":{"post":{"parameters":[],"responses":{"200":{"description":"Search response with hotels and pagination support","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"description":"Whether the search was successful","type":"boolean"},"data":{"description":"Array of hotel results (20 per page)","type":"array","items":{}},"error":{"description":"Error message if search failed","type":"string"},"requestId":{"description":"Request ID for pagination. Use with page parameter for next pages.","type":"string"},"metadata":{"type":"object","properties":{"total":{"description":"Total number of matching hotels","type":"number"},"page":{"description":"Current page number","type":"number"},"limit":{"description":"Results per page (20)","type":"number"},"totalPages":{"description":"Total number of pages available","type":"number"},"hasMore":{"description":"Whether more results are available","type":"boolean"},"cached":{"description":"Whether results came from cache","type":"boolean"},"filters":{"description":"Applied filters"},"executionTime":{"description":"Search execution time in ms","type":"number"},"strategy":{"description":"Search strategy used","type":"string"}},"required":["total","page","limit","totalPages","filters","executionTime","strategy"]},"searchMetadata":{"type":"object","properties":{"query":{"type":"string"},"mode":{"type":"string"},"opensearchTook":{"type":"number"},"embeddingMs":{"description":"Time in ms spent generating query embedding (vector/hybrid)","type":"number"},"fetchedCount":{"description":"Total hotels fetched and cached","type":"number"}}}},"required":["success","data","metadata"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"success":{"description":"Whether the search was successful","type":"boolean"},"data":{"description":"Array of hotel results (20 per page)","type":"array","items":{}},"error":{"description":"Error message if search failed","type":"string"},"requestId":{"description":"Request ID for pagination. Use with page parameter for next pages.","type":"string"},"metadata":{"type":"object","properties":{"total":{"description":"Total number of matching hotels","type":"number"},"page":{"description":"Current page number","type":"number"},"limit":{"description":"Results per page (20)","type":"number"},"totalPages":{"description":"Total number of pages available","type":"number"},"hasMore":{"description":"Whether more results are available","type":"boolean"},"cached":{"description":"Whether results came from cache","type":"boolean"},"filters":{"description":"Applied filters"},"executionTime":{"description":"Search execution time in ms","type":"number"},"strategy":{"description":"Search strategy used","type":"string"}},"required":["total","page","limit","totalPages","filters","executionTime","strategy"]},"searchMetadata":{"type":"object","properties":{"query":{"type":"string"},"mode":{"type":"string"},"opensearchTook":{"type":"number"},"embeddingMs":{"description":"Time in ms spent generating query embedding (vector/hybrid)","type":"number"},"fetchedCount":{"description":"Total hotels fetched and cached","type":"number"}}}},"required":["success","data","metadata"]}},"text/plain":{"schema":{"type":"object","properties":{"success":{"description":"Whether the search was successful","type":"boolean"},"data":{"description":"Array of hotel results (20 per page)","type":"array","items":{}},"error":{"description":"Error message if search failed","type":"string"},"requestId":{"description":"Request ID for pagination. Use with page parameter for next pages.","type":"string"},"metadata":{"type":"object","properties":{"total":{"description":"Total number of matching hotels","type":"number"},"page":{"description":"Current page number","type":"number"},"limit":{"description":"Results per page (20)","type":"number"},"totalPages":{"description":"Total number of pages available","type":"number"},"hasMore":{"description":"Whether more results are available","type":"boolean"},"cached":{"description":"Whether results came from cache","type":"boolean"},"filters":{"description":"Applied filters"},"executionTime":{"description":"Search execution time in ms","type":"number"},"strategy":{"description":"Search strategy used","type":"string"}},"required":["total","page","limit","totalPages","filters","executionTime","strategy"]},"searchMetadata":{"type":"object","properties":{"query":{"type":"string"},"mode":{"type":"string"},"opensearchTook":{"type":"number"},"embeddingMs":{"description":"Time in ms spent generating query embedding (vector/hybrid)","type":"number"},"fetchedCount":{"description":"Total hotels fetched and cached","type":"number"}}}},"required":["success","data","metadata"]}}}}},"operationId":"postV2SearchVector","tags":["V2 Search"],"summary":"Vector/Semantic Search","description":"\nSearch using **vector mode** - pure semantic similarity search using embeddings.\n\n**Best For:**\n- Natural language queries\n- Conceptual searches\n- Queries like \"quiet place for business meetings\" or \"romantic anniversary destination\"\n\n**How it Works:**\n1. Query is converted to a vector embedding\n2. k-NN search finds hotels with similar embedding vectors\n3. Results ranked by cosine similarity score\n\n**Note:** Works best with descriptive, natural language queries rather than keywords.\n\n### Request Body Example\n```json\n{\n  \"q\": \"romantic beachside getaway with spa\",\n  \"stars\": 5,\n  \"limit\": 15\n}\n```\n        ","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"q":{"minLength":0,"maxLength":500,"description":"Search query text (e.g., 'luxury hotels dubai', 'beachfront resort')","examples":["luxury hotels dubai","family friendly resort"],"type":"string"},"query":{"minLength":0,"maxLength":500,"description":"Alias for 'q' parameter","type":"string"},"strategy":{"description":"Search strategy: 'text' (BM25), 'hybrid' (text+vector), 'vector' (semantic). Omit to use route default.","anyOf":[{"const":"hybrid","type":"string"},{"const":"text","type":"string"},{"const":"vector","type":"string"}]},"requestId":{"description":"Request ID from previous search. Use with page > 1 to fetch cached results.","type":"string"},"page":{"minimum":1,"default":1,"description":"Page number. Use with requestId for subsequent pages.","type":"number"},"fetchSize":{"minimum":50,"maximum":300,"default":100,"description":"Number of hotels to fetch and cache (50-300). Higher = more pages cached.","type":"number"},"limit":{"minimum":1,"maximum":100,"default":20,"description":"Results per page (default: 20, ignored when using requestId)","type":"number"},"size":{"minimum":1,"maximum":100,"description":"Alias for 'limit'","type":"number"},"offset":{"minimum":0,"default":0,"description":"Deprecated: Use page instead","type":"number"},"lat":{"minimum":-90,"maximum":90,"description":"Latitude for geo-search (requires lng)","examples":[25.2048],"type":"number"},"lng":{"minimum":-180,"maximum":180,"description":"Longitude for geo-search (requires lat)","examples":[55.2708],"type":"number"},"radius":{"minimum":1,"maximum":500000,"description":"Search radius in meters (1-500000, default: 50000)","default":50000,"examples":[1000,10000,50000],"type":"number"},"city":{"minLength":1,"maxLength":200,"description":"Filter by city name","examples":["Dubai","Abu Dhabi"],"type":"string"},"country":{"minLength":2,"maxLength":2,"pattern":"^[A-Za-z]{2}$","description":"Filter by country code (ISO 3166-1 alpha-2). Must be a country code present in the index (e.g. AE, US, SA).","examples":["AE","SA","US"],"type":"string"},"regionId":{"minimum":0,"description":"Filter by region ID (non-negative integer)","type":"number"},"stars":{"minimum":1,"maximum":5,"description":"Minimum star rating (1-5)","type":"number"},"starRating":{"description":"Star rating filter - single number (1-5) or array of up to 10 values. Matches index values.","examples":[[4,5]],"anyOf":[{"minimum":1,"maximum":5,"type":"number"},{"maxItems":10,"type":"array","items":{"minimum":1,"maximum":5,"type":"number"}}]},"minStarRating":{"minimum":1,"maximum":5,"description":"Minimum star rating for range filter","type":"number"},"maxStarRating":{"minimum":1,"maximum":5,"description":"Maximum star rating for range filter","type":"number"},"kind":{"maxItems":20,"description":"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.","examples":[["HOTEL","RESORT"]],"type":"array","items":{"minLength":1,"maxLength":100,"type":"string"}},"hotelChain":{"maxItems":20,"description":"Hotel chain names (e.g., ['Marriott', 'Hilton']). Max 20 values.","type":"array","items":{"minLength":1,"maxLength":150,"type":"string"}},"familyFriendly":{"description":"Filter for family-friendly hotels (only set to true to filter)","type":"boolean"},"petFriendly":{"description":"Filter for pet-friendly hotels (only set to true to filter)","type":"boolean"},"businessFriendly":{"description":"Filter for business-friendly hotels (only set to true to filter)","type":"boolean"},"wellnessSpa":{"description":"Filter for hotels with spa/wellness facilities (only set to true to filter)","type":"boolean"},"beachfront":{"description":"Filter for beachfront properties (only set to true to filter)","type":"boolean"},"freeWifi":{"description":"Filter for hotels with free WiFi","type":"boolean"},"breakfastIncluded":{"description":"Filter for hotels with breakfast included","type":"boolean"},"petsAllowed":{"description":"Filter for hotels that allow pets","type":"boolean"},"parkingAvailable":{"description":"Filter for hotels with parking available","type":"boolean"},"freeParking":{"description":"Filter for hotels with free parking","type":"boolean"},"shuttleAvailable":{"description":"Filter for hotels with airport shuttle","type":"boolean"},"childrenAllowed":{"description":"Filter for hotels that allow children","type":"boolean"},"internetIncluded":{"description":"Filter for hotels with internet included","type":"boolean"},"parkingIncluded":{"description":"Filter for hotels with parking included in rate","type":"boolean"},"features":{"maxItems":50,"description":"Filter by feature slugs (e.g. free_wifi, pool_outdoor). Values must exist in features.json. Max 50.","type":"array","items":{"minLength":1,"maxLength":80,"type":"string"}},"preferFeatures":{"maxItems":20,"description":"Feature slugs for soft-boost scoring. Hotels matching more features rank higher, but those with fewer still appear. Max 20.","type":"array","items":{"minLength":1,"maxLength":80,"type":"string"}},"filterMode":{"description":"Filter mode for amenity/boolean filters. 'strict' (default): hard AND — only hotels matching ALL filters. 'prefer': soft boost — amenity filters become scoring signals; hotels matching more rank higher, but results never disappear.","default":"strict","anyOf":[{"const":"strict","type":"string"},{"const":"prefer","type":"string"}]},"poiTypesNearby":{"maxItems":30,"description":"Filter by nearby POI types (e.g., ['restaurant', 'beach']). Max 30 values.","type":"array","items":{"minLength":1,"maxLength":100,"type":"string"}},"poiNamesNearby":{"maxItems":30,"description":"Filter by specific nearby POI names (e.g., ['Burj Khalifa', 'Dubai Mall']). Max 30 values.","type":"array","items":{"minLength":1,"maxLength":200,"type":"string"}},"excludeClosed":{"description":"Exclude closed hotels (default: true)","default":true,"type":"boolean"},"providerHid":{"minimum":0,"description":"Filter by provider HID (non-negative integer)","type":"number"},"providerId":{"minLength":1,"maxLength":100,"description":"Filter by provider ID (string)","type":"string"},"sortBy":{"description":"Sort field: relevance, star_rating, name, distance, updated_at","default":"relevance","anyOf":[{"const":"relevance","type":"string"},{"const":"star_rating","type":"string"},{"const":"name","type":"string"},{"const":"distance","type":"string"},{"const":"updated_at","type":"string"}]},"sortOrder":{"description":"Sort order: asc or desc","default":"desc","anyOf":[{"const":"asc","type":"string"},{"const":"desc","type":"string"}]},"includeAggregations":{"description":"Include aggregations/facets in response","default":false,"type":"boolean"},"boostByQuality":{"description":"Enable quality-based re-ranking. Boosts results by rating_global and star_rating. Useful for ranking by hotel quality while maintaining relevance.","default":false,"type":"boolean"},"qualityRatingWeight":{"minimum":0,"maximum":1,"description":"Weight for guest rating (rating_global) in quality scoring (0-1). Default: 0.7. Higher values prioritize guest ratings over star ratings.","default":0.7,"type":"number"},"qualityStarsWeight":{"minimum":0,"maximum":1,"description":"Weight for star rating in quality scoring (0-1). Default: 0.3. Higher values prioritize hotel stars over guest ratings.","default":0.3,"type":"number"},"checkIn":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Check-in date (YYYY-MM-DD). Required for real-time pricing.","examples":["2026-03-01"],"type":"string"},"checkOut":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Check-out date (YYYY-MM-DD). Required for real-time pricing.","examples":["2026-03-05"],"type":"string"},"adults":{"minimum":1,"maximum":10,"default":2,"description":"Number of adults (1-10)","type":"number"},"children":{"minimum":0,"maximum":4,"default":0,"description":"Number of children (0-4)","type":"number"},"childAges":{"description":"Ages of children (0-17 each). Array length should match 'children' count.","examples":[[5,10]],"type":"array","items":{"minimum":0,"maximum":17,"type":"number"}},"rooms":{"minimum":1,"maximum":5,"default":1,"description":"Number of rooms (1-5)","type":"number"},"currency":{"minLength":3,"maxLength":3,"pattern":"^[A-Z]{3}$","default":"AED","description":"Currency code for prices (ISO 4217, 3 letters)","examples":["AED","USD","EUR"],"type":"string"}},"additionalProperties":false}},"multipart/form-data":{"schema":{"type":"object","properties":{"q":{"minLength":0,"maxLength":500,"description":"Search query text (e.g., 'luxury hotels dubai', 'beachfront resort')","examples":["luxury hotels dubai","family friendly resort"],"type":"string"},"query":{"minLength":0,"maxLength":500,"description":"Alias for 'q' parameter","type":"string"},"strategy":{"description":"Search strategy: 'text' (BM25), 'hybrid' (text+vector), 'vector' (semantic). Omit to use route default.","anyOf":[{"const":"hybrid","type":"string"},{"const":"text","type":"string"},{"const":"vector","type":"string"}]},"requestId":{"description":"Request ID from previous search. Use with page > 1 to fetch cached results.","type":"string"},"page":{"minimum":1,"default":1,"description":"Page number. Use with requestId for subsequent pages.","type":"number"},"fetchSize":{"minimum":50,"maximum":300,"default":100,"description":"Number of hotels to fetch and cache (50-300). Higher = more pages cached.","type":"number"},"limit":{"minimum":1,"maximum":100,"default":20,"description":"Results per page (default: 20, ignored when using requestId)","type":"number"},"size":{"minimum":1,"maximum":100,"description":"Alias for 'limit'","type":"number"},"offset":{"minimum":0,"default":0,"description":"Deprecated: Use page instead","type":"number"},"lat":{"minimum":-90,"maximum":90,"description":"Latitude for geo-search (requires lng)","examples":[25.2048],"type":"number"},"lng":{"minimum":-180,"maximum":180,"description":"Longitude for geo-search (requires lat)","examples":[55.2708],"type":"number"},"radius":{"minimum":1,"maximum":500000,"description":"Search radius in meters (1-500000, default: 50000)","default":50000,"examples":[1000,10000,50000],"type":"number"},"city":{"minLength":1,"maxLength":200,"description":"Filter by city name","examples":["Dubai","Abu Dhabi"],"type":"string"},"country":{"minLength":2,"maxLength":2,"pattern":"^[A-Za-z]{2}$","description":"Filter by country code (ISO 3166-1 alpha-2). Must be a country code present in the index (e.g. AE, US, SA).","examples":["AE","SA","US"],"type":"string"},"regionId":{"minimum":0,"description":"Filter by region ID (non-negative integer)","type":"number"},"stars":{"minimum":1,"maximum":5,"description":"Minimum star rating (1-5)","type":"number"},"starRating":{"description":"Star rating filter - single number (1-5) or array of up to 10 values. Matches index values.","examples":[[4,5]],"anyOf":[{"minimum":1,"maximum":5,"type":"number"},{"maxItems":10,"type":"array","items":{"minimum":1,"maximum":5,"type":"number"}}]},"minStarRating":{"minimum":1,"maximum":5,"description":"Minimum star rating for range filter","type":"number"},"maxStarRating":{"minimum":1,"maximum":5,"description":"Maximum star rating for range filter","type":"number"},"kind":{"maxItems":20,"description":"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.","examples":[["HOTEL","RESORT"]],"type":"array","items":{"minLength":1,"maxLength":100,"type":"string"}},"hotelChain":{"maxItems":20,"description":"Hotel chain names (e.g., ['Marriott', 'Hilton']). Max 20 values.","type":"array","items":{"minLength":1,"maxLength":150,"type":"string"}},"familyFriendly":{"description":"Filter for family-friendly hotels (only set to true to filter)","type":"boolean"},"petFriendly":{"description":"Filter for pet-friendly hotels (only set to true to filter)","type":"boolean"},"businessFriendly":{"description":"Filter for business-friendly hotels (only set to true to filter)","type":"boolean"},"wellnessSpa":{"description":"Filter for hotels with spa/wellness facilities (only set to true to filter)","type":"boolean"},"beachfront":{"description":"Filter for beachfront properties (only set to true to filter)","type":"boolean"},"freeWifi":{"description":"Filter for hotels with free WiFi","type":"boolean"},"breakfastIncluded":{"description":"Filter for hotels with breakfast included","type":"boolean"},"petsAllowed":{"description":"Filter for hotels that allow pets","type":"boolean"},"parkingAvailable":{"description":"Filter for hotels with parking available","type":"boolean"},"freeParking":{"description":"Filter for hotels with free parking","type":"boolean"},"shuttleAvailable":{"description":"Filter for hotels with airport shuttle","type":"boolean"},"childrenAllowed":{"description":"Filter for hotels that allow children","type":"boolean"},"internetIncluded":{"description":"Filter for hotels with internet included","type":"boolean"},"parkingIncluded":{"description":"Filter for hotels with parking included in rate","type":"boolean"},"features":{"maxItems":50,"description":"Filter by feature slugs (e.g. free_wifi, pool_outdoor). Values must exist in features.json. Max 50.","type":"array","items":{"minLength":1,"maxLength":80,"type":"string"}},"preferFeatures":{"maxItems":20,"description":"Feature slugs for soft-boost scoring. Hotels matching more features rank higher, but those with fewer still appear. Max 20.","type":"array","items":{"minLength":1,"maxLength":80,"type":"string"}},"filterMode":{"description":"Filter mode for amenity/boolean filters. 'strict' (default): hard AND — only hotels matching ALL filters. 'prefer': soft boost — amenity filters become scoring signals; hotels matching more rank higher, but results never disappear.","default":"strict","anyOf":[{"const":"strict","type":"string"},{"const":"prefer","type":"string"}]},"poiTypesNearby":{"maxItems":30,"description":"Filter by nearby POI types (e.g., ['restaurant', 'beach']). Max 30 values.","type":"array","items":{"minLength":1,"maxLength":100,"type":"string"}},"poiNamesNearby":{"maxItems":30,"description":"Filter by specific nearby POI names (e.g., ['Burj Khalifa', 'Dubai Mall']). Max 30 values.","type":"array","items":{"minLength":1,"maxLength":200,"type":"string"}},"excludeClosed":{"description":"Exclude closed hotels (default: true)","default":true,"type":"boolean"},"providerHid":{"minimum":0,"description":"Filter by provider HID (non-negative integer)","type":"number"},"providerId":{"minLength":1,"maxLength":100,"description":"Filter by provider ID (string)","type":"string"},"sortBy":{"description":"Sort field: relevance, star_rating, name, distance, updated_at","default":"relevance","anyOf":[{"const":"relevance","type":"string"},{"const":"star_rating","type":"string"},{"const":"name","type":"string"},{"const":"distance","type":"string"},{"const":"updated_at","type":"string"}]},"sortOrder":{"description":"Sort order: asc or desc","default":"desc","anyOf":[{"const":"asc","type":"string"},{"const":"desc","type":"string"}]},"includeAggregations":{"description":"Include aggregations/facets in response","default":false,"type":"boolean"},"boostByQuality":{"description":"Enable quality-based re-ranking. Boosts results by rating_global and star_rating. Useful for ranking by hotel quality while maintaining relevance.","default":false,"type":"boolean"},"qualityRatingWeight":{"minimum":0,"maximum":1,"description":"Weight for guest rating (rating_global) in quality scoring (0-1). Default: 0.7. Higher values prioritize guest ratings over star ratings.","default":0.7,"type":"number"},"qualityStarsWeight":{"minimum":0,"maximum":1,"description":"Weight for star rating in quality scoring (0-1). Default: 0.3. Higher values prioritize hotel stars over guest ratings.","default":0.3,"type":"number"},"checkIn":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Check-in date (YYYY-MM-DD). Required for real-time pricing.","examples":["2026-03-01"],"type":"string"},"checkOut":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Check-out date (YYYY-MM-DD). Required for real-time pricing.","examples":["2026-03-05"],"type":"string"},"adults":{"minimum":1,"maximum":10,"default":2,"description":"Number of adults (1-10)","type":"number"},"children":{"minimum":0,"maximum":4,"default":0,"description":"Number of children (0-4)","type":"number"},"childAges":{"description":"Ages of children (0-17 each). Array length should match 'children' count.","examples":[[5,10]],"type":"array","items":{"minimum":0,"maximum":17,"type":"number"}},"rooms":{"minimum":1,"maximum":5,"default":1,"description":"Number of rooms (1-5)","type":"number"},"currency":{"minLength":3,"maxLength":3,"pattern":"^[A-Z]{3}$","default":"AED","description":"Currency code for prices (ISO 4217, 3 letters)","examples":["AED","USD","EUR"],"type":"string"}},"additionalProperties":false}},"text/plain":{"schema":{"type":"object","properties":{"q":{"minLength":0,"maxLength":500,"description":"Search query text (e.g., 'luxury hotels dubai', 'beachfront resort')","examples":["luxury hotels dubai","family friendly resort"],"type":"string"},"query":{"minLength":0,"maxLength":500,"description":"Alias for 'q' parameter","type":"string"},"strategy":{"description":"Search strategy: 'text' (BM25), 'hybrid' (text+vector), 'vector' (semantic). Omit to use route default.","anyOf":[{"const":"hybrid","type":"string"},{"const":"text","type":"string"},{"const":"vector","type":"string"}]},"requestId":{"description":"Request ID from previous search. Use with page > 1 to fetch cached results.","type":"string"},"page":{"minimum":1,"default":1,"description":"Page number. Use with requestId for subsequent pages.","type":"number"},"fetchSize":{"minimum":50,"maximum":300,"default":100,"description":"Number of hotels to fetch and cache (50-300). Higher = more pages cached.","type":"number"},"limit":{"minimum":1,"maximum":100,"default":20,"description":"Results per page (default: 20, ignored when using requestId)","type":"number"},"size":{"minimum":1,"maximum":100,"description":"Alias for 'limit'","type":"number"},"offset":{"minimum":0,"default":0,"description":"Deprecated: Use page instead","type":"number"},"lat":{"minimum":-90,"maximum":90,"description":"Latitude for geo-search (requires lng)","examples":[25.2048],"type":"number"},"lng":{"minimum":-180,"maximum":180,"description":"Longitude for geo-search (requires lat)","examples":[55.2708],"type":"number"},"radius":{"minimum":1,"maximum":500000,"description":"Search radius in meters (1-500000, default: 50000)","default":50000,"examples":[1000,10000,50000],"type":"number"},"city":{"minLength":1,"maxLength":200,"description":"Filter by city name","examples":["Dubai","Abu Dhabi"],"type":"string"},"country":{"minLength":2,"maxLength":2,"pattern":"^[A-Za-z]{2}$","description":"Filter by country code (ISO 3166-1 alpha-2). Must be a country code present in the index (e.g. AE, US, SA).","examples":["AE","SA","US"],"type":"string"},"regionId":{"minimum":0,"description":"Filter by region ID (non-negative integer)","type":"number"},"stars":{"minimum":1,"maximum":5,"description":"Minimum star rating (1-5)","type":"number"},"starRating":{"description":"Star rating filter - single number (1-5) or array of up to 10 values. Matches index values.","examples":[[4,5]],"anyOf":[{"minimum":1,"maximum":5,"type":"number"},{"maxItems":10,"type":"array","items":{"minimum":1,"maximum":5,"type":"number"}}]},"minStarRating":{"minimum":1,"maximum":5,"description":"Minimum star rating for range filter","type":"number"},"maxStarRating":{"minimum":1,"maximum":5,"description":"Maximum star rating for range filter","type":"number"},"kind":{"maxItems":20,"description":"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.","examples":[["HOTEL","RESORT"]],"type":"array","items":{"minLength":1,"maxLength":100,"type":"string"}},"hotelChain":{"maxItems":20,"description":"Hotel chain names (e.g., ['Marriott', 'Hilton']). Max 20 values.","type":"array","items":{"minLength":1,"maxLength":150,"type":"string"}},"familyFriendly":{"description":"Filter for family-friendly hotels (only set to true to filter)","type":"boolean"},"petFriendly":{"description":"Filter for pet-friendly hotels (only set to true to filter)","type":"boolean"},"businessFriendly":{"description":"Filter for business-friendly hotels (only set to true to filter)","type":"boolean"},"wellnessSpa":{"description":"Filter for hotels with spa/wellness facilities (only set to true to filter)","type":"boolean"},"beachfront":{"description":"Filter for beachfront properties (only set to true to filter)","type":"boolean"},"freeWifi":{"description":"Filter for hotels with free WiFi","type":"boolean"},"breakfastIncluded":{"description":"Filter for hotels with breakfast included","type":"boolean"},"petsAllowed":{"description":"Filter for hotels that allow pets","type":"boolean"},"parkingAvailable":{"description":"Filter for hotels with parking available","type":"boolean"},"freeParking":{"description":"Filter for hotels with free parking","type":"boolean"},"shuttleAvailable":{"description":"Filter for hotels with airport shuttle","type":"boolean"},"childrenAllowed":{"description":"Filter for hotels that allow children","type":"boolean"},"internetIncluded":{"description":"Filter for hotels with internet included","type":"boolean"},"parkingIncluded":{"description":"Filter for hotels with parking included in rate","type":"boolean"},"features":{"maxItems":50,"description":"Filter by feature slugs (e.g. free_wifi, pool_outdoor). Values must exist in features.json. Max 50.","type":"array","items":{"minLength":1,"maxLength":80,"type":"string"}},"preferFeatures":{"maxItems":20,"description":"Feature slugs for soft-boost scoring. Hotels matching more features rank higher, but those with fewer still appear. Max 20.","type":"array","items":{"minLength":1,"maxLength":80,"type":"string"}},"filterMode":{"description":"Filter mode for amenity/boolean filters. 'strict' (default): hard AND — only hotels matching ALL filters. 'prefer': soft boost — amenity filters become scoring signals; hotels matching more rank higher, but results never disappear.","default":"strict","anyOf":[{"const":"strict","type":"string"},{"const":"prefer","type":"string"}]},"poiTypesNearby":{"maxItems":30,"description":"Filter by nearby POI types (e.g., ['restaurant', 'beach']). Max 30 values.","type":"array","items":{"minLength":1,"maxLength":100,"type":"string"}},"poiNamesNearby":{"maxItems":30,"description":"Filter by specific nearby POI names (e.g., ['Burj Khalifa', 'Dubai Mall']). Max 30 values.","type":"array","items":{"minLength":1,"maxLength":200,"type":"string"}},"excludeClosed":{"description":"Exclude closed hotels (default: true)","default":true,"type":"boolean"},"providerHid":{"minimum":0,"description":"Filter by provider HID (non-negative integer)","type":"number"},"providerId":{"minLength":1,"maxLength":100,"description":"Filter by provider ID (string)","type":"string"},"sortBy":{"description":"Sort field: relevance, star_rating, name, distance, updated_at","default":"relevance","anyOf":[{"const":"relevance","type":"string"},{"const":"star_rating","type":"string"},{"const":"name","type":"string"},{"const":"distance","type":"string"},{"const":"updated_at","type":"string"}]},"sortOrder":{"description":"Sort order: asc or desc","default":"desc","anyOf":[{"const":"asc","type":"string"},{"const":"desc","type":"string"}]},"includeAggregations":{"description":"Include aggregations/facets in response","default":false,"type":"boolean"},"boostByQuality":{"description":"Enable quality-based re-ranking. Boosts results by rating_global and star_rating. Useful for ranking by hotel quality while maintaining relevance.","default":false,"type":"boolean"},"qualityRatingWeight":{"minimum":0,"maximum":1,"description":"Weight for guest rating (rating_global) in quality scoring (0-1). Default: 0.7. Higher values prioritize guest ratings over star ratings.","default":0.7,"type":"number"},"qualityStarsWeight":{"minimum":0,"maximum":1,"description":"Weight for star rating in quality scoring (0-1). Default: 0.3. Higher values prioritize hotel stars over guest ratings.","default":0.3,"type":"number"},"checkIn":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Check-in date (YYYY-MM-DD). Required for real-time pricing.","examples":["2026-03-01"],"type":"string"},"checkOut":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Check-out date (YYYY-MM-DD). Required for real-time pricing.","examples":["2026-03-05"],"type":"string"},"adults":{"minimum":1,"maximum":10,"default":2,"description":"Number of adults (1-10)","type":"number"},"children":{"minimum":0,"maximum":4,"default":0,"description":"Number of children (0-4)","type":"number"},"childAges":{"description":"Ages of children (0-17 each). Array length should match 'children' count.","examples":[[5,10]],"type":"array","items":{"minimum":0,"maximum":17,"type":"number"}},"rooms":{"minimum":1,"maximum":5,"default":1,"description":"Number of rooms (1-5)","type":"number"},"currency":{"minLength":3,"maxLength":3,"pattern":"^[A-Z]{3}$","default":"AED","description":"Currency code for prices (ISO 4217, 3 letters)","examples":["AED","USD","EUR"],"type":"string"}},"additionalProperties":false}}}}}},"/v2/search/text":{"post":{"parameters":[],"responses":{"200":{"description":"Search response with hotels and pagination support","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"description":"Whether the search was successful","type":"boolean"},"data":{"description":"Array of hotel results (20 per page)","type":"array","items":{}},"error":{"description":"Error message if search failed","type":"string"},"requestId":{"description":"Request ID for pagination. Use with page parameter for next pages.","type":"string"},"metadata":{"type":"object","properties":{"total":{"description":"Total number of matching hotels","type":"number"},"page":{"description":"Current page number","type":"number"},"limit":{"description":"Results per page (20)","type":"number"},"totalPages":{"description":"Total number of pages available","type":"number"},"hasMore":{"description":"Whether more results are available","type":"boolean"},"cached":{"description":"Whether results came from cache","type":"boolean"},"filters":{"description":"Applied filters"},"executionTime":{"description":"Search execution time in ms","type":"number"},"strategy":{"description":"Search strategy used","type":"string"}},"required":["total","page","limit","totalPages","filters","executionTime","strategy"]},"searchMetadata":{"type":"object","properties":{"query":{"type":"string"},"mode":{"type":"string"},"opensearchTook":{"type":"number"},"embeddingMs":{"description":"Time in ms spent generating query embedding (vector/hybrid)","type":"number"},"fetchedCount":{"description":"Total hotels fetched and cached","type":"number"}}}},"required":["success","data","metadata"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"success":{"description":"Whether the search was successful","type":"boolean"},"data":{"description":"Array of hotel results (20 per page)","type":"array","items":{}},"error":{"description":"Error message if search failed","type":"string"},"requestId":{"description":"Request ID for pagination. Use with page parameter for next pages.","type":"string"},"metadata":{"type":"object","properties":{"total":{"description":"Total number of matching hotels","type":"number"},"page":{"description":"Current page number","type":"number"},"limit":{"description":"Results per page (20)","type":"number"},"totalPages":{"description":"Total number of pages available","type":"number"},"hasMore":{"description":"Whether more results are available","type":"boolean"},"cached":{"description":"Whether results came from cache","type":"boolean"},"filters":{"description":"Applied filters"},"executionTime":{"description":"Search execution time in ms","type":"number"},"strategy":{"description":"Search strategy used","type":"string"}},"required":["total","page","limit","totalPages","filters","executionTime","strategy"]},"searchMetadata":{"type":"object","properties":{"query":{"type":"string"},"mode":{"type":"string"},"opensearchTook":{"type":"number"},"embeddingMs":{"description":"Time in ms spent generating query embedding (vector/hybrid)","type":"number"},"fetchedCount":{"description":"Total hotels fetched and cached","type":"number"}}}},"required":["success","data","metadata"]}},"text/plain":{"schema":{"type":"object","properties":{"success":{"description":"Whether the search was successful","type":"boolean"},"data":{"description":"Array of hotel results (20 per page)","type":"array","items":{}},"error":{"description":"Error message if search failed","type":"string"},"requestId":{"description":"Request ID for pagination. Use with page parameter for next pages.","type":"string"},"metadata":{"type":"object","properties":{"total":{"description":"Total number of matching hotels","type":"number"},"page":{"description":"Current page number","type":"number"},"limit":{"description":"Results per page (20)","type":"number"},"totalPages":{"description":"Total number of pages available","type":"number"},"hasMore":{"description":"Whether more results are available","type":"boolean"},"cached":{"description":"Whether results came from cache","type":"boolean"},"filters":{"description":"Applied filters"},"executionTime":{"description":"Search execution time in ms","type":"number"},"strategy":{"description":"Search strategy used","type":"string"}},"required":["total","page","limit","totalPages","filters","executionTime","strategy"]},"searchMetadata":{"type":"object","properties":{"query":{"type":"string"},"mode":{"type":"string"},"opensearchTook":{"type":"number"},"embeddingMs":{"description":"Time in ms spent generating query embedding (vector/hybrid)","type":"number"},"fetchedCount":{"description":"Total hotels fetched and cached","type":"number"}}}},"required":["success","data","metadata"]}}}}},"operationId":"postV2SearchText","tags":["V2 Search"],"summary":"Text/BM25 Search","description":"\nSearch using **text mode** - traditional BM25 full-text search.\n\n**Best For:**\n- Exact hotel name searches\n- Specific location searches\n- Keyword-heavy queries\n- Queries like \"Burj Al Arab\" or \"Marriott JBR Dubai\"\n\n**How it Works:**\n1. Query is tokenized and matched against hotel fields\n2. TF-IDF scoring ranks exact matches higher\n3. Supports fuzzy matching for typo tolerance\n\n**Note:** Faster than hybrid/vector for simple keyword queries.\n\n### Request Body Example\n```json\n{\n  \"q\": \"Burj Al Arab\",\n  \"limit\": 10\n}\n```\n        ","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"q":{"minLength":0,"maxLength":500,"description":"Search query text (e.g., 'luxury hotels dubai', 'beachfront resort')","examples":["luxury hotels dubai","family friendly resort"],"type":"string"},"query":{"minLength":0,"maxLength":500,"description":"Alias for 'q' parameter","type":"string"},"strategy":{"description":"Search strategy: 'text' (BM25), 'hybrid' (text+vector), 'vector' (semantic). Omit to use route default.","anyOf":[{"const":"hybrid","type":"string"},{"const":"text","type":"string"},{"const":"vector","type":"string"}]},"requestId":{"description":"Request ID from previous search. Use with page > 1 to fetch cached results.","type":"string"},"page":{"minimum":1,"default":1,"description":"Page number. Use with requestId for subsequent pages.","type":"number"},"fetchSize":{"minimum":50,"maximum":300,"default":100,"description":"Number of hotels to fetch and cache (50-300). Higher = more pages cached.","type":"number"},"limit":{"minimum":1,"maximum":100,"default":20,"description":"Results per page (default: 20, ignored when using requestId)","type":"number"},"size":{"minimum":1,"maximum":100,"description":"Alias for 'limit'","type":"number"},"offset":{"minimum":0,"default":0,"description":"Deprecated: Use page instead","type":"number"},"lat":{"minimum":-90,"maximum":90,"description":"Latitude for geo-search (requires lng)","examples":[25.2048],"type":"number"},"lng":{"minimum":-180,"maximum":180,"description":"Longitude for geo-search (requires lat)","examples":[55.2708],"type":"number"},"radius":{"minimum":1,"maximum":500000,"description":"Search radius in meters (1-500000, default: 50000)","default":50000,"examples":[1000,10000,50000],"type":"number"},"city":{"minLength":1,"maxLength":200,"description":"Filter by city name","examples":["Dubai","Abu Dhabi"],"type":"string"},"country":{"minLength":2,"maxLength":2,"pattern":"^[A-Za-z]{2}$","description":"Filter by country code (ISO 3166-1 alpha-2). Must be a country code present in the index (e.g. AE, US, SA).","examples":["AE","SA","US"],"type":"string"},"regionId":{"minimum":0,"description":"Filter by region ID (non-negative integer)","type":"number"},"stars":{"minimum":1,"maximum":5,"description":"Minimum star rating (1-5)","type":"number"},"starRating":{"description":"Star rating filter - single number (1-5) or array of up to 10 values. Matches index values.","examples":[[4,5]],"anyOf":[{"minimum":1,"maximum":5,"type":"number"},{"maxItems":10,"type":"array","items":{"minimum":1,"maximum":5,"type":"number"}}]},"minStarRating":{"minimum":1,"maximum":5,"description":"Minimum star rating for range filter","type":"number"},"maxStarRating":{"minimum":1,"maximum":5,"description":"Maximum star rating for range filter","type":"number"},"kind":{"maxItems":20,"description":"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.","examples":[["HOTEL","RESORT"]],"type":"array","items":{"minLength":1,"maxLength":100,"type":"string"}},"hotelChain":{"maxItems":20,"description":"Hotel chain names (e.g., ['Marriott', 'Hilton']). Max 20 values.","type":"array","items":{"minLength":1,"maxLength":150,"type":"string"}},"familyFriendly":{"description":"Filter for family-friendly hotels (only set to true to filter)","type":"boolean"},"petFriendly":{"description":"Filter for pet-friendly hotels (only set to true to filter)","type":"boolean"},"businessFriendly":{"description":"Filter for business-friendly hotels (only set to true to filter)","type":"boolean"},"wellnessSpa":{"description":"Filter for hotels with spa/wellness facilities (only set to true to filter)","type":"boolean"},"beachfront":{"description":"Filter for beachfront properties (only set to true to filter)","type":"boolean"},"freeWifi":{"description":"Filter for hotels with free WiFi","type":"boolean"},"breakfastIncluded":{"description":"Filter for hotels with breakfast included","type":"boolean"},"petsAllowed":{"description":"Filter for hotels that allow pets","type":"boolean"},"parkingAvailable":{"description":"Filter for hotels with parking available","type":"boolean"},"freeParking":{"description":"Filter for hotels with free parking","type":"boolean"},"shuttleAvailable":{"description":"Filter for hotels with airport shuttle","type":"boolean"},"childrenAllowed":{"description":"Filter for hotels that allow children","type":"boolean"},"internetIncluded":{"description":"Filter for hotels with internet included","type":"boolean"},"parkingIncluded":{"description":"Filter for hotels with parking included in rate","type":"boolean"},"features":{"maxItems":50,"description":"Filter by feature slugs (e.g. free_wifi, pool_outdoor). Values must exist in features.json. Max 50.","type":"array","items":{"minLength":1,"maxLength":80,"type":"string"}},"preferFeatures":{"maxItems":20,"description":"Feature slugs for soft-boost scoring. Hotels matching more features rank higher, but those with fewer still appear. Max 20.","type":"array","items":{"minLength":1,"maxLength":80,"type":"string"}},"filterMode":{"description":"Filter mode for amenity/boolean filters. 'strict' (default): hard AND — only hotels matching ALL filters. 'prefer': soft boost — amenity filters become scoring signals; hotels matching more rank higher, but results never disappear.","default":"strict","anyOf":[{"const":"strict","type":"string"},{"const":"prefer","type":"string"}]},"poiTypesNearby":{"maxItems":30,"description":"Filter by nearby POI types (e.g., ['restaurant', 'beach']). Max 30 values.","type":"array","items":{"minLength":1,"maxLength":100,"type":"string"}},"poiNamesNearby":{"maxItems":30,"description":"Filter by specific nearby POI names (e.g., ['Burj Khalifa', 'Dubai Mall']). Max 30 values.","type":"array","items":{"minLength":1,"maxLength":200,"type":"string"}},"excludeClosed":{"description":"Exclude closed hotels (default: true)","default":true,"type":"boolean"},"providerHid":{"minimum":0,"description":"Filter by provider HID (non-negative integer)","type":"number"},"providerId":{"minLength":1,"maxLength":100,"description":"Filter by provider ID (string)","type":"string"},"sortBy":{"description":"Sort field: relevance, star_rating, name, distance, updated_at","default":"relevance","anyOf":[{"const":"relevance","type":"string"},{"const":"star_rating","type":"string"},{"const":"name","type":"string"},{"const":"distance","type":"string"},{"const":"updated_at","type":"string"}]},"sortOrder":{"description":"Sort order: asc or desc","default":"desc","anyOf":[{"const":"asc","type":"string"},{"const":"desc","type":"string"}]},"includeAggregations":{"description":"Include aggregations/facets in response","default":false,"type":"boolean"},"boostByQuality":{"description":"Enable quality-based re-ranking. Boosts results by rating_global and star_rating. Useful for ranking by hotel quality while maintaining relevance.","default":false,"type":"boolean"},"qualityRatingWeight":{"minimum":0,"maximum":1,"description":"Weight for guest rating (rating_global) in quality scoring (0-1). Default: 0.7. Higher values prioritize guest ratings over star ratings.","default":0.7,"type":"number"},"qualityStarsWeight":{"minimum":0,"maximum":1,"description":"Weight for star rating in quality scoring (0-1). Default: 0.3. Higher values prioritize hotel stars over guest ratings.","default":0.3,"type":"number"},"checkIn":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Check-in date (YYYY-MM-DD). Required for real-time pricing.","examples":["2026-03-01"],"type":"string"},"checkOut":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Check-out date (YYYY-MM-DD). Required for real-time pricing.","examples":["2026-03-05"],"type":"string"},"adults":{"minimum":1,"maximum":10,"default":2,"description":"Number of adults (1-10)","type":"number"},"children":{"minimum":0,"maximum":4,"default":0,"description":"Number of children (0-4)","type":"number"},"childAges":{"description":"Ages of children (0-17 each). Array length should match 'children' count.","examples":[[5,10]],"type":"array","items":{"minimum":0,"maximum":17,"type":"number"}},"rooms":{"minimum":1,"maximum":5,"default":1,"description":"Number of rooms (1-5)","type":"number"},"currency":{"minLength":3,"maxLength":3,"pattern":"^[A-Z]{3}$","default":"AED","description":"Currency code for prices (ISO 4217, 3 letters)","examples":["AED","USD","EUR"],"type":"string"}},"additionalProperties":false}},"multipart/form-data":{"schema":{"type":"object","properties":{"q":{"minLength":0,"maxLength":500,"description":"Search query text (e.g., 'luxury hotels dubai', 'beachfront resort')","examples":["luxury hotels dubai","family friendly resort"],"type":"string"},"query":{"minLength":0,"maxLength":500,"description":"Alias for 'q' parameter","type":"string"},"strategy":{"description":"Search strategy: 'text' (BM25), 'hybrid' (text+vector), 'vector' (semantic). Omit to use route default.","anyOf":[{"const":"hybrid","type":"string"},{"const":"text","type":"string"},{"const":"vector","type":"string"}]},"requestId":{"description":"Request ID from previous search. Use with page > 1 to fetch cached results.","type":"string"},"page":{"minimum":1,"default":1,"description":"Page number. Use with requestId for subsequent pages.","type":"number"},"fetchSize":{"minimum":50,"maximum":300,"default":100,"description":"Number of hotels to fetch and cache (50-300). Higher = more pages cached.","type":"number"},"limit":{"minimum":1,"maximum":100,"default":20,"description":"Results per page (default: 20, ignored when using requestId)","type":"number"},"size":{"minimum":1,"maximum":100,"description":"Alias for 'limit'","type":"number"},"offset":{"minimum":0,"default":0,"description":"Deprecated: Use page instead","type":"number"},"lat":{"minimum":-90,"maximum":90,"description":"Latitude for geo-search (requires lng)","examples":[25.2048],"type":"number"},"lng":{"minimum":-180,"maximum":180,"description":"Longitude for geo-search (requires lat)","examples":[55.2708],"type":"number"},"radius":{"minimum":1,"maximum":500000,"description":"Search radius in meters (1-500000, default: 50000)","default":50000,"examples":[1000,10000,50000],"type":"number"},"city":{"minLength":1,"maxLength":200,"description":"Filter by city name","examples":["Dubai","Abu Dhabi"],"type":"string"},"country":{"minLength":2,"maxLength":2,"pattern":"^[A-Za-z]{2}$","description":"Filter by country code (ISO 3166-1 alpha-2). Must be a country code present in the index (e.g. AE, US, SA).","examples":["AE","SA","US"],"type":"string"},"regionId":{"minimum":0,"description":"Filter by region ID (non-negative integer)","type":"number"},"stars":{"minimum":1,"maximum":5,"description":"Minimum star rating (1-5)","type":"number"},"starRating":{"description":"Star rating filter - single number (1-5) or array of up to 10 values. Matches index values.","examples":[[4,5]],"anyOf":[{"minimum":1,"maximum":5,"type":"number"},{"maxItems":10,"type":"array","items":{"minimum":1,"maximum":5,"type":"number"}}]},"minStarRating":{"minimum":1,"maximum":5,"description":"Minimum star rating for range filter","type":"number"},"maxStarRating":{"minimum":1,"maximum":5,"description":"Maximum star rating for range filter","type":"number"},"kind":{"maxItems":20,"description":"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.","examples":[["HOTEL","RESORT"]],"type":"array","items":{"minLength":1,"maxLength":100,"type":"string"}},"hotelChain":{"maxItems":20,"description":"Hotel chain names (e.g., ['Marriott', 'Hilton']). Max 20 values.","type":"array","items":{"minLength":1,"maxLength":150,"type":"string"}},"familyFriendly":{"description":"Filter for family-friendly hotels (only set to true to filter)","type":"boolean"},"petFriendly":{"description":"Filter for pet-friendly hotels (only set to true to filter)","type":"boolean"},"businessFriendly":{"description":"Filter for business-friendly hotels (only set to true to filter)","type":"boolean"},"wellnessSpa":{"description":"Filter for hotels with spa/wellness facilities (only set to true to filter)","type":"boolean"},"beachfront":{"description":"Filter for beachfront properties (only set to true to filter)","type":"boolean"},"freeWifi":{"description":"Filter for hotels with free WiFi","type":"boolean"},"breakfastIncluded":{"description":"Filter for hotels with breakfast included","type":"boolean"},"petsAllowed":{"description":"Filter for hotels that allow pets","type":"boolean"},"parkingAvailable":{"description":"Filter for hotels with parking available","type":"boolean"},"freeParking":{"description":"Filter for hotels with free parking","type":"boolean"},"shuttleAvailable":{"description":"Filter for hotels with airport shuttle","type":"boolean"},"childrenAllowed":{"description":"Filter for hotels that allow children","type":"boolean"},"internetIncluded":{"description":"Filter for hotels with internet included","type":"boolean"},"parkingIncluded":{"description":"Filter for hotels with parking included in rate","type":"boolean"},"features":{"maxItems":50,"description":"Filter by feature slugs (e.g. free_wifi, pool_outdoor). Values must exist in features.json. Max 50.","type":"array","items":{"minLength":1,"maxLength":80,"type":"string"}},"preferFeatures":{"maxItems":20,"description":"Feature slugs for soft-boost scoring. Hotels matching more features rank higher, but those with fewer still appear. Max 20.","type":"array","items":{"minLength":1,"maxLength":80,"type":"string"}},"filterMode":{"description":"Filter mode for amenity/boolean filters. 'strict' (default): hard AND — only hotels matching ALL filters. 'prefer': soft boost — amenity filters become scoring signals; hotels matching more rank higher, but results never disappear.","default":"strict","anyOf":[{"const":"strict","type":"string"},{"const":"prefer","type":"string"}]},"poiTypesNearby":{"maxItems":30,"description":"Filter by nearby POI types (e.g., ['restaurant', 'beach']). Max 30 values.","type":"array","items":{"minLength":1,"maxLength":100,"type":"string"}},"poiNamesNearby":{"maxItems":30,"description":"Filter by specific nearby POI names (e.g., ['Burj Khalifa', 'Dubai Mall']). Max 30 values.","type":"array","items":{"minLength":1,"maxLength":200,"type":"string"}},"excludeClosed":{"description":"Exclude closed hotels (default: true)","default":true,"type":"boolean"},"providerHid":{"minimum":0,"description":"Filter by provider HID (non-negative integer)","type":"number"},"providerId":{"minLength":1,"maxLength":100,"description":"Filter by provider ID (string)","type":"string"},"sortBy":{"description":"Sort field: relevance, star_rating, name, distance, updated_at","default":"relevance","anyOf":[{"const":"relevance","type":"string"},{"const":"star_rating","type":"string"},{"const":"name","type":"string"},{"const":"distance","type":"string"},{"const":"updated_at","type":"string"}]},"sortOrder":{"description":"Sort order: asc or desc","default":"desc","anyOf":[{"const":"asc","type":"string"},{"const":"desc","type":"string"}]},"includeAggregations":{"description":"Include aggregations/facets in response","default":false,"type":"boolean"},"boostByQuality":{"description":"Enable quality-based re-ranking. Boosts results by rating_global and star_rating. Useful for ranking by hotel quality while maintaining relevance.","default":false,"type":"boolean"},"qualityRatingWeight":{"minimum":0,"maximum":1,"description":"Weight for guest rating (rating_global) in quality scoring (0-1). Default: 0.7. Higher values prioritize guest ratings over star ratings.","default":0.7,"type":"number"},"qualityStarsWeight":{"minimum":0,"maximum":1,"description":"Weight for star rating in quality scoring (0-1). Default: 0.3. Higher values prioritize hotel stars over guest ratings.","default":0.3,"type":"number"},"checkIn":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Check-in date (YYYY-MM-DD). Required for real-time pricing.","examples":["2026-03-01"],"type":"string"},"checkOut":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Check-out date (YYYY-MM-DD). Required for real-time pricing.","examples":["2026-03-05"],"type":"string"},"adults":{"minimum":1,"maximum":10,"default":2,"description":"Number of adults (1-10)","type":"number"},"children":{"minimum":0,"maximum":4,"default":0,"description":"Number of children (0-4)","type":"number"},"childAges":{"description":"Ages of children (0-17 each). Array length should match 'children' count.","examples":[[5,10]],"type":"array","items":{"minimum":0,"maximum":17,"type":"number"}},"rooms":{"minimum":1,"maximum":5,"default":1,"description":"Number of rooms (1-5)","type":"number"},"currency":{"minLength":3,"maxLength":3,"pattern":"^[A-Z]{3}$","default":"AED","description":"Currency code for prices (ISO 4217, 3 letters)","examples":["AED","USD","EUR"],"type":"string"}},"additionalProperties":false}},"text/plain":{"schema":{"type":"object","properties":{"q":{"minLength":0,"maxLength":500,"description":"Search query text (e.g., 'luxury hotels dubai', 'beachfront resort')","examples":["luxury hotels dubai","family friendly resort"],"type":"string"},"query":{"minLength":0,"maxLength":500,"description":"Alias for 'q' parameter","type":"string"},"strategy":{"description":"Search strategy: 'text' (BM25), 'hybrid' (text+vector), 'vector' (semantic). Omit to use route default.","anyOf":[{"const":"hybrid","type":"string"},{"const":"text","type":"string"},{"const":"vector","type":"string"}]},"requestId":{"description":"Request ID from previous search. Use with page > 1 to fetch cached results.","type":"string"},"page":{"minimum":1,"default":1,"description":"Page number. Use with requestId for subsequent pages.","type":"number"},"fetchSize":{"minimum":50,"maximum":300,"default":100,"description":"Number of hotels to fetch and cache (50-300). Higher = more pages cached.","type":"number"},"limit":{"minimum":1,"maximum":100,"default":20,"description":"Results per page (default: 20, ignored when using requestId)","type":"number"},"size":{"minimum":1,"maximum":100,"description":"Alias for 'limit'","type":"number"},"offset":{"minimum":0,"default":0,"description":"Deprecated: Use page instead","type":"number"},"lat":{"minimum":-90,"maximum":90,"description":"Latitude for geo-search (requires lng)","examples":[25.2048],"type":"number"},"lng":{"minimum":-180,"maximum":180,"description":"Longitude for geo-search (requires lat)","examples":[55.2708],"type":"number"},"radius":{"minimum":1,"maximum":500000,"description":"Search radius in meters (1-500000, default: 50000)","default":50000,"examples":[1000,10000,50000],"type":"number"},"city":{"minLength":1,"maxLength":200,"description":"Filter by city name","examples":["Dubai","Abu Dhabi"],"type":"string"},"country":{"minLength":2,"maxLength":2,"pattern":"^[A-Za-z]{2}$","description":"Filter by country code (ISO 3166-1 alpha-2). Must be a country code present in the index (e.g. AE, US, SA).","examples":["AE","SA","US"],"type":"string"},"regionId":{"minimum":0,"description":"Filter by region ID (non-negative integer)","type":"number"},"stars":{"minimum":1,"maximum":5,"description":"Minimum star rating (1-5)","type":"number"},"starRating":{"description":"Star rating filter - single number (1-5) or array of up to 10 values. Matches index values.","examples":[[4,5]],"anyOf":[{"minimum":1,"maximum":5,"type":"number"},{"maxItems":10,"type":"array","items":{"minimum":1,"maximum":5,"type":"number"}}]},"minStarRating":{"minimum":1,"maximum":5,"description":"Minimum star rating for range filter","type":"number"},"maxStarRating":{"minimum":1,"maximum":5,"description":"Maximum star rating for range filter","type":"number"},"kind":{"maxItems":20,"description":"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.","examples":[["HOTEL","RESORT"]],"type":"array","items":{"minLength":1,"maxLength":100,"type":"string"}},"hotelChain":{"maxItems":20,"description":"Hotel chain names (e.g., ['Marriott', 'Hilton']). Max 20 values.","type":"array","items":{"minLength":1,"maxLength":150,"type":"string"}},"familyFriendly":{"description":"Filter for family-friendly hotels (only set to true to filter)","type":"boolean"},"petFriendly":{"description":"Filter for pet-friendly hotels (only set to true to filter)","type":"boolean"},"businessFriendly":{"description":"Filter for business-friendly hotels (only set to true to filter)","type":"boolean"},"wellnessSpa":{"description":"Filter for hotels with spa/wellness facilities (only set to true to filter)","type":"boolean"},"beachfront":{"description":"Filter for beachfront properties (only set to true to filter)","type":"boolean"},"freeWifi":{"description":"Filter for hotels with free WiFi","type":"boolean"},"breakfastIncluded":{"description":"Filter for hotels with breakfast included","type":"boolean"},"petsAllowed":{"description":"Filter for hotels that allow pets","type":"boolean"},"parkingAvailable":{"description":"Filter for hotels with parking available","type":"boolean"},"freeParking":{"description":"Filter for hotels with free parking","type":"boolean"},"shuttleAvailable":{"description":"Filter for hotels with airport shuttle","type":"boolean"},"childrenAllowed":{"description":"Filter for hotels that allow children","type":"boolean"},"internetIncluded":{"description":"Filter for hotels with internet included","type":"boolean"},"parkingIncluded":{"description":"Filter for hotels with parking included in rate","type":"boolean"},"features":{"maxItems":50,"description":"Filter by feature slugs (e.g. free_wifi, pool_outdoor). Values must exist in features.json. Max 50.","type":"array","items":{"minLength":1,"maxLength":80,"type":"string"}},"preferFeatures":{"maxItems":20,"description":"Feature slugs for soft-boost scoring. Hotels matching more features rank higher, but those with fewer still appear. Max 20.","type":"array","items":{"minLength":1,"maxLength":80,"type":"string"}},"filterMode":{"description":"Filter mode for amenity/boolean filters. 'strict' (default): hard AND — only hotels matching ALL filters. 'prefer': soft boost — amenity filters become scoring signals; hotels matching more rank higher, but results never disappear.","default":"strict","anyOf":[{"const":"strict","type":"string"},{"const":"prefer","type":"string"}]},"poiTypesNearby":{"maxItems":30,"description":"Filter by nearby POI types (e.g., ['restaurant', 'beach']). Max 30 values.","type":"array","items":{"minLength":1,"maxLength":100,"type":"string"}},"poiNamesNearby":{"maxItems":30,"description":"Filter by specific nearby POI names (e.g., ['Burj Khalifa', 'Dubai Mall']). Max 30 values.","type":"array","items":{"minLength":1,"maxLength":200,"type":"string"}},"excludeClosed":{"description":"Exclude closed hotels (default: true)","default":true,"type":"boolean"},"providerHid":{"minimum":0,"description":"Filter by provider HID (non-negative integer)","type":"number"},"providerId":{"minLength":1,"maxLength":100,"description":"Filter by provider ID (string)","type":"string"},"sortBy":{"description":"Sort field: relevance, star_rating, name, distance, updated_at","default":"relevance","anyOf":[{"const":"relevance","type":"string"},{"const":"star_rating","type":"string"},{"const":"name","type":"string"},{"const":"distance","type":"string"},{"const":"updated_at","type":"string"}]},"sortOrder":{"description":"Sort order: asc or desc","default":"desc","anyOf":[{"const":"asc","type":"string"},{"const":"desc","type":"string"}]},"includeAggregations":{"description":"Include aggregations/facets in response","default":false,"type":"boolean"},"boostByQuality":{"description":"Enable quality-based re-ranking. Boosts results by rating_global and star_rating. Useful for ranking by hotel quality while maintaining relevance.","default":false,"type":"boolean"},"qualityRatingWeight":{"minimum":0,"maximum":1,"description":"Weight for guest rating (rating_global) in quality scoring (0-1). Default: 0.7. Higher values prioritize guest ratings over star ratings.","default":0.7,"type":"number"},"qualityStarsWeight":{"minimum":0,"maximum":1,"description":"Weight for star rating in quality scoring (0-1). Default: 0.3. Higher values prioritize hotel stars over guest ratings.","default":0.3,"type":"number"},"checkIn":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Check-in date (YYYY-MM-DD). Required for real-time pricing.","examples":["2026-03-01"],"type":"string"},"checkOut":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Check-out date (YYYY-MM-DD). Required for real-time pricing.","examples":["2026-03-05"],"type":"string"},"adults":{"minimum":1,"maximum":10,"default":2,"description":"Number of adults (1-10)","type":"number"},"children":{"minimum":0,"maximum":4,"default":0,"description":"Number of children (0-4)","type":"number"},"childAges":{"description":"Ages of children (0-17 each). Array length should match 'children' count.","examples":[[5,10]],"type":"array","items":{"minimum":0,"maximum":17,"type":"number"}},"rooms":{"minimum":1,"maximum":5,"default":1,"description":"Number of rooms (1-5)","type":"number"},"currency":{"minLength":3,"maxLength":3,"pattern":"^[A-Z]{3}$","default":"AED","description":"Currency code for prices (ISO 4217, 3 letters)","examples":["AED","USD","EUR"],"type":"string"}},"additionalProperties":false}}}}}},"/v2/search/autocomplete":{"get":{"parameters":[{"description":"Search prefix (min 1 character)","schema":{"type":"string","minLength":1},"in":"query","name":"q","required":true},{"description":"Filter by country code (e.g., AE, GB)","schema":{"type":"string"},"in":"query","name":"countryCode","required":false},{"schema":{"type":"number","minimum":1,"maximum":50,"default":10},"in":"query","name":"size","required":false}],"operationId":"getV2SearchAutocomplete","tags":["V2 Search"],"summary":"Autocomplete Hotel Names","description":"\nFast prefix-based hotel name suggestions for typeahead UI.\n\n### Parameters\n- `q`: Search prefix (required, min 1 char)\n- `countryCode`: Optional country filter\n- `size`: Max suggestions (default: 10, max: 50)\n\n### Example\n`GET /v2/search/autocomplete?q=burj&size=5`\n\n### Response\n```json\n{\n  \"success\": true,\n  \"data\": [\n    { \"id\": \"...\", \"name\": \"Burj Al Arab\", \"city\": \"Dubai\" },\n    { \"id\": \"...\", \"name\": \"Burj Khalifa Hotel\", \"city\": \"Dubai\" }\n  ]\n}\n```\n        ","responses":{"200":{}}}},"/v2/search/by-ids":{"post":{"parameters":[],"operationId":"postV2SearchBy-ids","tags":["V2 Search"],"summary":"Get Hotels by IDs","description":"\nRetrieve multiple hotels by their UUIDs in a single request.\n\n### Request Body\n```json\n{\n  \"ids\": [\"uuid-1\", \"uuid-2\", \"uuid-3\"]\n}\n```\n\n### Limits\n- Minimum: 1 ID\n- Maximum: 100 IDs per request\n\n### Response\nReturns hotels in the same order as requested IDs. Missing hotels are omitted.\n        ","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"minItems":1,"maxItems":100,"description":"Array of hotel UUIDs to fetch","type":"array","items":{"type":"string"}}},"required":["ids"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"ids":{"minItems":1,"maxItems":100,"description":"Array of hotel UUIDs to fetch","type":"array","items":{"type":"string"}}},"required":["ids"]}},"text/plain":{"schema":{"type":"object","properties":{"ids":{"minItems":1,"maxItems":100,"description":"Array of hotel UUIDs to fetch","type":"array","items":{"type":"string"}}},"required":["ids"]}}}},"responses":{"200":{}}}},"/v2/search/count":{"post":{"parameters":[],"operationId":"postV2SearchCount","tags":["V2 Search"],"summary":"Count Hotels","description":"\nGet count of hotels matching specified filters without returning results.\n\n### Request Body\n```json\n{\n  \"countryCode\": \"AE\",\n  \"starRating\": [4, 5],\n  \"familyFriendly\": true\n}\n```\n\n### Response\n```json\n{\n  \"success\": true,\n  \"count\": 1234\n}\n```\n        ","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"countryCode":{"description":"Filter by country code","type":"string"},"city":{"description":"Filter by city name","type":"string"},"minStarRating":{"minimum":1,"maximum":5,"type":"number"},"maxStarRating":{"minimum":1,"maximum":5,"type":"number"},"starRating":{"description":"Exact star rating(s)","anyOf":[{"type":"number"},{"type":"array","items":{"type":"number"}}]},"familyFriendly":{"type":"boolean"},"beachfront":{"type":"boolean"},"wellnessSpa":{"type":"boolean"},"kind":{"description":"Property types","type":"array","items":{"type":"string"}}}}},"multipart/form-data":{"schema":{"type":"object","properties":{"countryCode":{"description":"Filter by country code","type":"string"},"city":{"description":"Filter by city name","type":"string"},"minStarRating":{"minimum":1,"maximum":5,"type":"number"},"maxStarRating":{"minimum":1,"maximum":5,"type":"number"},"starRating":{"description":"Exact star rating(s)","anyOf":[{"type":"number"},{"type":"array","items":{"type":"number"}}]},"familyFriendly":{"type":"boolean"},"beachfront":{"type":"boolean"},"wellnessSpa":{"type":"boolean"},"kind":{"description":"Property types","type":"array","items":{"type":"string"}}}}},"text/plain":{"schema":{"type":"object","properties":{"countryCode":{"description":"Filter by country code","type":"string"},"city":{"description":"Filter by city name","type":"string"},"minStarRating":{"minimum":1,"maximum":5,"type":"number"},"maxStarRating":{"minimum":1,"maximum":5,"type":"number"},"starRating":{"description":"Exact star rating(s)","anyOf":[{"type":"number"},{"type":"array","items":{"type":"number"}}]},"familyFriendly":{"type":"boolean"},"beachfront":{"type":"boolean"},"wellnessSpa":{"type":"boolean"},"kind":{"description":"Property types","type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{}}}},"/v2/search/health":{"get":{"operationId":"getV2SearchHealth","tags":["Health"],"summary":"V2 Search Health Check","description":"\nCheck OpenSearch cluster and embedding service connectivity.\n\n### Response\n```json\n{\n  \"status\": \"healthy\",\n  \"opensearch\": { \"connected\": true },\n  \"embedding\": { \"available\": true }\n}\n```\n        ","responses":{"200":{}}}},"/v2/search/similar/{hotelId}":{"get":{"parameters":[{"description":"UUID of the source hotel","schema":{"type":"string"},"in":"path","name":"hotelId","required":true},{"description":"Max results (default 5, max 20)","schema":{"type":"string"},"in":"query","name":"limit","required":false},{"description":"Search radius in km (default 10, max 50)","schema":{"type":"string"},"in":"query","name":"radiusKm","required":false}],"operationId":"getV2SearchSimilarByHotelId","tags":["V2 Search"],"summary":"Find similar hotels","description":"Returns hotels similar to the given hotel using its stored embedding vector + geo-distance filtering. Goes through the full search pipeline (hydration, pricing) so results include media, amenities, etc.","responses":{"200":{}}}},"/admin/opensearch/index":{"get":{"operationId":"getAdminOpensearchIndex","summary":"Get index info, doc count, and field list","tags":["admin"],"responses":{"200":{}}}},"/admin/opensearch/mapping":{"get":{"operationId":"getAdminOpensearchMapping","summary":"Get full index mapping","tags":["admin"],"responses":{"200":{}}}},"/admin/opensearch/sample":{"get":{"parameters":[{"schema":{"type":"string"},"in":"query","name":"size","required":false},{"schema":{"type":"string"},"in":"query","name":"city","required":false},{"schema":{"type":"string"},"in":"query","name":"fields","required":false}],"operationId":"getAdminOpensearchSample","summary":"Get sample documents from index","description":"Query sample documents. Use `fields` to select specific fields (comma-separated), `city` to filter, `size` for count (max 20).","tags":["admin"],"responses":{"200":{}}}},"/admin/opensearch/field/{fieldName}":{"get":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"fieldName","required":true},{"schema":{"type":"string"},"in":"query","name":"size","required":false}],"operationId":"getAdminOpensearchFieldByFieldName","summary":"Check field coverage — how many docs have this field","tags":["admin"],"responses":{"200":{}}}},"/admin/opensearch/query":{"post":{"parameters":[],"operationId":"postAdminOpensearchQuery","summary":"Run raw OpenSearch query","description":"Execute a raw OpenSearch query against the hotel index. Use `fields` to limit returned fields.","tags":["admin"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{},"fields":{"type":"array","items":{"type":"string"}},"size":{"type":"number"}}}},"multipart/form-data":{"schema":{"type":"object","properties":{"query":{},"fields":{"type":"array","items":{"type":"string"}},"size":{"type":"number"}}}},"text/plain":{"schema":{"type":"object","properties":{"query":{},"fields":{"type":"array","items":{"type":"string"}},"size":{"type":"number"}}}}}},"responses":{"200":{}}}},"/":{"get":{"operationId":"getIndex","tags":["Health"],"summary":"Service Info","description":"Get service information and available endpoints.","responses":{"200":{}}}},"/health":{"get":{"operationId":"getHealth","tags":["Health"],"summary":"Health Check","description":"\nCheck service health and dependency status.\n\n### Response\n```json\n{\n  \"status\": \"healthy\",\n  \"service\": \"hotel-search-discovery-engine\",\n  \"version\": \"2.0.0\",\n  \"timestamp\": \"2026-01-29T12:00:00Z\",\n  \"dependencies\": {\n    \"opensearch\": \"connected\",\n    \"postgresql\": \"connected\",\n    \"redis\": \"connected\",\n    \"kafka\": { ... }\n  }\n}\n```\n        ","responses":{"200":{}}}}},"components":{"schemas":{}}}