Solera API (v1)

Every result, from every source, in both delivery modes, is shaped by one canonical model. A field means the same thing regardless of which provider produced it, so comparing two airlines is a matter of comparing two structs, not writing a mapping layer per provider.

Each source's payload is an envelope of three parts:

capture and resolved_query are not decoration. The same route scanned under a different point_of_sale or device is legitimately a different price, and resolved_query records what the provider really searched for, which is not always what you asked for. Reconcile against them before comparing results across sources.

Field naming

One thing to get right before you write a parser: Solera names fields in snake_case, and the JSON on the wire uses camelCase.

Protobuf's canonical JSON mapping lower-camel-cases field names, so the field display_price arrives as displayPrice, award_points as awardPoints, and source_ids is sent as sourceIds. The schemas below are labelled with both: the property name is the JSON name you will actually see, and the title above it is the field's name in the model.

Requests accept either spelling; responses always use camelCase.

Cash and rewards

Cash and award pricing sit side by side on every flight and hotel result, rather than in separate response shapes:

• price_mode — CASH, AWARD or MIXED. Read this first; it determines which of the price fields is meaningful.
• display_price / currency — the cash price as displayed.
• award_points / loyalty_program — the award price. Points from different programmes are not comparable, so never read award_points without its programme.
• award_surcharge — cash still payable on an award booking (taxes, surcharges, resort fees). Carries its own currency. An award fare is rarely points-only, so ignoring this understates the real cost.

Solera is a Connect RPC API. Every operation is a POST to /{proto.package}.{Service}/{Method} — paths are never parameterized, and there are no GET/PUT/DELETE variants. It is not a REST API and does not pretend to be one.

The same endpoints speak three protocols, selected by Content-Type:

The gRPC content types are listed on each operation for completeness, but this document does not describe their binary framing — use the .proto, or the server's gRPC reflection, for that.

Streaming operations

SearchFlights and SearchHotels are server-streaming: one response is emitted per requested source_id as that provider finishes, in completion order rather than request order. The stream closes once every requested source has produced a result.

OpenAPI has no vocabulary for this. The response schema shown below is the schema of a single message in the stream, not of the whole HTTP response body — the real body is a sequence of those messages inside Connect's envelope frames. Read the schema as "what each chunk looks like", and the operation description as the authority on how many chunks arrive.

If your infrastructure will not hold a connection open for the length of a scan — seconds, not milliseconds — use TravelJobService instead. Same data, no long-lived connection.

Two layers, and confusing them is the most common integration mistake.

RPC errors use the Connect error shape (code, message, details) with an HTTP status derived from the code — see the connect.error schema, present as the default response on every operation. These mean the call itself failed.

Source-level failures are not RPC errors. A provider that times out, is unreachable, or returns nothing still yields a normal 200 response carrying that source's status and error. A multi-source search where every source failed is still a successful call. The per-source status field is the authoritative outcome — check it on every result before reading data.

Note that NO_AVAILABILITY is a success: the search ran cleanly and the route or property genuinely has nothing on sale. Do not retry it as though it were a failure.

Request constraints are declared in the .proto with protovalidate and enforced server-side before any handler runs. The constraints rendered on each schema (minItems, minimum, required, …) are generated from those same declarations, so they are the rules the server actually applies — not documentation-only hints. A violation returns invalid_argument naming the field that failed.

Negative source_id values address the mock collector, which synthesizes results deterministically without touching the live fleet: 0 is a generic mock, and -1 through -30 each mock the correspondingly numbered real source. Use them to exercise every success and failure path during integration — including the ones that are hard to provoke on purpose, like SOURCE_BLOCKED and THROTTLER_TIMEOUT.

Asynchronous travel search: submit a job, poll for completion, fetch the results.

Same collectors, same payloads and same source semantics as TravelSearchService — the only difference is delivery. Nothing is held open: you submit, you get a job_id back immediately, and you come back for the results whenever you like.

Use this for scheduled and batch work: overnight refreshes, rate monitoring across many routes, anything running where no user is waiting, and anything behind infrastructure that will not hold a streaming connection open for the length of a scan.

The lifecycle is:

1. SubmitSearch — enqueue the work, receive a job_id.
2. GetSearchJob — poll until status is terminal. Honour retry_after_ms; it reflects real queue depth.
3. GetSearchResults — page through the completed sources' payloads.

Results are retained for a limited window after completion (see expires_at) and then deleted. Fetch what you need before then.

Realtime travel search.

Both RPCs are server-streaming: you send one request naming several sources, and results arrive one source at a time as each collector finishes. Use this when a caller is waiting on the answer and you want to show the first results without waiting for the slowest provider.

Sources are dispatched concurrently and are independent of one another. A source that fails, times out or finds nothing still produces a response carrying its status and error — it never fails the call or suppresses the other sources. That means a stream can complete with every source having failed, and the RPC will still report success; the per-source status is the authoritative outcome, not the RPC's.

Responses arrive in completion order, not request order. Correlate on source_id, and treat the stream as complete only when it closes — not when a particular source arrives.

A scan takes seconds, and a stream is held open for its whole duration. If your caller cannot hold a connection that long — a batch job, a scheduled refresh, or anything behind a proxy with an aggressive idle timeout — use TravelJobService instead, which does the same work and lets you poll for the result.