--- title: "Google Hotels Entegrasyonu: Developer Rehberi" description: "Google Hotels entegrasyonunu Hotel List, property mapping, Pull/Changed Pricing/ARI, Transaction XML, landing pages, OAuth2, request/response modelleri, error handling ve monitoring ile developer gözüyle uygulayın." slug: "google-hotels-integration" translationKey: "integration-google-hotels" locale: "tr" type: "guide" category: "integration" tags: ["google-hotels","hotel","feed","ari","transaction-xml","landing-page","price-accuracy","oauth"] vertical: ["hotel"] platform: "Google Hotels" domain: "developers.google.com" featured: true publishedAt: "2026-09-19" updatedAt: "2026-09-26" reviewedAt: "2026-09-26" technicalVerifiedAt: "2026-09-26" sourceVersion: "Travel Partner API v3 + Hotel Prices public docs reviewed 2026-09-26" testedAgainst: "Official public documentation; not a live Hotel Center account" codeExampleStatus: "illustrative" changelog: - "2026-09-26 — Provider companion standard applied; access, limits, lifecycle and evidence boundaries clarified." sources: - title: "Google Hotels — Hotel prices documentation" url: "https://developers.google.com/hotels/hotel-prices" - title: "Google Hotels — Integration overview / data feeds" url: "https://developers.google.com/hotels/hotel-prices/dev-guide/data-feeds" - title: "Google Hotels — Transaction messages XML reference" url: "https://developers.google.com/hotels/hotel-prices/xml-reference/transaction-messages" - title: "Google Hotels — Hint Response messages" url: "https://developers.google.com/hotels/hotel-prices/dev-guide/hint-response-messages" - title: "Google Hotels — Landing pages overview" url: "https://developers.google.com/hotels/hotel-prices/dev-guide/pos-overview" - title: "Google Hotels — API authorization" url: "https://developers.google.com/hotels/hotel-prices/dev-guide/api-auth" - title: "Google Hotels — Hotel price structured data" url: "https://developers.google.com/hotels/hotel-prices/structured-data/hotel-price-structured-data" --- Google Hotels entegrasyonu tek bir REST endpoint çağırmak değildir. Production bağlantı en az dört ayrı contract'tan oluşur: 1. **Property identity** — Google'a hangi hotelleri gönderdiğiniz ve bunların nasıl eşleştiği, 2. **Pricing & availability** — fiyatı hangi delivery mode ile ve hangi XML contract'ıyla taşıdığınız, 3. **Landing page handoff** — Google'daki offer click'inin booking engine'e doğru context ile aktarılması, 4. **Monitoring & quality** — mapping, freshness, price accuracy ve downstream conversion kalitesi. Developer açısından en sağlıklı yaklaşım Google-specific XML/API modellerini internal domain modelinizden ayırmaktır. ```text Internal Hotel Domain | +--> Google Hotel List Adapter | +--> Google Pricing Adapter | +--> Pull | +--> Changed Pricing | +--> ARI | +--> Landing Page Adapter | +--> Travel Partner API / Diagnostics ``` Bu rehber Google dokümantasyonunu tekrar etmek yerine, entegrasyon boundary'sini nasıl tasarlayacağınızı gösterir. ## Provider companion özeti | Alan | Durum | |---|---| | Erişim | Hotel Center / partner setup gerekir; tüm yüzeyler anonymous self-service API değildir | | Auth | Travel Partner API ve ilgili API yüzeylerinde OAuth 2.0 / service account | | Primary contracts | Hotel List, Pricing/ARI/Transaction messages, Landing Pages, Travel Partner API | | Data direction | Pull, Changed Pricing veya ARI modeline göre pull/push/hybrid | | Pagination | Travel Partner API resource'larına göre endpoint-specific; pricing XML/message flow için generic pagination kavramı yok | | Polling | Feed/message modeline göre değişir; Google'ın Query/Hint akışında partner kendi sabit polling interval'ını uydurmamalıdır | | Universal public rate limit | Bu companion için account-independent tek bir public QPS/quota değeri doğrulanmadı; account/docs/configuration üzerinden doğrulayın | | Booking ownership | Google Hotels generic booking-creation API değildir; kullanıcı booking partner/engine'e handoff olur | | Evidence level | Official documentation reviewed; live Hotel Center account ile test edildiği iddia edilmiyor | | Code examples | Illustrative architecture/mapping examples | ### Capability boundary Google Hotels'i tek bir endpoint gibi modellemeyin. Entegrasyon yüzeyleri farklı sorumluluk taşır: ```text Property identity -> Hotel List / matching Price distribution -> Pull / Changed Pricing / ARI / Transaction Consumer handoff -> Landing Pages Account diagnostics -> Travel Partner API Price validation -> crawler navigation / structured data / price accuracy tooling ``` Bir yüzeydeki auth, retry, pagination veya quota davranışını diğer yüzeye otomatik taşımayın. ### Rate limit ve quota yaklaşımı Bu rehberde universal bir Google Hotels QPS değeri vermiyoruz; çünkü public dokümantasyonda tüm partner/account/surface kombinasyonları için tek bir account-independent limit doğrulanmadı. Uygulama: - aktif Hotel Center / API dokümantasyonundaki account-specific quota'yı okuyun, - 429/quota response'larını ayrı sınıflandırın, - exponential backoff + jitter kullanın, - internal concurrency budget belirleyin, - gözlenen account limitini "Google global limiti" diye yayımlamayın. ### Polling ve pagination yaklaşımı Pricing message flow klasik paginated REST collection değildir. Pull/Changed Pricing/ARI kendi message lifecycle'ına sahiptir. Travel Partner API tarafında ise collection/resource endpoint'i pagination sunuyorsa o endpoint'in resmi contract'ını uygulayın. Bu yüzden companion standardında bu alanların değeri **surface-specific** olarak işaretlenmiştir. ### Booking / reprice lifecycle Google Hotels entegrasyonunda price discovery ve booking handoff ayrıdır: ```text Hotel/partner price state -> Google price surface -> user click -> landing/booking engine -> downstream booking confirmation ``` Google'da görüntülenen bir offer, internal sisteminizde confirmed booking değildir. Click/handoff sonrası selected context, landing total ve booking confirmation ayrı event olarak tutulmalıdır. Platform sorumlulukları ve operasyona hazırlık kararları için [Google Hotels profiline](/tr/metasearch/hotels/google-hotels) bakın. Sözleşme sınırları, yayınlama hatalarından kurtarma ve Hotel List/POI ayrımı için [Google Hotel Feeds referansını](/tr/metasearch/feeds/google-hotel-feeds) kullanın. ## 1. Ön koşullar ve erişim modeli Google Hotels bağlantısı yalnız public bir API key ile açılan self-service bir endpoint değildir. Hotel Center partner hesabı, ilgili feed/pricing setup'ı ve bazı API'ler için trusted-partner erişimi gerekir. Travel Partner API tarafında Google OAuth 2.0 ve service account kullanır. Güncel dokümantasyonda Travel Partner API scope'u: ```text https://www.googleapis.com/auth/travelpartner ``` Price Feeds API için kullanılan scope: ```text https://www.googleapis.com/auth/travel-partner-price-upload ``` Travel Partner API endpoint paterni: ```text https://travelpartner.googleapis.com/v3/accounts/{account_id}/{path} ``` Service account'un ayrıca ilgili Hotel Center hesabına erişimi olmalıdır. ### Internal credential boundary Credential browser'a gitmemelidir. ```ts interface GoogleHotelsCredentials { serviceAccountEmail: string; privateKeyRef: string; hotelCenterAccountId: string; partnerKey?: string; } ``` Secret'ın kendisini config object içine gömmek yerine secret manager reference kullanın. ## 2. Canonical hotel modeli önce gelmeli Google'a property göndermeden önce kendi canonical property modeliniz stable olmalıdır. ```ts interface Hotel { id: string; // internal canonical id name: string; countryCode: string; city?: string; addressLine?: string; latitude?: number; longitude?: number; phone?: string; website?: string; active: boolean; } ``` Google-specific mapping ayrı tutulmalı: ```ts interface GoogleHotelMapping { hotelId: string; // internal canonical id googlePartnerHotelId: string; matchStatus: "matched" | "unmatched" | "review"; matchConfidence?: number; lastSubmittedAt?: string; lastMatchedAt?: string; } ``` Önemli invariant: ```text internal hotel id != Google partner hotel id ``` Hotel adı veya brand değiştiğinde internal identity değişmemelidir. ## 3. Hotel List entegrasyonu Hotel List Google tarafındaki property identity layer'dır. Pricing message içindeki `` değeri Hotel List'teki listing ID ile eşleşmelidir. ### Internal → Google Hotel List mapping Örnek internal model: ```json { "id": "HTL-84721", "name": "Example Bosphorus Hotel", "countryCode": "TR", "city": "Istanbul", "latitude": 41.0423, "longitude": 29.0082, "phone": "+90...", "active": true } ``` Google adapter'ın ürettiği simplified listing: ```xml HTL-84721 Example Bosphorus Hotel
TR Istanbul
41.0423 29.0082 ``` Bu örnek minimal ve açıklayıcıdır; production payload'ı Google'ın güncel Hotel List XML referansına göre üretilmelidir. ### Hotel List pipeline ```text Canonical Hotel DB | v Eligibility validation | v Google Hotel List serializer | v Feed delivery | v Match report / diagnostics | +--> matched +--> unmatched +--> manual review ``` ### Kontrol edilmesi gerekenler - stable ID, - doğru geo, - duplicate property, - rebrand, - closure/reactivation, - invalid address, - unsupported entity type. Hotel List accepted olsa bile mapping sonucu ayrıca izlenmelidir. ## 4. Pricing delivery mode nasıl seçilir? Google dokümantasyonunda üç ana model bulunur: ### Pull Google size `` gönderir; siz ilgili itinerary/property için güncel `` döndürürsünüz. Uygundur: - price change'i kendi tarafınızda güvenilir detect edemiyorsanız, - query-time backend hızlıysa, - supplier fan-out latency'niz kontrol altındaysa. Risk: - upstream latency, - query burst, - supplier timeout, - yüksek look-to-book. ### Changed Pricing Google `` gönderir. Siz hangi property/itinerary'lerin değiştiğini `` ile belirtirsiniz. Google yalnız ilgili context için `` gönderir. Google'ın akışı: ```text Google HintRequest | Partner Hint | Google Query | Partner Transaction ``` Bu model change detection'iniz güvenilir olduğunda Pull trafiğini azaltır. ### ARI Availability, Rate ve Inventory değişikliklerini siz push edersiniz. Uygundur: - local inventory/rate state güçlü ise, - değişiklikleri event/delta olarak yakalayabiliyorsanız, - yüksek hacimde predictable update akışı istiyorsanız. ### Karar tablosu | Durum | Daha uygun başlangıç | |---|---| | Change detection zayıf, backend hızlı | Pull | | Change detection güçlü | Changed Pricing | | ARI source-of-truth sizde | ARI | | Supplier latency yüksek | Cache/Changed/ARI ağırlıklı | | Child occupancy context kritik | Live/context-aware pricing gereksinimini ayrıca değerlendirin | ## 5. Pull / Changed Pricing request-response akışı Google'dan gelebilecek simplified query: ```xml 2026-10-10 3 HTL-84721 ``` Bunu doğrudan domain modeliniz yapmayın. Önce adapter DTO'ya parse edin: ```ts interface GooglePriceQuery { checkIn: string; nights: number; propertyIds: string[]; } ``` Sonra internal request'e çevirin: ```ts interface HotelPriceRequest { hotelIds: string[]; checkIn: string; checkOut: string; rooms: Array<{ adults: number; childAges: number[]; }>; currency?: string; market?: string; } ``` Adapter sorumluluğu: ```text Google Query -> parse -> validate -> provider hotel id -> internal hotel id -> build internal pricing request -> price engine -> normalize -> Google Transaction serializer ``` ## 6. Transaction XML response modeli Google pricing response'un merkezinde `` bulunur. Minimal conceptual response: ```xml HTL-84721 2026-10-10 3 12000.00 2400.00 300.00 2 ``` Google'ın Transaction mesajında: - `timestamp` zorunlu, - `id` zorunlu ve unique olmalı, - `` Hotel List ID ile eşleşmeli, - `` price/availability state taşır, - room/rate çeşitliliği için `` ve `` kullanılabilir. Google Transaction mesajlarının toplam boyutu için dokümantasyonda 100 MB sınırı belirtilir; bunu hard-coded operational target gibi değil üst protocol sınırı olarak düşünün. ## 7. Internal normalized offer modeli Google XML'i business logic'inizde dolaştırmayın. ```ts interface HotelOffer { hotelId: string; provider: string; checkIn: string; nights: number; occupancy: { adults: number; childAges: number[]; }; roomId?: string; ratePlanId?: string; baseAmount: number; taxAmount: number; mandatoryFeeAmount: number; totalAmount: number; currency: string; refundable?: boolean; refundableUntil?: string; observedAt: string; source: "live" | "cache"; } ``` Serializer: ```ts function toGoogleTransaction(offer: HotelOffer): GoogleTransaction { return { property: offer.hotelId, checkIn: offer.checkIn, nights: offer.nights, baseRate: offer.baseAmount, tax: offer.taxAmount, otherFees: offer.mandatoryFeeAmount, currency: offer.currency, occupancy: offer.occupancy.adults }; } ``` Ama gerçek production serializer Google'ın XML schema'sını tam uygulamalıdır. ## 8. RoomData, PackageData ve RoomBundle ne zaman gerekli? Simple property-level price yeterli değilse oda ve package metadata'sı önem kazanır. Google Transaction modeli: ```text Transaction ├── PropertyDataSet │ ├── Property │ ├── RoomData │ └── PackageData │ └── Result ├── Rates └── RoomBundle ``` Internal modeliniz de physical room ile commercial rate'i ayırmalıdır: ```ts interface Room { id: string; hotelId: string; name: string; maxOccupancy?: number; } interface RatePlan { id: string; meal?: string; refundable?: boolean; paymentType?: string; conditionalRule?: string; } ``` `RoomID` ve `PackageID` provider adapter concern olmalı; canonical room/rate identity ile bire bir aynı olmak zorunda değildir. ## 9. Taxes, fees ve total price Google pricing'de base, tax ve other fee component'leri ayrı taşınabilir. Kendi modelinizde de bunları flatten etmeyin. ```ts interface PriceBreakdown { base: number; taxes: number; mandatoryFees: number; payAtProperty?: number; total: number; currency: string; } ``` Kontrol: ```text total = base + taxes + mandatory fees ``` Ancak pay-at-property ve market-specific component'ler için display semantics ayrıca tanımlanmalıdır. En yaygın hata: > Google'a base rate göndermek ama landing page'de mandatory fee sonrası daha yüksek total göstermek. Bu doğrudan price accuracy problemine dönüşür. ## 10. Occupancy ve child pricing Occupancy cache key'in bir parçası olmalıdır. ```text hotel + check-in + nights + adults + child ages + currency + market ``` Google'ın güncel Transaction dokümantasyonu child occupancy rates için context-aware live pricing sınırına özellikle dikkat çeker. Child pricing'i generic double-occupancy cache'e sıkıştırmak yanlış sonuç üretir. Örnek: ```ts interface Occupancy { adults: number; childAges: number[]; } ``` ```text 2 adults != 2 adults + child age 7 ``` ## 11. Changed Pricing Hint modeli Change detection yapabiliyorsanız internal event üretin: ```ts interface PriceChangeEvent { hotelId: string; firstAffectedDate: string; lastAffectedDate?: string; nights?: number; changedAt: string; version: number; } ``` Bundan Google Hint üretilebilir: ```xml HTL-84721 2026-10-10 3 ``` Change event idempotent olmalı; aynı version tekrar işlendiğinde gereksiz inconsistent state yaratmamalıdır. ## 12. Landing page entegrasyonu Google landing page dosyasının root elementi ``'dır ve her landing hedefi `` ile tanımlanır. Buradaki asıl developer problemi URL template değil **context preservation**'dır. Booking engine URL: ```text https://booking.example.com/hotel/{hotelId} ?checkin={checkIn} &checkout={checkOut} &adults={adults} ¤cy={currency} &click_id={trackingId} ``` Internal handoff modeli: ```ts interface BookingHandoff { hotelId: string; checkIn: string; checkOut: string; occupancy: Occupancy; currency: string; roomId?: string; ratePlanId?: string; clickId: string; } ``` Test yalnız URL'nin açılması değildir. Doğrulayın: - doğru hotel, - doğru dates, - occupancy, - currency, - selected room/rate, - total price, - mobile redirect, - attribution ID. ## 13. Travel Partner API nerede kullanılır? Travel Partner API pricing XML transport'unun yerine geçen generic booking API değildir. Hotel Center hesabı ve diagnostic/management verisi için ayrı bir API surface'tir. Örnek authorization header: ```http Authorization: Bearer ``` Conceptual request: ```http GET https://travelpartner.googleapis.com/v3/accounts/123456/priceAccuracyViews/latest Authorization: Bearer ``` Internal API client boundary: ```ts interface GoogleTravelPartnerClient { getPriceAccuracyView(accountId: string, viewId: string): Promise; getAccountDiagnostics(accountId: string): Promise; } ``` Google API DTO'larını doğrudan dashboard domain modeliniz yapmayın. ## 14. Price accuracy feedback loop Google structured-data ve price-accuracy mekanizmaları landing tarafındaki visible price ile gönderdiğiniz pricing bilgisinin tutarlılığını doğrulamaya yardımcı olur. Internal loop: ```text Price submitted | v Google displays offer | v Landing page validation | +--> match | +--> mismatch | +--> classify reason +--> provider/hotel alert +--> freshness policy update +--> mapping/rate fix ``` Mismatch taxonomy: ```text TAX_MISMATCH MANDATORY_FEE_MISMATCH STALE_PRICE WRONG_ROOM WRONG_ITINERARY CONDITIONAL_RATE LANDING_CONTEXT_LOST UNAVAILABLE UNKNOWN ``` ## 15. Timeout, retry ve error handling Tüm error'ları aynı retry policy ile ele almayın. ### Retryable - transient network failure, - selected 5xx, - temporary timeout, - quota/rate-limit condition uygun backoff ile. ### Non-retryable veya manual-fix - invalid XML, - Hotel List ID mismatch, - schema validation, - unsupported currency, - malformed occupancy, - invalid landing config. Örnek policy: ```ts interface RetryPolicy { maxAttempts: number; initialBackoffMs: number; maxBackoffMs: number; retryableStatusCodes: number[]; } ``` Google-specific error'ı internal taxonomy'ye map edin: ```text GOOGLE_AUTH GOOGLE_SCHEMA GOOGLE_MAPPING GOOGLE_RATE_LIMIT GOOGLE_TIMEOUT GOOGLE_UPSTREAM GOOGLE_PRICE_REJECTED GOOGLE_LANDING_ERROR ``` ## 16. Idempotency ve ordering Transaction message'da unique ID kullanılması debugging için kritiktir. Ayrıca Google dokümantasyonu Transaction processing'de timestamp semantics'ini önemser. Eski state'in yeni state üzerine yazmasını önlemek için internal version/order kontrolünüz olmalı. ```ts interface PricingUpdateEnvelope { eventId: string; hotelId: string; version: number; sourceUpdatedAt: string; generatedAt: string; } ``` Rule: ```text older version -> ignore same version -> idempotent no-op new version -> publish ``` ## 17. Persistence ve audit Her XML payload'ı sonsuza kadar full blob olarak saklamak şart değildir; fakat replay/debug için yeterli lineage tutulmalıdır. Örnek: ```text google_price_updates - event_id - hotel_id - check_in - nights - occupancy_key - source_version - base_amount - tax_amount - fee_amount - currency - generated_at - sent_at - result_status - retry_count - payload_hash ``` Raw payload için object storage reference kullanılabilir. ## 18. Monitoring ve SLO ### Property identity - Hotel List accepted count, - mapping coverage, - unmatched hotels, - duplicate/review queue. ### Pricing - query count, - transaction success, - p95 response latency, - stale age, - changed-pricing event lag, - rejected message count. ### Quality - price accuracy, - tax/fee mismatch, - unavailable-after-click, - landing context success. ### Commercial - Google click → booking conversion, - cancellation-adjusted conversion, - unattributed booking, - revenue by freshness bucket. Örnek SLO: ```text mapping coverage >= 99% p95 pricing response <= internal budget offers under freshness threshold >= 97% severe price mismatch < 1% landing context success >= 99% ``` Rakamlar kendi account/supply profile'ınıza göre belirlenmelidir. ## 19. Integration test matrisi | Test | Beklenen | |---|---| | 1 gece / 2 adult | base happy path | | 3 gece | stay total doğru | | child occupancy | child context korunuyor | | refundable | policy doğru | | non-refundable | policy doğru | | tax-heavy market | total doğru | | mandatory property fee | disclosure doğru | | currency change | correct currency | | sold out | offer kaldırılıyor | | price changed | fresh response | | hotel renamed | stable ID | | hotel closed | listing state güncel | | mobile landing | context korunuyor | | expired/stale cache | revalidation/fallback doğru | | duplicate event | idempotent | ## 20. Go-live checklist - Hotel Center / partner access hazır - Service account yetkili - Canonical hotel IDs stable - Hotel List validation tamam - Mapping coverage dashboard hazır - Pricing delivery mode seçildi - Google Query parser test edildi - Transaction serializer schema-valid - Room/rate semantics normalize - Tax/fee breakdown doğru - Occupancy/child cases test edildi - Changed Pricing/ARI event ordering güvenli - Landing pages context-preserving - OAuth token rotation/refresh çalışıyor - Retry taxonomy uygulanmış - Idempotency uygulanmış - Price accuracy dashboard var - Alert'ler provider/hotel seviyesinde - Conversion reconciliation ownership belli ## Sonuç Google Hotels entegrasyonunu “Google'a XML gönderme işi” olarak kurarsanız sistem kısa sürede provider-specific logic ile dolar. Daha sağlam model: ```text canonical domain -> Google adapter -> Google XML/API contract -> diagnostics -> quality feedback ``` şeklindedir. Developer açısından başarı kriteri yalnız feed'in accepted olması değildir. Aynı hotel identity'sinin, aynı occupancy ve rate semantics'inin, doğru total price'ın ve doğru landing context'inin Google result'tan booking engine'e kadar korunmasıdır.