نقل البيانات من الإصدار 3 إلى الإصدار 4 من Geocoding API

المطوّرون في المنطقة الاقتصادية الأوروبية

يقدّم الإصدار 4 من Geocoding API عدة طرق جديدة تحلّ محلّ الوظائف في الإصدار 3 من واجهة برمجة التطبيقات. يوضّح لك هذا الدليل كيفية نقل تطبيقك لاستخدام طرق الإصدار 4 الجديدة.

يمكنك استخدام مفاتيح واجهة برمجة التطبيقات الحالية مع طرق الإصدار 4 الجديدة. ومع ذلك، إذا طلبت زيادة الحصة في الإصدار 3 من واجهة برمجة التطبيقات، يجب طلب زيادة في الإصدار 4 الجديد من واجهات برمجة التطبيقات.

النقل من الإصدار 3 من خدمة الترميز الجغرافي

إذا كنت تستخدم الإصدار الثالث من الترميز الجغرافي لترميز العناوين جغرافيًا، عليك نقل بياناتك إلى طريقة الترميز الجغرافي لعنوان في الإصدار الرابع، والتي تقبل طلب استرداد بيانات باستخدام GET.

تغيّر واجهة برمجة التطبيقات الإصدار 4 الأسماء والبنية وتتيح استخدام عدة مَعلمات. ننصحك بشدة باستخدام قناع حقل لتحديد الحقول التي تريد عرضها في الرد.

تغييرات مَعلمات الطلب

مَعلمة v3 مَعلمة الإصدار 4 ملاحظات
‫address، components address يتم الآن تمرير العنوان غير المنظَّم (v3 address) في مسار عنوان URL. يمكن تمرير مكوّنات العنوان المنظَّم (الإصدار 3 components) كمَعلمات طلب بحث address.*. يُرجى الاطّلاع على إعادة إنشاء فلاتر مكوّنات الإصدار 3.
bounds locationBias.rectangle تمت إعادة تسميته، وتم تغيير البنية إلى عنصر.
language languageCode تمت إعادة التسمية. في حال عدم إدخال قيمة، يستخدم الإصدار 3 العنوان Accept-Language أو القيمة التلقائية en، بينما يستخدم الإصدار 4 اللغة والنص البرمجي المحليين للموقع الجغرافي كقيم تلقائية.
region regionCode تمت إعادة التسمية. عند حذفها، تكون القيمة التلقائية للإصدار 3 هي us، بينما لا يتضمّن الإصدار 4 قيمة تلقائية.
extra_computations مُزال تم استبداله بالطريقة SearchDestinations.

تغييرات حقل الردّ

الحقل v3 حقل v4 ملاحظات
‫status، error_message مُزال يستخدم الإصدار 4 رموز حالة 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 تمت إعادة التسمية. تم الآن عرضها لبلدة واحدة أو أكثر (الإصدار 3 مطلوب > 1).
results.partial_match مُزال
الأرباح الجديدة results.addressComponents.languageCode لغة مكوّن العنوان المحدّد
الأرباح الجديدة results.bounds حدود صريحة باستخدام high/low
الأرباح الجديدة results.place اسم المورد للمكان
الأرباح الجديدة results.postalAddress عنصر PostalAddress منظَّم

إعادة إنتاج فلاتر المكوّن v3

تضمّن الترميز الجغرافي الأمامي في الإصدار 3 من Geocoding مَعلمة components التي أتاحت الفلترة الصارمة للنتائج لمكوّنات معيّنة (مثل components=country:US). لا يتيح الترميز الجغرافي الأمامي في الإصدار 4 هذا النوع من الفلترة الصارمة في مَعلمات الطلب. في الإصدار 4، يمكنك تقديم معلومات العنوان إما كسلسلة واحدة غير منظَّمة في المسار أو كمَعلمات طلب بحث منظَّمة، مثل address.addressLines وaddress.locality وaddress.administrativeArea وaddress.postalCode وaddress.regionCode. لا تعمل المَعلمات المنظَّمة كفلاتر صارمة. بدلاً من ذلك، يتم دمج جميع المكوّنات المقدَّمة لتشكيل العنوان الكامل الذي ستحاول واجهة برمجة التطبيقات ترميزه جغرافيًا. تبحث واجهة برمجة التطبيقات عن أفضل تطابق للعنوان الكامل المحدّد في جميع المكوّنات. يمكن أن يساعد توفير المكوّنات بطريقة منظَّمة واجهة برمجة التطبيقات في فهم الغرض بشكل أفضل، خاصةً عند جمع معلومات العنوان من حقول نموذج منفصلة. يمكن أن يساعد ذلك واجهة برمجة التطبيقات في معالجة الأخطاء الإملائية البسيطة أو حالات الالتباس داخل كل مكوّن، لأنّ نوع المعلومات في كل حقل يكون واضحًا.

