تعرض هذه الصفحة بعض نماذج المكالمات باستخدام الإصدار 3 من واجهة برمجة تطبيقات شركاء السفر.
تستخدم نقاط نهاية واجهة برمجة تطبيقات شركاء السفر بنية REST-ful عبر استدعاءات HTTPS. base_url لجميع طلبات البيانات من واجهة برمجة التطبيقات هي:
https://travelpartner.googleapis.com/v3/accounts/account_id
للحصول على قائمة كاملة بحقول الطلبات والردود، يُرجى الاطّلاع على كتالوج موارد واجهة برمجة التطبيقات.
تقرير أداء الموقع
توفّر خدمة عرض تقرير أداء الموقع إمكانية طلب (تقرير وفلترة وتقسيم) تقرير أداء الموقع لحساب معيّن.
طلب البحث عن تقرير أداء الموقع
يحصل المثال التالي على تقرير أداء الموقع لجميع المواقع في الحساب 12345678، وتتم فلترته حتى تاريخ 11 أيار (مايو) 2022، ويتم تجميعه حسب رقم تعريف فندق الشريك.
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
يقبل الطلب معلّمات طلب البحث للتنقّل بين النتائج المتعددة الصفحات:
GETbase_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 ويفلتر التقرير باستخدام تاريخ 10/4/20.
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
}
]
}
دقة السعر
تتيح خدمة الاطّلاع على دقة السعر استرداد تقارير دقة الأسعار وبطاقات قياس الأداء لحساب معيّن.
الحصول على تقرير دقة الأسعار
يسترد المثال التالي تقرير دقة السعر في 26/8/2019 للحساب 12345678:
GET https://travelpartner.googleapis.com/v3/accounts/12345678/priceAccuracyViews/20190826
إلى جانب معلَمات طلب البحث العادية للتنقّل بين الردود، هناك بضعة عوامل أخرى لتضمين الأسعار المتطابقة أو إشارات البكسل في النتائج.
في هذا المثال، يشمل تقرير دقة الأسعار في 26/8/2019 الأسعار المطابقة وإشارات البكسل:
GETbase_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
},
...
]
}
السعر
تتيح لك خدمة الاطّلاع على الأسعار إمكانية استرداد تقرير السعر لموقع معيّن.
الحصول على بيانات الأسعار لأحد المواقع
للحصول على تقرير الأسعار لفندق معيّن (رقم التعريف=101) ينتمي إلى الحساب 12345678، يُرجى إصدار هذا الطلب:
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
ويمكنك تضمين معلّمات طلب البحث الاختيارية لتاريخ البدء والانتهاء للحدّ من النتائج. على سبيل المثال، يقتصر طلب البحث هذا على التقارير بين 6/15/2019 و9/15/2019 فقط:
GETbase_url /reconciliationReports?startDate=2019-06-15&endDate=2019-09-15
نموذج إجابة
{
"reconciliationReports": [
{
"name": "accounts/12345678/reconciliationReports/2019-09-19T08:32:00~booking_report.csv"
}
]
}
جارٍ تنزيل تقرير تسوية
يسترد هذا المثال تقرير booking_report.csv (كاستجابة JSON) الذي تم تحميله في 2019-08-26T12:00:00:
GETbase_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"
}
}