Trang này được dịch bởi Cloud Translation API.

Mã địa điểm

Chọn nền tảng: Android iOS JavaScript Dịch vụ web

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. Mã địa điểm được chấp nhận trong các yêu cầu gửi đến các API Maps sau:

Truy xuất địa chỉ cho một Mã địa điểm trong dịch vụ web của API Mã hoá địa lý và Dịch vụ mã hoá địa lý, API Maps JavaScript.
Chỉ định điểm xuất phát, điểm đến và điểm trung gian trong dịch vụ web Route API và Directions API cũng như Dịch vụ chỉ đường, API Maps JavaScript.
Chỉ định điểm xuất phát và điểm đến trong API Tuyến đường và dịch vụ web API Ma trận khoảng cách, cũng như Dịch vụ ma trận khoảng cách, API Maps JavaScript.
Truy xuất Thông tin chi tiết về địa điểm trong dịch vụ web API Địa điểm, SDK Địa điểm dành cho Android, SDK Địa điểm dành cho iOS và Thư viện Địa điểm.
Sử dụng các tham số Mã địa điểm trong Maps Embed API.
Truy xuất cụm từ tìm kiếm trong URL của Maps.
Hiển thị giới hạn tốc độ trong API Đường.
Tìm và tạo kiểu đa giác ranh giới trong kiểu dựa trên dữ liệu cho ranh giới.

Tìm mã nhận dạng của một địa điểm cụ thể

Bạn đang tìm mã địa điểm của một địa điểm cụ thể? Sử dụng công cụ tìm mã địa điểm bên dưới để tìm một địa điểm và lấy mã địa điểm của địa điểm đó:

Ngoài ra, bạn có thể xem trình tìm mã địa điểm bằng mã của trình tìm này trong tài liệu về API JavaScript của Maps.

Tổng quan

Mã địa điểm là giá trị nhận dạng dạng văn bản giúp xác định duy nhất một địa điểm. Độ dài của giá trị nhận dạng có thể khác nhau (không có độ dài tối đa cho Mã địa điểm). Ví dụ:

ChIJgUbEo8cfqokR5lP9_Wh_DaM
GhIJQWDl0CIeQUARxks3icF8U8A
EicxMyBNYXJrZXQgU3QsIFdpbG1pbmd0b24sIE5DIDI4NDAxLCBVU0EiGhIYChQKEgnRTo6ixx-qiRHo_bbmkCm7ZRAN
EicxMyBNYXJrZXQgU3QsIFdpbG1pbmd0b24sIE5DIDI4NDAxLCBVU0E
IhoSGAoUChIJ0U6OoscfqokR6P225pApu2UQDQ

Mã địa điểm có sẵn cho hầu hết các vị trí, bao gồm cả doanh nghiệp, địa danh, công viên và giao lộ. Một địa điểm hoặc vị trí có thể có nhiều mã địa điểm. Mã địa điểm có thể thay đổi theo thời gian.

Bạn có thể sử dụng cùng một mã địa điểm trên API Địa điểm và một số API Nền tảng Google Maps. Ví dụ: bạn có thể sử dụng cùng một mã địa điểm để tham chiếu một địa điểm trong API Địa điểm, API Maps JavaScript, API Mã hoá địa lý, API Nhúng Maps và API Đường.

Truy xuất thông tin chi tiết về địa điểm bằng mã địa điểm

Một cách phổ biến để sử dụng mã địa điểm là tìm kiếm một địa điểm (ví dụ: sử dụng Places API hoặc thư viện Địa điểm trong API Maps JavaScript), sau đó sử dụng mã địa điểm được trả về để truy xuất thông tin chi tiết về địa điểm. Bạn có thể lưu trữ mã địa điểm và sử dụng mã này để truy xuất thông tin về cùng một địa điểm sau này. Hãy đọc phần lưu mã địa điểm ở bên dưới.

Ví dụ về cách sử dụng SDK Địa điểm dành cho Android

Trong SDK Địa điểm dành cho Android, bạn có thể truy xuất mã nhận dạng của một địa điểm bằng cách gọi Place.getId(). Dịch vụ Tự động hoàn thành địa điểm cũng trả về mã địa điểm cho mỗi địa điểm khớp với cụm từ tìm kiếm và bộ lọc đã cung cấp. Sử dụng mã địa điểm để truy xuất lại đối tượng Place sau.

Để lấy một địa điểm theo mã nhận dạng, hãy gọi PlacesClient.fetchPlace(), truyền FetchPlaceRequest.

API trả về một FetchPlaceResponse trong Task. FetchPlaceResponse chứa đối tượng Place khớp với mã địa điểm được cung cấp.

Ví dụ về mã sau đây cho thấy cách gọi fetchPlace() để lấy thông tin chi tiết về địa điểm đã chỉ định.

Kotlin

// Define a Place ID.
val placeId = "INSERT_PLACE_ID_HERE"

// Specify the fields to return.
val placeFields = listOf(Place.Field.ID, Place.Field.NAME)

// Construct a request object, passing the place ID and fields array.
val request = FetchPlaceRequest.newInstance(placeId, placeFields)

placesClient.fetchPlace(request)
    .addOnSuccessListener { response: FetchPlaceResponse ->
        val place = response.place
        Log.i(PlaceDetailsActivity.TAG, "Place found: ${place.name}")
    }.addOnFailureListener { exception: Exception ->
        if (exception is ApiException) {
            Log.e(TAG, "Place not found: ${exception.message}")
            val statusCode = exception.statusCode
            TODO("Handle error with given status code")
        }
    }

Java