لتحقيق سلوك مشابه لفلاتر المكوّنات الصارمة في الإصدار 3، عليك تنفيذ فلترة من جهة العميل على مصفوفة results التي تعرضها واجهة برمجة التطبيقات للإصدار 4 استنادًا إلى العنصرين postalAddress وaddressComponents في الردّ.

يعرض الجدول التالي أفضل تطابق بين فلاتر components في الإصدار 3 وحقول postalAddress في الإصدار 4:

فلتر المكوّنات في الإصدار 3 حقل الردّ في الإصدار 4
country postalAddress.regionCode
postal_code postalAddress.postalCode
administrative_area postalAddress.administrativeArea أو addressComponents

أمثلة على الفلترة من جهة العميل

توضّح الأمثلة التالية كيفية فلترة النتائج لتحقيق سلوك مشابه لفلترة المكوّنات في الإصدار 3 للحقول المتوافقة: البلد والمنطقة الإدارية والرمز البريدي. لا ننصح بالفلترة حسب الحقول الأخرى لأنّه لا تتوفّر معايير فلترة موثوقة.

الفلترة حسب البلد

طابِق address.regionCode من طلبك مع postalAddress.regionCode في كل نتيجة. يُرجى العِلم أنّه على الرغم من أنّ واجهة برمجة التطبيقات تقبل رموز المناطق المكتوبة بأحرف صغيرة في الطلب، فإنّها تعرضها دائمًا بأحرف كبيرة في الردّ، لذا يجب توحيد الإدخال إلى أحرف كبيرة قبل المقارنة.

مثال على رمز 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 في طلبك مع اختصار عادي من حرفَين. قد لا يتطابق postalAddress.administrativeArea في الرد مباشرةً مع لاحقات رمز ISO 3166-2 لعدة أسباب. أولاً، في بعض المناطق، لا يشكّل التقسيم الفرعي المقابل لرمز ISO 3166-2 جزءًا من التمثيل العادي للعناوين البريدية. على سبيل المثال، في إسبانيا، قد يكون مستوى المنطقة الإدارية 1 (مثل "CN" لجزر الكناري) متوفّرًا في addressComponents، ولكن قد يحتوي postalAddress.administrativeArea على مستوى المنطقة 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 أرقام حتى إذا تم تقديم أو عرض الرمز البريدي المكوّن من 9 أرقام.

مثال على رمز 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 من واجهة برمجة التطبيقات Reverse Geocoding API

إذا كنت تستخدم الإصدار الثالث من عكس الترميز الجغرافي لتحويل الإحداثيات إلى عناوين، عليك نقل بياناتك إلى الإصدار الرابع من طريقة عكس الترميز الجغرافي لموقع جغرافي التي تقبل طلب استرداد بيانات باستخدام GET.

تغيّر واجهة برمجة التطبيقات v4 الأسماء والبنية والدعم لعدة معلَمات. ننصحك بشدة باستخدام قناع حقل لتحديد الحقول التي تريد عرضها في الاستجابة.

تغييرات مَعلمات الطلب

مَعلمة v3 مَعلمة الإصدار 4 ملاحظات
language languageCode تمت إعادة التسمية. في حال حذف هذه المَعلمة، يستخدم الإصدار 3 العنوان Accept-Language أو الإعداد التلقائي en، في حين يستخدم الإصدار 4 الإعداد التلقائي للغة المحلية والنص البرمجي للموقع الجغرافي.
region regionCode تمت إعادة التسمية. عند حذفها، يتم ضبط الإصدار 3 تلقائيًا على us، في حين لا يتضمّن الإصدار 4 قيمة تلقائية.
result_type types تمت إعادة تسميته، ويستخدم مَعلمات طلب بحث متكرّرة.
location_type granularity تمت إعادة تسميتها، وتستخدم معلَمات طلب بحث متكررة.
extra_computations مُزال تم استبدالها بطريقة SearchDestinations.

