إشعار: ستتوفّر قريبًا ميزة جديدة لتصميم الخرائط الأساسية في "منصة خرائط Google". يتضمّن هذا التعديل على تصميم الخريطة لوحة ألوان تلقائية جديدة وعلامات جديدة وتحسينات على تجارب الخريطة وسهولة استخدامها. سيتم تعديل جميع أنماط الخرائط تلقائيًا في آذار (مارس) 2025. لمزيد من المعلومات عن مدى التوفّر وكيفية التفعيل في وقت سابق، يُرجى الاطّلاع على نمط خريطة جديد لـ "منصة خرائط Google".

تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

نظرة عامة

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

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

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

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

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

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

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

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

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

الأسعار

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

السياسات

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

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

{
  "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 التي تختلف أحيانًا عن قيم نطاقات المستوى الأعلى التي يتم ترميزها حسب البلد (ccTLD) (على سبيل المثال، "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. تتيح قيم الفلاتر استخدام طرق تصحيح الأخطاء الإملائية والمطابقة الجزئية نفسها المستخدَمة في طلبات تحديد المواقع الجغرافية الأخرى.

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

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

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

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

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

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

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

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

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

عرض مثال

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

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

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