خدمة الترميز الجغرافي

ملاحظة: مكتبات من جهة الخادم

توضّح هذه الصفحة الخدمة التي تعمل من جهة العميل والمتاحة من خلال Maps JavaScript API. إذا أردت استخدام خدمات الويب في "خرائط Google" على خادمك، يمكنك الاطّلاع على برنامج Node.js للعميل الخاص بخدمات "خرائط Google". تقدّم الصفحة المتوفرة على هذا الرابط أيضًا Java Client وPython Client وGo Client لخدمات "خرائط Google".

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

إذا كان عنوان إرسال الفواتير الخاص بك يقع في المنطقة الاقتصادية الأوروبية، ستسري بنود خدمة "منصة خرائط Google" في المنطقة الاقتصادية الأوروبية على استخدامك للخدمات اعتبارًا من 8 تموز (يوليو) 2025. تختلف الوظائف حسب المنطقة. مزيد من المعلومات

نظرة عامة

يمكنك أيضًا الاطّلاع على مرجع Maps JavaScript API: الترميز الجغرافي

الترميز الجغرافي هو عملية تحويل العناوين (مثل "1600 Amphitheatre Parkway, Mountain View, CA") إلى إحداثيات جغرافية (مثل خط العرض 37.423021 وخط الطول -122.083739)، ويمكنك استخدامها لوضع علامات أو تحديد موضع الخريطة.

الترميز الجغرافي العكسي هو عملية تحويل الإحداثيات الجغرافية إلى عنوان يمكن قراءته (راجِع الترميز الجغرافي العكسي (البحث عن العنوان)).

يمكنك أيضًا استخدام أداة الترميز الجغرافي للعثور على عنوان معرّف مكان معيّن.

توفّر Maps JavaScript API فئة Geocoder للترميز الجغرافي وعكس الترميز الجغرافي بشكل ديناميكي من بيانات أدخلها المستخدم. إذا كنت تريد ترميز جغرافي لعناوين ثابتة ومعروفة، يمكنك الاطّلاع على خدمة الويب الخاصة بالترميز الجغرافي.

البدء

قبل استخدام خدمة ترميز المواقع الجغرافية في Maps JavaScript API، تأكَّد أولاً من تفعيل Geocoding API في Google Cloud Console، وذلك في المشروع نفسه الذي أعددته لاستخدام Maps JavaScript API.

للاطّلاع على قائمة واجهات برمجة التطبيقات المفعَّلة، اتّبِع الخطوات التالية:

1. انتقِل إلى وحدة تحكّم Google Cloud.
2. انقر على الزر اختيار مشروع، ثم اختَر المشروع نفسه الذي أعددته لواجهة برمجة التطبيقات JavaScript في "خرائط Google" وانقر على فتح.
3. من قائمة واجهات برمجة التطبيقات في لوحة البيانات، ابحث عن Geocoding API.
4. إذا ظهرت واجهة برمجة التطبيقات في القائمة، يعني ذلك أنّك جاهز. إذا لم تكن واجهة برمجة التطبيقات مدرَجة، فعِّلها باتّباع الخطوات التالية:
   1. في أعلى الصفحة، انقر على تفعيل واجهة برمجة التطبيقات لعرض علامة التبويب المكتبة. بدلاً من ذلك، انقر على المكتبة من القائمة الجانبية اليمنى.
   2. ابحث عن Geocoding API، ثم اختَرها من قائمة النتائج.
   3. انقر على تفعيل. عند انتهاء العملية، ستظهر Geocoding API في قائمة واجهات برمجة التطبيقات ضمن لوحة البيانات.

الأسعار والسياسات

الأسعار

للتعرّف على سياسات الأسعار والاستخدام لخدمة ترميز المواقع الجغرافية في JavaScript، يُرجى الاطّلاع على مقالة الاستخدام والفوترة في Geocoding API.

السياسات

يجب أن يكون استخدامك لخدمة الترميز الجغرافي متوافقًا مع سياسات Geocoding API.

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

الوصول إلى خدمة الترميز الجغرافي غير متزامن، ويتطلّب إجراء مكالمة إلى خادم خارجي. لهذا السبب، تعرض الطريقة geocode وعدًا يتم تنفيذه عند اكتمال الطلب. بعد حلّها، يمكنك استخدام .then() أو await للتعامل مع الردّ.

re

يمكنك الوصول إلى خدمة الترميز الجغرافي في Google Maps API ضمن الرمز البرمجي باستخدام عنصر الإنشاء google.maps.Geocoder. يبدأ الإجراء Geocoder.geocode() طلبًا إلى خدمة الترميز الجغرافي، ويُمرِّر إليها كائنًا حرفيًا GeocoderRequest يحتوي على عبارات الإدخال وطريقة رد الاتصال المطلوب تنفيذها عند تلقّي الردّ.

يحتوي الكائن الحرفي GeocoderRequest على الحقول التالية:

{
 address: string,
 location: LatLng,
 placeId: string,
 bounds: LatLngBounds,
 componentRestrictions: GeocoderComponentRestrictions,
 region: string
}

المَعلمات المطلوبة: يجب تقديم حقل واحد فقط من الحقول التالية:

• address: العنوان الذي تريد ترميزه جغرافيًا.
       أو
  location: تمثّل LatLng (أو LatLngLiteral) الذي تريد الحصول على أقرب عنوان إليه يمكن قراءته. تنفّذ أداة الترميز الجغرافي عملية عكس الترميز الجغرافي. لمزيد من المعلومات، يمكنك الاطّلاع على الترميز الجغرافي العكسي.
       أو
  placeId: معرّف المكان الذي تريد الحصول على أقرب عنوان له يمكن قراءته. مزيد من المعلومات حول استرداد عنوان لمعرّف مكان

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

