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

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

نظرة عامة

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

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

البدء

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

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

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

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

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

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

الحصص

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

السياسات

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

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

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

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

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

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

البحث عن مكان من طلب البحث

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

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

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

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

  • phoneNumber (مطلوب) رقم هاتف، بتنسيق E.164.
  • fields (مطلوب) حقل أو أكثر من الحقول التي تحدّد أنواع بيانات "الأماكن" المطلوب عرضها
  • locationBias (اختيارية) هي المنطقة المحدّدة للبحث. ويمكن أن يكون ذلك واحدًا مما يلي:
    • مجموعة من إحداثيات لاتّ ولنغ والتي يتم تحديدها على أنها LatLngLiteral أو كائن LatLng
    • حدود مستطيلة (أربع نقاط/خط lng أو كائن 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
(متوقّف في "مكتبة الأماكن" أو Maps API API. استخدِم طلب تفاصيل المكان للحصول على نتائج opening_hours.

الأجواء

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

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

تحديد انحياز الموقع (العثور على طرق المكان)

يمكنك استخدام المعلمة locationBias لجعل نتائج البحث عن المكان أفضل في منطقة معينة. يمكنك ضبط locationBias بالطرق التالية:

انحياز نتائج في منطقة معينة:

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

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

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

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

حدد نطاقًا جغرافيًا للبحث (بالمتر)، يركّز على منطقة معينة:

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

طلبات البحث القريبة

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

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

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

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

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

    يتم تنسيق رمز Plus Codes كرمز عام ورمز مركّب:

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

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_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 (}{/20 JavaScript/Library1} وفي ما يلي} .

جهة اتصال

تتضمّن فئة جهات الاتصال الحقول التالية:
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[] هي مصفوفة تشير إلى type لمكوّن العنوان. راجِع قائمة الأنواع المتوافقة.
    • long_name هو الوصف الكامل أو اسم مكوّن العنوان الذي يعرضه برنامج الترميز الجغرافي.
    • short_name هو اسم نصي مختصر لمكوّن العنوان إذا كان متاحًا. على سبيل المثال، قد يحتوي مكوّن عنوان لولاية ألاسكا على long_name من "ألاسكا" وshort_name من "ألاسكا" باستخدام الاختصار البريدي المكوّن من حرفين.

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

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

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

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

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

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

    يتم تنسيق رمز Plus Codes كرمز عام ورمز مركّب:

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

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