本頁面提供一些使用 Travel Partner API v3 的呼叫範例。
Travel Partner API 端點會透過 HTTPS 呼叫使用符合 REST 樣式的語法。所有 API 要求的 base_url 如下：
https://travelpartner.googleapis.com/v3/accounts/account_id
如需完整的要求與回應欄位清單，請參閱 API 資源目錄。
資源成效報表資料檢視服務可讓您查詢 (取得、篩選及區隔) 特定帳戶的資源成效報表。
以下範例列出了 12345678 帳戶所有資源的資源成效報表，依 2022 年 5 月 11 日篩選，並按合作夥伴飯店 ID 分組。
GET https://travelpartner.googleapis.com/v3/accounts/12345678/propertyPerformanceReportViews:query?filter=date%20%3D%20%272022-05-11%27&aggregateBy=partnerPropertyId
回應範例
{
"results": [
{
"partnerPropertyId": "10001",
"clickCount": "47"
"impressionCount": "360"
},
{
"partnerPropertyId": "10003",
"clickCount": "23"
"impressionCount": "400"
},
{
"partnerPropertyId": "10007",
"clickCount": "106"
"impressionCount": "780"
},
{
"partnerPropertyId": "10009",
"clickCount": "81"
"impressionCount": "520"
},
]
}
飯店
飯店檢視服務會提供所有飯店的清單，或是特定帳戶的摘要。
取得飯店清單
以下範例會擷取 12345678 帳戶中的所有飯店清單：
GET https://travelpartner.googleapis.com/v3/accounts/12345678/hotelviews
此要求接受查詢參數，以便在多頁結果中瀏覽：
GET base_url/hotelviews?pageSize=10&pageToken=11
回應範例
{
"nextPageToken": "11",
"hotelViews": [
{
"googleHotelDisplayName": "Alameda Hotel",
"googleHotelId": "11111111111111111111",
"partnerHotelDisplayName": "Alameda Hotel",
"partnerHotelId": "10",
"dataIssues": [
"MISSING_STREET_NUMBER"
],
"googleClusterId": "1131326789990787753"
},
{
"googleClusterId": "11390920309628839218",
"googleHotelDisplayName": "At Hotel",
"googleHotelId": "9999999999999999999",
"partnerHotelDisplayName": "At Hotel and Restaurant",
"partnerHotelId": "100001"
},
...
{
"googleHotelDisplayName": "Aquapark & Spa Hotel",
"googleHotelId": "444444444444444444",
"partnerHotelDisplayName": "Aquapark & Spa Hotel",
"partnerHotelId": "100069",
"dataIssues": [
"MISSING_PHONE_NUMBER",
"MISSING_STREET_NUMBER",
"LATLONG_INCONSISTENT_WITH_ADDRESS"
],
"googleClusterId": "18401597592098761505"
}
]
}
取得屬性摘要
以下範例會取得帳戶 12345678 的資源摘要：
GET https://travelpartner.googleapis.com/v3/accounts/12345678/hotelviews:summarize
回應範例
{
"lastManifestUpdateTime": "2019-09-26T18:24:54.479972Z",
"matchedPropertyCount": "206107",
"overclusteredPropertyWithErrorsCount": "16927",
"overclusteredPropertyCount": "17611",
"unmatchedPropertyWithErrorsCount": "93638",
"lastFeedSubmissionTime": "2019-09-19T20:51:08Z",
"unmatchedPropertyCount": "99673"
}
參與
參與報表資料檢視服務可讓您查詢 (取得、篩選及區隔) 特定帳戶的參與報表。
查詢參與報表
以下範例會取得 12345678 帳戶所有資源的參與報表，並使用日期 2020 年 10 月 4 日篩選報表。
GET https://travelpartner.googleapis.com/v3/accounts/12345678/participationReportViews:query?filter=date%20%3D%20%272020-10-04%27
回應範例
{
"results": [
{
"missedParticipationCountDetails": {
"noAvailabilityCount": "628873",
"otherReasonCount": "22",
"hotelSuspendedCount": "262",
"noTaxBreakdownCount": "1",
"noLandingPageCount": "4558",
"noPriceCount": "43194",
"noPriceCountDetails": {
"livePricingTechnicalIssueCount": "4795",
"livePricingNotTriggeredCount": "2",
"livePricingConfigIssueCount": "3",
"livePricingNotAvailableCount": "27731",
"livePricingOtherReasonCount": "1"
}
"otherReasonCount": "1"
"priceMissingCount": "2235",
"priceMissingCountDetails": {
"cacheRateMissingCount": "2030",
"itineraryBlockedCount": "196",
"livePricingNotSetupCount": "0",
"bandwidthDepletedCount": "1",
"livePricingTimeoutCount": "8",
"livePricingErrorCount": "0"
}
"priceProblemCount": "0",
"priceProblemCountDetails": {
"hotelSuspendedCount": "0",
"priceUnusuallyHighCount": "0",
"priceUnusuallyLowCount": "0",
"taxesAndFeesMissingCount": "0"
}
"priceUnavailableCount": "0",
"priceUnavailableCountDetails": {
"priceUnavailableCount": "0",
"participationNotLikelyCount": "0"
}
},
"participationCount": "1298876",
"missedParticipationCount": "679146",
"opportunityCount": "1975787",
"participationPercent": 0.6573967740444975
}
]
}
價格準確性
價格準確性檢視服務可讓您擷取特定帳戶的價格準確度報表和評量表。
取得價格準確性報表
以下範例擷取了 2019 年 8 月 26 日帳戶 12345678 的價格準確性報表：
GET https://travelpartner.googleapis.com/v3/accounts/12345678/priceAccuracyViews/20190826
除了透過回應分頁的常見查詢參數外，您還必須在搜尋結果中加入比對成功的價格或像素信號。
在這個範例中，2019 年 8 月 26 日的價格準確性報表包含相符的價格和像素信號：
GET base_url/priceAccuracyViews/20190826?includeMatchedPrices=true&includePixels=true
列出可用價格準確性報表
如要取得可用報表的清單，請傳送這項要求：
GET https://travelpartner.googleapis.com/v3/accounts/12345678/priceAccuracyViews
您可以加入一般查詢參數的查詢參數。
回應範例
{
"priceAccuracyViews": [
{
"name": "accounts/12345678/priceAccuracyViews/20190925"
},
...
{
"name": "accounts/12345678/priceAccuracyViews/20190827"
}
]
}
取得價格準確性分數
如要取得價格準確性評量表，請使用 summarize 方法：
GET https://travelpartner.googleapis.com/v3/accounts/12345678/priceAccuracyViews:summarize
回應範例
{
"updateTime": "2019-09-26T18:29:32.372204Z",
"currentScore": "EXCELLENT",
"predictedScore": "EXCELLENT"
}
價格涵蓋範圍
價格涵蓋範圍檢視服務提供最新的價格涵蓋率報表，或完整的價格涵蓋率記錄。
取得最新的價格範圍統計資料
以下範例會擷取帳戶 12345678 的最新價格涵蓋率統計資料：
GET https://travelpartner.googleapis.com/v3/accounts/12345678/priceCoverageViews:latest
回應範例
{
"calculationDate": {
"month": 10,
"day": 1,
"year": 2019
},
"priceCoveragePercent": 7.683124346337668,
"matchedPropertyCount": 486546,
"priceCoverageBuckets": [
{
"availablePriceCount": "57708897",
"advanceBookingWindowRange": "DAYS_0_TO_30",
"priceCoveragePercent": 54.65867924338515,
"lengthOfStayRange": "LENGTH_OF_STAY_1_TO_7"
},
{
"availablePriceCount": "44221",
"advanceBookingWindowRange": "DAYS_0_TO_30",
"priceCoveragePercent": 0.04188368831276978,
"lengthOfStayRange": "LENGTH_OF_STAY_8_TO_14"
},
{
"availablePriceCount": "59988397",
"advanceBookingWindowRange": "DAYS_31_TO_60",
"priceCoveragePercent": 58.71161890824986,
"lengthOfStayRange": "LENGTH_OF_STAY_1_TO_7"
},
{
"availablePriceCount": "8805",
"advanceBookingWindowRange": "DAYS_31_TO_60",
"priceCoveragePercent": 0.008617596574336533,
"lengthOfStayRange": "LENGTH_OF_STAY_8_TO_14"
},
{
"availablePriceCount": "55096752",
"advanceBookingWindowRange": "DAYS_61_TO_90",
"priceCoveragePercent": 53.9240864613594,
"lengthOfStayRange": "LENGTH_OF_STAY_1_TO_7"
},
{
"availablePriceCount": "11747",
"advanceBookingWindowRange": "DAYS_61_TO_90",
"priceCoveragePercent": 0.011496979779526548,
"lengthOfStayRange": "LENGTH_OF_STAY_8_TO_14"
},
{
"availablePriceCount": "117074",
"advanceBookingWindowRange": "DAYS_91_TO_120",
"priceCoveragePercent": 0.11458222616057641,
"lengthOfStayRange": "LENGTH_OF_STAY_1_TO_7"
},
{
"availablePriceCount": "7527",
"advanceBookingWindowRange": "DAYS_91_TO_120",
"priceCoveragePercent": 0.007366797207839987,
"lengthOfStayRange": "LENGTH_OF_STAY_8_TO_14"
},
{
"availablePriceCount": "71904",
"advanceBookingWindowRange": "DAYS_121_TO_150",
"priceCoveragePercent": 0.07037361318354277,
"lengthOfStayRange": "LENGTH_OF_STAY_1_TO_7"
},
{
"availablePriceCount": "5544",
"advanceBookingWindowRange": "DAYS_121_TO_150",
"priceCoveragePercent": 0.005426002885646989,
"lengthOfStayRange": "LENGTH_OF_STAY_8_TO_14"
},
{
"availablePriceCount": "56528",
"advanceBookingWindowRange": "DAYS_151_TO_180",
"priceCoveragePercent": 0.05532487213561562,
"lengthOfStayRange": "LENGTH_OF_STAY_1_TO_7"
},
{
"availablePriceCount": "4680",
"advanceBookingWindowRange": "DAYS_151_TO_180",
"priceCoveragePercent": 0.00458039204632538,
"lengthOfStayRange": "LENGTH_OF_STAY_8_TO_14"
},
{
"availablePriceCount": "29269",
"advanceBookingWindowRange": "DAYS_181_TO_210",
"priceCoveragePercent": 0.02864604589826871,
"lengthOfStayRange": "LENGTH_OF_STAY_1_TO_7"
},
{
"availablePriceCount": "2336",
"advanceBookingWindowRange": "DAYS_181_TO_210",
"priceCoveragePercent": 0.0022862811581658314,
"lengthOfStayRange": "LENGTH_OF_STAY_8_TO_14"
},
{
"availablePriceCount": "22967",
"advanceBookingWindowRange": "DAYS_211_TO_240",
"priceCoveragePercent": 0.022478176095716885,
"lengthOfStayRange": "LENGTH_OF_STAY_1_TO_7"
},
{
"availablePriceCount": "1906",
"advanceBookingWindowRange": "DAYS_211_TO_240",
"priceCoveragePercent": 0.001865433171003456,
"lengthOfStayRange": "LENGTH_OF_STAY_8_TO_14"
},
{
"availablePriceCount": "19387",
"advanceBookingWindowRange": "DAYS_241_TO_270",
"priceCoveragePercent": 0.01897437192352781,
"lengthOfStayRange": "LENGTH_OF_STAY_1_TO_7"
},
{
"availablePriceCount": "2179",
"advanceBookingWindowRange": "DAYS_241_TO_270",
"priceCoveragePercent": 0.0021326227070391033,
"lengthOfStayRange": "LENGTH_OF_STAY_8_TO_14"
},
{
"availablePriceCount": "14102",
"advanceBookingWindowRange": "DAYS_271_TO_300",
"priceCoveragePercent": 0.013801856546427458,
"lengthOfStayRange": "LENGTH_OF_STAY_1_TO_7"
},
{
"availablePriceCount": "2048",
"advanceBookingWindowRange": "DAYS_271_TO_300",
"priceCoveragePercent": 0.0020044108783919615,
"lengthOfStayRange": "LENGTH_OF_STAY_8_TO_14"
},
{
"availablePriceCount": "10280",
"advanceBookingWindowRange": "DAYS_301_TO_330",
"priceCoveragePercent": 0.010061203041928398,
"lengthOfStayRange": "LENGTH_OF_STAY_1_TO_7"
},
{
"availablePriceCount": "1333",
"advanceBookingWindowRange": "DAYS_301_TO_330",
"priceCoveragePercent": 0.0013046287602033614,
"lengthOfStayRange": "LENGTH_OF_STAY_8_TO_14"
}
],
"priceCoverageBinaryPercent": 76.38722751805585
}
取得價格涵蓋範圍記錄
這項要求會取得帳戶的完整價格涵蓋率記錄：
GET https://travelpartner.googleapis.com/v3/accounts/12345678/priceCoverageViews
回應範例
{
"priceCoverageViews": [
{
"calculationDate": {
"month": 9,
"day": 17,
"year": 2019
},
"priceCoveragePercent": 7.75351958685931,
"matchedPropertyCount": 492550,
"priceCoverageBuckets": [
{
"availablePriceCount": "57557901",
"advanceBookingWindowRange": "DAYS_0_TO_30",
"priceCoveragePercent": 53.85113864788107,
"lengthOfStayRange": "LENGTH_OF_STAY_1_TO_7"
},
{
"availablePriceCount": "40549",
"advanceBookingWindowRange": "DAYS_0_TO_30",
"priceCoveragePercent": 0.037937620780037304,
"lengthOfStayRange": "LENGTH_OF_STAY_8_TO_14"
},
{
"availablePriceCount": "60927294",
"advanceBookingWindowRange": "DAYS_31_TO_60",
"priceCoveragePercent": 58.90365880186203,
"lengthOfStayRange": "LENGTH_OF_STAY_1_TO_7"
},
{
"availablePriceCount": "9151",
"advanceBookingWindowRange": "DAYS_31_TO_60",
"priceCoveragePercent": 0.00884705927848756,
"lengthOfStayRange": "LENGTH_OF_STAY_8_TO_14"
},
{
"availablePriceCount": "58125328",
"advanceBookingWindowRange": "DAYS_61_TO_90",
"priceCoveragePercent": 56.19475711917089,
"lengthOfStayRange": "LENGTH_OF_STAY_1_TO_7"
},
{
"availablePriceCount": "6943",
"advanceBookingWindowRange": "DAYS_61_TO_90",
"priceCoveragePercent": 0.0067123956475291366,
"lengthOfStayRange": "LENGTH_OF_STAY_8_TO_14"
},
{
"availablePriceCount": "112206",
"advanceBookingWindowRange": "DAYS_91_TO_120",
"priceCoveragePercent": 0.10847919718085183,
"lengthOfStayRange": "LENGTH_OF_STAY_1_TO_7"
},
{
"availablePriceCount": "9665",
"advanceBookingWindowRange": "DAYS_91_TO_120",
"priceCoveragePercent": 0.00934398731576683,
"lengthOfStayRange": "LENGTH_OF_STAY_8_TO_14"
},
{
"availablePriceCount": "42373",
"advanceBookingWindowRange": "DAYS_121_TO_150",
"priceCoveragePercent": 0.04096562592146797,
"lengthOfStayRange": "LENGTH_OF_STAY_1_TO_7"
},
{
"availablePriceCount": "4123",
"advanceBookingWindowRange": "DAYS_121_TO_150",
"priceCoveragePercent": 0.0039860589449463675,
"lengthOfStayRange": "LENGTH_OF_STAY_8_TO_14"
},
{
"availablePriceCount": "34813",
"advanceBookingWindowRange": "DAYS_151_TO_180",
"priceCoveragePercent": 0.033656723271990756,
"lengthOfStayRange": "LENGTH_OF_STAY_1_TO_7"
},
{
"availablePriceCount": "3296",
"advanceBookingWindowRange": "DAYS_151_TO_180",
"priceCoveragePercent": 0.003186526869401704,
"lengthOfStayRange": "LENGTH_OF_STAY_8_TO_14"
},
{
"availablePriceCount": "26839",
"advanceBookingWindowRange": "DAYS_181_TO_210",
"priceCoveragePercent": 0.02594757119170884,
"lengthOfStayRange": "LENGTH_OF_STAY_1_TO_7"
},
{
"availablePriceCount": "2188",
"advanceBookingWindowRange": "DAYS_181_TO_210",
"priceCoveragePercent": 0.00211532790966351,
"lengthOfStayRange": "LENGTH_OF_STAY_8_TO_14"
},
{
"availablePriceCount": "20301",
"advanceBookingWindowRange": "DAYS_211_TO_240",
"priceCoveragePercent": 0.0196267239004017,
"lengthOfStayRange": "LENGTH_OF_STAY_1_TO_7"
},
{
"availablePriceCount": "1589",
"advanceBookingWindowRange": "DAYS_211_TO_240",
"priceCoveragePercent": 0.0015362230568808583,
"lengthOfStayRange": "LENGTH_OF_STAY_8_TO_14"
},
{
"availablePriceCount": "17661",
"advanceBookingWindowRange": "DAYS_241_TO_270",
"priceCoveragePercent": 0.01707440868947315,
"lengthOfStayRange": "LENGTH_OF_STAY_1_TO_7"
},
{
"availablePriceCount": "1768",
"advanceBookingWindowRange": "DAYS_241_TO_270",
"priceCoveragePercent": 0.0017092777624703316,
"lengthOfStayRange": "LENGTH_OF_STAY_8_TO_14"
},
{
"availablePriceCount": "14245",
"advanceBookingWindowRange": "DAYS_271_TO_300",
"priceCoveragePercent": 0.013771867492301967,
"lengthOfStayRange": "LENGTH_OF_STAY_1_TO_7"
},
{
"availablePriceCount": "2019",
"advanceBookingWindowRange": "DAYS_271_TO_300",
"priceCoveragePercent": 0.0019519410647214931,
"lengthOfStayRange": "LENGTH_OF_STAY_8_TO_14"
},
{
"availablePriceCount": "10625",
"advanceBookingWindowRange": "DAYS_301_TO_330",
"priceCoveragePercent": 0.010272101937922665,
"lengthOfStayRange": "LENGTH_OF_STAY_1_TO_7"
},
{
"availablePriceCount": "1401",
"advanceBookingWindowRange": "DAYS_301_TO_330",
"priceCoveragePercent": 0.0013544672767086734,
"lengthOfStayRange": "LENGTH_OF_STAY_8_TO_14"
}
],
"priceCoverageBinaryPercent": 77.83737691604914
},
...
]
}
價格
價格瀏覽服務可讓您擷取特定資源的價格報表。
取得房源的定價資料
如要取得帳戶 12345678 中特定飯店 (ID=101) 的定價報表，請發出這項要求：
GET https://travelpartner.googleapis.com/v3/accounts/12345678/priceViews/101
回應範例
{
"perItineraryPrices": [
{
"updateTime": "2019-09-30T23:24:32Z",
"checkinDate": {
"month": 9,
"day": 30,
"year": 2019
},
"taxes": 8.83,
"currencyCode": "USD",
"lengthOfStayDays": 1,
"roomAvailable": true,
"price": 68.25
},
...
{
"updateTime": "2019-10-02T03:32:22.347810Z",
"checkinDate": {
"month": 4,
"day": 23,
"year": 2020
},
"currencyCode": "USD",
"price": -1,
"lengthOfStayDays": 3,
"allInclusive": true
}
],
"name": "accounts/12345678/priceViews/101"
}
對帳報告
對帳報告服務
取得對帳報告清單
以下範例會取得帳戶 12345678 的報表：
GET https://travelpartner.googleapis.com/v3/accounts/12345678/reconciliationReports
您可以加入選用的開始和結束日期參數來限制結果。舉例來說，這項查詢可將報表限制在 2019 年 6 月 15 日至 2019 年 9 月 15 日之間的報表：
GET base_url/reconciliationReports?startDate=2019-06-15&endDate=2019-09-15
回應範例
{
"reconciliationReports": [
{
"name": "accounts/12345678/reconciliationReports/2019-09-19T08:32:00~booking_report.csv"
}
]
}
下載對帳報告
此範例會擷取在 2019-08-26T12:00:00 上傳的 booking_report.csv 報表 (做為 JSON 回應)：
GET base_url/reconciliationReports/2019-08-26T12%3A00%3A00~bookings.csv
回應範例
{
"contents": "Hotel ID,Hotel Name,Hotel Address,Hotel City,Hotel State/Region,Hotel PostalCode,Hotel Country Code,Hotel Phone Number,Booking Reference,Booking Date and Time,Check-in Date,Check-out Date,Number of Rooms,Number of Guests,Booking Revenue,Booking Revenue Currency,Booking Revenue Currency to Billing Currency Conversion Rate,Booking Status,Commission,Commission Currency,Commission Currency to Billing Currency Conversion Rate,Payment Date,Payment Status\n\n111,\"Capybara Hotel and Spa\",123 Foo Driveway,Boston,MA,02472,US,+11234567890,2thHRTY,2016-01-04,2016-02-01,2016-02-03,1,4,213.88,USD,1,Stayed,21.39,USD,1.0,2016-06-07,Invoice Required\n\n211,\"Mabels Gabels\",45678 Bar Street,London,,KT13 0PU,GB,+440203456123,z452121A,2016-02-04,2016-02-01,2016-02-03,1,3,414.21,GBP,1.249,Stayed,64.43,USD,1.0,2016-06-07,Invoice Required\n\n311,\"No-Tell Motels\",66 Acacia Avenue,Geneva,,1211,CH,+412241820000,42,2016-03-04,2016-02-01,2016-02-03,1,2,451.15,CHF,1.05,Stayed,37.41,EUR,0.99889,2016-06-07,Invoice Required"
}
驗證對帳報告
在上傳報表之前，您可以使用這種方法來驗證報表。驗證報表並不會上傳檔案。
請求的對帳報告會包含在要求內文中，做為 contents 欄位的值。對帳報告必須符合對帳報告一節中的語法。
以下範例會驗證帳戶 12345678 的報表：
POST https://travelpartner.googleapis.com/v3/accounts/12345678/reconciliationReports:validate
成功回應範例
{
"successfulRecordCount": 3
}
上傳對帳報告
確認對帳報告有效後，即可將其上傳至 Google，如以下範例所示：
POST https://travelpartner.googleapis.com/v3/accounts/12345678/reconciliationReports
成功回應範例
{
"successfulRecordCount": 3,
"reconciliationReport": {
"name": "accounts/12345678/reconciliationReports/2019-09-30T09:17~2019-09-19T08:32:00~booking_report.csv"
}
}
