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

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

نظرة عامة

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

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

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

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

البدء

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

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

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

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

السعر

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

السياسات

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

طلبات ترميز المواقع الجغرافية

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

يمكنك الوصول إلى خدمة ترميز المواقع الجغرافية في Google Maps API ضمن الرمز من خلال عنصر الكائن google.maps.Geocoder. تبدأ الطريقة Geocoder.geocode() طلبًا لخدمة الترميز الجغرافي، حيث تمرِّر عنصر GeocoderRequest حرفيًا يحتوي على عبارات الإدخال وطريقة استدعاء لتنفيذها عند استلام الاستجابة.

يحتوي الحرف GeocoderRequest للعنصر على الحقول التالية:

{
 address: string,
 location: LatLng,
 placeId: string,
 bounds: LatLngBounds,
 componentRestrictions: GeocoderComponentRestrictions,
 region: string
}

المعلّمات المطلوبة: يجب تقديم معلّمة واحدة فقط من الحقول التالية:

  • address — العنوان الذي تريد ترميزه جغرافيًا.
    أو
    locationLatLng (أو LatLngLiteral) التي تريد الحصول على أقرب عنوان يمكن للمستخدمين قراءتها. ينفِّذ أداة الترميز جغرافيًا ترميزًا عكسيًا. راجِع الترميز الجغرافي العكسي للحصول على مزيد من المعلومات.
    أو
    placeId — رقم تعريف المكان الذي تريد الحصول عليه لأقرب عنوان يمكن للمستخدمين قراءته. اطّلِع على مزيد من المعلومات عن استرداد عنوان لرقم تعريف مكان.

المعلّمات الاختيارية:

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

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

  • السمة address_components[] هي مصفوفة تحتوي على المكوّنات المنفصلة التي تنطبق على هذا العنوان.

    عادةً ما يحتوي كل مكوّن من عناوين العناوين على الحقول التالية:

    • السمة types[] هي مصفوفة تشير إلى type لمكوّن العنوان. راجِع قائمة الأنواع المتوافقة.
    • long_name هو الوصف الكامل أو اسم مكوّن العنوان الذي يعرضه برنامج الترميز الجغرافي.
    • short_name هو اسم نصي مختصر لمكوّن العنوان إذا كان متاحًا. على سبيل المثال، قد يحتوي مكوّن عنوان لولاية ألاسكا على long_name من "ألاسكا" وshort_name من "ألاسكا" باستخدام الاختصار البريدي المكوّن من حرفين.

    يُرجى ملاحظة الحقائق التالية حول المصفوفة 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 التي يمكن أن تحتوي على النتيجة المعروضة بالكامل. تجدر الإشارة إلى أن هذه الحدود قد لا تتطابق مع إطار العرض المقترَح. (على سبيل المثال، تتضمن سان فرانسيسكو جزر فارالون، التي تُعتبر جزءًا فنيًا من المدينة، ولكن يجب عدم عرضها في إطار العرض.)

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

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

