Các phương thức của Geocoding API v4 có hạn mức mặc định là 25 truy vấn mỗi giây (QPS). Để biết thông tin về cách yêu cầu hạn mức cao hơn, hãy xem bài viết Xem và quản lý hạn mức rồi chọn Geocoding API làm dịch vụ.

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Di chuyển từ Geocoding v3 sang v4

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

Geocoding API phiên bản 4 giới thiệu một số phương thức mới thay thế chức năng trong phiên bản 3 của API này. Hướng dẫn này sẽ cho bạn biết cách di chuyển ứng dụng để sử dụng các phương thức v4 mới.

Bạn có thể sử dụng khoá API hiện có với các phương thức v4 mới. Tuy nhiên, nếu đã yêu cầu tăng hạn mức trên API phiên bản 3, bạn phải yêu cầu tăng hạn mức trên API phiên bản 4 mới.

Di chuyển từ tính năng Mã hoá địa lý xuôi phiên bản 3

Nếu sử dụng v3 Geocoding để mã hoá địa chỉ thành mã địa lý, bạn nên di chuyển sang phương thức Mã hoá địa chỉ thành mã địa lý v4. Phương thức này chấp nhận yêu cầu GET.

API phiên bản 4 thay đổi tên, cấu trúc và khả năng hỗ trợ cho một số tham số. Bạn nên sử dụng một mặt nạ trường để chỉ định các trường mà bạn muốn trả về trong phản hồi.

Yêu cầu thay đổi tham số

Tham số v3	Tham số phiên bản 4	Ghi chú
`address`, `components`	`address`	Địa chỉ không có cấu trúc (v3 `address`) hiện được truyền trong đường dẫn URL. Bạn có thể truyền các thành phần địa chỉ có cấu trúc (`components` phiên bản 3) dưới dạng tham số truy vấn `address.*`. Xem phần Tái tạo bộ lọc thành phần phiên bản 3.
`bounds`	`locationBias.rectangle`	Đã đổi tên; cấu trúc đã thay đổi thành đối tượng.
`language`	`languageCode`	Đã đổi tên.
`region`	`regionCode`	Đã đổi tên.
`extra_computations`	Đã xoá	Được thay thế bằng phương thức SearchDestinations.

Thay đổi về trường phản hồi

Trường v3	Trường v4	Ghi chú
`status`, `error_message`	Đã xoá	Phiên bản 4 sử dụng mã trạng thái HTTP và nội dung lỗi.
`results.address_components.long_name`/`results.address_components.short_name`	`results.addressComponents.longText`/`results.addressComponents.shortText`	Đã đổi tên.
`results.geometry.location_type`	`results.granularity`	Đã đổi tên.
`results.geometry.location`	`results.location`	Tên trường: `lat`/`lng` -> `latitude`/`longitude`.
`results.geometry.viewport`	`results.viewport`	Tên trường: `northeast`/`southwest` -> `high`/`low`.
`results.postcode_localities`	`results.postalCodeLocalities`	Đã đổi tên. Hiện đã trả về cho một hoặc nhiều địa phương (cần có phiên bản 3 > 1).
`results.partial_match`	Đã xoá
Mới	`results.addressComponents.languageCode`	Ngôn ngữ của thành phần địa chỉ cụ thể.
Mới	`results.bounds`	Ranh giới rõ ràng bằng cách sử dụng `high`/`low`.
Mới	`results.place`	Tên tài nguyên của địa điểm.
Mới	`results.postalAddress`	Đối tượng `PostalAddress` có cấu trúc.

Tái tạo bộ lọc thành phần phiên bản 3

