בחירת פלטפורמה: Android iOS שירות אינטרנט

שימוש בטוקנים של סשן

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

יצירת טוקן סשן

המשתמשים אחראים ליצירת טוקנים ייחודיים של סשנים לכל סשן. ‫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

תשובה 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"
        ]
      }
    },
  /.../
  ]
}

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

סיום הסשן

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

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

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

הבקשה הבאה של Place Details (New) כוללת את id של המקום שנבחר ואת sessionToken ששימש בקריאות קודמות של Autocomplete (New).

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

הקריאה עם placeholder של מקום 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"
    }

הפסקת שימוש בסשן

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