الحصول على مفتاح Maps Demo Key: يمكنك تجربة ميزات محدّدة من Maps JavaScript API و"حزمة أدوات خرائط Google الجاهزة للأماكن" بدون أي تكلفة باستخدام مفتاح Maps Demo Key، وبدون الحاجة إلى إدخال معلومات الفوترة.

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

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

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

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

نظرة عامة

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

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

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

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

البدء

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

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

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

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

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

الأسعار

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

السياسات

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

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

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

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

تحدث المطابقات الجزئية في أغلب الأحيان لعناوين الشوارع غير الموجودة ضمن المنطقة التي تمررها في الطلب. قد يتم أيضًا عرض المطابقات الجزئية عندما يتطابق طلب مع موقعَين جغرافيَين أو أكثر في المنطقة نفسها. على سبيل المثال، سيؤدي البحث عن "Hillpar St, Bristol, UK" إلى عرض مطابقة جزئية لكل من Henry Street وHenrietta Street. يُرجى العِلم أنّه إذا كان الطلب يتضمّن مكوّن عنوان مكتوبًا بشكل غير صحيح، قد تقترح خدمة الترميز الجغرافي عنوانًا بديلاً. سيتم أيضًا وضع علامة على الاقتراحات التي يتم عرضها بهذه الطريقة على أنّها مطابقة جزئية.
place_idهو معرّف فريد لمكان معيّن، ويمكن استخدامه مع Google APIs الأخرى. على سبيل المثال، يمكنك استخدام 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`	طريق مسمّى (مثل "US 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`	نقطة اهتمام مُسمّاة عادةً ما تكون "نقاط الاهتمام" هذه كيانات محلية بارزة لا تندرج بسهولة ضمن فئة أخرى، مثل "مبنى إمباير ستيت" أو "برج إيفل".

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

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

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

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

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

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

{
  "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"
}

سيؤدي الترميز الجغرافي لـ "Toledo" مع ضبط الحقل 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 المقابل للبلد.

يوضّح المثال التالي كيفية استخدام المَعلمة 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 Code في الوعد إذا ضبطنا 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" عندما تكون الإحداثيات المُدخلة قريبة من حافة المنطقة.

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

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

الملاحظات

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

بالنسبة إلى المشاكل المتعلّقة بمنطقة الهند فقط، يُرجى التواصل مع فريق الدعم.
لتقديم ملاحظات حول الإصدار التجريبي، يُرجى مراسلتنا عبر البريد الإلكتروني على address-descriptors-feedback@google.com.
يمكنك الاطّلاع على تفاصيل تغطية واصفات العناوين لمزيد من المعلومات.

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

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

بدلاً من تقديم 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

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 APIs الأخرى. على سبيل المثال، يمكنك تقديم 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

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

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

اختيار واجهة برمجة التطبيقات المناسبة للعناوين أو الإحداثيات

يمكنك توسيع القسم التالي لمقارنة google.maps.Geocoder مع واجهات برمجة التطبيقات الأخرى في "منصة خرائط Google" لتنفيذ المهام الشائعة المتعلّقة بالعناوين والإحداثيات:

مقارنة Geocoder بواجهات برمجة التطبيقات الأخرى في "منصة خرائط Google"

هدف المطوّر	واجهة برمجة التطبيقات أو الطريقة المقترَحة	حالات الاستخدام
تحويل عنوان شارع كامل إلى إحداثيات `LatLng` (الترميز الجغرافي الأمامي)	`geocoder.geocode({ address })` (`google.maps.Geocoder`)	استخدِم هذه الخدمة عندما يكون لديك سلسلة عنوان كاملة وغير غامضة وتحتاج إلى إحداثيات الخريطة.
تحويل إحداثيات نظام تحديد المواقع العالمي (GPS) أو إحداثيات الخريطة التي تم النقر عليها (`{ lat, lng }`) إلى عنوان شارع يمكن لشخص عادي قراءته (عكس الترميز الجغرافي)	`geocoder.geocode({ location })` (`google.maps.Geocoder`)	يمكنك استخدامها لإعداد التقارير الميدانية أو تحديد مواقع التسليم أو عرض أقرب عنوان شارع لإحداثيات معيّنة.
البحث عن العناوين باستخدام ميزة "الكتابة المسبقة" أثناء كتابة المستخدم في حقل إدخال	`<gmp-place-autocomplete>` (`PlaceAutocompleteElement`)	استخدِم هذه الطريقة لمربّعات البحث التفاعلية أثناء كتابة المستخدم، بدلاً من استدعاء `Geocoder` عند كل ضغطة مفتاح.
التحقّق من عنوان الدفع أو الشحن، أو توحيد مكوّنات الرمز البريدي، أو التحقّق من إمكانية التسليم إلى المباني الفرعية والوحدات	Address Validation API (`POST https://addressvalidation.googleapis.com/v1:validateAddress`)	يمكنك استخدامها في عمليات الدفع في التجارة الإلكترونية ونماذج الشحن وسير العمل التي يجب أن تؤكّد ما إذا كان عنوان البريد أو رقم الشقة/الوحدة السكنية قابلاً للتسليم (وهو ما لا تتحقّق منه `Geocoder`).
تحويل إحداثيات (`lat, lng`) وطابع زمني إلى فارق زمني عن التوقيت العالمي المنسق (`rawOffset`، `dstOffset`) ومنطقة زمنية وفقًا لقاعدة بيانات IANA (`timeZoneId`)	Time Zone API (`GET https://maps.googleapis.com/maps/api/timezone/json`)	يمكنك استخدامها عندما تحتاج إلى معرّف المنطقة الزمنية في IANA أو معادلة التوقيت العالمي المنسّق أو معادلة التوقيت الصيفي لإحداثيات وطابع زمني (لا تعرضهما `Geocoder`).

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

نظرة عامة

البدء

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

الأسعار

السياسات

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

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

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

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

رموز الحالة

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

TypeScript

JavaScript

الانحياز لإطار العرض

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

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

تنفيذ الطلب في حال عدم توفّر نتائج

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

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

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

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

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

الملاحظات

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

TypeScript

JavaScript

CSS

HTML

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

TypeScript

JavaScript

اختيار واجهة برمجة التطبيقات المناسبة للعناوين أو الإحداثيات

مقارنة Geocoder بواجهات برمجة التطبيقات الأخرى في "منصة خرائط Google"

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