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

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

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

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

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

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

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

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