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

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

مقدمة

تحدِّد أرقام تعريف الأماكن مكانًا بشكلٍ فريد في قاعدة بيانات "أماكن 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 أو مكتبة الأماكن في Maps JavaScript API. بعد ذلك، استخدِم رقم تعريف المكان الذي تم عرضه لاسترداد تفاصيل المكان. يمكنك تخزين رقم تعريف المكان واستخدامه لاسترداد تفاصيل المكان نفسه لاحقًا. يمكنك الاطّلاع على مزيد من المعلومات عن حفظ أرقام تعريف الأماكن لاحقًا في هذا المستند.

مثال على استخدام "مكتبة الأماكن" في 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