طلب الاستجابة العكسية للموقع الجغرافي (البحث عن العنوان) والردّ عليه

يشير مصطلح الترميز الجغرافي بشكل عام إلى ترجمة عنوان يمكن للمستخدمين قراءته إلى موقع على الخريطة. تُعرف عملية إجراء العكس، ترجمة الموقع على الخريطة إلى عنوان يمكن قراءته، باسم الترميز الجغرافي العكسي.

عكس طلبات الترميز الجغرافي

المعلمات المطلوبة

• latlng — إحداثيات خطوط العرض وخطوط الطول التي تحدد الموقع الجغرافي الذي تريد أن يكون العنوان الأقرب إليه والذي يمكن للمستخدمين قراءته.
• key — مفتاح واجهة برمجة التطبيقات للتطبيق. يحدّد هذا المفتاح تطبيقك لأغراض إدارة الحصص. تعرَّف على كيفية الحصول على مفتاح.

المعلمات الاختيارية

في ما يلي المعلمات الاختيارية التي يمكنك تضمينها في طلب الترميز الجغرافي العكسي:

• language — اللغة التي سيتم عرض النتائج بها.
  • راجِع قائمة اللغات المتوافقة. غالبًا ما تحدّث Google اللغات المتوافقة، لذا قد لا تكون هذه القائمة شاملة.
  • إذا لم يتم تقديم language، يحاول برنامج الترميز الجغرافي استخدام اللغة المفضّلة على النحو المحدّد في العنوان Accept-Language أو اللغة الأصلية للنطاق الذي يتم إرسال الطلب منه.
  • وتبذل أداة الترميز الجغرافي أقصى جهدها لتوفير عنوان شارع يمكن لكل من المستخدم والسكان المحليين قراءته. ولتحقيق هذا الهدف، تعرض علامة التبويب هذه عناوين الشوارع باللغة المحلية، ويتم تحويلها إلى نص برمجي يمكن للمستخدم قراءته، إذا لزم الأمر، مع مراعاة اللغة المفضّلة. ويتم عرض جميع العناوين الأخرى باللغة المفضّلة. ويتم عرض جميع مكوّنات العناوين باللغة نفسها التي يتم اختيارها من المكوِّن الأول.
  • إذا لم يكن الاسم متوفّرًا باللغة المفضّلة، يستخدم برنامج الترميز الجغرافي التطابق الأقرب.
