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

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

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

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

  • 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 إلى كيان مدني من الدرجة الأولى يقع تحت مستوى البلد. في الولايات المتحدة، تُمثّل هذه المستويات الإدارية الولايات. لا تعرض كل الدول هذه والمستويات الإدارية. في معظم الحالات، تتوافق الأسماء المختصرة لسمة administrative_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" سوى العناوين التي يتم تحديدها على أنّها تقريبية.
  • ‫extra_computations: استخدِم هذه المَعلمة لتحديد الميزات الإضافية التالية في الاستجابة: لتفعيل العديد من هذه الميزات لطلب البيانات من واجهة برمجة التطبيقات نفسه، يجب تضمين معلَمة extra_computations في الطلب لكل ميزة على سبيل المثال: 
    extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES

في حال توفّر الفلترَين 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 أمتار