--- title: "Flexible-date price matrix (one-way or round-trip)" method: POST path: "/flights/rates/matrix" tags: ["Flight Search"] --- # Flexible-date price matrix (one-way or round-trip) `POST /flights/rates/matrix` ## Request - Base URL: `https://api.liteapi.travel/v3.0` - URL: `https://api.liteapi.travel/v3.0/flights/rates/matrix` - Auth: API key in header `X-API-Key` ## Overview Search the cheapest fare for each departure (and, on round-trips, return) date combination across a grid of nearby dates — `±flexDays` around the dates in your request. Accepts the same `legs`-based body as `POST /flights/rates` plus optional `flexDays` (1–3, default 3). **Supported:** one-way (1 leg) or round-trip (2 legs) only. Multi-city (3+ legs) is not supported. **Date limit:** each leg `date` must not be more than 11 months from today (same as `POST /flights/rates`). **Not supported:** top-level `origin`, `destination`, `departureDate`, or `returnDate` — use `legs` only. ## Access Requires Flights API access and matrix enablement on your account. Matrix search is not enabled by default — contact the LiteAPI support team to request access. ## When to Use - **Flexible-date calendars** — price heatmap when the traveller can shift dates - **Cheap-date discovery** — find the lowest fare in a ±N day window before a full `/flights/rates` search - **Round-trip date pairing** — compare outbound × return combinations on one grid - **Progressive UI** — stream cells over SSE as each underlying search completes ## What You Get - **`cells`** — one entry per valid date combination, sorted by `(outboundOffset, returnOffset)` - **`cheapest`** — globally lowest-priced cell (null when nothing was priced) - **`currency`** — currency of the global cheapest cell - **`baseOutboundDate`** / **`baseReturnDate`** — the originally requested dates - **`flexDays`**, **`roundTrip`** — grid metadata - Per-cell **`price`**, **`currency`**, date offsets, and whether the underlying search was **`cached`** or **`success`** - **Margined prices** — cell `price`, `cheapest`, and `currency` include the authenticated user's rate-search margin (same as `/flights/rates`) ## Key Features - Probes `±flexDays` (1–3) around requested departure and return dates - Each underlying date pair uses normal provider caching — a later `POST /flights/rates` for a matrix date is served from warm cache - **SSE:** send header `Accept: text/event-stream` for incremental events: `matrix-start` (grid skeleton), `matrix-chunk` (one priced cell), `matrix-complete` (full sorted grid + cheapest) - Same global `filters`, `sort`, and `options` as `/flights/rates` where applicable ## Quick Start **Required:** `legs` (1 leg for one-way or 2 for round-trip, each with `origin`, `destination`, `date`), `adults` (≥ 1), `currency` **Optional:** `flexDays` (1–3, default 3), `country`, passenger counts, `filters`, `sort` **Round-trip:** two legs — outbound then return with optional `direction` `OUTBOUND` / `INBOUND`. **One-way:** one leg. After choosing a date pair from the matrix, call `POST /flights/rates` with `legs` set to those dates for full offer details. ## Request body - object - `legs` object[], required: One leg (one-way) or two legs (round-trip). Multi-city is not supported. - `origin` string, required: Origin airport or city IATA code for this leg. - `destination` string, required: Destination airport or city IATA code for this leg. - `date` string, date, required: Departure date for this leg (YYYY-MM-DD). Must not be more than 11 months from today. - `direction` 'OUTBOUND' | 'INBOUND': Leg direction (optional; defaults to OUTBOUND on the provider). - `adults` integer, required: Number of adult passengers (≥ 1). - `children` integer: Number of child passengers (ages 2-11). - `infants` integer: Number of infant passengers (under 2). - `currency` string, required: ISO 4217 currency for point of sale and displayed prices. - `country` string: ISO country code for point of sale - `margin` object: Optional per-request markup override. Only `rateSearch` affects the matrix (cell prices are fares); other categories are accepted for parity with `/flights/rates` but have no effect here. Only honoured when flight margin editing is enabled for your account; ignored otherwise. - `rateSearch` number: Fare markup percentage applied to matrix cell prices instead of your account-level flight markup. - `flexDays` integer: Days before/after requested dates to probe ## Response `200` Price matrix - FlightMatrixResponse: Response for POST /flights/rates/matrix. - `data` FlightMatrixData[], required: Matrix result sets (one element for this endpoint). - `baseOutboundDate` string, date: The originally requested departure date (YYYY-MM-DD). - `baseReturnDate` string, date, nullable: The originally requested return date. Null for one-way searches. - `cells` FlightMatrixCell[]: One cell per valid date combination, sorted by (outboundOffset, returnOffset). - `outboundDate` string, date: Departure date for this cell (YYYY-MM-DD). - `outboundOffset` integer: Days from the requested departure date (-flexDays..+flexDays). - `returnDate` string, date, nullable: Return date for this cell (YYYY-MM-DD). Null for one-way searches. - `returnOffset` integer, nullable: Days from the requested return date (-flexDays..+flexDays). Null for one-way searches. - `price` number, float, nullable: Cheapest display total for this date combination (includes rate-search margin). Null when no priced offer was found. - `currency` string, nullable: ISO 4217 currency of the cell price. Null when no priced offer was found. - `success` boolean: True when the underlying search returned at least one priced offer for this combination. - `cached` boolean: True when the underlying search was served from cache. - `cheapest` FlightMatrixCell: Cheapest-price summary for a single departure/return date combination. - `outboundDate` string, date: Departure date for this cell (YYYY-MM-DD). - `outboundOffset` integer: Days from the requested departure date (-flexDays..+flexDays). - `returnDate` string, date, nullable: Return date for this cell (YYYY-MM-DD). Null for one-way searches. - `returnOffset` integer, nullable: Days from the requested return date (-flexDays..+flexDays). Null for one-way searches. - `price` number, float, nullable: Cheapest display total for this date combination (includes rate-search margin). Null when no priced offer was found. - `currency` string, nullable: ISO 4217 currency of the cell price. Null when no priced offer was found. - `success` boolean: True when the underlying search returned at least one priced offer for this combination. - `cached` boolean: True when the underlying search was served from cache. - `currency` string, nullable: ISO 4217 currency of the global cheapest cell. Null when nothing was priced. - `flexDays` integer: Effective flexibility window applied (1-3). - `roundTrip` boolean: True when the request was a round-trip (return dates vary across columns). - `totalCells` integer, nullable: Total number of date combinations in the grid. Present on matrix-start SSE events; omitted from the non-streaming JSON response. ## Other responses - `400`: Bad request — missing or invalid matrix search parameters - `401`: Unauthorized - `403`: Forbidden — matrix access not enabled for this account - `500`: Internal server error --- [API](https://skmtc.dev/liteapi/apis/api-flights.md) - [All operations](https://skmtc.dev/liteapi/apis/api-flights/llms.txt) - [OpenAPI document](https://skmtc.dev/liteapi/apis/api-flights/revisions/7ccb4b3a8bde?raw)