ย้ายข้อมูลจาก Geocoding v3 ไปยัง v4

นักพัฒนาซอฟต์แวร์ในเขตเศรษฐกิจยุโรป (EEA)

Geocoding API v4 มีเมธอดใหม่หลายรายการที่แทนที่ฟังก์ชันการทำงานใน API เวอร์ชัน 3 คู่มือนี้จะแสดงวิธีย้ายข้อมูลแอปเพื่อใช้เมธอด v4 ใหม่

คุณใช้คีย์ API ที่มีอยู่กับเมธอด v4 ใหม่ได้ อย่างไรก็ตาม หากคุณได้ขอเพิ่มโควต้าใน API เวอร์ชัน 3 คุณต้องขอเพิ่มโควต้าใน API เวอร์ชัน 4 ใหม่

ย้ายข้อมูลจากการเข้ารหัสพิกัดภูมิศาสตร์แบบไปข้างหน้าเวอร์ชัน 3

หากใช้ v3 Geocoding เพื่อ แปลงรหัสพิกัดภูมิศาสตร์ของที่อยู่ คุณควรย้ายข้อมูลไปยังเมธอด Geocode an address ใน v4 ซึ่งยอมรับคำขอ GET

API เวอร์ชัน 4 เปลี่ยนชื่อ โครงสร้าง และการรองรับพารามิเตอร์หลายรายการ เราขอแนะนำเป็นอย่างยิ่งให้คุณใช้ Field Mask เพื่อระบุช่องที่ต้องการให้แสดงผลในการตอบกลับ

ขอเปลี่ยนแปลงพารามิเตอร์

พารามิเตอร์ v3 พารามิเตอร์ v4 หมายเหตุ
address, components address ตอนนี้ระบบจะส่งที่อยู่ที่ไม่มีโครงสร้าง (v3 address) ในเส้นทาง URL คุณส่งคอมโพเนนต์ของที่อยู่ที่จัดโครงสร้าง (v3 components) เป็นaddress.*พารามิเตอร์การค้นหาได้ ดูสร้างตัวกรองคอมโพเนนต์ v3 ขึ้นมาใหม่
bounds locationBias.rectangle เปลี่ยนชื่อแล้ว โครงสร้างเปลี่ยนเป็นออบเจ็กต์
language languageCode เปลี่ยนชื่อแล้ว เมื่อละเว้น v3 จะใช้ส่วนหัว Accept-Language หรือค่าเริ่มต้นเป็น en ส่วน v4 จะใช้ค่าเริ่มต้นเป็นภาษาท้องถิ่นและสคริปต์ของสถานที่ตั้ง
region regionCode เปลี่ยนชื่อแล้ว เมื่อละเว้น v3 จะมีค่าเริ่มต้นเป็น us ส่วน v4 จะไม่มีค่าเริ่มต้น
extra_computations นำออกแล้ว แทนที่ด้วยเมธอด SearchDestinations

การเปลี่ยนแปลงช่องคำตอบ

ฟิลด์ v3 ช่อง v4 หมายเหตุ
status, error_message นำออกแล้ว v4 ใช้รหัสสถานะ HTTP และเนื้อหาข้อผิดพลาด
results.address_components.long_name / results.address_components.short_name results.addressComponents.longText / results.addressComponents.shortText เปลี่ยนชื่อแล้ว
results.geometry.location_type results.granularity เปลี่ยนชื่อแล้ว
results.geometry.location results.location ชื่อฟิลด์: lat/lng -> latitude/longitude
results.geometry.viewport results.viewport ชื่อฟิลด์: northeast/southwest -> high/low
results.postcode_localities results.postalCodeLocalities เปลี่ยนชื่อแล้ว ตอนนี้แสดงผลสำหรับท้องถิ่นอย่างน้อย 1 แห่ง (v3 ต้องมีค่ามากกว่า 1)
results.partial_match นำออกแล้ว
ใหม่ results.addressComponents.languageCode ภาษาของคอมโพเนนต์ที่อยู่เฉพาะ
ใหม่ results.bounds ขอบเขตที่ชัดเจนโดยใช้ high/low
ใหม่ results.place ชื่อทรัพยากรของสถานที่
ใหม่ results.postalAddress ออบเจ็กต์ PostalAddress แบบมีโครงสร้าง

