نظرة عامة
الترميز الجغرافي هو عملية تحويل العناوين (مثل "1600 Amphitheatre Parkway, Mountain View, CA") إلى إحداثيات جغرافية (مثل latitude 37.423021 وخط الطول -122.083739)، والتي يمكنك استخدامها لوضع العلامات أو وضع الخريطة.
الترميز الجغرافي العكسي هو عملية تحويل الإحداثيات الجغرافية إلى عنوان يمكن للمستخدمين قراءته (راجع الترميز الجغرافي العكسي (البحث عن العنوان)).
يمكنك أيضًا استخدام أداة الترميز الجغرافي للعثور على عنوان رقم تعريف المكان.
توفّر واجهة برمجة تطبيقات JavaScript للخرائط فئة برنامج ترميز جغرافي للترميز الجغرافي وعكس الترميز الجغرافي بشكل ديناميكي من إدخال المستخدم. وإذا كنت تريد ترميز العناوين الثابتة والمعروفة جغرافيًا، يمكنك الاطّلاع على خدمة الترميز الجغرافي.
البدء
قبل استخدام خدمة الترميز الجغرافي في واجهة برمجة تطبيقات JavaScript للخرائط، تأكّد أولاً من تفعيل واجهة برمجة تطبيقات الترميز الجغرافي في Google Cloud Console، في المشروع نفسه الذي أعددته لواجهة برمجة تطبيقات JavaScript للخرائط.
لعرض قائمة بواجهات برمجة التطبيقات التي تم تمكينها:
- انتقِل إلى Google Cloud Console.
- انقر على زر اختيار مشروع، ثم حدد المشروع نفسه الذي أعددته لواجهة برمجة تطبيقات جافا سكريبت للخرائط وانقر على فتح.
- من قائمة واجهات برمجة التطبيقات في لوحة البيانات، ابحث عن واجهة برمجة تطبيقات الترميز الجغرافي.
- إذا كنت ترى واجهة برمجة التطبيقات في القائمة، فأنت على أتم استعداد. في حال عدم إدراج واجهة برمجة التطبيقات،
يمكنك تفعيلها:
- في أعلى الصفحة، اختَر تفعيل واجهة برمجة التطبيقات لعرض علامة التبويب المكتبة. بدلاً من ذلك، اختَر المكتبة من القائمة الجانبية اليمنى.
- ابحث عن واجهة برمجة التطبيقات للترميز الجغرافي، ثم اخترها من قائمة النتائج.
- اختَر تفعيل. عند انتهاء العملية، تظهر واجهة برمجة تطبيقات الترميز الجغرافي في قائمة واجهات برمجة التطبيقات في لوحة البيانات.
التسعير والسياسات
التسعير
اعتبارًا من 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
.
يوضّح المثال التالي ترميزًا جغرافيًا لقيمة خط العرض/خط الطول ويحدّد الخريطة في ذلك الموقع الجغرافي، ما يؤدي إلى ظهور نافذة معلومات تتضمّن العنوان المنسَّق:
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;
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;
تجربة النموذج
في المثال السابق، عرضنا النتيجة الأولى باختيار
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;
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;