حزمة أدوات Places UI Kit: هي مكتبة جاهزة للاستخدام تتيح للمطوّرين إمكانية التخصيص والتحكّم. ننصحك بتجربتها ومشاركة ملاحظاتك حول تجربتك مع حزمة واجهة المستخدم.

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

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

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

نظرة عامة

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

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

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

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

البدء

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

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

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

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

الأسعار

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

السياسات

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

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

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

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

ردود الترميز الجغرافي

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

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

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

يمثّل العنصر GeocoderResult نتيجة واحدة لترميز جغرافي. قد يعرض طلب الرمز الجغرافي عناصر نتائج متعددة:

results[]: {
 types[]: string,
 formatted_address: string,
 address_components[]: {
   short_name: string,
   long_name: string,
   postcode_localities[]: string,
   types[]: string
 },
 partial_match: boolean,
 place_id: string,
 postcode_localities[]: string,
 geometry: {
   location: LatLng,
   location_type: GeocoderLocationType
   viewport: LatLngBounds,
   bounds: LatLngBounds
 }
}

في ما يلي شرح لهذه الحقول:

‫types[] هو صفيف يشير إلى نوع العنوان للنتيجة التي تم إرجاعها. تحتوي هذه المصفوفة على مجموعة من صفر أو أكثر من العلامات التي تحدد نوع الميزة التي تم عرضها في النتيجة. على سبيل المثال، تعرض عملية الترميز الجغرافي لـ "القاهرة" "المنطقة المحلية"، ما يشير إلى أنّ "القاهرة" هي مدينة، وتعرض أيضًا "سياسية"، ما يشير إلى أنّها كيان سياسي. يمكنك الاطّلاع على مزيد من المعلومات حول أنواع العناوين وأنواع عناصر العناوين أدناه.
‫formatted_address هي سلسلة تحتوي على العنوان الذي يمكن قراءته لهذا الموقع الجغرافي.
وغالبًا ما يكون هذا العنوان مطابقًا للعنوان البريدي. يُرجى العِلم أنّ بعض البلدان، مثل المملكة المتحدة، لا تسمح بتوزيع العناوين البريدية الصحيحة بسبب قيود الترخيص.

يتألف العنوان المنسّق منطقيًا من عنصر واحد أو أكثر من عناصر العنوان. على سبيل المثال، يتألف العنوان "111 8th Avenue, New York, NY" من المكوّنات التالية: "111" (رقم الشارع) و"8th Avenue" (الطريق) و"New York" (المدينة) و "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 التي يمكن أن تحتوي بالكامل على النتيجة المعروضة. يُرجى العِلم أنّ هذه الحدود قد لا تتطابق مع إطار العرض المقترَح. (على سبيل المثال، تشمل سان فرانسيسكو جزر فارالون التي تُعدّ جزءًا من المدينة، ولكن لا يجب عرضها في إطار العرض).

تعرض خدمة Geocoder العناوين باستخدام إعدادات اللغة المفضّلة في المتصفّح أو اللغة المحدّدة عند تحميل JavaScript الخاصة بواجهة برمجة التطبيقات باستخدام المَعلمة language. (لمزيد من المعلومات، يُرجى الاطّلاع على الأقلمة).

أنواع العناوين وأنواع مكونات العناوين

تشير مصفوفة types[] في GeocoderResult ضمن الاستجابة إلى نوع العنوان. تشمل أمثلة أنواع العناوين عنوان شارع أو بلدًا أو كيانًا سياسيًا. تشير مصفوفة types في GeocoderAddressComponent إلى نوع كل جزء من العنوان. وتشمل الأمثلة رقم الشارع أو البلد.

قد تتضمّن العناوين أنواعًا متعددة. ويمكن اعتبار الأنواع "علامات". على سبيل المثال، يتم وضع علامات من النوعين political وlocality على العديد من المدن.

تتوفّر الأنواع التالية ويتم عرضها في كل من مصفوفة نوع العنوان ومصفوفة نوع عنصر العنوان:

نوع العنوان	الوصف
`street_address`	تمثّل هذه السمة عنوان الشارع الدقيق.
`route`	طريق مسمّى (مثل "الطريق السريع 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>

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

Viewport Biasing

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

في ما يلي مثال على هذا السلوك لخطوط الطول والعرض في القارة القطبية الجنوبية. على الرغم من عدم توفّر نتائج ترميز جغرافي عكسي، سيظل بإمكاننا طباعة الرمز الإضافي في الوعد إذا ضبطنا fulfillOnZeroResults=true.

    function addressDescriptorReverseGeocoding() {
      var latlng = new google.maps.LatLng(-75.290330, 38.653861);
      geocoder
        .geocode({
          'location': latlng,
          'fulfillOnZeroResults': true,
        })
        .then((response) => {
          console.log(response.plus_code);
        })
        .catch((error) => {
          window.alert(`Error`);
        });
    }

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

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

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

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

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

function addressDescriptorPlaceIdLookup() {
  geocoder.geocode({
  geocoder.geocode({
    'placeId': 'ChIJyxAX8Bj9DDkRgBfAnBYa66Q',
    'extraComputations': ['ADDRESS_DESCRIPTORS']
    }, function(results, status) {
    if (status == 'OK') {
      console.log(results[0].address_descriptor);
    } else {
      window.alert('Geocode was not successful for the following reason: ' + status);
    }
  });
}

مثال على الترميز الجغرافي العكسي

يحتوي طلب البحث التالي على قيمة خط الطول/العرض لموقع جغرافي في دلهي.

    function addressDescriptorReverseGeocoding() {
      var latlng = new google.maps.LatLng(28.640964,77.235875);
      geocoder
        .geocode({
          'location': latlng,
          'extraComputations': ["ADDRESS_DESCRIPTORS"],
        })
        .then((response) => {
          console.log(response.address_descriptor);
        })
        .catch((error) => {
          window.alert(`Error`);
        });
    }

مثال على واصف العنوان

في ما يلي مثال address_descriptor على ذلك.

  {
    "address_descriptor" : {
       "areas" : [
          {
             "containment" : "OUTSKIRTS",
             "display_name" : {
                "language_code" : "en",
                "text" : "Turkman Gate"
             },
             "place_id" : "ChIJ_7LLvyb9DDkRMKKxP9YyXgs"
          },
          {
             "containment" : "OUTSKIRTS",
             "display_name" : {
                "language_code" : "en",
                "text" : "Chandni Chowk"
             },
             "place_id" : "ChIJWcXciBr9DDkRUb4dCDykTwI"
          },
          {
             "containment" : "NEAR",
             "display_name" : {
                "language_code" : "en",
                "text" : "Katar Ganj"
             },
             "place_id" : "ChIJH3cWUyH9DDkRaw-9CjvcRvY"
          }
       ],
       "landmarks" : [
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "Delite Cinema"
             },
             "straight_line_distance_meters" : 29.9306755065918,
             "place_id" : "ChIJLfiYDCT9DDkROoEa7NdupUM",
             "travel_distance_meters" : 418.7794799804688,
             "spatial_relationship" : "ACROSS_THE_ROAD",
             "types" : [ "establishment", "movie_theater", "point_of_interest" ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "YES Bank"
             },
             "straight_line_distance_meters" : 66.83731079101562,
             "place_id" : "ChIJFYHM3yb9DDkRRKGkZl2mpSQ",
             "travel_distance_meters" : 489.0340270996094,
             "spatial_relationship" : "DOWN_THE_ROAD",
             "types" : [ "bank", "establishment", "finance", "point_of_interest" ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "UCO Bank"
             },
             "straight_line_distance_meters" : 25.38849639892578,
             "place_id" : "ChIJ-c6_wCb9DDkRjIk1LeqRtGM",
             "travel_distance_meters" : 403.2246398925781,
             "spatial_relationship" : "ACROSS_THE_ROAD",
             "types" : [ "atm", "bank", "establishment", "finance", "point_of_interest" ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "Delhi By Cycle Meeting Point"
             },
             "straight_line_distance_meters" : 44.02867126464844,
             "place_id" : "ChIJNxVfkSb9DDkRJD22l-eGFdM",
             "travel_distance_meters" : 97.41281890869141,
             "spatial_relationship" : "AROUND_THE_CORNER",
             "types" : [
                "establishment",
                "point_of_interest",
                "tourist_attraction",
                "travel_agency"
             ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "Axis Bank Branch"
             },
             "straight_line_distance_meters" : 102.3495178222656,
             "place_id" : "ChIJr3uaDCT9DDkR8roHTVSn1x4",
             "travel_distance_meters" : 330.8566284179688,
             "spatial_relationship" : "DOWN_THE_ROAD",
             "types" : [ "bank", "establishment", "finance", "point_of_interest" ]
          }
       ]
    }
  }

تتضمّن كل كائن address_descriptor مصفوفتَين: landmarks وareas. تحتوي مصفوفة landmarks على ما يصل إلى 5 نتائج مرتبة حسب الصلة، مع مراعاة القرب من الإحداثيات المطلوبة ومدى توفّر المعلم وإمكانية رؤيته. تحتوي كل نتيجة خاصة بمعلم بارز على القيم التالية:

‫place_id هو رقم تعريف المكان الخاص بنتيجة المعالم. اطّلِع على نظرة عامة حول معرّف المكان.
‫display_name هو الاسم المعروض للمعلم ويتضمّن language_code وtext.
‫straight_line_distance_meters هي المسافة بين نقطة وأخرى بالأمتار بين الإحداثيات المُدخَلة ونتيجة المعالم.
تمثّل travel_distance_meters المسافة بالأمتار التي تم قطعها باستخدام شبكة الطرق (مع تجاهل القيود المفروضة على الطرق) بين الإحداثيات المُدخَلة ونتيجة المعالم.
spatial_relationship هي العلاقة المقدَّرة بين الإحداثيات المُدخَلة ونتيجة المعالم:

"NEAR" هي العلاقة التلقائية في حال عدم انطباق أي مما يلي.
"WITHIN" عندما تكون إحداثيات الإدخال مضمّنة في حدود البنية المرتبطة بالمعلم
"BESIDE" عندما تكون الإحداثية المُدخَلة مجاورة مباشرةً للمعلم أو نقطة الوصول إليه
‫"ACROSS_THE_ROAD" عندما تكون إحداثيات الإدخال معاكسة تمامًا للمعلم البارز على الجانب الآخر من الطريق
"DOWN_THE_ROAD" عندما تكون الإحداثية المُدخَلة على المسار نفسه الذي يقع عليه المعلم، ولكن ليس "BESIDES" أو "ACROSS_THE_ROAD"
"AROUND_THE_CORNER" عندما تكون إحداثيات الإدخال على طول طريق عمودي على المعلم (يقتصر على انعطاف واحد)
"BEHIND" عندما تكون إحداثيات الإدخال قريبة مكانيًا من المعلم، ولكنها بعيدة عن نقطة الوصول إليه

types هي أنواع الأماكن الخاصة بالمعلم.

يحتوي العنصر areas على ما يصل إلى 3 ردود ويقتصر على الأماكن التي تمثّل مناطق صغيرة، مثل الأحياء والمناطق الفرعية والمجمّعات الكبيرة. يتم إدراج المناطق التي تحتوي على الإحداثيات المطلوبة أولاً، ثم يتم ترتيبها من الأصغر إلى الأكبر. تحتوي كل نتيجة areas على القيم التالية:

‫place_id هو رقم تعريف المكان الخاص بنتيجة المناطق. اطّلِع على نظرة عامة حول معرّف المكان.
‫display_name هو الاسم المعروض للمنطقة ويتضمّن language_code وtext.
containment هي علاقة الاحتواء المقدَّرة بين الإحداثيات المُدخَلة ونتائج المناطق:

"NEAR" هي العلاقة التلقائية في حال عدم انطباق أي مما يلي.
‫"WITHIN" عندما تكون إحداثيات الإدخال قريبة من مركز المنطقة
‫"OUTSKIRTS" عندما تكون إحداثيات الإدخال قريبة من حافة المنطقة

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

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

الملاحظات

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

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

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

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

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

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

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

TypeScript

let marker;

async function initMap() {
    //  Request the needed libraries.
    const [{ Map, InfoWindow }, { Geocoder }, { AdvancedMarkerElement }] =
        await Promise.all([
            google.maps.importLibrary(
                'maps'
            ) as Promise<google.maps.MapsLibrary>,
            google.maps.importLibrary(
                'geocoding'
            ) as Promise<google.maps.GeocodingLibrary>,
            google.maps.importLibrary(
                'marker'
            ) as Promise<google.maps.MarkerLibrary>,
        ]);

    // Get the gmp-map element.
    const mapElement = document.querySelector(
        'gmp-map'
    ) as google.maps.MapElement;

    // Get the inner map.
    const innerMap = mapElement.innerMap;

    // Get the latlng input box.
    const latLngQuery = document.getElementById('latlng') as HTMLInputElement;

    // Get the submit button.
    const submitButton = document.getElementById('submit') as HTMLElement;

    // Set the cursor to crosshair.
    innerMap.setOptions({
        draggableCursor: 'crosshair',
        zoom: 13,
    });

    // Create a marker for re-use.
    marker = new AdvancedMarkerElement({
        map: innerMap,
    });

    const geocoder = new Geocoder();
    const infowindow = new InfoWindow();

    // Add a click event listener to the submit button.
    submitButton.addEventListener('click', () => {
        geocodeLatLng(geocoder, innerMap, infowindow);
    });

    // Add a click event listener to the map.
    innerMap.addListener('click', (event) => {
        latLngQuery.value = `${event.latLng.lat()}, ${event.latLng.lng()}`;
        geocodeLatLng(geocoder, innerMap, infowindow);
    });

    // Make an initial request upon loading.
    geocodeLatLng(geocoder, innerMap, infowindow);
}

async 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]) {
                marker.position = latlng;
                map.setCenter(latlng);
                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));
}