Tính năng Chuyển đổi địa chỉ thành toạ độ địa lý xuôi trong Geocoding phiên bản 3 có một tham số components cho phép lọc cứng kết quả cho các thành phần cụ thể (ví dụ: components=country:US). Tính năng Chuyển đổi địa chỉ thành toạ độ địa lý xuôi trong phiên bản 4 không hỗ trợ loại lọc cứng này trong các tham số yêu cầu. Trong phiên bản 4, bạn có thể cung cấp thông tin địa chỉ dưới dạng một chuỗi không có cấu trúc duy nhất trong đường dẫn hoặc dưới dạng các tham số truy vấn có cấu trúc như address.addressLines, address.locality, address.administrativeArea, address.postalCode và address.regionCode. Các tham số có cấu trúc không hoạt động như bộ lọc cứng. Thay vào đó, tất cả các thành phần được cung cấp sẽ kết hợp với nhau để tạo thành địa chỉ hoàn chỉnh mà API sẽ cố gắng mã hoá địa lý. API này tìm kiếm kết quả khớp chính xác nhất cho toàn bộ địa chỉ được chỉ định trên tất cả các thành phần. Việc cung cấp các thành phần theo cách có cấu trúc có thể giúp API hiểu rõ hơn ý định, đặc biệt là khi thông tin địa chỉ được thu thập từ các trường biểu mẫu riêng biệt. Điều này có thể hỗ trợ API xử lý các lỗi chính tả nhỏ hoặc sự mơ hồ trong từng thành phần, vì loại thông tin trong mỗi trường đều rõ ràng.

Để đạt được hành vi tương tự như bộ lọc thành phần cố định của phiên bản 3, bạn phải triển khai tính năng lọc phía máy khách trên mảng results do API phiên bản 4 trả về dựa trên các đối tượng postalAddress và addressComponents trong phản hồi.

Bảng sau đây cho thấy mối tương quan phù hợp nhất giữa các bộ lọc components phiên bản 3 và các trường postalAddress phiên bản 4:

bộ lọc thành phần v3	trường phản hồi v4
`country`	`postalAddress.regionCode`
`postal_code`	`postalAddress.postalCode`
`administrative_area`	`postalAddress.administrativeArea` hoặc `addressComponents`

Ví dụ về việc lọc phía máy khách

Các ví dụ sau đây cho thấy cách lọc kết quả để đạt được hành vi tương tự như tính năng lọc thành phần của phiên bản 3 cho các trường được hỗ trợ: quốc gia, khu vực hành chính và mã bưu chính. Bạn không nên lọc trên các trường khác vì không có tiêu chí lọc đáng tin cậy.

Lọc theo quốc gia

Ghép address.regionCode trong yêu cầu của bạn với postalAddress.regionCode trong mỗi kết quả. Xin lưu ý rằng mặc dù API chấp nhận mã khu vực viết thường trong yêu cầu, nhưng API luôn trả về mã khu vực viết hoa trong phản hồi, vì vậy, bạn phải chuẩn hoá dữ liệu đầu vào thành chữ viết hoa trước khi so sánh.

Ví dụ về mã Python

def filter_by_country(results, region_code):
    return [
        res for res in results
        if res.get('postalAddress', {}).get('regionCode') == region_code.upper()
    ]

# Example usage:
# v4_response = ... # API call response
# filtered = filter_by_country(v4_response.get('results', []), 'US')

Ví dụ về mã Node.js

function filterByCountry(results, regionCode) {
    return results.filter(res => res.postalAddress?.regionCode === regionCode.toUpperCase());
}

// Example usage:
// const v4Response = ... # API call response
// const filtered = filterByCountry(v4Response.results, 'US');

Lọc theo tỉnh

Ghép address.administrativeArea trong yêu cầu của bạn với postalAddress.administrativeArea trong mỗi kết quả. Tương tự như mã quốc gia, bạn nên chuẩn hoá đầu vào thành chữ hoa trước khi so sánh. Điều này chỉ đáng tin cậy khi administrativeArea trong yêu cầu của bạn được cung cấp bằng một chữ viết tắt tiêu chuẩn gồm 2 chữ cái. postalAddress.administrativeArea trong phản hồi có thể không khớp trực tiếp với hậu tố mã ISO 3166-2 vì một số lý do. Thứ nhất, ở một số khu vực, phân vùng tương ứng với mã ISO 3166-2 không thuộc phần trình bày tiêu chuẩn của địa chỉ bưu chính. Ví dụ: ở Tây Ban Nha, cấp 1 của khu vực hành chính (ví dụ: "CN" cho Canarias) có thể xuất hiện trong addressComponents, nhưng postalAddress.administrativeArea có thể chứa khu vực cấp 2 (ví dụ: "Santa Cruz de Tenerife"). Thứ hai, ở một số khu vực, chữ viết tắt của tiểu khu không được sử dụng phổ biến và được biểu thị trong postalAddress.administrativeArea bằng một tên dài hơn (vì những lý do tương tự, addressComponents.shortText cho thành phần địa chỉ tương ứng với tiểu khu có thể không khớp với hậu tố mã ISO 3166-2 của tiểu khu). Ngoài ra, trong một số trường hợp, phân khu có thể được biểu thị ở thành phần địa chỉ cho administrative_area_level_n với n lớn hơn 1. Để có kết quả toàn diện nhất, bạn nên kiểm tra xem có giá trị nào khớp trong cả postalAddress.administrativeArea và mọi addressComponents có kiểu administrative_area_level_n (ví dụ: administrative_area_level_1) hay không.

