إشعار: ستتوفّر قريبًا ميزة جديدة لتصميم الخرائط الأساسية في "منصة خرائط 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.
انقر على الزر اختيار مشروع، ثم اختَر المشروع نفسه الذي أعددته لمكتبة Maps JavaScript API، ثم انقر على فتح.
من قائمة واجهات برمجة التطبيقات في لوحة البيانات، ابحث عن Geocoding API.
إذا ظهرت لك واجهة برمجة التطبيقات في القائمة، يعني ذلك أنّك قد أكملت الخطوات اللازمة. إذا لم تكن واجهة برمجة التطبيقات مُدرَجة، فعِّلها:
1. في أعلى الصفحة، انقر على تفعيل واجهة برمجة التطبيقات لعرض علامة التبويب المكتبة. بدلاً من ذلك، انقر على المكتبة من القائمة اليمنى.
2. ابحث عن Geocoding API، ثم اختَره من قائمة النتائج.
3. انقر على تفعيل. عند اكتمال العملية، تظهر Geocoding API في قائمة واجهات برمجة التطبيقات في لوحة البيانات.

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

التسعير

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

السياسات

يجب أن يكون استخدام خدمة الترميز الجغرافي متوافقًا مع السياسات الموضّحة في 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 شارع 8، القاهرة، القاهرة" من المكوّنات التالية: "111" (رقم الشارع)، "شارع 8" (المسار)، و"القاهرة" (المدينة) و "القاهرة" (الولاية).

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

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

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

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