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

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

نظرة عامة

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

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

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

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

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

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

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

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

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

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

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

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

الحصص

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

السياسات

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

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

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

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

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

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

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

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

  • query (مطلوبة) سلسلة النص المطلوب البحث عليها، على سبيل المثال: "مطعم" أو "123 Main Street". ويجب أن يكون هذا الحقل اسمًا لمكان أو عنوانًا أو فئة من المنشآت. يمكن أن تؤدي أي أنواع أخرى من الإدخالات إلى حدوث أخطاء، ولا يمكن ضمان عرض نتائج صالحة. ستعرض 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);
    }
  });
}
عرض مثال

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

تأخذ ميزة "البحث عن مكان" من رقم الهاتف رقم هاتف وترجع إلى مكان. لتقديم طلب "العثور على مكان من رقم الهاتف"، يمكنك استدعاء طريقة PlacesServicefindPlaceFromPhoneNumber()، والتي تأخذ المعلمات التالية:

  • 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 Main Street". ويجب أن يكون اسمًا لمكان أو عنوانًا أو فئة من المنشآت. يمكن أن تؤدي أي أنواع أخرى من الإدخالات إلى حدوث أخطاء، ولا يمكن ضمان عرض نتائج صالحة. ستعرض خدمة "الأماكن" النتائج المطابِقة المرشحة استنادًا إلى هذه السلسلة، ثم ترتّب النتائج استنادًا إلى مدى صلتها بالموضوع. تصبح هذه المَعلمة اختيارية إذا تمّ أيضًا استخدام المَعلمة type في طلب البحث.
  • اختياريًا:
    • openNow — قيمة منطقية تشير إلى أنّ خدمة "الأماكن" يجب أن تعرض فقط الأماكن التي تكون مفتوحة لمزاولة النشاط التجاري وقت إرسال طلب البحث لن يتم عرض الأماكن التي لا تحدّد ساعات العمل في قاعدة بيانات "أماكن Google" إذا ضمّنت هذه المعلمة في طلب البحث. وليس هناك أيّ تأثير لضبط openNow على false.
    • minPriceLevel وmaxPriceLevel - لحصر النتائج بتلك الأماكن ضمن مستوى السعر المحدّد فقط. تتراوح القيم الصالحة بين 0 (الأقل تكلفة) و4 (الأكثر تكلفة).
    • أيّ ممّا يلي:
      • bounds — كائن google.maps.LatLngBounds يحدد المستطيل المطلوب البحث فيه، أو
      • location وradius: يمكنك انحياز النتائج إلى دائرة محدّدة من خلال ضبط معلَمة location وradius. وسيؤدي هذا إلى تفضيل خدمة "الأماكن" لعرض النتائج داخل تلك الدائرة. وقد يستمر عرض النتائج خارج المنطقة المحددة. يأخذ الموقع الجغرافي عنصر google.maps.LatLng، ويأخذ نصف القطر عددًا صحيحًا بسيطًا يمثل نصف قطر الدائرة بالمتر. يبلغ الحد الأقصى المسموح به للنطاق الجغرافي 50 ألف متر.
    • 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 شارع السلام، القاهرة"، من العناصر التالية: "111" (رقم الشارع) و"الجادة الثامنة" (المسار) و"نيويورك" (المدينة) و "نيويورك" (الولاية الأمريكية).

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

  • geometry: معلومات عن المكان من حيث الأشكال الهندسية ويشمل ذلك ما يلي:
    • توفِّر السمة location خط العرض وخط الطول للمكان.
    • تحدّد السمة viewport إطار العرض المفضّل على الخريطة عند عرض هذا المكان.
  • permanently_closed (متوقّفة نهائيًا) هي علامة منطقية تشير إلى ما إذا كان قد تم إيقاف المكان نهائيًا أو بشكل مؤقت (القيمة true). لا تستخدم permanently_closed. بدلاً من ذلك، استخدِم business_status للاطّلاع على الحالة التشغيلية للأنشطة التجارية.
  • plus_code (راجِع رمز الموقع المفتوح ورموز المواقع المفتوحة) هو مرجع موقع مشفّر، يتم اشتقاقه من إحداثيات خط الطول وخط العرض ويمثّل منطقة: 1/8, 000 درجة وزاوية 1/8, 000 درجة من الدرجة (حوالي 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 هي قيمة منطقية تشير إلى ما إذا كان المكان مفتوحًا في الوقت الحالي (تم إيقافه في "مكتبة الأماكن" وواجهة برمجة تطبيقات 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;

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;
الاطّلاع على مثال

تجربة النموذج

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

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

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

يتم طلب تفاصيل المكان من خلال استدعاء طريقة 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 وurl وutc_offset و{120/icon و{19/2} ووواجهة برمجة التطبيقات و/ متوقّفة نهائيًاutc_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 شارع السلام، القاهرة"، من العناصر التالية: "111" (رقم الشارع) و"الجادة الثامنة" (المسار) و"نيويورك" (المدينة) و "نيويورك" (الولاية الأمريكية).

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

  • formatted_phone_number: رقم هاتف المكان، منسَّق وفقًا للاصطلاح الإقليمي.
  • geometry: معلومات عن المكان من حيث الأشكال الهندسية ويشمل ذلك ما يلي:
    • توفِّر السمة location خط العرض وخط الطول للمكان.
    • تحدّد السمة viewport إطار العرض المفضّل على الخريطة عند عرض هذا المكان.
  • permanently_closed (متوقّفة نهائيًا) هي علامة منطقية تشير إلى ما إذا كان قد تم إيقاف المكان نهائيًا أو بشكل مؤقت (القيمة true). لا تستخدم permanently_closed. بدلاً من ذلك، استخدِم business_status للاطّلاع على الحالة التشغيلية للأنشطة التجارية.
  • plus_code (راجِع رمز الموقع المفتوح ورموز المواقع المفتوحة) هو مرجع موقع مشفّر، يتم اشتقاقه من إحداثيات خط الطول وخط العرض ويمثّل منطقة: 1/8, 000 درجة وزاوية 1/8, 000 درجة من الدرجة (حوالي 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 متوقف نهائيًا في "مكتبة الأماكن" وواجهة برمجة تطبيقات 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 ساعة 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". في حال ضبط معلَمة لغة، ستعرض العبارة "مستخدم Google" سلسلة مترجَمة.
    • author_url: عنوان URL للمستخدمين في الملف الشخصي في +Google، في حال توفّره
    • language يشير هذا الرمز إلى اللغة المستخدَمة في مراجعة المستخدم من قِبل مجموعة مهندسي شبكة الإنترنت (IETF). يحتوي هذا الحقل على علامة اللغة الرئيسية فقط، وليس على العلامة الثانوية التي تشير إلى البلد أو المنطقة. على سبيل المثال، يتم وضع علامة "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 (في حال توفّره) أو عدم تضمين أي تقييم على الإطلاق.

استخدام مكوِّن "نظرة عامة على المكان"

ملاحظة: يستخدم هذا النموذج مكتبة مفتوحة المصدر. يمكنك الاطّلاع على ملف README للحصول على الدعم والملاحظات المتعلقة بالمكتبة.

جرِّب مكوّنات الويب. استخدِم مكوّن الويب نظرة عامة على المكان للحصول على تفاصيل المكان من خلال تمثيل مرئي.

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

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

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