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

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

نظرة عامة

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

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

البدء

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

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

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

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

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

جارٍ تحميل المكتبة

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

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

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

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

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

الحدود القصوى للاستخدام والسياسات

الحصص

تشارك مكتبة الأماكن حصة استخدام مع واجهة برمجة تطبيقات الأماكن كما هو موضح في مستندات حدود الاستخدام الخاصة بواجهة برمجة تطبيقات الأماكن.

السياسات

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

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

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

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

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

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

العثور على مكان من الاستعلام

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

  • 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);
    }
  });
}
عرض مثال

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

تأخذ ميزة "العثور على المكان" من رقم الهاتف رقم هاتف وترجع مكانًا. لتقديم طلب "العثور على مكان" من رقم الهاتف، اتصل بطريقة 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
(تم إيقافها في "مكتبة الأماكن"، وواجهة برمجة تطبيقات JavaScript للخرائط. استخدِم طلب تفاصيل المكان للحصول على نتائج 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 يحدّد منطقة البحث المستطيلة، أو
    • تمثّل هذه السمة 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 يحدّد المستطيل المطلوب البحث فيه
      • location وradius: يمكنك تحيز النتائج لدائرة محددة من خلال تمرير معلَمة location والمَعلمة radius. وسيؤدي ذلك إلى توجيه خدمة "الأماكن" إلى خيار تفضيل عرض النتائج داخل تلك الدائرة. قد يستمر عرض النتائج خارج المنطقة المحددة. يأخذ الموقع الجغرافي الكائن google.maps.LatLng، ويأخذ نصف القطر عددًا صحيحًا بسيطًا يمثّل نصف قطر الدائرة بالمتر. الحد الأقصى لنصف القطر المسموح به هو 50,000 متر.
    • type - لحصر النتائج بالأماكن المطابقة للنوع المحدّد. يمكن تحديد نوع واحد فقط (في حال تقديم أكثر من نوع واحد، سيتم تجاهل جميع الأنواع التي تلي الإدخال الأول). راجِع قائمة الأنواع المتوافقة.

يجب أيضًا ضبط طريقة معاودة الاتصال إلى 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: تعذّرت معالجة طلب PlacesService بسبب خطأ في الخادم. قد ينجح الطلب إذا حاولت مرة أخرى.
  • ZERO_RESULTS: لم يتم العثور على نتائج لهذا الطلب.

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

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

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

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

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

    يتكون العنوان المنسَّق منطقيًا من مكوّن عنوان واحد أو أكثر. على سبيل المثال، يتكوّن العنوان "111 8th Africa, New York, NY" من المكونات التالية: "111" (رقم الشارع) و"8th Street" (المسار) و"New York" (المدينة) و "NY" (ولاية الولايات المتحدة).

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

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

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

    • 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 هي قيمة منطقية تشير إلى ما إذا كان المكان مفتوحًا في الوقت الحالي (متوقّف نهائيًا في "مكتبة الأماكن" وواجهة برمجة تطبيقات JavaScript للخرائط، ويمكنك استخدام utc_offset_minutes بدلاً من ذلك).
  • place_id هو معرّف نصي يحدّد المكان بشكل فريد. لاسترداد معلومات عن المكان، أدخِل هذا المعرّف في طلب تفاصيل المكان. اطّلِع على مزيد من المعلومات عن كيفية الإحالة إلى مكان باستخدام معرّف مكان.
  • يحتوي rating على تقييم المكان، من 0.0 إلى 5.0، استنادًا إلى مراجعات المستخدمين المجمَّعة.
  • types مصفوفة من الأنواع لهذا المكان (على سبيل المثال، ["political", "locality"] أو ["restaurant", "lodging"]). قد تحتوي هذه المصفوفة على قيم متعددة أو قد تكون فارغة. يمكن تقديم قيم جديدة بدون إشعار مسبق. راجِع قائمة الأنواع المتوافقة.
  • vicinity: عنوان مبسّط للمكان، بما في ذلك اسم الشارع ورقم الشارع والمنطقة المحلية، وليس الإقليم/الولاية أو الرمز البريدي أو البلد. على سبيل المثال، قيمة vicinity لمكتب Google في مدينة سيدني بأستراليا هي 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 و/2} وutc_offsetutc_offset_minutesvicinity