จำลองตัวกรองคอมโพเนนต์ v3

Forward Geocoding ใน Geocoding v3 มีพารามิเตอร์ components ที่เปิดใช้การกรองผลลัพธ์อย่างเข้มงวดสำหรับคอมโพเนนต์ที่เฉพาะเจาะจง (เช่น components=country:US) Forward Geocoding ใน v4 ไม่รองรับการกรองอย่างเข้มงวดประเภทนี้ในพารามิเตอร์คำขอ ใน v4 คุณสามารถระบุข้อมูลที่อยู่เป็นสตริงที่ไม่มีโครงสร้างรายการเดียวในเส้นทาง หรือเป็นพารามิเตอร์การค้นหาที่มีโครงสร้าง เช่น address.addressLines, address.locality, address.administrativeArea, address.postalCode และ address.regionCode พารามิเตอร์ที่มีโครงสร้างไม่ได้ทำหน้าที่เป็นตัวกรองแบบเข้มงวด แต่จะรวมคอมโพเนนต์ทั้งหมดที่ระบุไว้เพื่อสร้างที่อยู่แบบสมบูรณ์ที่ API จะพยายามเข้ารหัสพิกัดภูมิศาสตร์ API จะค้นหารายการที่ตรงกันมากที่สุดสำหรับที่อยู่ทั้งหมดที่ระบุในคอมโพเนนต์ทั้งหมด การระบุคอมโพเนนต์ในลักษณะที่มีโครงสร้างจะช่วยให้ API เข้าใจเจตนาได้ดีขึ้น โดยเฉพาะอย่างยิ่งเมื่อรวบรวมข้อมูลที่อยู่จากช่องแบบฟอร์มแยกกัน ซึ่งจะช่วยให้ API จัดการกับการพิมพ์ผิดเล็กน้อยหรือความกำกวมภายในแต่ละคอมโพเนนต์ได้ เนื่องจากประเภทข้อมูลในแต่ละฟิลด์มีความชัดเจน

หากต้องการให้ทำงานคล้ายกับตัวกรองคอมโพเนนต์แบบเข้มงวดของ v3 คุณต้องใช้การกรองฝั่งไคลเอ็นต์ในอาร์เรย์ results ที่ API v4 แสดงผลตามออบเจ็กต์ postalAddress และ addressComponents ในการตอบกลับ

ตารางต่อไปนี้แสดงการจับคู่ที่ดีที่สุดระหว่างตัวกรอง v3 components กับฟิลด์ v4 postalAddress

ตัวกรองคอมโพเนนต์ v3 ฟิลด์การตอบกลับ v4
country postalAddress.regionCode
postal_code postalAddress.postalCode
administrative_area postalAddress.administrativeArea หรือ addressComponents

ตัวอย่างการกรองฝั่งไคลเอ็นต์

ตัวอย่างต่อไปนี้แสดงวิธีกรองผลลัพธ์เพื่อให้ได้ลักษณะการทำงานที่คล้ายกับการกรองคอมโพเนนต์ v3 สำหรับช่องที่รองรับ ได้แก่ ประเทศ เขตบริหาร และรหัสไปรษณีย์ ไม่แนะนำให้กรองฟิลด์อื่นๆ เนื่องจากไม่มีเกณฑ์การกรองที่เชื่อถือได้

กรองตามประเทศ