تشير المصفوفة types[] في GeocoderResult إلى نوع العنوان. يمكن أيضًا عرض المصفوفة types[] ضمن GeocoderAddressComponent للإشارة إلى نوع مكوّن العنوان المحدّد. قد تكون العناوين التي يعرضها أداة الترميز متعددة الأنواع، ويمكن اعتبار الأنواع كعلامات. على سبيل المثال، تم وضع علامة على عدة مدن بالنوعين political وlocality.

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

  • يشير street_address إلى عنوان شارع دقيق.
  • يشير route إلى مسار مُسمى (مثل "US 101").
  • تشير علامة intersection إلى تقاطع طرق رئيسي، وعادةً ما يتألف من طريقين رئيسيين.
  • يشير political إلى كيان سياسي. ويشير هذا النوع عادةً إلى مضلّع محدّد للإدارة المدنية.
  • ويشير country إلى الكيان السياسي الوطني، وهو عادةً أعلى نوع ترتيب يعرضه الموقع الجغرافي.
  • يشير administrative_area_level_1 إلى كيان مدني من الدرجة الأولى أسفل مستوى البلد. تقع هذه المستويات الإدارية داخل الولايات المتحدة. يُرجى العِلم أنّه لا يتم عرض هذه المستويات الإدارية في جميع البلدان. في معظم الحالات، ستتطابق الأسماء الإدارية_area_level_1 إلى حد كبير مع الأقسام الفرعية وفقًا لمعايير ISO 3166-2 وغيرها من القوائم المتداولة على نطاق واسع، إلا أن ذلك لا يضمن حدوث ذلك لأن نتائج الترميز الجغرافي تستند إلى مجموعة متنوعة من الإشارات وبيانات الموقع الجغرافي.
  • يشير administrative_area_level_2 إلى كيان مدني من المستوى الثاني أسفل مستوى البلد. في الولايات المتحدة، تكون هذه المستويات الإدارية مقاطعات. يُرجى العِلم أنّه لا يتم عرض هذه المستويات الإدارية في جميع البلدان.
  • تشير السمة administrative_area_level_3 إلى كيان مدني تابع لطرف ثالث أسفل مستوى البلد. يشير هذا النوع إلى تقسيم مدني ثانوي. لا تعرض جميع الدول هذه المستويات الإدارية.
  • تشير القيمة administrative_area_level_4 إلى كيان مدني من المستوى الرابع أسفل مستوى البلد. يشير هذا النوع إلى تقسيم مدني ثانوي. لا تعرض جميع الدول هذه المستويات الإدارية.
  • تشير الخاصية administrative_area_level_5 إلى كيان مدني من المستوى الخامس أسفل مستوى البلد. يشير هذا النوع إلى تقسيم مدني ثانوي. لا تعرض جميع الدول هذه المستويات الإدارية.
  • تشير السمة administrative_area_level_6 إلى كيان مدني بالمستوى السادس أسفل مستوى البلد. يشير هذا النوع إلى تقسيم مدني ثانوي. لا تعرض جميع الدول هذه المستويات الإدارية.
  • تشير الخاصية administrative_area_level_7 إلى كيان مدني من المستوى السابع أسفل مستوى البلد. يشير هذا النوع إلى تقسيم مدني ثانوي. لا تعرض جميع الدول هذه المستويات الإدارية.
  • تشير السمة colloquial_area إلى اسم بديل شائع الاستخدام للكيان.
  • ويشير locality إلى كيان سياسي مرتبط بالمدينة أو البلدة.
  • يشير sublocality إلى كيان مدني من الدرجة الأولى أسفل منطقة محلية. بالنسبة إلى بعض المواقع الجغرافية، قد تتلقى أحد الأنواع الإضافية: sublocality_level_1 إلى sublocality_level_5. كل مستوى من المناطق المحلية هو كيان مدني. وتشير الأرقام الأكبر إلى منطقة جغرافية أصغر.
  • يشير neighborhood إلى حي مُسمّى
  • يشير premise إلى موقع جغرافي مُسمّى، وعادةً ما يكون مبنى أو مجموعة مبانٍ تحمل الاسم الشائع.
  • يشير subpremise إلى كيان من المستوى الأول أسفل موقع معيّن، ويكون عادةً مبنى فرديًا ضمن مجموعة من المباني التي تحمل اسمًا شائعًا.
  • يشير plus_code إلى مرجع موقع مشفّر، مشتق من خط الطول وخط العرض. يمكن استخدام رموز Plus Codes كبديل لعناوين الشوارع في الأماكن التي لا توجد فيها (حيث لا يتم ترقيم المباني أو عدم تسمية الشوارع). يمكنك الاطّلاع على https://plus.codes لمعرفة التفاصيل.
  • يشير postal_code إلى رمز بريدي يُستخدم لمعالجة البريد داخل البلد.
  • تشير علامة natural_feature إلى ميزة طبيعية بارزة.
  • يشير airport إلى مطار.
  • يشير park إلى منتزه محدد.
  • تشير علامة point_of_interest إلى نقطة اهتمام مُعنونة. عادةً ما تكون "نقاط الاهتمام" هذه كيانات محلية بارزة لا تتناسب بسهولة مع فئة أخرى، مثل "مبنى إمباير ستيت" أو "برج إيفل".

