مكتبة الأماكن

نظرة عامة

تتيح الدوالّ في مكتبة الأماكن وواجهة برمجة التطبيقات JavaScript API في "خرائط Google" لتطبيقك البحث عن الأماكن (التي يتم تعريفها في واجهة برمجة التطبيقات هذه على أنّها أماكن إقامة أو مواقع جغرافية أو نقاط اهتمام بارزة) ضمن منطقة محدّدة، مثل حدود خريطة أو حول نقطة ثابتة.

توفّر Places API ميزة الإكمال التلقائي التي يمكنك استخدامها لمنح تطبيقاتك سلوك البحث أثناء الكتابة في حقل البحث في "خرائط Google". عندما يبدأ المستخدم بكتابة عنوان، سيتم استخدام ميزة الملء التلقائي لملء الباقي. لمزيد من المعلومات، يُرجى الاطّلاع على مستندات ميزة "الإكمال التلقائي".

الخطوات الأولى

إذا لم تكن على دراية بخدمة Maps JavaScript API أو JavaScript، ننصحك بمراجعة JavaScript و الحصول على مفتاح واجهة برمجة التطبيقات قبل البدء.

تفعيل واجهات برمجة التطبيقات

قبل استخدام مكتبة Places في Maps JavaScript API، تأكَّد أولاً من تفعيل Places API في Google Cloud Console، في المشروع نفسه الذي أعددته لواجهة برمجة التطبيقات Maps JavaScript API.

للاطّلاع على قائمة واجهات برمجة التطبيقات المفعَّلة:

  1. انتقِل إلى Google Cloud Console.
  2. انقر على الزر اختيار مشروع، ثم اختَر المشروع نفسه الذي أعددته لمكتبة Maps JavaScript API، ثم انقر على فتح.
  3. من قائمة واجهات برمجة التطبيقات في لوحة البيانات، ابحث عن Places API.
  4. إذا ظهرت لك Places API في القائمة، يعني ذلك أنّها مفعّلة. إذا كانت واجهة برمجة التطبيقات غير مُدرَجة، فعِّلها:
    1. في أعلى الصفحة، انقر على تفعيل واجهات برمجة التطبيقات والخدمات لعرض علامة التبويب المكتبة. بدلاً من ذلك، انقر على المكتبة من القائمة اليمنى.
    2. ابحث عن Places API، ثم اختَره من قائمة النتائج.
    3. انقر على تفعيل. عند اكتمال العملية، تظهر Places API في قائمة واجهات برمجة التطبيقات في لوحة البيانات.

تحميل المكتبة

خدمة "الأماكن" هي مكتبة مكتفية ذاتيًا، منفصلة عن الرمز الرئيسي لـ واجهة برمجة التطبيقات JavaScript لخرائط Google. لاستخدام الوظائف المضمّنة في هذه المكتبة، عليك أولاً تحميلها باستخدام المَعلمة libraries في عنوان URL لبدء تشغيل Maps API:

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&libraries=places&callback=initMap">
</script>

اطّلِع على نظرة عامة على المكتبات للحصول على مزيد من المعلومات.

إضافة Places API إلى قائمة القيود المفروضة على واجهة برمجة التطبيقات لمفتاح واجهة برمجة التطبيقات

يؤدي تطبيق قيود واجهة برمجة التطبيقات على مفاتيحك إلى حصر استخدام مفتاح واجهة برمجة التطبيقات بواجهة برمجة تطبيقات واحدة أو أكثر أو حِزم تطوير برامج (SDK). سيتم معالجة الطلبات المرسَلة إلى واجهة برمجة تطبيقات أو حزمة تطوير برامج (SDK) مرتبطة بمفتاح واجهة برمجة التطبيقات. لن يتم إكمال الطلبات المرسَلة إلى واجهة برمجة تطبيقات أو حزمة تطوير برامج (SDK) غير مرتبطة بمفتاح واجهة برمجة التطبيقات. لتقييد مفتاح واجهة برمجة التطبيقات لاستخدامه مع Places Library وMaps JavaScript API، اتّبِع الخطوات التالية:
  1. انتقِل إلى Google Cloud Console.
  2. انقر على القائمة المنسدلة للمشروع واختَر المشروع الذي يحتوي على مفتاح واجهة برمجة التطبيقات الذي تريد تأمينه.
  3. انقر على زر القائمة واختَر منصّة خرائط Google > بيانات الاعتماد.
  4. في صفحة بيانات الاعتماد، انقر على اسم مفتاح واجهة برمجة التطبيقات الذي تريد تأمينه.
  5. في صفحة تقييد مفتاح واجهة برمجة التطبيقات وإعادة تسميته، اضبط القيود:
    • القيود المفروضة على واجهة برمجة التطبيقات
      • انقر على تقييد المفتاح.
      • انقر على اختيار واجهات برمجة التطبيقات واختَر كلّ من Maps JavaScript API وPlaces API.
        (إذا لم تكن إحدى واجهات برمجة التطبيقات مُدرَجة، عليك تفعيلها).
  6. انقر على حفظ.

حدود الاستخدام والسياسات

الحصص

تشترك مكتبة Places Library في حصة الاستخدام مع Places API كما هو موضّح في مستندات حدود الاستخدام الخاصة بـ Places API.

السياسات

يجب أن يكون استخدام Places Library وواجهة برمجة تطبيقات JavaScript للخرائط متوافقًا مع السياسات الموضّحة في واجهة برمجة تطبيقات Places API.

عمليات البحث عن الأماكن

باستخدام خدمة "الأماكن"، يمكنك إجراء الأنواع التالية من عمليات البحث:

يمكن أن تتضمّن المعلومات التي يتم عرضها المؤسسات، مثل المطاعم والمتاجر والمكاتب، بالإضافة إلى نتائج "الرمز الجغرافي" التي تشير إلى العناوين والمناطق الإدارية، مثل البلدات والمدن، وغيرها من نقاط الاهتمام.

طلبات العثور على مكان

يتيح لك طلب "العثور على مكان" البحث عن مكان إما من خلال طلب بحث نصي أو رقم هاتف. هناك نوعان من طلبات "العثور على مكان":

العثور على مكان من طلب البحث

