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

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

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

  • استرداد عنوان لرقم تعريف مكان في خدمة الويب Geocoding API و خدمة ترميز المواقع الجغرافية، واجهة برمجة تطبيقات JavaScript للخرائط
  • تحديد نقاط البداية والوجهة والنقاط الوسيطة في خدمة Routes API وDirections API على الويب وDirections Service وMaps JavaScript API
  • تحديد نقاط المغادرة والوجهات في واجهة برمجة التطبيقات Routes API و خدمة الويب Distance Matrix API و خدمة Distance Matrix، وواجهة برمجة التطبيقات Maps JavaScript API
  • استرداد تفاصيل الأماكن في خدمة الويب Places API وحزمة تطوير البرامج (SDK) للأماكن لنظام Android وحزمة تطوير البرامج (SDK) للأماكن لنظام iOS ومكتبة الأماكن
  • استخدام مَعلمات رقم تعريف المكان في واجهة برمجة التطبيقات Maps Embed API
  • استرداد طلبات البحث في عناوين URL في "خرائط Google"
  • عرض حدود السرعة في Roads API
  • العثور على مضلّعات الحدود وتصميمها في التصميم المستنِد إلى البيانات للحدود

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

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

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

نظرة عامة

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

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

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

يمكنك استخدام معرّف المكان نفسه في Places API و عدد من واجهات برمجة تطبيقات "منصّة خرائط Google". على سبيل المثال، يمكنك استخدام معرّف المكان نفسه لتحديد مكان في Places API وMaps JavaScript API وGeocoding API وMaps Embed API وRoads API.

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

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

توضِّح الأمثلة التالية كيفية طلب عنوان URL لرمز Places API (الإصدار الجديد) و Places API.

‫Places API (جديدة)

باستخدام 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

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

باستخدام Places API، يمكنك العثور على معرّف مكان من خلال إرسال طلب بحث عن مكان.

في ما يلي مثال على طلب بحث عن أماكن من النوع "مطعم" ضمن دائرة نصف قطرها 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 Maps Platform. ويمكنك بالتالي تخزين قيم معرّفات الأماكن لاستخدامها في وقت لاحق.

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

ننصحك بتعديل أرقام تعريف الأماكن إذا مرّ أكثر من 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

يؤدي هذا الطلب إلى تنشيط Place Detail New (IDs Only) (تفاصيل المكان الجديدة (أرقام التعريف فقط)) أوPlaces Details - ID Refresh (تفاصيل الأماكن - إعادة تحميل أرقام التعريف) رمز التخزين التعريفي.

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

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

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

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

على وجه الخصوص، قد تؤدي بعض أنواع معرّفات الأماكن أحيانًا إلى 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