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

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

تصف هذه الصفحة الخدمة من جهة العميل المتاحة في Maps JavaScript API. إذا كنت تريد العمل مع خدمات الويب من "خرائط Google" على خادمك، يمكنك الاطّلاع على عميل Node.js في "خرائط Google". تقدّم الصفحة في هذا الرابط أيضًا برنامج Java Client وPython وبرنامج Go لخدمات "خرائط Google".

نظرة عامة

يمكنك أيضًا الاطّلاع على مرجع واجهة برمجة تطبيقات JavaScript للخرائط: أداة ترميز المواقع الجغرافية

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

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

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

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

البدء

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

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

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

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

التسعير

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

السياسات

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

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

إنّ الوصول إلى خدمة ترميز المواقع الجغرافية غير متزامن، لأنّ "واجهة برمجة تطبيقات "خرائط 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: رمز المنطقة المحدَّد على شكل علامة فرعية لمنطقة يونيكود مكوّنة من حرفَين (غير رقمية). وفي معظم الحالات، يتم ربط هذه العلامات مباشرةً بقيم مكوّنة من حرفين لـ "نطاق 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 هي الوصف النصي الكامل أو اسم مكوّن العنوان كما هو وارد في برنامج 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 API الأخرى. على سبيل المثال، يمكنك استخدام place_id مع مكتبة واجهة برمجة تطبيقات أماكن Google للحصول على تفاصيل نشاط تجاري محلي، مثل رقم الهاتف وساعات العمل ومراجعات المستخدمين وغير ذلك. يمكنك الاطّلاع على نظرة عامة على رقم تعريف المكان.
• تمثّل السمة postcode_localities[] مصفوفةً تشير إلى جميع المناطق المحلية المضمّنة في رمز بريدي، ويمكن العثور عليها فقط في حال كانت النتيجة عبارة عن رمز بريدي يحتوي على عدة مناطق محلية.

• يحتوي geometry على المعلومات التالية:

  • يحتوي location على قيمة خط العرض وخط الطول المشفّرة. يُرجى العِلم أنّنا نعرض هذا الموقع الجغرافي ككائن LatLng، وليس كسلسلة منسّقة.
  • تخزِّن خدمة location_type بيانات إضافية حول الموقع الجغرافي المحدّد. في ما يلي القيم المتوافقة:
    • تشير السمة ROOFTOP إلى أن النتيجة المعروضة تعكس رمزًا جغرافيًا دقيقًا.
    • تشير السمة RANGE_INTERPOLATED إلى أن النتيجة المعروضة تعكس تقريبًا (على طريق عادةً) بين نقطتين دقيقتَين (مثل التقاطعات). ويتم عادةً عرض النتائج التي يتم وضعها على الشاشة عندما لا تتوفّر الرموز الجغرافية على السطح لعنوان شارع.
    • تشير السمة GEOMETRIC_CENTER إلى أن النتيجة المعروضة هي المركز الهندسي لنتيجة مثل خط متعدد (مثل شارع) أو شكل مضلع (منطقة).
    • تشير السمة APPROXIMATE إلى أن النتيجة المعروضة تقريبية.
  
  
  • يخزّن السمة viewport إطار العرض المقترَح للنتيجة المعروضة.
  • يخزّن السمة bounds (اختياري) السمة LatLngBounds التي يمكن أن تحتوي على النتيجة المعروضة بالكامل. تجدر الإشارة إلى أن هذه الحدود قد لا تتطابق مع إطار العرض المقترح. (على سبيل المثال، تضم مدينة سان فرانسيسكو جزر فرالون التي تشكّل جزءًا فنيًا من المدينة، ولكن يجب عدم عرضها في إطار العرض.)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

بدلاً من تقديم نص address، أدخِل زوجًا من خطوط الطول والعرض في المعلَمة location.

ملاحظة: في حال تضمين المَعلمة componentRestrictions في الطلب، سيتم تجاهل المَعلمة location.

يوضّح المثال التالي ترميز خطّي العرض/الطول ويركّز الخريطة على هذا الموقع الجغرافي، ما يؤدي إلى إظهار نافذة معلومات تحمل العنوان المنسّق:

TypeScript

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 8,
      center: { lat: 40.731, lng: -73.997 },
    }
  );
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  (document.getElementById("submit") as HTMLElement).addEventListener(
    "click",
    () => {
      geocodeLatLng(geocoder, map, infowindow);
    }
  );
}

