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

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

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

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

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

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

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

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

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