تشير قائمة الأنواع الفارغة إلى عدم توفّر أنواع معروفة لمكوّن العنوان المعيّن، مثل Lieu-dit في فرنسا.

بالإضافة إلى ما ورد أعلاه، قد تتضمن مكوّنات العنوان الأنواع أدناه.

ملاحظة: هذه القائمة ليست شاملة، وتخضع للتغيير.

  • يشير floor إلى طابق عنوان المبنى.
  • تشير الخاصية establishment عادةً إلى مكان لم يتم تصنيفه بعد.
  • تشير السمة landmark إلى مكان مجاور يتم استخدامه كمرجع، للمساعدة في التنقّل.
  • تشير علامة point_of_interest إلى نقطة اهتمام مُعنونة.
  • يشير parking إلى موقف للسيارات أو بنية موقف سيارات.
  • post_box يشير إلى صندوق بريدي محدد.
  • يشير postal_town إلى مجموعة من المناطق الجغرافية، مثل locality وsublocality، ويُستخدم للعناوين البريدية في بعض البلدان.
  • يشير room إلى غرفة عنوان المبنى.
  • يشير street_number إلى رقم الشارع الدقيق.
  • تشير السمات bus_station وtrain_station وtransit_station إلى الموقع الجغرافي للحافلة أو القطار أو النقل العام.

رموز الحالة

قد يعرض الرمز status إحدى القيم التالية:

  • تشير القيمة "OK" إلى عدم حدوث أي أخطاء، وقد تم تحليل العنوان بنجاح وعرض ما لا يقل عن رمز جغرافي واحد.
  • تشير عبارة "ZERO_RESULTS" إلى أنّ الترميز تم بنجاح ولكن لم يتم العثور على أي نتائج. ويمكن أن يحدث ذلك في حال تمرير أداة الترميز address بدون توفُّر.
  • يشير "OVER_QUERY_LIMIT" إلى أنك تجاوزت حصتك.
  • ويشير "REQUEST_DENIED" إلى أنه تم رفض طلبك. ولا يُسمح لصفحة الويب باستخدام أداة ترميز المواقع الجغرافية.
  • تشير السمة "INVALID_REQUEST" بشكل عام إلى أنّ طلب البحث (address أو components أو latlng) غير متوفّر.
  • تشير القيمة "UNKNOWN_ERROR" إلى أنّه تعذّرت معالجة الطلب بسبب خطأ في الخادم. قد ينجح الطلب في حال إعادة المحاولة.
  • يشير "ERROR" إلى أن المهلة المحددة للطلب أو حدثت مشكلة أثناء التواصل مع خوادم Google. قد ينجح الطلب في حال إعادة المحاولة.

في هذا المثال، نعمل على ترميز العنوان الجغرافي ووضع علامة على قيم خطوط الطول والعرض. لاحظ أن المعالج يتم تمريره كدالة حرفية مجهولة.

  var geocoder;
  var map;
  function initialize() {
    geocoder = new google.maps.Geocoder();
    var latlng = new google.maps.LatLng(-34.397, 150.644);
    var mapOptions = {
      zoom: 8,
      center: latlng
    }
    map = new google.maps.Map(document.getElementById('map'), mapOptions);
  }

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

<body onload="initialize()">
 <div id="map" style="width: 320px; height: 480px;"></div>
  <div>
    <input id="address" type="textbox" value="Sydney, NSW">
    <input type="button" value="Encode" onclick="codeAddress()">
  </div>
</body>

عرض مثال:

انحياز إطار العرض

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

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

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

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

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

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

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

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

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

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

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

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

  • يطابق 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 APIs الأخرى. على سبيل المثال، يمكنك توفير السمة 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;
عرض مثال

جرّب عيّنة