จับคู่ address.regionCode จากคำขอของคุณกับ postalAddress.regionCode ในแต่ละผลลัพธ์ โปรดทราบว่าแม้ว่า API จะยอมรับรหัสภูมิภาคที่เป็นตัวพิมพ์เล็กในคำขอ แต่จะแสดงรหัสภูมิภาคเป็นตัวพิมพ์ใหญ่เสมอในการตอบกลับ ดังนั้นคุณต้องปรับอินพุตให้เป็นตัวพิมพ์ใหญ่ก่อนทำการเปรียบเทียบ

ตัวอย่างโค้ด 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')
ตัวอย่างโค้ด 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');
กรองตามเขตบริหาร

จับคู่ address.administrativeArea จากคำขอของคุณกับ postalAddress.administrativeArea ในผลการค้นหาแต่ละรายการ คุณควรปรับอินพุตให้เป็นตัวพิมพ์ใหญ่ก่อนการเปรียบเทียบ เช่นเดียวกับรหัสประเทศ วิธีนี้จะเชื่อถือได้ก็ต่อเมื่อ administrativeArea ในคำขอของคุณมีตัวย่อ 2 ตัวอักษรมาตรฐาน postalAddress.administrativeArea ในการตอบกลับอาจไม่ตรงกับคำต่อท้ายของรหัส ISO 3166-2 โดยตรงเนื่องจากสาเหตุหลายประการ ประการแรก ในบางพื้นที่ เขตปกครองย่อยที่สอดคล้องกับรหัส ISO 3166-2 ไม่ได้เป็นส่วนหนึ่งของการแสดงที่อยู่ทางไปรษณีย์ตามมาตรฐาน เช่น ในสเปน เขตการปกครองระดับ 1 (เช่น "CN" สำหรับกานาเรียส) อาจอยู่ใน addressComponents แต่ postalAddress.administrativeArea อาจมีพื้นที่ระดับ 2 (เช่น "ซานตาครูซเดเตเรนิเฟ") ประการที่ 2 ในบางพื้นที่ ตัวย่อของเขตย่อยไม่เป็นที่ใช้กันโดยทั่วไปและจะแสดงใน postalAddress.administrativeArea ด้วยชื่อที่ยาวกว่า (ด้วยเหตุผลที่คล้ายกัน addressComponents.shortText สำหรับคอมโพเนนต์ที่อยู่ซึ่งสอดคล้องกับเขตย่อยอาจไม่ตรงกับส่วนต่อท้ายรหัส ISO 3166-2 ของเขตย่อย) นอกจากนี้ ในบางกรณีอาจมีการแสดงเขตย่อยที่คอมโพเนนต์ที่อยู่สำหรับ administrative_area_level_n โดยที่ n มากกว่า 1 เพื่อให้ได้ผลลัพธ์ที่ครอบคลุมมากที่สุด คุณควรตรวจสอบการจับคู่ในทั้ง postalAddress.administrativeArea และ addressComponents ที่มีประเภท administrative_area_level_n (เช่น administrative_area_level_1)

ตัวอย่างโค้ด 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')
ตัวอย่างโค้ด 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');
กรองตามรหัสไปรษณีย์

จับคู่ address.postalCode จากคำขอของคุณกับ postalAddress.postalCode ในผลการค้นหาแต่ละรายการ คุณต้องปรับรหัสไปรษณีย์ทั้งอินพุตและผลลัพธ์ให้เป็นมาตรฐานก่อนเปรียบเทียบ ตรรกะการปรับให้เป็นมาตรฐานขึ้นอยู่กับภูมิภาคเป็นอย่างมาก แนวทางพื้นฐานคือการนำช่องว่างและขีดกลางออก แล้วแปลงเป็นตัวพิมพ์เล็กหรือตัวพิมพ์ใหญ่ทั้งหมด

