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

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

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

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

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

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

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

• language: اللغة التي سيتم عرض النتائج بها
  • اطّلِع على قائمة اللغات المتوافقة. وغالبًا ما تُعدِّل Google اللغات المتاحة، لذا قد لا تكون هذه القائمة شاملة.
  • إذا لم يتم توفير السمة language، يحاول مشرف الموقع الجغرافي استخدام اللغة المفضّلة على النحو المحدّد في عنوان Accept-Language أو اللغة الأصلية للنطاق الذي تم إرسال الطلب منه.
  • وتبذل أداة ترميز البيانات قصارى جهدها لتوفير عنوان شارع يمكن للمستخدمين والمستخدمين المحليين رؤيته. ولتحقيق هذا الهدف، تعرض الخدمة عناوين الشوارع باللغة المحلية التي يتم تحويلها إلى نص برمجي يمكن للمستخدم قراءته عند الضرورة مع مراعاة اللغة المفضّلة. ويتم عرض جميع العناوين الأخرى باللغة المفضّلة. يتم عرض جميع مكوّنات العنوان باللغة نفسها، والتي يتم اختيارها من المكوّن الأول.
  • وإذا لم يكن الاسم متاحًا باللغة المفضّلة، يستخدم برنامج الترميز الجغرافي أقرب مطابقة.
• region: رمز المنطقة الذي يتم تحديده على أنه حرفَي نطاق ccTLD ("نطاق المستوى الأعلى") يمكن أن تؤثر المَعلمة أيضًا في النتائج استنادًا إلى القانون الساري.
• result_type: فلتر واحد أو أكثر من أنواع العناوين، مفصولة بفواصل (|). إذا كانت المعلَمة تحتوي على أنواع متعددة من العناوين، ستعرض واجهة برمجة التطبيقات جميع العناوين التي تطابق أيًا من الأنواع. ملاحظة حول المعالجة: لا تؤدي المعلَمة result_type إلى تقييد البحث بأنواع العناوين المحدّدة. وبدلاً من ذلك، تعمل السمة result_type كفلتر لما بعد البحث: تجلب واجهة برمجة التطبيقات جميع نتائج latlng المحدّدة، ثم تتجاهل النتائج التي لا تتطابق مع أنواع العناوين المحدّدة. والقيم التالية متاحة:
  • street_address يشير إلى عنوان شارع دقيق.
  • تشير القيمة route إلى مسار مُسمّى (مثل "US 101").
  • تشير السمة intersection إلى تقاطع رئيسي، يتألف عادةً من طريقَين رئيسيتَين.
  • تشير السمة political إلى كيان سياسي. عادةً ما يشير هذا النوع إلى شكل مضلع بعض الإدارة المدنية.
  • تشير السمة country إلى الكيان السياسي الوطني، وعادةً ما تكون أعلى نوع ترتيب يعرضه برنامج ترميز المواقع الجغرافية.
  • تشير السمة administrative_area_level_1 إلى كيان مدني من المستوى الأول أسفل مستوى البلد. تكون هذه المستويات الإدارية في الولايات المتحدة. ولا تعرض جميع البلدان هذه المستويات الإدارية. في معظم الحالات، تتطابق الأسماء الإدارية_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 إلى مرجع موقع مشفّر مشتق من خط العرض وخط الطول. يمكن استخدام رموز Plus Codes لاستبدال عناوين الشوارع في الأماكن التي لا تتوفّر فيها (حيث لا تكون المباني مرقّمة أو لا تتم تسمية الشوارع بها). يمكنك الاطّلاع على 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

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

{
   "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 وعنوان يحتوي على رمز علامة زائد. يتم ضمان المسافة بين رمز Plus Codes ونقطة الطلب الأقل من 10 أمتار.