Mã hoá địa lý chuyển đổi một địa chỉ thành một vị trí trên bản đồ. Khi bạn mã hoá địa lý một địa chỉ, phản hồi sẽ chứa:
- Mã địa điểm của vị trí
- Toạ độ vĩ độ và kinh độ của vị trí
- Plus Code của vị trí
- Thông tin chi tiết mở rộng về địa chỉ
Yêu cầu mã hoá địa lý
Yêu cầu mã hoá địa lý là yêu cầu HTTP GET. Bạn có thể chỉ định địa chỉ dưới dạng chuỗi không có cấu trúc:
https://geocode.googleapis.com/v4/geocode/address/ADDRESS_STRING
Hoặc dưới dạng một tập hợp có cấu trúc gồm các thành phần địa chỉ được biểu thị bằng các tham số truy vấn:
https://geocode.googleapis.com/v4/geocode/address?STRUCTURED_ADDRESS
Bạn thường sử dụng định dạng có cấu trúc khi xử lý các thành phần địa chỉ được thu thập trong biểu mẫu HTML.
Truyền tất cả các tham số khác dưới dạng tham số URL hoặc đối với các tham số như khoá API và mặt nạ trường, hãy truyền trong tiêu đề như một phần của yêu cầu GET.
Truyền chuỗi địa chỉ không có cấu trúc
Địa chỉ không có cấu trúc là địa chỉ được định dạng dưới dạng chuỗi hoặc Plus Code. Tính năng mã hoá địa lý địa chỉ không phân giải toạ độ vĩ độ và kinh độ hoặc các chuỗi không có cấu trúc khác không đại diện cho địa chỉ hoặc Plus Code. Các yêu cầu sử dụng những chuỗi như vậy không được hỗ trợ và có thể dẫn đến phản hồi lỗi hoặc hành vi không xác định. Sau đây là ví dụ về các truy vấn không được hỗ trợ:
| Loại truy vấn | Ví dụ |
|---|---|
| Toạ độ vĩ độ và kinh độ. Thay vào đó, hãy sử dụng tính năng mã hoá địa lý ngược. | "37.422131,-122.084801" |
| Có quá nhiều khái niệm hoặc ràng buộc, chẳng hạn như tên của nhiều địa điểm, đường hoặc thành phố trong một truy vấn | "Market Street San Francisco San Jose Airport" |
| Các thành phần địa chỉ bưu chính không được biểu thị trên Google Maps |
"C/O John Smith 123 Main Street" "P.O. Box 13 San Francisco" |
| Tên của doanh nghiệp, chuỗi hoặc danh mục kết hợp với các địa điểm mà các thực thể này không có mặt | "Tesco near Dallas, Texas" |
| Truy vấn không rõ ràng có nhiều cách diễn giải | "Charger drop-off" |
| Tên cũ không còn được sử dụng | "Middlesex United Kingdom" |
| Ý định hoặc thành phần không liên quan đến vị trí địa lý | "How many boats are in Ventura Harbor?" |
| Tên không chính thức hoặc tên tuỳ chỉnh |
"The Jenga" "The Helter Skelter" |
Ví dụ: ví dụ sau đây truyền chuỗi địa chỉ được mã hoá URL "1600 Amphitheatre Parkway, Mountain View, CA":
https://geocode.googleapis.com/v4/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA?key=API_KEY
Xin lưu ý rằng ký tự "+" trong URL được chuyển đổi thành dấu cách.
Bạn cũng có thể đưa ra yêu cầu bằng lệnh curl:
curl -H "X-Goog-Api-Key: API_KEY" \ "https://geocode.googleapis.com/v4/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA"
Địa chỉ có thể chứa nhiều loại ký tự đặc biệt. Ví dụ: dấu "/" như trong "7/1 King St, Concord West". Mã hoá URL dấu "/" thành %2F:
https://geocode.googleapis.com/v4/geocode/address/7%2F1+King+St,+Concord+West?key=API_KEY
Một ví dụ phổ biến khác là ký tự "#", như trong "9500 W Bryn Mawr Ave #650, Rosemont". Mã hoá URL dấu "#" thành %2FE:
https://geocode.googleapis.com/v4/geocode/address/9500+W+Bryn+Mawr+Ave+%23650,+Rosemont?key=API_KEY
Trong ví dụ tiếp theo, bạn chỉ định chuỗi địa chỉ không có cấu trúc làm Plus Code 849VCWC8+R4. Đảm bảo bạn mã hoá URL ký tự "+" thành %2B:
https://geocode.googleapis.com/v4/geocode/address/849VCWC8%2BR4?key=API_KEY
Truyền địa chỉ có cấu trúc
Chỉ định địa chỉ có cấu trúc bằng cách sử dụng tham số truy vấn address thuộc loại
PostalAddress.
Đối tượng PostalAddress cho phép bạn chỉ định một số hoặc tất cả các thành phần địa chỉ trong yêu cầu dưới dạng tham số truy vấn riêng lẻ.
Ví dụ: để chỉ định mã bưu chính của địa chỉ, bạn hãy sử dụng PostalAddress.postalCode:
https://geocode.googleapis.com/v4/geocode/address?address.postalCode=01062&key=API_KEY
Để chỉ định nhiều thành phần địa chỉ, chẳng hạn như các thành phần địa chỉ được thu thập trong biểu mẫu HTML, hãy sử dụng nhiều tham số truy vấn:
https://geocode.googleapis.com/v4/geocode/address?address.addressLines=1600+Amphithreater+Pkwy&address.locality=Mountain+View &address.administrativeArea=CA &key=API_KEY
Sử dụng OAuth để đưa ra yêu cầu
Geocoding API v4 hỗ trợ OAuth 2.0 để xác thực. Để sử dụng OAuth với Geocoding API, mã thông báo OAuth phải được gán phạm vi chính xác. Geocoding API hỗ trợ các phạm vi sau đây để sử dụng với tính năng mã hoá địa lý chuyển tiếp:
https://www.googleapis.com/auth/maps-platform.geocode– Sử dụng với tất cả các phương thức Geocoding API.https://www.googleapis.com/auth/maps-platform.geocode.address– Chỉ sử dụng vớiGeocodeAddressđể mã hoá địa lý chuyển tiếp.
Ngoài ra, bạn có thể sử dụng phạm vi https://www.googleapis.com/auth/cloud-platform chung cho tất cả các phương thức Geocoding API. Phạm vi đó hữu ích trong quá trình phát triển nhưng không hữu ích trong quá trình sản xuất vì đây là phạm vi chung cho phép truy cập vào tất cả các phương thức.
Để biết thêm thông tin và ví dụ, hãy xem Sử dụng OAuth.
Phản hồi mã hoá địa lý
Tính năng mã hoá địa lý trả về một
GeocodeAddressResponse
đối tượng chứa mảng results của các
GeocodeResult
đối tượng. Mỗi đối tượng GeocodeResult đại diện cho một địa điểm.
Phản hồi của Geocoding API bao gồm types mảng ở 2 vị trí chính trong
GeocodeResult:
GeocodeResult.types: Mảng này cho biết(các) loại chung của kết quả. Các giá trị có thể có được lấy từ Bảng A và Bảng B trên trang Loại địa điểm (Mới).GeocodeResult.addressComponents[].types: Mỗi thành phần địa chỉ có mộttypesmảng cho biết loại của phần địa chỉ cụ thể đó. Các giá trị này được lấy từ bảng Loại địa chỉ và loại thành phần địa chỉ trên trang Loại địa điểm (Mới).
Đối tượng JSON hoàn chỉnh có dạng:
{ "results": [ { "place": "//places.googleapis.com/places/ChIJF4Yf2Ry7j4AR__1AkytDyAE", "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE", "location": { "latitude": 37.422010799999995, "longitude": -122.08474779999999 }, "granularity": "ROOFTOP", "viewport": { "low": { "latitude": 37.420656719708511, "longitude": -122.08547523029148 }, "high": { "latitude": 37.4233546802915, "longitude": -122.0827772697085 } }, "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94043", "administrativeArea": "CA", "locality": "Mountain View", "addressLines": [ "1600 Amphitheatre Pkwy" ] }, "addressComponents": [ { "longText": "1600", "shortText": "1600", "types": [ "street_number" ] }, { "longText": "Amphitheatre Parkway", "shortText": "Amphitheatre Pkwy", "types": [ "route" ], "languageCode": "en" }, ... ], "types": [ "street_address" ], "plusCode": { "globalCode": "849VCWC8+R4", "compoundCode": "CWC8+R4 Mountain View, CA, USA" } } ] }
Tham số bắt buộc
address– Địa chỉ đường phố hoặc Plus Code mà bạn muốn mã hoá địa lý. Lưu ý: Tính năng mã hoá địa lý địa chỉ không phân giải toạ độ vĩ độ và kinh độ, hoặc các chuỗi không có cấu trúc khác không đại diện cho địa chỉ hoặc Plus Code. Hãy xem phần Truyền chuỗi địa chỉ không có cấu trúc để biết thêm thông tin và ví dụ về các truy vấn không được hỗ trợ. Chỉ định địa chỉ theo định dạng mà dịch vụ bưu chính quốc gia của quốc gia liên quan sử dụng. Bạn nên tránh các thành phần địa chỉ bổ sung như tên doanh nghiệp và số đơn vị, dãy nhà hoặc tầng. Các thành phần địa chỉ đường phố phải được phân tách bằng dấu cách được mã hoá URL thành%20. Ví dụ: truyền địa chỉ "24 Sussex Drive Ottawa ON" như sau:24%20Sussex%20Drive%20Ottawa%20ON
%2Bvà dấu cách được mã hoá URL thành%20:- Mã toàn cầu là mã vùng gồm 4 ký tự và mã địa phương gồm 6 ký tự trở lên. Ví dụ: mã hoá "849VCWC8+R9" thành
849VCWC8%2BR9. - A mã ghép là mã địa phương gồm 6 ký tự trở lên có vị trí
rõ ràng. Ví dụ: mã hoá "CWC8+R9 Mountain View, CA, USA"
thành
CWC8%2BR9%20Mountain%20View%20CA%20USA.
- Mã toàn cầu là mã vùng gồm 4 ký tự và mã địa phương gồm 6 ký tự trở lên. Ví dụ: mã hoá "849VCWC8+R9" thành
Thông số tùy chọn
locationBias
Chỉ định một khu vực để tìm kiếm dưới dạng
Viewport. Vị trí này đóng vai trò là một xu hướng, nghĩa là kết quả xung quanh vị trí đã chỉ định có thể được trả về, bao gồm cả kết quả ở gần nhưng bên ngoài khu vực đó.Chỉ định khu vực dưới dạng Khung nhìn hình chữ nhật. Hình chữ nhật là khung nhìn vĩ độ-kinh độ, được biểu thị dưới dạng 2 điểm thấp và cao đối diện theo đường chéo. Điểm thấp đánh dấu góc tây nam của hình chữ nhật và điểm cao đại diện cho góc đông bắc của hình chữ nhật.
Khung nhìn được coi là một khu vực khép kín, nghĩa là bao gồm cả ranh giới của nó. Giới hạn vĩ độ phải nằm trong khoảng từ -90 đến 90 độ (bao gồm cả hai giá trị này) và giới hạn kinh độ phải nằm trong khoảng từ -180 đến 180 độ (bao gồm cả hai giá trị này):
- Nếu
low=high, khung nhìn sẽ bao gồm điểm duy nhất đó. - Nếu
low.longitude>high.longitude, dải kinh độ sẽ bị đảo ngược (khung nhìn cắt đường kinh độ 180 độ). - Nếu
low.longitude= -180 độ vàhigh.longitude= 180 độ, khung nhìn sẽ bao gồm tất cả các kinh độ. - Nếu
low.longitude= 180 độ vàhigh.longitude= -180 độ, dải kinh độ sẽ trống. - Nếu
low.latitude>high.latitude, dải vĩ độ sẽ trống.
Bạn phải điền cả giá trị thấp và cao, đồng thời hộp được biểu thị không được trống. Khung nhìn trống sẽ dẫn đến lỗi.
Ví dụ: chuỗi truy vấn này xác định khung nhìn bao quanh hoàn toàn Thành phố New York:
?locationBias.rectangle.low.latitude=40.477398
&locationBias.rectangle.low.longitude=-74.259087 &locationBias.rectangle.high.latitude=40.91618 &locationBias.rectangle.high.longitude=-73.70018 - Nếu
languageCode
Ngôn ngữ để trả về kết quả.
- Xem danh sách ngôn ngữ được hỗ trợ . Google thường cập nhật các ngôn ngữ được hỗ trợ, vì vậy, danh sách này có thể không đầy đủ.
-
Nếu bạn không cung cấp
languageCode, API sẽ mặc định làen. Nếu bạn chỉ định mã ngôn ngữ không hợp lệ, API sẽ trả về lỗiINVALID_ARGUMENT. - API sẽ cố gắng cung cấp địa chỉ đường phố mà cả người dùng và người dân địa phương đều có thể đọc được. Để đạt được mục tiêu đó, API sẽ trả về địa chỉ đường phố bằng ngôn ngữ địa phương, được chuyển tự sang một tập lệnh mà người dùng có thể đọc được nếu cần, đồng thời tuân thủ ngôn ngữ ưu tiên. Tất cả các địa chỉ khác được trả về bằng ngôn ngữ ưu tiên. Tất cả các thành phần địa chỉ đều được trả về bằng cùng một ngôn ngữ, được chọn từ thành phần đầu tiên.
- Nếu không có tên bằng ngôn ngữ ưu tiên, API sẽ sử dụng kết quả gần đúng nhất.
- Ngôn ngữ ưu tiên có ảnh hưởng nhỏ đến tập hợp kết quả mà API chọn trả về và thứ tự trả về. Bộ mã hoá địa lý diễn giải các từ viết tắt theo cách khác nhau tuỳ thuộc vào ngôn ngữ, chẳng hạn như các từ viết tắt cho loại đường hoặc từ đồng nghĩa có thể hợp lệ ở một ngôn ngữ nhưng không hợp lệ ở ngôn ngữ khác.
regionCode
Mã khu vực dưới dạng giá trị mã CLDR gồm 2 ký tự. Không có giá trị mặc định. Hầu hết các mã CLDR đều giống với mã ISO 3166-1.
Khi mã hoá địa lý một địa chỉ, mã hoá địa lý chuyển tiếp, tham số này có thể ảnh hưởng nhưng không hạn chế hoàn toàn kết quả từ dịch vụ đối với khu vực đã chỉ định. Khi mã hoá địa lý một vị trí hoặc địa điểm, mã hoá địa lý ngược hoặc mã hoá địa lý địa điểm, bạn có thể sử dụng tham số này để định dạng địa chỉ. Trong mọi trường hợp, tham số này có thể ảnh hưởng đến kết quả dựa trên luật hiện hành.
-
FieldMask
Tạo mặt nạ trường phản hồi để chỉ định các trường cần trả về trong phản hồi. Truyền mặt nạ trường phản hồi vào phương thức bằng cách sử dụng tham số URL
$fieldshoặcfields, hoặc bằng cách sử dụng tiêu đề HTTPX-Goog-FieldMask. Ví dụ: yêu cầu bên dưới sẽ chỉ trả về trườngplaceIDcủa phản hồi.curl -X GET -H 'Content-Type: application/json' \ -H 'X-Goog-FieldMask: results.placeId' \ -H "X-Goog-Api-Key: API_KEY" \ https://geocode.googleapis.com/v4/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA
{ "results": [ { "placeId": "ChIJiSSC8QK6j4AR98Thup8mqTc" } ] }
Hãy xem phần Chọn các trường cần trả về để biết thêm thông tin.
Xu hướng vị trí
Sử dụng tham số locationBias để hướng dẫn dịch vụ Mã hoá địa lý ưu tiên kết quả trong một khung nhìn nhất định (được biểu thị dưới dạng hộp giới hạn).
Tham số locationBias xác định toạ độ vĩ độ/kinh độ của các góc tây nam và đông bắc của hộp giới hạn này.
Ví dụ: yêu cầu mã hoá địa lý cho địa chỉ "Washington" có thể trả về kết quả cho Washington, D.C. và cho tiểu bang Washington của Hoa Kỳ:
https://geocode.googleapis.com/v4/geocode/address/Washington?key=API_KEY
Phản hồi có dạng:
{ "results": [ { "place": "//places.googleapis.com/places/ChIJW-T2Wt7Gt4kRKl2I1CJFUsI", "placeId": "ChIJW-T2Wt7Gt4kRKl2I1CJFUsI", "location": { "latitude": 38.9071923, "longitude": -77.0368707 }, "granularity": "APPROXIMATE", "viewport": { "low": { "latitude": 38.7916449, "longitude": -77.119759 }, "high": { "latitude": 38.9958641, "longitude": -76.909393 } }, "bounds": { "low": { "latitude": 38.7916449, "longitude": -77.119759 }, "high": { "latitude": 38.9958641, "longitude": -76.909393 } }, "formattedAddress": "Washington, DC, USA", "addressComponents": [ { "longText": "Washington", "shortText": "Washington", "types": [ "locality", "political" ], "languageCode": "en" }, ... ], "types": [ "locality", "political" ] }, { "place": "//places.googleapis.com/places/ChIJ-bDD5__lhVQRuvNfbGh4QpQ", "placeId": "ChIJ-bDD5__lhVQRuvNfbGh4QpQ", "location": { "latitude": 47.7510741, "longitude": -120.7401386 }, "granularity": "APPROXIMATE", "viewport": { "low": { "latitude": 45.543541, "longitude": -124.84897389999999 }, "high": { "latitude": 49.0024945, "longitude": -116.91607109999998 } }, "bounds": { "low": { "latitude": 45.543541, "longitude": -124.84897389999999 }, "high": { "latitude": 49.0024442, "longitude": -116.91607109999998 } }, "formattedAddress": "Washington, USA", "addressComponents": [ { "longText": "Washington", "shortText": "WA", "types": [ "administrative_area_level_1", "political" ], "languageCode": "en" }, ... ], "types": [ "administrative_area_level_1", "political" ] } ] }
Tuy nhiên, việc thêm tham số locationBias xác định hộp giới hạn xung quanh phần đông bắc của Hoa Kỳ sẽ khiến mã địa lý này chỉ trả về thành phố Washington, D.C.:
https://geocode.googleapis.com/v4/geocode/address/Washington?locationBias.rectangle.low.latitude=36.47&locationBias.rectangle.low.longitude=-84.72 &locationBias.rectangle.high.latitude=43.39 &locationBias.rectangle.high.longitude=-65.90 &key=API_KEY
Xu hướng khu vực
Trong yêu cầu mã hoá địa lý, bạn có thể hướng dẫn dịch vụ Mã hoá địa lý trả về kết quả có xu hướng đối với một khu vực cụ thể bằng cách sử dụng tham số regionCode. Tham số này lấy giá trị mã CLDR gồm
2 ký tự chỉ định xu hướng khu vực. Hầu hết các mã CLDR đều giống với mã ISO 3166-1.
Không có giá trị mặc định cho regionCode. Ví dụ: mã địa lý cho "Toledo" trả về kết quả cho Hoa Kỳ và Tây Ban Nha:
https://geocode.googleapis.com/v4/geocode/address/Toledo?key=API_KEY
Phản hồi:
{ "results": [ { "place": "//places.googleapis.com/places/ChIJeU4e_C2HO4gRRcM6RZ_IPHw", "placeId": "ChIJeU4e_C2HO4gRRcM6RZ_IPHw", "location": { "latitude": 41.652805199999996, "longitude": -83.5378674 }, "granularity": "APPROXIMATE", "viewport": { "low": { "latitude": 41.579513, "longitude": -83.6944089 }, "high": { "latitude": 41.733036, "longitude": -83.4493851 } }, "bounds": { "low": { "latitude": 41.579513, "longitude": -83.6944089 }, "high": { "latitude": 41.733036, "longitude": -83.4493851 } }, "formattedAddress": "Toledo, OH, USA", "addressComponents": [ { "longText": "Toledo", "shortText": "Toledo", "types": [ "locality", "political" ], "languageCode": "en" }, ... ], "types": [ "locality", "political" ] }, { "place": "//places.googleapis.com/places/ChIJkwyrlqwLag0RiQIn2fdIshM", "placeId": "ChIJkwyrlqwLag0RiQIn2fdIshM", "location": { "latitude": 39.8628296, "longitude": -4.0273067 }, "granularity": "APPROXIMATE", "viewport": { "low": { "latitude": 39.8116682, "longitude": -4.179933 }, "high": { "latitude": 39.9251319, "longitude": -3.8148935 } }, "bounds": { "low": { "latitude": 39.8116682, "longitude": -4.179933 }, "high": { "latitude": 39.9251319, "longitude": -3.8148935 } }, "formattedAddress": "Toledo, España", "addressComponents": [ { "longText": "Toledo", "shortText": "Toledo", "types": [ "administrative_area_level_4", "political" ], "languageCode": "es" }, ... ], "types": [ "administrative_area_level_4", "political" ] }, ... ] }
Yêu cầu mã hoá địa lý cho "Toledo" có regionCode=es (Tây Ban Nha) chỉ trả về kết quả từ Tây Ban Nha:
https://geocode.googleapis.com/v4/geocode/address/Toledo?regionCode=es&key=API_KEY