อาจต้องมีการจัดรูปแบบขั้นสูงเพิ่มเติมเพื่อจัดการคำนำหน้า (เช่น "L2" ในสหราชอาณาจักร) หรือคำต่อท้าย (เช่น "+4" ในรหัสไปรษณีย์ของสหรัฐอเมริกา) ตรรกะการปรับมาตรฐานที่เฉพาะเจาะจงที่จำเป็นจะแตกต่างกันไปตามประเทศและรูปแบบของรหัสไปรษณีย์ที่เกี่ยวข้อง คุณอาจต้องปรับฟังก์ชันการปรับให้เป็นมาตรฐานที่ระบุไว้ หรือใช้ตรรกะที่ซับซ้อนมากขึ้นสำหรับภูมิภาคที่คุณกำหนดเป้าหมาย

ตัวอย่างที่ให้ไว้จะจัดการรหัสไปรษณีย์ของสหรัฐอเมริกาและอนุญาตให้จับคู่กับฐาน 5 หลักได้แม้ว่าจะมีการระบุหรือแสดงผล ZIP+4 ก็ตาม

ตัวอย่างโค้ด Python (เน้นรหัสไปรษณีย์ของสหรัฐอเมริกา) 
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')
ตัวอย่างโค้ด Node.js (เน้นรหัสไปรษณีย์ของสหรัฐอเมริกา) 
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');

ย้ายข้อมูลจากการเข้ารหัสพิกัดภูมิศาสตร์แบบย้อนกลับเวอร์ชัน 3

หากใช้ v3 Reverse Geocoding เพื่อเปลี่ยนพิกัดเป็นที่อยู่ คุณควรย้ายข้อมูลไปยังเมธอด Reverse geocode a location เวอร์ชัน 4 ซึ่งยอมรับคำขอ GET

v4 API จะเปลี่ยนชื่อ โครงสร้าง และการรองรับพารามิเตอร์หลายรายการ เราขอแนะนำเป็นอย่างยิ่งให้คุณใช้ Field Mask เพื่อระบุช่องที่ต้องการให้แสดงผลในการตอบกลับ

ขอเปลี่ยนแปลงพารามิเตอร์

พารามิเตอร์ v3 พารามิเตอร์ v4 หมายเหตุ
language languageCode เปลี่ยนชื่อแล้ว เมื่อละเว้น v3 จะใช้ส่วนหัว Accept-Language หรือค่าเริ่มต้นเป็น en ส่วน v4 จะใช้ค่าเริ่มต้นเป็นภาษาท้องถิ่นและสคริปต์ของสถานที่ตั้ง
region regionCode เปลี่ยนชื่อแล้ว เมื่อละเว้น v3 จะมีค่าเริ่มต้นเป็น us ส่วน v4 จะไม่มีค่าเริ่มต้น
result_type types เปลี่ยนชื่อแล้ว โดยใช้พารามิเตอร์การค้นหาซ้ำ
location_type granularity เปลี่ยนชื่อแล้ว ใช้พารามิเตอร์การค้นหาที่ซ้ำกัน
extra_computations นำออกแล้ว แทนที่ด้วยเมธอด SearchDestinations

การเปลี่ยนแปลงช่องคำตอบ

ฟิลด์ v3 ช่อง v4 หมายเหตุ
status, error_message นำออกแล้ว v4 ใช้รหัสสถานะ HTTP และเนื้อหาข้อผิดพลาด
results.address_components.long_name / results.address_components.short_name results.addressComponents.longText / results.addressComponents.shortText เปลี่ยนชื่อแล้ว
results.geometry.location_type results.granularity เปลี่ยนชื่อแล้ว
results.geometry.location results.location ชื่อฟิลด์: lat/lng -> latitude/longitude
results.geometry.viewport results.viewport ชื่อฟิลด์: northeast/southwest -> high/low
ใหม่ results.addressComponents.languageCode ภาษาของคอมโพเนนต์ที่อยู่เฉพาะ
ใหม่ results.bounds ขอบเขตที่ชัดเจนโดยใช้ high/low
ใหม่ results.place ชื่อทรัพยากรของสถานที่
ใหม่ results.postalAddress ออบเจ็กต์ PostalAddress แบบมีโครงสร้าง

