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

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

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

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

يتحمّل المستخدمون مسؤولية إنشاء رموز مميّزة للجلسات لكل جلسة. تنصح Google باستخدام الإصدار 4 من معرّفات UUID.

تقديم طلب ميزة "الإكمال التلقائي" (جديد)

طلب "الإكمال التلقائي (جديد)" هو طلب POST لبروتوكول HTTP. لمزيد من المعلومات عن مَعلمات محتوى الطلب، يُرجى الاطّلاع على طلبات إكمال الأماكن تلقائيًا (جديد).

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

الطلب والاستجابة الأولان

الطلب 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).

تقديم طلب "تفاصيل المكان (جديد)"

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

تقديم طلب التحقّق من العنوان

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

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

مغادرة جلسة

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