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

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

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

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

• 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

ملاحظة: تأكد من عدم وجود مسافة بين قيم خطوط الطول والعرض عند المرور في latlng .

يعرض الاستعلام أعلاه النتيجة التالية:

{
   "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 أمتار

ملاحظة: لا تعرض واجهة برمجة التطبيقات دائمًا علامة زائد الرموز.