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

استخدام رموز الجلسات

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

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

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

إرسال طلب بيانات من واجهة برمجة التطبيقات "الإكمال التلقائي (جديد)"

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

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

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

الطلب 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"
        ]
      }
    },
  /.../
  ]
}

إنهاء الجلسة

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

إرسال طلب بيانات من واجهة برمجة التطبيقات "تفاصيل المكان (جديد)"

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

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

يتضمّن طلب البيانات التالي من واجهة برمجة التطبيقات "التحقّق من صحة العنوان" عنوان المكان الذي تم اختياره، والذي تم العثور عليه في حقل 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")، تنتهي الجلسة وينتهي الرمز المميز للجلسة.