• result_type — فلتر من نوع واحد أو أكثر من أنواع العناوين، مفصول بينها بشرطة (|). إذا كانت المعلمة تحتوي على أنواع عناوين متعددة، تعرض واجهة برمجة التطبيقات جميع العناوين التي تطابق أيًا من الأنواع. ملاحظة عن المعالجة: لا تقوم المعلمة result_type بتقييد البحث على أنواع العناوين المحددة. وبدلاً من ذلك، تعمل السمة result_type كفلتر بعد البحث: تجلب واجهة برمجة التطبيقات جميع النتائج للسمة latlng المحدّدة، ثم تتجاهل النتائج التي لا تتطابق مع أنواع العناوين المحدّدة. القيم التالية متاحة:
  • يشير street_address إلى عنوان شارع دقيق.
  • تشير القيمة route إلى مسار مسمّى (مثل "US 101").
  • تشير علامة intersection إلى تقاطع رئيسي، يتألف عادةً من طريقين رئيسيين.
  • تشير القيمة political إلى كيان سياسي. يشير هذا النوع عادةً إلى مضلع بعض الإدارة المدنية.
  • يشير country إلى الكيان السياسي الوطني، وهو عادةً أعلى نوع من الطلبات يعرضه برنامج الترميز الجغرافي.
  • تشير السمة administrative_area_level_1 إلى كيان مدني من الدرجة الأولى أسفل مستوى البلد. في الولايات المتحدة، تكون هذه المستويات الإدارية ولايات. ولا تعرض جميع الدول هذه المستويات الإدارية. في معظم الحالات، تتطابق الأسماء المختصرة على مستوى ISO_area_level_1 بشكل وثيق مع الأقسام الفرعية ISO 3166-2 والقوائم الأخرى المتداولة على نطاق واسع، إلا أن هذا لا يمكن ضمانه لأن نتائج الترميز الجغرافي تستند إلى إشارات متنوعة وبيانات موقع جغرافي.
  • تشير الخاصية administrative_area_level_2 إلى كيان مدني من الدرجة الثانية أسفل مستوى البلد. وتندرج هذه المستويات الإدارية في الولايات المتحدة ضمن المقاطعات. ولا تعرض جميع الدول هذه المستويات الإدارية.
  • تشير السمة administrative_area_level_3 إلى كيان مدني من الدرجة الثالثة أسفل مستوى البلد. يشير هذا النوع إلى تقسيم مدني ثانوي. ولا تعرض جميع الدول هذه المستويات الإدارية.
  • تشير السمة administrative_area_level_4 إلى كيان مدني من المستوى الرابع أسفل مستوى البلد. يشير هذا النوع إلى تقسيم مدني ثانوي. ولا تعرض جميع الدول هذه المستويات الإدارية.
  • تشير القيمة administrative_area_level_5 إلى كيان مدني ذي ترتيب خامس أسفل مستوى البلد. يشير هذا النوع إلى تقسيم مدني ثانوي. ولا تعرض جميع الدول هذه المستويات الإدارية.
  • تشير القيمة administrative_area_level_6 إلى كيان مدني من المستوى السادس أسفل مستوى البلد. يشير هذا النوع إلى تقسيم مدني ثانوي. ولا تعرض جميع الدول هذه المستويات الإدارية.
  • تشير القيمة administrative_area_level_7 إلى كيان مدني من المستوى السابع أسفل مستوى البلد. يشير هذا النوع إلى تقسيم مدني ثانوي. ولا تعرض جميع الدول هذه المستويات الإدارية.
  • تشير السمة colloquial_area إلى اسم بديل شائع الاستخدام للكيان.
  • تشير القيمة locality إلى كيان سياسي مضمّن في مدينة أو بلدة.
  • تشير الخاصية sublocality إلى الكيان المدني من الدرجة الأولى أسفل المنطقة المحلية. بالنسبة إلى بعض المواقع الجغرافية، قد تتلقّى أحد الأنواع الإضافية: sublocality_level_1 إلى sublocality_level_5. كل مستوى من مستويات المنطقة المحلية الفرعية هو كيان مدني. وتشير الأرقام الأكبر إلى مساحة جغرافية أصغر.
  • يشير neighborhood إلى حي مُعنون
  • تشير علامة premise إلى موقع جغرافي مُسمّى، وعادةً ما يكون مبنى أو مجموعة من المباني ذات الاسم الشائع.
  • تشير علامة subpremise إلى كيان من المستوى الأول أسفل موقع جغرافي محدّد، ويكون عادةً مبنى واحدًا ضمن مجموعة من المباني ذات الاسم الشائع.
  • يشير plus_code إلى مرجع موقع مشفر، مستمد من خط العرض وخط الطول. يمكن استخدام رموز المواقع المفتوحة كبديل لعناوين الشوارع في الأماكن التي لا توجد فيها (حيث لا تكون المباني مرقمة أو لا تحمل أسماء الشوارع). راجع https://plus.codes للحصول على التفاصيل.
  • تشير السمة postal_code إلى رمز بريدي يُستخدم للتعامل مع البريد البريدي داخل البلد.
  • تشير علامة natural_feature إلى موضع طبيعي بارز.
  • يشير airport إلى مطار.
  • تشير علامة park إلى متنزه مُعنون.
  • تشير علامة point_of_interest إلى نقطة اهتمام مُعنونة. وعادةً ما تكون "نقاط الاهتمام" هذه كيانات محلية بارزة لا تلائم بسهولة فئة أخرى، مثل "مبنى إمباير ستيت" أو "برج إيفل".
• location_type — فلتر لنوع واحد أو أكثر من أنواع المواقع الجغرافية، مع الفصل بينها بخط عمودي (|). إذا كانت المعلّمة تحتوي على أنواع مواقع جغرافية متعددة، ستعرض واجهة برمجة التطبيقات جميع العناوين التي تتطابق مع أي نوع من الأنواع. ملاحظة عن المعالجة: لا تُجري المعلّمة location_type تقييدًا للبحث على أنواع المواقع الجغرافية المحدّدة. وبدلاً من ذلك، تعمل السمة location_type كفلتر بعد البحث: تجلب واجهة برمجة التطبيقات جميع النتائج للسمة latlng المحدّدة، ثم تتجاهل النتائج التي لا تتطابق مع أنواع المواقع الجغرافية المحدّدة. تتوفّر القيم التالية:
  • لا تعرض "ROOFTOP" سوى العناوين التي يشتمل محرك بحث Google على معلومات موقعها بدقة حتى دقة عنوان الشارع.
  • لا تعرض "RANGE_INTERPOLATED" سوى العناوين التي تعكس موقعًا تقريبيًا (عادةً على طريق) في ما بين نقطتين دقيقتين (مثل التقاطعات). يشير النطاق الذي تمت إضافته بشكل عام إلى أنّ الرموز الجغرافية على السطح غير متاحة لعنوان الشارع.
  • تعرض "GEOMETRIC_CENTER" المراكز الهندسية لموقع جغرافي فقط مثل الخط المتعدد الخطوط (مثل الشارع) أو المضلّع (المنطقة).
  • لا تعرض "APPROXIMATE" سوى العناوين التي يتم تحديدها على أنها تقريبية.

