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

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

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

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

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

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

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

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

  • ‫language: اللغة التي سيتم عرض النتائج بها
    • اطّلِع على قائمة اللغات المتاحة. تعدّل Google اللغات المتاحة بشكل متكرر، لذا قد لا تكون هذه القائمة شاملة.
    • في حال عدم توفير المَعلمة language، تحاول أداة الترميز الجغرافي استخدام اللغة المفضّلة كما هو محدّد في العنوان Accept-Language أو اللغة الأصلية للنطاق الذي يتم إرسال الطلب منه.
    • تبذل أداة الترميز الجغرافي قصارى جهدها لتوفير عنوان شارع يمكن قراءته لكل من المستخدم والسكان المحليين. لتحقيق هذا الهدف، تعرض الدالة عناوين الشوارع باللغة المحلية، ويتم تحويلها صوتيًا إلى نص يمكن للمستخدم قراءته إذا لزم الأمر، مع مراعاة اللغة المفضّلة. All other addresses are returned in the preferred 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 ضمن استجابة الترميز الجغرافي على رمز Plus Code يقدّم أفضل تقريب لخطوط العرض والطول التي تم البحث عنها. بالإضافة إلى ذلك، تحتوي مصفوفة نتائج JSON في معظم الحالات على نتيجة ترميز جغرافي كاملة مع نوع plus_code وعنوان يحتوي على رمز Plus Code. نضمن أن تكون المسافة بين رمز Plus Code الذي تم فك ترميزه ونقطة الطلب أقل من 10 أمتار.