Ví dụ về mã Python

def filter_by_admin_area(results, admin_area):
    target = admin_area.upper()
    filtered = []
    for res in results:
        # Check postalAddress
        pa_aa = res.get('postalAddress', {}).get('administrativeArea', '')
        if pa_aa == target:
            filtered.append(res)
            continue
        # Check all administrative area levels in addressComponents
        for comp in res.get('addressComponents', []):
            is_admin_level = any(t.startswith('administrative_area_level_')
                               for t in comp.get('types', []))
            if is_admin_level:
                short = comp.get('shortText', '')
                if short == target:
                    filtered.append(res)
                    break
    return filtered

# Example usage:
# filtered = filter_by_admin_area(v4_response.get('results', []), 'CA')

Ví dụ về mã Node.js

function filterByAdminArea(results, adminArea) {
    const target = adminArea.toUpperCase();
    return results.filter(res => {
        // Check postalAddress.administrativeArea
        if (res.postalAddress?.administrativeArea === target) {
            return true;
        }
        // Check addressComponents for any administrative area level
        return res.addressComponents?.some(c => {
            const isAdmin = c.types?.some(t => t.startsWith('administrative_area_level_'));
            return isAdmin && c.shortText === target;
        });
    });
}

// Example usage:
// const filtered = filterByAdminArea(v4Response.results, 'CA');

Lọc theo mã bưu chính

Ghép address.postalCode trong yêu cầu của bạn với postalAddress.postalCode trong mỗi kết quả. Bạn phải chuẩn hoá cả mã bưu chính đầu vào và kết quả trước khi so sánh. Logic chuẩn hoá phụ thuộc rất nhiều vào khu vực. Một phương pháp cơ bản là loại bỏ dấu cách và dấu gạch ngang, đồng thời chuyển đổi thành một trường hợp nhất quán.

Bạn có thể cần chuẩn hoá nâng cao hơn để xử lý tiền tố mã bưu chính (ví dụ: "L2" ở Vương quốc Anh) hoặc hậu tố (ví dụ: "+4" trong mã ZIP của Hoa Kỳ). Logic chuẩn hoá cụ thể bắt buộc sẽ khác nhau tuỳ thuộc vào quốc gia và định dạng của mã bưu chính có liên quan. Bạn có thể cần điều chỉnh các hàm chuẩn hoá được cung cấp hoặc triển khai logic phức tạp hơn cho những khu vực mà bạn đang nhắm đến.

Ví dụ được cung cấp xử lý mã bưu chính của Hoa Kỳ và cho phép so khớp trên cơ sở 5 chữ số ngay cả khi ZIP+4 được cung cấp hoặc trả về.

Ví dụ về mã Python (tập trung vào mã bưu chính của Hoa Kỳ)

import re

def normalize_postal_code_us(pc):
    # Basic normalization for US: uppercase, alphanumeric only
    if not pc:
        return ""
    normalized = re.sub(r'[^A-Z0-9]', '', pc.upper())
    # Return only the first 5 digits for US ZIP codes
    return normalized[:5]

def filter_by_postal_code_us(results, postal_code):
    normalized_input = normalize_postal_code_us(postal_code)
    if not normalized_input:
        return []
    filtered_results = []
    for res in results:
        pa_pc = res.get('postalAddress', {}).get('postalCode', '')
        if normalize_postal_code_us(pa_pc) == normalized_input:
            filtered_results.append(res)
    return filtered_results

# Example usage:
# Matches '94043', '94043-1351', '940431351'
# filtered = filter_by_postal_code_us(v4_response.get('results', []), '94043')
# filtered = filter_by_postal_code_us(v4_response.get('results', []), '94043-1234')