• bounds: هو LatLngBounds الذي يتم فيه عرض نتائج الترميز الجغرافي بشكل أكثر بروزًا. سيؤثر المَعلمة bounds فقط في النتائج التي يعرضها برنامج الترميز الجغرافي، ولن يقيّدها بالكامل. يمكنك الاطّلاع على مزيد من المعلومات حول تحيّز إطار العرض أدناه.
• componentRestrictions: يُستخدم لحصر النتائج بمنطقة معيّنة. يمكنك الاطّلاع على مزيد من المعلومات حول فلترة المكوّنات أدناه.
• region: رمز المنطقة، ويتم تحديده كعلامة فرعية لمنطقة يونيكود مكوّنة من حرفين (غير رقميين). في معظم الحالات، ترتبط هذه العلامات مباشرةً بقيم مألوفة من حرفين لنطاقات المستوى الأعلى (ccTLD). لن تؤثّر المَعلمة region إلا في نتائج الترميز الجغرافي، ولن تفرض قيودًا كاملة عليها. يمكنك الاطّلاع على مزيد من المعلومات حول تحديد رموز المناطق أدناه.
• extraComputations: القيمة الوحيدة المسموح بها لهذه المَعلمة هي ADDRESS_DESCRIPTORS. لمزيد من التفاصيل، يُرجى الاطّلاع على أوصاف العناوين.
• fulfillOnZeroResults — يجب تنفيذ الوعد عند ظهور الحالة ZERO_RESULT في الرد. قد يكون ذلك مرغوبًا فيه لأنّه حتى في حال عدم توفّر أي نتائج ترميز جغرافي، قد يتم عرض حقول إضافية على مستوى الرد. لمزيد من التفاصيل، اطّلِع على مقالة التنفيذ عند عدم توفّر نتائج.

ردود الترميز الجغرافي

تتطلّب خدمة الترميز الجغرافي طريقة ردّ الاتصال لتنفيذها عند استرداد نتائج أداة الترميز الجغرافي. يجب أن تمرّر دالة الاستدعاء هذه مَعلمتَين للاحتفاظ بالرمز results والرمز status، بهذا الترتيب.

ملاحظة: يحتوي ردّ Geocoding أيضًا على الحقلَين plus_code وaddress_descriptor على مستوى الردّ، ولكن لا يمكن الوصول إليهما من خلال الحقلَين address_descriptor على مستوى الردّ، ولكن لا يمكن الوصول إليهما من خلال وظيفة معاودة الاتصال. بدلاً من ذلك، يجب الوصول إليها من خلال الوعد. يمكنك الاطّلاع على تلبية الطلبات التي لا تعرض أي نتائج لمزيد من التفاصيل.

نتائج الترميز الجغرافي

يمثّل العنصر GeocoderResult نتيجة ترميز جغرافي واحدة. قد يعرض طلب الترميز الجغرافي عناصر نتائج متعددة:

results[]: {
 types[]: string,
 formatted_address: string,
 address_components[]: {
   short_name: string,
   long_name: string,
   postcode_localities[]: string,
   types[]: string
 },
 partial_match: boolean,
 place_id: string,
 postcode_localities[]: string,
 geometry: {
   location: LatLng,
   location_type: GeocoderLocationType
   viewport: LatLngBounds,
   bounds: LatLngBounds
 }
}

في ما يلي شرح لهذه الحقول:

• ‫types[] هي مصفوفة تشير إلى نوع العنوان للنتيجة التي تم إرجاعها. تحتوي هذه المصفوفة على مجموعة من صفر أو أكثر من العلامات التي تحدّد نوع الميزة المعروضة في النتيجة. على سبيل المثال، تعرض عملية الترميز الجغرافي لـ "القاهرة" "الموقع الجغرافي" الذي يشير إلى أنّ "القاهرة" هي مدينة، وتعرض أيضًا "سياسي" الذي يشير إلى أنّها كيان سياسي. يمكنك الاطّلاع على مزيد من المعلومات حول أنواع العناوين وأنواع مكوّنات العناوين أدناه.
• ‫formatted_address هي سلسلة تحتوي على العنوان الذي يمكن قراءته لهذا الموقع الجغرافي.

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

  يتألف العنوان المنسّق منطقيًا من مكوّن واحد أو أكثر من مكوّنات العنوان. على سبيل المثال، يتألف العنوان "111 8th Avenue, New York, NY" من المكوّنات التالية: "111" (رقم الشارع) و"8th Avenue" (الطريق) و"New York" (المدينة) و "NY" (ولاية الولايات المتحدة).

  لا تحلّل العنوان المنسَّق آليًا. بدلاً من ذلك، عليك استخدام مكوّنات العنوان الفردية التي تتضمّنها استجابة واجهة برمجة التطبيقات بالإضافة إلى حقل العنوان المنسّق.

• ‫address_components[] هي مصفوفة تحتوي على المكوّنات المنفصلة التي تنطبق على هذا العنوان.

  يتضمّن كل مكوّن من مكونات العنوان عادةً الحقول التالية:

  • types[] هي مصفوفة تشير إلى نوع مكوّن العنوان. قد يحتوي مكوّن العنوان على مصفوفة أنواع فارغة عندما لا تتوفّر أنواع معروفة لمكوّن العنوان هذا. قد تضيف واجهة برمجة التطبيقات قيمًا جديدة للنوع حسب الحاجة. لمزيد من المعلومات، يُرجى الاطّلاع على أنواع العناوين وأنواع عناصر العناوين.
  • ‫long_name هو الوصف النصي الكامل أو اسم مكوّن العنوان الذي يعرضه Geocoder.
  • ‫short_name هي اسم نصي مختصر لمكوّن العنوان، إذا كان متاحًا. على سبيل المثال، قد يتضمّن أحد عناصر العنوان الخاص بولاية ألاسكا long_name بقيمة "ألاسكا" وshort_name بقيمة "AK" باستخدام الاختصار البريدي المكوّن من حرفين.

  يُرجى ملاحظة الحقائق التالية حول مصفوفة address_components[]:

  • قد تحتوي مصفوفة مكوّنات العنوان على مكوّنات أكثر من formatted_address.
  • لا تتضمّن المصفوفة بالضرورة جميع الكيانات السياسية التي تحتوي على عنوان، باستثناء تلك المضمّنة في formatted_address. لاسترداد جميع الكيانات السياسية التي تحتوي على عنوان معيّن، عليك استخدام الترميز الجغرافي العكسي، مع تمرير خط العرض/خط الطول الخاصين بالعنوان كمَعلمة للطلب.
  • لا نضمن أن يظل تنسيق الرد كما هو بين الطلبات. على وجه الخصوص، يختلف عدد address_components استنادًا إلى العنوان المطلوب، ويمكن أن يتغيّر بمرور الوقت بالنسبة إلى العنوان نفسه. يمكن أن يغيّر أحد المكوّنات موضعه في المصفوفة. يمكن أن يتغيّر نوع المكوّن. قد لا يتضمّن الردّ اللاحق مكوّنًا معيّنًا.

  يمكنك الاطّلاع على مزيد من المعلومات حول أنواع العناوين وأنواع مكوّنات العناوين أدناه.

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

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

