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

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

نظرة عامة

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

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

البدء

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

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

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

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

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

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

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

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

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

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

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

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

الحصص

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

السياسات

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

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

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

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

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

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

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

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

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

عليك أيضًا تمرير طريقة معاودة الاتصال إلى 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
    • حدود مستطيلة (أربعة نقاط خط طول/خط كبير، أو كائن LatLNGBounds)
    • نصف القُطر (بالمتر) المرتكز على خط العرض/lg

عليك أيضًا تمرير طريقة معاودة الاتصال إلى 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}

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

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

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

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

var map;
var service;
var infowindow;

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

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

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

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

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

عرض مثال

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

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

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

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

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

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

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

var map;
var service;
var infowindow;

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

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

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

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

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

ردود البحث

رموز الحالة

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

  • INVALID_REQUEST: هذا الطلب غير صالح.
  • OK: تحتوي الإجابة على نتيجة صالحة.
  • OVER_QUERY_LIMIT: تجاوزت صفحة الويب حصة الطلبات.
  • REQUEST_DENIED: لا يُسمح لصفحة الويب باستخدام خدمة ServiceService.
  • UNKNOWN_ERROR: تعذّرت معالجة طلب الأماكن في الخدمة بسبب خطأ في الخادم. قد تتم معالجة الطلب بنجاح في حال إعادة المحاولة.
  • 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 لرمز ملوّن 71 × 71 بكسل بتنسيق 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_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 (0}}الإصدار الثاني }}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: لا يُسمح لصفحة الويب باستخدام خدمة ServiceService.
  • UNKNOWN_ERROR: تعذّرت معالجة طلب الأماكن في الخدمة بسبب خطأ في الخادم. قد تتم معالجة الطلب بنجاح في حال إعادة المحاولة.
  • ZERO_RESULTS: لم يتمّ العثور على نتائج لهذا الطلب.

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

