Di chuyển từ các tính năng của phiên bản 3 sang điểm cuối SearchDestinations

Nhà phát triển ở Khu vực kinh tế Châu Âu (EEA)

Những tính năng sau đây trong Geocoding API phiên bản 3 sẽ được thay thế bằng điểm cuối SearchDestinations của Geocoding API phiên bản 4:

  • Số lần truy cập
  • Điểm điều hướng
  • Đường viền của toà nhà
  • Vé các hoạt động trong khuôn viên

Nếu bạn đang sử dụng Geocoding API phiên bản 3 cho các tính năng nêu trên, hãy sử dụng tài liệu này để giúp bạn sử dụng điểm cuối SearchDestinations thay vì sử dụng các tính năng này. Tài liệu này giải thích vị trí của các tính năng này trong phản hồi SearchDestinations API và sự khác biệt về cách các tính năng này được biểu thị trong phản hồi API giữa Geocoding API phiên bản 3 và điểm cuối SearchDestinations của Geocoding API phiên bản 4.

Số lần truy cập

Để lấy các lối vào liên kết với destination, hãy sử dụng trường destination.entrances.

Xin lưu ý rằng định dạng của entrance hơi khác so với định dạng lối vào trong Geocoding API phiên bản 3. Mỗi lối vào trong destination.entrances đều có các trường sau:

  • displayName – đây là một trường mới không bắt buộc và sẽ có tên dễ đọc cho lối vào, ví dụ: "Cổng B".
  • location – đây là một vị trí thuộc loại LatLng, khác với định dạng được dùng trong Geocoding API phiên bản 3.
  • tags – giống với trường tags của các lối vào trong Geocoding API phiên bản 3.
  • place – tương tự như trường buildingPlaceId của các lối vào trong Geocoding API phiên bản 3. Tuy nhiên, Mã địa điểm trong trường này có thể là Mã địa điểm của một Địa điểm thuộc bất kỳ loại nào, không nhất thiết chỉ là một toà nhà.

Để lấy các điểm điều hướng được liên kết với một destination, hãy sử dụng trường destination.navigationPoints.

Xin lưu ý rằng định dạng của navigationPoint hơi khác so với định dạng điểm điều hướng trong Geocoding API phiên bản 3. Mỗi điểm điều hướng trong destination.navigationPoints đều có các trường sau:

  • displayName – đây là một trường mới không bắt buộc và sẽ có tên dễ đọc cho điểm điều hướng, ví dụ: "Đại lộ 5".
  • location – đây là một vị trí thuộc loại LatLng, khác với định dạng được dùng trong Geocoding API phiên bản 3.
  • travelModes – trường này tương tự như trường restrictedTravelModes của các điểm điều hướng trong Geocoding API phiên bản 3. Các giá trị enum có thể giống nhau, điểm khác biệt duy nhất là trường này hiện đại diện cho các chế độ di chuyển được chấp nhận cho điểm điều hướng, thay vì các chế độ di chuyển bị hạn chế.
  • usage – đây là một trường mới chứa các trường hợp sử dụng được điểm điều hướng hỗ trợ. Xin lưu ý rằng hầu hết các điểm điều hướng sẽ có mức sử dụng UNKNOWN, nhưng điều đó không nhất thiết có nghĩa là mức sử dụng của điểm điều hướng bị hạn chế theo bất kỳ cách nào.

Đường viền của toà nhà

Để lấy đường viền của toà nhà được liên kết với một destination, bạn nên sử dụng trường displayPolygon của các đối tượng placeView trong destination đại diện cho các toà nhà. Đối với mỗi placeView, bạn có thể kiểm tra xem đó có phải là một toà nhà hay không bằng trường placeView.structureType. Nếu loại cấu trúc là BUILDING, bạn có thể lấy đường viền từ trường placeView.displayPolygon. placeView cũng sẽ có các trường bổ sung cho toà nhà không có trong Geocoding API phiên bản 3.

destination có thể có một đối tượng placeView đại diện cho một toà nhà trong các trường sau:

  • destination.primary – đây là vị trí chính của điểm đến.
  • destination.containingPlaces – đây là một trường lặp lại có thể chứa các địa điểm lớn hơn "chứa" địa điểm chính. Ví dụ: nếu địa điểm chính là subpremise, thì containingPlaces thường sẽ chứa placeView đại diện cho toà nhà.
  • destination.subDestinations – đây là một trường lặp lại có thể chứa các điểm đến phụ của địa điểm chính. Ví dụ: từng căn hộ riêng lẻ trong một toà nhà. Trường này thường không có placeView đại diện cho một toà nhà.

Xin lưu ý rằng định dạng của placeView.displayPolygon khớp với định dạng đường viền toà nhà trong Geocoding API phiên bản 3, đây là định dạng GeoJSON, sử dụng định dạng RFC 7946.

Vé các hoạt động trong khuôn viên

Tương tự như việc tạo đường viền, để lấy các khu đất được liên kết với một destination, bạn nên sử dụng trường displayPolygon của các đối tượng placeView trong destination đại diện cho khu đất. Đối với mỗi placeView, bạn có thể kiểm tra xem đó có phải là căn cứ hay không bằng trường placeView.structureType. Nếu loại cấu trúc là GROUNDS, bạn có thể lấy đường viền từ trường placeView.displayPolygon. placeView cũng sẽ có thêm các trường cho những địa điểm không có trong Geocoding API phiên bản 3.

destination có thể có một đối tượng placeView đại diện cho các căn cứ trong các trường sau:

  • destination.primary
  • destination.containingPlaces
  • destination.subDestinations

Xin lưu ý rằng định dạng của placeView.displayPolygon khớp với định dạng đường viền của mặt đất trong Geocoding API phiên bản 3, đây là định dạng GeoJSON, sử dụng định dạng RFC 7946.

Sử dụng mặt nạ trường để yêu cầu các tính năng này

Điểm cuối SearchDestinations yêu cầu một mặt nạ trường, như được giải thích trong phần Chọn các trường cần trả về. Bạn có thể đặt mặt nạ trường thành * để trả về tất cả các trường hoặc bạn có thể đặt mặt nạ trường thành các trường cụ thể mà bạn muốn nhận. Ví dụ: yêu cầu API sau đây đặt mặt nạ trường để nhận tất cả các trường cần thiết để nhận lối vào, điểm điều hướng, đường viền toà nhà và mặt bằng của một địa điểm:

curl -X POST -d '{"place": "places/ChIJG3kh4hq6j4AR_XuFQnV0_t8"}' \
  -H "X-Goog-Api-Key: API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Goog-FieldMask: destinations.entrances,destinations.navigationPoints,destinations.primary,destinations.containingPlaces,destinations.subDestinations" \
  https://geocode.googleapis.com/v4alpha/geocode/destinations