• place_idهو معرّف فريد لمكان معيّن، ويمكن استخدامه مع واجهات برمجة تطبيقات أخرى من Google. على سبيل المثال، يمكنك استخدام place_id مع مكتبة Google Places API للحصول على تفاصيل حول مؤسسة محلية، مثل رقم الهاتف وساعات العمل ومراجعات المستخدمين وغير ذلك. اطّلِع على نظرة عامة على معرّف المكان.
• postcode_localities[] هي مصفوفة تشير إلى جميع المواقع الجغرافية المضمّنة في رمز بريدي، ولا تظهر إلا عندما تكون النتيجة رمزًا بريديًا يحتوي على مواقع جغرافية متعددة.

• يتضمّن geometry المعلومات التالية:

  • يحتوي location على قيمة خطوط الطول والعرض التي تم ترميزها جغرافيًا. يُرجى العِلم أنّنا نعرض هذا الموقع الجغرافي ككائن LatLng، وليس كسلسلة منسَّقة.
  • location_type تخزِّن بيانات إضافية حول الموقع الجغرافي المحدّد. في ما يلي القيم المتوافقة:
    • يشير ROOFTOP إلى أنّ النتيجة التي تم عرضها تعكس رمزًا جغرافيًا دقيقًا.
    • يشير RANGE_INTERPOLATED إلى أنّ النتيجة المعروضة تعكس قيمة تقريبية (عادةً على طريق) تم استيفاؤها بين نقطتين دقيقتين (مثل التقاطعات). يتم عرض النتائج المستنبطة بشكل عام عندما لا تتوفّر رموز جغرافية على مستوى المبنى لعنوان شارع.
    • يشير الرمز GEOMETRIC_CENTER إلى أنّ النتيجة المعروضة هي المركز الهندسي لنتيجة، مثل خط متعدد الأضلاع (على سبيل المثال، شارع) أو مضلّع (منطقة).
    • يشير الرمز APPROXIMATE إلى أنّ النتيجة التي تم إرجاعها تقريبية.
  
  
  • يخزّن viewport إطار العرض المقترَح للنتيجة التي تم عرضها.
  • يخزّن bounds (يتم عرضه بشكل اختياري) LatLngBounds الذي يمكن أن يحتوي بالكامل على النتيجة المعروضة. يُرجى العِلم أنّ هذه الحدود قد لا تتطابق مع إطار العرض المقترَح. (على سبيل المثال، تشمل سان فرانسيسكو جزر فارالون التي تُعدّ جزءًا من المدينة من الناحية الفنية، ولكن لا يجب عرضها في إطار العرض.)

تعرض خدمة الترميز الجغرافي العناوين باستخدام إعدادات اللغة المفضّلة في المتصفّح أو اللغة المحدّدة عند تحميل JavaScript لواجهة برمجة التطبيقات باستخدام المَعلمة language. (لمزيد من المعلومات، راجِع مقالة التوطين).

أنواع العناوين وأنواع مكوّنات العناوين

يشير مصفوفة types[] في GeocoderResult في الرد إلى نوع العنوان. تشمل أمثلة أنواع العناوين عنوان شارع أو بلدًا أو كيانًا سياسيًا. تشير مصفوفة types في GeocoderAddressComponent إلى نوع كل جزء من العنوان. وتشمل الأمثلة رقم الشارع أو البلد.

قد تتضمّن العناوين أنواعًا متعددة. يمكن اعتبار الأنواع "علامات". على سبيل المثال، يتم وضع علامات من النوعين political وlocality على العديد من المدن.

تتوفّر الأنواع التالية ويتم عرضها في كل من مصفوفة نوع العنوان ومصفوفة نوع عنصر العنوان:

نوع العنوان	الوصف
street_address	تمثّل هذه السمة عنوان الشارع الدقيق.
route	طريق مسمّى (مثل "الطريق السريع 101 في الولايات المتحدة")
intersection	تقاطع رئيسي، عادةً ما يكون بين طريقَين رئيسيَّين
political	كيان سياسي يشير هذا النوع عادةً إلى مضلّع تابع لإحدى الإدارات المدنية.
country	تمثّل هذه السمة الكيان السياسي الوطني، وهي عادةً النوع الأعلى ترتيبًا الذي يعرضه Geocoder.
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 كبديل لعناوين الشوارع في الأماكن التي لا تتوفّر فيها (حيث لا يتم ترقيم المباني أو تسمية الشوارع). لمزيد من التفاصيل، يُرجى الانتقال إلى https://plus.codes.
postal_code	الرمز البريدي المستخدَم في عنونة البريد داخل البلد
natural_feature	معلَم طبيعي بارز
airport	مطار
park	تمثّل هذه السمة حديقة تحمل اسمًا.
point_of_interest	تمثّل هذه السمة نقطة اهتمام محدّدة الاسم. عادةً ما تكون "نقاط الاهتمام" هذه عبارة عن كيانات محلية بارزة لا يمكن تصنيفها بسهولة ضمن فئة أخرى، مثل "مبنى إمباير ستيت" أو "برج إيفل".

تشير القائمة الفارغة من الأنواع إلى عدم توفّر أي أنواع معروفة لمكوّن العنوان المحدّد (على سبيل المثال، Lieu-dit في فرنسا).

بالإضافة إلى ما سبق، قد تتضمّن مكوّنات العنوان الأنواع أدناه.

ملاحظة: هذه القائمة ليست شاملة، وهي عرضة للتغيير.

بالإضافة إلى ما سبق، قد تتضمّن مكوّنات العنوان الأنواع المدرَجة أدناه.

ملاحظة: هذه القائمة ليست شاملة، وهي عرضة للتغيير.

نوع مكوّن العنوان	الوصف
floor	تمثّل هذه السمة طابق عنوان المبنى.
establishment	عادةً ما يكون مكانًا لم يتم تصنيفه بعد.
landmark	مكان قريب يُستخدم كمرجع للمساعدة في التنقّل
point_of_interest	تمثّل هذه السمة نقطة اهتمام محدّدة الاسم.
parking	موقف أو مرآب للسيارات
post_box	صندوق بريد معيّن
postal_town	هي مجموعة من المناطق الجغرافية، مثل locality وsublocality، تُستخدَم لعناوين المراسلة في بعض البلدان.
room	غرفة في عنوان مبنى
street_number	تمثّل هذه السمة رقم الشارع الدقيق.
bus_station وtrain_station وtransit_station	الموقع الجغرافي لموقف حافلة أو قطار أو وسيلة نقل عام

رموز الحالة

قد يعرض الرمز status إحدى القيم التالية:

• يشير الرمز "OK" إلى أنّه لم تحدث أي أخطاء، وتم تحليل العنوان بنجاح وعرض رمز جغرافي واحد على الأقل.
• يشير الرمز "ZERO_RESULTS" إلى أنّه تمّت عملية الترميز الجغرافي بنجاح ولكن لم يتم عرض أي نتائج. قد يحدث ذلك إذا تم تمرير address غير موجود إلى أداة الترميز الجغرافي.
• يشير الرمز "OVER_QUERY_LIMIT" إلى أنّك تجاوزت حصتك.
• يشير الرمز "REQUEST_DENIED" إلى أنّه تم رفض طلبك. لا يُسمح لصفحة الويب باستخدام أداة الترميز الجغرافي.
• يشير "INVALID_REQUEST" بشكل عام إلى أنّ طلب البحث (address أو components أو latlng) غير متوفّر.
• يشير الرمز "UNKNOWN_ERROR" إلى أنّه تعذّر معالجة الطلب بسبب حدوث خطأ في الخادم. قد ينجح الطلب إذا أعدت المحاولة.
• يشير الرمز "ERROR" إلى أنّ مهلة الطلب قد انتهت أو حدثت مشكلة في الاتصال بخوادم Google. قد ينجح الطلب إذا أعدت المحاولة.

مثال على الترميز الجغرافي

يوضّح المثال التالي عملية الترميز الجغرافي لعنوان ووضع علامة في قيم خطوط الطول والعرض التي تم عرضها. تتم معالجة نتيجة الترميز الجغرافي باستخدام وعد. انقر على أي مكان على الخريطة لترميز العنوان جغرافيًا في ذلك الموقع.

TypeScript

async function geocode(request: google.maps.GeocoderRequest) {
    clear();
    const { LatLng } = await google.maps.importLibrary('core');

    try {
        const response = await geocoder.geocode(request);
        const { results } = response;

        innerMap.setCenter(results[0].geometry.location);
        marker.position = new LatLng(results[0].geometry.location);
        mapElement.append(marker);
        responseDiv.style.display = 'block';
        responsePre.innerText = JSON.stringify(response, null, 2);
        return results;
    } catch (e) {
        alert(
            'Geocode was not successful for the following reason: ' + String(e)
        );
    }
}
index.ts

ملاحظة: يُرجى الاطّلاع على الدليل حول استخدام TypeScript و"خرائط Google".

JavaScript

async function geocode(request) {
    clear();
    const { LatLng } = await google.maps.importLibrary('core');

    try {
        const response = await geocoder.geocode(request);
        const { results } = response;

        innerMap.setCenter(results[0].geometry.location);
        marker.position = new LatLng(results[0].geometry.location);
        mapElement.append(marker);
        responseDiv.style.display = 'block';
        responsePre.innerText = JSON.stringify(response, null, 2);
        return results;
    } catch (e) {
        alert(
            'Geocode was not successful for the following reason: ' + String(e)
        );
    }
}
index.js

الاطّلاع على المثال الكامل

تحسين إطار العرض

يمكنك توجيه "خدمة الترميز الجغرافي" لتفضيل النتائج ضمن إطار عرض معيّن (يتم التعبير عنه كمربع محيط). يمكنك إجراء ذلك من خلال ضبط المَعلمة bounds ضمن الحرفية الخاصة بالكائن GeocoderRequest لتحديد حدود إطار العرض هذا. يُرجى العِلم أنّ التحيز يفضّل النتائج ضمن الحدود فقط، وإذا كانت هناك نتائج أكثر صلة خارج هذه الحدود، قد يتم تضمينها.

على سبيل المثال، يعرض الرمز الجغرافي الخاص بـ "Winnetka" عادةً هذه الضاحية من شيكاغو:

{
  "types":["locality","political"],
  "formatted_address":"Winnetka, IL, USA",
  "address_components":[{
    "long_name":"Winnetka",
    "short_name":"Winnetka",
    "types":["locality","political"]
  },{
    "long_name":"Illinois",
    "short_name":"IL",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"United States",
    "short_name":"US",
    "types":["country","political"]
  }],
  "geometry":{
    "location":[ -87.7417070, 42.1083080],
    "location_type":"APPROXIMATE"
  },
  "place_id": "ChIJW8Va5TnED4gRY91Ng47qy3Q"
}

ومع ذلك، يؤدي تحديد المَعلمة bounds التي تحدد المربع المحيط لمنطقة "سان فرناندو فالي" في لوس أنجلوس إلى أن يعرض رمز الموقع الجغرافي الحي المسمى "وينتكا" في ذلك الموقع الجغرافي:

{
  "types":["sublocality","political"],
  "formatted_address":"Winnetka, California, USA",
  "address_components":[{
    "long_name":"Winnetka",
    "short_name":"Winnetka",
    "types":["sublocality","political"]
  },{
    "long_name":"Los Angeles",
    "short_name":"Los Angeles",
    "types":["administrative_area_level_3","political"]
  },{
    "long_name":"Los Angeles",
    "short_name":"Los Angeles",
    "types":["administrative_area_level_2","political"]
  },{
    "long_name":"California",
    "short_name":"CA",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"United States",
    "short_name":"US",
    "types":["country","political"]
  }],
  "geometry":{
    "location": [34.213171,-118.571022],
    "location_type":"APPROXIMATE"
  },
  "place_id": "ChIJ0fd4S_KbwoAR2hRDrsr3HmQ"
}

تفضيل رمز المنطقة

يمكنك ضبط خدمة الترميز الجغرافي لعرض نتائج متحيزة لمنطقة معيّنة بشكل صريح باستخدام المَعلمة region. تتلقّى هذه المَعلمة رمز منطقة، ويتم تحديده كعلامة فرعية للمنطقة بتنسيق Unicode تتألف من حرفَين (غير رقميين). تتطابق هذه العلامات مباشرةً مع قيم ccTLD المألوفة (نطاق المستوى الأعلى) المكوّنة من حرفين، مثل "uk" في "co.uk" مثلاً. في بعض الحالات، تتيح العلامة region أيضًا رموز ISO-3166-1 التي تختلف أحيانًا عن قيم نطاقات المستوى الأعلى لرموز البلدان (مثل "GB" لـ "بريطانيا العظمى").

عند استخدام المَعلمة region:

• حدِّد بلدًا أو منطقة واحدة فقط. يتم تجاهل القيم المتعددة، وقد يؤدي ذلك إلى تعذّر تنفيذ الطلب.
• استخدِم علامات فرعية للمناطق تتألف من حرفين فقط (تنسيق Unicode CLDR). وستؤدي جميع الإدخالات الأخرى إلى حدوث أخطاء.
• لا تتوفّر هذه الميزة إلا في البلدان والمناطق المدرَجة في تفاصيل تغطية "منصة خرائط Google".

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