Ví dụ về mã Node.js (tập trung vào mã vùng của Hoa Kỳ)

function normalizePostalCodeUs(pc) {
    // Basic normalization for US: uppercase, alphanumeric only
    const normalized = (pc || '').toUpperCase().replace(/[^A-Z0-9]/g, '');
    // Return only the first 5 digits for US ZIP codes
    return normalized.substring(0, 5);
}

function filterByPostalCodeUs(results, postalCode) {
    const normalizedInput = normalizePostalCodeUs(postalCode);
    if (!normalizedInput) {
        return [];
    }
    return results.filter(res => {
        const paPc = res.postalAddress?.postalCode || '';
        return normalizePostalCodeUs(paPc) === normalizedInput;
    });
}

// Example usage:
// Matches '94043', '94043-1351', '940431351'
// const filtered = filterByPostalCodeUs(v4Response.results, '94043');
// const filtered = filterByPostalCodeUs(v4Response.results, '94043-1234');

Di chuyển từ tính năng Mã hoá địa lý ngược phiên bản 3

Nếu sử dụng v3 Reverse Geocoding (v3 Mã hoá địa lý ngược) để chuyển đổi toạ độ thành địa chỉ, bạn nên di chuyển sang phương thức v4 Reverse geocode a location (v4 Mã hoá địa lý ngược một vị trí) chấp nhận yêu cầu GET.

Yêu cầu thay đổi tham số

Tham số v3	Tham số phiên bản 4	Ghi chú
`language`	`languageCode`	Đã đổi tên.
`region`	`regionCode`	Đã đổi tên.
`result_type`	`types`	Đã đổi tên; sử dụng các tham số truy vấn lặp lại.
`location_type`	`granularity`	Đã đổi tên; sử dụng các tham số truy vấn lặp lại.
`extra_computations`	Đã xoá	Được thay thế bằng phương thức SearchDestinations.

Thay đổi về trường phản hồi

Trường v3	Trường v4	Ghi chú
`status`, `error_message`	Đã xoá	Phiên bản 4 sử dụng mã trạng thái HTTP và nội dung lỗi.
`results.address_components.long_name`/`results.address_components.short_name`	`results.addressComponents.longText`/`results.addressComponents.shortText`	Đã đổi tên.
`results.geometry.location_type`	`results.granularity`	Đã đổi tên.
`results.geometry.location`	`results.location`	Tên trường: `lat`/`lng` -> `latitude`/`longitude`.
`results.geometry.viewport`	`results.viewport`	Tên trường: `northeast`/`southwest` -> `high`/`low`.
Mới	`results.addressComponents.languageCode`	Ngôn ngữ của thành phần địa chỉ cụ thể.
Mới	`results.bounds`	Ranh giới rõ ràng bằng cách sử dụng `high`/`low`.
Mới	`results.place`	Tên tài nguyên của địa điểm.
Mới	`results.postalAddress`	Đối tượng `PostalAddress` có cấu trúc.

Di chuyển từ bộ mô tả Địa chỉ phiên bản 3

Nếu dùng address_descriptor để nhận thêm thông tin về một vị trí bằng Geocoding phiên bản 3, bạn phải di chuyển sang dùng trường landmarks của SearchDestinationsResponse.

Di chuyển từ tính năng mã hoá địa lý Địa điểm phiên bản 3

Nếu sử dụng place_id để lấy địa chỉ cho một Mã địa điểm cụ thể bằng Phương thức mã hoá địa lý v3, bạn phải di chuyển sang phương thức Mã hoá địa lý địa điểm v4. Phương thức này chấp nhận yêu cầu GET.

Yêu cầu thay đổi tham số

Tham số v3	Tham số phiên bản 4	Ghi chú
`place_id`	`place` trường trong proto yêu cầu	Giờ đây, mã địa điểm được cung cấp dưới dạng một tham số đường dẫn `places/{place}`, ví dụ: `https://geocode.googleapis.com/v4/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw`. Thao tác này tương ứng với trường địa điểm trong yêu cầu cơ bản.
`language`	`languageCode`	Đã đổi tên.
`region`	`regionCode`	Đã đổi tên.

