{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-docs/stays/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition","img"]},"type":"markdown"},"seo":{"title":"Tutorial: SearchComplete API Object Model","description":"Create AI-native travel products with Travelport's powerful, flexible APIs.","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"tutorial-searchcomplete-api-object-model","__idx":0},"children":["Tutorial: SearchComplete API Object Model"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This document provides general information about the Stays API. For the most current endpoints and examples, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/getting-started/authentication"},"children":["Authentication"]},", ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/stays/general/stays-api-endpoints"},"children":["Stays Endpoints"]},", and the API References."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"introduction","__idx":1},"children":["Introduction"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This tutorial explains the object model of the Hotel Search Complete API. If you're familiar with hotel search APIs and JSON/REST basics, this guide will help you understand how to structure requests and navigate responses."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["What You'll Learn:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["How to structure a search request"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Understanding the response object hierarchy"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Key objects and their relationships"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Practical examples for common use cases"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Prerequisites: Basic understanding of REST APIs and JSON. Familiarity with hotel booking concepts (properties, rates, rooms, cancellation policies)."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"api-overview","__idx":2},"children":["API Overview"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"endpoint","__idx":3},"children":["Endpoint"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["POST /search/searchcomplete"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This single endpoint handles hotel searches and returns comprehensive results including properties, availability, rates, and policies."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["GET /search/searchcomplete/{identifier}"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Retrieves additional pages when search results exceed one page. The identifier comes from the pagination object in the initial response."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"authentication","__idx":4},"children":["Authentication"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The API uses OAuth 2.0 Bearer tokens. Include your token in the Authorization header:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"xml","header":{"controls":{"copy":{}}},"source":"Authorization: Bearer YOUR_ACCESS_TOKEN\n","lang":"xml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"important-headers","__idx":5},"children":["Important Headers"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"class":"doc-table md","className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Header"},"children":["Header"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required?"},"children":["Required?"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Purpose"},"children":["Purpose"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["XAUTH_TRAVELPORT_ACCESSGROUP"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Your access group (equivalent to PCC)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["TVP-Trace-Id"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Request tracking identifier"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["TVP-Cache-Control"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Control caching behavior (e.g., \"no-cache\")"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["TVP-Enable-Error-Details"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Get detailed error messages"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"request-object-model","__idx":6},"children":["Request Object Model"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"hotelsearchrequest-structure","__idx":7},"children":["HotelSearchRequest Structure"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The request is organized into logical groups:"]},{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/assets/tutorial_x1.0cd4503992de38c7b6e91cca9293b6815cecfb64eb41e03c053e9c14004bb02d.3a4aeaca.jpg","withLightbox":false},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"key-request-objects","__idx":8},"children":["Key Request Objects"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["stayDetails (Required)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Purpose: Defines when and for whom you're searching."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Required Fields:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["checkInDateLocal: Check-in date (YYYY-MM-DD format)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["checkOutDateLocal: Check-out date (YYYY-MM-DD format)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["guests: Number and ages of guests"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"{\n \"stayDetails\": {\n  \"checkInDateLocal\": \"2025-03-15\",\n  \"checkOutDateLocal\": \"2025-03-17\",\n  \"guests\": {\n   \"numberOfAdults\": 2,\n   \"numberOfChildren\": 1,\n   \"childAges\": [\n    5\n   ]\n  },\n  \"rooms\": 1\n }\n}\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["propertyFilter (Required)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Purpose: Defines which properties to search for and what data to return."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Search By Location:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"{\n \"propertyFilter\": {\n  \"location\": {\n   \"city\": \"San Francisco\",\n   \"countryCode\": \"US\"\n  },\n  \"returnOnlyAvailableProperties\": true,\n  \"chainCodes\": [\n   \"HI\",\n   \"MA\"\n  ],\n  \"imageSize\": \"LARGE\",\n  \"returnAllImageURLs\": true\n }\n}\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Search By Property IDs"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"{\n \"propertyFilter\": {\n  \"propertyKeys\": [\n   \"TVPT-12345\",\n   \"TVPT-67890\"\n  ]\n }\n}\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Common propertyFilter Options:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["returnOnlyAvailableProperties: Only return properties with availability"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["chainCodes: Filter by hotel chains (e.g., [\"HI\", \"MA\"])"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["categories: Filter by rate categories (e.g., [\"CORPORATE\", \"GOVERNMENT\"])"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["hotelNameContains: Partial name match"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["imageSize: Control image dimensions (SMALL, MEDIUM, LARGE)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["returnRateSummaryInfo: Include rate summary in response"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["roomFilter (Optional)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Purpose: Filter results by room characteristics. Only rates matching these criteria will be returned."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"{\n \"roomFilter\": {\n  \"nonSmoking\": true,\n  \"accessible\": false,\n  \"bedConfiguration\": {\n   \"preferredBedTypes\": [\n    \"KING\",\n    \"QUEEN\"\n   ]\n  },\n  \"amenityCodes\": [\n   \"WIFI\",\n   \"MINIBAR\"\n  ]\n }\n}\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["rateFilter (Optional)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Purpose: Filter results by rate characteristics."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"{\n \"rateFilter\": {\n  \"rateFlags\": {\n   \"refundable\": true,\n   \"breakfastIncluded\": true\n  }\n }\n}\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"response-object-model","__idx":9},"children":["Response Object Model"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"hotelsearchresponse-structure","__idx":10},"children":["HotelSearchResponse Structure"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The response follows this hierarchy:"]},{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/assets/tutorial_x7.d9bc3f6cfc8e384a6584217d889f495fe75851671bfdc4f3ebae4758ea93e826.3a4aeaca.jpg","withLightbox":false},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"key-response-objects","__idx":11},"children":["Key Response Objects"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["PropertyItem (Hotel Object)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each hotel in the hotels[] array contains:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["propertyKey: Unique identifier (use this for booking)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["propertyInfo: Hotel details (name, rating, description)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["location: Address and coordinates"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["amenities: Property amenities (pool, gym, parking, etc.)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["images: Property images"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["rates: Array of available rates (this is what you need for pricing)"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Rate Object"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each rate object contains everything you need to display and book:"]},{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/assets/tutorial_x8.1d417620e68eb855502bb9f3276830d06c3c3b182103466db5ca08dc83b9668e.3a4aeaca.jpg","withLightbox":false},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Important:"]}," The rateRules object contains all cancellation and payment policies. You MUST display this information to users before booking."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"practical-examples","__idx":12},"children":["Practical Examples"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example 1: Basic Location Search Request"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"{\n \"stayDetails\": {\n  \"checkInDateLocal\": \"2025-04-10\",\n  \"checkOutDateLocal\": \"2025-04-12\",\n  \"guests\": {\n   \"numberOfAdults\": 2,\n   \"numberOfChildren\": 0\n  }\n },\n \"propertyFilter\": {\n  \"location\": {\n   \"city\": \"Boston\",\n   \"stateProvince\": \"MA\",\n   \"countryCode\": \"US\"\n  },\n  \"returnOnlyAvailableProperties\": true\n },\n \"requestedCurrency\": \"USD\"\n}\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example 2: Search with Room and Rate Filters Request"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"{\n \"stayDetails\": {\n  \"checkInDateLocal\": \"2025-05-15\",\n  \"checkOutDateLocal\": \"2025-05-17\",\n  \"guests\": {\n   \"numberOfAdults\": 2,\n   \"numberOfChildren\": 0\n  }\n },\n \"propertyFilter\": {\n  \"location\": {\n   \"coordinates\": {\n    \"latitude\": 37.7749,\n    \"longitude\": -122.4194\n   },\n   \"radiusMiles\": 5\n  },\n  \"chainCodes\": [\n   \"HI\"\n  ],\n  \"returnOnlyAvailableProperties\": true,\n  \"categories\": [\n   \"CORPORATE\"\n  ]\n },\n \"roomFilter\": {\n  \"nonSmoking\": true,\n  \"bedConfiguration\": {\n   \"preferredBedTypes\": [\n    \"KING\"\n   ]\n  }\n },\n \"rateFilter\": {\n  \"rateFlags\": {\n   \"refundable\": true\n  }\n },\n \"requestedCurrency\": \"USD\"\n}\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"navigating-the-response","__idx":13},"children":["Navigating the Response"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"accessing-hotel-data","__idx":14},"children":["Accessing Hotel Data"]},{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/assets/tutorial_x11.f95bee488829c5f0bce8619761377718b86d3179821a95ef9c82c3eceb2f7fb1.3a4aeaca.jpg","withLightbox":false},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"finding-the-lowest-rate","__idx":15},"children":["Finding the Lowest Rate"]},{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/assets/tutorial_x12.35decbc22270dd2a07bb99ea4675a2f9347c55db33978572a40b15d27187e623.3a4aeaca.jpg","withLightbox":false},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"common-patterns-and-tips","__idx":16},"children":["Common Patterns and Tips"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"handling-pagination","__idx":17},"children":["Handling Pagination"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If your search returns many results, use pagination:"]},{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/assets/tutorial_x13.aa1588b4c16dd8b6d2dbcd86a47808c8d39c5bc0aaa16c5df28f6da42497a06d.3a4aeaca.jpg","withLightbox":false},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"using-rate-keys-for-booking","__idx":18},"children":["Using Rate Keys for Booking"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When a user selects a rate, save both the propertyKey and rateKey:"]},{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/assets/tutorial_x14.5945612a3ef4e85935510410dd402587b94ec9fabcb1b826a5696d3a98a12385.3a4aeaca.jpg","withLightbox":false},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"checking-for-refundability","__idx":19},"children":["Checking for Refundability"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Always check the cancellation policy before displaying rates:"]},{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/assets/tutorial_x15.a36597931ed399b54c48e81b1fb3c5aab4af13e8162eb3b160545c72f7abcded.3a4aeaca.jpg","withLightbox":false},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"using-cache-control","__idx":20},"children":["Using Cache Control"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Control whether you want cached or fresh results:"]},{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/assets/tutorial_x16.37e57917ca430d3757c78114100dfae2e268e749806f914618a867966f91021f.3a4aeaca.jpg","withLightbox":false},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"quick-reference","__idx":21},"children":["Quick Reference"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Essential Response Paths"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"class":"doc-table md","className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"To Get..."},"children":["To Get..."]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Navigate To..."},"children":["Navigate To..."]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["List of hotels"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["response.hotelsResponse.hotels[]"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Hotel name"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["hotel.propertyInfo.propertyName"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Hotel address"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["hotel.location.address"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Star rating"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["hotel.propertyInfo.rating"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Available rates"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["hotel.rates[]"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Rate price"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["rate.pricing.total.value"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Room type"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["rate.roomType.name"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Cancellation policy"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["rate.rateRules.cancelPolicy"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Deposit requirements"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["rate.rateRules.depositPolicy"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Property ID (for booking)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["hotel.propertyKey"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Rate ID (for booking)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["rate.rateKey"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"common-mistakes-to-avoid","__idx":22},"children":["Common Mistakes to Avoid"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Not checking rateRules: Always check rateRules.cancelPolicy and rateRules.depositPolicy before displaying rates to users. Showing a rate without cancellation details can lead to customer complaints."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Forgetting to filter by availability: Set returnOnlyAvailableProperties: true in propertyFilter unless you want to show properties without available rooms."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Not saving propertyKey and rateKey: You need both identifiers when making a booking. Save them when the user selects a rate."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Ignoring the warnings array: Check response.warnings for non-fatal issues that might affect the results (e.g., some properties didn't respond in time)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Not handling pagination: Large searches may return hundreds of properties. Check response.pagination and implement pagination if needed."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Using cached data for final booking: Before booking, make a fresh search with TVP-Cache-Control: no-cache to get current pricing."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"summary","__idx":23},"children":["Summary"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Key Takeaways:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Request Structure: stayDetails (when/who) + propertyFilter (where) + optional filters (what kind)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Response Structure: hotels[] contains properties, each with rates[], each rate has pricing and rateRules"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["For Booking: Save propertyKey and rateKey from selected rate"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Always Display: Rate rules (cancellation and deposit policies) to users"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Cache Control: Use TVP-Cache-Control header to control whether you get cached or fresh data"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Pagination: Check response.pagination for additional pages of results"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Next Steps:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Review the complete API documentation for all available fields and options"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Test with your authentication credentials in a development environment"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Implement error handling for network issues and API errors"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Build your booking flow using the propertyKey and rateKey from search results"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Contact your Travelport account manager for additional support"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"mailto:john.callaway@travelport.com?subject=JSON%20API%20Hotel%20Feedback"},"children":["Provide feedback about this documentation"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["This link does not provide Help Desk support. If you need immediate assistance with Travelport APIs, please create a support request in ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://my.travelport.com/"},"children":["MyTravelport"]}," or use your normal support path."]}]}]},"headings":[{"value":"Tutorial: SearchComplete API Object Model","id":"tutorial-searchcomplete-api-object-model","depth":1},{"value":"Introduction","id":"introduction","depth":2},{"value":"API Overview","id":"api-overview","depth":2},{"value":"Endpoint","id":"endpoint","depth":3},{"value":"Authentication","id":"authentication","depth":3},{"value":"Important Headers","id":"important-headers","depth":3},{"value":"Request Object Model","id":"request-object-model","depth":2},{"value":"HotelSearchRequest Structure","id":"hotelsearchrequest-structure","depth":3},{"value":"Key Request Objects","id":"key-request-objects","depth":3},{"value":"Response Object Model","id":"response-object-model","depth":2},{"value":"HotelSearchResponse Structure","id":"hotelsearchresponse-structure","depth":3},{"value":"Key Response Objects","id":"key-response-objects","depth":3},{"value":"Practical Examples","id":"practical-examples","depth":3},{"value":"Navigating the Response","id":"navigating-the-response","depth":2},{"value":"Accessing Hotel Data","id":"accessing-hotel-data","depth":3},{"value":"Finding the Lowest Rate","id":"finding-the-lowest-rate","depth":3},{"value":"Common Patterns and Tips","id":"common-patterns-and-tips","depth":2},{"value":"Handling Pagination","id":"handling-pagination","depth":3},{"value":"Using Rate Keys for Booking","id":"using-rate-keys-for-booking","depth":3},{"value":"Checking for Refundability","id":"checking-for-refundability","depth":3},{"value":"Using Cache Control","id":"using-cache-control","depth":3},{"value":"Quick Reference","id":"quick-reference","depth":2},{"value":"Common Mistakes to Avoid","id":"common-mistakes-to-avoid","depth":2},{"value":"Summary","id":"summary","depth":2}],"frontmatter":{"seo":{"title":"Tutorial: SearchComplete API Object Model"}},"lastModified":"2026-05-27T15:34:23.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/stays/tutorials/search-complete-api-object-model","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}