نقل البيانات من ميزات الإصدار 3 إلى نقطة النهاية SearchDestinations

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

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

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

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

مرّات الدخول

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

يُرجى العِلم أنّ تنسيق entrance يختلف قليلاً عن تنسيق المدخل في Geocoding API v3. يحتوي كل مدخل في 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 v3. تحتوي كل نقطة تنقّل في 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 يتطابق مع تنسيق مخطط الأراضي في الإصدار 3 من Geocoding API، وهو تنسيق 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/v4alpha/geocode/destinations