تغييرات حقل الردّ

الحقل v3 حقل v4 ملاحظات
‫status، error_message مُزال يستخدم الإصدار 4 رموز حالة 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 منظَّم

نقل البيانات من واصفات العناوين في الإصدار 3

إذا كنت تستخدم address_descriptor للحصول على معلومات إضافية عن موقع جغرافي باستخدام الإصدار 3 من Geocoding، عليك الانتقال إلى استخدام الحقل landmarks في SearchDestinationsResponse.

نقل البيانات من الإصدار 3 من خدمة الترميز الجغرافي للأماكن

إذا كنت تستخدم place_id للحصول على عنوان رقم تعريف مكان معيّن باستخدام الإصدار 3 من Geocoding، عليك الانتقال إلى الإصدار 4 من طريقة Place Geocoding التي تقبل طلب استرداد بيانات باستخدام GET.

تغيّر واجهة برمجة التطبيقات v4 الأسماء والبنية والدعم لعدة معلَمات. ننصحك بشدة باستخدام قناع حقل لتحديد الحقول التي تريد عرضها في الرد.

تغييرات مَعلمات الطلب

مَعلمة v3 مَعلمة الإصدار 4 ملاحظات
place_id الحقل place في بروتوكول الطلب يتم الآن تقديم معرّف المكان كمَعلمة مسار places/{place}، على سبيل المثال: https://geocode.googleapis.com/v4/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw. يتم ربط هذا الحقل بحقل المكان في الطلب الأساسي.
language languageCode تمت إعادة التسمية. في حال عدم إدخال قيمة، يستخدم الإصدار 3 العنوان Accept-Language أو القيمة التلقائية en، بينما يستخدم الإصدار 4 اللغة والنص البرمجي المحليين للموقع الجغرافي كقيم تلقائية.
region regionCode تمت إعادة التسمية. عند حذفها، تكون القيمة التلقائية للإصدار 3 هي us، بينما لا يتضمّن الإصدار 4 قيمة تلقائية.

تغييرات حقل الردّ

الحقل v3 حقل v4 ملاحظات
‫status، error_message مُزال يستخدم الإصدار 4 رموز حالة HTTP ونصوص الأخطاء.
results (root) تعرض الإصدار 4 عنصر نتيجة واحدًا، وليس مصفوفة 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 تمت إعادة التسمية. تم الآن عرضها لبلدة واحدة أو أكثر (الإصدار 3 مطلوب > 1).
الأرباح الجديدة addressComponents.languageCode لغة مكوّن العنوان المحدّد
الأرباح الجديدة bounds حدود صريحة باستخدام high/low
الأرباح الجديدة place اسم المورد للمكان
الأرباح الجديدة postalAddress عنصر PostalAddress منظَّم

الانتقال من "الترميز الجغرافي للبيانات المحلية" إلى "الوجهات"

سيتم استبدال الميزات التالية في الإصدار 3 من Geocoding API بطريقة SearchDestinations في الإصدار 4 من Geocoding API:

  • مرّات الدخول
  • نقاط التنقّل
  • مخطّطات المباني
  • الأراضي المحيطة

إذا كنت تستخدم الإصدار 3 من Geocoding API للميزات المذكورة أعلاه، يمكنك الاستعانة بهذا المستند للاستفادة من طريقة SearchDestinations بدلاً من ذلك للحصول على هذه الميزات. يوضّح هذا المستند مكان العثور على هذه الميزات في الردّ SearchDestinations، والاختلافات في طريقة تمثيل هذه الميزات في الردود التي تقدّمها واجهة برمجة التطبيقات بين الإصدار 3 من Geocoding API وطريقة SearchDestinations في الإصدار 4 من Geocoding API.

مرّات الدخول

للحصول على المداخل المرتبطة بـ destination، استخدِم الحقل destination.entrances.

