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

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

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

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

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

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

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

نظرة عامة

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

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

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

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

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

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

توضّح الأمثلة التالية كيفية طلب عنوان URL لرمز لواجهة برمجة تطبيقات الأماكن (جديدة) وواجهة برمجة تطبيقات الأماكن.

‫Places API (جديدة)

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

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.id,places.displayName,places.formattedAddress' \
'https://places.googleapis.com/v1/places:searchText'

يتضمن الرد معرّف مكان في حقل id، كما هو موضّح أدناه:

{
  "places": [
    {
      "id": "ChIJs5ydyTiuEmsR0fRSlU0C7k0",
      "formattedAddress": "29 King St, Sydney NSW 2000, Australia",
      "displayName": {
        "text": "Peace Harmony",
        "languageCode": "en"
      }
    },
  ...
}

يمكنك الآن تقديم طلب تفاصيل المكان (جديد) عن طريق تضمين رقم تعريف المكان في عنوان URL للطلب:

https://places.googleapis.com/v1/places/ChIJs5ydyTiuEmsR0fRSlU0C7k0?fields=id,displayName&key=API_KEY

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

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

والمثال التالي هو طلب بحث عن أماكن من النوع "مطعم" ضمن نطاق جغرافي قدره 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 شهرًا. يمكنك إعادة تحميل أرقام تعريف الأماكن بدون أي رسوم عن طريق إنشاء طلب "تفاصيل المكان"، مع تحديد حقل "رقم تعريف المكان" فقط في المعلَمة fields.

‫Places API (جديدة)

على سبيل المثال، باستخدام تفاصيل المكان (جديد):

https://places.googleapis.com/v1/places/ChIJ05IRjKHxEQ0RJLV_5NLdK2w?fields=id&key=API_KEY

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

على سبيل المثال، باستخدام واجهة برمجة التطبيقات القديمة Place Details (تفاصيل المكان): 

https://maps.googleapis.com/maps/api/place/details/json?place_id=ChIJ05IRjKHxEQ0RJLV_5NLdK2w&fields=place_id&key=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