Google Flights Partner Entegrasyonu: Live API ve Price Feed Developer Rehberi

Google Flights entegrasyonunu public bir search API gibi düşünmek yanlış olur. Google Flights partner yapısında teknik entegrasyon, partner onboarding'e bağlıdır ve public dokümantasyonda en görünür üç pricing modeli şunlardır:

• Live API — Google Flights Search partner endpoint'inize query gönderir.
• Price Feed — partner flight/price datasını feed olarak Google'a iletir.
• Price Through Google — Google fiyatı kendi pricing engine'i veya web-fare yaklaşımıyla hesaplar.

Bu nedenle developer açısından ilk soru “hangi endpoint'i çağıracağım?” değil, Google ile hangi integration mode üzerinden bağlanıyorum? olmalıdır.

Partner erişimi, ücret eşdeğerliği ve rezervasyon sorumluluğu için Google Flights profiline bakın. Bu rehber uygulama sınırlarına odaklanır.

1. Public API ile partner API'yi ayırın

Genel kullanıma açık, Skyscanner benzeri bir Google Flights search endpoint'i yoktur. Live API erişimi partner/onboarding kapsamındadır.

Bu yüzden internal architecture'ınızı Google'ın private wire contract'ına kilitlemeyin.

Google Flights
    |
    v
Partner Integration Adapter
    |
    +--> Live API endpoint
    +--> Price Feed exporter
    +--> Booking-link generator
    +--> Quality / analytics ingestion
    |
    v
Canonical Flight Domain

2. Live API akışı

Google'ın public Travel Analytics dokümantasyonu, Google Flights Search'ün partner API endpoint'lerine query gönderdiğini açıkça belirtir.

Conceptual flow:

Google Flights search
        |
        v
Partner Live API
        |
        v
availability + pricing
        |
        v
Google Flights booking options
        |
        v
partner booking page

Google ayrıca Live API tarafında one-way ve round-trip query'leri desteklediğini, timeout ve response-time metriklerini Travel Analytics Center'da izlediğini belirtir.

3. Internal request modeli

Google'ın gerçek partner wire schema'sı onboarding contract'ının parçası olabilir. Internal modeliniz ise provider bağımsız olmalıdır.

interface FlightPricingRequest {
  userCountry?: string;

  tripType: "one_way" | "round_trip";

  origin: {
    airportCode: string;
  };

  destination: {
    airportCode: string;
  };

  outboundDate: string;
  returnDate?: string;

  passengers: {
    adults: number;
    nonAdults: number;
  };

  cabinClass?:
    | "economy"
    | "premium_economy"
    | "business"
    | "first";

  currency?: string;
}

Adapter:

Google partner request
    -> validate
    -> map to FlightPricingRequest
    -> pricing engine
    -> canonical itinerary/offer
    -> Google response serializer

4. Internal response modeli

Google-specific response yerine canonical offer üretin.

interface FlightPricingResponse {
  requestId: string;
  solutions: FlightSolution[];
  generatedAt: string;
}

interface FlightSolution {
  itinerary: FlightItinerary;
  bookingOptions: FlightBookingOption[];
}

interface FlightBookingOption {
  providerId: string;
  price: {
    amount: number;
    currency: string;
  };
  deeplink: string;
  available: boolean;
}

Bu model daha sonra Google adapter tarafından partner contract'ına serialize edilir.

5. Itinerary modeli

Google Flights quality datası origin/destination, slices, segments, marketing carriers, operating carriers, validating carrier ve trip type gibi alanları raporlar.

Bu nedenle domain modeliniz en az şu ayrımları korumalıdır:

interface FlightItinerary {
  slices: FlightSlice[];
  validatingCarrier?: string;
}

interface FlightSlice {
  segments: FlightSegment[];
}

interface FlightSegment {
  origin: string;
  destination: string;
  departure: string;
  arrival: string;
  marketingCarrier?: string;
  operatingCarrier?: string;
  flightNumber?: string;
}

Marketing carrier ile operating carrier'ı tek alanda birleştirmeyin.

6. Price Feed yaklaşımı

Price Feed modelinde partner flight ve price datasını Google'a önceden iletir.

