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

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

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

نظرة عامة

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

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

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

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

البدء

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

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

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

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

التسعير

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

السياسات

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

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

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

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

عدم تحليل العنوان المنسَّق آليًا. وبدلاً من ذلك، عليك استخدام مكوّنات العناوين الفردية، التي تتضمّن استجابة واجهة برمجة التطبيقات بالإضافة إلى حقل العنوان المنسَّق.
address_components[] عبارة عن مصفوفة تحتوي على المكونات المنفصلة السارية على هذا العنوان.

يحتوي كل مكون من مكونات العنوان عادةً على الحقول التالية:
- types[] عبارة عن مصفوفة تشير إلى نوع مكوِّن العنوان. اطّلِع على قائمة الأنواع المتوافقة.
- long_name هو الوصف النصي الكامل أو اسم مكوّن العنوان كما هو مكتوب بواسطة Geocoder.
- 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 للحصول على تفاصيل نشاط تجاري محلي، مثل رقم الهاتف وساعات العمل ومراجعات المستخدمين والمزيد. اطّلِع على نظرة عامة على رقم تعريف المكان.
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 إلى كيان مدني من الدرجة الأولى أسفل مستوى البلد. في الولايات المتحدة، تكون هذه المستويات الإدارية ولايات. ولا تعرض جميع الدول هذه المستويات الإدارية. في معظم الحالات، تتطابق الأسماء المختصرة على مستوى ISO_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 التي تُحدِّد مربّع إحاطة لوادي سان فرناندو في لوس أنجلوس إلى عرض هذا الترميز الجغرافي للحي المسمى "Winnetka" في هذا الموقع الجغرافي:

{
  "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:

يُرجى تحديد بلد واحد أو منطقة واحدة فقط. ويتم تجاهل القيم المتعددة، وقد يؤدي ذلك إلى تعذُّر تنفيذ الطلب.
استخدِم فقط العلامات الفرعية للمنطقة المؤلفة من حرفين (تنسيق CLDR لـ Unicode). وستؤدي جميع الإدخالات الأخرى إلى حدوث أخطاء.
لا تتوفّر سوى البُلدان والمناطق المدرَجة في تفاصيل "تغطية النظام الأساسي" في "خرائط 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);
  }
});
}

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

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

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

عرض مثال

تجربة النموذج

Stackblitz.com CodeSandbox.io JSFiddle.net GitPod.io 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 التي تعرضها واجهة برمجة التطبيقات للطرق للحصول على عنوان نقطة فاصلة. لمزيد من المعلومات حول أرقام تعريف الأماكن، اطّلِع على نظرة عامة على أرقام تعريف الأماكن.

عند تقديم 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

عرض مثال

تجربة النموذج

Stackblitz.com CodeSandbox.io JSFiddle.net GitPod.io Google Cloud Shell