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

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

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

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

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

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

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

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

المَعلمة v3 مَعلمة الإصدار 4 ملاحظات
‫address، components address يتم الآن تمرير العنوان غير المنظَّم (الإصدار 3 address) في مسار عنوان URL. يتم الآن تمرير فلاتر المكوّنات (الإصدار 3 components) كمَعلمات طلب بحث address.*.
bounds locationBias.rectangle تمت إعادة تسميته، وتم تغيير البنية إلى عنصر.
language languageCode تمت إعادة التسمية.
region regionCode تمت إعادة التسمية.
extra_computations مُزال

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

الحقل 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 منظَّم

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

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

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

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

المَعلمة v3 مَعلمة الإصدار 4 ملاحظات
language languageCode تمت إعادة التسمية.
region regionCode تمت إعادة التسمية.
result_type types تمت إعادة تسميته، ويستخدم مَعلمات طلب بحث متكرّرة.
location_type granularity تمت إعادة تسميته، ويستخدم مَعلمات طلب بحث متكرّرة.
extra_computations مُزال

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

الحقل 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 من الترميز الجغرافي، عليك الانتقال إلى استخدام الحقل landmarks من SearchDestinationsResponse.

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

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

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

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

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

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

الحقل v3 الحقل v4 ملاحظات
‫status، error_message مُزال يستخدم الإصدار 4 رموز حالة HTTP ونصوص الأخطاء.
results (الجذر) تعرض الإصدار 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 منظَّم

الانتقال من Geocoding Hyperlocal Data إلى Destinations

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

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

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

مرّات الدخول

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

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

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

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

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

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

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

للحصول على المخططات التفصيلية للمباني المرتبطة بـ 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.

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

تتطلّب طريقة 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 من جهة العميل (على سبيل المثال، في متصفّح) باستخدام مفتاح API يعرّض مفتاح API لخطر كبير من السرقة وإساءة الاستخدام.

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

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

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

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