تأخذ دالة "العثور على مكان من طلب بحث" إدخال نصيًا وتُعرِض مكانًا. يمكن أن يكون الإدخال أي نوع من بيانات الأماكن، مثل اسم نشاط تجاري أو عنوان. لتقديم طلب العثور على مكان من طلب بحث، يمكنك استدعاء PlacesService findPlaceFromQuery() الطريقة التي تأخذ المَعلمات التالية:

  • ‫query (مطلوبة) سلسلة النصوص التي يتم البحث فيها، على سبيل المثال: "مطعم" أو "123 شارع التحرير". يجب أن يكون هذا الاسم اسم مكان أو عنوانًا أو فئة من المؤسسات. يمكن أن تؤدي أي أنواع أخرى من الإدخال إلى توليد أخطاء ولا يمكن ضمان عرض نتائج صالحة. ستُعرِض Places API مطابقات مرشحة استنادًا إلى هذه السلسلة وسيتم ترتيب النتائج استنادًا إلى مدى صلة كل منها بموضوع البحث.
  • fields (مطلوبة) حقل واحد أو أكثر لتحديد أنواع بيانات الأماكن المطلوب عرضها
  • locationBias (اختياري) الإحداثيات التي تحدّد المنطقة المطلوب البحث فيها يمكن أن يكون ذلك أحد ما يلي:
    • مجموعة من إحداثيات خط الطول/العرض المحدّدة على النحو التالي: LatLngLiteral أو كائن LatLng
    • الحدود المستطيلة (زوجان من خطوط الطول/العرض، أو كائن LatLngBounds)
    • شعاع (بالمتر) متمركز على خطي الطول والعرض

يجب أيضًا تمرير طريقة ردّ اتصال إلى findPlaceFromQuery()، لمعالجة عنصر النتائج واستجابة google.maps.places.PlacesServiceStatus.

يعرض المثال التالي طلبًا إلى findPlaceFromQuery()، للبحث عن "متحف الفن المعاصر في أستراليا"، مع تضمين الحقلَين name وgeometry.

var map;
var service;
var infowindow;

function initMap() {
  var sydney = new google.maps.LatLng(-33.867, 151.195);

  infowindow = new google.maps.InfoWindow();

  map = new google.maps.Map(
      document.getElementById('map'), {center: sydney, zoom: 15});

  var request = {
    query: 'Museum of Contemporary Art Australia',
    fields: ['name', 'geometry'],
  };

  var service = new google.maps.places.PlacesService(map);

  service.findPlaceFromQuery(request, function(results, status) {
    if (status === google.maps.places.PlacesServiceStatus.OK) {
      for (var i = 0; i < results.length; i++) {
        createMarker(results[i]);
      }
      map.setCenter(results[0].geometry.location);
    }
  });
}
 عرض مثال

العثور على مكان من رقم هاتف

تأخذ دالة Find Place from Phone Number رقم هاتف وتُعرِض مكانًا. لمحاولة إجراء طلب "العثور على مكان من رقم هاتف"، يمكنك الاتصال بأسلوب PlacesService findPlaceFromPhoneNumber() الذي يأخذ المَعلمات التالية:

  • phoneNumber (مطلوبة) رقم هاتف بتنسيق E.164
  • fields (مطلوبة) حقل واحد أو أكثر لتحديد أنواع بيانات الأماكن المطلوب عرضها
  • locationBias (اختياري) إحداثيات تحدّد المنطقة التي يتم فيها البحث يمكن أن يكون أحد الخيارات التالية:
    • مجموعة من إحداثيات خط الطول/العرض المحدّدة على النحو التالي: LatLngLiteral أو كائن LatLng
    • الحدود المستطيلة (أربع نقاط خطوط العرض/الطول أو كائن LatLngBounds)
    • شعاع (بالمتر) متمركز على خطي الطول والعرض

يجب أيضًا تمرير طريقة ردّ اتصال إلى findPlaceFromPhoneNumber()، لمعالجة عنصر النتائج واستجابة google.maps.places.PlacesServiceStatus.

الحقول (طُرق البحث عن مكان)

استخدِم المَعلمة fields لتحديد مصفوفة من أنواع بيانات الأماكن المطلوب عرضها. على سبيل المثال: fields: ['formatted_address', 'opening_hours', 'geometry']. استخدِم نقطة عند تحديد قيم مركبة. على سبيل المثال: opening_hours.weekday_text.

تتطابق الحقول مع نتائج البحث عن الأماكن، وتنقسم إلى ثلاث فئات فوترة: أساسية وجهات اتصال وجو. يتم تحصيل رسوم الحقول الأساسية بالسعر الأساسي، ولا يتم تحصيل أي رسوم إضافية. يتم تحصيل رسوم أعلى مقابل حقلَي "جهة الاتصال" و"الجو" . يمكنك الاطّلاع على جدول الأسعار لمزيد من المعلومات. يتم دائمًا عرض الإحالات (html_attributions) مع كل مكالمة، بغض النظر عمّا إذا تم طلب الحقل.

أساسي

تتضمّن الفئة الأساسية الحقول التالية:
business_status وformatted_address وgeometry icon وicon_mask_base_uri وicon_background_color name وpermanently_closed (تم إيقافه نهائيًا) photos وplace_id وplus_code وtypes

التواصل

تتضمّن فئة "جهة الاتصال" الحقل التالي: opening_hours
(تم إيقافه نهائيًا في Places Library، وMaps JavaScript API. استخدِم طلب "تفاصيل المكان" للحصول على opening_hours النتائج).

الغلاف الجوي

تتضمّن فئة "الجوّ" الحقول التالية: price_level وrating وuser_ratings_total

تأخذ كلّ من الطريقتَين findPlaceFromQuery() و findPlaceFromPhoneNumber() المجموعة نفسها من الحقول، ويمكن أن تعرض الحقول نفسها في الردود الخاصة بكلّ منهما.

ضبط الميل إلى الموقع الجغرافي (طُرق البحث عن مكان)

استخدِم المَعلمة locationBias لجعل ميزة "العثور على مكان" تفضّل النتائج في منطقة معيّنة. يمكنك ضبط locationBias بالطرق التالية:

توجيه النتائج نحو منطقة معيّنة:

locationBias: {lat: 37.402105, lng: -122.081974}

حدِّد منطقة مستطيلة للبحث:

locationBias: {north: 37.41, south: 37.40, east: -122.08, west: -122.09}

يمكنك أيضًا استخدام LatLngBounds.

حدِّد نصف قطر للبحث (بالمتر) يكون مركزه في منطقة معيّنة:

locationBias: {radius: 100, center: {lat: 37.402105, lng: -122.081974}}

طلبات البحث في الأماكن القريبة

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

  • أ LatLngBounds.
  • منطقة دائرية يتم تحديدها على أنّها مجموعة من سمة location التي تحدّد مركز الدائرة على أنّه كائن LatLng ونصف قطر يتم قياسه بالمتر

يتم بدء البحث عن "الأماكن المجاورة" من خلال طلب nearbySearch() في PlacesService، ما يؤدي إلى عرض صفيف من عناصر PlaceResult. يُرجى العلم أنّ طريقة nearbySearch() تحلّ محلّ طريقة search() اعتبارًا من الإصدار 3.9.

service = new google.maps.places.PlacesService(map);
service.nearbySearch(request, callback);

