Tài liệu tham khảo nhanh về Geocoding API

Geocoding API là một dịch vụ web giúp chuyển đổi địa chỉ thành toạ độ và Mã địa điểm, đồng thời chuyển đổi toạ độ hoặc Mã địa điểm thành địa chỉ. Phương thức v4 SearchDestinations cũng trả về thông tin chi tiết về điểm đến, chẳng hạn như lối vào toà nhà, điểm đi theo chỉ dẫn, đường viền toà nhà và khuôn viên, cũng như các địa danh lân cận.

Geocoding API: dữ kiện chính

  • Sản phẩm: Geocoding API
  • Danh mục: Địa điểm
  • Nền tảng: Dịch vụ web (REST)
  • Chạy trên: Máy chủ (mã phụ trợ)
  • Giai đoạn ra mắt: GA
  • Vòng đời: Đang hoạt động
  • Tổng quan: Tổng quan về Geocoding API

Geocoding API: trường hợp sử dụng

Sử dụng Geocoding API khi:

  • Bạn cần chuyển đổi địa chỉ đường phố thành toạ độ vĩ độ/kinh độ và Mã địa điểm trên máy chủ phụ trợ.
  • Bạn cần có địa chỉ hiển thị hoặc khu vực hành chính (thành phố, mã bưu chính) cho toạ độ GPS hoặc Mã địa điểm đã biết.
  • Bạn cần có lối vào toà nhà, điểm đi theo chỉ dẫn hoặc đường viền toà nhà/khuôn viên để chỉ đường cho tài xế hoặc nhân viên giao hàng đến một điểm đến.
  • Bạn cần phân giải một điểm đến bên trong một khu phức hợp lớn (sân bay, trung tâm mua sắm, khuôn viên) thành các điểm đến phụ hoặc địa danh lân cận.

Đừng sử dụng Geocoding API khi:

  • Bạn cần mã hoá địa lý từ JavaScript của trình duyệt phía máy khách; việc gọi v4 bằng khoá API công khai là một rủi ro bảo mật. Thay vào đó, hãy sử dụng Maps JavaScript API.
  • Bạn cần tính toán tuyến đường hoặc thời gian đến dự kiến (ETA) cho điểm đến được mã hoá địa lý. Hãy sử dụng Routes API.
  • Bạn cần có hướng dẫn từng chặng đến một mã thông báo điểm điều hướng trong ứng dụng Android. Hãy sử dụng Navigation SDK cho Android.
  • Bạn cần được hướng dẫn từng chặng đến một mã thông báo điểm đi theo chỉ dẫn trong ứng dụng iOS. Hãy sử dụng Navigation SDK cho iOS.

Geocoding API: thiết lập

Geocoding API: lỗi thường gặp

  • Vấn đề: Các yêu cầu SearchDestinations không có mặt nạ trường sẽ không thành công và có lỗi; không giống như GeocodeAddress, GeocodeLocation và GeocodePlace, mặt nạ trường là bắt buộc. Cách khắc phục: Đặt tiêu đề X-Goog-FieldMask hoặc tham số $fields trên mọi yêu cầu SearchDestinations. Xem /maps/documentation/geocoding/choose-fields.
  • Vấn đề: v4 GeocodeAddress không có bộ lọc thành phần cứng (v3 components=country:US). Các tham số address.* có cấu trúc được kết hợp thành một địa chỉ và không lọc kết quả; regionCode cũng không có giá trị mặc định trong v4 (v3 mặc định là us). Cách khắc phục: Lọc results phía máy khách: so khớp regionCode viết hoa với postalAddress.regionCode; so khớp các khu vực quản trị gồm 2 chữ cái viết hoa với postalAddress.administrativeArea và administrative_area_level_n addressComponents (shortText); chuẩn hoá cả dữ liệu đầu vào và postalAddress.postalCode (loại bỏ dấu cách/dấu gạch nối và áp dụng quy tắc khu vực). Xem /maps/documentation/geocoding/geocoding-v4-migrate.
  • Vấn đề: Việc gọi trực tiếp Geocoding API phiên bản 4 từ JavaScript của trình duyệt sẽ làm lộ khoá API; người dùng có thể bỏ qua các quy định hạn chế về liên kết giới thiệu HTTP bằng cách giả mạo tiêu đề Referer. Cách khắc phục: Gọi phiên bản 4 từ phần phụ trợ của riêng bạn bằng khoá được bảo vệ hoặc sử dụng Dịch vụ mã hoá địa lý của API JavaScript của Maps (phần phụ trợ phiên bản 3) cho các nhu cầu phía máy khách. Xem /maps/documentation/geocoding/geocoding-v4-migrate.
  • Vấn đề: SearchDestinations có thể trả về kết quả không có địa chỉ chính xác, không giống như v3 và các phương thức v4 khác. Cách khắc phục: Đặt placeFilter.addressability thành PRIMARY khi bạn chỉ cần kết quả có địa chỉ chính xác. Xem /maps/documentation/geocoding/geocoding-v4-migrate.
  • Vấn đề: Mã được viết cho Geocoding API phiên bản 3 không hoạt động trên phản hồi REST phiên bản 4: phiên bản 4 sử dụng tên trường lowerCamelCase (addressComponents, không phải address_components), xoá status và error_message, đồng thời trả về một đối tượng gốc duy nhất từ GeocodePlace thay vì một mảng results. Cách khắc phục: Kiểm tra mã trạng thái HTTP và nội dung lỗi trong các lệnh gọi REST phiên bản 4, đọc các trường lowerCamelCase (addressComponents, postalAddress) và lưu ý rằng phản hồi gRPC vẫn sử dụng kiểu viết con rắn (viết thường chữ cái đầu tiên và thay dấu cách bằng dấu gạch dưới). Xem /maps/documentation/geocoding/geocoding-v4-migrate.

Geocoding API: các tính năng cũ và không còn được dùng nữa

  • Dữ liệu theo từng khu vực cụ thể của Geocoding API phiên bản 3 (extra_computations: BUILDING_AND_ENTRANCES, NAVIGATION_POINTS, GROUNDS; các trường phản hồi buildings.entrances, navigation_points, buildings.building_outlines, grounds): Ngừng hoạt động kể từ ngày 13 tháng 8 năm 2025. Phương thức thay thế: Phương thức SearchDestinations của Geocoding API phiên bản 4 (POST /v4/geocode/destinations). Xem hướng dẫn di chuyển.

Những việc bạn có thể làm với Geocoding API

Hãy xem hướng dẫn được liên kết bên dưới cho từng nhiệm vụ hoặc so sánh giữa các sản phẩm trong Trình khám phá chức năng.