Technology
The partner search contract, in full. Endpoints, request and response shape, error semantics, how price identity works and what happens when a quote expires. If something here doesn't fit your integration, we change it — see what partners have asked us for on the distribution page.
Endpoints
Search
Live search. Returns a synchronous JSON array of bookable options — no polling, no session to open first. Cold routes can take up to 15 seconds; repeat queries on the same route return in tens of milliseconds.
Routes
Route directory: origin and destination IATA pairs in both orientations, computed live from current inventory rather than served from a static list. No authentication — you can pull it before we've issued you a key.
Statistics
Order reconciliation: statuses, amounts, your marker and market echoed back. XML by default, JSON via the Accept header.
Search request
Query-string parameters of GET /api/search/external:
| Parameter | Meaning |
|---|---|
| password | Your partner API key |
| from / to | IATA city or airport code |
| date1 | Departure date, YYYY-MM-DD |
| date2 | Return date for round trips, optional |
| cabin | Y (economy) or C (business) |
| adults | 1-9, default 1 |
| children | Accepted and priced as adults, default 0 |
| infants | Default 0, must not exceed adults |
| currency | Optional: usd, eur or gel |
| locale | Optional deeplink locale: en, ru or ka |
| market | Optional, stored on the resulting order and echoed in statistics |
Response
The response body is a bare JSON array of options. Nesting is option → segment[] → flight[]: a segment is one direction of travel, a flight is one leg inside it.
[
{
"price": 812,
"currency": "usd",
"url": "https://gtavia.com/en/booking/5f0c2f6a-1b7e-5c2d-9a44-83f0e6c21d7b?currency=usd",
"seats": 4,
"segment": [
{
"flight": [
{
"operatingCarrier": "KC",
"marketingCarrier": "KC",
"number": "927",
"departure": "ALA",
"departureDate": "2026-10-12",
"departureTime": "07:40",
"arrival": "AYT",
"arrivalDate": "2026-10-12",
"arrivalTime": "10:55",
"cabin": "Y",
"isCharter": true,
"isBus": false,
"isTrain": false,
"baggage": "1PC20",
"handbags": "1PC5"
}
]
}
]
}
]- price — integer, the total for all passengers in whole units of the requested currency. No minor units, no per-passenger breakdown.
- currency — lowercase, one of usd, eur, gel.
- url — the ready deeplink. The UUID in it is the quote identity; append your marker and market to the query string and we store both against the order.
- seats — how many seats are still bookable on this option, capped at 9. Every option we return is bookable for the passenger count you asked for.
- operatingCarrier / marketingCarrier — IATA codes. On charter blocks they're usually the same; when they differ, the operating carrier is what the passenger boards.
- departureDate / departureTime — local time at the departure airport, ISO date and 24-hour time as separate strings.
- cabin — Y or C.
- isCharter — always true. Every option in this feed is a tour operator block.
- isBus / isTrain — always false. Reserved fields, safe to ignore.
- baggage / handbags — piece-and-weight notation. 1PC20 is one piece up to 20 kg.
- technicalStops — a stop where passengers stay on the aircraft. A stop where they change aircraft appears instead as two entries in flight[].
Behaviour
Errors
Validation problems never produce an error status. An unresolvable city, an unparseable date or an impossible passenger set returns HTTP 200 with an empty array, so a bad query on your side never registers as an outage on ours. The only failure status is HTTP 401 on an unknown API key. Treat anything else as an empty result.
Price identity
Each option's identifier is derived from its final price in all currencies, the passenger composition and your partner account. The price behind an identifier cannot change, because the identifier is computed from it. Any price movement produces a new identifier, and the original option keeps serving and booking at the price it was issued with.
Booking window
60 minutes from the moment the option was priced. An option handed to a traveller always has at least 45 minutes left, because we never serve a cached quote older than 15 minutes. The quote refreshes silently before expiry; if the price has moved by then, the traveller sees both amounts and must confirm before payment unlocks.
Deeplink
https://gtavia.com/{locale}/booking/{variantId}?currency={code}Locales: en, ru, ka. The variantId is the price identity above. Your marker and market parameters are carried through the booking flow, stored on the order and returned in /partners/statistics.
Other channels
Hourly price feed
For feed-based consumers we export the full sellable inventory every hour as CSV over SFTP: routes, flight numbers, departure dates, seat availability, one-way, return and infant prices, baggage options and end-of-sale dates. The exact column set and delivery details are in the technical pack. In production today with a European distribution platform.
Reconciliation
GET /partners/statistics returns your orders with statuses, amounts, currency and the marker and market values captured at booking time. Use it for periodic settlement; we also produce a monthly reconciliation report on our side.
Anything else
A different schema, a different transport, push instead of pull — that's a request, not a limitation. Typical delivery for a custom contract is 1–4 weeks. Write to it@gtavia.com.