على سبيل المثال، يعرض الرمز الجغرافي الخاص بـ "توليدو" النتيجة التالية، لأنّ النطاق التلقائي لخدمة الترميز الجغرافي مضبوط على الولايات المتحدة:

{
  "types":["locality","political"],
  "formatted_address":"Toledo, OH, USA",
  "address_components":[{
    "long_name":"Toledo",
    "short_name":"Toledo",
    "types":["locality","political"]
  },{
    "long_name":"Ohio",
    "short_name":"OH",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"United States",
    "short_name":"US",
    "types":["country","political"]
  }],
  "place_id": "ChIJeU4e_C2HO4gRRcM6RZ_IPHw"
}

سيؤدي البحث عن رمز جغرافي لمدينة "طليطلة" مع ضبط الحقل region على 'es' (إسبانيا) إلى عرض المدينة الإسبانية:

{
  "types":["locality","political"],
  "formatted_address":"Toledo, España",
  "address_components":[{
    "long_name":"Toledo",
    "short_name":"Toledo",
    "types":["locality","political"]
  },{
    "long_name":"Toledo",
    "short_name":"TO",
    "types":["administrative_area_level_2","political"]
  },{
    "long_name":"Castilla-La Mancha",
    "short_name":"CM",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"España",
    "short_name":"ES",
    "types":["country","political"]
  }],
  "place_id": "ChIJ8f21C60Lag0R_q11auhbf8Y"
}

فلترة المكوّنات

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

لا يعرض برنامج الترميز الجغرافي سوى النتائج التي تتطابق مع جميع فلاتر المكوّنات. أي أنّه يقيّم مواصفات الفلتر على أنّها "و"، وليس "أو".

يتألف فلتر المكوّنات من عنصر واحد أو أكثر من العناصر التالية:

• يمثّل route الاسم الطويل أو الاسم المختصر لمسار.
• تتم مطابقة locality مع أنواع المواقع المحلية والمواقع الفرعية.
• administrativeArea تطابق جميع مستويات المنطقة الإدارية.
• تطابق postalCode الرموز البريدية وبادئات الرموز البريدية
• تطابق country اسم بلد أو رمز بلد مكوّنًا من حرفَين وفقًا لمعيار ISO 3166-1. ملاحظة: تتّبع واجهة برمجة التطبيقات معيار ISO في تحديد البلدان، وتعمل الفلترة بشكل أفضل عند استخدام رمز ISO الخاص بالبلد.

يوضّح المثال التالي كيفية استخدام المَعلمة componentRestrictions للفلتَرة حسب country وpostalCode:

async function codeAddress(request: google.maps.GeocoderRequest) {
    clear();
    geocoder.geocode({
        componentRestrictions: {
            country: 'AU',
            postalCode: '2000'
        }
    })
    .then((result) => {
        const { results } = result;
        innerMap.setCenter(results[0].geometry.location);
        let marker = new google.maps.marker.AdvancedMarkerElement({
            map: innerMap,
            position: results[0].geometry.location
        });
    })
    .catch((e) => {
        alert('Geocode was not successful for the following reason: ' + e);
    });
};

الاستيفاء عند عدم توفّر نتائج

بالنسبة إلى الترميز الجغرافي العكسي، يتم رفض الوعد تلقائيًا عند status=ZERO_RESULTS. ومع ذلك، قد تظل حقول مستوى الاستجابة الإضافية plus_code وaddress_descriptor معبّأة في هذه الحالة. إذا تمّ تقديم القيمة "صحيح" للمَعلمة fulfillOnZeroResults، سيتمّ ملء هذا الحقل في هذه الحالة. إذا تم توفير القيمة "صحيح" للمَعلمة fulfillOnZeroResults، لن يتم تجاهل الوعد ويمكن الوصول إلى هذه الحقول الإضافية من الوعد إذا كانت متوفرة.

في ما يلي مثال على هذا السلوك لخطوط الطول والعرض في القارة القطبية الجنوبية. على الرغم من عدم توفّر نتائج لعكس الترميز الجغرافي، سيظل بإمكاننا إرسال رمز Plus Codes في العمليّة غير المكتملة إذا ضبطنا fulfillOnZeroResults=true.

function addressDescriptorReverseGeocoding() {
  var latlng = new google.maps.LatLng(-75.290330, 38.653861);
  geocoder
    .geocode({
      'location': latlng,
      'fulfillOnZeroResults': true,
    })
    .then((response) => {
      console.log(response.plus_code);
    })
    .catch((error) => {
      window.alert(`Error: ${error}`);
    });
}

واصفات العناوين

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

يمكن تفعيل أوصاف العناوين من خلال استخدام المَعلمة extraComputations. أدرِج extra_computations=ADDRESS_DESCRIPTORS في طلب ترميز جغرافي أو طلب عكس الترميز الجغرافي أو طلب ترميز جغرافي للأماكن لتلقّي أوصاف العناوين في ردّك.

مثال على الترميز الجغرافي للأماكن

يحتوي الاستعلام التالي على عنوان مكان في دلهي.