تأخذ هذه الطريقة طلبًا يتضمّن الحقول التالية:

  • يمكنك تنفيذ أيّ من الإجراءَين التاليَين:
    • bounds، والذي يجب أن يكون عنصرًا google.maps.LatLngBounds يحدّد منطقة البحث المربّعة الحد الأقصى للمسافة القطرية المسموح بها لحدود المنطقة هو 100,000 متر تقريبًا.
    • location وradius، حيث يأخذ الأول كائنًا من النوع google.maps.LatLng، ويأخذ الأخير عددًا صحيحًا بسيطًا يمثّل نصف قطر الدائرة بالمتر. الحد الأقصى للدائرة المسموح بها هو 50,000 متر. يُرجى العلم أنّه عند ضبط rankBy على DISTANCE، يجب تحديد location ولكن لا يمكنك تحديد radius أو bounds.
  • keyword (اختياري) - عبارة لمطابقتها مع جميع الحقول المتاحة، بما في ذلك على سبيل المثال لا الحصر، الاسم والنوع والعنوان، بالإضافة إلى مراجعات العملاء والمحتوى الآخر التابع لجهات خارجية.
  • ‫minPriceLevel وmaxPriceLevel (اختياري) - لحصر النتائج بالأماكن التي تقع ضمن النطاق المحدّد فقط تتراوح القيم الصالحة بين 0 (الأكثر تكلفة) و4 (الأكثر تكلفة)، شاملة.
  • name ميزة متوقّفة نهائيًا يعادل keyword. يتم دمج القيم في هذا الحقل مع القيم في حقل keyword ويتم تمريرها كجزء من سلسلة البحث نفسها.
  • ‫openNow (اختياري) : قيمة منطقية، تشير إلى أنّ خدمة "الأماكن" يجب أن تعرِض فقط الأماكن التي تكون مفتوحة للأنشطة التجارية في وقت إرسال الطلب. لن يتم عرض الأماكن التي لا تحدد ساعات العمل في قاعدة بيانات "أماكن Google" إذا تضمّنت هذه المَعلمة في طلب البحث. لن يكون لضبط openNow على false أي تأثير.
  • ‫rankBy (اختياري) - لتحديد الترتيب الذي يتم فيه إدراج النتائج القيم المحتمَلة هي:
    • google.maps.places.RankBy.PROMINENCE (الإعداد التلقائي) يُرتِّب هذا الخيار النتائج حسب أهميتها. سيمنح الترتيب الأولوية للأماكن البارزة ضمن النطاق الجغرافي المحدّد على الأماكن المجاورة التي تتطابق مع طلب البحث ولكنها أقل بروزًا. يمكن أن يتأثر مدى بروز مكان ما بترتيبه في فهرس Google ومدى رواجه على مستوى العالم وعوامل أخرى. عند تحديد google.maps.places.RankBy.PROMINENCE ، تكون المَعلمة radius مطلوبة.
    • google.maps.places.RankBy.DISTANCE: يفرِّز هذا الخيار النتائج تصاعديًا حسب المسافة من location المحدّد (مطلوب). تجدر الإشارة إلى أنّه لا يمكنك تحديد قيمة مخصّصة لbounds و/أو radius إذا تحديد القيمة RankBy.DISTANCE. عند تحديد RankBy.DISTANCE، يجب تحديد واحد أو أكثر من keyword أو name أو type.
  • type - لحصر النتائج بالأماكن التي تتطابق مع النوع المحدّد يمكن تحديد نوع واحد فقط فقط (إذا تم تقديم أكثر من نوع واحد، سيتم تجاهل جميع الأنواع التي تلي الإدخال الأول). اطّلِع على قائمة الأنواع المتوافقة.

يجب أيضًا تمرير طريقة ردّ اتصال إلى nearbySearch()، لمعالجة عنصر النتائج وgoogle.maps.places.PlacesServiceStatus الاستجابة.

var map;
var service;
var infowindow;