function geocodeLatLng(
  geocoder: google.maps.Geocoder,
  map: google.maps.Map,
  infowindow: google.maps.InfoWindow
) {
  const input = (document.getElementById("latlng") as HTMLInputElement).value;
  const latlngStr = input.split(",", 2);
  const latlng = {
    lat: parseFloat(latlngStr[0]),
    lng: parseFloat(latlngStr[1]),
  };

  geocoder
    .geocode({ location: latlng })
    .then((response) => {
      if (response.results[0]) {
        map.setZoom(11);

        const marker = new google.maps.Marker({
          position: latlng,
          map: map,
        });

        infowindow.setContent(response.results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

ملاحظة: اقرأ الدليل حول استخدام TypeScript و"خرائط Google".

JavaScript

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 8,
    center: { lat: 40.731, lng: -73.997 },
  });
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  document.getElementById("submit").addEventListener("click", () => {
    geocodeLatLng(geocoder, map, infowindow);
  });
}

function geocodeLatLng(geocoder, map, infowindow) {
  const input = document.getElementById("latlng").value;
  const latlngStr = input.split(",", 2);
  const latlng = {
    lat: parseFloat(latlngStr[0]),
    lng: parseFloat(latlngStr[1]),
  };

  geocoder
    .geocode({ location: latlng })
    .then((response) => {
      if (response.results[0]) {
        map.setZoom(11);

        const marker = new google.maps.Marker({
          position: latlng,
          map: map,
        });

        infowindow.setContent(response.results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

window.initMap = initMap;
index.js

ملاحظة: يتم تجميع JavaScript من المقتطف TypeScript.

عرض مثال

تجربة عيّنة من المحتوى

JSFiddle.net CodeSandbox.io Google Cloud Shell

وفي المثال السابق، عرضنا النتيجة الأولى من خلال اختيار results[0]. غالبًا ما يعرض الباحث الجغرافي العكسي أكثر من نتيجة واحدة. إنّ العناوين الجغرافية التي تم ترميزها ليست مجرد عناوين بريدية، ولكن هي أي طريقة لتسمية الموقع الجغرافي. على سبيل المثال، عند إضافة ترميز جغرافي إلى نقطة في مدينة شيكاغو، قد يتم تصنيف النقطة التي تحمل رموزًا جغرافية كعنوان شارع، كالمدينة (شيكاغو)، كولاية (إلينوي) أو كبلد (الولايات المتحدة). تمثّل كل هذه العناوين عناوين أدوات الترميز. وتعرض أداة ترميز البيانات العكسية كل هذه النتائج.

يتطابق صانع المحتوى العكسي مع الكيانات السياسية (البلدان والمقاطعات والمدن والأحياء) وعناوين الشوارع والرموز البريدية.

إليك مثال على قائمة العناوين التي قد يعرضها طلب البحث أعلاه:

results[0].formatted_address: "277 Bedford Ave, Brooklyn, NY 11211, USA"
results[1].formatted_address: "Grand St/Bedford Av, Brooklyn, NY 11211, USA"
results[2].formatted_address: "Williamsburg, Brooklyn, NY, USA"
results[3].formatted_address: "Brooklyn, NY, USA"
results[4].formatted_address: "New York, NY, USA"
results[5].formatted_address: "Brooklyn, NY 11211, USA"
results[6].formatted_address: "Kings County, NY, USA"
results[7].formatted_address: "New York-Northern New Jersey-Long Island, NY-NJ-PA, USA"
results[8].formatted_address: "New York Metropolitan Area, USA"
results[9].formatted_address: "New York, USA"

يتم عرض العناوين بالترتيب من الأفضل إلى الأقل مطابقة. وبوجهٍ عام، إن العنوان الأكثر دقة هو النتيجة الأكثر بروزًا، كما هو الحال في هذه الحالة. يُرجى العِلم أننا نعرض أنواعًا مختلفة من العناوين، بدءًا من عنوان الشارع الأكثر تحديدًا وصولاً إلى الكيانات السياسية الأقل تحديدًا، مثل الأحياء والمدن والمقاطعات والولايات وما إلى ذلك. وإذا كنت تريد مطابقة عنوان أكثر عمومية، يمكنك فحص الحقل results[].types.

ملاحظة: إنّ ترميز المواقع الجغرافية العكسي ليس علمًا دقيقًا. سيحاول مشرف الموقع الجغرافي العثور على أقرب موقع جغرافي قابل للتعامل معه ضمن حدود تساهل معيّنة.

استرداد عنوان لرقم تعريف مكان

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

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

• address
• latLng
• location
• componentRestrictions

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

TypeScript

// Initialize the map.
function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 8,
      center: { lat: 40.72, lng: -73.96 },
    }
  );
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  (document.getElementById("submit") as HTMLElement).addEventListener(
    "click",
    () => {
      geocodePlaceId(geocoder, map, infowindow);
    }
  );
}

// This function is called when the user clicks the UI button requesting
// a geocode of a place ID.
function geocodePlaceId(
  geocoder: google.maps.Geocoder,
  map: google.maps.Map,
  infowindow: google.maps.InfoWindow
) {
  const placeId = (document.getElementById("place-id") as HTMLInputElement)
    .value;

  geocoder
    .geocode({ placeId: placeId })
    .then(({ results }) => {
      if (results[0]) {
        map.setZoom(11);
        map.setCenter(results[0].geometry.location);

        const marker = new google.maps.Marker({
          map,
          position: results[0].geometry.location,
        });

        infowindow.setContent(results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

ملاحظة: اقرأ الدليل حول استخدام TypeScript و"خرائط Google".

JavaScript

// Initialize the map.
function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 8,
    center: { lat: 40.72, lng: -73.96 },
  });
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  document.getElementById("submit").addEventListener("click", () => {
    geocodePlaceId(geocoder, map, infowindow);
  });
}

// This function is called when the user clicks the UI button requesting
// a geocode of a place ID.
function geocodePlaceId(geocoder, map, infowindow) {
  const placeId = document.getElementById("place-id").value;

  geocoder
    .geocode({ placeId: placeId })
    .then(({ results }) => {
      if (results[0]) {
        map.setZoom(11);
        map.setCenter(results[0].geometry.location);

        const marker = new google.maps.Marker({
          map,
          position: results[0].geometry.location,
        });

        infowindow.setContent(results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

window.initMap = initMap;
index.js

ملاحظة: يتم تجميع JavaScript من المقتطف TypeScript.

عرض مثال

تجربة عيّنة من المحتوى

JSFiddle.net CodeSandbox.io Google Cloud Shell