ย้ายข้อมูลจากข้อบ่งชี้ที่อยู่ v3

หากใช้ address_descriptor เพื่อรับข้อมูลเพิ่มเติมเกี่ยวกับสถานที่ตั้งด้วย Geocoding v3 คุณต้องย้ายไปใช้ช่อง landmarks ของ SearchDestinationsResponse

ย้ายข้อมูลจากการเข้ารหัสที่อยู่เป็นพิกัดภูมิศาสตร์ของสถานที่เวอร์ชัน 3

หากใช้ place_id เพื่อรับที่อยู่สำหรับรหัสสถานที่ที่เฉพาะเจาะจงด้วย Geocoding v3 คุณต้องย้ายข้อมูลไปยังเมธอด Place Geocoding v4 ซึ่ง ยอมรับคำขอ GET

v4 API จะเปลี่ยนชื่อ โครงสร้าง และการรองรับพารามิเตอร์หลายรายการ เราขอแนะนำเป็นอย่างยิ่งให้คุณใช้ Field Mask เพื่อระบุช่องที่ต้องการให้แสดงผลในการตอบกลับ

ขอเปลี่ยนแปลงพารามิเตอร์

พารามิเตอร์ v3 พารามิเตอร์ v4 หมายเหตุ
place_id ฟิลด์ place ในโปรโตคำขอ ตอนนี้ระบบจะระบุรหัสสถานที่ตั้งเป็นพารามิเตอร์เส้นทาง places/{place} เช่น https://geocode.googleapis.com/v4/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw ซึ่งจะแมปกับฟิลด์สถานที่ในคำขอที่เกี่ยวข้อง
language languageCode เปลี่ยนชื่อแล้ว หากไม่ระบุ v3 จะใช้ส่วนหัว Accept-Language หรือใช้ค่าเริ่มต้นเป็น en ในขณะที่ v4 จะใช้ภาษาและสคริปต์ของสถานที่ตั้งเป็นค่าเริ่มต้น
region regionCode เปลี่ยนชื่อแล้ว หากละเว้น v3 จะมีค่าเริ่มต้นเป็น us แต่ v4 จะไม่มีค่าเริ่มต้น

การเปลี่ยนแปลงช่องคำตอบ

ฟิลด์ v3 ช่อง v4 หมายเหตุ
status, error_message นำออกแล้ว v4 ใช้รหัสสถานะ HTTP และเนื้อหาข้อผิดพลาด
results (root) v4 จะแสดงผลออบเจ็กต์ผลลัพธ์รายการเดียว ไม่ใช่อาร์เรย์ results
results.address_components.long_name / results.address_components.short_name addressComponents.longText / addressComponents.shortText เปลี่ยนชื่อแล้ว
results.geometry.location_type granularity เปลี่ยนชื่อแล้ว
results.geometry.location location ชื่อฟิลด์: lat/lng -> latitude/longitude
results.geometry.viewport viewport ชื่อฟิลด์: northeast/southwest -> high/low
results.postcode_localities postalCodeLocalities เปลี่ยนชื่อแล้ว ตอนนี้แสดงผลสำหรับเขตพื้นที่อย่างน้อย 1 แห่ง (ต้องใช้ v3 >1)
ใหม่ addressComponents.languageCode ภาษาของคอมโพเนนต์ที่อยู่เฉพาะ
ใหม่ bounds ขอบเขตที่ชัดเจนโดยใช้ high/low
ใหม่ place ชื่อทรัพยากรของสถานที่
ใหม่ postalAddress ออบเจ็กต์ PostalAddress ที่มีโครงสร้าง

ย้ายข้อมูลจากข้อมูลเจาะจงเฉพาะพื้นที่ของการเข้ารหัสพิกัดภูมิศาสตร์ไปยังปลายทาง

ฟีเจอร์ต่อไปนี้ใน Geocoding API v3 จะถูกแทนที่ด้วยเมธอด SearchDestinations ของ Geocoding API v4

  • การเข้าชม
  • จุดนำทาง
  • โครงร่างอาคาร
  • ค่าเข้า