function initialize() {
  var pyrmont = new google.maps.LatLng(-33.8665433,151.1956316);

  map = new google.maps.Map(document.getElementById('map'), {
      center: pyrmont,
      zoom: 15
    });

  var request = {
    location: pyrmont,
    radius: '500',
    type: ['restaurant']
  };

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

function callback(results, status) {
  if (status == google.maps.places.PlacesServiceStatus.OK) {
    for (var i = 0; i < results.length; i++) {
      createMarker(results[i]);
    }
  }
}

عرض مثال

طلبات البحث النصي

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

تبدأ عمليات البحث النصي من خلال طلب textSearch() في PlacesService. 

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

تأخذ هذه الطريقة طلبًا يتضمّن الحقول التالية:

  • query (سمة مطلوبة) سلسلة النصوص التي سيتم البحث فيها، على سبيل المثال: "مطعم" أو "123 شارع التحرير". يجب أن يكون هذا العنصر اسمًا أو عنوانًا أو فئة لمكان. يمكن أن تؤدي أي أنواع أخرى من الإدخال إلى حدوث أخطاء ولا يمكن ضمان عرض نتائج صالحة. ستعرِض خدمة "الأماكن" مطابقات مرشحة استنادًا إلى هذه السلسلة وسيتم ترتيب النتائج استنادًا إلى مدى صلتها بموضوع البحث. تصبح هذه المَعلمة اختيارية إذا تم استخدام المَعلمة type أيضًا في طلب البحث.
  • اختياري:
    • ‫openNow: قيمة منطقية، تشير إلى أنّ خدمة "الأماكن" يجب أن تعرِض فقط الأماكن التي تكون مفتوحة في وقت إرسال الطلب. لن يتم عرض الأماكن التي لا تحدد ساعات العمل في قاعدة بيانات "أماكن Google" إذا تضمّنت هذه المَعلمة في طلب البحث. لن يكون لضبط openNow على false أي تأثير.
    • ‫minPriceLevel وmaxPriceLevel — لحصر النتائج بالأماكن التي تقع ضمن مستوى السعر المحدّد فقط تتراوح القيم الصالحة بين 0 (الأكثر تكلفة) و4 (الأكثر تكلفة) بشكل شامل.
    • يمكنك تنفيذ أيّ من الإجراءَين التاليَين:
      • bounds، والذي يجب أن يكون عنصرًا google.maps.LatLngBounds يحدّد منطقة البحث المستطيلة. الحد الأقصى للمسافة القطرية المسموح بها لحدود المنطقة هو 100,000 متر تقريبًا.
      • ‫location وradius: يمكنك توجيه النتائج إلى دائرة محدّدة من خلال تمرير مَعلمتَي location وradius. سيؤدي ذلك إلى توجيه خدمة "الأماكن" إلى تفضيل عرض النتائج ضمن تلك دائرة. قد يستمر عرض النتائج خارج المنطقة المحدّدة. يأخذ الموقع الجغرافي عنصر google.maps.LatLng، ويأخذ نصف القطر عددًا صحيحًا بسيطًا يمثّل نصف قطر الدائرة بالمتر. الحد الأقصى للدائرة المسموح بها هو 50,000 متر.
    • type - لحصر النتائج بالأماكن التي تتطابق مع النوع المحدّد يمكن تحديد نوع واحد فقط (إذا تم تقديم أكثر من نوع ، يتم تجاهل جميع الأنواع التي تلي الإدخال الأول). اطّلِع على قائمة الأنواع المتوافقة.

يجب أيضًا تمرير طريقة ردّ اتصال إلى textSearch()، لمعالجة textSearch() google.maps.places.PlacesServiceStatus.

var map;
var service;
var infowindow;

function initialize() {
  var pyrmont = new google.maps.LatLng(-33.8665433,151.1956316);

  map = new google.maps.Map(document.getElementById('map'), {
      center: pyrmont,
      zoom: 15
    });

  var request = {
    location: pyrmont,
    radius: '500',
    query: 'restaurant'
  };

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

function callback(results, status) {
  if (status == google.maps.places.PlacesServiceStatus.OK) {
    for (var i = 0; i < results.length; i++) {
      var place = results[i];
      createMarker(results[i]);
    }
  }
}

الردود على طلب البحث

رموز الحالة

يحتوي عنصر الاستجابة PlacesServiceStatus على حالة الطلب، وقد يحتوي على معلومات تصحيح الأخطاء لمساعدتك في تحديد سبب تعذُّر طلب بيانات المكان. في ما يلي القيم المحتملة للحالة:

  • INVALID_REQUEST: كان هذا الطلب غير صالح.
  • OK: يحتوي الردّ على نتيجة صالحة.
  • OVER_QUERY_LIMIT: تجاوزت صفحة الويب حصة الطلبات المسموح بها.
  • REQUEST_DENIED: لا يُسمح لصفحة الويب باستخدام مكتبة PlacesService.
  • UNKNOWN_ERROR: تعذّر processingمعالجة طلب PlacesService بسبب خطأ في الخادم. قد ينجح الطلب إذا حاولت مرة أخرى.
  • ZERO_RESULTS: لم يتم العثور على أي نتيجة لهذا الطلب.

نتائج البحث عن الأماكن

تعرض الدوالّ findPlace() وnearbySearch() و textSearch() صفيفًا من عناصر PlaceResult.

يمكن أن يتضمّن كل عنصر PlaceResult السمات التالية:

  • يشير الرمز business_status إلى حالة تشغيل المكان، إذا كان نشاطًا تجاريًا. يمكن أن يحتوي على إحدى القيم التالية:
    • OPERATIONAL
    • CLOSED_TEMPORARILY
    • CLOSED_PERMANENTLY
    في حال عدم توفّر بيانات، لن يتم عرض business_status.
  • formatted_address هي سلسلة تحتوي على عنوان هذا المكان بتنسيق يمكن لشخص عادي قراءته. لا يتم عرض الخاصية formatted_address إلا في البحث النصي.

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

    يتألّف العنوان المنسَّق منطقيًا من مكوّن عنوان واحد أو أكثر. على سبيل المثال، يتألّف العنوان "111 شارع 8، القاهرة، القاهرة" من المكوّنات التالية: "111" (رقم الشارع)، "شارع 8" (المسار)، و"القاهرة" (المدينة) و "القاهرة" (الولاية).

    لا تُحلِّل العنوان المنسَّق آليًا. بدلاً من ذلك، يجب استخدام عناصر العنوان الفردية التي تتضمّنها استجابة واجهة برمجة التطبيقات بالإضافة إلى حقل العنوان المنسَّق.

  • geometry: المعلومات المتعلّقة بهندسة المكان ويشمل ذلك ما يلي:
    • تقدّم location خطي العرض والطول للمكان.
    • viewport يحدِّد إطار العرض المفضَّل على الخريطة عند عرض هذا المكان.
  • ‫permanently_closed (ميزة متوقّفة نهائيًا) هي علامة منطقية تشير إلى ما إذا كان المكان قد تم إغلاقه نهائيًا أو مؤقتًا (القيمة true). لا تستخدِم permanently_closed. بدلاً من ذلك، استخدِم business_status للاطّلاع على الحالة التشغيلية للأنشطة التجارية.
  • plus_code (راجِع رمز الموقع المفتوح ورموز Plus Codes) هو مرجع موقع جغرافي مشفَّر، يتم الحصول عليه من إحداثيات خطوط الطول والعرض، ويمثّل منطقة: 1/8000 من الدرجة في 1/8000 من الدرجة (حوالي 14 مترًا في 14 مترًا عند خط الاستواء) أو أصغر. يمكن استخدام رموز Plus Codes كبديل لعناوين الشوارع في الأماكن التي لا تتوفّر فيها (حيث لا يتم ترقيم المباني أو تسمية الشوارع).

    يتم تنسيق رمز الموقع المفتوح كرمز عالمي ورمز مركب:

    • global_code هو رمز منطقة مكوّن من 4 أحرف ورمز محلي مكوّن من 6 أحرف أو أكثر (849VCWC8+R9).
    • compound_code هو رمز محلي مكوّن من 6 أحرف أو أكثر يتضمّن موقعًا جغرافيًا واضحًا (CWC8+R9، ماونتن فيو، كاليفورنيا، الولايات المتحدة). لا تُحلِّل هذا المحتوى آليًا.
    يتم عادةً عرض كل من الرمز الشامل والرمز المركب. ومع ذلك، إذا كانت النتيجة في موقع جغرافي بعيد (مثل محيط أو صحراء)، قد يتم عرض الرمز الشامل فقط.
  • ‫html_attributions: مصفوفة من الإسنادات التي يجب عرضها عند عرض نتائج البحث يحتوي كل إدخال في الصفيف على نص HTML لإسناد واحد. ملاحظة: هذه مجموعة من جميع الإحالات لردّ البحث بالكامل. وبالتالي، تحتوي جميع عناصر PlaceResult في الاستجابة على قوائم تحديد مصدر متطابقة.
  • icon تعرِض عنوان URL لرمز PNG ملون أبعاده 71 بكسل × 71 بكسل.
  • تعرِض دالة icon_mask_base_uri عنوان URL الأساسي لرمز غير ملون، بدون إضافة ‎ .svg أو ‎ .png.
  • icon_background_color تعرِض رمز اللون السداسي التلقائي ل فئة المكان.
  • name: اسم المكان
  • opening_hours قد يحتوي على المعلومات التالية:
    • ‫open_now هي قيمة منطقية تشير إلى ما إذا كان المكان مفتوحًا في الوقت الحالي (تم إيقافها نهائيًا في Places Library وMaps JavaScript API، استخدِم utc_offset_minutes بدلاً من ذلك).
  • place_id هو معرّف نصي يحدِّد مكانًا بشكل فريد. لاسترداد معلومات عن المكان، يجب ضبط هذا المعرّف في طلب تفاصيل المكان. اطّلِع على مزيد من المعلومات عن كيفية الإشارة إلى مكان باستخدام رقم تعريف مكان.
  • تحتوي السمة rating على تقييم المكان، من 0.0 إلى 5.0، استنادًا إلى مراجعات المستخدمين المجمّعة.
  • types مصفوفة من أنواع هذا المكان (مثل ["political", "locality"] أو ["restaurant", "lodging"]). قد تحتوي هذه المصفوفة على قيم متعدّدة، أو قد تكون فارغة. قد يتمّ إدخال قيم جديدة بدون إشعار مسبق. اطّلِع على قائمة الأنواع المتوافقة.
  • vicinity: عنوان مبسط للمكان، بما في ذلك اسم الشارع ورقمه والموقع الجغرافي، ولكن ليس المقاطعة أو الولاية أو الرمز البريدي أو البلد على سبيل المثال، مكتب Google في سيدني، أستراليا، لديه قيمة vicinity‏=5/48 Pirrama Road, Pyrmont.

الوصول إلى نتائج إضافية

يعرض كل بحث عن مكان تلقائيًا ما يصل إلى 20 نتيجة لكل طلب بحث. ومع ذلك، يمكن أن تعرِض كل عملية بحث ما يصل إلى 60 نتيجة، مُقسَّمة على ثلاث صفحات. تتوفّر صفحات إضافية من خلال عنصر PlaceSearchPagination. للوصول إلى صفحات إضافية، يجب تسجيل عنصر PlaceSearchPagination من خلال دالة استدعاء. يتم تعريف العنصر PlaceSearchPagination على النحو التالي:

  • hasNextPage سمة منطقية تشير إلى ما إذا كانت هناك نتائج أخرى متاحة. true عند توفّر صفحة نتائج إضافية
  • nextPage() دالة ستُعرِض المجموعة التالية من النتائج بعد تنفيذ عملية بحث، عليك الانتظار لمدة ثانيتين قبل أن تصبح الصفحة التالية من النتائج متاحة.

للاطّلاع على المجموعة التالية من النتائج، يُرجى الاتصال على nextPage. يجب عرض كل صفحة من الصفحات قبل عرض الصفحة التالية من النتائج. يُرجى العِلم أنّ كل عملية بحث تُحتسَب كطلب واحد ضمن حدود استخدامك.

يوضّح المثال أدناه كيفية تغيير دالة ردّ الاتصال لالتقاط عنصر PlaceSearchPagination، حتى تتمكّن من إرسال طلبات بحث متعددة.

TypeScript

// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">

function initMap(): void {
  // Create the map.
  const pyrmont = { lat: -33.866, lng: 151.196 };
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      center: pyrmont,
      zoom: 17,
      mapId: "8d193001f940fde3",
    } as google.maps.MapOptions
  );

  // Create the places service.
  const service = new google.maps.places.PlacesService(map);
  let getNextPage: () => void | false;
  const moreButton = document.getElementById("more") as HTMLButtonElement;

  moreButton.onclick = function () {
    moreButton.disabled = true;

    if (getNextPage) {
      getNextPage();
    }
  };

  // Perform a nearby search.
  service.nearbySearch(
    { location: pyrmont, radius: 500, type: "store" },
    (
      results: google.maps.places.PlaceResult[] | null,
      status: google.maps.places.PlacesServiceStatus,
      pagination: google.maps.places.PlaceSearchPagination | null
    ) => {
      if (status !== "OK" || !results) return;

      addPlaces(results, map);
      moreButton.disabled = !pagination || !pagination.hasNextPage;

      if (pagination && pagination.hasNextPage) {
        getNextPage = () => {
          // Note: nextPage will call the same handler function as the initial call
          pagination.nextPage();
        };
      }
    }
  );
}

