Mã hoá địa lý địa chỉ

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 về địa chỉ mở rộng

Yêu cầu mã địa lý

Yêu cầu địa lý hoá là một yêu cầu HTTP GET. Bạn có thể chỉ định địa chỉ dưới dạng một chuỗi không có cấu trúc:

https://geocode.googleapis.com/v4beta/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/v4beta/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 ghi lại trong biểu mẫu HTML.

Truyền tất cả các thông số khác dưới dạng thông số URL hoặc đối với các thông số như khoá API và mặt nạ trường, trong tiêu đề dưới dạng một phần của yêu cầu GET.

Truyền một 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. 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/v4beta/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/v4beta/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ụ: "/" như trong "7/1 King St, Concord West". Mã hoá URL "/" thành %2F:

https://geocode.googleapis.com/v4beta/geocode/address/7%2F1+King+St,+Concord+West
?key=API_KEY

Một ví dụ phổ biến khác là ký tự "#", chẳng hạn như "9500 W Bryn Mawr Ave #650, Rosemont". Mã hoá URL cho "#" dưới dạng %2FE:

https://geocode.googleapis.com/v4beta/geocode/address/9500+W+Bryn+Mawr+Ave+%23650,+Rosemont?key=API_KEY

Trong ví dụ tiếp theo, bạn chỉ định một chuỗi địa chỉ không có cấu trúc làm Plus Code 849VCWC8+R4. Đảm bảo rằng bạn mã hoá URL ký tự "+" thành %2B:

https://geocode.googleapis.com/v4beta/geocode/address/849VCWC8%2BR4?key=API_KEY

Truyền địa chỉ có cấu trúc

Chỉ định một đị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ả thành phần địa chỉ trong yêu cầu dưới dạng các tham số truy vấn riêng lẻ.

Ví dụ: để chỉ định mã bưu chính của địa chỉ mà bạn sử dụng PostalAddress.postalCode:

https://geocode.googleapis.com/v4beta/geocode/address?address.postalCode=01062&key=API_KEY

Để chỉ định nhiều thành phần địa chỉ, chẳng hạn như đối với các thành phần địa chỉ được ghi lại trong biểu mẫu HTML, hãy sử dụng nhiều tham số truy vấn:

https://geocode.googleapis.com/v4beta/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 phiên bản 4 hỗ trợ OAuth 2.0 để xác thực. Để sử dụng OAuth với Geocoding API, bạn phải chỉ định đúng phạm vi cho mã thông báo OAuth. Geocoding API hỗ trợ các phạm vi sau để sử dụng với tính năng mã hoá địa lý xuôi:

• https://www.googleapis.com/auth/maps-platform.geocode – Sử dụng với tất cả các điểm cuối của Geocoding API.
• https://www.googleapis.com/auth/maps-platform.geocode.address – Chỉ sử dụng với GeocodeAddress để chuyển đổi địa chỉ thành toạ độ.

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 điểm cuối của Geocoding API. Phạm vi đó rất 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à một phạm vi chung cho phép truy cập vào tất cả các điểm cuối.

Để biết thêm thông tin và ví dụ, hãy xem phần Sử dụng OAuth.

Phản hồi mã địa lý

Dịch mã địa lý trả về một đối tượng GeocodeAddressResponse chứa mảng results gồm các đối tượng GeocodeResult. Mỗi đối tượng GeocodeResult đại diện cho một địa điểm duy nhất.

Đố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"
      }
    }
  ]
}

Thông số bắt buộc

• address – Địa chỉ đường phố hoặc Plus Code mà bạn muốn mã hoá địa lý. Hãy 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 khác trong địa chỉ, chẳng hạn như tên doanh nghiệp và số căn hộ, số nhà hoặc số tầng. Các phần tử địa chỉ đường phố phải được phân tách bằng dấu cách và được mã hoá URL thành %20. Ví dụ: truyền địa chỉ "24 Sussex Drive Ottawa ON" dưới dạng:

  24%20Sussex%20Drive%20Ottawa%20ON

  Định dạng mã Plus như minh hoạ bên dưới. Dấu cộng được mã hoá URL thành %2B và 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.
  • Mã kết hợp là mã địa phương có từ 6 ký tự trở lên và có vị trí rõ ràng. Ví dụ: mã hoá "CWC8+R9 Mountain View, CA, Hoa Kỳ" thành CWC8%2BR9%20Mountain%20View%20CA%20USA.

