trivago FastConnect Integration: Developer Guide

trivago FastConnect is not a normal search API that your application calls. trivago calls endpoints that you expose to retrieve live hotel rates and availability.

Hotel inventory feed
      |
      v
trivago property mapping
      |
      v
User search on trivago
      |
      v
POST /hotel_availability
      |
      v
Your pricing engine
      |
      v
JSON room/rate response
      |
      v
trivago result
      |
      v
deeplink -> booking engine
      |
      v
conversion tracking

The integration is therefore an inbound realtime pricing API + property mapping + handoff quality problem.

Provider companion snapshot

Capability boundary

Inventory/mapping        -> hotel data feed/API
Live user search         -> trivago -> /hotel_availability
Offer handoff            -> deeplink -> advertiser booking engine
Booking confirmation     -> advertiser -> Conversion API POST
Booking modification     -> advertiser -> Conversion API PUT
Booking cancellation     -> advertiser -> Conversion API DELETE

FastConnect does not create bookings. The booking lifecycle lives in the advertiser system and trivago receives attribution/conversion events.

Why pagination and polling are N/A

hotel_availability is a realtime request-response endpoint. There is no search-session pagination or client polling. Capacity planning should use:

inbound search traffic
x hotels/request
x cache miss ratio
x supplier fan-out
x retry amplification

Rate limits and capacity

The public FastConnect documentation reviewed does not expose one universal QPS limit for every advertiser. Therefore:

• align expected traffic with the trivago Technical Account Manager,
• enforce an inbound concurrency budget,
• bound supplier fan-out,
• use timeouts/circuit breakers,
• define explicit overload fallback behavior.

Do not invent a global FastConnect QPS limit.

Conversion lifecycle and idempotency

Conversion API uses HTTP methods to represent booking lifecycle events:

POST   -> booking confirmation
PUT    -> booking update
DELETE -> booking cancellation

The trv_reference carried in the deeplink connects click attribution to the booking. Use booking identity plus lifecycle revision for idempotency so duplicate notifications cannot double-count revenue or conversions.

For platform responsibilities, commercial boundaries and operational decisions, see the trivago profile. This guide covers implementation contracts and request/response handling.

1. Endpoints you expose

trivago documents two core methods:

GET  /hotel_data
POST /hotel_availability

Requests use:

Content-Type: application/x-www-form-urlencoded

Responses use JSON and should be compressed. The technical requirements explicitly expect HTTP 200 responses and no redirects.

2. Security boundary

FastConnect endpoints are internet-facing. trivago can optionally use HTTP Basic Authentication; use it only over HTTPS.

interface FastConnectSecurityConfig {
  username?: string;
  passwordRef?: string;
  allowedNetworks?: string[];
  requireTls: true;
}

Add WAF, request throttling, correlation logging and secret rotation as appropriate.

3. Hotel inventory and mapping

Only hotels submitted in the inventory and mapped by trivago can participate in availability requests.

interface Hotel {
  id: string;
  name: string;
  address?: string;
  city?: string;
  countryCode: string;
  latitude?: number;
  longitude?: number;
  active: boolean;
}

interface TrivagoHotelMapping {
  hotelId: string;
  partnerHotelId: string;
  mapped: boolean;
  lastSubmittedAt?: string;
}

internal hotel id != trivago partner reference

4. hotel_data response

Hotel data may be supplied by CSV or API. A simplified API response might look like:

[
  {
    "hotel_id": "HTL-84721",
    "hotel_name": "Example Bosphorus Hotel",
    "city": "Istanbul",
    "country": "TR",
    "latitude": 41.0423,
    "longitude": 29.0082
  }
]

Use the current hotel-data reference for the production field set.

5. hotel_availability request model

A request includes hotel IDs, stay dates and occupancy context.

interface TrivagoAvailabilityRequest {
  hotelIds: string[];
  checkIn: string;
  checkOut: string;
  adults: number;
  children?: number;
  locale?: string;
  currency?: string;
}

Normalize into your own domain:

interface HotelAvailabilityRequest {
  hotelIds: string[];
  checkIn: string;
  checkOut: string;
  rooms: Array<{
    adults: number;
    childAges: number[];
  }>;
  currency?: string;
  market?: string;
}

6. Availability response

