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

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

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

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

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

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

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

  • language - اللغة التي يتم عرض النتائج بها.
    • راجِع قائمة اللغات المتوافقة. وغالبًا ما يعدّل محرّك البحث Google اللغات المتوافقة، لذا قد لا تكون هذه القائمة شاملة.
    • وفي حال عدم توفّر السمة language، يحاول محرّر الترميز استخدام اللغة المفضّلة على النحو المحدّد في العنوان Accept-Language أو اللغة الأصلية للنطاق الذي تم إرسال الطلب منه.
    • وتبذل أداة ترميز البيانات قصارى جهدها لتوفير عنوان شارع يمكن للمستخدمين والمستخدمين المحليين قراءته. ولتحقيق هذا الهدف، يتم عرض عناوين الشوارع باللغة المحلية، مع تحويلها إلى نص برمجي يمكن للمستخدم قراءته إذا لزم الأمر، مع ملاحظة اللغة المفضّلة. ويتم عرض جميع العناوين الأخرى باللغة المفضّلة. يتم عرض مكوّنات العنوان باللغة نفسها، والتي يتم اختيارها من المكوّن الأول.
    • وإذا لم يكن الاسم متوفّرًا باللغة المفضّلة، يستخدم برنامج الترميز الجغرافي أقرب محتوى مطابق.
  • result_type: فلتر من نوع واحد أو أكثر من العناوين، مفصول بشرطة (|). إذا كانت المعلّمة تحتوي على أنواع عناوين متعددة، ستعرض واجهة برمجة التطبيقات جميع العناوين التي تطابق أيًا من الأنواع. ملاحظة حول المعالجة: لا تؤدي المعلّمة result_type إلى حظر البحث على أنواع العناوين المحدّدة. بدلاً من ذلك، تعمل result_type كفلتر لما بعد البحث: تعمل واجهة برمجة التطبيقات على جلب جميع النتائج لـ latlng المحددة، ثم تتجاهل تلك النتائج التي لا تتطابق مع أنواع العناوين المحدّدة. القيم التالية متاحة:
    • يشير street_address إلى عنوان شارع دقيق.
    • تشير السمة route إلى مسار محدّد (مثل "US;US 101").
    • تشير علامة intersection إلى تقاطع طرق رئيسي، وعادةً ما يتألف من طريقين رئيسيين.
    • يشير political إلى كيان سياسي. ويشير هذا النوع عادةً إلى مضلّع محدّد للإدارة المدنية.
    • ويشير country إلى الكيان السياسي الوطني، وهو عادةً أعلى نوع ترتيب يعرضه الموقع الجغرافي.
    • يشير administrative_area_level_1 إلى كيان مدني من الدرجة الأولى أسفل مستوى البلد. تقع هذه المستويات الإدارية داخل الولايات المتحدة. يُرجى العِلم أنّه لا يتم عرض هذه المستويات الإدارية في جميع البلدان. في معظم الحالات، ستتطابق الأسماء الإدارية_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" سوى العناوين التي تم تمييزها على أنها تقريبية.

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

يتطابق أداة الترميز العكسي مع الكيانات السياسية (البلدان والمقاطعات والمدن والأحياء) وعناوين الشوارع والرموز البريدية.

في ما يلي القائمة الكاملة لقيم formatted_address التي يعرضها طلب البحث السابق.

"formatted_address" : "277 Bedford Avenue, Brooklyn, NY 11211, USA",
"formatted_address" : "Grand St/Bedford Av, Brooklyn, NY 11211, USA",
"formatted_address" : "Grand St/Bedford Av, Brooklyn, NY 11249, USA",
"formatted_address" : "Bedford Av/Grand St, Brooklyn, NY 11211, USA",
"formatted_address" : "Brooklyn, NY 11211, USA",
"formatted_address" : "Williamsburg, Brooklyn, NY, USA",
"formatted_address" : "Brooklyn, NY, USA",
"formatted_address" : "New York, NY, USA",
"formatted_address" : "New York, USA",
"formatted_address" : "United States",

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

فلترة الموقع الجغرافي العكسي حسب النوع

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