> ## Documentation Index > Fetch the complete documentation index at: https://docs.pageonetravel.com/llms.txt > Use this file to discover all available pages before exploring further. # Search API > Get available accommodations and priced options. ## Endpoint ```http theme={null} POST /api/search ``` Alternative TGX-shaped endpoint: ```http theme={null} POST /api/search/tgx ``` ## Authentication * Required header: `api-key: ` * Required body field: `settings.access.code` ## Headers | Header | Required | Description | | ----------------- | -------- | --------------------------------------- | | `Content-Type` | Yes | `application/json` | | `api-key` | Yes | Partner API key | | `connection-code` | Optional | Auto-filled from `settings.access.code` | | `session-id` | Optional | Auto-generated if missing | ## Request Body ### Top-level fields | Field | Type | Required | Notes | | --------------------- | ------- | -------- | ---------------------------------- | | `searchCriteria` | object | Yes | Search input details | | `settings` | object | Yes | Connection access + business rules | | `filters` | object | No | Optional filtering controls | | `distributionContext` | object | No | Optional distribution metadata | | `listing` | boolean | No | Default `false` | | `requestFromPortal` | boolean | No | Default `false` | ### `searchCriteria` fields | Field | Type | Required | Notes | | ------------------------------------ | --------- | ----------- | ---------------------------------------------------------------------------- | | `destinations.accommodations[]` | array | Conditional | Required only when selector is `destinations.accommodations`; size `1..1000` | | `destinations.accommodations[].type` | string | No | Default `Hotel` | | `destinations.accommodations[].code` | string | Conditional | Required when selector is `destinations.accommodations` | | `occupancies[]` | array | Yes | Room occupancies | | `occupancies[].occupancyId` | number | No | Optional reference ID | | `occupancies[].paxes[]` | array | Yes | Guests in occupancy | | `occupancies[].paxes[].age` | number | Yes | Guest age | | `occupancies[].paxes[].nationality` | string | No | ISO country code | | `geo.lat` | number | Conditional | Required only when selector is `geo` | | `geo.lng` | number | Conditional | Required only when selector is `geo` | | `geo.radiusKm` | number | No | Optional for `geo` selector, range `0.1..60`, default `20` | | `geo.limit` | number | No | Optional for `geo` selector, range `1..1000`, default `1000` | | `accommodationName` | string | Conditional | Required only when selector is `accommodationName`; length `2..200` | | `markets[]` | string\[] | No | Market codes | | `checkIn` | string | Yes | `YYYY-MM-DD` | | `checkOut` | string | Yes | `YYYY-MM-DD` | | `language` | string | No | Language code | | `currency` | string | No | Currency code | | `nationality` | string | No | Nationality code | ### Selector rule (mutually exclusive) Exactly one selector must be present in `searchCriteria`: * `destinations.accommodations[]` * `geo.lat` + `geo.lng` (with optional `geo.radiusKm`, `geo.limit`) * `accommodationName` If no selector is provided, or multiple selectors are combined, the API returns `400`. ### `settings` fields | Field | Type | Required | Notes | | -------------------------------- | ------- | -------- | ----------------------------------------------------------- | | `access.code` | number | Yes | Partner connection code | | `access.user` | string | No | Reserved | | `access.password` | string | No | Reserved | | `access.apiKey` | string | No | Reserved | | `access.urls` | object | No | Reserved (`book/search/quote/generic`) | | `access.parameters` | object | No | Reserved key-value map | | `businessRules.optionsQuota` | number | No | `>=1`; per-accommodation cap, only applied for `DEFAULT` | | `businessRules.businessRuleType` | string | No | `CHEAPEST` or `DEFAULT`; defaults to `DEFAULT` when omitted | | `supplier` | string | No | Reserved | | `platform` | string | No | Reserved | | `client` | string | No | Reserved | | `timeout` | string | No | Upstream timeout hint | | `includeProviderTransactions` | boolean | No | Reserved | ### `filters` fields | Field | Type | Required | Notes | | --------------------------------------------- | --------- | -------- | ------------------------------------- | | `status.includes[]` | string\[] | No | Include statuses | | `status.excludes[]` | string\[] | No | Exclude statuses | | `rateRuleFilter.includes[]` | string\[] | No | Include rate rules | | `rateRuleFilter.excludes[]` | string\[] | No | Exclude rate rules | | `rateRuleFilter.includeEmptyRateRulesOptions` | boolean | No | Include options with empty rate rules | ### `distributionContext` fields (top-level) | Field | Type | Required | Notes | | ---------------------------- | --------- | -------- | ---------------------------------------- | | `customer` | object | No | Device/user/location context | | `salesChannel` | string | No | `WEB` / `APP` / `OFFLINE` | | `distributionMode` | string | No | `CUSTOMER` / `REDISTRIBUTION` | | `supportedVisibilityTypes[]` | string\[] | No | `PUBLIC` / `PACKAGE` / `OPAQUE_PROPERTY` | Full shared object details: `/api-reference/models/common-objects`. ## Example Request ```json theme={null} { "searchCriteria": { "destinations": { "accommodations": [ { "type": "Hotel", "code": "6475503709317edd78e1dbd9" } ] }, "occupancies": [ { "occupancyId": 1, "paxes": [ { "age": 30, "nationality": "US" }, { "age": 28, "nationality": "US" } ] } ], "checkIn": "2026-03-01", "checkOut": "2026-03-03", "language": "EN", "currency": "USD", "nationality": "US" }, "settings": { "access": { "code": 10001 }, "businessRules": { "businessRuleType": "DEFAULT", "optionsQuota": 10 } } } ``` ### Example Request (Geo selector) ```json theme={null} { "searchCriteria": { "geo": { "lat": 40.7128, "lng": -74.006, "radiusKm": 20, "limit": 1000 }, "occupancies": [ { "occupancyId": 1, "paxes": [ { "age": 30 } ] } ], "checkIn": "2026-03-01", "checkOut": "2026-03-03", "language": "EN", "currency": "USD" }, "settings": { "access": { "code": 10001 } } } ``` ### Example Request (Accommodation name selector) ```json theme={null} { "searchCriteria": { "accommodationName": "Hilton Times Square", "occupancies": [ { "occupancyId": 1, "paxes": [ { "age": 30 } ] } ], "checkIn": "2026-03-01", "checkOut": "2026-03-03", "language": "EN", "currency": "USD" }, "settings": { "access": { "code": 10001 } } } ``` ## Success Response `POST /api/search` returns flattened options per accommodation (current default implementation): ```json theme={null} { "data": { "accommodations": [ { "accommodationCode": "6475503709317edd78e1dbd9", "accommodationName": "Comfort Inn & Suites", "accommodationType": "Hotel", "location": { "country": "US", "longitude": -81.90058, "latitude": 41.41568 }, "options": [ { "id": "177f8ec3-6d98-4a2f-8567-5c45eddb0ead", "boardCode": "RO", "boardName": "Room Only", "isRefundable": true, "rate": { "currency": "USD", "baseRate": 120.0, "taxesAndFees": 18.5, "chargeTotal": 138.5 }, "cancelPolicy": { "refundable": true, "cancelPenalties": [ { "penaltyType": "IMPORT", "currency": "USD", "deadline": "2026-02-28T23:59:59Z", "value": 50 } ] }, "rooms": [ { "occupancyRefId": 1, "code": "DBL", "description": "Double Room", "rate": { "currency": "USD", "baseRate": 120.0, "taxesAndFees": 18.5, "chargeTotal": 138.5 } } ] } ] } ], "requestId": "req_search_64f5..._1739260000000_83915", "responseTime": 132 }, "message": "success" } ``` ## Response Field Map | Field | Type | Notes | | ---------------------------------------------- | ------- | --------------------------------------- | | `data.accommodations[]` | array | Accommodation list | | `data.accommodations[].accommodationCode` | string | Accommodation ID | | `data.accommodations[].accommodationName` | string | Accommodation name | | `data.accommodations[].accommodationType` | string | Usually `Hotel` | | `data.accommodations[].location` | object | Country/geo info | | `data.accommodations[].options[]` | array | Available options | | `data.accommodations[].options[].id` | string | Option reference (`optionId`) for quote | | `data.accommodations[].options[].boardCode` | string | Board code | | `data.accommodations[].options[].boardName` | string | Board label | | `data.accommodations[].options[].isRefundable` | boolean | Refundability flag | | `data.accommodations[].options[].rate` | object | Option-level price block | | `data.accommodations[].options[].cancelPolicy` | object | Cancellation policy | | `data.accommodations[].options[].rooms[]` | array | Room-level details | | `data.requestId` | string | Trace ID | | `data.responseTime` | number | Milliseconds | | `message` | string | Always `success` for success | ## Rate Limit Headers `/search` includes: * `X-RateLimit-Limit` * `X-RateLimit-Remaining` * `X-RateLimit-Reset` * `Retry-After` when limited (`429`) ## Business Rules Behavior `businessRules` are applied per accommodation: * `businessRuleType = CHEAPEST`: returns 1 cheapest option per accommodation; `optionsQuota` is ignored. * `businessRuleType = DEFAULT`: returns all options per accommodation; if `optionsQuota` is provided, returns cheapest N options per accommodation. * `businessRuleType` omitted: treated as `DEFAULT`. Behavior matrix: | Input | Effect | | ---------------------------------------------- | ----------------------------------------------------------------------- | | `businessRuleType=CHEAPEST`, `optionsQuota=10` | Same as CHEAPEST only: 1 option per accommodation | | `businessRuleType=CHEAPEST` only | 1 cheapest option per accommodation | | `businessRuleType=DEFAULT`, `optionsQuota=10` | Up to 10 cheapest options per accommodation | | `businessRuleType=DEFAULT` only | All options per accommodation | | `optionsQuota=10` only | Treated as DEFAULT + quota, up to 10 cheapest options per accommodation | | both omitted | Treated as DEFAULT without quota | ## Common Errors * `400 Exactly one selector is required: destinations.accommodations, geo(lat/lng), or accommodationName` * `400 Invalid connection code` * `400 No connection` * `401 API key is required` * `401 Invalid API key` * `401 Connection not found` * `401 Connection access denied` * `429 Rate limit exceeded`