وفي حال توفّر الفلترَين result_type وlocation_type، ستعرض واجهة برمجة التطبيقات فقط النتائج التي تتطابق مع القيمتَين result_type وlocation_type. إذا لم تكن أي من قيم الفلتر مقبولة، ستعرض واجهة برمجة التطبيقات ZERO_RESULTS.

مثال على الترميز الجغرافي العكسي

يحتوي طلب البحث التالي على قيمة خط العرض/الطول لموقع في الإسكندرية:

https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452&key=YOUR_API_KEY

ملاحظة: تأكَّد من عدم وجود أي مسافة بين قيم خطوط العرض وخطوط الطول عند تمريرها في المعلَمة latlng.

يعرض طلب البحث أعلاه النتيجة التالية:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "277",
               "short_name" : "277",
               "types" : [ "street_number" ]
            },
            {
               "long_name" : "Bedford Avenue",
               "short_name" : "Bedford Ave",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Williamsburg",
               "short_name" : "Williamsburg",
               "types" : [ "neighborhood", "political" ]
            },
            {
               "long_name" : "Brooklyn",
               "short_name" : "Brooklyn",
               "types" : [ "sublocality", "political" ]
            },
            {
               "long_name" : "Kings",
               "short_name" : "Kings",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "New York",
               "short_name" : "NY",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "11211",
               "short_name" : "11211",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "277 Bedford Avenue, Brooklyn, NY 11211, USA",
         "geometry" : {
            "location" : {
               "lat" : 40.714232,
               "lng" : -73.9612889
            },
            "location_type" : "ROOFTOP",
            "viewport" : {
               "northeast" : {
                  "lat" : 40.7155809802915,
                  "lng" : -73.9599399197085
               },
               "southwest" : {
                  "lat" : 40.7128830197085,
                  "lng" : -73.96263788029151
               }
            }
         },
         "place_id" : "ChIJd8BlQ2BZwokRAFUEcm_qrcA",
         "types" : [ "street_address" ]
      },

  ... Additional <code>results[]</code> ...

لاحظ أن برنامج الترميز الجغرافي العكسي عرض أكثر من نتيجة واحدة. لا تمثل نتائج "formatted_address" عناوين بريدية فحسب، بل هي طريقة لتسمية موقع جغرافي. على سبيل المثال، عند ترميز موقع جغرافي في مدينة شيكاغو، يمكن الإشارة إلى النقطة جغرافيًا على أنها عنوان شارع، أو كالمدينة (شيكاغو)، أو الولاية (إلينوي) أو كبلد (الولايات المتحدة). جميعها "عناوين" إلى أداة الترميز الجغرافي. وتعرض أداة الترميز العكسية أيًا من هذه الأنواع كنتائج صالحة.

ويتطابق نظام الترميز الجغرافي العكسي مع الكيانات السياسية (البلاد والمقاطعات والمدن والأحياء) وعناوين الشوارع والرموز البريدية.

في ما يلي القائمة الكاملة لقيم formatted_address التي يعرضها طلب البحث السابق.