يُرجى العِلم أنّ تنسيق entrance يختلف قليلاً عن تنسيق المدخل في الإصدار 3 من Geocoding API. يحتوي كل مدخل في destination.entrances على الحقول التالية:

  • ‫displayName: هذا حقل اختياري جديد يتضمّن اسمًا للمدخل يمكن لشخص عادي قراءته، مثل "البوابة ب".
  • location: يمثّل هذا الموقع الجغرافي من النوع LatLng، وهو يختلف عن التنسيق المستخدَم في الإصدار 3 من Geocoding API.
  • tags: هذا الحقل هو نفسه الحقل tags الخاص بالمداخل من الإصدار 3 من Geocoding API.
  • place - يشبه حقل buildingPlaceId للمداخل من الإصدار الثالث من Geocoding API. ومع ذلك، يمكن أن يكون رقم تعريف المكان في هذا الحقل لمكان من أي نوع، وليس بالضرورة مبنى فقط.

للحصول على نقاط التنقّل المرتبطة بـ destination، استخدِم الحقل destination.navigationPoints.

يُرجى العِلم أنّ تنسيق navigationPoint يختلف قليلاً عن تنسيق نقطة التنقّل في الإصدار 3 من Geocoding API. تحتوي كل نقطة تنقّل في destination.navigationPoints على الحقول التالية:

  • ‫displayName: هذا حقل اختياري جديد يتضمّن اسمًا يمكن قراءته لنقطة التنقّل، مثل "شارع 5".
  • location - هذا موقع جغرافي من النوع LatLng، وهو يختلف عن التنسيق المستخدَم في الإصدار 3 من Geocoding API.
  • ‫travelModes: يشبه هذا الحقل الحقل restrictedTravelModes الخاص بنقاط التنقّل من الإصدار 3 من Geocoding API. قيم التعداد الممكنة هي نفسها، والفرق الوحيد هو أنّ هذا الحقل يمثّل الآن وسائل النقل المقبولة لنقطة التنقّل، بدلاً من وسائل النقل المحظورة.
  • ‫usage: هذا حقل جديد يحتوي على حالات الاستخدام التي تتيحها نقطة التنقّل.

مخطّطات المباني

للحصول على المخططات التفصيلية للمباني المرتبطة بـ destination، يجب استخدام الحقل displayPolygon في عناصر placeView ضمن destination التي تمثّل المباني. بالنسبة إلى كل placeView، يمكنك التحقّق مما إذا كان مبنى باستخدام الحقل placeView.structureType. إذا كان نوع البنية هو BUILDING، يمكنك الحصول على المخطط التفصيلي من الحقل placeView.displayPolygon. ستتضمّن placeView أيضًا حقولاً إضافية للمبنى لم تكن متوفّرة في الإصدار 3 من Geocoding API.

يمكن أن يحتوي destination على عنصر placeView يمثّل مبنى في الحقول التالية:

  • ‫destination.primary: هذا هو المكان الأساسي للوجهة.
  • ‫destination.containingPlaces: هذا حقل متكرّر يمكن أن يتضمّن أماكن أكبر "تحتوي" على المكان الأساسي. على سبيل المثال، إذا كان المكان الأساسي هو subpremise، سيحتوي containingPlaces عادةً على placeView الذي يمثّل المبنى.
  • ‫destination.subDestinations: هذا حقل متكرّر يمكنه الاحتفاظ بوجهات فرعية للمكان الأساسي. على سبيل المثال، وحدات الشقق الفردية في المبنى. لا يتضمّن هذا الحقل عادةً placeView يمثّل مبنى.

يُرجى العِلم أنّ تنسيق placeView.displayPolygon يتطابق مع تنسيق مخطط المبنى في الإصدار 3 من Geocoding API، وهو تنسيق GeoJSON، باستخدام تنسيق RFC 7946.

الأراضي المحيطة

على غرار مخططات المباني، للحصول على الأراضي المرتبطة بـ destination، عليك استخدام الحقل displayPolygon الخاص بكائنات placeView في destination التي تمثّل الأراضي. بالنسبة إلى كل placeView، يمكنك التحقّق مما إذا كان يمثّل أرضًا باستخدام الحقل placeView.structureType. إذا كان نوع البنية هو GROUNDS، يمكنك الحصول على المخطط من الحقل placeView.displayPolygon. ستتضمّن placeView أيضًا حقولاً إضافية للأراضي لم تكن متوفّرة في الإصدار 3 من Geocoding API.

يمكن أن يحتوي destination على عنصر placeView يمثّل أرضًا في الحقول التالية:

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

يُرجى العِلم أنّ تنسيق placeView.displayPolygon يتطابق مع تنسيق مخطط الأراضي في Geocoding API الإصدار 3، وهو تنسيق GeoJSON، باستخدام تنسيق RFC 7946.