หากคุณใช้ Geocoding API v3 สำหรับฟีเจอร์ข้างต้น ให้ใช้เอกสารนี้เพื่อช่วยให้คุณใช้เมธอด SearchDestinations แทนเพื่อรับฟีเจอร์เหล่านี้ เอกสารนี้อธิบายตำแหน่งที่จะค้นหาฟีเจอร์เหล่านี้ในการตอบกลับของ SearchDestinations และความแตกต่างในการแสดงฟีเจอร์เหล่านี้ในการตอบกลับจาก API ระหว่าง Geocoding API v3 กับเมธอด SearchDestinations ของ Geocoding API v4

การเข้าชม

หากต้องการดูทางเข้าที่เชื่อมโยงกับ destination ให้ใช้ช่อง destination.entrances

โปรดทราบว่ารูปแบบของ entrance แตกต่างจากรูปแบบทางเข้าใน Geocoding API v3 เล็กน้อย ทางเข้าแต่ละทางใน destination.entrances มีฟิลด์ต่อไปนี้

  • displayName - นี่คือฟิลด์ใหม่ที่ไม่บังคับซึ่งจะมีชื่อที่มนุษย์อ่านได้ สำหรับทางเข้า เช่น "ประตู B"
  • location - นี่คือตำแหน่งของประเภท LatLng ซึ่งแตกต่างจากรูปแบบที่ใช้ใน Geocoding API v3
  • tags - เหมือนกับฟิลด์ tags ของทางเข้าจาก Geocoding API v3
  • place - เทียบเท่ากับฟิลด์ buildingPlaceId ของทางเข้าจาก Geocoding API v3 อย่างไรก็ตาม รหัสสถานที่ในช่องนี้อาจเป็นของสถานที่ประเภทใดก็ได้ ไม่จำเป็นต้องเป็นอาคารเท่านั้น

หากต้องการรับจุดนำทางที่เชื่อมโยงกับ destination ให้ใช้ฟิลด์ destination.navigationPoints

โปรดทราบว่ารูปแบบของ navigationPoint แตกต่างจากรูปแบบจุดนำทางใน Geocoding API v3 เล็กน้อย จุดนำทางแต่ละจุดใน destination.navigationPoints มีฟิลด์ต่อไปนี้

  • displayName - นี่คือฟิลด์ใหม่ที่ไม่บังคับซึ่งจะมีชื่อที่มนุษย์อ่านได้ สำหรับจุดนำทาง เช่น "5th Ave"
  • location - นี่คือสถานที่ตั้งประเภท LatLng ซึ่งแตกต่างจากรูปแบบที่ใช้ใน Geocoding API v3
  • travelModes - ซึ่งคล้ายกับฟิลด์ restrictedTravelModes ของ จุดนำทางจาก Geocoding API v3 ค่า enum ที่เป็นไปได้จะเหมือนกัน โดยความแตกต่างเพียงอย่างเดียวคือตอนนี้ช่องนี้แสดงรูปแบบการเดินทางที่ยอมรับได้สำหรับจุดนำทาง แทนที่จะเป็นรูปแบบการเดินทางที่จำกัด
  • usage - นี่คือฟิลด์ใหม่ที่มีกรณีการใช้งานที่จุดนำทางรองรับ

โครงร่างอาคาร

หากต้องการรับโครงร่างอาคารที่เชื่อมโยงกับ destination คุณควรใช้ฟิลด์ displayPolygon ของออบเจ็กต์ placeView ใน destination ที่แสดงถึงอาคาร สำหรับ placeView แต่ละรายการ คุณสามารถตรวจสอบได้ว่าเป็นอาคารที่มีช่อง placeView.structureType หรือไม่ หากประเภทโครงสร้างคือ BUILDING คุณจะดูโครงร่างได้จากช่อง placeView.displayPolygon placeView จะมีฟิลด์เพิ่มเติมสำหรับอาคารที่ไม่ได้อยู่ใน Geocoding API v3 ด้วย

