استخدام رموز الجلسات
تجمِّع رموز الجلسات مراحل طلب البحث والاختيار في بحث الإكمال التلقائي للمستخدم في جلسة منفصلة لأغراض الفوترة. تعرض الأمثلة التالية كيفية استخدام رموز الجلسات في طلبات بيانات من واجهتَي برمجة التطبيقات Autocomplete (New) وPlace Details (New).
إنشاء رمز جلسة
تقع على عاتق المستخدمين مسؤولية إنشاء رموز جلسات فريدة لكل جلسة. تنصح Google باستخدام معرّفات UUID الإصدار 4.
إرسال طلب بيانات من واجهة برمجة التطبيقات Autocomplete (New)
طلب البيانات من واجهة برمجة التطبيقات Autocomplete (New) هو طلب HTTP POST. لمزيد من المعلومات عن مَعلمات نص الطلب، يُرجى الاطّلاع على طلبات البيانات من واجهة برمجة التطبيقات Autocomplete (New).
تعرض سلسلة الطلبات التالية مستخدمًا يبحث عن متجر بيتزا في سان فرانسيسكو. عندما يبدأ المستخدم بكتابة طلب بحث، يتم استدعاء واجهة برمجة التطبيقات Autocomplete (New) لكل ضغطة مفتاح. ويتم تمرير رمز الجلسة الذي تم إنشاؤه كمعلَمة في كل طلب.
الطلب والاستجابة الأولان
Request 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
Response 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" ] } }, ] / ... / }
الطلب والاستجابة الثانيان
Request 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
Response 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" ] } }, /.../ ] }
الطلب والاستجابة الثالثان
Request 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
Response 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)
طلب البيانات من واجهة برمجة التطبيقات Place Details (New) هو طلب HTTP 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 } }
إرسال طلب بيانات من واجهة برمجة التطبيقات Address Validation
طلب البيانات من واجهة برمجة التطبيقات Address Validation هو طلب 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)، تنتهي الجلسة وينتهي رمز الجلسة.