initMap();index.ts

JavaScript

let marker;
async function initMap() {
    //  Request the needed libraries.
    const [{ Map, InfoWindow }, { Geocoder }, { AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary('maps'),
        google.maps.importLibrary('geocoding'),
        google.maps.importLibrary('marker'),
    ]);
    // Get the gmp-map element.
    const mapElement = document.querySelector('gmp-map');
    // Get the inner map.
    const innerMap = mapElement.innerMap;
    // Get the latlng input box.
    const latLngQuery = document.getElementById('latlng');
    // Get the submit button.
    const submitButton = document.getElementById('submit');
    // Set the cursor to crosshair.
    innerMap.setOptions({
        draggableCursor: 'crosshair',
        zoom: 13,
    });
    // Create a marker for re-use.
    marker = new AdvancedMarkerElement({
        map: innerMap,
    });
    const geocoder = new Geocoder();
    const infowindow = new InfoWindow();
    // Add a click event listener to the submit button.
    submitButton.addEventListener('click', () => {
        geocodeLatLng(geocoder, innerMap, infowindow);
    });
    // Add a click event listener to the map.
    innerMap.addListener('click', (event) => {
        latLngQuery.value = `${event.latLng.lat()}, ${event.latLng.lng()}`;
        geocodeLatLng(geocoder, innerMap, infowindow);
    });
    // Make an initial request upon loading.
    geocodeLatLng(geocoder, innerMap, infowindow);
}
async 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]) {
            marker.position = latlng;
            map.setCenter(latlng);
            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));
}
initMap();index.js

عرض مثال

تجربة عيّنة

JSFiddle.net

يُرجى العِلم أنّه في المثال السابق، عرضنا النتيجة الأولى من خلال اختيار 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

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

عرض مثال

تجربة عيّنة

JSFiddle.net Google Cloud Shell

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

نظرة عامة

البدء

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

الأسعار

السياسات

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

ردود الترميز الجغرافي

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

أنواع العناوين وأنواع مكونات العناوين

رموز الحالة

Viewport Biasing

تفضيل رمز المنطقة

فلترة المكوّنات

استيفاء متطلبات العرض عند عدم توفّر نتائج

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

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

مثال على الترميز الجغرافي العكسي

مثال على واصف العنوان

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

الملاحظات

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

TypeScript

JavaScript

تجربة عيّنة

استرداد عنوان لمعرّف مكان

TypeScript

JavaScript

تجربة عيّنة

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