Di chuyển từ Geocoding v3 sang v4

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. Hướng dẫn này trình bày cách di chuyển ứng dụng của bạn để sử dụng các phương thức v4 mới.

Bạn có thể sử dụng các 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, thì 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ý chuyển tiếp phiên bản 3

Nếu sử dụng tính năng Mã hoá địa lý phiên bản 3 để mã hoá địa lý cho địa chỉ, bạn nên chuyển sang phương thức Mã hoá địa lý cho địa chỉ phiên bản 4. 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ố

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

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ẽ được kết hợp để 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ả phù hợp 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ứng 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:

Ví dụ về bộ 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 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 theo 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

So khớp address.regionCode trong yêu cầu của bạn với postalAddress.regionCode trong từng kết quả. Xin lưu ý rằng mặc dù API chấp nhận mã vùng viết thường trong yêu cầu, nhưng API luôn trả về mã vùng 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.

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')

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 khu vực hành chính

So khớp address.administrativeArea trong yêu cầu của bạn với postalAddress.administrativeArea trong từng kết quả. Tương tự như mã quốc gia, bạn nên chuẩn hoá dữ liệu đầu vào thành chữ hoa trước khi so sánh. Thông tin này chỉ đáng tin cậy khi administrativeArea trong yêu cầu của bạn được cung cấp bằng chữ viết tắt gồm 2 chữ cái theo tiêu chuẩn. 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, khu vực hành chính cấp 1 (ví dụ: "CN" cho Canarias) có thể có 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, tên viết tắt của đơn vị hành chính không được sử dụng phổ biến và được thể hiện trong postalAddress.administrativeArea bằng tên dài hơn (vì lý do tương tự, addressComponents.shortText cho thành phần địa chỉ tương ứng với đơn vị hành chính có thể không khớp với hậu tố mã ISO 3166-2 của đơn vị hành chính). Ngoài ra, trong một số trường hợp, phân khu có thể được biểu thị tại 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ó kết quả trùng khớp trong cả postalAddress.administrativeArea và bất kỳ addressComponents nào có loại administrative_area_level_n (ví dụ: administrative_area_level_1) hay không.

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')

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

So khớ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à mã bưu chính 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à xoá dấu cách và dấu gạch nối, đồng thời chuyển đổi thành một kiểu viết hoa 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ã ZIP của Hoa Kỳ và cho phép so khớp trên cơ sở 5 chữ số ngay cả khi mã ZIP + 4 được cung cấp hoặc trả về.

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')

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.

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

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

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

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

Di chuyển từ tính năng mã hoá địa lý của Đị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 Mã hoá địa lý phiên bản 3, bạn phải di chuyển sang phương thức Mã hoá địa lý địa điểm phiên bản 4, 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 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ố

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

Di chuyển từ Dữ liệu mã hoá địa lý theo từng khu vực cụ thể sang Điểm đến

Các tính năng sau đây trong Geocoding API phiên bản 3 đang đượ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 tham khảo tài liệu này để biết cách sử dụng phương thức SearchDestinations để có được các tính năng này. Tài liệu này giải thích vị trí tìm thấy các tính năng này trong phản hồi của SearchDestinations, cũng như 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 của 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 sử 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 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à 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 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 có các trường sau:

• displayName – đây là một trường tuỳ chọn mới, sẽ có tên mà con người có thể đọc được cho điểm điều hướng, ví dụ: "Đại lộ số 5".
• location – đây là 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 toà nhà liên kết với một 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 toà nhà. Đối với mỗi placeView, bạn có thể kiểm tra xem đó có phải là một toà nhà hay không bằng trường placeView.structureType. Nếu loại cấu trúc là BUILDING, bạn có thể lấy dà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ẽ giữ placeView đại diện cho toà nhà.
• destination.subDestinations – đây là một trường lặp lại có thể lưu giữ 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 mặt đất đượ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 mặt đất. Đối với mỗi placeView, bạn có thể kiểm tra xem đó có phải là căn cứ hay không bằng trường placeView.structureType. Nếu loại cấu trúc là GROUNDS, bạn có thể lấy dàn ý từ trường placeView.displayPolygon. placeView cũng sẽ có thêm các trường cho những khu đất không có trong Geocoding API phiên bản 3.

destination có thể có đối tượng placeView đại diện cho một căn cứ 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 khuôn viên trong Geocoding API phiên bản 3, tức 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 (phiên bản 4 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 mã hoá địa lý tiêu 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 sẽ 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 và cấu trúc không gian đượ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ằm lấy lối vào, điểm điều hướng, đường viền toà nhà và khuôn viên của một điểm đến:

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ủ. Không có lộ trình di chuyển trực tiếp cho người dùng JavaScript 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 đích.

Các quy định hạn chế về liên kết giới thiệu HTTP, tuy hữu ích, nhưng không đủ để bảo vệ các điểm cuối của dịch vụ web vì kẻ tấn công có thể dễ dàng vượt qua bằng cách giả mạo tiêu đề Referer trong 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 nên gửi yêu cầu đến máy chủ trung gian này, sau đó máy chủ này sẽ gọi Google API một cách an toàn bằng khoá API được bảo vệ (ví dụ: khoá được lưu trữ trong biến môi trường hoặc 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 phương á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 dịch mã đị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ử Place Autocomplete, cho các phần tử giao diện người dùng liên quan đến địa chỉ.