function addressDescriptorPlaceIdLookup() {
  geocoder.geocode({
  geocoder.geocode({
    'placeId': 'ChIJyxAX8Bj9DDkRgBfAnBYa66Q',
    'extraComputations': ['ADDRESS_DESCRIPTORS']
    }, function(results, status) {
    if (status == 'OK') {
      console.log(results[0].address_descriptor);
    } else {
      window.alert('Geocode was not successful for the following reason: ' + status);
    }
  });
}

ملاحظة: لا تتوافق بعض الأماكن مع أدوات وصف العناوين. لن تتلقّى الأماكن الكبيرة جدًا (مثل المطارات) أو المناطق (مثل منطقة بريدية) أبدًا وصفًا للعنوان.

مثال على عكس الترميز الجغرافي

يحتوي طلب البحث التالي على قيمة خط الطول/العرض لموقع جغرافي في دلهي.

    function addressDescriptorReverseGeocoding() {
      var latlng = new google.maps.LatLng(28.640964,77.235875);
      geocoder
        .geocode({
          'location': latlng,
          'extraComputations': ["ADDRESS_DESCRIPTORS"],
        })
        .then((response) => {
          console.log(response.address_descriptor);
        })
        .catch((error) => {
          window.alert(`Error`);
        });
    }
  

ملاحظة: يتضمّن الترميز الجغرافي العكسي واصف عنوان واحدًا على مستوى الردّ. ستتلقّى خدمة الترميز الجغرافي وخدمة الترميز الجغرافي للأماكن واصف عنوان لكل نتيجة متوافقة في الرد

مثال على واصف العنوان

في ما يلي مثال address_descriptor.

  {
    "address_descriptor" : {
       "areas" : [
          {
             "containment" : "OUTSKIRTS",
             "display_name" : {
                "language_code" : "en",
                "text" : "Turkman Gate"
             },
             "place_id" : "ChIJ_7LLvyb9DDkRMKKxP9YyXgs"
          },
          {
             "containment" : "OUTSKIRTS",
             "display_name" : {
                "language_code" : "en",
                "text" : "Chandni Chowk"
             },
             "place_id" : "ChIJWcXciBr9DDkRUb4dCDykTwI"
          },
          {
             "containment" : "NEAR",
             "display_name" : {
                "language_code" : "en",
                "text" : "Katar Ganj"
             },
             "place_id" : "ChIJH3cWUyH9DDkRaw-9CjvcRvY"
          }
       ],
       "landmarks" : [
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "Delite Cinema"
             },
             "straight_line_distance_meters" : 29.9306755065918,
             "place_id" : "ChIJLfiYDCT9DDkROoEa7NdupUM",
             "travel_distance_meters" : 418.7794799804688,
             "spatial_relationship" : "ACROSS_THE_ROAD",
             "types" : [ "establishment", "movie_theater", "point_of_interest" ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "YES Bank"
             },
             "straight_line_distance_meters" : 66.83731079101562,
             "place_id" : "ChIJFYHM3yb9DDkRRKGkZl2mpSQ",
             "travel_distance_meters" : 489.0340270996094,
             "spatial_relationship" : "DOWN_THE_ROAD",
             "types" : [ "bank", "establishment", "finance", "point_of_interest" ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "UCO Bank"
             },
             "straight_line_distance_meters" : 25.38849639892578,
             "place_id" : "ChIJ-c6_wCb9DDkRjIk1LeqRtGM",
             "travel_distance_meters" : 403.2246398925781,
             "spatial_relationship" : "ACROSS_THE_ROAD",
             "types" : [ "atm", "bank", "establishment", "finance", "point_of_interest" ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "Delhi By Cycle Meeting Point"
             },
             "straight_line_distance_meters" : 44.02867126464844,
             "place_id" : "ChIJNxVfkSb9DDkRJD22l-eGFdM",
             "travel_distance_meters" : 97.41281890869141,
             "spatial_relationship" : "AROUND_THE_CORNER",
             "types" : [
                "establishment",
                "point_of_interest",
                "tourist_attraction",
                "travel_agency"
             ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "Axis Bank Branch"
             },
             "straight_line_distance_meters" : 102.3495178222656,
             "place_id" : "ChIJr3uaDCT9DDkR8roHTVSn1x4",
             "travel_distance_meters" : 330.8566284179688,
             "spatial_relationship" : "DOWN_THE_ROAD",
             "types" : [ "bank", "establishment", "finance", "point_of_interest" ]
          }
       ]
    }
  }

تتضمّن كل كائن address_descriptor مصفوفتَين: landmarks وareas. تحتوي مصفوفة landmarks على ما يصل إلى 5 نتائج مرتبة حسب مدى الصلة بالموضوع، مع الأخذ في الاعتبار القرب من الإحداثيات المطلوبة ومدى انتشار المعلم وإمكانية رؤيته. تحتوي كل نتيجة خاصة بمعلم بارز على القيم التالية:

• ‫place_id هو رقم تعريف المكان الخاص بنتيجة المعالم. اطّلِع على نظرة عامة حول معرّف المكان.
• ‫display_name هو الاسم المعروض للمعلم ويتضمّن language_code وtext.
• ‫straight_line_distance_meters هي المسافة بين نقطتين بالأمتار بين الإحداثيات المُدخَلة ونتيجة المعالم.
• ‫travel_distance_meters هي المسافة بالأمتار التي تم قطعها باستخدام شبكة الطرق (مع تجاهل القيود المفروضة على الطرق) بين الإحداثيات المُدخَلة ونتيجة المعالم.
• spatial_relationship هي العلاقة المقدَّرة بين الإحداثيات المُدخَلة ونتيجة المعالم:
• "NEAR" هي العلاقة التلقائية عندما لا ينطبق أي مما يلي.
• "WITHIN" عندما تكون إحداثيات الإدخال مضمّنة في حدود البنية المرتبطة بالمعلم.
• "BESIDE" عندما تكون الإحداثية المُدخَلة مجاورة مباشرةً للمعلم أو نقطة الوصول إليه
• "ACROSS_THE_ROAD" عندما تكون إحداثيات الإدخال معاكسة تمامًا للمعلم على الجانب الآخر من الطريق
• ‫"DOWN_THE_ROAD" عندما تكون الإحداثية المُدخَلة على المسار نفسه الذي يقع عليه المعلم، ولكن ليس "BESIDES" أو "ACROSS_THE_ROAD"
• "AROUND_THE_CORNER" عندما تكون إحداثيات الإدخال على طول مسار عمودي على المعلم (يقتصر على انعطاف واحد)
• "BEHIND" عندما تكون إحداثيات الإدخال قريبة مكانيًا من المعلم، ولكنها بعيدة عن نقطة الوصول إليه
• types هي أنواع الأماكن الخاصة بالمعلم.

يحتوي العنصر areas على ما يصل إلى 3 ردود ويقتصر على الأماكن التي تمثّل مناطق صغيرة، مثل الأحياء والمناطق الفرعية والمجمّعات الكبيرة. يتم أولاً إدراج المناطق التي تحتوي على الإحداثيات المطلوبة، ثم ترتيبها من الأصغر إلى الأكبر. يحتوي كل areas نتيجة على القيم التالية:

• ‫place_id هو رقم تعريف المكان الخاص بنتيجة المناطق. اطّلِع على نظرة عامة حول معرّف المكان.
• ‫display_name هو الاسم المعروض للمنطقة ويتضمّن language_code وtext.
• ‫containment هي علاقة الاحتواء المقدَّرة بين الإحداثيات المُدخَلة ونتائج المناطق:
• "NEAR" هي العلاقة التلقائية عندما لا ينطبق أي مما يلي.
• ‫"WITHIN" عندما تكون الإحداثيات المُدخَلة قريبة من مركز المنطقة
• "OUTSKIRTS" عندما تكون الإحداثية المُدخَلة قريبة من حافة المنطقة

