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

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

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

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

  • 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 Codes

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