دقة النتائج

في الإصدار 3 من Geocoding API، كان حقل location_type في هندسة الاستجابة يشير إلى دقة النتائج، وكان بعض العملاء يرتّبون النتائج أو يفلترونها استنادًا إلى هذه القيم (ROOFTOP وRANGE_INTERPOLATED وGEOMETRIC_CENTER وAPPROXIMATE). في عمليات نقل البيانات العادية إلى الإصدار 4 من Geocoding API، تتم إعادة تسمية هذا الحقل ليصبح granularity.

في Destinations API (الإصدار 4 SearchDestinations)، لا يتوفّر الحقل location_type. بدلاً من ذلك، يتم التعامل مع المعلومات المكانية بشكل مختلف:

  • لا حاجة إلى فلترة يدوية من جهة العميل: على الرغم من أنّ خدمة الترميز الجغرافي العادية تقدّم نتائج متعدّدة بمستويات تفصيل مختلفة، تقلّل طريقة SearchDestinations من الغموض من خلال تحديد وجهة واحدة محسّنة كلما أمكن ذلك. يؤدي هذا إلى إزالة حاجة العملاء إلى التصفية حسب نوع الموقع لتحديد النتيجة الأفضل.
  • المعلومات المكانية الممثَّلة بنوع البنية والمضلّعات المعروضة: يتم الإشارة إلى الهندسة المكانية والبنية من خلال:
    • ‫displayPolygon (للحصول على هندسة دقيقة)
    • الحقل structureType ضمن الكائن placeView
  • تحديد نوع البنية:
    • إنّ التقييم structureType من POINT أو BUILDING أو SECTION يتوافق بشكل عام مع ما كان يُعرف سابقًا باسم ROOFTOP.
    • يمثّل structureType من GROUNDS بشكل عام GEOMETRIC_CENTER.

استخدام قناع حقل لطلب هذه الميزات

تتطلّب طريقة SearchDestinations قناع حقل، كما هو موضّح في مقالة اختيار الحقول المطلوب عرضها. يمكن ضبط قناع الحقل على * لعرض جميع الحقول، أو يمكنك ضبطه على الحقول المحدّدة التي تريد تلقّيها. على سبيل المثال، يضبط طلب البيانات من واجهة برمجة التطبيقات التالي قناع الحقل لتلقّي جميع الحقول المطلوبة للحصول على المداخل ونقاط التنقّل ومخططات المباني والأراضي الخاصة بوجهة معيّنة:

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

الاعتبارات الأمنية

تم تصميم الإصدار 4 من Geocoding API ليكون واجهة برمجة تطبيقات من خادم إلى خادم. لا يتوفّر مسار نقل بيانات مباشر لمستخدمي JavaScript من الإصدار 3 إلى الإصدار 4. إنّ استدعاء طرق الإصدار 4 مباشرةً من JavaScript من جهة العميل (على سبيل المثال، في متصفّح) باستخدام مفتاح واجهة برمجة التطبيقات يعرّض مفتاح واجهة برمجة التطبيقات لخطر كبير يتمثّل في السرقة وإساءة الاستخدام.

على الرغم من أنّ القيود المفروضة على مُحيل HTTP مفيدة، إلا أنّها لا توفّر حماية كافية لنقاط نهاية خدمة الويب، إذ يمكن للمهاجمين تجاوزها بسهولة من خلال تزوير عنوان Referer في طلباتهم.

الطريقة المقترَحة لاستخدام الإصدار 4 من Geocoding API هي من خلال خادم الخلفية الخاص بك. يجب أن يرسل تطبيق العميل الطلبات إلى هذا الخادم الوسيط، الذي يستدعي بعد ذلك Google APIs بشكل آمن باستخدام مفتاح واجهة برمجة تطبيقات محمي (على سبيل المثال، مفتاح مخزَّن في متغيّر بيئة أو مدير أسرار). يضمن ذلك عدم الكشف عن مفتاح واجهة برمجة التطبيقات في رمز الواجهة الأمامية.

بدائل لاحتياجات من جهة العميل

إذا كانت لديك احتياجات من جهة العميل تتطلّب الترميز الجغرافي، ننصحك باستخدام أحد الحلول الحالية من جهة العميل: