Google sử dụng công nghệ AI để dịch nội dung sang ngôn ngữ bạn ưu tiên. Bản dịch bằng AI có thể có lỗi.

Mã địa điểm

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

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

Giới thiệu

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 những Maps API sau:

Truy xuất địa chỉ cho một mã địa điểm trong Geocoding API và Geocoding Service, Maps JavaScript API.
Chỉ định điểm xuất phát, điểm đến và các điểm tham chiếu trung gian trong Routes API và Directions API (cũ) cũng như Directions Service, Maps JavaScript API (cũ).
Chỉ định điểm xuất phát và điểm đến trong Routes API và Distance Matrix API (Cũ) cũng như Distance Matrix Service, Maps JavaScript API (Cũ).
Truy xuất thông tin chi tiết về địa điểm trong Places API (mới), Places SDK cho Android (mới), Places SDK cho iOS (mới) và Thư viện Địa điểm.
Sử dụng các tham số mã địa điểm trong Maps Embed API.
Đang 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 Roads API.
Tìm và định kiểu cho đa giác ranh giới trong tính năng định kiểu dựa trên dữ liệu cho ranh giới.

Tìm mã 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 kiế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 cùng với 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à một giá trị nhận dạng dạng văn bản giúp xác định riêng một địa điểm. Độ dài của giá trị nhận dạng có thể thay đổi (không có độ dài tối đa cho Mã địa điểm). Ví dụ:

ChIJgUbEo8cfqokR5lP9_Wh_DaM
GhIJQWDl0CIeQUARxks3icF8U8A
EicxMyBNYXJrZXQgU3QsIFdpbG1pbmd0b24sIE5DIDI4NDAxLCBVU0EiGhIYChQKEgnRTo6ixx-qiRHo_bbmkCm7ZRAN
EicxMyBNYXJrZXQgU3QsIFdpbG1pbmd0b24sIE5DIDI4NDAxLCBVU0E
IhoSGAoUChIJ0U6OoscfqokR6P225pApu2UQDQ

Mã địa điểm được cung cấp 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 khác nhau. 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 Places API và một số API của Nền tảng Google Maps. Ví dụ: bạn có thể dùng cùng một mã địa điểm để tham chiếu một địa điểm trong Places API, Maps JavaScript API, Geocoding API, Maps Embed API và Roads API.

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

Cách phổ biến để sử dụng mã địa điểm là tìm kiếm địa điểm bằng cách sử dụng Places API hoặc Thư viện địa điểm trong Maps JavaScript API. Sau đó, hãy dùng Mã địa điểm được trả về để truy xuất Place Details. Bạn có thể lưu trữ Mã địa điểm và sử dụng mã đó để truy xuất Place Details về cùng một địa điểm sau này. Đọc về cách lưu mã địa điểm ở phần sau của tài liệu này.

Ví dụ sử dụng Places SDK cho Android (mới)

Trong Places SDK cho Android (mới), 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ụ Place Autocomplete (Legacy) cũng trả về một 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 đượ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 một FetchPlaceRequest.

API này trả về một FetchPlaceResponse trong Task. FetchPlaceResponse chứa một đố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 được chỉ định.

Kotlin

// Define a Place ID.
val placeId = PlaceIdProvider.getRandomPlaceId()

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

// 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

        val name = place.displayName
        val address = place.formattedAddress
        val location = place.location

        binding.placeName.text = name
        binding.placeAddress.text = address
        if (location != null) {
            binding.placeLocation.text = getString(
                R.string.place_location, location.latitude, location.longitude
            )
        } else {
            binding.placeLocation.text = null
        }
        Log.i(TAG, "Place found: ${place.displayName}")
    }.addOnFailureListener { exception: Exception ->
        if (exception is ApiException) {
            val message = getString(R.string.place_not_found, exception.message)
            binding.placeName.text = message
            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 = PlaceIdProvider.getRandomPlaceId();

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

// 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();

    final CharSequence name = place.getDisplayName();
    final CharSequence address = place.getFormattedAddress();
    final LatLng location = place.getLocation();

    binding.placeName.setText(name);
    binding.placeAddress.setText(address);
    if (location != null) {
        binding.placeLocation.setText(
                getString(R.string.place_location, location.latitude, location.longitude)
        );
    } else {
        binding.placeLocation.setText(null);
    }

    Log.i(TAG, "Place found: " + place.getDisplayName());
}).addOnFailureListener((exception) -> {
    if (exception instanceof ApiException apiException) {
        final String message = getString(R.string.place_not_found, apiException.getMessage());
        binding.placeName.setText(message);
        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 theo các quy định hạn chế về việc lưu vào bộ nhớ đệm được 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 này.

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

Vì mã địa điểm có thể thay đổi do các bản cập nhật trên cơ sở dữ liệu của Google Maps, nên Google khuyến nghị bạn làm mới mã địa điểm nếu mã đó đã được tạo hơn 12 tháng. Bạn có thể làm mới Mã địa điểm miễn phí bằng cách đưa ra một yêu cầu 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 Place Details – Làm mới mã nhận dạng.

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

`INVALID_REQUEST`

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.

`NOT_FOUND`

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ể trở nên lỗi thời nếu một doanh nghiệp đóng cửa hoặc chuyển đến một địa điểm mới. Mã địa điểm cũng có thể thay đổi do 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ã địa điểm cũ sẽ trả về phản hồi NOT_FOUND.

Để làm mới kết quả trong trường hợp mã địa điểm không còn hiệu lực, hãy lưu trữ yêu cầu ban đầu đã trả về từng mã địa điểm và phát hành lại yêu cầu nếu cần. Xin lưu ý rằng yêu cầu được phát hành lại sẽ được tính phí theo SKU thích hợp.

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ã đị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, nhưng đượ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ộ.
Những địa điểm có thành phần địa chỉ thuộc loại subpremise.

Các mã nhận dạng này thường có dạng một 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