function addPlaces(
  places: google.maps.places.PlaceResult[],
  map: google.maps.Map
) {
  const placesList = document.getElementById("places") as HTMLElement;

  for (const place of places) {
    if (place.geometry && place.geometry.location) {
      const image = {
        url: place.icon!,
        size: new google.maps.Size(71, 71),
        origin: new google.maps.Point(0, 0),
        anchor: new google.maps.Point(17, 34),
        scaledSize: new google.maps.Size(25, 25),
      };

      new google.maps.Marker({
        map,
        icon: image,
        title: place.name!,
        position: place.geometry.location,
      });

      const li = document.createElement("li");

      li.textContent = place.name!;
      placesList.appendChild(li);

      li.addEventListener("click", () => {
        map.setCenter(place.geometry!.location!);
      });
    }
  }
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

JavaScript

// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">
function initMap() {
  // Create the map.
  const pyrmont = { lat: -33.866, lng: 151.196 };
  const map = new google.maps.Map(document.getElementById("map"), {
    center: pyrmont,
    zoom: 17,
    mapId: "8d193001f940fde3",
  });
  // Create the places service.
  const service = new google.maps.places.PlacesService(map);
  let getNextPage;
  const moreButton = document.getElementById("more");

  moreButton.onclick = function () {
    moreButton.disabled = true;
    if (getNextPage) {
      getNextPage();
    }
  };

  // Perform a nearby search.
  service.nearbySearch(
    { location: pyrmont, radius: 500, type: "store" },
    (results, status, pagination) => {
      if (status !== "OK" || !results) return;

      addPlaces(results, map);
      moreButton.disabled = !pagination || !pagination.hasNextPage;
      if (pagination && pagination.hasNextPage) {
        getNextPage = () => {
          // Note: nextPage will call the same handler function as the initial call
          pagination.nextPage();
        };
      }
    },
  );
}

function addPlaces(places, map) {
  const placesList = document.getElementById("places");

  for (const place of places) {
    if (place.geometry && place.geometry.location) {
      const image = {
        url: place.icon,
        size: new google.maps.Size(71, 71),
        origin: new google.maps.Point(0, 0),
        anchor: new google.maps.Point(17, 34),
        scaledSize: new google.maps.Size(25, 25),
      };

      new google.maps.Marker({
        map,
        icon: image,
        title: place.name,
        position: place.geometry.location,
      });

      const li = document.createElement("li");

      li.textContent = place.name;
      placesList.appendChild(li);
      li.addEventListener("click", () => {
        map.setCenter(place.geometry.location);
      });
    }
  }
}

window.initMap = initMap;
index.js
عرض مثال

تجربة عيّنة

تفاصيل المكان

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

طلبات تفاصيل الأماكن

يتم طلب تفاصيل المكان من خلال طلب إلى getDetails() في الخدمة.

service = new google.maps.places.PlacesService(map);
service.getDetails(request, callback);

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

ويأخذ الإجراء أيضًا طريقة طلب معاودة الاتصال التي يجب أن تتعامل مع رمز الحالة الذي تم تمريره في استجابة google.maps.places.PlacesServiceStatus، بالإضافة إلى عنصر google.maps.places.PlaceResult.

var request = {
  placeId: 'ChIJN1t_tDeuEmsRUsoyG83frY4',
  fields: ['name', 'rating', 'formatted_phone_number', 'geometry']
};

service = new google.maps.places.PlacesService(map);
service.getDetails(request, callback);

function callback(place, status) {
  if (status == google.maps.places.PlacesServiceStatus.OK) {
    createMarker(place);
  }
}

عرض مثال

الحقول (تفاصيل المكان)

تأخذ المَعلمة fields صفيفًا من السلاسل (أسماء الحقول).

استخدِم المَعلمة fields لتحديد مصفوفة من أنواع بيانات الأماكن المطلوب عرضها. على سبيل المثال: fields: ['address_components', 'opening_hours', 'geometry']. استخدِم نقطة عند تحديد قيم مركبة. على سبيل المثال: opening_hours.weekday_text.

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

أساسي

تتضمّن الفئة الأساسية الحقول التالية:
address_components وadr_address وbusiness_status formatted_address وgeometry وicon icon_mask_base_uri وicon_background_color وname permanently_closed (تم إيقافه نهائيًا) photo وplace_id وplus_code وtype url وutc_offset (تم إيقافه نهائيًا في Places Library وMaps JavaScript API) وutc_offset_minutes vicinity

التواصل

تتضمّن فئة "جهة الاتصال" الحقول التالية:
formatted_phone_number وinternational_phone_number opening_hours وwebsite

الغلاف الجوي

تتضمّن فئة "الجوّ" الحقول التالية: price_level وrating وreviews user_ratings_total

اطّلِع على مزيد من المعلومات عن حقول الأماكن. لمزيد من المعلومات حول كيفية تحصيل رسوم طلبات بيانات "الأماكن"، يُرجى الاطّلاع على الاستخدام والفوترة.

الردود على تفاصيل المكان

رموز الحالة

يحتوي عنصر الاستجابة PlacesServiceStatus على حالة الطلب، وقد يحتوي على معلومات تصحيح الأخطاء لمساعدتك في تحديد سبب عدم نجاح طلب تفاصيل المكان. في ما يلي القيم المحتملة للحالة:

  • INVALID_REQUEST: كان هذا الطلب غير صالح.
  • OK: يحتوي الردّ على نتيجة صالحة.
  • OVER_QUERY_LIMIT: تجاوزت صفحة الويب حصتها من الطلبات
  • NOT_FOUND لم يتم العثور على الموقع الجغرافي المُشار إليه في قاعدة بيانات "الأماكن".
  • REQUEST_DENIED: لا يُسمح لصفحة الويب باستخدام مكتبة PlacesService.
  • UNKNOWN_ERROR: تعذّر processingمعالجة طلب PlacesService بسبب خطأ في الخادم. قد ينجح الطلب إذا حاولت مرة أخرى.
  • ZERO_RESULTS: لم يتم العثور على أي نتيجة لهذا الطلب.

نتائج تفاصيل المكان

يؤدي طلب getDetails() الناجح إلى عرض عنصر PlaceResult يتضمّن السمات التالية:

  • ‫address_components: مصفوفة تحتوي على المكونات المنفصلة السارية على هذا العنوان

    يحتوي كلّ مكوّن من مكوّنات العنوان عادةً على الحقول التالية:

    • types[] هو صفيف يشير إلى نوع مكوّن العنوان. اطّلِع على قائمة الأنواع المتوافقة.
    • long_name هو الوصف النصي الكامل أو اسم مكوّن العنوان كما يعرضه "محوِّل العناوين الجغرافية".
    • short_name هو اسم نصي مختصر لمكوّن العنوان ، إن توفّر. على سبيل المثال، قد يحتوي أحد مكوّنات العنوان لولاية ألاسكا على long_name‏ "ألاسكا" و short_name‏ "AK" باستخدام الاختصار البريدي المكوّن من حرفَين.

    يُرجى ملاحظة الحقائق التالية حول الصفيف address_components[]:

    • قد تحتوي صفيف مكوّنات العنوان على مكوّنات أكثر من formatted_address.
    • لا تتضمّن المصفوفة بالضرورة جميع الكيانات السياسية التي تحتوي على عنوان، باستثناء تلك المضمّنة في formatted_address. لاسترداد جميع الكيانات السياسية التي تحتوي على عنوان معيّن، يجب استخدام الترميز الجغرافي العكسي، مع تمرير خط العرض/خط الطول للعنوان كمَعلمة للطلب.
    • لا يمكن ضمان أن يظل تنسيق الردّ كما هو بين الطلبات. على وجه الخصوص، يختلف عدد address_components حسب العنوان المطلوب، ويمكن أن يتغيّر بمرور الوقت للعنوان نفسه. يمكن أن يغيّر المكوّن موضعه في الصفيف. يمكن أن يتغيّر نوع المكوّن. قد يكون أحد المكوّنات مفقودًا في ردّ لاحق.
  • يشير الرمز business_status إلى حالة تشغيل المكان، إذا كان نشاطًا تجاريًا. يمكن أن يحتوي على إحدى القيم التالية:
    • OPERATIONAL
    • CLOSED_TEMPORARILY
    • CLOSED_PERMANENTLY
    في حال عدم توفّر بيانات، لن يتم عرض business_status.
  • ‫formatted_address: العنوان السهل القراءة لهذا المكان

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

    يتألّف العنوان المنسَّق منطقيًا من مكوّن عنوان واحد أو أكثر. على سبيل المثال، يتألّف العنوان "111 شارع 8، القاهرة، القاهرة" من المكوّنات التالية: "111" (رقم الشارع)، "شارع 8" (المسار)، و"القاهرة" (المدينة) و "القاهرة" (الولاية).

    لا تُحلِّل العنوان المنسَّق آليًا. بدلاً من ذلك، يجب استخدام عناصر العنوان الفردية التي تتضمّنها استجابة واجهة برمجة التطبيقات بالإضافة إلى حقل العنوان المنسَّق.

  • formatted_phone_number: رقم هاتف المكان بالتنسيق وفقًا للمعيار الإقليمي للرقم
  • geometry: المعلومات المتعلّقة بهندسة المكان ويشمل ذلك ما يلي:
    • تقدّم location خطي العرض والطول للمكان.
    • viewport تحدِّد إطار العرض المفضّل على الخريطة عند عرض هذا المكان.
  • ‫permanently_closed (ميزة متوقّفة نهائيًا) هي علامة منطقية تشير إلى ما إذا كان المكان قد تم إغلاقه نهائيًا أو مؤقتًا (القيمة true). لا تستخدِم permanently_closed. بدلاً من ذلك، استخدِم business_status للاطّلاع على الحالة التشغيلية للأنشطة التجارية.
  • plus_code (راجِع رمز الموقع المفتوح ورموز Plus Codes) هو مرجع موقع جغرافي مشفَّر، يتم الحصول عليه من إحداثيات خطوط الطول والعرض، ويمثّل منطقة: 1/8000 من الدرجة في 1/8000 من الدرجة (حوالي 14 مترًا في 14 مترًا عند خط الاستواء) أو أصغر. يمكن استخدام رموز Plus Codes كبديل لعناوين الشوارع في الأماكن التي لا تتوفّر فيها (حيث لا يتم ترقيم المباني أو تسمية الشوارع).

    يتم تنسيق رمز الموقع المفتوح كرمز عالمي ورمز مركب:

    • global_code هو رمز منطقة مكوّن من 4 أحرف ورمز محلي مكوّن من 6 أحرف أو أكثر (849VCWC8+R9).
    • compound_code هو رمز محلي مكوّن من 6 أحرف أو أكثر يتضمّن موقعًا جغرافيًا واضحًا (CWC8+R9، ماونتن فيو، كاليفورنيا، الولايات المتحدة). لا تُحلِّل هذا المحتوى آليًا.
    يتم عادةً عرض كل من الرمز الشامل والرمز المركب. ومع ذلك، إذا كانت النتيجة في موقع جغرافي بعيد (مثل محيط أو صحراء)، قد يتم عرض الرمز الشامل فقط.
  • html_attributions: نص الإحالة الذي سيتم عرضه لهذه النتيجة الخاصة بالموقع الجغرافي
  • ‫icon: عنوان URL لمصدر صورة يمكن استخدامه لتمثيل نوع هذا المكان
  • يحتوي international_phone_number على رقم هاتف المكان بالتنسيق الدولي. يتضمّن التنسيق الدولي رمز البلد، ويتمّ وضع علامة الجمع (+) قبله. على سبيل المثال، رمز international_phone_number لمكتب Google في سيدني، أستراليا هو +61 2 9374 4000.
  • name: اسم المكان
  • utc_offset تم إيقافه نهائيًا في Places Library، استخدِم utc_offset_minutes بدلاً من ذلك.
  • يحتوي الحقل utc_offset_minutes على عدد الدقائق التي تختلف بها المنطقة الزمنية الحالية لهذا المكان عن التوقيت العالمي المنسق. على سبيل المثال، بالنسبة إلى الأماكن في سيدني بأستراليا خلال التوقيت الصيفي، سيكون ذلك 660 (+11 ساعة من التوقيت العالمي المنسَّق)، وبالنسبة إلى الأماكن في كاليفورنيا خارج التوقيت الصيفي، سيكون ذلك -480 (-8 ساعات من التوقيت العالمي المنسَّق).
  • يحتوي opening_hours على المعلومات التالية:
    • open_now (تم إيقافه نهائيًا في Places Library وMaps JavaScript API، استخدِم opening_hours.isOpen() بدلاً منه. يمكنك مشاهدة هذا الفيديو لمعرفة كيفية استخدام isOpen مع "تفاصيل المكان".) هي قيمة منطقية تشير إلى ما إذا كان المكان مفتوحًا في الوقت الحالي.
    • periods[] هي صفيف لفترات العمل التي تغطّي سبعة أيام، بدءًا من الأحد، بترتيب زمني. تحتوي كل فترة على ما يلي:
      • يحتوي open على عنصرَي يوم ووقت يصِف وقت افتتاح المكان:
        • day رقم من 0 إلى 6 يمثّل أيام الأسبوع بدءًا من الأحد على سبيل المثال، 2 تعني الثلاثاء.
        • يمكن أن يحتوي time على وقت من اليوم بتنسيق 24 ساعة hhmm (تكون القيم في النطاق 0000-2359). سيتم تسجيل time حسب المنطقة الزمنية للمكان.
      • قد يحتوي close على زوج من عناصر اليوم والوقت لوصف وقت إغلاق المكان. ملاحظة: إذا كان مكان مفتوحًا دائمًا، لن يظهر القسم close في الردّ. يمكن للتطبيقات الاعتماد على القيمة "مفتوح دائمًا" التي يتم تمثيلها على أنّها فترة open تحتوي على day بالقيمة 0 وtime بالقيمة 0000، بدون close.
    • weekday_text هي صفيف من سلاسل ستة تمثل ساعات العمل المنسَّقة لكل يوم من أيام الأسبوع. إذا تم تحديد مَعلمة language في طلب "تفاصيل المكان"، ستُعدّل خدمة "الأماكن" تنسيق ساعات العمل وتُجري عليها ترجمة مناسبة لهذه اللغة. يعتمد ترتيب العناصر في هذه الصفيفة على المَعلمة language. تبدأ بعض اللغات الأسبوع يوم الاثنين بينما تبدأ لغات أخرى يوم الأحد.
  • ‫permanently_closed (ميزة متوقّفة نهائيًا) هي علامة منطقية تشير إلى ما إذا كان المكان قد تم إغلاقه نهائيًا أو مؤقتًا (القيمة true). لا تستخدِم permanently_closed. بدلاً من ذلك، استخدِم business_status للاطّلاع على الحالة التشغيلية للأنشطة التجارية.
  • ‫photos[]: مصفوفة من عناصر PlacePhoto يمكن استخدام PlacePhoto للحصول على صورة باستخدام الأسلوب getUrl()، أو يمكنك فحص العنصر بحثًا عن القيم التالية:
    • ‫height: الحد الأقصى لارتفاع الصورة، بالبكسل
    • ‫width: الحد الأقصى لعرض الصورة، بالبكسل
    • html_attributions: نص الإحالة الذي سيتم عرضه مع صورة المكان هذه
  • ‫place_id: معرّف نصي يحدِّد مكانًا بشكل فريد ويمكن استخدامه لاسترداد معلومات عن المكان من خلال طلب تفاصيل المكان. اطّلِع على مزيد من المعلومات عن كيفية الإشارة إلى مكان باستخدام رقم تعريف مكان.
  • ‫rating: تقييم المكان، من 0.0 إلى 5.0، استنادًا إلى المراجعات المجمَّعة للمستخدمين
  • reviews صفيف من مراجعات تصل إلى خمس مراجعات تتألف كل مراجعة من عدة مكوّنات:
    • يحتوي aspects[] على صفيف من عناصر PlaceAspectRating، يقدّم كلّ منها تقييمًا لسمة واحدة من سمات الفندق. يُعدّ العنصر الأول في الصفيف هو الجانب الأساسي. يتم تعريف كل PlaceAspectRating على النحو التالي:
      • type اسم الجانب الذي يتم تقييمه الأنواع التالية متوافقة: appeal، atmosphere وdecor، facilities وfood وoverall، quality وservice.
      • rating تقييم المستخدِم لهذا الصعيد المحدّد، من 0 إلى 3
    • author_name اسم المستخدم الذي أرسل المراجعة يتم إسناد المراجعات المجهولة المصدر إلى "مستخدم Google". إذا تم ضبط مَعلمة language، ستعرض العبارة "مستخدم Google" سلسلة مترجمة.
    • author_url عنوان URL الخاص بالملف الشخصي للمستخدم على Google+، إذا كان متاحًا
    • language رمز لغة IETF يشير إلى اللغة المستخدَمة في مراجعة المستخدم يحتوي هذا الحقل على علامة اللغة الرئيسية فقط، وليس العلامة الثانوية التي تشير إلى البلد أو المنطقة. على سبيل المثال، تتم الإشارة إلى جميع المراجعات باللغة الإنجليزية باسم ‎"en"، وليس ‎"en-AU" أو ‎"en-UK" وما إلى ذلك.
    • rating التقييم العام الذي قدمه المستخدم لهذا المكان يمثّل هذا المقياس عددًا صحيحًا يتراوح بين 1 و5.
    • text مراجعة المستخدم عند مراجعة موقع جغرافي باستخدام "أماكن Google"، تكون المراجعات النصية اختيارية، وبالتالي، قد يكون هذا الحقل فارغًا.
  • types مصفوفة من أنواع هذا المكان (مثل ["political", "locality"] أو ["restaurant", "lodging"]). قد تحتوي هذه المصفوفة على قيم متعدّدة، أو قد تكون فارغة. قد يتمّ إدخال قيم جديدة بدون إشعار مسبق. اطّلِع على قائمة الأنواع المتوافقة.
  • url: عنوان URL لصفحة Google الرسمية لهذا المكان. هذه هي الصفحة التي تملكها Google وتتضمن أفضل المعلومات المتاحة عن المكان. يجب أن ترتبط التطبيقات بهذه الصفحة أو تضمّنها على أي شاشة تعرض نتائج تفصيلية عن المكان للمستخدم.
  • vicinity: عنوان مبسط للمكان، بما في ذلك اسم الشارع ورقمه والمنطقة، ولكن ليس المقاطعة أو الولاية أو الرمز البريدي أو البلد على سبيل المثال، مكتب Google في سيدني، أستراليا، لديه قيمة vicinity‏=5/48 Pirrama Road, Pyrmont. لا يتم عرض السمة vicinity إلا في بحث عن الأماكن القريبة.
  • يعرض website الموقع الإلكتروني الموثوق به لهذا المكان، مثل الصفحة الرئيسية للنشاط التجاري.

ملاحظة: قد لا تتوفّر التقييمات المتعدّدة السمات في جميع المواقع الجغرافية. إذا كانت هناك مراجعات قليلة جدًا، سيتضمّن ردّ التفاصيل إما تقييمًا قديمًا على مقياس من 0.0 إلى 5.0 (إذا كان متاحًا) أو لن يتضمّن أي تقييم على الإطلاق.

الإشارة إلى مكان باستخدام رقم تعريف مكان

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

لاستخدام معرّف مكان في تطبيقك، عليك أولاً البحث عن المعرّف الذي يكون متوفّرًا في PlaceResult من طلب البحث عن مكان أو طلب الحصول على التفاصيل. يمكنك بعد ذلك استخدام رقم تعريف المكان هذا للاطّلاع على تفاصيل المكان.

تكون أرقام تعريف الأماكن مُعفاة من القيود المفروضة على التخزين المؤقت والمذكورة في الفقرة 3.2.3(ب) من بنود خدمة Google Maps Platform. ولذلك، يمكنك تخزين قيم معرّفات الأماكن لاستخدامها لاحقًا. للاطّلاع على أفضل الممارسات عند تخزين أرقام تعريف الأماكن، اطّلِع على نظرة عامة على أرقام تعريف الأماكن.

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);