Thay đổi về trường phản hồi

Trường v3	Trường v4	Ghi chú
`status`, `error_message`	Đã xoá	Phiên bản 4 sử dụng mã trạng thái HTTP và nội dung lỗi.
`results`	(root)	v4 trả về một đối tượng kết quả duy nhất, không phải mảng `results`.
`results.address_components.long_name`/`results.address_components.short_name`	`addressComponents.longText`/`addressComponents.shortText`	Đã đổi tên.
`results.geometry.location_type`	`granularity`	Đã đổi tên.
`results.geometry.location`	`location`	Tên trường: `lat`/`lng` -> `latitude`/`longitude`.
`results.geometry.viewport`	`viewport`	Tên trường: `northeast`/`southwest` -> `high`/`low`.
`results.postcode_localities`	`postalCodeLocalities`	Đã đổi tên. Hiện đã trả về cho một hoặc nhiều địa phương (cần có phiên bản 3 > 1).
Mới	`addressComponents.languageCode`	Ngôn ngữ của thành phần địa chỉ cụ thể.
Mới	`bounds`	Ranh giới rõ ràng bằng cách sử dụng `high`/`low`.
Mới	`place`	Tên tài nguyên của địa điểm.
Mới	`postalAddress`	Đối tượng `PostalAddress` có cấu trúc.

Di chuyển từ Dữ liệu siêu cục bộ về mã hoá địa lý sang Đích đến

Những tính năng sau đây trong Geocoding API phiên bản 3 sẽ được thay thế bằng phương thức SearchDestinations của Geocoding API phiên bản 4:

Số lần truy cập
Điểm điều hướng
Đường viền toà nhà
Vé các hoạt động trong khuôn viên

Nếu bạn đang sử dụng Geocoding API phiên bản 3 cho các tính năng nêu trên, hãy sử dụng tài liệu này để giúp bạn sử dụng phương thức SearchDestinations thay thế để có được các tính năng này. Tài liệu này giải thích vị trí của các tính năng này trong phản hồi SearchDestinations và sự khác biệt về cách các tính năng này được thể hiện trong phản hồi API giữa Geocoding API phiên bản 3 và phương thức SearchDestinations của Geocoding API phiên bản 4.

Số lần truy cập

Để lấy các lối vào liên kết với một destination, hãy dùng trường destination.entrances.

Xin lưu ý rằng định dạng của entrance hơi khác so với định dạng lối vào trong Geocoding API phiên bản 3. Mỗi lối vào trong destination.entrances đều có các trường sau:

displayName – đây là một trường mới không bắt buộc và sẽ có tên dễ đọc cho lối vào, ví dụ: "Cổng B".
location – đây là một vị trí thuộc loại LatLng, khác với định dạng được dùng trong Geocoding API phiên bản 3.
tags – giống với trường tags của các lối vào trong Geocoding API phiên bản 3.
place – tương tự như trường buildingPlaceId của các lối vào trong Geocoding API phiên bản 3. Tuy nhiên, Mã địa điểm trong trường này có thể là Mã địa điểm của một Địa điểm thuộc bất kỳ loại nào, không nhất thiết chỉ là một toà nhà.

Điểm điều hướng

Để lấy các điểm điều hướng được liên kết với một destination, hãy sử dụng trường destination.navigationPoints.

Xin lưu ý rằng định dạng của navigationPoint hơi khác so với định dạng điểm điều hướng trong Geocoding API phiên bản 3. Mỗi điểm điều hướng trong destination.navigationPoints đều có các trường sau:

displayName – đây là một trường mới không bắt buộc và sẽ có tên dễ đọc cho điểm điều hướng, ví dụ: "Đại lộ 5".
location – đây là một vị trí thuộc loại LatLng, khác với định dạng được dùng trong Geocoding API phiên bản 3.
travelModes – trường này tương tự như trường restrictedTravelModes của các điểm điều hướng trong Geocoding API phiên bản 3. Các giá trị enum có thể có là như nhau, điểm khác biệt duy nhất là trường này hiện đại diện cho các chế độ di chuyển được chấp nhận cho điểm điều hướng, thay vì các chế độ di chuyển bị hạn chế.
usage – đây là một trường mới chứa các trường hợp sử dụng được điểm điều hướng hỗ trợ.

