استخدام رموز الجلسات
تجمِّع رموز الجلسات مراحل طلب البحث والاختيار في عملية بحث المستخدم عن الإكمال التلقائي في جلسة منفصلة لأغراض الفوترة. تعرض الأمثلة التالية كيفية استخدام الرموز المميزة للجلسات في طلبات بيانات من واجهتَي برمجة التطبيقات Autocomplete (New) وPlace Details (New).
إنشاء الرمز المميز للجلسة
تقع على عاتق المستخدمين مسؤولية إنشاء رموز جلسات فريدة لكل جلسة. تنصح Google باستخدام معرّفات UUID الإصدار 4.
إرسال طلب بيانات من واجهة برمجة التطبيقات Autocomplete (New)
طلب البيانات من واجهة برمجة التطبيقات Autocomplete (New) هو طلب HTTP POST. لمزيد من المعلومات عن مَعلمات نص الطلب، يُرجى الاطّلاع على طلبات البيانات من واجهة برمجة التطبيقات Autocomplete (New).
تعرض سلسلة الطلبات التالية مستخدمًا يبحث عن متجر بيتزا في سان فرانسيسكو. عندما يبدأ المستخدم بكتابة طلب بحث، يتم استدعاء واجهة برمجة التطبيقات Autocomplete (New) لكل ضغطة مفتاح. ويتم تمرير الرمز المميز للجلسة الذي تم إنشاؤه كمعلَمة في كل طلب.
الطلب والاستجابة الأولان
الطلب 1
curl -X POST -d '{
"input": "p",
"sessionToken": "3519edfe-0f75-4a30-bfe4-7cbd89340b2c",
"locationBias": {
"circle": {
"center": {
"latitude": 37.7937,
"longitude": -122.3965
},
"radius": 500.0
}
}
}' -H 'Content-Type: application/json' -H "X-Goog-Api-Key: YOUR_API_KEY" \
https://places.googleapis.com/v1/places:autocomplete
الاستجابة 1
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJHSGzi_yAhYARnrPmDWAx9ro", "placeId": "ChIJHSGzi_yAhYARnrPmDWAx9ro", "text": { "text": "PIER 39, The Embarcadero, San Francisco, CA, USA", "matches": [ { "endOffset": 1 } ] }, "structuredFormat": { "mainText": { "text": "PIER 39", "matches": [ { "endOffset": 1 } ] }, "secondaryText": { "text": "The Embarcadero, San Francisco, CA, USA" } }, "types": [ "historical_landmark", "shopping_mall", "point_of_interest", "establishment", "marina", "tourist_attraction" ] } }, ] / ... / }
الطلب والاستجابة الثانيان
الطلب 2
curl -X POST -d '{
"input": "pi",
"sessionToken": "3519edfe-0f75-4a30-bfe4-7cbd89340b2c",
"locationBias": {
"circle": {
"center": {
"latitude": 37.7937,
"longitude": -122.3965
},
"radius": 500.0
}
}
}' -H 'Content-Type: application/json' -H "X-Goog-Api-Key: YOUR_API_KEY" \
https://places.googleapis.com/v1/places:autocomplete
الاستجابة 2
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJHSGzi_yAhYARnrPmDWAx9ro", "placeId": "ChIJHSGzi_yAhYARnrPmDWAx9ro", "text": { "text": "PIER 39, The Embarcadero, San Francisco, CA, USA", "matches": [ { "endOffset": 2 } ] }, "structuredFormat": { "mainText": { "text": "PIER 39", "matches": [ { "endOffset": 2 } ] }, "secondaryText": { "text": "The Embarcadero, San Francisco, CA, USA" } }, "types": [ "establishment", "point_of_interest", "shopping_mall", "marina", "historical_landmark", "tourist_attraction" ] } }, /.../ ] }
الطلب والاستجابة الثالثان
الطلب 3
curl -X POST -d '{
"input": "piz",
"sessionToken": "3519edfe-0f75-4a30-bfe4-7cbd89340b2c",
"locationBias": {
"circle": {
"center": {
"latitude": 37.7937,
"longitude": -122.3965
},
"radius": 500.0
}
}
}' -H 'Content-Type: application/json' -H "X-Goog-Api-Key: YOUR_API_KEY" https://places.googleapis.com/v1/places:autocomplete
الاستجابة 3
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJ_QJSSfGAhYARQVFJBNKy3HE", "placeId": "ChIJ_QJSSfGAhYARQVFJBNKy3HE", "text": { "text": "Pizza By The Slice, Grant Avenue, San Francisco, CA, USA", "matches": [ { "endOffset": 3 } ] }, "structuredFormat": { "mainText": { "text": "Pizza By The Slice", "matches": [ { "endOffset": 3 } ] }, "secondaryText": { "text": "Grant Avenue, San Francisco, CA, USA" } }, "types": [ "establishment", "point_of_interest", "food", "pizza_restaurant", "restaurant" ] } }, /.../ ] }
إنهاء الجلسة
يمكنك إنهاء الجلسة عن طريق إرسال طلب بيانات إلى واجهة برمجة التطبيقات Place Details (New) أو Address Validation وتمرير الرمز المميز للجلسة نفسه الذي استخدمته لطلبات البيانات من واجهة برمجة التطبيقات Autocomplete (New).
إرسال طلب بيانات من واجهة برمجة التطبيقات Place Details (New)
طلب تفاصيل المكان (جديد) هو طلب استرداد بيانات باستخدام GET. لمزيد من المعلومات عن مَعلمات نص الطلب، يُرجى الاطّلاع على طلبات البيانات من واجهة برمجة التطبيقات Place Details (New).
يتضمّن طلب البيانات التالي من واجهة برمجة التطبيقات Place Details (New) id للمكان الذي تم اختياره وsessionToken المستخدَم في طلبات البيانات السابقة من واجهة برمجة التطبيقات Autocomplete (New).
curl -X GET -H 'Content-Type: application/json' \ -H "X-Goog-Api-Key: YOUR_API_KEY" \ -H "X-Goog-FieldMask: id,displayName,accessibilityOptions,businessStatus" \ https://places.googleapis.com/v1/places/ChIJ_QJSSfGAhYARQVFJBNKy3HE?sessionToken=3519edfe-0f75-4a30-bfe4-7cbd89340b2c
باستخدام id للمكان ChIJ_QJSSfGAhYARQVFJBNKy3HE، يُنشئ الطلب استجابة JSON التالية:
{ "id": "ChIJ_QJSSfGAhYARQVFJBNKy3HE", "businessStatus": "OPERATIONAL", "displayName": { "text": "Pizza By The Slice", "languageCode": "en" }, "accessibilityOptions": { "wheelchairAccessibleParking": false, "wheelchairAccessibleEntrance": true } }
إرسال طلب التحقّق من صحة العنوان
طلب التحقّق من صحة العنوان هو طلب HTTP POST. لمزيد من المعلومات عن مَعلمات نص الطلب، يُرجى الاطّلاع على إرسال طلب التحقّق من صحة العنوان.
يتضمّن طلب التحقّق من صحة العنوان التالي عنوان المكان الذي تم اختياره، والذي تم العثور عليه في حقلtext الخاص باستجابة Autocomplete (New)، وsessionToken المستخدَم في طلبات البيانات السابقة من واجهة برمجة التطبيقات Autocomplete (New).
curl -X POST -d '{
"sessionToken": "3519edfe-0f75-4a30-bfe4-7cbd89340b2c",
"address": {
"addressLines": "Pizza By The Slice, Grant Avenue, San Francisco, CA, USA"
}
}' \
-H 'Content-Type: application/json' \
"https://addressvalidation.googleapis.com/v1:validateAddress?key=YOUR_API_KEY"
يُنشئ الطلب استجابة JSON التالية:
{ "result": { "verdict": { "inputGranularity": "PREMISE", "validationGranularity": "PREMISE", "geocodeGranularity": "PREMISE", "hasInferredComponents": true }, "address": { "formattedAddress": "Pizza By The Slice, Grant Avenue, San Francisco, CA 94133, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94133", "administrativeArea": "CA", "locality": "San Francisco", "addressLines": [ "Pizza By The Slice", "Grant Ave" ] }, "addressComponents": [ { "componentName": { "text": "Pizza By The Slice", "languageCode": "en" }, "componentType": "point_of_interest", "confirmationLevel": "CONFIRMED" }, { "componentName": { "text": "Grant Avenue", "languageCode": "en" }, "componentType": "route", "confirmationLevel": "CONFIRMED" }, { "componentName": { "text": "San Francisco", "languageCode": "en" }, "componentType": "locality", "confirmationLevel": "CONFIRMED" }, { "componentName": { "text": "CA", "languageCode": "en" }, "componentType": "administrative_area_level_1", "confirmationLevel": "CONFIRMED" }, { "componentName": { "text": "USA", "languageCode": "en" }, "componentType": "country", "confirmationLevel": "CONFIRMED" }, { "componentName": { "text": "94133" }, "componentType": "postal_code", "confirmationLevel": "CONFIRMED", "inferred": true } ], "missingComponentTypes": [ "street_number" ] }, "geocode": { "location": { "latitude": 37.800504, "longitude": -122.4074794 }, "plusCode": { "globalCode": "849VRH2V+62" }, "bounds": { "low": { "latitude": 37.800504, "longitude": -122.4074794 }, "high": { "latitude": 37.800504, "longitude": -122.4074794 } }, "featureSizeMeters": 10, "placeId": "ChIJ_QJSSfGAhYARQVFJBNKy3HE", "placeTypes": [ "food", "restaurant", "point_of_interest", "establishment" ] }, "uspsData": { "standardizedAddress": { "firstAddressLine": "PIZZA BY THE SLICE", "secondAddressLine": "GRANT AVE", "cityStateZipAddressLine": "SAN FRANCISCO", "city": "SAN FRANCISCO", "state": "CA", "zipCode": "94133" }, "dpvFootnote": "A1M1", "postOfficeCity": "SAN FRANCISCO", "postOfficeState": "CA" } }, "responseId": "4b669675-2c3b-463a-ae20-400248cf6ac9" }
إلغاء الجلسة
تنتهي الجلسة إذا ألغاها المستخدم. على سبيل المثال، إذا بدأ المستخدم البحث عن متجر بيتزا ولكن لم يختَر مكانًا (ما يؤدي إلى استدعاء واجهة برمجة التطبيقات Place Details (New)) أو لم يتحقّق من صحة العنوان (ما يؤدي إلى استدعاء واجهة برمجة التطبيقات Address Validation)، تنتهي الجلسة وينتهي الرمز المميز للجلسة.