Internal export modeli:

interface FlightPriceFeedRow {
  itineraryKey: string;
  origin: string;
  destination: string;
  departureDate: string;
  returnDate?: string;

  cabinClass?: string;

  price: number;
  currency: string;

  bookingUrl: string;

  generatedAt: string;
  expiresAt?: string;
}

Feed'in en büyük riski freshness'tir.

feed accepted != price still valid

7. Price Through Google

Google'ın Quality dokümantasyonu Price Through Google için iki farklı kaynak tarif eder:

• GDS tabanlı pricing,
• web-fare tabanlı pricing.

Bu modelde partner price generation sorumluluğu Live API/Price Feed'e göre farklıdır.

Architecture kararında şunları ayırın:

Who computes the price?
Who owns availability?
Who owns booking link quality?
Who owns final price reconciliation?

8. Booking link contract

Google Flights booking page kullanıcının partner site'a gitmeden önce gördüğü son adımdır.

Deep link mümkün olduğunca şunları taşımalıdır:

• itinerary,
• passenger mix,
• cabin,
• selected fare,
• currency,
• referral/tracking context.

Internal model:

interface GoogleFlightsHandoff {
  itineraryKey: string;
  providerId: string;
  displayedPrice: number;
  currency: string;
  deeplink: string;
  referralId?: string;
}

Generic homepage'e düşmek link quality'yi bozar.

9. Price quality ve itinerary-not-found

Google Quality dashboard iki ana kalite metriğini öne çıkarır:

• Itinerary Not Found
• Price Discrepancy

Google'ın public dokümanında price discrepancy, partner site fiyatının Google'ın beklediği fiyattan belirgin şekilde sapması olarak ölçülür.

Internal taxonomy:

ITINERARY_NOT_FOUND
PRICE_MISMATCH
CURRENCY_MISMATCH
FARE_UNAVAILABLE
DEEPLINK_BROKEN
WRONG_PASSENGER_CONTEXT
WRONG_CABIN
STALE_PRICE
UNKNOWN

10. Live API latency

Google Live API Performance dashboard:

• query success,
• failure rate,
• p50,
• p90,
• p99 latency,
• no-solution ratio

gibi metrikleri raporlar.

Public dokümantasyonda 45 saniyelik timeout state'i ve p90 < 15 saniyenin genellikle yeterince hızlı kabul edildiği belirtilir.

Bu rakamları kendi SLO'nuz gibi kopyalamayın; Google partner behavior'ını anlamak için referans olarak kullanın.

Internal:

provider_query_duration_ms
pricing_engine_duration_ms
supplier_fanout_duration_ms
serialization_duration_ms
total_response_duration_ms

11. Timeout ve fallback

45 saniyeyi backend target yapmak kötü fikirdir.

Daha iyi:

Google timeout
   > your API timeout
      > supplier timeout

Örnek:

interface FlightPricingTimeouts {
  totalBudgetMs: number;
  supplierBudgetMs: number;
  fallbackBudgetMs: number;
}

Fallback seçenekleri:

• cached price,
• partial provider coverage,
• no-solution response,
• controlled degradation.

12. Query success != useful result

HTTP 200 dönmek yeterli değildir.

Google dashboard no-solution ratio'yu ayrıca izler.

Internal ayrım:

transport success
business success
priced solution found
bookable solution found

14. Retry policy

Live pricing path'ında tüm hataları retry etmek latency ve duplicate load üretir.

Retryable adaylar:

• transient network failure,
• selected provider 5xx,
• kısa süreli upstream timeout,
• throttling/rate-limit sinyali varsa bounded backoff.

Blind retry yapılmaması gerekenler:

• malformed request,
• unsupported itinerary/context,
• stale/invalid booking link,
• deterministic pricing validation failure.

Örnek policy:

interface RetryPolicy {
  maxAttempts: number;
  baseDelayMs: number;
  maxDelayMs: number;
  retryableCodes: string[];
}

Interactive search'te retry bütçesi total latency budget'ın parçası olmalıdır. Bir retry yüzünden outer Google timeout'a yaklaşmak yerine kontrollü no-solution/fallback daha güvenli olabilir.

