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

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

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

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

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

نظرة عامة

يمكنك أيضًا الاطّلاع على مرجع Maps JavaScript API: Geocoder

الترميز الجغرافي هو عملية تحويل العناوين (مثل "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. انقر على الزر اختيار مشروع، ثم اختَر المشروع نفسه الذي أعددته لاستخدام Maps JavaScript API، وانقر على فتح.
3. من قائمة واجهات برمجة التطبيقات في لوحة البيانات، ابحث عن Geocoding API.
4. إذا ظهرت واجهة برمجة التطبيقات في القائمة، يعني ذلك أنّك قد انتهيت من عملية الإعداد. إذا لم تكن واجهة برمجة التطبيقات مُدرَجة، فعِّلها:
   1. في أعلى الصفحة، انقر على تفعيل واجهة برمجة التطبيقات (API) لعرض علامة التبويب المكتبة. بدلاً من ذلك، انقروا على المكتبة من القائمة الجانبية اليمنى.
   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 — رمز المنطقة، ويتم تحديده كعلامة فرعية لمنطقة Unicode مكوّنة من حرفين (غير رقميين). في معظم الحالات، يتم ربط هذه العلامات مباشرةً بقيم مألوفة من حرفين لنطاقات المستوى الأعلى التي يتم ترميزها حسب البلد (ccTLD). لن يؤثّر المَعلمة region إلا في نتائج الترميز الجغرافي، ولن يقيّدها بالكامل. يمكنك الاطّلاع على مزيد من المعلومات حول تفضيل رموز المناطق أدناه.
• extraComputations: القيمة المسموح بها الوحيدة لهذه المَعلمة هي ADDRESS_DESCRIPTORS. يمكنك الاطّلاع على واصفات العناوين لمزيد من التفاصيل.
• ‫fulfillOnZeroResults: يجب تنفيذ الوعد بحالة ZERO_RESULT في الرد. قد يكون ذلك مرغوبًا فيه لأنّه حتى في حال عدم توفّر أي نتائج ترميز جغرافي، قد تظل هناك حقول إضافية على مستوى الرد يتم عرضها. يمكنك الاطّلاع على مقالة التنفيذ عند عدم توفّر نتائج لمزيد من التفاصيل.

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

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

ملاحظة: يحتوي ردّ الترميز الجغرافي أيضًا على الحقلَين 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 هو الوصف النصي الكامل أو اسم مكوّن العنوان كما تعرضه أداة الترميز الجغرافي.
  • ‫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 التي يمكن أن تحتوي بالكامل على النتيجة المعروضة. يُرجى العِلم أنّ هذه الحدود قد لا تتطابق مع إطار العرض المقترَح. (على سبيل المثال، تشمل سان فرانسيسكو جزر فارالون التي تُعدّ جزءًا من المدينة، ولكن لا يجب عرضها في إطار العرض).

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

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

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

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

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

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

تشير القائمة الفارغة من الأنواع إلى عدم توفّر أي أنواع معروفة لمكوّن العنوان المحدّد (على سبيل 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();

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

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

JavaScript

async function geocode(request) {
    clear();
    geocoder
        .geocode(request)
        .then((result) => {
        const { results } = result;
        innerMap.setCenter(results[0].geometry.location);
        marker.position = new google.maps.LatLng(results[0].geometry.location);
        mapElement.append(marker);
        responseDiv.style.display = 'block';
        response.innerText = JSON.stringify(result, null, 2);
        return results;
    })
        .catch((e) => {
        alert('Geocode was not successful for the following reason: ' + e);
    });
}
index.js

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

Viewport Biasing

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

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

الملاحظات

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

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

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

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

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

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

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

TypeScript

let marker;

async function initMap() {
    //  Request the needed libraries.
    const [{ Map, InfoWindow }, { Geocoder }, { AdvancedMarkerElement }] =
        await Promise.all([
            google.maps.importLibrary(
                'maps'
            ) as Promise<google.maps.MapsLibrary>,
            google.maps.importLibrary(
                'geocoding'
            ) as Promise<google.maps.GeocodingLibrary>,
            google.maps.importLibrary(
                'marker'
            ) as Promise<google.maps.MarkerLibrary>,
        ]);

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

    // 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') as HTMLElement;

    // 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', () => {
        geocodeLatLng(geocoder, innerMap, infowindow);
    });

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

    // Make an initial request upon loading.
    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]),
    };

    geocoder
        .geocode({ location: latlng })
        .then((response) => {
            if (response.results[0]) {
                marker.position = latlng;
                map.setCenter(latlng);
                infowindow.setContent(response.results[0].formatted_address);
                infowindow.open(map, marker);
            } else {
                window.alert('No results found');
            }
        })
        .catch((e) => window.alert('Geocoder failed due to: ' + e));
}

