اختيار النظام الأساسي: 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"
        ]
      }
    },
  /.../
  ]
}

إنهاء الجلسة

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

إجراء طلب 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 ضمن استجابة 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"
    }

إلغاء جلسة

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

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