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

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

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

نظرة عامة

يمكنك أيضًا الاطّلاع على مرجع 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، في المشروع نفسه الذي أعددته لواجهة برمجة التطبيقات Maps JavaScript API.

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

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

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

التسعير

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

السياسات

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

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

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

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

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

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

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

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

يمثّل العنصر 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[] هو صفيف يشير إلى نوع العنوان للنتيجة المعروضة. تحتوي هذه المصفوفة على مجموعة من علامات معدومة أو أكثر لتحديد نوع العنصر الذي يتم عرضه في النتيجة. على سبيل المثال، يعرض الرمز الجغرافي لمدينة "القاهرة" القيمة "locality" التي تشير إلى أنّ "القاهرة" هي مدينة، ويعرض أيضًا القيمة "political" التي تشير إلى أنّها كيان سياسي. يمكنك الاطّلاع على مزيد من المعلومات حول أنواع العناوين وأنواع مكونات العنوان أدناه.
• 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 الأخرى. على سبيل المثال، يمكنك استخدام 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 إلى كيان مدني من الدرجة الأولى أسفل مستوى البلد. وداخل الولايات المتحدة، تمثّل هذه المستويات الإدارية الولايات. لا تعرض بعض البلدان هذه المستويات الإدارية. في معظم الحالات، ستتطابق الأسماء المختصرة إدارية مع الإدارات المستهدفة إلى حد كبير مع الأقسام الفرعية وفقًا لمعيار 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 الثابت لتحديد حدود إطار العرض هذا. يُرجى العلم أنّ التحيز يقتصر على منح الأولوية للنتائج ضمن الحدود، وإذا كانت هناك نتائج أكثر صلة خارج هذه الحدود، قد يتم تضمينها.

على سبيل المثال، يعرض الرمز الجغرافي لـ "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:

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

في ما يلي مثال على هذا السلوك لموقع جغرافي على خط العرض/خط الطول في القارة القطبية الجنوبية. على الرغم من عدم توفّر نتائج ترميز جغرافي عكسي، لا يزال بإمكاننا طباعة رمز Plus код في الوعد إذا ضبطنا 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({
  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 إجابات كحدّ أقصى ويقتصر على الأماكن التي represent مناطق صغيرة، مثل الأحياء والمناطق الفرعية والمجمّعات الكبيرة. يتم إدراج المناطق التي تحتوي على الإحداثيات المطلوبة أولاً، ويتم ترتيبها من الأصغر إلى الأكبر. تحتوي كل نتيجة من نتائج areas على القيم التالية:

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

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

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

الملاحظات

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

• إذا كانت لديك مشاكل متعلّقة بمنطقة الهند فقط، يُرجى التواصل مع فريق الدعم.
• لإرسال ملاحظاتك حول الإصدار التجريبي، يُرجى مراسلتنا على البريد الإلكتروني التالي: [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 الأخرى. على سبيل المثال، يمكنك تقديم 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