اختيار النظام الأساسي: Android iOS خدمة الويب

استخدام الرموز المميّزة للجلسات

تجمع الرموز المميزة للجلسات مرحلتَي طلب البحث والاختيار في عملية بحث الإكمال التلقائي التي يجريها المستخدم في جلسة منفصلة لأغراض الفوترة. توضّح الأمثلة التالية كيفية استخدام الرموز المميّزة للجلسات في طلبات "الإكمال التلقائي (الجديد)" و"تفاصيل المكان (الجديد)".

إنشاء رمز مميّز للجلسة

ويتحمّل المستخدمون مسؤولية إنشاء رموز مميّزة فريدة لكل جلسة. تنصح 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"
        ]
      }
    },
  /.../
  ]
}

إنهاء الجلسة

يمكنك إنهاء جلسة من خلال إرسال طلب إلى "تفاصيل المكان (جديد)" أو "التحقّق من صحة العنوان" وإدخال الرمز المميّز للجلسة نفسه الذي استخدمته لطلبات "الإكمال التلقائي (جديد)".

إرسال طلب للحصول على تفاصيل المكان (الإصدار الجديد)

طلب "تفاصيل المكان (الجديد)" هو طلب استرداد بيانات باستخدام 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
  }
}

إرسال طلب إلى Address Validation API

طلب Address Validation هو طلب HTTP POST. لمزيد من المعلومات حول مَعلمات نص الطلب، يُرجى الاطّلاع على إرسال طلب للتحقّق من العنوان.

يتضمّن طلب Address Validation التالي عنوان المكان المحدّد، والذي يظهر في حقل 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"
    }

إلغاء جلسة

وتنتهي الجلسة إذا غادرها المستخدم. على سبيل المثال، إذا بدأ المستخدم البحث عن محل بيتزا ولكنّه لم يختَر مكانًا (ما يؤدي إلى تفعيل طلب "تفاصيل المكان (الجديد)") أو لم يتحقّق من العنوان (ما يؤدي إلى تفعيل طلب "التحقّق من العنوان")، تنتهي الجلسة وتنتهي صلاحية الرمز المميّز للجلسة.

السابق
لمحة عن الرموز المميّزة للجلسة
التالي
الإكمال التلقائي (جديد) وتسعير الجلسات