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

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

مقدمة

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

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

مثال على استخدام Places Library في Maps JavaScript API

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

var map;

function initialize() {
  // Create a map centered in Pyrmont, Sydney (Australia).
  map = new google.maps.Map(document.getElementById('map'), {
    center: {lat: -33.8666, lng: 151.1958},
    zoom: 15
  });

  // Search for Google's office in Australia.
  var request = {
    location: map.getCenter(),
    radius: '500',
    query: 'Google Sydney'
  };

  var service = new google.maps.places.PlacesService(map);
  service.textSearch(request, callback);
}

// Checks that the PlacesServiceStatus is OK, and adds a marker
// using the place ID and location from the PlacesService.
function callback(results, status) {
  if (status == google.maps.places.PlacesServiceStatus.OK) {
    var marker = new google.maps.Marker({
      map: map,
      place: {
        placeId: results[0].place_id,
        location: results[0].geometry.location
      }
    });
  }
}

google.maps.event.addDomListener(window, 'load', initialize);

حفظ أرقام تعريف الأماكن لاستخدامها لاحقًا

إنّ أرقام تعريف الأماكن معفاة من قيود التخزين المؤقت الواردة في الفقرة 3.2.3(ب) من بنود خدمة "منصة خرائط Google". وبالتالي، يمكنك تخزين قيم أرقام تعريف الأماكن لاستخدامها لاحقًا.

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

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

يؤدي هذا الطلب إلى تشغيل رمز التخزين التعريفي تفاصيل الأماكن - إعادة تحميل المعرّف.

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

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