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

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

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

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

نظرة عامة

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

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

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

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

البدء

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

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

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

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

السعر

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

السياسات

ويجب أن يتوافق استخدام خدمة الترميز الجغرافي مع السياسات الموضّحة في واجهة برمجة التطبيقات للترميز الجغرافي.

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

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

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

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

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

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

غالبًا ما تحدث المطابقات الجزئية لعناوين الشوارع التي لا توجد ضمن المنطقة المحلية التي يتم تمريرها في الطلب. ويمكن أيضًا عرض المطابقات الجزئية عندما يتطابق الطلب مع موقعَين أو أكثر في المنطقة المحلية نفسها. على سبيل المثال، ستعرض نتائج البحث "Hillpar St, Bristol, UK" مطابقة جزئية لكل من شارع "هنري ستريت" و"شارع هنرييتا". لاحظ أنه إذا اشتمل الطلب على عنصر عنوان به خطأ إملائي، فقد تقترح خدمة الترميز الجغرافي عنوانًا بديلاً. سيتم أيضًا تمييز الاقتراحات التي يتم تنفيذها بهذه الطريقة على أنّها مطابقة جزئية.
place_id هو معرّف فريد للمكان، ويمكن استخدامه مع واجهات Google APIs الأخرى. على سبيل المثال، يمكنك استخدام 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 إلى الكيان السياسي الوطني، ويكون عادةً أعلى نوع ترتيب يعرضه برنامج Geocoder.
تشير السمة administrative_area_level_1 إلى كيان مدني من الدرجة الأولى أسفل مستوى البلد. وداخل الولايات المتحدة، هذه المستويات الإدارية هي الولايات. لا تظهر هذه المستويات الإدارية في بعض الدول. في معظم الحالات، تتطابق الأسماء المختصرة في admin_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 إلى مرجع موقع جغرافي مشفّر مشتق من خط العرض وخط الطول. يمكن استخدام رموز المواقع المفتوحة كبديل لعناوين الشوارع في الأماكن التي لا تتوفر فيها (حيث لا تكون المباني مرقمة أو لا تتم تسمية الشوارع). يمكنك الاطّلاع على 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 التي تختلف أحيانًا عن قيم ccTLD (مثلاً "GB" لـ "بريطانيا العظمى").

عند استخدام مَعلمة region:

يُرجى تحديد بلد واحد أو منطقة واحدة فقط. ويتم تجاهل قيم متعددة، ويمكن أن يؤدي ذلك إلى تعذّر تنفيذ الطلب.
استخدِم فقط علامات فرعية للمناطق من حرفَين (تنسيق Unicode CLDR). وستؤدي جميع الإدخالات الأخرى إلى حدوث أخطاء.
البلدان والمناطق المدرَجة في تفاصيل تغطية "منصة خرائط Google" هي فقط المتاحة.

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

على سبيل المثال، يعرض الرمز الجغرافي لـ "Toledo" هذه النتيجة، لأنّ النطاق التلقائي لخدمة الترميز الجغرافي مضبوط على الولايات المتحدة:

{
  "types":["locality","political"],
  "formatted_address":"Toledo, OH, USA",
  "address_components":[{
    "long_name":"Toledo",
    "short_name":"Toledo",
    "types":["locality","political"]
  },{
    "long_name":"Ohio",
    "short_name":"OH",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"United States",
    "short_name":"US",
    "types":["country","political"]
  }],
  "place_id": "ChIJeU4e_C2HO4gRRcM6RZ_IPHw"
}

سيعيد الرمز الجغرافي لـ "توليدو" مع ضبط الحقل region على 'es' (إسبانيا) المدينة الإسبانية:

{
  "types":["locality","political"],
  "formatted_address":"Toledo, España",
  "address_components":[{
    "long_name":"Toledo",
    "short_name":"Toledo",
    "types":["locality","political"]
  },{
    "long_name":"Toledo",
    "short_name":"TO",
    "types":["administrative_area_level_2","political"]
  },{
    "long_name":"Castilla-La Mancha",
    "short_name":"CM",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"España",
    "short_name":"ES",
    "types":["country","political"]
  }],
  "place_id": "ChIJ8f21C60Lag0R_q11auhbf8Y"
}

تصفية المكونات

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

لا يعرض أداة الترميز الجغرافي سوى النتائج التي تتطابق مع جميع فلاتر المكوِّن. وهذا يعني أنّه يقيّم مواصفات الفلتر بالرمز AND وليس بالرمز OR.

يتألف فلتر المكوّنات من عنصر واحد أو أكثر من العناصر التالية:

يتطابق route مع الاسم الطويل أو المختصر للمسار.
تتطابق السمة locality مع أنواع المنطقة المحلية والفرعية.
يتطابق administrativeArea مع جميع مستويات المنطقة الإدارية.
تتطابق السمة postalCode مع الرموز البريدية وبادئات الرمز البريدي.
تتطابق السمة country مع اسم البلد أو رمز البلد المكوّن من حرفَين وفقًا لمعيار ISO 3166-1. ملاحظة: تتّبع واجهة برمجة التطبيقات معيار ISO لتحديد البلدان، وتعمل الفلترة على النحو الأمثل عند استخدام رمز ISO المقابل للبلد.

يوضِّح المثال التالي استخدام المَعلمة componentRestrictions لفلترة البيانات حسب country وpostalCode:

function codeAddress() {
geocoder.geocode({
  componentRestrictions: {
    country: 'AU',
    postalCode: '2000'
  }
}, function(results, status) {
  if (status == 'OK') {
    map.setCenter(results[0].geometry.location);
    var marker = new google.maps.Marker({
      map: map,
      position: results[0].geometry.location
    });
  } else {
    window.alert('Geocode was not successful for the following reason: ' + status);
  }
});
}

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

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

بدلاً من تقديم 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 APIs الأخرى. على سبيل المثال، يمكنك توفير placeId التي تعرضها Roads API للحصول على عنوان نقطة سريعة. لمزيد من المعلومات عن معرّفات الأماكن، اطّلِع على نظرة عامة على معرّف المكان.

عند توفير placeId، لا يمكن أن يحتوي الطلب على أي من الحقول التالية:

address
latLng
location
componentRestrictions

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