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
- Dịch vụ cần bật:
geocoding-backend.googleapis.com - Xác thực: Khoá API, OAuth 2.0, Tài khoản dịch vụ
- Bắt đầu: Thiết lập Geocoding API
- Tài liệu tham khảo: Tài liệu tham khảo Geocoding API
- Giá: Mức sử dụng và thanh toán cho Geocoding API
- Chính sách: Chính sách về Geocoding API
- Ghi chú phát hành: Ghi chú phát hành về Geocoding API
Geocoding API: sản phẩm có liên quan
- Thường dùng với: Routes API, Navigation SDK cho Android, Navigation SDK cho iOS
Geocoding API: lỗi thường gặp
- Vấn đề: Các yêu cầu
SearchDestinationskhông có mặt nạ trường sẽ không thành công và có lỗi; không giống nhưGeocodeAddress,GeocodeLocationvàGeocodePlace, mặt nạ trường là bắt buộc. Cách khắc phục: Đặt tiêu đềX-Goog-FieldMaskhoặc tham số$fieldstrên mọi yêu cầuSearchDestinations. Xem /maps/documentation/geocoding/choose-fields. - Vấn đề: v4
GeocodeAddresskhông có bộ lọc thành phần cứng (v3components=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ả;regionCodecũng không có giá trị mặc định trong v4 (v3 mặc định làus). Cách khắc phục: Lọcresultsphía máy khách: so khớpregionCodeviết hoa vớipostalAddress.regionCode; so khớp các khu vực quản trị gồm 2 chữ cái viết hoa vớipostalAddress.administrativeAreavàadministrative_area_level_naddressComponents(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 đề:
SearchDestinationscó 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: ĐặtplaceFilter.addressabilitythànhPRIMARYkhi 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ảiaddress_components), xoástatusvàerror_message, đồng thời trả về một đối tượng gốc duy nhất từGeocodePlacethay vì một mảngresults. 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ồibuildings.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ứcSearchDestinationscủ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.
- Trả về toạ độ vĩ độ/kinh độ của một địa chỉ (mã hoá địa lý).
- Trả về địa chỉ cho một tập hợp toạ độ vĩ độ/kinh độ (mã hoá địa lý ngược).
- Giới hạn yêu cầu mã hoá địa lý để trả về kết quả trong một khung nhìn cụ thể. Lưu ý: Trong Geocoding API phiên bản 4, locationBias sẽ ưu tiên kết quả cho khung nhìn được chỉ định thay vì hạn chế nghiêm ngặt kết quả.
- Hạn chế yêu cầu mã hoá địa lý hoặc mã hoá địa lý ngược để chỉ trả về kết quả trong một khu vực, quốc gia hoặc mã bưu chính cụ thể. Lưu ý: Trong Geocoding API phiên bản 4, regionCode thiên về kết quả cho một khu vực CLDR cụ thể thay vì hạn chế nghiêm ngặt; để biết thông tin về cách lọc thành phần theo quốc gia hoặc mã bưu chính trong phiên bản 3 cũ, hãy xem https://developers.google.com/maps/documentation/geocoding/guides-v3/requests-geocoding#ComponentFiltering.
- Hạn chế yêu cầu mã hoá địa lý ngược để chỉ trả về kết quả cho các loại địa chỉ được chỉ định. Lưu ý: Trong Geocoding API phiên bản 4, tham số types sẽ lọc kết quả mã hoá địa lý ngược được trả về theo loại địa chỉ sau khi tìm kiếm, thay vì hạn chế kết quả tìm kiếm cơ bản.
- Trả về thông tin về khoảng cách đến các địa danh hoặc khu vực của một địa chỉ.
- Trả về thông tin về khoảng cách đến các địa danh hoặc khu vực cho một tập hợp toạ độ vĩ độ/kinh độ.
- Trả về thông tin về khoảng cách đến các địa danh hoặc khu vực cho một giá trị nhận dạng địa điểm trên Google.
- Trả về địa chỉ cho giá trị nhận dạng địa điểm trên Google.
- Trả về toạ độ vĩ độ/kinh độ của đường viền toà nhà cho một địa chỉ.
- Trả về toạ độ vĩ độ/kinh độ của đường viền toà nhà cho một tập hợp toạ độ vĩ độ/kinh độ.
- Trả về toạ độ vĩ độ/kinh độ của đường viền toà nhà cho giá trị nhận dạng Địa điểm trên Google.
- Trả về toạ độ vĩ độ/kinh độ của lối vào toà nhà cho một địa chỉ.
- Trả về toạ độ vĩ độ/kinh độ của lối vào toà nhà cho một tập hợp toạ độ vĩ độ/kinh độ.
- Trả về toạ độ vĩ độ/kinh độ của lối vào toà nhà cho giá trị nhận dạng Địa điểm trên Google.