پلتفرم مورد نظر را انتخاب کنید: اندروید، iOS، وب سرویس

استفاده از توکن‌های جلسه

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

ایجاد توکن جلسه

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

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

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

سری درخواست‌های زیر، کاربری را نشان می‌دهد که در سانفرانسیسکو به دنبال یک پیتزا فروشی می‌گردد. به محض اینکه کاربر شروع به تایپ یک پرس‌وجو می‌کند، برای هر بار فشردن کلید، Autocomplete (جدید) فراخوانی می‌شود. توکن session تولید شده به عنوان پارامتر در هر فراخوانی ارسال می‌شود.

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

درخواست ۱ 

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

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

با ارسال درخواست برای Place Details (جدید) یا Address Validation و ارسال همان توکن session که برای درخواست‌های Autocomplete (جدید) استفاده کرده‌اید، یک session را خاتمه دهید.

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

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

ترک یک جلسه

اگر کاربر جلسه را ترک کند، یک جلسه خاتمه می‌یابد. برای مثال، اگر کاربری شروع به جستجوی یک پیتزا فروشی کند اما مکانی را انتخاب نکند (فراخوانی Place Details (New) را اجرا کند) یا آدرس را اعتبارسنجی نکند (فراخوانی Address Validation را اجرا کند)، جلسه خاتمه می‌یابد و توکن جلسه منقضی می‌شود.

قبلی
درباره نشانه های جلسه
بعدی
تکمیل خودکار (جدید) و قیمت گذاری جلسه