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