تعرض استدعاء getDetails() الناجح عنصر PlaceResult مع السمات التالية:

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

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

    • types[] هي مصفوفة تشير إلى type لمكوّن العنوان. اطّلِع على قائمة الأنواع المتوافقة.
    • 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 شارع 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 متوقّفة نهائيًا في "مكتبة الأماكن" وMaps JavaScript API، استخدِم 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 على وقت من اليوم بتنسيق hhmm 24 ساعة (تتراوح القيم بين 0000 و2359). سيتم الإبلاغ عن time في المنطقة الزمنية للمكان.
      • قد تحتوي السمة close على زوج من العناصر اليومية والوقت عند إغلاق المكان. ملاحظة: إذا كان أحد الأماكن مفتوحًا دائمًا، لن يتوفّر القسم close في الرد. يمكن أن تعتمد التطبيقات على أن تكون مفتوحة دائمًا كفترة open تحتوي على day بالقيمة 0 وtime بالقيمة 0000، وليس close.
    • تمثّل السمة weekday_text مصفوفة من سبعة سلاسل تمثّل ساعات العمل المنسّقة لكل يوم من أيام الأسبوع. إذا تم تحديد مَعلمة language في طلب تفاصيل المكان، ستعمل خدمة "الأماكن" على تنسيق ساعات العمل وترجمتها على نحو مناسب لتلك اللغة. ويعتمد ترتيب العناصر في هذه المصفوفة على المعلَمة language. وبعض اللغات تبدأ الأسبوع يوم الاثنين بينما تبدأ اللغات الأخرى يوم الأحد.
  • permanently_closed (متوقّفة نهائيًا) هي علامة منطقية تشير إلى ما إذا كان المكان قد تمّ إيقافه نهائيًا أو بشكل مؤقت (القيمة true). لا تستخدم permanently_closed. بدلاً من ذلك، يمكنك استخدام business_status للاطّلاع على الحالة التشغيلية للأنشطة التجارية.
  • photos[]: مصفوفة من PlacePhoto عنصر. ويمكن استخدام السمة PlacePhoto للحصول على صورة باستخدام الطريقة getUrl()، أو يمكنك فحص العنصر بحثًا عن القيم التالية:
    • height: الحد الأقصى لطول الصورة بالبكسل.
    • width: الحد الأقصى لعرض الصورة بالبكسل.
    • html_attributions: نص الإحالة الذي سيتم عرضه مع صورة هذا المكان.
  • place_id: معرِّف نصي يحدِّد مكانًا فريدًا ويمكن استخدامه لاسترداد المعلومات عن المكان من خلال طلب تفاصيل المكان. اطّلِع على مزيد من المعلومات حول كيفية الإشارة إلى مكان باستخدام رقم تعريف المكان.
  • rating: تقييم المكان من 0.0 إلى 5.0، استنادًا إلى مراجعات المستخدمين المجمّعة
  • reviews مصفوفة من خمس مراجعات كحد أقصى. تتكوّن كل مراجعة من عدة مكوّنات:
    • يحتوي الحقل aspects[] على صفيف من PlaceAspectRating عنصر، يقدّم كل منها تقييمًا لسمة واحدة من المبنى. ويُعتبر العنصر الأول في المصفوفة السمة الأساسية. يتم تعريف كل PlaceAspectRating على النحو التالي:
      • type اسم الجانب الذي يتم تقييمه. تتوفّر الأنواع التالية: appeal وatmosphere وdecor وfacilities وfood وoverall وquality وservice.
      • rating تمثّل هذه السمة تقييم المستخدم لهذا الجانب بالتحديد، من 0 إلى 3.
    • author_name اسم المستخدم الذي أرسل المراجعة. وتُنسب المراجعات المجهولة المصدر إلى "مستخدم Google". في حال ضبط معلَمة لغة، ستعرض العبارة "مستخدم Google" سلسلة مترجَمة.
    • author_url عنوان URL الذي ينقل إلى الملف الشخصي للمستخدمين في Google+ ، في حال توفّره.
    • language رمز لغة مجموعة مهندسي شبكة الإنترنت (IETF) يشير إلى اللغة المستخدمة في مراجعة المستخدم. يحتوي هذا الحقل على علامة اللغة الرئيسية فقط، وليس العلامة الثانوية التي تشير إلى البلد أو المنطقة. على سبيل المثال، تم وضع علامة على جميع المراجعات باللغة الإنجليزية على أنّها "en"، وليس "en-AU" أو "en-UK" وما إلى ذلك.
    • rating هو التقييم العام للمستخدم لهذا المكان. هذا عدد صحيح يتراوح بين 1 و5.
    • text: مراجعة المستخدم وعند مراجعة أحد المواقع الجغرافية في "أماكن Google"، تُعتبر المراجعات النصية اختيارية، وبالتالي قد يكون هذا الحقل فارغًا.
  • types مصفوفة من الأنواع لهذا المكان (على سبيل المثال، ["political", "locality"] أو ["restaurant", "lodging"]: قد تحتوي هذه المصفوفة على قيم متعدّدة، أو قد تكون فارغة. قد يتم تقديم قيم جديدة بدون إشعار مسبق. اطّلِع على قائمة الأنواع المتوافقة.
  • url: عنوان URL لصفحة Google الرسمية لهذا المكان. هذه هي الصفحة التي تملكها Google وتحتوي على أفضل المعلومات المتاحة حول المكان. يجب أن تتضمّن التطبيقات رابطًا أو يؤدي إلى هذه الصفحة على أي شاشة تعرض نتائج تفصيلية حول المكان للمستخدم.
  • vicinity: عنوان مبسّط للمكان، بما في ذلك اسم الشارع ورقمه ومنطقته المحلية، ولكن ليس المقاطعة/الولاية أو الرمز البريدي أو البلد على سبيل المثال، لدى مكتب 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، فيجب تضمين الإسناد الإضافي في تطبيقك حيثما تعرض الصورة.