أرقام تعريف الأماكن

اختَر النظام الأساسي: Android iOS JavaScript خدمة الويب

تحدد أرقام تعريف الأماكن بشكل فريد أحد الأماكن في قاعدة بيانات "أماكن Google" و"خرائط Google". يتم قبول أرقام تعريف الأماكن في طلبات واجهات برمجة تطبيقات "خرائط Google" التالية:

  • استرداد عنوان لرقم تعريف المكان في خدمة الويب Geocode API وخدمة الترميز الجغرافي، وMaps JavaScript API
  • تحديد نقاط المنشأ والوجهة والطريق المتوسطة في خدمة الويب Directions API والاتجاهات في الخدمة وMaps JavaScript API
  • تحديد المصادر والوجهات في خدمة الويب Mamax API وService Matrix Service وMaps JavaScript API
  • جارٍ استرداد تفاصيل المكان في خدمة الويب لواجهة برمجة التطبيقات للأماكن، وحزمة تطوير البرامج الأماكن للأماكن المخصصة لنظام التشغيل Android.
  • استخدام معلمات معرّف المكان في واجهة برمجة تطبيقات تضمين الخرائط.
  • جارٍ استرداد طلبات البحث في عناوين URL للخرائط.
  • يتم عرض حدود السرعة في Roads API.
  • العثور على المضلّعات الحدودية وتصميمها باستخدام أنماط مستندة إلى بيانات للحدود

العثور على رقم تعريف مكان معيّن

هل تبحث عن معرّف مكان معيّن؟ استخدِم أداة البحث عن معرّف المكان أدناه للبحث عن مكان والحصول على معرّفه:

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

نظرة عامة

رقم تعريف المكان هو معرّف نصي يحدِّد مكانًا بشكلٍ فريد. قد يختلف طول المعرّف (ليس هناك حد أقصى لطول معرّفات الأماكن). أمثلة:

  • ChIJgUbEo8cfqokR5lP9_Wh_DaM
  • GhIJQWDl0CIeQUARxks3icF8U8A
  • EicxMyBNYXJrZXQgU3QsIFdpbG1pbmd0b24sIE5DIDI4NDAxLCBVU0EiGhIYChQKEgnRTo6ixx-qiRHo_bbmkCm7ZRAN
  • EicxMyBNYXJrZXQgU3QsIFdpbG1pbmd0b24sIE5DIDI4NDAxLCBVU0E
  • IhoSGAoUChIJ0U6OoscfqokR6P225pApu2UQDQ

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

يمكنك استخدام رقم تعريف المكان نفسه عبر واجهة برمجة تطبيقات الأماكن وعدد من واجهات برمجة تطبيقات "منصة خرائط Google". على سبيل المثال، يمكنك استخدام رقم تعريف المكان نفسه للإشارة إلى مكان معيّن في PLACES API وMaps JavaScript API وواجهة برمجة تطبيقات ترميز المواقع الجغرافية وMaps Include API وواجهة برمجة تطبيقات الطرق.

استرداد تفاصيل المكان باستخدام رقم تعريف المكان

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

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

مثال باستخدام الأماكن

باستخدام واجهة برمجة تطبيقات الأماكن، يمكنك العثور على رقم تعريف المكان من خلال تقديم طلب البحث عن الأماكن.

المثال التالي هو طلب بحث عن أماكن من النوع "مطعم" ضمن نطاق جغرافي يبلغ 1,500 متر حول نقطة في "سيدني" في أستراليا، ويحتوي على الكلمة "رحلة بحرية":

https://maps.googleapis.com/maps/api/place/nearbysearch/json?location=-33.8670522,151.1957362&radius=1500&type=restaurant&keyword=cruise&key=YOUR_API_KEY

تتضمّن الإجابة رقم تعريف مكان في الحقل place_id، كما هو موضّح في هذا المقتطف:

{
  "html_attributions" : [],
  "results" : [
    {
      "geometry" : {
        "location" : {
          "lat" : -33.870775,
          "lng" : 151.199025
        }
      },
      ...
      "place_id" : "ChIJrTLr-GyuEmsRBfy61i59si0",
      ...
    }
  ],
  "status" : "OK"
}