التواصل

تتضمّن فئة "جهة الاتصال" الحقول التالية:
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: تعذّرت معالجة طلب 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 8th Africa, New York, NY" من المكونات التالية: "111" (رقم الشارع) و"8th Street" (المسار) و"New York" (المدينة) و "NY" (ولاية الولايات المتحدة).

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

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

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

    • 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 متوقّف نهائيًا في "مكتبة الأماكن" أو واجهة برمجة تطبيقات JavaScript للخرائط، لذا يمكنك استخدام utc_offset_minutes بدلاً من ذلك.
  • يتضمّن utc_offset_minutes عدد الدقائق التي يتم تعويضها عن المنطقة الزمنية الحالية لهذا المكان من التوقيت العالمي المتفق عليه. على سبيل المثال، بالنسبة إلى الأماكن في سيدني بأستراليا أثناء التوقيت الصيفي، قد يكون النطاق 660 (+11 ساعة من التوقيت العالمي المنسَّق)، وبالنسبة إلى الأماكن في كاليفورنيا خارج التوقيت الصيفي، سيكون الرقم -480 (أقل من 8 ساعات من التوقيت العالمي المنسَّق).
  • يحتوي opening_hours على المعلومات التالية:
    • open_now (متوقّف نهائيًا في "مكتبة الأماكن" أو واجهة برمجة تطبيقات JavaScript للخرائط، لذا يمكنك استخدام opening_hours.isOpen() بدلاً من ذلك. يمكنك مشاهدة هذا الفيديو للتعرّف على كيفية استخدام isOpen مع "تفاصيل المكان".) هي قيمة منطقية تشير إلى ما إذا كان المكان مفتوحًا في الوقت الحالي.
    • تمثّل السمة periods[] مجموعة من فترات الافتتاح التي تغطي سبعة أيام، بدءًا من يوم الأحد، بترتيب زمني. وتحتوي كل فترة على ما يلي:
      • يحتوي open على كائنين من اليوم والوقت يصفان وقت فتح المكان:
        • day رقمًا من 0 إلى 6 يتطابق مع أيام الأسبوع، بدءًا من يوم الأحد. على سبيل المثال، 2 تعني الثلاثاء.
        • قد يحتوي الحقل time على وقت من اليوم بتنسيق 24 ساعة (تتراوح القيم بين 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". في حال ضبط معلَمة لغة، ستعرض العبارة "مستخدم 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: عنوان مبسّط للمكان، بما في ذلك اسم الشارع ورقم الشارع والمنطقة المحلية، وليس الإقليم/الولاية أو الرمز البريدي أو البلد. على سبيل المثال، قيمة vicinity لمكتب Google في مدينة سيدني بأستراليا هي 5/48 Pirrama Road, Pyrmont. ولا يتم عرض السمة vicinity إلا عند إجراء بحث عن قرب.
  • تعرض السمة website الموقع الإلكتروني الموثوق به لهذا المكان، مثل الصفحة الرئيسية لنشاط تجاري.

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

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

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

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

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

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 المحلي. عند حصولك على معلومات المكان من خلال طلب تفاصيل المكان، سيتم إرجاع مراجع الصور للمحتوى الفوتوغرافي ذي الصلة. وتعرض طلبات البحث عن المواقع القريبة والبحث النصي أيضًا مرجعًا واحدًا للصورة لكل مكان، وذلك عندما يكون ذلك ذا صلة. باستخدام خدمة الصور، يمكنك بعد ذلك الوصول إلى الصور المشار إليها وتغيير حجم الصورة إلى الحجم الأمثل لتطبيقك.

سيتم عرض مصفوفة من كائنات 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})
  });
}

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