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

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

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

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

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

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

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

• language — اللغة التي يتم عرض النتائج بها.
  • اطّلِع على قائمة اللغات المتاحة. غالبًا ما يعدّل Google اللغات المتاحة، لذا قد لا تكون هذه القائمة شاملة.
  • إذا لم يتم توفير السمة language، يحاول برنامج الترميز الجغرافي استخدام اللغة المفضّلة على النحو المحدّد في العنوان Accept-Language، أو اللغة الأم للنطاق الذي تم إرسال الطلب منه.
  • يقدّم أداة الترميز الجغرافي قصارى جهده لتقديم عنوان شارع يمكن لكل من المستخدم والسكان المحليين قراءته. ولتحقيق هذا الهدف، يتم عرض عناوين الشوارع باللغة المحلية، ويتم تحويلها صوتيًا إلى نص برمجي يمكن للمستخدم قراءته عند الضرورة، مع مراعاة اللغة المفضّلة. ويتم عرض جميع العناوين الأخرى باللغة المفضّلة. يتم عرض جميع مكونات العنوان بنفس اللغة التي يتم اختيارها من المكون الأول.
  • إذا لم يكُن الاسم متاحًا باللغة المفضّلة، يستخدم برنامج الترميز الجغرافي أقرب تطابق.
• region — هو رمز المنطقة الذي يتم تحديده على أنّه قيمة مؤلفة من حرفَين لنطاق المستوى الأعلى التي يتم ترميزها حسب البلد ("نطاق المستوى الأعلى") . ويمكن أن تؤثر المَعلمة أيضًا في النتائج استنادًا إلى القانون الساري.
• result_type - فلتر لنوع واحد أو أكثر من العناوين، مع الفصل باستخدام الشرطة الرأسية (|). إذا كانت المَعلمة تحتوي على أنواع متعددة من العناوين، تعرض واجهة برمجة التطبيقات جميع العناوين التي تتطابق مع أي من الأنواع. ملاحظة حول المعالجة: لا تؤدّي المَعلمة result_type إلى restrict البحث على أنواع العناوين المحدَّدة. بدلاً من ذلك، يعمل 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 — فلتر لنوع واحد أو أكثر من أنواع المواقع الجغرافية، مفصولاً بشرطة (|). إذا كانت المَعلمة تحتوي على أنواع متعددة من المواقع الجغرافية، تعرض واجهة برمجة التطبيقات جميع العناوين التي تتطابق مع أي نوع من الأنواع. ملاحظة حول المعالجة: لا تؤدّي المَعلمة location_type إلى restrict البحث بأنواع المواقع الجغرافية المحدّدة. بدلاً من ذلك، يعمل location_type كفلتر بعد البحث: تجلب واجهة برمجة التطبيقات جميع النتائج الخاصة بـ latlng المحدَّد، ثم تتجاهل النتائج التي لا تتطابق مع أنواع المواقع الجغرافية المحدّدة. القيم التالية متاحة:
  • تعرض "ROOFTOP" فقط العناوين التي يتوفر لدى Google معلومات موقع جغرافي دقيقة لها استنادًا إلى دقة عنوان الشارع.
  • تعرض "RANGE_INTERPOLATED" فقط العناوين التي تمثّل التقريب (على الطريق عادةً) المُدخَلة بين نقطتين دقيقتَين (مثل التقاطعات). يشير النطاق المستقيم بشكل عام إلى أنّ الرموز الجغرافية الخاصة بالأسطح غير متاحة لعنوان شارع محدّد.
  • تعرض "GEOMETRIC_CENTER" المراكز الهندسية فقط لموقع جغرافي، مثل الخطوط المتعددة (على سبيل المثال، شارع) أو المضلّع (المنطقة).
  • تعرض السمة "APPROXIMATE" العناوين التي يتم تصنيفها على أنّها تقريبية فقط.
• extra_computations — القيمة الوحيدة المسموح بها لهذه المعلَمة هي ADDRESS_DESCRIPTORS. راجِع أدوات وصف العناوين للحصول على مزيد من التفاصيل.

في حال توفّر الفلتر 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" في كائن الاستجابة Geocoding على حالة الطلب، وقد يحتوي على معلومات تصحيح الأخطاء لمساعدتك في تتبع سبب عدم عمل الترميز الجغرافي العكسي. قد يحتوي الحقل "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 أمتار.

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