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

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

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

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

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

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

    تشير القائمة الفارغة للأنواع إلى عدم توفّر أنواع معروفة لمكوّن العنوان المحدّد (مثل 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 في معظم الحالات على نتيجة كاملة لنظام ترميز المواقع الجغرافية بنوع plus_code وعنوان يحتوي على رمز زائد. يُؤكَّد أنّ المسافة بين رمز Plus Codes الذي تم فك تشفيره ونقطة الطلب ستكون أقل من 10 أمتار.