انتخاب پلاتفرم: Android iOS سرویس وب

استفاده از داده‌واحد جلسه

کدهای جلسه، مراحل پُرسمان و انتخاب جستجوی تکمیل خودکار کاربر را برای اهداف صورت‌حساب در یک جلسه مجزا گروه‌بندی می‌کنند. مثال‌های زیر نحوه استفاده از نشان‌های جلسه را در تماس‌های «تکمیل خودکار (جدید)» و «جزئیات مکان (جدید)» نشان می‌دهد.

ایجاد کردن کد جلسه

کاربران مسئول تولید کردن نشان‌های جلسه منحصربه‌فرد برای هر جلسه هستند. ‫Google استفاده از شناسه‌های منحصربه‌فرد جهانی نسخه ۴ را توصیه می‌کند.

ایجاد درخواست «تکمیل خودکار (جدید)»

درخواست «تکمیل خودکار (جدید)» یک درخواست HTTP POST است. برای اطلاعات بیشتر درباره پارامترهای بدنه درخواست، به درخواست‌های تکمیل خودکار (جدید) مراجعه کنید.

مجموعه درخواست‌های زیر کاربری را نشان می‌دهد که درحال جستجوی پیتزافروشی در سان‌فرانسیسکو است. وقتی کاربر شروع به تایپ کردن پُرسمانی می‌کند، «تکمیل خودکار» (جدید) برای هر ضربه کلید فراخوانده می‌شود. کد جلسه تولیدشده به‌عنوان پارامتر در هر تماس ارسال می‌شود.

اولین درخواست و پاسخ

درخواست ۱

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

پاسخ ۱

{
  "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"
        ]
      }
    },
  ]
   / ... /
}

درخواست و پاسخ دوم

درخواست ۲

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

پاسخ ۲

{
  "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"
        ]
      }
    },
  /.../
  ]
}

درخواست و پاسخ سوم

درخواست ۳

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

پاسخ ۳

{
  "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"
        ]
      }
    },
  /.../
  ]
}

پایان دادن جلسه

با درخواست کردن از «جزئیات مکان (جدید)» یا «اعتبارسنجی نشانی» و ارسال همان نشان جلسه که برای درخواست‌های «تکمیل خودکار (جدید)» استفاده کرده‌اید، جلسه را خاتمه دهید.

درخواست «جزئیات مکان (جدید)» را انجام دهید

درخواست «جزئیات مکان (جدید)» یک درخواست 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
  }
}

ایجاد درخواست «اعتبارسنجی نشانی»

درخواست «اعتبارسنجی نشانی» یک درخواست 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"
    }

رها کردن جلسه

اگر کاربر جلسه را ترک کند، جلسه پایان می‌یابد. برای مثال، اگر کاربری جستجوی پیتزا فروشی را شروع کند اما مکانی را انتخاب نکند (باعث راه‌اندازی تماس «جزئیات مکان (جدید)» شود) یا نشانی را اعتبارسنجی نکند (باعث راه‌اندازی تماس «اعتبارسنجی نشانی» شود)، جلسه پایان می‌یابد و کد جلسه منقضی می‌شود.