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

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
اختيار نظام أساسي: Android iOS JavaScript خدمة الويب

نظرة عامة

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

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

البدء

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

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

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

لعرض قائمة بواجهات برمجة التطبيقات التي تم تمكينها:

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

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

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

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

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

إضافة الأماكن إلى قائمة قيود واجهة برمجة التطبيقات لمفتاح واجهة برمجة التطبيقات

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

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

الحصص

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

السياسات

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

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

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

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

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

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

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

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

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

البحث عن مكان من رقم الهاتف

يتطلب البحث عن مكان من رقم الهاتف رقم هاتف ويعرض مكانًا. لتقديم طلب "العثور على مكان من رقم هاتف"، يمكنك استدعاء طريقة findPlaceFromPhoneNumber() في PlacesService، والتي تستخدم المعلمات التالية:

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

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

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

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

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

أساسية

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

تبدأ عمليات البحث النصي عن طريق استدعاء طريقة PlacesService في textSearch(). 

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 يحدد المستطيل الذي يتم البحث فيه، أو
      • a location وradius — يمكنك انحياز نتائج إلى دائرة محددة عن طريق تمرير location ومعلمة radius. سيؤدي هذا إلى توجيه خدمة الأماكن لتفضيل عرض النتائج داخل هذه الدائرة. قد يستمر عرض النتائج خارج المنطقة المحددة. يأخذ الموقع كائن google.maps.LatLng، ويأخذ النطاق الجغرافي عددًا صحيحًا بسيطًا يمثل نصف قطر الدائرة بالأمتار. الحد الأقصى المسموح به للنطاق هو 50000 متر.
    • 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: غير مسموح لصفحة الويب باستخدام خدمة الأماكن.
  • UNKNOWN_ERROR: تعذّرت معالجة طلب خدمة الأماكن بسبب خطأ في الخادم. قد ينجح الطلب في حال إعادة المحاولة.
  • ZERO_RESULTS: لم يتم العثور على نتائج لهذا الطلب.

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

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

قد يتضمن كل كائن PlaceResult الخصائص التالية:

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

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

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

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

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

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

    • global_code هو رمز منطقة مكوّن من 4 أحرف ورمز محلي مكوّن من 6 أحرف أو أكثر (849VCWC8+R9).
    • compound_code هو رمز محلي مكون من 6 أحرف أو أكثر يتضمّن موقعًا جغرافيًا صريحًا (CWC8+R9, Mountain View, CA, USA). لا تحلل هذا المحتوى برمجيًا.
    يتم عادةً عرض كل من الرمز العام والرمز المركَّب. ومع ذلك، إذا كانت النتيجة في موقع جغرافي بعيد (مثلاً، محيط أو صحراء)، قد يتم عرض الرمز العالمي فقط.
  • html_attributions: صفيف من السمات التي يجب عرضها عند عرض نتائج البحث. يحتوي كل إدخال في المصفوفة على نص HTML لإحالة واحدة. ملاحظة: هذه عبارة عن تجميع لكل الإحالات في استجابة البحث بالكامل. وبالتالي، تحتوي جميع عناصر PlaceResult في الاستجابة على قوائم إحالة متطابقة.
  • تعرض icon عنوان URL لرمز PNG 71px x 71px PNG.
  • تعرض icon_mask_base_uri عنوان URL الأساسي لرمز غير ملون، مطروحًا منه الامتداد svg. أو png.
  • تعرض icon_background_color رمز لون HEX التلقائي لفئة المكان.
  • name: اسم المكان.
  • قد يحتوي opening_hours على المعلومات التالية:
    • open_now هي قيمة منطقية تشير إلى ما إذا كان المكان مفتوحًا في الوقت الحالي (تم إيقاف العمل به في مكتبة الأماكن، وواجهة برمجة تطبيقات JavaScript للخرائط، واستخدِم 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_component', 'opening_hours', 'geometry'] استخدم نقطة عند تحديد قيم مركبة. على سبيل المثال: opening_hours.weekday_text

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

أساسية

تتضمن الفئة الأساسية الحقول التالية:
address_component، 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 (،WIDGET2}/Maps1}}،}،}Google{/1

التواصل

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

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

يعرض طلب getDetails() الناجح كائن PlaceResult بالخصائص التالية:

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

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

    • types[] عبارة عن مصفوفة تشير إلى نوع مكوِّن العنوان. اطّلِع على قائمة الأنواع المتوافقة.
    • long_name هو الوصف النصي الكامل أو اسم مكوّن العنوان كما هو مكتوب بواسطة Geocoder.
    • 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 Avenue, New York, NY" من المكوّنات التالية: "111" (رقم الشارع) و"8th Avenue" (المسار) و"New York" (المدينة) و"NY" (ولاية الولايات المتحدة).

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

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

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

    • global_code هو رمز منطقة مكوّن من 4 أحرف ورمز محلي مكوّن من 6 أحرف أو أكثر (849VCWC8+R9).
    • compound_code هو رمز محلي مكون من 6 أحرف أو أكثر يتضمّن موقعًا جغرافيًا صريحًا (CWC8+R9, Mountain View, CA, USA). لا تحلل هذا المحتوى برمجيًا.
    يتم عادةً عرض كل من الرمز العام والرمز المركَّب. ومع ذلك، إذا كانت النتيجة في موقع جغرافي بعيد (مثلاً، محيط أو صحراء)، قد يتم عرض الرمز العالمي فقط.
  • 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 عدد الدقائق التي تتم فيها معادلة المنطقة الزمنية الحالية لهذا المكان من التوقيت العالمي المنسق (UTC). على سبيل المثال، بالنسبة إلى الأماكن في سيدني بأستراليا خلال التوقيت الصيفي، ستكون النتيجة 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" وليس "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". ولذلك، يمكنك تخزين قيم معرّفات الأماكن لاستخدامها لاحقًا. للاطّلاع على أفضل الممارسات عند تخزين أرقام تعريف الأماكن، اطّلِع على نظرة عامة على رقم تعريف المكان.

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