مهاجرت از Geocoding نسخه ۳ به نسخه ۴

API نسخه ۴ ژئوکدینگ چندین متد جدید معرفی می‌کند که جایگزین قابلیت‌های نسخه ۳ این API می‌شوند. این راهنما به شما نشان می‌دهد که چگونه برنامه خود را برای استفاده از متدهای جدید نسخه ۴ مهاجرت دهید.

شما می‌توانید از کلیدهای API موجود خود با روش‌های جدید نسخه ۴ استفاده کنید. با این حال، اگر درخواست افزایش سهمیه در نسخه ۳ API را داده‌اید، باید برای APIهای جدید نسخه ۴ نیز درخواست افزایش سهمیه دهید.

مهاجرت از نسخه ۳ به جلو

اگر از Geocoding نسخه ۳ برای geocode آدرس‌ها استفاده می‌کنید، باید به متد address نسخه ۴ Geocode مهاجرت کنید که درخواست GET را می‌پذیرد.

API نسخه ۴ نام‌ها، ساختار و پشتیبانی از چندین پارامتر را تغییر می‌دهد. اکیداً توصیه می‌کنیم از یک ماسک فیلد برای مشخص کردن فیلدهایی که می‌خواهید در پاسخ برگردانده شوند، استفاده کنید .

درخواست تغییر پارامترها

تغییرات فیلد پاسخ

فیلترهای کامپوننت v3 را بازتولید کنید

ژئوکدینگ رو به جلو در ژئوکدینگ نسخه ۳ شامل یک پارامتر components بود که فیلتر سخت نتایج را برای کامپوننت‌های خاص (مثلاً components=country:US ) فعال می‌کرد. ژئوکدینگ رو به جلو در نسخه ۴ از این نوع فیلتر سخت در پارامترهای درخواست پشتیبانی نمی‌کند. در نسخه ۴، می‌توانید اطلاعات آدرس را به صورت یک رشته بدون ساختار واحد در مسیر یا به صورت پارامترهای پرس‌وجوی ساختاریافته مانند address.addressLines ، address.locality ، address.administrativeArea ، address.postalCode و address.regionCode ارائه دهید. پارامترهای ساختاریافته به عنوان فیلترهای سخت عمل نمی‌کنند. در عوض، تمام کامپوننت‌های ارائه شده با هم ترکیب می‌شوند تا آدرس کاملی را که API سعی در ژئوکدینگ آن دارد، تشکیل دهند. API به دنبال بهترین تطابق برای کل آدرس مشخص شده در تمام کامپوننت‌ها می‌گردد. ارائه کامپوننت‌ها به صورت ساختاریافته می‌تواند به API کمک کند تا هدف را بهتر درک کند، به خصوص هنگامی که اطلاعات آدرس از فیلدهای فرم جداگانه جمع‌آوری می‌شود. این می‌تواند به API در مدیریت غلط‌های املایی یا ابهامات جزئی در هر کامپوننت کمک کند، زیرا نوع اطلاعات در هر فیلد مشخص است.

برای دستیابی به رفتاری مشابه فیلترهای کامپوننت سخت نسخه ۳، باید فیلترینگ سمت کلاینت را روی آرایه results برگردانده شده توسط API نسخه ۴ بر اساس اشیاء postalAddress و addressComponents در پاسخ پیاده‌سازی کنید.

جدول زیر بهترین تطابق بین فیلترهای components نسخه ۳ و فیلدهای postalAddress نسخه ۴ را نشان می‌دهد:

مثال‌های فیلترینگ سمت کلاینت

مثال‌های زیر نحوه فیلتر کردن نتایج را برای دستیابی به رفتاری مشابه فیلترینگ کامپوننت نسخه ۳ برای فیلدهای پشتیبانی‌شده نشان می‌دهند: کشور، منطقه اداری و کد پستی. فیلتر کردن روی فیلدهای دیگر توصیه نمی‌شود زیرا معیارهای فیلترینگ قابل اعتمادی وجود ندارد.

فیلتر بر اساس کشور

address.regionCode از درخواست خود را با postalAddress.regionCode در هر نتیجه مطابقت دهید. توجه داشته باشید که اگرچه API کدهای منطقه حروف کوچک را در درخواست می‌پذیرد، اما همیشه آنها را در پاسخ با حروف بزرگ برمی‌گرداند، بنابراین قبل از مقایسه باید ورودی خود را به حروف بزرگ نرمال‌سازی کنید.

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

فیلتر بر اساس منطقه اداری

