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

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

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

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

البحث عن رقم تعريف مكان معيّن

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

بدلاً من ذلك، يمكنك عرض أداة البحث عن معرّف المكان مع رمزه في مستندات 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.

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

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

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

‫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". وبالتالي، يمكنك تخزين قيم رقم تعريف الأماكن لاستخدامها في وقت لاحق.

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

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