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

المطوّرون في المنطقة الاقتصادية الأوروبية

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

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

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

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

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

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

  • language: هي اللغة التي سيتم عرض النتائج بها.
    • اطّلِع على قائمة اللغات المتاحة. تُحدّث Google اللغات المتوافقة بشكل متكرر، لذا قد لا تكون هذه القائمة شاملة.
    • في حال عدم توفير language، يحاول برنامج الترميز الجغرافي استخدام اللغة المفضّلة كما هو محدّد في العنوان Accept-Language، أو اللغة الأصلية للنطاق الذي يتم إرسال الطلب منه.
    • يبذل برنامج الترميز الجغرافي قصارى جهده لتقديم عنوان شارع يمكن قراءته من قِبل المستخدمين والسكان المحليين. لتحقيق هذا الهدف، تعرض الخدمة عناوين الشوارع باللغة المحلية، مع ترجمتها إلى نص يمكن للمستخدم قراءته إذا لزم الأمر، مع مراعاة اللغة المفضّلة. ويتم عرض جميع العناوين الأخرى باللغة المفضّلة. يتم عرض جميع مكوّنات العنوان باللغة نفسها، التي يتم اختيارها من المكوّن الأول.
    • إذا لم يتوفّر اسم باللغة المفضّلة، سيستخدم برنامج الترميز الجغرافي أقرب نتيجة مطابقة.
  • استبدِل region برمز المنطقة المحدّد كنطاق ccTLD (نطاق المستوى الأعلى) المكوّن من حرفين. يمكن أن تؤثّر المَعلمة أيضًا في النتائج استنادًا إلى القانون الساري.
  • result_type: فلتر لنوع واحد أو أكثر من أنواع العناوين، مفصولة بعلامة الشرطة العمودية (|). إذا كانت المَعلمة تحتوي على أنواع عناوين متعددة، تعرض واجهة برمجة التطبيقات جميع العناوين التي تتطابق مع أي من الأنواع. ملاحظة حول المعالجة: لا تعمل المَعلمة result_type على حصر البحث بأنواع العناوين المحدّدة. بل إنّ result_type يعمل كفلتر بعد البحث: تسترد واجهة برمجة التطبيقات جميع النتائج الخاصة بـ latlng المحدّد، ثم تتجاهل النتائج التي لا تتطابق مع أنواع العناوين المحدّدة. القيم التالية متاحة:

    أنواع العناوين وأنواع مكونات العناوين

    تشير مصفوفة types في نص GeocodeResult ضمن الاستجابة إلى نوع العنوان. تشمل أمثلة أنواع العناوين عنوان شارع أو بلدًا أو كيانًا سياسيًا. تشير مصفوفة types في حقل AddressComponents ضمن نص GeocodeResult إلى نوع كل جزء من العنوان. وتشمل الأمثلة رقم الشارع أو البلد.

    قد تتضمّن العناوين أنواعًا متعددة. يمكن اعتبار الأنواع "علامات". على سبيل المثال، يتم وضع علامات من النوعين political وlocality على العديد من المدن.

    تتوفّر الأنواع التالية ويتم عرضها في كل من مصفوفة نوع العنوان ومصفوفة نوع عنصر العنوان:

    نوع العنوان الوصف
    street_address تمثّل هذه السمة عنوان الشارع الدقيق.
    route طريق مسمّى (مثل "الطريق السريع 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 تمثّل هذه السمة نقطة اهتمام محدّدة الاسم. عادةً ما تكون "نقاط الاهتمام" هذه عبارة عن كيانات محلية بارزة لا يمكن تصنيفها بسهولة ضمن فئة أخرى، مثل "مبنى إمباير ستيت" أو "برج إيفل".

    تشير القائمة الفارغة من الأنواع إلى عدم توفّر أي أنواع معروفة لمكوّن العنوان المحدّد (على سبيل المثال، Lieu-dit في فرنسا).

  • 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 في معظم الحالات على نتيجة Geocoding كاملة تتضمّن نوع plus_code وعنوانًا يحتوي على رمز زائد. من المفترض أن تكون المسافة بين رمز Plus Code الذي تم فك ترميزه ونقطة الطلب أقل من 10 أمتار.