address.administrativeArea از درخواست خود با postalAddress.administrativeArea در هر نتیجه مطابقت دهید. مشابه کدهای کشورها، قبل از مقایسه، باید ورودی خود را به حروف بزرگ تبدیل کنید. این کار فقط زمانی قابل اعتماد است که administrativeArea در درخواست شما با یک اختصار استاندارد دو حرفی ارائه شده باشد. postalAddress.administrativeArea در پاسخ ممکن است به چند دلیل مستقیماً با پسوندهای کد ISO 3166-2 مطابقت نداشته باشد. اولاً، در برخی مناطق، زیربخش مربوط به کد ISO 3166-2 بخشی از نمایش استاندارد آدرس‌های پستی نیست. به عنوان مثال، در اسپانیا، سطح ۱ منطقه اداری (مثلاً "CN" برای جزایر قناری) ممکن است در addressComponents وجود داشته باشد، اما postalAddress.administrativeArea ممکن است شامل منطقه سطح ۲ (مثلاً "سانتا کروس د تنریف") باشد. ثانیاً، در برخی مناطق، اختصار زیربخش معمولاً استفاده نمی‌شود و در postalAddress.administrativeArea با نامی طولانی‌تر نمایش داده می‌شود (به دلایل مشابه، addressComponents.shortText برای مؤلفه آدرس مربوط به زیربخش ممکن است با پسوند کد ISO 3166-2 زیربخش مطابقت نداشته باشد). علاوه بر این، زیربخش در برخی موارد ممکن است در مؤلفه آدرس برای administrative_area_level_n با n بزرگتر از 1 نمایش داده شود. برای جامع‌ترین نتایج، باید تطابق را هم در postalAddress.administrativeArea و هم در هر addressComponents با نوع administrative_area_level_n (مثلاً administrative_area_level_1 ) بررسی کنید.

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

فیلتر بر اساس کد پستی

address.postalCode از درخواست خود را با postalAddress.postalCode در هر نتیجه مطابقت دهید. قبل از مقایسه، باید کدهای پستی ورودی و نتیجه را نرمال‌سازی کنید. منطق نرمال‌سازی به منطقه بسیار وابسته است. یک رویکرد اساسی شامل حذف فاصله‌ها و خط فاصله‌ها و تبدیل به یک حالت سازگار است.

ممکن است برای مدیریت پیشوندهای کد پستی (مثلاً "L2" در بریتانیا) یا پسوندها (مثلاً "+4" در کدهای پستی ایالات متحده) به نرمال‌سازی پیشرفته‌تری نیاز باشد. منطق نرمال‌سازی خاص مورد نیاز بسته به کشور و قالب کدهای پستی مربوطه متفاوت خواهد بود. ممکن است لازم باشد توابع نرمال‌سازی ارائه شده را تطبیق دهید یا منطق پیچیده‌تری را برای مناطقی که هدف قرار می‌دهید پیاده‌سازی کنید.

مثال ارائه شده کدهای پستی ایالات متحده را مدیریت می‌کند و حتی اگر ZIP+4 ارائه یا برگردانده شود، امکان تطبیق در مبنای ۵ رقمی را فراهم می‌کند.

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

مهاجرت از ژئوکدینگ معکوس نسخه ۳

اگر از Geocoding معکوس نسخه ۳ برای تبدیل مختصات به آدرس استفاده می‌کنید، باید به یک متد مکان‌یابی به نام geocode معکوس نسخه ۴ مهاجرت کنید که درخواست GET را می‌پذیرد.

API نسخه ۴ نام‌ها، ساختار و پشتیبانی از چندین پارامتر را تغییر می‌دهد. اکیداً توصیه می‌کنیم از یک ماسک فیلد برای مشخص کردن فیلدهایی که می‌خواهید در پاسخ برگردانده شوند، استفاده کنید .

درخواست تغییر پارامترها

تغییرات فیلد پاسخ

مهاجرت از توصیف‌گرهای آدرس نسخه ۳

اگر address_descriptor برای دریافت اطلاعات بیشتر در مورد یک مکان با Geocoding نسخه ۳ استفاده می‌کنید، باید به استفاده از فیلد landmarks در SearchDestinationsResponse مهاجرت کنید.

مهاجرت از نسخه ۳ مکان‌یابی جغرافیایی

اگر place_id برای دریافت آدرس یک Place ID خاص با Geocoding نسخه ۳ استفاده می‌کنید، باید به متد Place Geocoding نسخه ۴ مهاجرت کنید که درخواست GET را می‌پذیرد.

