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

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

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

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

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

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

التسعير

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