13. Error taxonomy

GOOGLE_FLIGHTS_BAD_REQUEST
GOOGLE_FLIGHTS_TIMEOUT
GOOGLE_FLIGHTS_UNREACHABLE
GOOGLE_FLIGHTS_PARSE_ERROR
GOOGLE_FLIGHTS_NO_SOLUTION
GOOGLE_FLIGHTS_PRICE_MISMATCH
GOOGLE_FLIGHTS_LINK_INVALID
GOOGLE_FLIGHTS_STALE_PRICE

Public Live API dashboard hata state'leri arasında:

• TIMEOUT,
• UNREACHABLE,
• ERROR

bulunur.

15. Idempotency ve request correlation

Her inbound query için internal correlation ID üretin.

interface FlightPricingEnvelope {
  requestId: string;
  receivedAt: string;
  queryHash: string;
  request: FlightPricingRequest;
}

Aynı query tekrar geldiğinde response cache uygulanabilir; ancak passenger/currency/market context'i hash'in parçası olmalıdır.

16. Referral tracking

Google Flights referral, kullanıcının booking option seçerek partner linkine tıklamasıyla oluşur.

Internal click event:

interface GoogleFlightsReferralEvent {
  requestId: string;
  itineraryKey: string;
  providerId: string;

  displayedPrice: number;
  currency: string;

  clickedAt: string;
}

Booking tarafında:

interface FlightConversionEvent {
  referralId?: string;
  bookingId: string;
  bookingValue: number;
  currency: string;
  bookedAt: string;
}

17. Conversion reconciliation

Google referral ile downstream booking'i reconcile edin.

Google referral
    -> deeplink click
    -> booking created
    -> booking confirmed
    -> cancellation/refund
    -> matured booking

Metric:

referral_to_booking
referral_to_matured_booking
cancellation_rate
unattributed_booking_rate

18. Travel Analytics Center ve BigQuery

Google Flights partner analytics'i yalnız dashboard'da kalmak zorunda değildir.

Google, Quality ve Competitiveness dataset'lerini BigQuery üzerinden programatik olarak erişilebilir hale getirir.

Bu şu use case'leri açar:

• automated alert,
• route-level anomaly detection,
• carrier-level quality scoring,
• price discrepancy trend,
• invalid-link monitoring.

Örnek internal quality table:

google_flights_quality
- date
- integration_id
- origin
- destination
- trip_type
- marketing_carriers
- operating_carriers
- google_price
- partner_price
- price_diff_percentage
- is_valid_partner_link
- source

19. Monitoring

API

• query success rate,
• p50/p90/p99,
• timeout,
• unreachable,
• parse error,
• no-solution.

Price quality

• discrepancy rate,
• stale price,
• currency mismatch.

Link quality

• itinerary not found,
• invalid partner link,
• deeplink landing success.

Commercial

• referrals,
• conversion,
• matured conversion,
• revenue,
• cancellation-adjusted revenue.

20. Test matrisi

21. Go-live checklist

• Google partner onboarding tamam
• integration mode net: Live API / Price Feed / Price Through Google
• canonical flight model hazır
• marketing/operating carrier ayrımı var
• request adapter test edildi
• response serializer test edildi
• price freshness policy var
• timeout budget tanımlı
• no-solution handling var
• booking-link validation var
• referral correlation var
• price discrepancy monitoring var
• itinerary-not-found monitoring var
• TAC dashboard ownership belli
• BigQuery export/alert ihtiyacı değerlendirildi

Sonuç

Google Flights entegrasyonunu “Google Flights API çağırmak” olarak düşünmek yanlış abstraction'dır.

Daha doğru model:

Google Flights partner query/feed
        |
        v
Google adapter
        |
        v
Canonical flight pricing domain
        |
        v
pricing / availability
        |
        v
Google booking option
        |
        v
deeplink + referral
        |
        v
quality + conversion reconciliation

Developer açısından asıl değer, private partner contract'ını internal flight domain'den izole etmek; fiyat, itinerary ve booking-link kalitesini uçtan uca ölçülebilir hale getirmektir.