destination สามารถมีออบเจ็กต์ placeView ที่แสดงถึงอาคารในช่องต่อไปนี้

  • destination.primary - นี่คือสถานที่หลักของจุดหมายปลายทาง
  • destination.containingPlaces - นี่คือฟิลด์ที่ซ้ำได้ซึ่งเก็บสถานที่ขนาดใหญ่กว่าที่ "มี" สถานที่หลัก เช่น หากสถานที่หลักคือ subpremise โดยปกติแล้ว containingPlaces จะมี placeView ซึ่งแสดงถึงอาคาร
  • destination.subDestinations - นี่คือฟิลด์ที่ซ้ำได้ซึ่งเก็บปลายทางย่อยของสถานที่หลักได้ เช่น ห้องชุดแต่ละห้องในอาคาร โดยปกติแล้วช่องนี้จะไม่มี placeView ที่แสดงถึงอาคาร

โปรดทราบว่ารูปแบบของ placeView.displayPolygon ตรงกับรูปแบบโครงร่างอาคารใน Geocoding API v3 ซึ่งเป็นรูปแบบ GeoJSON โดยใช้รูปแบบ RFC 7946

ค่าเข้า

เช่นเดียวกับการสร้างขอบเขตอาคาร หากต้องการรับพื้นที่ที่เชื่อมโยงกับ destination คุณควรใช้ฟิลด์ displayPolygon ของออบเจ็กต์ placeView ใน destination ที่แสดงถึงพื้นที่ สำหรับแต่ละ placeView คุณ สามารถตรวจสอบว่ามีเหตุผลด้วยฟิลด์ placeView.structureType หรือไม่ หาก ประเภทโครงสร้างเป็น GROUNDS คุณจะดูโครงร่างได้จากฟิลด์ placeView.displayPolygon placeView จะมีฟิลด์เพิ่มเติมสำหรับเหตุผลที่ไม่ได้อยู่ใน Geocoding API v3 ด้วย

destination สามารถมีออบเจ็กต์ placeView ที่แสดงถึงเหตุผลในฟิลด์ต่อไปนี้

  • destination.primary
  • destination.containingPlaces
  • destination.subDestinations

โปรดทราบว่ารูปแบบของ placeView.displayPolygon ตรงกับรูปแบบขอบเขตของพื้นที่ ใน Geocoding API v3 ซึ่งเป็นรูปแบบ GeoJSON โดยใช้รูปแบบ RFC 7946

ความแม่นยำของผลลัพธ์

ใน Geocoding API v3 ฟิลด์ location_type ในเรขาคณิตของการตอบกลับ ระบุความแม่นยำของผลลัพธ์ และไคลเอ็นต์บางรายจะจัดอันดับหรือกรอง ผลลัพธ์ตามค่าเหล่านี้ (ROOFTOP, RANGE_INTERPOLATED, GEOMETRIC_CENTER และ APPROXIMATE) ในการย้ายข้อมูล Geocoding API v4 มาตรฐาน ฟิลด์นี้จะเปลี่ยนชื่อเป็น granularity