للحصول على وصف لجميع الحقول في الرد، يُرجى الاطّلاع على مستندات البحث عن الأماكن.

يمكنك الآن إرسال طلب تفاصيل المكان، وإدراج رقم تعريف المكان في المعلَمة place_id:

https://maps.googleapis.com/maps/api/place/details/json?place_id=ChIJrTLr-GyuEmsRBfy61i59si0&key=YOUR_API_KEY

حفظ أرقام تعريف الأماكن لاستخدامها لاحقًا

يتم إعفاء أرقام تعريف الأماكن من قيود التخزين المؤقت المذكورة في الفقرة 3.2.3(أ) من بنود خدمة "منصة خرائط Google". ولذلك، يمكنك تخزين قيم معرّف المكان لاستخدامه لاحقًا.

إعادة تحميل أرقام تعريف الأماكن المخزّنة

ننصح بإعادة تحميل أرقام تعريف الأماكن إذا كانت عمرها أكثر من 12 شهرًا. يمكنك إعادة تحميل أرقام تعريف الأماكن بدون أي رسوم من خلال تقديم طلب تفاصيل المكان، مع تحديد الحقل place_id فقط في المعلَمة fields.

على سبيل المثال: 

  https://maps.googleapis.com/maps/api/place/details/json?place_id=ChIJ05IRjKHxEQ0RJLV_5NLdK2w&fields=place_id&key=YOUR_API_KEY

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

رموز الخطأ عند استخدام أرقام تعريف الأماكن

يشير رمز الحالة INVALID_REQUEST إلى أنّ رقم تعريف المكان المحدّد غير صالح. يمكن عرض INVALID_REQUEST عند اقتطاع رقم تعريف المكان أو تعديله بأي طريقة أخرى، ولم يعُد صحيحًا.

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

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

  • عناوين الشوارع التي لا تتوفّر في "خرائط Google" كعناوين دقيقة، ولكن يتم استنتاجها من مجموعة من العناوين.
  • شرائح مسار طويل، حيث يحدّد الطلب أيضًا المدينة أو المنطقة المحلية
  • تقاطعات:
  • الأماكن التي تتضمن مكوّن عنوان من النوع subpremise.

وتكون هذه المعرّفات غالبًا على شكل سلسلة طويلة (ليس هناك حد أقصى لطول معرّفات الأماكن). على سبيل المثال:

EpID4LC14LC_4LCo4LCv4LGN4LCo4LCX4LCw4LGNIC0g4LC44LGI4LCm4LGN4LCs4LC-4LCm4LGNIOCwsOCxi-CwoeCxjeCwoeCxgSAmIOCwteCwv-CwqOCwr-CxjSDgsKjgsJfgsLDgsY0g4LCu4LGG4LCv4LC_4LCo4LGNIOCwsOCxi-CwoeCxjeCwoeCxgSwg4LC14LC_4LCo4LCv4LGNIOCwqOCwl-CwsOCxjSDgsJXgsL7gsLLgsKjgsYAsIOCwsuCwleCxjeCwt-CxjeCwruCwv-CwqOCwl-CwsOCxjSDgsJXgsL7gsLLgsKjgsYAsIOCwuOCwsOCxguCwsOCxjSDgsKjgsJfgsLDgsY0g4LC14LGG4LC44LGN4LCf4LGNLCDgsLjgsK_gsYDgsKbgsL7gsKzgsL7gsKbgsY0sIOCwueCxiOCwpuCwsOCwvuCwrOCwvuCwpuCxjSwg4LCk4LGG4LCy4LCC4LCX4LC-4LCjIDUwMDA1OSwg4LCt4LC-4LCw4LCk4LCm4LGH4LC24LCCImYiZAoUChIJ31l5uGWYyzsR9zY2qk9lDiASFAoSCd9ZebhlmMs7Efc2NqpPZQ4gGhQKEglDz61OZpjLOxHgDJCFY-o1qBoUChIJi37TW2-YyzsRr_uv50r7tdEiCg1MwFcKFS_dyy4