تغطية واصفات العناوين

تتوفّر واصفات العناوين في "إحصاءات Google" في الهند. لا تتكبّد أي تكلفة إضافية عند استخدام واصفات العناوين في الهند، ويتم احتساب الاستخدام ضمن رمز التخزين التعريفي الأساسي لخدمة الترميز الجغرافي (الهند) الحالي.

الملاحظات

تتوفّر هذه الميزة في جميع المناطق. وهي متاحة للجمهور العام في الهند، وفي مرحلة الإطلاق التجريبي لمرحلة ما قبل التوفّر للجمهور العام في جميع المناطق الأخرى. يسرّنا تلقّي ملاحظاتك:

• إذا كانت لديك مشاكل متعلّقة بمنطقة الهند فقط، يُرجى التواصل مع فريق الدعم.
• لإرسال ملاحظات حول الإصدار التجريبي، يُرجى مراسلتنا عبر البريد الإلكتروني على [e-mail].
• يمكنك الاطّلاع على تفاصيل تغطية أوصاف العناوين لمزيد من المعلومات.

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

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

بدلاً من تقديم address نصي، قدِّم زوج خط عرض/خط طول مفصولاً بفاصلة في المَعلمة location.

ملاحظة: إذا تضمّنت المَعلمة componentRestrictions في الطلب، سيتم تجاهل المَعلمة location.

يوضح المثال التالي كيفية تحويل قيمة خط العرض/خط الطول إلى رمز جغرافي وتوسيط الخريطة في ذلك الموقع الجغرافي، ما يؤدي إلى ظهور نافذة معلومات تتضمّن العنوان المنسّق. انقر على أي مكان على الخريطة لترميز الموقع الجغرافي أو إدخال الإحداثيات الخاصة بك.

TypeScript

let marker: google.maps.marker.AdvancedMarkerElement;

async function init() {
    //  Request the needed libraries.
    const [{ InfoWindow }, { Geocoder }, { AdvancedMarkerElement }] =
        await Promise.all([
            google.maps.importLibrary('maps'),
            google.maps.importLibrary('geocoding'),
            google.maps.importLibrary('marker'),
        ]);

    // Get the gmp-map element.
    const mapElement = document.querySelector('gmp-map')!;

    // Get the inner map.
    const innerMap = mapElement.innerMap;

    // Get the latlng input box.
    const latLngQuery = document.getElementById('latlng') as HTMLInputElement;

    // Get the submit button.
    const submitButton = document.getElementById('submit')!;

    // Set the cursor to crosshair.
    innerMap.setOptions({
        draggableCursor: 'crosshair',
        zoom: 13,
        mapTypeControl: false,
    });

    // Create a marker for re-use.
    marker = new AdvancedMarkerElement({
        map: innerMap,
    });

    marker.anchorTop = '40px';

    const geocoder = new Geocoder();
    const infoWindow = new InfoWindow();

    // Add a click event listener to the submit button.
    submitButton.addEventListener('click', () => {
        void geocodeLatLng(geocoder, innerMap, infoWindow);
    });

    // Add a click event listener to the map.
    innerMap.addListener('click', (event: google.maps.MapMouseEvent) => {
        if (event.latLng) {
            latLngQuery.value = `${event.latLng.lat()}, ${event.latLng.lng()}`;
            void geocodeLatLng(geocoder, innerMap, infoWindow);
        }
    });

    // Make an initial request upon loading.
    void geocodeLatLng(geocoder, innerMap, infoWindow);
}

async function geocodeLatLng(
    geocoder: google.maps.Geocoder,
    map: google.maps.Map,
    infoWindow: google.maps.InfoWindow
) {
    const input = (document.getElementById('latlng') as HTMLInputElement).value;
    const latlngStr = input.split(',', 2);
    const latlng = {
        lat: parseFloat(latlngStr[0]),
        lng: parseFloat(latlngStr[1]),
    };

    try {
        const { results } = await geocoder.geocode({ location: latlng });

        if (results[0]) {
            marker.position = latlng;
            map.setCenter(latlng);
            infoWindow.setContent(results[0].formatted_address);
            infoWindow.open(map, marker);
        } else {
            window.alert('No results found');
        }
    } catch (e) {
        window.alert('Geocoder failed due to: ' + String(e));
    }
}

void init();
index.ts

ملاحظة: يمكنك الاطّلاع على الدليل حول استخدام TypeScript و"خرائط Google".

JavaScript

let marker;

async function init() {
    //  Request the needed libraries.
    const [{ InfoWindow }, { Geocoder }, { AdvancedMarkerElement }] =
        await Promise.all([
            google.maps.importLibrary('maps'),
            google.maps.importLibrary('geocoding'),
            google.maps.importLibrary('marker'),
        ]);

    // Get the gmp-map element.
    const mapElement = document.querySelector('gmp-map');

    // Get the inner map.
    const innerMap = mapElement.innerMap;

    // Get the latlng input box.
    const latLngQuery = document.getElementById('latlng');

    // Get the submit button.
    const submitButton = document.getElementById('submit');

    // Set the cursor to crosshair.
    innerMap.setOptions({
        draggableCursor: 'crosshair',
        zoom: 13,
        mapTypeControl: false,
    });

    // Create a marker for re-use.
    marker = new AdvancedMarkerElement({
        map: innerMap,
    });

    marker.anchorTop = '40px';

    const geocoder = new Geocoder();
    const infoWindow = new InfoWindow();

    // Add a click event listener to the submit button.
    submitButton.addEventListener('click', () => {
        void geocodeLatLng(geocoder, innerMap, infoWindow);
    });

    // Add a click event listener to the map.
    innerMap.addListener('click', (event) => {
        if (event.latLng) {
            latLngQuery.value = `${event.latLng.lat()}, ${event.latLng.lng()}`;
            void geocodeLatLng(geocoder, innerMap, infoWindow);
        }
    });

    // Make an initial request upon loading.
    void geocodeLatLng(geocoder, innerMap, infoWindow);
}

async function geocodeLatLng(geocoder, map, infoWindow) {
    const input = document.getElementById('latlng').value;
    const latlngStr = input.split(',', 2);
    const latlng = {
        lat: parseFloat(latlngStr[0]),
        lng: parseFloat(latlngStr[1]),
    };

    try {
        const { results } = await geocoder.geocode({ location: latlng });

        if (results[0]) {
            marker.position = latlng;
            map.setCenter(latlng);
            infoWindow.setContent(results[0].formatted_address);
            infoWindow.open(map, marker);
        } else {
            window.alert('No results found');
        }
    } catch (e) {
        window.alert('Geocoder failed due to: ' + String(e));
    }
}