Đường viền toà nhà

Để lấy đường viền của toà nhà được liên kết với destination, bạn nên sử dụng trường displayPolygon của các đối tượng placeView trong destination đại diện cho các toà nhà. Đối với mỗi placeView, bạn có thể kiểm tra xem đó có phải là một toà nhà có trường placeView.structureType hay không. Nếu loại cấu trúc là BUILDING, bạn có thể lấy đường viền từ trường placeView.displayPolygon. placeView cũng sẽ có các trường bổ sung cho toà nhà mà không có trong Geocoding API phiên bản 3.

destination có thể có một đối tượng placeView đại diện cho một toà nhà trong các trường sau:

destination.primary – đây là vị trí chính của điểm đến.
destination.containingPlaces – đây là một trường lặp lại có thể chứa những địa điểm lớn hơn "chứa" địa điểm chính. Ví dụ: nếu địa điểm chính là subpremise, thì containingPlaces thường sẽ chứa placeView đại diện cho toà nhà.
destination.subDestinations – đây là một trường lặp lại có thể chứa các điểm đến phụ của địa điểm chính. Ví dụ: từng căn hộ riêng lẻ trong một toà nhà. Trường này thường không có placeView đại diện cho một toà nhà.

Xin lưu ý rằng định dạng của placeView.displayPolygon khớp với định dạng đường viền toà nhà trong Geocoding API phiên bản 3, đây là định dạng GeoJSON, sử dụng định dạng RFC 7946.

Vé các hoạt động trong khuôn viên

Tương tự như việc tạo đường viền, để lấy các khu đất được liên kết với một destination, bạn nên dùng trường displayPolygon của các đối tượng placeView trong destination đại diện cho khu đất. Đối với mỗi placeView, bạn có thể kiểm tra xem đó có phải là căn cứ theo trường placeView.structureType hay không. Nếu loại cấu trúc là GROUNDS, bạn có thể lấy đường viền từ trường placeView.displayPolygon. placeView cũng sẽ có thêm các trường cho những địa điểm không có trong Geocoding API phiên bản 3.

destination có thể có một đối tượng placeView đại diện cho một cơ sở trong các trường sau:

destination.primary
destination.containingPlaces
destination.subDestinations

Xin lưu ý rằng định dạng của placeView.displayPolygon khớp với định dạng đường viền mặt đất trong Geocoding API phiên bản 3, đây là định dạng GeoJSON, sử dụng định dạng RFC 7946.

Độ chính xác của kết quả

Trong Geocoding API phiên bản 3, trường location_type trong hình học phản hồi cho biết độ chính xác của kết quả và một số ứng dụng sẽ xếp hạng hoặc lọc kết quả dựa trên các giá trị này (ROOFTOP, RANGE_INTERPOLATED, GEOMETRIC_CENTER và APPROXIMATE). Trong quá trình di chuyển Geocoding API phiên bản 4 tiêu chuẩn, trường này được đổi tên thành granularity.

Trong Destinations API (v4 SearchDestinations), không có trường location_type. Thay vào đó, thông tin không gian được xử lý theo cách khác:

Không cần lọc thủ công phía máy khách: Mặc dù tính năng Địa lý chuẩn cung cấp nhiều kết quả trên nhiều mức độ chi tiết, nhưng phương thức SearchDestinations giảm thiểu sự mơ hồ bằng cách phân giải thành một đích đến duy nhất, được tối ưu hoá bất cứ khi nào có thể. Nhờ đó, khách hàng không cần phải lọc theo loại vị trí để xác định kết quả phù hợp nhất.
Thông tin không gian được biểu thị bằng loại cấu trúc và đa giác hiển thị: Hình học không gian và cấu trúc được biểu thị bằng:
- displayPolygon (đối với hình học chính xác).
- Trường structureType trong đối tượng placeView.
Ánh xạ loại cấu trúc:
- structureType của POINT, BUILDING hoặc SECTION thường tương ứng với những gì được gọi là ROOFTOP trước đây.
- structureType của GROUNDS thường tương ứng với GEOMETRIC_CENTER.

Sử dụng mặt nạ trường để yêu cầu các tính năng này

