Chọn nền tảng: Android iOS Dịch vụ web

Sử dụng mã thông báo phiên

Mã thông báo phiên nhóm các giai đoạn truy vấn và lựa chọn của một cụm từ tìm kiếm tự động hoàn thành của người dùng thành một phiên riêng biệt cho mục đích thanh toán. Các ví dụ sau đây minh hoạ cách sử dụng mã thông báo phiên trong các lệnh gọi Tự động hoàn thành (Mới) và Chi tiết về địa điểm (Mới).

Tạo mã thông báo phiên

Người dùng chịu trách nhiệm tạo mã thông báo phiên duy nhất cho mỗi phiên. Google khuyên bạn nên sử dụng UUID phiên bản 4.

Lưu ý: Mã thông báo phiên có thể trùng lặp giữa các dự án trên Google Cloud Console, nhưng phải là duy nhất cho mỗi dự án. Ví dụ: một ứng dụng sử dụng Dự án A và một ứng dụng sử dụng Dự án B có thể dùng cùng một mã thông báo phiên, nhưng nhiều ứng dụng sử dụng Dự án A không thể dùng cùng một mã thông báo phiên.

Gửi yêu cầu Tự động hoàn thành (Mới)

Yêu cầu về tính năng Tự động hoàn thành (Mới) là một yêu cầu HTTP POST. Để biết thêm thông tin về các tham số của nội dung yêu cầu, hãy xem các yêu cầu Tự động hoàn thành (Mới).

Chuỗi yêu cầu sau đây cho thấy một người dùng đang tìm kiếm một cửa hàng bánh pizza ở San Francisco. Khi người dùng bắt đầu nhập một cụm từ tìm kiếm, tính năng Tự động hoàn thành (Mới) sẽ được gọi cho mỗi lần nhấn phím. Mã thông báo phiên được tạo sẽ được truyền dưới dạng một tham số trong mỗi lệnh gọi.

Yêu cầu và phản hồi đầu tiên

Yêu cầu 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

Phản hồi 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"
        ]
      }
    },
  ]
   / ... /
}

Yêu cầu và phản hồi thứ hai

Yêu cầu 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

Phản hồi 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"
        ]
      }
    },
  /.../
  ]
}

Yêu cầu và phản hồi của bên thứ ba

Yêu cầu 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

Phản hồi 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"
        ]
      }
    },
  /.../
  ]
}

Lưu ý: Bạn có thể sử dụng tham số inputOffset không bắt buộc để chỉ định vị trí của con trỏ trong trường nhập.

Kết thúc phiên

Kết thúc một phiên bằng cách đưa ra yêu cầu cho Place Details (New) hoặc Address Validation và truyền cùng một mã thông báo phiên mà bạn đã dùng cho các yêu cầu Autocomplete (New).

Đưa ra yêu cầu Chi tiết về địa điểm (Mới)

Yêu cầu Chi tiết về địa điểm (mới) là một yêu cầu HTTP GET. Để biết thêm thông tin về các tham số của phần nội dung yêu cầu, hãy xem phần Yêu cầu Chi tiết về địa điểm (Mới).

Yêu cầu Chi tiết về địa điểm (mới) sau đây bao gồm id của địa điểm đã chọn và sessionToken được dùng trong các lệnh gọi Tự động hoàn thành (mới) trước đó.

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

Khi dùng một địa điểm id của ChIJ_QJSSfGAhYARQVFJBNKy3HE, lệnh gọi sẽ tạo ra phản hồi JSON sau:

{
  "id": "ChIJ_QJSSfGAhYARQVFJBNKy3HE",
  "businessStatus": "OPERATIONAL",
  "displayName": {
    "text": "Pizza By The Slice",
    "languageCode": "en"
  },
  "accessibilityOptions": {
    "wheelchairAccessibleParking": false,
    "wheelchairAccessibleEntrance": true
  }
}

Đưa ra yêu cầu Xác thực địa chỉ

Yêu cầu Xác thực địa chỉ là một yêu cầu HTTP POST. Để biết thêm thông tin về các tham số trong phần nội dung yêu cầu, hãy xem bài viết Gửi yêu cầu xác thực địa chỉ.

Yêu cầu Xác thực địa chỉ sau đây bao gồm địa chỉ của địa điểm đã chọn, có trong trường text của phản hồi Tự động hoàn thành (Mới) và sessionToken được dùng trong các lệnh gọi Tự động hoàn thành (Mới) trước đó.

    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"

Lệnh gọi này tạo ra phản hồi JSON sau:

    {
      "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"
    }

Huỷ phiên

Một phiên sẽ kết thúc nếu người dùng bỏ phiên. Ví dụ: nếu người dùng bắt đầu tìm kiếm một cửa hàng bánh pizza nhưng không chọn một địa điểm (kích hoạt lệnh gọi Chi tiết về địa điểm (Mới)) hoặc xác thực địa chỉ (kích hoạt lệnh gọi Xác thực địa chỉ), thì phiên sẽ kết thúc và mã thông báo phiên sẽ hết hạn.