API نسخه ۴ نام‌ها، ساختار و پشتیبانی از چندین پارامتر را تغییر می‌دهد. اکیداً توصیه می‌کنیم از یک ماسک فیلد برای مشخص کردن فیلدهایی که می‌خواهید در پاسخ برگردانده شوند، استفاده کنید .

درخواست تغییر پارامترها

تغییرات فیلد پاسخ

مهاجرت از داده‌های فرامحلی ژئوکدینگ به مقاصد

ویژگی‌های زیر در Geocoding API نسخه ۳ با متد SearchDestinations از Geocoding API نسخه ۴ جایگزین می‌شوند:

• ورودی‌ها
• نقاط ناوبری
• طرح کلی ساختمان
• زمین‌ها

اگر برای ویژگی‌های فوق از Geocoding API نسخه ۳ استفاده می‌کردید، از این سند برای کمک به شما در استفاده از متد SearchDestinations به جای آن برای دریافت این ویژگی‌ها استفاده کنید. این سند توضیح می‌دهد که در کجای پاسخ SearchDestinations می‌توان این ویژگی‌ها را پیدا کرد و تفاوت‌های نحوه نمایش این ویژگی‌ها در پاسخ‌های API بین Geocoding API نسخه ۳ و متد SearchDestinations از Geocoding API نسخه ۴ را شرح می‌دهد.

ورودی‌ها

برای دریافت ورودی‌های مرتبط با یک destination ، از فیلد destination.entrances استفاده کنید.

توجه داشته باشید که قالب یک entrance کمی با قالب ورودی در Geocoding API نسخه ۳ متفاوت است. هر ورودی در destination.entrances دارای فیلدهای زیر است:

• displayName - این یک فیلد اختیاری جدید است که یک نام خوانا برای ورودی خواهد داشت، برای مثال "دروازه B".
• location - این یک مکان از نوع LatLng است که با فرمت مورد استفاده در Geocoding API نسخه ۳ متفاوت است.
• tags - این همان فیلد tags برای ورودی‌ها از API Geocoding نسخه ۳ است.
• place - مشابه فیلد buildingPlaceId ورودی‌ها از Geocoding API نسخه ۳. با این حال، شناسه مکان در این فیلد می‌تواند برای هر نوع مکانی باشد، نه لزوماً فقط یک ساختمان.

نقاط ناوبری

برای دریافت نقاط ناوبری مرتبط با یک destination ، از فیلد destination.navigationPoints استفاده کنید.

توجه داشته باشید که قالب یک navigationPoint کمی با قالب نقطه ناوبری در Geocoding API نسخه ۳ متفاوت است. هر نقطه ناوبری در destination.navigationPoints دارای فیلدهای زیر است:

• displayName - این یک فیلد اختیاری جدید است که یک نام خوانا برای نقطه ناوبری خواهد داشت، برای مثال "خیابان پنجم".
• location - این یک مکان از نوع LatLng است که با فرمت مورد استفاده در Geocoding API نسخه ۳ متفاوت است.
• travelModes - این فیلد مشابه فیلد restrictedTravelModes مربوط به نقاط ناوبری از Geocoding API نسخه ۳ است. مقادیر شمارشی ممکن یکسان هستند، تنها تفاوت این است که این فیلد اکنون حالت‌های سفر قابل قبول برای نقطه ناوبری را نشان می‌دهد، نه حالت‌های سفر محدود شده.
• usage - این یک فیلد جدید است که شامل موارد استفاده پشتیبانی شده توسط نقطه ناوبری است. توجه داشته باشید که اکثر نقاط ناوبری کاربرد UNKNOWN دارند، اما این لزوماً به این معنی نیست که کاربرد نقطه ناوبری به هیچ وجه محدود شده است.

طرح کلی ساختمان

برای دریافت خطوط کلی ساختمان مرتبط با یک destination ، باید از فیلد displayPolygon از اشیاء placeView در destination که نشان دهنده ساختمان‌ها هستند استفاده کنید. برای هر placeView ، می‌توانید با فیلد placeView.structureType بررسی کنید که آیا یک ساختمان است یا خیر. اگر نوع ساختار BUILDING باشد، می‌توانید خطوط کلی را از فیلد placeView.displayPolygon دریافت کنید. placeView همچنین فیلدهای اضافی برای ساختمان خواهد داشت که در Geocoding API نسخه ۳ وجود نداشتند.

یک destination می‌تواند یک شیء placeView داشته باشد که نشان‌دهنده‌ی یک ساختمان در فیلدهای زیر است:

