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

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

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ạ độ theo 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/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 ghi lại 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, 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. Tính năng mã hoá địa lý địa chỉ không phân giải được toạ độ vĩ độ và kinh độ, hoặc các chuỗi không có cấu trúc khác không biểu thị một địa chỉ hoặc mã Plus. 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ề những 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 phương thức 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 cụm từ tìm kiếm "Market Street San Francisco San Jose Airport"
Các phần tử địa chỉ bưu chính không được thể hiện 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 cửa hàng hoặc danh mục kết hợp với những vị trí mà các thực thể này không có mặt "Tesco gần Dallas, Texas"
Truy vấn mơ hồ có nhiều cách diễn giải "Trả lại bộ sạc"
Tên cũ không còn được sử dụng nữa "Middlesex, Vương quốc Anh"
Phần tử hoặc ý định không gian địa lý "Có bao nhiêu chiếc thuyền ở Cảng Ventura?"
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ụ: "/" như trong "7/1 King St, Concord West". Mã hoá URL "/" 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ự "#", chẳng hạn như "9500 W Bryn Mawr Ave #650, Rosemont". Mã hoá URL "#" 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 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/v4/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/v4/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/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 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 phương thức 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 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à một 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 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.

Phản hồi của Geocoding API bao gồm các mảng types ở 2 vị trí chính trong GeocodeResult:

  1. GeocodeResult.types: Mảng này cho biết(các) loại kết quả tổng thể. Các giá trị có thể được lấy từ Bảng A và Bảng B trên trang Loại địa điểm (Mới).
  2. GeocodeResult.addressComponents[].types: Mỗi thành phần địa chỉ đều có một mảng types 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"
      }
    }
  ]
}

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ý. 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 Mã Plus. Hãy xem phần Truyền một 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 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 không được để trống hộp được biểu thị. 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 các 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ã 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 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 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.

  • FieldMask

    Tạo một 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 đến phương thức bằng cách sử dụng tham số URL $fields hoặc fields, hoặc bằng cách sử dụng tiêu đề HTTP X-Goog-FieldMask. Ví dụ: yêu cầu bên dưới sẽ chỉ trả về trường placeID củ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
    Câu trả lời là: 
    {
  "results": [
    {
      "placeId": "ChIJiSSC8QK6j4AR98Thup8mqTc"
    }
  ]
}

    Xem phần Chọn các trường cần trả về để biết thêm thông tin chi tiết.

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/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 một tham số locationBias xác định một khung hình chữ nhật 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ả 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/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" bằng 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