Thông số tùy chọn

• locationBias

  Chỉ định một vùng để tìm kiếm dưới dạng Viewport. Vị trí này đóng vai trò là một thiên kiến, tức là các kết quả xung quanh vị trí được chỉ định có thể được trả về, bao gồm cả các kết quả ở gần nhưng nằm ngoài khu vực.

  Chỉ định khu vực dưới dạng một Khung hiển thị hình chữ nhật. Hình chữ nhật là một khung hiển thị vĩ độ-kinh độ, được biểu thị dưới dạng hai đ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, còn điểm cao biểu thị góc đông bắc của hình chữ nhật.

  Khung nhìn được coi là một vùng khép kín, tức là bao gồm cả ranh giới của vùng đó. Phạm vi vĩ độ phải nằm trong khoảng từ -90 đến 90 độ (bao gồm cả hai giá trị này), còn phạm vi 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, thì phạm vi kinh độ sẽ bị đảo ngược (khung nhìn vượt qua đường kinh độ 180 độ).
  • Nếu low.longitude = -180 độ và high.longitude = 180 độ, thì khung nhìn sẽ bao gồm tất cả các kinh độ.
  • Nếu low.longitude = 180 độ và high.longitude = -180 độ, thì phạm vi kinh độ sẽ trống.
  • Nếu low.latitude > high.latitude, thì phạm vi 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 hiển thị trống sẽ dẫn đến lỗi.

  Ví dụ: chuỗi truy vấn này xác định một khung hiển thị bao trọ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

• languageCode

  Ngôn ngữ mà bạn muốn nhận kết quả.

  • Xem danh sách ngôn ngữ được hỗ trợ. Google thường xuyên cập nhật các ngôn ngữ được hỗ trợ, vì vậy, danh sách này có thể chưa đầ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ột mã ngôn ngữ không hợp lệ, API sẽ trả về lỗi INVALID_ARGUMENT.
  • API này cố gắng cung cấp một đị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 đó, phương thức này sẽ trả về địa chỉ đường phố bằng ngôn ngữ địa phương, được chuyển tự sang một kịch bản mà người dùng có thể đọc được (nếu cần), tuân theo ngôn ngữ ưu tiên. Tất cả các địa chỉ khác đều đượ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ả trùng khớp gần 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ề. Trình mã hoá địa lý diễn giải các từ viết tắt theo nhiều cách tuỳ thuộc vào ngôn ngữ, chẳng hạn như từ viết tắt cho các loại đường phố hoặc từ đồng nghĩa có thể hợp lệ trong một ngôn ngữ nhưng không hợp lệ trong ngôn ngữ khác.

• regionCode

  Mã vùng 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 mã CLDR đều giống với mã ISO 3166-1.

  Khi mã hoá địa lý một địa chỉ, mã hoá địa lý xuôi, tham số này có thể ảnh hưởng nhưng không hoàn toàn hạn chế kết quả từ dịch vụ đối với khu vực được chỉ định. Khi mã hoá địa lý một vị trí hoặc một địa điểm, mã hoá địa lý ngược hoặc mã hoá địa lý địa điểm, bạn có thể 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.

Thiên vị về vị trí

Sử dụng tham số locationBias để hướng dẫn dịch vụ Địa lý mã hoá ưu tiên kết quả trong một khung hiển thị nhất định (được biểu thị dưới dạng một 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ụ: một 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/v4beta/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 một tham số locationBias xác định một 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/v4beta/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 theo 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ả thiên về một khu vực cụ thể bằng cách sử dụng tham số regionCode. Tham số này nhận giá trị mã CLDR gồm 2 ký tự chỉ định độ lệch khu vực. Hầu hết 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" sẽ trả về kết quả cho Hoa Kỳ và Tây Ban Nha:

https://geocode.googleapis.com/v4beta/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" bằng regionCode=es (Tây Ban Nha) chỉ trả về kết quả từ Tây Ban Nha:

https://geocode.googleapis.com/v4beta/geocode/address/Toledo?regionCode=es&key=API_KEY