void init();
index.js

CSS

/*
* Always set the map height explicitly to define the size of the div element
* that contains the map.
*/
gmp-map {
    height: 100%;
}

/*
* Optional: Makes the sample page fill the window.
*/
html,
body {
    height: 100%;
    margin: 0;
    padding: 0;
    font-family: Roboto, sans-serif;
}

#floating-panel {
    background-color: #fff;
    border-radius: 5px;
    box-shadow: rgba(0, 0, 0, 0.35) 0px 5px 15px;
    margin: 10px;
    padding: 10px;
    font-family: Roboto, sans-serif;
    font-size: 1rem;
}

#latlng {
    width: 100%;
    font-family: Roboto, sans-serif;
    font-size: 1rem;
    margin-bottom: 4px;
}

#submit {
    font-size: 1rem;
}
style.css

HTML

<html>
    <head>
        <title>Reverse Geocoding</title>

        <link rel="stylesheet" type="text/css" href="./style.css" />
        <script type="module" src="./index.js"></script>
        <script>
            // prettier-ignore
            (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
                key: "GOOGLE_MAPS_API_KEY"
            });
        </script>
    </head>
    <body>
        <gmp-map center="0.714224, -73.961452" zoom="8" map-id="DEMO_MAP_ID">
            <div id="floating-panel" slot="control-block-start-inline-start">
                <p>
                    Click the map to reverse geocode, or add your own
                    coordinates.
                </p>
                <input
                    id="latlng"
                    type="text"
                    value="40.714224, -73.961452" /><br />
                <input id="submit" type="button" value="Reverse Geocode" />
            </div>
        </gmp-map>
    </body>
</html>
index.html

عرض مثال

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

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

في ما يلي مثال على قائمة العناوين التي قد يعرضها طلب البحث أعلاه:

results[0].formatted_address: "277 Bedford Ave, Brooklyn, NY 11211, USA"
results[1].formatted_address: "Grand St/Bedford Av, Brooklyn, NY 11211, USA"
results[2].formatted_address: "Williamsburg, Brooklyn, NY, USA"
results[3].formatted_address: "Brooklyn, NY, USA"
results[4].formatted_address: "New York, NY, USA"
results[5].formatted_address: "Brooklyn, NY 11211, USA"
results[6].formatted_address: "Kings County, NY, USA"
results[7].formatted_address: "New York-Northern New Jersey-Long Island, NY-NJ-PA, USA"
results[8].formatted_address: "New York Metropolitan Area, USA"
results[9].formatted_address: "New York, USA"

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

ملاحظة: عكس الترميز الجغرافي ليس علمًا دقيقًا. سيحاول برنامج الترميز الجغرافي العثور على أقرب موقع جغرافي يمكن تحديد عنوان له ضمن هامش خطأ معيّن.

استرداد عنوان لمعرّف مكان

قدِّم placeId للعثور على عنوان لمعرّف مكان معيّن. معرّف المكان هو معرّف فريد يمكن استخدامه مع واجهات Google API الأخرى. على سبيل المثال، يمكنك تقديم placeId الذي تعرضه Roads API للحصول على عنوان نقطة تم التقاطها. لمزيد من المعلومات حول معرّفات الأماكن، راجِع نظرة عامة على معرّفات الأماكن.

عند تقديم placeId، لا يمكن أن يتضمّن الطلب أيًا من الحقول التالية:

• address
• latLng
• location
• componentRestrictions

يقبل المثال التالي معرّف مكان، ويعثر على العنوان المطابق، ويوسّط الخريطة في ذلك الموقع الجغرافي. كما تظهر نافذة معلومات تعرض العنوان المنسّق للمكان ذي الصلة:

TypeScript

// Initialize the map.
async function init(): Promise<void> {
    const [{ Geocoder }, { InfoWindow }] = await Promise.all([
        google.maps.importLibrary('geocoding'),
        google.maps.importLibrary('maps'),
        google.maps.importLibrary('marker'),
    ]);

    const mapElement = document.querySelector('gmp-map')!;
    const innerMap = mapElement.innerMap;
    const geocoder = new Geocoder();
    const infoWindow = new InfoWindow();

    document.getElementById('submit')!.addEventListener('click', () => {
        void geocodePlaceId(geocoder, innerMap, infoWindow);
    });
}

// This function is called when the user clicks the UI button.
async function geocodePlaceId(
    geocoder: google.maps.Geocoder,
    map: google.maps.Map,
    infoWindow: google.maps.InfoWindow
) {
    const placeId = (document.getElementById('place-id') as HTMLInputElement)
        .value;

    const { AdvancedMarkerElement } = await google.maps.importLibrary('marker');

    const { results } = await geocoder.geocode({ placeId });
    if (results[0]) {
        map.setZoom(11);
        map.setCenter(results[0].geometry.location);

        const marker = new AdvancedMarkerElement({
            map,
            position: results[0].geometry.location,
        });

        infoWindow.setContent(results[0].formatted_address);
        infoWindow.open(map, marker);
    } else {
        window.alert('No results found');
    }
}

void init();
index.ts

ملاحظة: يمكنك الاطّلاع على الدليل حول استخدام TypeScript و"خرائط Google".

JavaScript

// Initialize the map.
async function init() {
    const [{ Geocoder }, { InfoWindow }] = await Promise.all([
        google.maps.importLibrary('geocoding'),
        google.maps.importLibrary('maps'),
        google.maps.importLibrary('marker'),
    ]);

    const mapElement = document.querySelector('gmp-map');
    const innerMap = mapElement.innerMap;
    const geocoder = new Geocoder();
    const infoWindow = new InfoWindow();

    document.getElementById('submit').addEventListener('click', () => {
        void geocodePlaceId(geocoder, innerMap, infoWindow);
    });
}

// This function is called when the user clicks the UI button.
async function geocodePlaceId(geocoder, map, infoWindow) {
    const placeId = document.getElementById('place-id').value;

    const { AdvancedMarkerElement } = await google.maps.importLibrary('marker');

    const { results } = await geocoder.geocode({ placeId });
    if (results[0]) {
        map.setZoom(11);
        map.setCenter(results[0].geometry.location);

        const marker = new AdvancedMarkerElement({
            map,
            position: results[0].geometry.location,
        });

        infoWindow.setContent(results[0].formatted_address);
        infoWindow.open(map, marker);
    } else {
        window.alert('No results found');
    }
}

void init();
index.js

عرض مثال