Mã hoá địa lý một địa điểm

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

Tính năng mã hoá địa lý cho địa điểm cho phép bạn truy xuất địa chỉ từ một place ID (mã địa điểm).

Mã địa điểm giúp xác định riêng một địa điểm trong cơ sở dữ liệu của Google Địa điểm và trên Google Maps. Truy xuất mã địa điểm khi bạn Mã hoá địa lý một địa chỉ. Bạn cũng có thể truy xuất mã địa điểm từ nhiều API khác, chẳng hạn như Chi tiết địa điểm (Mới), Tìm kiếm bằng văn bản (Mới), và Tìm kiếm lân cận (Mới).

Đưa ra yêu cầu mã hoá địa lý cho địa điểm

Yêu cầu địa lý mã hoá vị trí là một yêu cầu HTTP GET ở dạng:

https://geocode.googleapis.com/v4/geocode/places/PLACE_ID

Trong đó PLACE_ID chứa mã địa điểm của vị trí mà người dùng quan tâm.

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 hoặc mặt nạ trường, hãy truyền trong tiêu đề dưới dạng một phần của yêu cầu GET. Ví dụ:

https://geocode.googleapis.com/v4/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw?key=API_KEY

Hoặc trong lệnh curl:

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw"

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 phạm vi chính xác 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ý địa điểm:

  • 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.place — Chỉ sử dụng với GeocodePlace để mã hoá địa lý cho địa điểm.

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 của 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 phát hành công khai, 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 bài viết Sử dụng OAuth.

Câu trả lời về mã hoá địa lý cho địa điểm

Mã hoá địa lý địa điểm trả về một đối tượng GeocodeResult đại diện cho địa điểm tương ứng với mã địa điểm.

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 tổng thể của kết quả. Các giá trị có thể có được lấy từ các loại Địa điểm mà Places API sử dụng. Để biết thêm thông tin, hãy xem Bảng A và B về loại địa điểm.
  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 Các loại địa chỉ và thành phần địa chỉ mà Places API sử dụng.

Đối tượng JSON hoàn chỉnh có dạng:

{
  "place": "//places.googleapis.com/places/ChIJj61dQgK6j4AR4GeTYWZsKWw",
  "placeId": "ChIJj61dQgK6j4AR4GeTYWZsKWw",
  "location": {
    "latitude": 37.4220541,
    "longitude": -122.08532419999999
  },
  "granularity": "ROOFTOP",
  "viewport": {
    "low": {
      "latitude": 37.4209489697085,
      "longitude": -122.08846930000001
    },
    "high": {
      "latitude": 37.4236469302915,
      "longitude": -122.0829156
    }
  },
  "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"
    },
    {
      "longText": "Mountain View",
      "shortText": "Mountain View",
      "types": [
        "locality",
        "political"
      ],
      "languageCode": "en"
    },
    {
      "longText": "Santa Clara County",
      "shortText": "Santa Clara County",
      "types": [
        "administrative_area_level_2",
        "political"
      ],
      "languageCode": "en"
    },
    {
      "longText": "California",
      "shortText": "CA",
      "types": [
        "administrative_area_level_1",
        "political"
      ],
      "languageCode": "en"
    },
    {
      "longText": "United States",
      "shortText": "US",
      "types": [
        "country",
        "political"
      ],
      "languageCode": "en"
    },
    {
      "longText": "94043",
      "shortText": "94043",
      "types": [
        "postal_code"
      ]
    }
  ],
  "types": [
    "establishment",
    "point_of_interest"
  ]
}

Tham số bắt buộc

  • place — Mã địa điểm của địa điểm mà bạn muốn lấy địa chỉ mà con người có thể đọc được. Mã địa điểm là một giá trị nhận dạng riêng biệt có thể dùng với các API khác của Google. Ví dụ: bạn có thể sử dụng placeID do Roads API trả về để lấy địa chỉ cho một điểm được ghim. Để biết thêm thông tin về mã địa điểm, hãy xem phần Mã địa điểm.

Thông số tùy chọn

  • 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 sử dụng ngôn ngữ và tập lệnh của vị trí. Nếu bạn chỉ định một mã ngôn ngữ không hợp lệ, thì API sẽ trả về lỗi INVALID_ARGUMENT.
    • API này cố gắng hết sức để 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 này sẽ trả về địa chỉ đường phố bằng ngôn ngữ địa phương, được chuyển tự sang một hệ chữ viết 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ả 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 nhóm 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ư 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ý cho 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.

  • 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 formattedAddress của phản hồi.

    curl -X GET -H 'Content-Type: application/json' \
-H 'X-Goog-FieldMask: formattedAddress' \
-H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
    Phản hồi: 
    {
  "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA"
}

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