صور المكان

تتيح لك ميزة "صورة المكان" إضافة محتوًى مصوّرًا بجودة عالية إلى موقعك الإلكتروني. تتيح لك خدمة "صور Google" الوصول إلى ملايين الصور المخزّنة في قاعدة بيانات "الأماكن" و"Google+ Local". عند الحصول على معلومات عن مكان باستخدام طلب "تفاصيل المكان"، سيتم عرض إشارات إلى الصور التي تتضمّن محتوى ذي صلة بالمكان. تعرِض طلبات البحث عن الأماكن المجاورة والبحث النصي أيضًا مرجعًا لصورة واحدة لكل مكان، عند الضرورة. باستخدام خدمة "صور Google"، يمكنك بعد ذلك الوصول إلى الصور المُشار إليها و تغيير حجم الصورة إلى الحجم الأمثل لتطبيقك.

سيتم عرض مصفوفة من كائنات PlacePhoto كجزء من كائن PlaceResult لأي طلب getDetails() أو textSearch() أو nearbySearch() تم تقديمه ضد PlacesService.

ملاحظة: يختلف عدد الصور التي يتم عرضها حسب الطلب.

  • سيعرض "البحث عن الأماكن القريبة" أو "البحث النصي" PlacePhoto عنصرًا واحدًا على الأكثر.
  • سيعرض طلب التفاصيل ما يصل إلى عشرة عناصر PlacePhoto.

