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

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
اختيار نظام أساسي: Android iOS JavaScript خدمة الويب

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

  • استرداد عنوان لمعرّف مكان في خدمة الويب لواجهة برمجة تطبيقات الترميز الجغرافي وخدمة الترميز الجغرافي، وواجهة برمجة تطبيقات JavaScript للخرائط.
  • تحديد نقاط المنشأ، والوجهة، والوسيطة في خدمة الويب لواجهة برمجة التطبيقات للاتجاهات وخدمة الاتجاهات، واجهة برمجة تطبيقات JavaScript للخرائط.
  • تحديد الوجهات والوجهات في خدمة الويب لواجهة برمجة التطبيقات لمصفوفة المسافات وواجهة برمجة التطبيقات لمصفوفة المسافات، وواجهة برمجة تطبيقات JavaScript للخرائط.
  • استرداد تفاصيل الأماكن في خدمة ويب واجهة برمجة تطبيقات الأماكن، وحزمة تطوير برامج الأماكن لـ Android، وأماكن SDK لنظام التشغيل iOS، ومكتبة الأماكن، وواجهة برمجة تطبيقات جافا سكريبت.
  • استخدام معلمات رقم تعريف المكان في واجهة برمجة التطبيقات لتضمين الخرائط.
  • استرداد طلبات البحث في عناوين URL للخرائط.
  • عرض حدود السرعة في واجهة برمجة التطبيقات للطرق
  • العثور على مضلعات الحدود وتصميمها في النمط المستند إلى البيانات.

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

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

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

نظرة عامة

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

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

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

يمكنك استخدام رقم تعريف المكان نفسه عبر واجهة برمجة تطبيقات الأماكن وعدد من واجهات برمجة تطبيقات النظام الأساسي لخرائط Google. على سبيل المثال، يمكنك استخدام رقم تعريف المكان نفسه للإشارة إلى مكان ما في واجهة برمجة تطبيقات الأماكن وواجهة برمجة تطبيقات JavaScript للخرائط وواجهة برمجة تطبيقات الترميز الجغرافي وواجهة برمجة تطبيقات تضمين الخرائط وواجهة برمجة تطبيقات الطرق.

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

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

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

مثال باستخدام واجهة برمجة تطبيقات الأماكن

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

المثال التالي عبارة عن طلب بحث عن أماكن من نوع "مطعم" على مسافة 1500 متر من نقطة في سيدني بأستراليا، ويحتوي على الكلمة "رحلة بحرية":

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