ใน Destinations API (v4 SearchDestinations) ไม่มีฟิลด์ location_type แต่จะจัดการข้อมูลเชิงพื้นที่แตกต่างออกไป ดังนี้

  • ไม่จำเป็นต้องกรองฝั่งไคลเอ็นต์ด้วยตนเอง: แม้ว่าการเข้ารหัสพิกัดภูมิศาสตร์มาตรฐานจะให้ผลลัพธ์หลายรายการในระดับความละเอียดที่แตกต่างกัน แต่วิธี SearchDestinations จะช่วยลดความกำกวมด้วยการแปลงเป็นปลายทางเดียวที่เพิ่มประสิทธิภาพเมื่อเป็นไปได้ ซึ่งช่วยให้ลูกค้าไม่ต้องกรองตามประเภทสถานที่ตั้งเพื่อพิจารณาว่าผลลัพธ์ใดดีที่สุด
  • ข้อมูลเชิงพื้นที่ที่แสดงตามประเภทโครงสร้างและรูปหลายเหลี่ยมที่แสดง: เรขาคณิตและโครงสร้างเชิงพื้นที่จะระบุด้วยสิ่งต่อไปนี้
    • displayPolygon (สำหรับเรขาคณิตที่แน่นอน)
    • ฟิลด์ structureType ภายในออบเจ็กต์ placeView
  • การแมปประเภทโครงสร้าง
    • structureType ของ POINT, BUILDING หรือ SECTION โดยทั่วไป จะสอดคล้องกับสิ่งที่ก่อนหน้านี้เรียกว่า ROOFTOP
    • structureType ของ GROUNDS มักจะสอดคล้องกับ GEOMETRIC_CENTER

ใช้มาสก์ฟิลด์เพื่อขอฟีเจอร์เหล่านี้

เมธอด SearchDestinations ต้องใช้มาสก์ฟิลด์ตามที่อธิบายไว้ในเลือกฟิลด์ที่จะแสดงผล คุณสามารถตั้งค่ามาสก์ฟิลด์เป็น * เพื่อแสดงฟิลด์ทั้งหมด หรือจะตั้งค่าเป็นฟิลด์ที่ต้องการรับก็ได้ ตัวอย่างเช่น คำขอ API ต่อไปนี้จะตั้งค่ามาสก์ฟิลด์ เพื่อรับฟิลด์ทั้งหมดที่จำเป็นในการรับทางเข้า จุดนำทาง โครงร่างอาคาร และพื้นที่ของจุดหมาย

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

ข้อควรพิจารณาด้านความปลอดภัย

Geocoding API v4 ออกแบบมาเป็น API แบบเซิร์ฟเวอร์ต่อเซิร์ฟเวอร์ ไม่มีเส้นทางการย้ายข้อมูลโดยตรงสำหรับผู้ใช้ JavaScript จาก v3 ไปยัง v4 การเรียกใช้เมธอด v4 โดยตรงจาก JavaScript ฝั่งไคลเอ็นต์ (เช่น ในเบราว์เซอร์) โดยใช้คีย์ API จะทำให้คีย์ API มีความเสี่ยงสูงต่อการถูกขโมยและการใช้ในทางที่ผิด

ข้อจำกัดเกี่ยวกับ HTTP Referrer แม้ว่าจะมีประโยชน์ แต่ก็ไม่เพียงพอที่จะปกป้องปลายทางของเว็บเซอร์วิส เนื่องจากผู้โจมตีที่ปลอมแปลงส่วนหัว Referer ในคำขอสามารถข้ามข้อจำกัดนี้ได้อย่างง่ายดาย

วิธีที่แนะนำในการใช้ Geocoding API v4 คือจากเซิร์ฟเวอร์แบ็กเอนด์ของคุณเอง แอปพลิเคชันไคลเอ็นต์ควรส่งคำขอไปยังเซิร์ฟเวอร์สื่อกลางนี้ ซึ่งจะเรียกใช้ Google API อย่างปลอดภัยโดยใช้คีย์ API ที่ได้รับการปกป้อง (เช่น คีย์ที่จัดเก็บไว้ในตัวแปรสภาพแวดล้อมหรือ Secret Manager) วิธีนี้ช่วยให้มั่นใจได้ว่าคีย์ API จะไม่แสดงในโค้ดฟรอนท์เอนด์

ทางเลือกสำหรับความต้องการฝั่งไคลเอ็นต์

หากคุณมีความต้องการฝั่งไคลเอ็นต์ที่ต้องใช้ Geocoding โปรดพิจารณาใช้โซลูชันฝั่งไคลเอ็นต์ที่มีอยู่ต่อไปนี้