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

اختيار النظام الأساسي: Android iOS JavaScript Web Service
المطوّرون في المنطقة الاقتصادية الأوروبية

مقدمة

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

  • استرداد عنوان لرقم تعريف مكان في Geocoding API وخدمة الترميز الجغرافي وMaps JavaScript API
  • تحديد نقطة الانطلاق والوجهة ونقاط المرور الوسيطة في Routes API وDirections API (الإصدار القديم) وDirections Service وMaps JavaScript API (الإصدار القديم)
  • تحديد نقاط الانطلاق والمقصد في Routes API وDistance Matrix API (الإصدار القديم) وخدمة Distance Matrix وMaps JavaScript API (الإصدار القديم)
  • استرداد تفاصيل الأماكن في Places API (الإصدار الجديد) و"حزمة تطوير البرامج بالاستناد إلى بيانات الأماكن" لنظام التشغيل Android (الإصدار الجديد) و"حزمة تطوير البرامج بالاستناد إلى بيانات الأماكن" لنظام التشغيل 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 أو Places Library في Maps JavaScript API. بعد ذلك، استخدِم رقم تعريف المكان الذي تم عرضه لاسترداد تفاصيل المكان. يمكنك تخزين رقم تعريف المكان واستخدامه لاسترداد تفاصيل المكان نفسها لاحقًا. يمكنك الاطّلاع على مزيد من المعلومات عن حفظ أرقام تعريف الأماكن لاحقًا في هذا المستند.

توضّح الأمثلة التالية كيفية طلب عنوان 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 (القديمة)

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

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

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

‫Places API (جديدة)

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

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

‫Places API (القديمة)

على سبيل المثال، عند استخدام Places API (الإصدار القديم):

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

يؤدي هذا الطلب إلى تفعيل رمز التخزين التعريفي Place Detail New Essentials IDs Only أو Places Details - ID Refresh.

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

INVALID_REQUEST

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

NOT_FOUND

يشير رمز الحالة 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