המוצר או התכונה הזו נמצאים בגרסת טרום-GA (גרסת טרום-GA). התמיכה במוצרים ובתכונות טרום-GA עשויה להיות מוגבלת, ויכול להיות ששינויים במוצרים ובתכונות טרום-GA לא יתאימו לגרסאות אחרות של טרום-GA. מוצרים במצב טרום-GA מכוסים על ידי התנאים הספציפיים לשירות בפלטפורמה של מפות Google. למידע נוסף, עיינו בתיאורים של שלבי ההשקה.

שימוש באסימוני סשן

אסימוני הפעלה מקבצים את שלבי השאילתה והבחירה של חיפוש בהשלמה אוטומטית של משתמש לסשן נפרד למטרות חיוב. הדוגמאות הבאות מראות איך להשתמש באסימוני סשן בקריאות להשלמה אוטומטית (חדש) ולפרטי מקום (חדש).

יצירת אסימון סשן

המשתמשים אחראים ליצור אסימונים ייחודיים לסשן לכל סשן. Google ממליצה להשתמש במזהי UUID בגרסה 4.

הערה: אסימוני הסשן יכולים להיות חופפים לפרויקטים שונים במסוף Google Cloud, אבל הם חייבים להיות ייחודיים לכל פרויקט. לדוגמה, אפליקציה שמשתמשת בפרויקט א ואפליקציה שמשתמשת בפרויקט ב' יכולות להשתמש באותו אסימון סשן, אבל כמה אפליקציות שמשתמשות בפרויקט א' לא יכולות להשתמש באותו אסימון סשן.

שליחת בקשה להשלמה אוטומטית (חדשה)

בקשת השלמה אוטומטית (חדשה) היא בקשת 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

תשובה ראשונה

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

הערה: אפשר להשתמש בפרמטר האופציונלי inputOffset כדי לציין את מיקום הסמן בשדה הקלט.

סיום הסשן

כדי לסיים סשן, צריך לשלוח בקשה לאימות פרטים (חדש) או לאימות כתובת, ולהעביר את אותו אסימון הסשן שבו השתמשתם לבקשות של השלמה אוטומטית (חדש).

יצירת בקשה לפרטי מקום (חדש)

בקשת 'פרטי מקום (חדש)' היא בקשת 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"
    }

נטישה של הפעלה

סשן מסתיים אם המשתמש נוטש את הסשן. לדוגמה, אם משתמש מתחיל לחפש פיצרייה אבל לא בוחר מקום (ומריץ שיחה עם פרטי מקום (חדש)) או מאמת את הכתובת (באמצעות הפעלה של שיחה לאימות כתובת), הסשן יסתיים ואסימון הסשן יפוג.