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

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

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

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

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

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

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

نظرة عامة

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

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

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

يمكنك استخدام رقم تعريف المكان نفسه في Places API عدد واجهات برمجة التطبيقات في Google Maps Platform. على سبيل المثال، يمكنك استخدام رقم تعريف المكان نفسه الإشارة إلى مكان في Places API، Maps JavaScript API, Geocoding API واجهة برمجة التطبيقات لتضمين الخرائط وRoads API.

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

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

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

تؤدي هذه المكالمة إلى تشغيل تفاصيل المكان جديدة (أرقام التعريف فقط) أو تفاصيل الأماكن - إعادة تحميل أرقام التعريف رمز التخزين التعريفي.

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

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

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

يشير رمز الحالة NOT_FOUND إلى أنّ رقم تعريف المكان المحدّد وأصبح قديمًا. قد يصبح رقم تعريف المكان قديمًا في حال إغلاق النشاط التجاري أو انتقاله إلى موقع جديد. قد تتغير أرقام تعريف الأماكن بسبب إجراء تعديلات على نطاق واسع في "بحث Google". قاعدة بيانات "خرائط 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