• destination.primary - این مکان اصلی برای مقصد است.
• destination.containingPlaces - این یک فیلد تکراری است که می‌تواند مکان‌های بزرگ‌تری را که «شامل» مکان اصلی هستند، در خود جای دهد. برای مثال، اگر مکان اصلی یک subpremise باشد، containingPlaces معمولاً placeView را که نمایانگر ساختمان است، در خود جای می‌دهد.
• destination.subDestinations - این یک فیلد تکراری است که می‌تواند زیرمقصدهای مکان اصلی را در خود نگه دارد. به عنوان مثال، واحدهای آپارتمانی مجزا از یک ساختمان. این فیلد معمولاً placeView که نشان‌دهنده یک ساختمان است را نخواهد داشت.

توجه داشته باشید که قالب placeView.displayPolygon با قالب طرح کلی ساختمان در Geocoding API نسخه ۳ ، که فرمت GeoJSON است و از فرمت RFC 7946 استفاده می‌کند، مطابقت دارد.

زمین‌ها

مشابه خطوط بیرونی ساختمان، برای دریافت زمین‌های مرتبط با یک destination ، باید از فیلد displayPolygon از اشیاء placeView در destination که نشان‌دهنده زمین‌ها هستند استفاده کنید. برای هر placeView ، می‌توانید با استفاده از فیلد placeView.structureType بررسی کنید که آیا زمین است یا خیر. اگر نوع ساختار GROUNDS باشد، می‌توانید خطوط بیرونی را از فیلد placeView.displayPolygon دریافت کنید. placeView همچنین فیلدهای اضافی برای زمین‌هایی که در Geocoding API نسخه ۳ وجود نداشتند، خواهد داشت.

یک destination می‌تواند یک شیء placeView داشته باشد که نشان‌دهنده‌ی یک زمینه (grounds) در فیلدهای زیر است:

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

توجه داشته باشید که قالب placeView.displayPolygon با قالب طرح کلی زمین در Geocoding API نسخه ۳ ، که همان قالب GeoJSON است و از قالب RFC 7946 استفاده می‌کند، مطابقت دارد.

دقت نتایج

در Geocoding API نسخه ۳، فیلد location_type در هندسه پاسخ، دقت نتایج را نشان می‌داد و برخی از کلاینت‌ها نتایج را بر اساس این مقادیر ( ROOFTOP ، RANGE_INTERPOLATED ، GEOMETRIC_CENTER و APPROXIMATE ) رتبه‌بندی یا فیلتر می‌کردند. در مهاجرت‌های استاندارد Geocoding API نسخه ۴، این فیلد به granularity تغییر نام داده شده است.

در Destinations API (نسخه ۴ SearchDestinations )، فیلد location_type وجود ندارد. در عوض، اطلاعات مکانی به طور متفاوتی مدیریت می‌شوند:

• نیازی به فیلترینگ دستی سمت کلاینت نیست : در حالی که Geocoding استاندارد نتایج متعددی را با جزئیات مختلف ارائه می‌دهد، متد 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، کلید API شما را در معرض خطر بالای سرقت و سوءاستفاده قرار می‌دهد.

محدودیت‌های ارجاع‌دهنده HTTP، اگرچه مفید هستند، اما برای محافظت از نقاط پایانی سرویس وب کافی نیستند، زیرا مهاجمانی که هدر Referer را در درخواست‌های خود جعل می‌کنند، می‌توانند به راحتی از آنها عبور کنند.

رویکرد پیشنهادی

روش توصیه‌شده برای استفاده از Geocoding API نسخه ۴، استفاده از سرور بک‌اند خودتان است. برنامه کلاینت شما باید درخواست‌هایی را به این سرور واسطه ارسال کند، که سپس با استفاده از یک کلید API محافظت‌شده (مثلاً کلیدی که در یک متغیر محیطی یا یک مدیر مخفی ذخیره شده است) به طور ایمن Google API را فراخوانی می‌کند. این تضمین می‌کند که کلید API شما هرگز در کد فرانت‌اند فاش نمی‌شود.

جایگزین‌هایی برای نیازهای سمت کلاینت

اگر نیازهای سمت کلاینت دارید که نیاز به کدگذاری جغرافیایی دارد، استفاده از یکی از راه‌حل‌های سمت کلاینت موجود را در نظر بگیرید:

• سرویس ژئوکدینگ در API جاوا اسکریپت نقشه‌ها: سرویس ژئوکدینگ همچنان از نسخه ۳ استفاده می‌کند و برای استفاده در محیط مرورگر طراحی شده است.
• کیت رابط کاربری Places: از کیت رابط کاربری Places ، شامل عناصر تکمیل خودکار Place ، برای عناصر رابط کاربری مرتبط با آدرس استفاده کنید.