Phương thức SearchDestinations yêu cầu một mặt nạ trường, như được giải thích trong phần Chọn các trường để trả về. Bạn có thể đặt mặt nạ trường thành * để trả về tất cả các trường hoặc bạn có thể đặt mặt nạ trường thành các trường cụ thể mà bạn muốn nhận. Ví dụ: yêu cầu API sau đây đặt mặt nạ trường để nhận tất cả các trường cần thiết để nhận lối vào, điểm điều hướng, đường viền toà nhà và mặt bằng của một địa điểm:

curl -X POST -d '{"place": "places/ChIJG3kh4hq6j4AR_XuFQnV0_t8"}' \
  -H "X-Goog-Api-Key: API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Goog-FieldMask: destinations.entrances,destinations.navigationPoints,destinations.primary,destinations.containingPlaces,destinations.subDestinations" \
  https://geocode.googleapis.com/v4/geocode/destinations

Lưu ý về bảo mật

Geocoding API phiên bản 4 được thiết kế dưới dạng API giữa các máy chủ. Người dùng JavaScript không có lộ trình di chuyển trực tiếp từ phiên bản 3 sang phiên bản 4. Việc gọi trực tiếp các phương thức v4 từ JavaScript phía máy khách (ví dụ: trong trình duyệt) bằng khoá API sẽ khiến khoá API của bạn có nguy cơ cao bị đánh cắp và sử dụng sai.

Mặc dù hữu ích, nhưng các hạn chế về giới thiệu HTTP không đủ để bảo vệ các điểm cuối dịch vụ web vì kẻ tấn công có thể dễ dàng bỏ qua các hạn chế này bằng cách giả mạo tiêu đề Referer trong các yêu cầu của chúng.

Phương pháp đề xuất

Cách nên dùng để sử dụng Geocoding API phiên bản 4 là từ máy chủ phụ trợ của riêng bạn. Ứng dụng khách của bạn sẽ gửi yêu cầu đến máy chủ trung gian này, sau đó máy chủ này sẽ gọi API Google một cách an toàn bằng khoá API được bảo vệ (ví dụ: khoá được lưu trữ trong một biến môi trường hoặc một trình quản lý bí mật). Điều này đảm bảo rằng khoá API của bạn không bao giờ bị lộ trong mã giao diện người dùng.

Các lựa chọn thay thế cho nhu cầu phía máy khách

Nếu bạn có nhu cầu phía máy khách cần mã hoá địa lý, hãy cân nhắc sử dụng một trong các giải pháp hiện có phía máy khách:

Dịch vụ mã hoá địa lý trong Maps JavaScript API: Dịch vụ mã hoá địa lý tiếp tục sử dụng phần phụ trợ v3 và được thiết kế để sử dụng trong môi trường trình duyệt.
Places UI Kit: Sử dụng Places UI Kit, bao gồm cả các phần tử Tự động hoàn thành địa điểm, cho các phần tử giao diện người dùng liên quan đến địa chỉ.

Di chuyển từ Geocoding v3 sang v4 Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Di chuyển từ tính năng Mã hoá địa lý xuôi phiên bản 3

Yêu cầu thay đổi tham số

Thay đổi về trường phản hồi

Tái tạo bộ lọc thành phần phiên bản 3

Ví dụ về việc lọc phía máy khách

Lọc theo quốc gia

Lọc theo tỉnh

Lọc theo mã bưu chính

Di chuyển từ tính năng Mã hoá địa lý ngược phiên bản 3

Yêu cầu thay đổi tham số

Thay đổi về trường phản hồi

Di chuyển từ bộ mô tả Địa chỉ phiên bản 3

Di chuyển từ tính năng mã hoá địa lý Địa điểm phiên bản 3

Yêu cầu thay đổi tham số

Thay đổi về trường phản hồi

Di chuyển từ Dữ liệu siêu cục bộ về mã hoá địa lý sang Đích đến

Số lần truy cập

Điểm điều hướng

Đường viền toà nhà

Vé các hoạt động trong khuôn viên

Độ chính xác của kết quả

Sử dụng mặt nạ trường để yêu cầu các tính năng này

Lưu ý về bảo mật

Phương pháp đề xuất

Các lựa chọn thay thế cho nhu cầu phía máy khách

Di chuyển từ Geocoding v3 sang v4