Di chuyển từ Geocoding v3 sang v4

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

Geocoding API phiên bản 4 giới thiệu một số điểm cuối mới thay thế chức năng trong phiên bản 3 của API. Hướng dẫn này cho bạn biết cách di chuyển ứng dụng để sử dụng các điểm cuối v4 mới.

Bạn có thể sử dụng khoá API hiện có với các điểm cuối v4 mới. Tuy nhiên, nếu đã yêu cầu tăng hạn mức trên API phiên bản 3, bạn phải yêu cầu tăng hạn mức trên API phiên bản 4 mới. Không có lộ trình di chuyển cho người dùng JavaScript.

Di chuyển từ tính năng Mã hoá địa lý xuôi phiên bản 3

Nếu sử dụng Geocoding để mã hoá địa chỉ theo địa lý, bạn nên di chuyển sang điểm cuối Mã hoá địa chỉ theo địa lý phiên bản 4. Điểm cuối này chấp nhận yêu cầu GET.

API phiên bản 4 thay đổi tên, cấu trúc và khả năng hỗ trợ cho một số tham số. Bạn nên sử dụng mặt nạ trường để chỉ định các trường mà bạn muốn trả về trong phản hồi.

Yêu cầu thay đổi tham số

Tham số v3 Tham số phiên bản 4 Ghi chú
address, components address Địa chỉ không có cấu trúc (v3 address) hiện được truyền trong đường dẫn URL. Bộ lọc thành phần (v3 components) hiện được truyền dưới dạng tham số truy vấn address.*.
bounds locationBias.rectangle Đã đổi tên; cấu trúc đã thay đổi thành đối tượng.
language languageCode Đã đổi tên.
region regionCode Đã đổi tên.
extra_computations Đã xoá

Thay đổi về trường phản hồi

Trường v3 Trường v4 Ghi chú
status, error_message Đã xoá Phiên bản 4 sử dụng mã trạng thái HTTP và nội dung lỗi.
results.address_components.long_name/results.address_components.short_name results.addressComponents.longText/results.addressComponents.shortText Đã đổi tên.
results.geometry.location_type results.granularity Đã đổi tên.
results.geometry.location results.location Tên trường: lat/lng -> latitude/longitude.
results.geometry.viewport results.viewport Tên trường: northeast/southwest -> high/low.
results.postcode_localities results.postalCodeLocalities Đã đổi tên. Hiện đã trả về cho một hoặc nhiều địa phương (cần có phiên bản 3 > 1).
results.partial_match Đã xoá
Mới results.addressComponents.languageCode Ngôn ngữ của thành phần địa chỉ cụ thể.
Mới results.bounds Ranh giới rõ ràng bằng cách sử dụng high/low.
Mới results.place Tên tài nguyên của địa điểm.
Mới results.postalAddress Đối tượng PostalAddress có cấu trúc.

Di chuyển từ tính năng Mã hoá địa lý ngược phiên bản 3

Nếu sử dụng Reverse Geocoding (Địa lý hoá ngược) để chuyển đổi toạ độ thành địa chỉ, bạn nên di chuyển sang điểm cuối v4 Reverse geocode a location (Địa lý hoá ngược một vị trí). Điểm cuối này chấp nhận yêu cầu GET.

API phiên bản 4 thay đổi tên, cấu trúc và khả năng hỗ trợ cho một số tham số. Bạn nên sử dụng mặt nạ trường để chỉ định các trường mà bạn muốn trả về trong phản hồi.

Yêu cầu thay đổi tham số

Tham số v3 Tham số phiên bản 4 Ghi chú
language languageCode Đã đổi tên.
region regionCode Đã đổi tên.
result_type types Đổi tên; sử dụng các tham số truy vấn lặp lại.
location_type granularity Đổi tên; sử dụng các tham số truy vấn lặp lại.
extra_computations Đã xoá

Thay đổi về trường phản hồi

Trường v3 Trường v4 Ghi chú
status, error_message Đã xoá Phiên bản 4 sử dụng mã trạng thái HTTP và nội dung lỗi.
results.address_components.long_name/results.address_components.short_name results.addressComponents.longText/results.addressComponents.shortText Đã đổi tên.
results.geometry.location_type results.granularity Đã đổi tên.
results.geometry.location results.location Tên trường: lat/lng -> latitude/longitude.
results.geometry.viewport results.viewport Tên trường: northeast/southwest -> high/low.
Mới results.addressComponents.languageCode Ngôn ngữ của thành phần địa chỉ cụ thể.
Mới results.bounds Ranh giới rõ ràng bằng cách sử dụng high/low.
Mới results.place Tên tài nguyên của địa điểm.
Mới results.postalAddress Đối tượng PostalAddress có cấu trúc.

Di chuyển từ dịch vụ Mã hoá địa lý của Địa điểm phiên bản 3

Nếu sử dụng place_id để lấy địa chỉ cho một Mã địa điểm cụ thể bằng Geocoding v3, bạn phải di chuyển sang điểm cuối Place Geocoding v4. Điểm cuối này chấp nhận yêu cầu GET.

API phiên bản 4 thay đổi tên, cấu trúc và khả năng hỗ trợ cho một số tham số. Bạn nên sử dụng mặt nạ trường để chỉ định các trường mà bạn muốn trả về trong phản hồi.

Yêu cầu thay đổi tham số

Tham số v3 Tham số phiên bản 4 Ghi chú
place_id Trường place trong proto yêu cầu Mã địa điểm hiện được cung cấp dưới dạng tham số đường dẫn places/{place}, ví dụ: https://geocode.googleapis.com/v4beta/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw. Điều này tương ứng với trường địa điểm trong yêu cầu cơ bản.
language languageCode Đã đổi tên.
region regionCode Đã đổi tên.

Thay đổi về trường phản hồi

Trường v3 Trường v4 Ghi chú
status, error_message Đã xoá Phiên bản 4 sử dụng mã trạng thái HTTP và nội dung lỗi.
results (root) v4 trả về một đối tượng kết quả duy nhất, chứ không phải mảng results.
results.address_components.long_name/results.address_components.short_name addressComponents.longText/addressComponents.shortText Đã đổi tên.
results.geometry.location_type granularity Đã đổi tên.
results.geometry.location location Tên trường: lat/lng -> latitude/longitude.
results.geometry.viewport viewport Tên trường: northeast/southwest -> high/low.
results.postcode_localities postalCodeLocalities Đã đổi tên. Hiện đã trả về cho một hoặc nhiều địa phương (cần có phiên bản 3 > 1).
Mới addressComponents.languageCode Ngôn ngữ của thành phần địa chỉ cụ thể.
Mới bounds Ranh giới rõ ràng bằng cách sử dụng high/low.
Mới place Tên tài nguyên của địa điểm.
Mới postalAddress Đối tượng PostalAddress có cấu trúc.

Di chuyển từ Dữ liệu siêu cục bộ về mã hoá địa lý sang Đích đến

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 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 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, cũng như sự khác biệt về cách các tính năng này được thể hiện trong phản hồi API giữa Geocoding API phiên bản 3 và SearchDestinations API 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ể có là như nhau, điểm khác biệt duy nhất là trường này hiện biểu thị 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 toà nhà

Để lấy đường viền của toà nhà được liên kết với 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à có trường placeView.structureType hay không. 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ẽ giữ 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 một cơ sở 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 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 để 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 điểm đến:

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