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

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

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

نظرة عامة

يمكنك أيضًا الاطّلاع على مرجع JavaScript API لـ "خرائط Google": Geocoder

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

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

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

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

الخطوات الأولى

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

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

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

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

التسعير

اعتبارًا من 16 تموز (يوليو) 2018، تم اعتماد خطة تسعير جديدة للدفع حسب الاستخدام للخرائط والمسارات والأماكن. لمزيد من المعلومات عن الحدود القصوى للسعر والاستخدام الجديدة لاستخدام خدمة JavaScript Geocoding، راجع الاستخدام والفوترة في Geocoding API.

السياسات

يجب أن يتوافق استخدام خدمة Geocoding مع السياسات الموضَّحة في Geocoding API.

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

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

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

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

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

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

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

  var geocoder;
  var map;
  function initialize() {
    geocoder = new google.maps.Geocoder();
    var latlng = new google.maps.LatLng(-34.397, 150.644);
    var mapOptions = {
      zoom: 8,
      center: latlng
    }
    map = new google.maps.Map(document.getElementById('map'), mapOptions);
  }

  function codeAddress() {
    var address = document.getElementById('address').value;
    geocoder.geocode( { 'address': address}, function(results, status) {
      if (status == 'OK') {
        map.setCenter(results[0].geometry.location);
        var marker = new google.maps.Marker({
            map: map,
            position: results[0].geometry.location
        });
      } else {
        alert('Geocode was not successful for the following reason: ' + status);
      }
    });
  }

<body onload="initialize()">
 <div id="map" style="width: 320px; height: 480px;"></div>
  <div>
    <input id="address" type="textbox" value="Sydney, NSW">
    <input type="button" value="Encode" onclick="codeAddress()">
  </div>
</body>

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

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

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

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

{
  "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. تستخدم هذه المَعلمة رمز منطقة يتم تحديده على أنّه علامة فرعية لمنطقة يونيكود مؤلّفة من حرفَين (غير رقمية). يتم ربط هذه العلامات مباشرةً بقيم مألوفة مكوّنة من حرفَين في نطاقات المستوى الأعلى التي يتم ترميزها حسب البلد ("نطاق المستوى الأعلى") مثل "uk" في "co.uk"، على سبيل المثال. في بعض الحالات، تتوافق العلامة region أيضًا مع رموز ISO-3166-1 التي تختلف أحيانًا عن قيم نطاقات المستوى الأعلى التي يتم ترميزها حسب البلد (ccTLD) (على سبيل المثال، "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"
}

تصفية المكونات

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

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

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

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

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

function codeAddress() {
geocoder.geocode({
  componentRestrictions: {
    country: 'AU',
    postalCode: '2000'
  }
}, function(results, status) {
  if (status == 'OK') {
    map.setCenter(results[0].geometry.location);
    var marker = new google.maps.Marker({
      map: map,
      position: results[0].geometry.location
    });
  } else {
    window.alert('Geocode was not successful for the following reason: ' + status);
  }
});
}

توصيل الطلب عند عدم العثور على أي نتائج

بالنسبة إلى الترميز الجغرافي العكسي، يتم تلقائيًا عدم الوفاء بالعد التنازلي في status=ZERO_RESULTS. ومع ذلك، يُحتمل أن تتم تعبئة الحقلَين الإضافيَين لمستوى الاستجابة plus_code وaddress_descriptor في هذه الحالة. إذا تم تقديم القيمة "صحيح" للمَعلمة 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`);
        });
    }
  

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

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

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

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

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

function addressDescriptorPlaceIdLookup() {
  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" عندما يكون إحداثي الإدخال قريبًا من حافة المنطقة.

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

تتوفّر هذه الميزة في بلدان محدّدة فقط.

هذه ميزة معاينة ونشكرك على إرسال ملاحظاتك. يُرجى إرسال رسالة إلكترونية إلى [e-mail].

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

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

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

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

يعمل المثال التالي على ترميز قيمة خط العرض/خط الطول جغرافيًا ويركّز على الخريطة عند ذلك الموقع، ما يؤدي إلى عرض نافذة معلومات تتضمّن العنوان المنسَّق:

TypeScript

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 8,
      center: { lat: 40.731, lng: -73.997 },
    }
  );
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

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

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]) {
        map.setZoom(11);

        const marker = new google.maps.Marker({
          position: latlng,
          map: map,
        });

        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));
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

ملاحظة: اقرأ الدليل حول استخدام TypeScript و"خرائط Google".

JavaScript

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 8,
    center: { lat: 40.731, lng: -73.997 },
  });
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  document.getElementById("submit").addEventListener("click", () => {
    geocodeLatLng(geocoder, map, infowindow);
  });
}

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]) {
        map.setZoom(11);

        const marker = new google.maps.Marker({
          position: latlng,
          map: map,
        });

        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));
}

window.initMap = initMap;
index.js

ملاحظة: يتم جمع JavaScript من مقتطف TypeScript.

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

تجربة "عيّنة"

JSFiddle.net Google Cloud Shell

يُرجى العلم أنّه في المثال السابق، عرضنا النتيجة الأولى من خلال اختيار 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.
function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 8,
      center: { lat: 40.72, lng: -73.96 },
    }
  );
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

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

// This function is called when the user clicks the UI button requesting
// a geocode of a place ID.
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({
          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));
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

ملاحظة: اقرأ الدليل حول استخدام TypeScript و"خرائط Google".

JavaScript

// Initialize the map.
function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 8,
    center: { lat: 40.72, lng: -73.96 },
  });
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

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

// This function is called when the user clicks the UI button requesting
// a geocode of a place ID.
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({
          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));
}

window.initMap = initMap;
index.js

ملاحظة: يتم جمع JavaScript من مقتطف TypeScript.

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

تجربة "عيّنة"

JSFiddle.net Google Cloud Shell