{
   "plus_code" : {
      "compound_code" : "P27Q+MCM New York, NY, USA",
      "global_code" : "87G8P27Q+MCM"
   },
   "results" : [
      {
         "formatted_address" : "277 Bedford Ave, Brooklyn, NY 11211, USA",
         ...
         "types" : [ "street_address" ]
      },
      {
         "formatted_address" : "279 Bedford Ave, Brooklyn, NY 11211, USA",
         ...
         "types" : [ "premise" ]
      },
      {
         "formatted_address" : "277 Bedford Ave, Brooklyn, NY 11211, USA",
         ...
         "types" : [ "establishment", "point_of_interest" ]
      },
      {
         "formatted_address" : "291-275 Bedford Ave, Brooklyn, NY 11211, USA",
         ...
         "types" : [ "route" ]
      },
      {
         "formatted_address" : "P27Q+MC New York, NY, USA",
         ...
         "types" : [ "plus_code" ]
      },
      {
         "formatted_address" : "South Williamsburg, Brooklyn, NY, USA",
         ...
         "types" : [ "neighborhood", "political" ]
      },
      {
         "formatted_address" : "Brooklyn, NY 11211, USA",
         ...
         "types" : [ "postal_code" ]
      },
      {
         "formatted_address" : "Williamsburg, Brooklyn, NY, USA",
         ...
         "types" : [ "neighborhood", "political" ]
      },
      {
         "formatted_address" : "Kings County, Brooklyn, NY, USA",
         ...
         "types" : [ "administrative_area_level_2", "political" ]
      },
      {
         "formatted_address" : "Brooklyn, NY, USA",
         ...
         "types" : [ "political", "sublocality", "sublocality_level_1" ]
      },
      {
         "formatted_address" : "New York, NY, USA",
         ...
         "types" : [ "locality", "political" ]
      },
      {
         "formatted_address" : "New York, USA",
         ...
         "types" : [ "administrative_area_level_1", "political" ]
      },
      {
         "formatted_address" : "United States",
         ...
         "types" : [ "country", "political" ]
      }
   ],
   "status" : "OK"
}

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

ملاحظة: يعتبر الترميز الجغرافي العكسي تقديريًا. يحاول برنامج الترميز الجغرافي العثور على أقرب موقع قابل للمعالجة ضمن نطاق تسامح معيّن. وإذا لم يعثر برنامج الترميز الجغرافي على مطابقة، لا يعرض أي نتائج.

عكس الترميز الجغرافي المفلتر حسب النوع

يوضّح المثال التالي العناوين التي تم عرضها لتتضمن فقط العناوين التي تتضمّن نوع الموقع الجغرافي ROOFTOP ونوع العنوان street_address.

https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452
&location_type=ROOFTOP&result_type=street_address&key=YOUR_API_KEY

ملاحظة: هذه الفلاتر صالحة فقط للترميز الجغرافي العكسي.

عكس استجابات الترميز الجغرافي

يكون تنسيق استجابة الترميز الجغرافي هو نفسه استجابة الترميز الجغرافي. راجع استجابات الترميز الجغرافي. في ما يلي شفرات الحالة الممكنة في استجابة الترميز الجغرافي.

رموز حالة الترميز الجغرافي العكسي

يحتوي الحقل "status" ضمن كائن الاستجابة "الترميز الجغرافي" على حالة الطلب، وقد يحتوي على معلومات تصحيح الأخطاء لمساعدتك في تتبّع سبب عدم عمل ميزة الترميز الجغرافي العكسي. قد يحتوي الحقل "status" على القيم التالية:

• تشير القيمة "OK" إلى عدم حدوث أخطاء وإرجاع عنوان واحد على الأقل.
• تشير القيمة "ZERO_RESULTS" إلى أن الترميز الجغرافي العكسي كان ناجحًا، ولكن لم يتم عرض أي نتائج. وقد يحدث ذلك إذا اجتازت أداة الترميز latlng في موقع بعيد.
• يشير "OVER_QUERY_LIMIT" إلى أنك تجاوزت حصتك.
• تشير علامة "REQUEST_DENIED" إلى أنه تم رفض الطلب. قد يكون السبب أنّ الطلب يتضمّن معلَمة result_type أو location_type ولكن لا يتضمّن مفتاح واجهة برمجة تطبيقات.
• تشير السمة "INVALID_REQUEST" بشكل عام إلى أحد العناصر التالية:
  • طلب البحث (address أو components أو latlng) مفقود.
  • تم تقديم سمة result_type أو location_type غير صالحة.
• تشير علامة "UNKNOWN_ERROR" إلى أنّه تعذّرت معالجة الطلب بسبب خطأ في الخادم. وقد ينجح الطلب في حال إعادة المحاولة.

عكس رموز المواقع الجغرافية الإضافية

يحتوي الحقل plus_code ضمن استجابة الترميز الجغرافي على رمز زائد يُطابق تقريبًا خطوط الطول والعرض المطلوبة. بالإضافة إلى ذلك، تحتوي مصفوفة نتائج JSON في معظم الحالات على نتيجة ترميز جغرافي كاملة مع نوع plus_code وعنوان يحتوي على رمز علامة زائد. يتم ضمان المسافة بين رمز الموقع المفتوح الذي تم فك ترميزه ونقطة الطلب لأقل من 10 أمتار.

ملاحظة: لا تعرض واجهة برمجة التطبيقات دائمًا رموز Plus Codes.