نظرة عامة
الترميز الجغرافي هو عملية تحويل العناوين (مثل "1600 Amphitheatre Parkway, Mountain View, CA") في الإحداثيات الجغرافية (مثل خط العرض 37.423021 وخط الطول -122.083739)، والذي يمكنك استخدامه من أجل محدّدات المواقع أو تحديد موضع الخريطة
الترميز الجغرافي العكسي هو عملية تحويل المواقع الجغرافية الإحداثيات إلى عنوان يمكن لشخص عادي قراءته (يُرجى الاطّلاع على الترميز الجغرافي العكسي (البحث عن العنوان)).
يمكنك أيضًا استخدام أداة الترميز الجغرافي للعثور على عنوان المحدد لرقم تعريف المكان.
توفر واجهة برمجة تطبيقات JavaScript للخرائط فئة الترميز الجغرافي في الترميز الجغرافي والترميز الجغرافي العكسي ديناميكيًا من خلال إدخال المستخدم. إذا كان العرض بدلاً من ذلك الذي تريد أن يتم ترميز العناوين الثابتة المعروفة به جغرافيًا، فانظر خدمة ويب لترميز المواقع الجغرافية:
الخطوات الأولى
قبل استخدام خدمة Geocoding في Maps JavaScript API، تأكد أولاً تفعيل واجهة برمجة التطبيقات Geocoding API على Google Cloud Console الذي أعددته لواجهة برمجة تطبيقات JavaScript للخرائط.
لعرض قائمة بواجهات برمجة التطبيقات المفعّلة:
- الانتقال إلى قسم Google Cloud Console:
- انقر على الزر اختيار مشروع، ثم اختَر المشروع نفسه الذي أعددته. لواجهة برمجة تطبيقات JavaScript للخرائط وانقر على فتح.
- من قائمة واجهات برمجة التطبيقات في لوحة البيانات، ابحث عن Geocoding API:
- إذا ظهرت لك واجهة برمجة التطبيقات في القائمة، هذا يعني أنّك جاهز للعمل. إذا لم يتم إدراج واجهة برمجة التطبيقات،
تفعيلها:
- في أعلى الصفحة، اختَر تفعيل واجهة برمجة التطبيقات لعرض علامة التبويب المكتبة بدلاً من ذلك، من القائمة الجانبية اليمنى، انقر على المكتبة.
- ابحث عن Geocoding API، ثم اختَرها من قائمة النتائج.
- انقر على تفعيل. عند انتهاء العملية، تظهر Geocoding API في قائمة واجهات برمجة التطبيقات على لوحة البيانات:
الأسعار والسياسات
التسعير
اعتبارًا من 16 تموز (يوليو) 2018، بدأ تطبيق خطة تسعير "الدفع حسب الاستخدام" الجديدة. للخرائط والمسارات والأماكن. مزيد من المعلومات حول الأسعار والاستخدام الجديدَين في حدود استخدامك لخدمة الترميز الجغرافي في JavaScript، راجع الاستخدام والفوترة لواجهة برمجة تطبيقات Geocoding.
السياسات
يجب أن يتوافق استخدام خدمة الترميز الجغرافي مع السياسات الموضّحة لواجهة برمجة التطبيقات Geocoding API.
طلبات الترميز الجغرافي
الوصول إلى خدمة الترميز الجغرافي غير متزامن، نظرًا لأن واجهة برمجة التطبيقات لخرائط 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
— رمز المنطقة المحدَّد على أنّه محددة على أنها علامة فرعية لمنطقة يونيكود من حرفين (غير رقمية). في معظم الحالات، يتم تعيين هذه العلامات مباشرةً إلى نطاقات المستوى الأعلى التي يتم ترميزها حسب البلد ("نطاق المستوى الأعلى") القيم المكونة من حرفين. وستؤثر المعلمةregion
فقط في لا يتم تقييدها بشكل كامل، تكون النتائج من أداة الترميز الجغرافي. الاطّلاع على مزيد من المعلومات عن انحياز رمز المنطقة أدناه.extraComputations
— القيمة الوحيدة المسموح بها لهذا العنصر المعلمةADDRESS_DESCRIPTORS
. عرض واصفات العناوين لمزيد من التفاصيل.fulfillOnZeroResults
— الوفاء بالوعد بالحصول على حالة ZERO_RESULT في الاستجابة. قد يكون هذا مطلوبًا لأنه حتى مع عدم وجود نتائج ترميز جغرافي، ربما لا تزال هناك تم عرض حقول إضافية لمستوى الاستجابة. عرض يُرجى تنفيذ الطلب عند عدم النتائج للاطّلاع على مزيد من التفاصيل.
استجابات الترميز الجغرافي
تتطلب خدمة الترميز الجغرافي طريقة استدعاء للتنفيذ عند الاسترجاع.
نتائج أداة الترميز الجغرافي. يجب أن يمرر رد الاتصال هذا معاملين للتحفظ على المعلومات
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" (رقم الشارع)، "الجادة 8" (المسار)، "نيويورك" (المدينة) و"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 APIs الأخرى. على سبيل المثال، يمكنك استخدام السمةplace_id
. مع أماكن Google واجهة برمجة التطبيقات للحصول على تفاصيل أي نشاط تجاري محلي، مثل رقم الهاتف وساعات العمل ومراجعات المستخدمين والمزيد. يمكنك الاطّلاع على نظرة عامة على رقم تعريف المكان.postcode_localities[]
هو صفيف يشير إلى جميع المناطق المحلية الواردة في رمز بريدي، ولا تظهر إلا عندما تكون النتيجة رمزًا بريديًا التعليمات البرمجية التي تحتوي على مناطق محلية متعددة.يحتوي
geometry
على المعلومات التالية:- يحتوي
location
على قيمة خط العرض وخط الطول المرمَّزة جغرافيًا. تجدر الإشارة إلى أنّنا نعرض هذا الموقع الجغرافي ككائنLatLng
، وليس كسلسلة منسقة. - تخزِّن ميزة "
location_type
" بيانات إضافية عن القيم المحدّدة الموقع. القيم التالية متاحة حاليًا:- تشير السمة
ROOFTOP
إلى أن النتيجة المعروضة تعكس رمزًا جغرافيًا دقيقًا. RANGE_INTERPOLATED
تشير إلى أن النتيجة المعروضة تعكس قيمة تقريبية (عادةً على طريق) مُدمجة بين نقطتين دقيقتين (على سبيل المثال كتقاطعات). يتم عادةً عرض النتائج التي تم استقراءها عندما لا تتوفر الترميزات الجغرافية للأسطح في عنوان شارع.GEOMETRIC_CENTER
إلى أن النتيجة المعروضة هي المركز الهندسي نتيجة مثل خط متعدد (مثل شارع) أو مضلّع (المنطقة).APPROXIMATE
إلى أن النتيجة التي تم إرجاعها تقريبية.
- تشير السمة
- يخزِّن
viewport
إطار العرض المقترح نتيجة لذلك. - تخزِّن
bounds
(يتم عرضها بشكل اختياري)LatLngBounds
التي يمكن أن تحتوي على النتيجة التي تم إرجاعها بالكامل. تجدر الإشارة إلى أنّ هذه الحدود قد لا تتطابق مع إطار العرض المقترَح. (بالنسبة إلى مثال، تتضمن سان فرانسيسكو Farallon الجزر، وهي جزء من المدينة من الناحية الفنية سيتم عرضها في إطار العرض).
- يحتوي
سيتم عرض العناوين بواسطة برنامج الترميز الجغرافي باستخدام الإعدادات المفضّلة للمتصفح
إعداد اللغة، أو اللغة المحددة عند تحميل JavaScript لواجهة برمجة التطبيقات
باستخدام المعلمة language
. (لمزيد من المعلومات، راجع
الأقلمة.)
أنواع العناوين وأنواع مكونات العناوين
الصفيفة types[]
في
GeocoderResult
إلى
نوع العنوان. قد يتم أيضًا عرض الصفيف types[]
داخل
GeocoderAddressComponent
للإشارة إلى نوع مكون العنوان الخاص. العناوين التي تم إرجاعها
التي يقوم بها أداة الترميز الجغرافي على أنواع متعددة؛ يمكن اعتبار الأنواع علامات.
على سبيل المثال، تمّ وضع علامة على العديد من المدن باستخدام political
و
النوع locality
.
يتم دعم الأنواع التالية وعرضها بواسطة برنامج الترميز الجغرافي في كلٍ من أنواع العناوين وأنواع مكونات العناوين:
- تشير السمة
street_address
إلى عنوان شارع دقيق. - تشير السمة
route
إلى مسار مُسمّى (مثل "US 101"). - تشير
intersection
إلى تقاطع رئيسي، يتألف عادةً من تقاطعين والطرق الرئيسية. - تشير السمة
political
إلى كيان سياسي. عادةً، هذا النوع تشير إلى مضلّع تابع لبعض الإدارة المدنية. - تشير السمة
country
إلى الكيان السياسي الوطني، عادةً ما يكون أعلى نوع طلب يعرضه برنامج الترميز الجغرافي. - تشير القيمة
administrative_area_level_1
إلى القيمة المدنية من الدرجة الأولى. أقل من مستوى البلد. داخل الولايات المتحدة، هذه والمستويات الإدارية هي الولايات. لا تعرض كل الدول هذه والمستويات الإدارية. في معظم الحالات، يكون الإذن الإداري بالوصول إلى مستوى_المنطقة_1 مطابقة إلى حد كبير مع التقسيمات الفرعية ISO 3166-2 وغيرها من القوائم المتداولة ولكن ذلك ليس مضمونًا لأنّ نتائج الترميز الجغرافي تستند إلى مجموعة من الإشارات وبيانات الموقع الجغرافي. - تشير القيمة
administrative_area_level_2
إلى نوع مدني من الرتبة الثانية أقل من مستوى البلد. داخل الولايات المتحدة، هذه والمستويات الإدارية هي المقاطعات. لا تعرض كل الدول هذه والمستويات الإدارية. - تشير القيمة
administrative_area_level_3
إلى نوع مدني من الدرجة الثالثة أقل من مستوى البلد. يشير هذا النوع إلى تقسيم مدني فرعي. لا تعرض جميع الدول هذه المستويات الإدارية. - تشير القيمة
administrative_area_level_4
إلى الرمز المدني من ترتيب رابع أقل من مستوى البلد. يشير هذا النوع إلى تقسيم مدني فرعي. لا تعرض جميع الدول هذه المستويات الإدارية. - تشير السمة
administrative_area_level_5
إلى رمز مدني من الفئة الخامسة أقل من مستوى البلد. يشير هذا النوع إلى تقسيم مدني فرعي. لا تعرض جميع الدول هذه المستويات الإدارية. - تشير السمة
administrative_area_level_6
إلى رمز مدني من الرتبة السادسة أقل من مستوى البلد. يشير هذا النوع إلى تقسيم مدني فرعي. لا تعرض جميع الدول هذه المستويات الإدارية. - تشير القيمة
administrative_area_level_7
إلى الترتيب المدني السابع أقل من مستوى البلد. يشير هذا النوع إلى تقسيم مدني فرعي. لا تعرض جميع الدول هذه المستويات الإدارية. - تشير القيمة
colloquial_area
إلى اسم بديل شائع الاستخدام. للكيان. - تشير السمة
locality
إلى مدينة أو بلدة مدمجة. . - تشير السمة
sublocality
إلى كيان مدني من الدرجة الأولى أسفل المنطقة المحلية. بالنسبة إلى بعض المواقع الجغرافية، قد يظهر أحد الأنواع الإضافية:sublocality_level_1
إلىsublocality_level_5
وكل مستوى من مستويات منطقة محلية فرعية هو كيان مدني. تشير الأرقام الأكبر إلى أن المنطقة الجغرافية. - تشير القيمة
neighborhood
إلى حي معيَّن - تشير السمة
premise
إلى موقع جغرافي مسمّى، وعادةً ما يكون مبنى أو مجموعة مبانٍ تحمل اسمًا شائعًا - تشير القيمة
subpremise
إلى كيان من الدرجة الأولى أسفل اسم مسمّى. موقع جغرافي، عادةً ما يكون مبنى واحد داخل مجموعة من المباني ذات اسم شائع - تشير السمة
plus_code
إلى مرجع موقع جغرافي مشفّر، مشتق من خطوط العرض وخطوط الطول. يمكن استخدام رموز Plus Codes كبديل عناوين الشوارع في أماكن لا توجد فيها هذه الأماكن (حيث تكون المباني غير مرقمة أو غير مرقمة لم تتم تسمية الشوارع). يمكنك الاطّلاع على https://plus.codes. لمزيد من التفاصيل. - تشير السمة
postal_code
إلى رمز بريدي مستخدَم في العنوان البريدي. البريد داخل البلد. - تشير السمة
natural_feature
إلى سمة طبيعية بارزة. - تشير السمة
airport
إلى مطار. - تشير السمة
park
إلى متنزه مُسمّى. - تشير القيمة
point_of_interest
إلى نقطة اهتمام مسماة. وعادةً ما تكون "نقاط الاهتمام" هذه كيانات محلية بارزة لا تتناسب في فئة أخرى، مثل "مبنى دبي" أو "برج إيفل".
تشير القائمة الفارغة من الأنواع إلى عدم وجود أنواع معروفة للنوع المستخدم، مثل Lieu-dit في فرنسا.
بالإضافة إلى ما سبق، قد تتضمّن مكوّنات العنوان الأنواع الواردة أدناه.
ملاحظة: هذه القائمة ليست شاملة و للتغيير.
- تشير السمة
floor
إلى الطابق في عنوان مبنى. - تشير السمة
establishment
عادةً إلى مكان لم الفئات. - تشير السمة
landmark
إلى مكان مجاور يُستخدم كمرجع، للمساعدة في التنقل. - تشير القيمة
point_of_interest
إلى نقطة اهتمام مسماة. - تشير السمة
parking
إلى موقف سيارات أو موقف سيارات. - تشير السمة
post_box
إلى صندوق بريدي معيّن. - تشير السمة
postal_town
إلى مجموعة من المناطق الجغرافية، مثلlocality
وsublocality
، يُستخدمان للعناوين البريدية في بعض البلدان. - أمّا السمة
room
، فيشير إلى الغرفة في عنوان مبنى. - تشير السمة
street_number
إلى رقم الشارع الدقيق. bus_station
وtrain_station
و تشير السمةtransit_station
إلى الموقع الجغرافي لحافلة أو قطار أو محطة عامة. محطة نقل عام.
رموز الحالة
قد يعرض الرمز status
إحدى القيم التالية:
- وتشير السمة
"OK"
إلى عدم حدوث أي أخطاء. تم تحليل العنوان بنجاح وفي وتم عرض رمز جغرافي واحد على الأقل. - تشير القيمة
"ZERO_RESULTS"
إلى أن الترميز الجغرافي كان ناجحًا ولكنه لم يعرض أي نتائج. قد يحدث ذلك إذا تم تمرير برنامج الترميز الجغرافي إلى علامةaddress
غير موجودة. - تشير القيمة
"OVER_QUERY_LIMIT"
إلى أنك تجاوزت حصتك. - تشير القيمة
"REQUEST_DENIED"
إلى أنّه تم رفض طلبك. صفحة الويب ليست الذين يُسمح لهم باستخدام أداة الترميز الجغرافي. - تشير
"INVALID_REQUEST"
بشكل عام إلى أن طلب البحث (address
، السمةcomponents
أوlatlng
) غير متوفّرة. - تشير السمة
"UNKNOWN_ERROR"
إلى تعذّر تنفيذ الطلب تمت معالجتها بسبب خطأ في الخادم. قد يتم تنفيذ الطلب بنجاح إذا يُرجى إعادة المحاولة. - تشير القيمة
"ERROR"
إلى انتهاء مهلة الطلب أو إلى حدوث خطأ مشكلة في الاتصال بخوادم Google. قد يتم تنفيذ الطلب بنجاح إذا يُرجى إعادة المحاولة.
في هذا المثال، نقوم بترميز عنوان جغرافيًا ووضع علامة في الصفحة المعروضة قيم خطوط الطول والعرض. لاحظ أنه يتم تمرير المعالج الدالة المجهولة الحرفية.
var geocoder; var map; function initialize() { geocoder = new google.maps.Geocoder(); var latlng = new google.maps.LatLng(-34.397, 150.644); var mapOptions = { zoom: 8, center: latlng } map = new google.maps.Map(document.getElementById('map'), mapOptions); } function codeAddress() { var address = document.getElementById('address').value; geocoder.geocode( { 'address': address}, function(results, status) { if (status == 'OK') { map.setCenter(results[0].geometry.location); var marker = new google.maps.Marker({ map: map, position: results[0].geometry.location }); } else { alert('Geocode was not successful for the following reason: ' + status); } }); } <body onload="initialize()"> <div id="map" style="width: 320px; height: 480px;"></div> <div> <input id="address" type="textbox" value="Sydney, NSW"> <input type="button" value="Encode" onclick="codeAddress()"> </div> </body>
انحياز إطار العرض
يمكنك أن تطلب من خدمة الترميز الجغرافي لتفضيل النتائج ضمن نطاق
إطار العرض (يتم التعبير عنه كمربع إحاطة). يمكنك إجراء ذلك من خلال تعيين
المَعلمة bounds
ضمن الكائن GeocoderRequest
حرفي لتحديد حدود إطار العرض هذا. لاحظ أن التحيز فقط
يفضّل النتائج داخل الحدود، إذا كانت هناك نتائج أكثر صلة
خارج هذه الحدود، فيمكن أن يتم تضمينها.
على سبيل المثال، الرمز الجغرافي لـ "وينيتكا" عادةً هذه الضاحية في شيكاغو:
{ "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
. هذه المعلمة
يأخذ رمز منطقة، محدد في شكل يونيكود من حرفين (غير رقمي)
المنطقة الفرعية. يتم تعيين هذه العلامات مباشرةً إلى نطاقات المستوى الأعلى التي يتم ترميزها حسب البلد ("نطاق المستوى الأعلى")
قيم مؤلفة من حرفين مثل "uk" في co.uk على سبيل المثال. في بعض الحالات،
تتوافق علامة region
أيضًا مع رموز ISO-3166-1 التي قد
عن قيم ccTLD (على سبيل المثال، "GB" تعني "بريطانيا العظمى").
عند استخدام مَعلمة region
:
- حدِّد بلدًا واحدًا أو منطقة واحدة فقط. يتم تجاهل القيم المتعددة، إلى فشل الطلب.
- استخدِم فقط علامات فرعية للمنطقة من حرفين (تنسيق Unicode CLDR). كل ما غير ذلك المدخلات إلى حدوث أخطاء.
- فقط البلدان والمناطق المدرَجة في Google تتوفّر تفاصيل تغطية منصة "خرائط 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، وليس أو
يتكون فلتر المكونات من عنصر واحد أو أكثر من العناصر التالية:
- يتطابق
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
غير
تم ملؤه في هذه الحالة. إذا تم توفير القيمة true للمَعلمة fulfillOnZeroResults
،
عدم الإخلال بالوعد ويمكن الوصول إلى هذه الحقول الإضافية من خلال الوعد إن وجدت.
في ما يلي مثال على هذا السلوك لخط العرض/خط الطول في أنتاركتيكا.
على الرغم من عدم وجود نتائج ترميز جغرافي عكسي، لا يزال بإمكاننا طباعة رمز Plus Codes
إذا حددنا السمة 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({ '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"
عندما يكون إحداثي الإدخال قريبًا من حافة المنطقة.
تغطية واصف العناوين
لا تتوفّر هذه الميزة إلا في البلدان.
هذه ميزة معاينة ونشكرك على إرسال ملاحظاتك. يُرجى إرسال رسالة إلكترونية لنا على [email protected].
الترميز الجغرافي العكسي (البحث عن العنوان)
يشير مصطلح الترميز الجغرافي عمومًا إلى ترجمة نص إلى موقع جغرافي على الخريطة. عملية القيام بالعكس، ترجمة موقع على الخريطة إلى عنوان يمكن للإنسان قراءته الترميز الجغرافي العكسي.
بدلاً من توفير حرف 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 APIs الأخرى. بالنسبة
على سبيل المثال، يمكنك توفير السمة 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;
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;