# Partner server

To integrate pricing and availability information, partners will need to
implement the Partner API. This interface is based on REST and allows Google to
send live calls over HTTP. While details of individual API methods are described
in the [Reference](https://developers.google.com/travel/transport/reference/overview) section, you can find
information about cross-cutting concerns later.

## Request \& response format

Initially only JSON formats will be supported. If additional request or response
formats are required, reach out to the Travel Transport team at
[transport-help@google.com](mailto:transport-help@google.com) to discuss your
use case.

Requests will be sent using HTTP method POST, with the request message in the
POST body.

Note that for structural clarity, the API interface documentation is provided as
Protocol Buffer message definitions, and translation of a Protocol Buffer
message definition to a JSON object is defined by the [canonical JSON
mapping](https://developers.google.com/protocol-buffers/docs/proto3#json), using
the
[options](https://developers.google.com/protocol-buffers/docs/proto3#json_options)
to **emit fields with default values** and to **use proto field names instead of
lowerCamelCase names**.

> [!IMPORTANT]
> **Important:** It is recommended to **use the [protocol buffer
> libraries](https://github.com/protocolbuffers/protobuf) and the included
> JsonFormat utilities** for a type-safe APIs which guarantee that syntactically correct responses are produced. Enum definitions shown in documentation exclude the [`UNSPECIFIED`](https://protobuf.dev/programming-guides/dos-donts/#unspecified-enum) value. These should be added when using protobufs directly.

## Authentication

Google supports HTTP Digest Authentication, OAuth 2.0 and Client Certificate
Authentication (see [Partner
Configuration](https://developers.google.com/travel/transport/guides/partner-integration/partner-configuration)).
Partners should provide Google with the right credentials during API testing:

- For Digest: username and password.
- For OAuth 2.0: client_id and client_secret.
- For Certificate: an SSL Client Certificate.

## Status codes \& error handling

In general, the following status codes can be returned in HTTP responses:

| HTTP Code | HTTP Description | Notes |
|---|---|---|
| 2xx | OK | Not an error; returned on success. The response body is expected to contain a successful result (for example, TripOptionsResult), **not** an error response. |
| 400 | Bad Request | The received request was invalid. Method-specific error responses should be used to return additional error details in the response body. HTTP 400 should generally only be used if Google made a technical error (for example, a misnamed field in a request). |
| 403 | Forbidden | Permission denied/forbidden (caller is known and rejected). This response must not be used for rejections caused by exhausting some resource (use Too Many Requests instead for those errors). Forbidden must not be used if the caller can not be identified (use Unauthorized instead for those errors). |
| 404 | Not found | The requested resource could not be found. Method-specific error responses should be used to return additional error details in the response body. |
| 429 | Too many requests | Some resource has been exhausted, perhaps a per-user quota. |
| 500 | Internal Server Error | Internal errors. This means that some invariants expected by the underlying system have been broken. This error code is reserved for serious errors and indicates a bug in the partner's API server implementation. |
| 503 | Service Unavailable | The service is unavailable. This is most likely a transient condition, which can be corrected by retrying with a backoff. |
| 504 | Gateway Timeout | The deadline expired before the operation could complete. For operations that change the state of the system, this error may be returned even if the operation has completed successfully. For example, a successful response from a server could have been delayed long enough for the deadline to expire. |

Note that for all preconditions, invalid arguments, or not found errors:

- the method-specific responses or error messages defined in the APIs should be used.
- the correct http code should be used, as specified in the method-specific codes (see, for example, [`TripOptionsErrorType`](https://developers.google.com/travel/transport/reference/partner-server/get-trip-options#gettripoptionsresponse))

This allows more detailed information about these types of errors to be
provided. This information can be used to:

- Determine if an error can be retried
  - `SEGMENT_KEY_NOT_FOUND` cannot be retried.
- Correct stale information
  - `Unavailable.Reason.CANCELED` indicates the trip should be removed (note that this is part of a successful response)
  - `Unavailable.Reason.TEMPORARILY_UNAVAILABLE` as well as the error codes `SEGMENT_KEY_NOT_FOUND`, `SUBOPTIMAL_ITINERARY`, `BOOKING_WINDOW_NOT_SUPPORTED` and `TICKETING_PROHIBITED` remove any prices we previously received from the cache.
- Provide relevant guidance to users

The current list of method-specific errors provided in
[`TripOptionsError`](https://developers.google.com/travel/transport/reference/partner-server/get-trip-options#gettripoptionsresponse)
is a starting point. If additional error types are needed, please reach out to
the Google Travel Transport team.

## QPS (Queries per second)

The level of QPS sent by Google is likely to vary based on partner inventory and
how many users view the cached data or click through to partner websites for
booking.

## Latency

Requests will timeout after 10 seconds. There will be no additional latency
guidelines for beta partner integrations. However, further latency SLOs will be
defined in our Partner Data Quality Guidelines.

## Currencies, taxes, and fees

All prices sent to Google must include all taxes and fees and be specified in a
supported currency.

### Currency

The currency for a price is specified using the `currency_code`
field, which must be a valid
[ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code.

**Example 10.25 USD:**

    {
      "price": {
        "currency_code": "USD",
        "units": 10,
        "nanos": 250000000
      }
    }

### Taxes and Fees

The price you provide must be the final, total price the user will pay,
inclusive of all taxes (like VAT) and any additional fees (like booking or
payment card fees). An optional fare breakdown can be added using the
repeatable `line_items` field. Google will display the total price
with an optional fare breakdown to the user.