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

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

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

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

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