يمكنك طلب عنوان URL للصورة المرتبطة من خلال استدعاء الأسلوب PlacePhoto.getUrl() وضبط عنصر PhotoOptions صالح. يسمح لك عنصر PhotoOptions بتحديد الحد الأقصى للارتفاع والعرض المطلوبَين للصورة. إذا تحديد قيمة لكل من maxHeight وmaxWidth، ستغيّر خدمة الصور حجم الصورة إلى أصغر حجم من الاثنين، مع الحفاظ على نسبة العرض إلى الارتفاع الأصلية.

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

function createPhotoMarker(place) {
  var photos = place.photos;
  if (!photos) {
    return;
  }

  var marker = new google.maps.Marker({
    map: map,
    position: place.geometry.location,
    title: place.name,
    icon: photos[0].getUrl({maxWidth: 35, maxHeight: 35})
  });
}

يتم الحصول على الصور التي تعرضها خدمة "صور Google" من مجموعة متنوعة من المواقع الجغرافية، بما في ذلك الصور التي ينشرها مالكو الأنشطة التجارية والمستخدمون. في معظم الحالات، يمكن استخدام هذه الصور بدون نسبها إلى مؤلفها، أو سيتم تضمين عملية تحديد المصدر المطلوبة كجزء من الصورة. ومع ذلك، إذا كان عنصر photo المعروض يتضمّن قيمة في حقل html_attributions، يجب تضمين مصدر الإضافي في تطبيقك في أي مكان تعرض فيه الصورة.