initMap();
index.ts

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

JavaScript

let marker;
async function initMap() {
    //  Request the needed libraries.
    const [{ Map, 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', () => {
        geocodeLatLng(geocoder, innerMap, infowindow);
    });
    // Add a click event listener to the map.
    innerMap.addListener('click', (event) => {
        latLngQuery.value = `${event.latLng.lat()}, ${event.latLng.lng()}`;
        geocodeLatLng(geocoder, innerMap, infowindow);
    });
    // Make an initial request upon loading.
    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]),
    };
    geocoder
        .geocode({ location: latlng })
        .then((response) => {
        if (response.results[0]) {
            marker.position = latlng;
            map.setCenter(latlng);
            infowindow.setContent(response.results[0].formatted_address);
            infowindow.open(map, marker);
        }
        else {
            window.alert('No results found');
        }
    })
        .catch((e) => window.alert('Geocoder failed due to: ' + e));
}
initMap();
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>
        <!-- prettier-ignore -->
        <script>(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: "AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8", v: "weekly" });</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

عرض مثال

تجربة عيّنة

JSFiddle.net

يُرجى العِلم أنّه في المثال السابق، عرضنا النتيجة الأولى من خلال اختيار 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 APIs أخرى. على سبيل المثال، يمكنك تقديم placeId الذي تعرضه Roads API للحصول على عنوان نقطة تم التقاطها. لمزيد من المعلومات حول معرّفات الأماكن، راجِع نظرة عامة على معرّفات الأماكن.

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

• address
• latLng
• location
• componentRestrictions

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

TypeScript

// Initialize the map.
async function initMap(): Promise<void> {
  await Promise.all([
    google.maps.importLibrary("maps"),
    google.maps.importLibrary("geocoding"),
    google.maps.importLibrary("marker"),
  ]);

  const mapElement = document.querySelector("gmp-map") as google.maps.MapElement;
  const innerMap = mapElement.innerMap;
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  (document.getElementById("submit") as HTMLElement).addEventListener(
    "click",
    () => {
      geocodePlaceId(geocoder, innerMap, infowindow);
    }
  );
}

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

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

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

        infowindow.setContent(results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

initMap();
index.ts

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

JavaScript

// Initialize the map.
async function initMap() {
    await Promise.all([
        google.maps.importLibrary("maps"),
        google.maps.importLibrary("geocoding"),
        google.maps.importLibrary("marker"),
    ]);
    const mapElement = document.querySelector("gmp-map");
    const innerMap = mapElement.innerMap;
    const geocoder = new google.maps.Geocoder();
    const infowindow = new google.maps.InfoWindow();
    document.getElementById("submit").addEventListener("click", () => {
        geocodePlaceId(geocoder, innerMap, infowindow);
    });
}
// This function is called when the user clicks the UI button.
function geocodePlaceId(geocoder, map, infowindow) {
    const placeId = document.getElementById("place-id")
        .value;
    geocoder
        .geocode({ placeId: placeId })
        .then(({ results }) => {
        if (results[0]) {
            map.setZoom(11);
            map.setCenter(results[0].geometry.location);
            const marker = new google.maps.marker.AdvancedMarkerElement({
                map,
                position: results[0].geometry.location,
            });
            infowindow.setContent(results[0].formatted_address);
            infowindow.open(map, marker);
        }
        else {
            window.alert("No results found");
        }
    })
        .catch((e) => window.alert("Geocoder failed due to: " + e));
}
initMap();
index.js

عرض مثال

تجربة عيّنة

JSFiddle.net