FastConnect responses model hotel -> room type -> offer.

Conceptual example:

[
  {
    "hotel_id": "HTL-84721",
    "room_types": {
      "Deluxe Room": {
        "price": 5400.00,
        "currency": "TRY",
        "breakfast_included": true,
        "free_cancellation": true,
        "booking_fee": 0,
        "deeplink": "https://booking.example.com/..."
      }
    }
  }
]

Use the current API Objects reference for exact mandatory and optional fields.

7. Internal offer model

interface HotelOffer {
  hotelId: string;
  roomName: string;
  ratePlanId?: string;
  price: {
    amount: number;
    currency: string;
  };
  breakfastIncluded?: boolean;
  refundable?: boolean;
  cancellationDeadline?: string;
  bookingFee?: number;
  deeplink: string;
  observedAt: string;
}

8. Rate semantics

trivago's update history shows that supported price models can change by locale or point of sale.

Preserve explicit semantics:

interface PriceBreakdown {
  base: number;
  taxes?: number;
  mandatoryFees?: number;
  bookingFee?: number;
  total: number;
  currency: string;
  model: "all_in" | "tax_exclusive" | "other";
}

The lowest numeric amount is not necessarily a comparable offer unless room, occupancy, cancellation and included benefits align.

9. Separate no availability from errors

AVAILABLE
SOLD_OUT
UNKNOWN_HOTEL
INVALID_STAY
UNSUPPORTED_OCCUPANCY
UPSTREAM_TIMEOUT
UPSTREAM_ERROR

Even when the external protocol expects HTTP 200, retain semantic outcomes internally.

10. Latency budget

FastConnect is on the user-facing search path.

Track:

• p50/p95/p99,
• supplier timeout,
• cache hit,
• answer rate,
• partial coverage.

Keep an internal budget for parsing, mapping, supplier calls, normalization and serialization.

11. Cache policy

A useful cache key includes:

hotel
+ check-in
+ check-out
+ occupancy
+ currency
+ market/locale

A fast stale rate can be worse than a slower fresh one. Tighten freshness as booking intent increases.

12. Deep-link handoff

Preserve hotel, dates, occupancy, currency, selected room/rate and tracking context.

interface BookingHandoff {
  hotelId: string;
  checkIn: string;
  checkOut: string;
  adults: number;
  children: number[];
  currency: string;
  offerId?: string;
  clickId: string;
}

13. Conversion tracking

Normalize conversion events and deduplicate by booking identity.

interface TrivagoConversion {
  clickId?: string;
  bookingId: string;
  bookingValue: number;
  currency: string;
  bookingStatus: "booked" | "cancelled" | "modified";
  occurredAt: string;
}

14. Error and retry policy

Bound retries for transient supplier failures. Do not blindly retry invalid mappings, malformed requests, unsupported occupancy or unsupported currency.

15. Capacity planning

Capacity is driven by:

peak searches
x requested hotels/search
x cache miss ratio
x supplier fan-out
x retry amplification

not simply by hotel count.

16. Monitoring

Inventory

• submitted hotels,
• mapping coverage,
• unmatched hotels.

Availability

• request count,
• answer rate,
• sold-out rate,
• timeout/error,
• p50/p95/p99.

Quality

• stale price,
• deep-link success,
• price mismatch,
• unsupported occupancy.

Commercial

• clicks,
• bookings,
• attributed bookings,
• cancellations,
• net conversion.

17. Test matrix

18. Go-live checklist

• trivago onboarding aligned
• hotel inventory feed valid
• mapping coverage monitored
• hotel_data stable
• hotel_availability schema-valid
• UTF-8 / JSON response correct
• compression enabled
• no redirects
• TLS configured
• Basic Auth configured if required
• rate semantics explicit
• latency dashboard ready
• cache/freshness policy defined
• deep-link context tested
• conversion idempotency implemented
• failure modes load-tested

Summary

Treat FastConnect as a realtime inbound pricing service, not simply a hotel-rate endpoint.

trivago request
   -> FastConnect adapter
   -> canonical availability request
   -> pricing engine
   -> normalized offers
   -> FastConnect JSON
   -> deeplink
   -> booking/conversion reconciliation

This keeps trivago-specific behavior isolated while making latency, price quality and commercial outcomes observable.