// Define a Place ID.
final String placeId = "INSERT_PLACE_ID_HERE";

// Specify the fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

// Construct a request object, passing the place ID and fields array.
final FetchPlaceRequest request = FetchPlaceRequest.newInstance(placeId, placeFields);

placesClient.fetchPlace(request).addOnSuccessListener((response) -> {
    Place place = response.getPlace();
    Log.i(TAG, "Place found: " + place.getName());
}).addOnFailureListener((exception) -> {
    if (exception instanceof ApiException) {
        final ApiException apiException = (ApiException) exception;
        Log.e(TAG, "Place not found: " + exception.getMessage());
        final int statusCode = apiException.getStatusCode();
        // TODO: Handle error with given status code.
    }
});

Lưu mã địa điểm để sử dụng sau

Mã địa điểm không phải tuân thủ các quy định hạn chế về việc lưu vào bộ nhớ đệm nêu trong Mục 3.2.3(b) của Điều khoản dịch vụ của Nền tảng Google Maps. Do đó, bạn có thể lưu trữ các giá trị mã địa điểm để sử dụng sau.

Làm mới mã địa điểm đã lưu trữ

Bạn nên làm mới mã địa điểm nếu mã đó đã tồn tại hơn 12 tháng. Bạn có thể làm mới Mã địa điểm mà không mất phí bằng cách tạo một yêu cầu Thông tin chi tiết về địa điểm, chỉ định trường Place.Field.ID trong tham số fields. Lệnh gọi này kích hoạt SKU Thông tin chi tiết về địa điểm – Làm mới mã nhận dạng.

Yêu cầu này cũng có thể trả về mã trạng thái NOT_FOUND. Một chiến lược là lưu trữ yêu cầu ban đầu đã trả về từng mã địa điểm. Nếu mã địa điểm không hợp lệ, bạn có thể đưa ra yêu cầu đó một lần nữa để nhận kết quả mới. Những kết quả này có thể bao gồm hoặc không bao gồm địa điểm ban đầu. Tuy nhiên, yêu cầu này sẽ tính phí.

Lưu ý: Trong vài ngày đầu tiên sau khi một Mã địa điểm trở nên không hợp lệ, chiến lược này vẫn có thể trả về NOT_FOUND khi yêu cầu ban đầu được sử dụng là yêu cầu Tự động hoàn thành địa điểm hoặc cụm từ tìm kiếm.

Mã lỗi khi sử dụng mã địa điểm

Mã trạng thái INVALID_REQUEST cho biết mã địa điểm được chỉ định không hợp lệ. INVALID_REQUEST có thể được trả về khi mã địa điểm bị cắt bớt hoặc sửa đổi và không còn chính xác nữa.

Mã trạng thái NOT_FOUND cho biết mã địa điểm được chỉ định đã lỗi thời. Mã địa điểm có thể không còn được dùng nữa nếu một doanh nghiệp đóng cửa hoặc chuyển đến một vị trí mới. Mã địa điểm có thể thay đổi do các nội dung cập nhật trên cơ sở dữ liệu của Google Maps. Trong những trường hợp như vậy, một địa điểm có thể nhận được mã địa điểm mới và mã cũ sẽ trả về phản hồi NOT_FOUND.

Cụ thể, một số loại mã địa điểm đôi khi có thể gây ra phản hồi NOT_FOUND hoặc API có thể trả về một mã địa điểm khác trong phản hồi. Các loại mã nhận dạng địa điểm này bao gồm:

Địa chỉ đường phố không tồn tại trong Google Maps dưới dạng địa chỉ chính xác, mà được suy luận từ một dải địa chỉ.
Các đoạn của một tuyến đường dài, trong đó yêu cầu cũng chỉ định một thành phố hoặc địa phương.
Giao lộ.
Địa điểm có thành phần địa chỉ thuộc loại subpremise.

Các mã này thường có dạng chuỗi dài (không có độ dài tối đa cho Mã địa điểm). Ví dụ:

EpID4LC14LC_4LCo4LCv4LGN4LCo4LCX4LCw4LGNIC0g4LC44LGI4LCm4LGN4LCs4LC-4LCm4LGNIOCwsOCxi-CwoeCxjeCwoeCxgSAmIOCwteCwv-CwqOCwr-CxjSDgsKjgsJfgsLDgsY0g4LCu4LGG4LCv4LC_4LCo4LGNIOCwsOCxi-CwoeCxjeCwoeCxgSwg4LC14LC_4LCo4LCv4LGNIOCwqOCwl-CwsOCxjSDgsJXgsL7gsLLgsKjgsYAsIOCwsuCwleCxjeCwt-CxjeCwruCwv-CwqOCwl-CwsOCxjSDgsJXgsL7gsLLgsKjgsYAsIOCwuOCwsOCxguCwsOCxjSDgsKjgsJfgsLDgsY0g4LC14LGG4LC44LGN4LCf4LGNLCDgsLjgsK_gsYDgsKbgsL7gsKzgsL7gsKbgsY0sIOCwueCxiOCwpuCwsOCwvuCwrOCwvuCwpuCxjSwg4LCk4LGG4LCy4LCC4LCX4LC-4LCjIDUwMDA1OSwg4LCt4LC-4LCw4LCk4LCm4LGH4LC24LCCImYiZAoUChIJ31l5uGWYyzsR9zY2qk9lDiASFAoSCd9ZebhlmMs7Efc2NqpPZQ4gGhQKEglDz61OZpjLOxHgDJCFY-o1qBoUChIJi37TW2-YyzsRr_uv50r7tdEiCg1MwFcKFS_dyy4