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

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

أصبح الجيل التالي من Places API متاحًا الآن مع إصدار فئة المكان

نظرة عامة

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

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

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

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

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

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

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

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

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

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

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

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

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

يؤدي تطبيق قيود واجهة برمجة التطبيقات على المفاتيح إلى تقييد استخدام مفتاح واجهة برمجة التطبيقات بمفتاح واحد أو أو المزيد من واجهات برمجة التطبيقات أو حزم SDK. سيتم تنفيذ الطلبات المُرسَلة إلى واجهة برمجة التطبيقات أو حزمة تطوير البرامج (SDK) المرتبطة بمفتاح واجهة برمجة التطبيقات. . سيتم تنفيذ الطلبات المُرسَلة إلى واجهة برمجة تطبيقات أو حزمة تطوير برامج (SDK) غير مرتبطة بمفتاح واجهة برمجة التطبيقات. إخفاق. لتقييد استخدام مفتاح واجهة برمجة تطبيقات مع مكتبة الأماكن، وواجهة برمجة تطبيقات JavaScript للخرائط:

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

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

الحصص

تشارك مكتبة الأماكن حصة استخدام مع Places API كما هو موصوف في وثائق حدود الاستخدام للموقع Places API.

السياسات

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

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

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

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

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

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

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

• العثور على مكان من طلب البحث
• العثور على مكان من رقم الهاتف

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

تأخذ ميزة "البحث عن مكان من الاستعلام" إدخالاً نصيًا وتعرض مكانًا. يمكن للإدخال عبارة عن أي نوع من بيانات الأماكن، مثل اسم النشاط التجاري أو عنوانه. لإجراء العثور على مكان من طلب البحث، والاتصال بـ 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);
    }
  });
}

الاطّلاع على مثال

العثور على مكان باستخدام رقم الهاتف

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

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

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

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

حقلا "الأماكن" opening_hours.open_now وutc_offset في حزم الأماكن لأجهزة iOS، وذلك اعتبارًا من 20 تشرين الثاني (نوفمبر) 2019، وسيتم إيقافها في 20 شباط (فبراير) 2021. مزيد من المعلومات

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

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

تنبيه: طلبات البحث عن الأماكن وتفاصيل المكان الطلبات لا تعرض نفس الحقول. تعرض طلبات "البحث عن الأماكن" مجموعة فرعية الحقول التي تُرجعها طلبات "تفاصيل المكان". إذا كان الحقل الذي نريدها عن طريق ميزة "البحث عن الأماكن"، فيمكنك استخدام ميزة "البحث عن الأماكن" للحصول على place_id، ثم استخدِم رقم تعريف المكان هذا لإنشاء تفاصيل المكان. .

أساسي

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

يبدأ بحث الأماكن المجاورة بالاتصال PlacesService's nearbySearch()، والتي ستنفّذ إرجاع صفيف من عناصر PlaceResult يُرجى العلم أنّ السمة nearbySearch() تستبدل طريقة search() اعتبارًا من الإصدار 3.9.

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

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

• أيّ مما يلي:
  • bounds، الذي يجب أن يكون كائن google.maps.LatLngBounds الذي يحدّد المستطيل منطقة البحث. أقصى مسافة قُطرية مسموح بها للحدود تبلغ مساحتها حوالي 100000 متر.
  • 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 هي خدمة ويب تعرض معلومات حول مجموعة من الأماكن استنادًا إلى سلسلة — على سبيل المثال "البيتزا في دبي" أو "متاجر أحذية بالقرب من أوتاوا". تستجيب الخدمة بـ قائمة بالأماكن التي تطابق السلسلة النصية وأي تحيز موقع له النهج التحليلي. ستتضمّن استجابة البحث قائمة بالأماكن. يمكنك إرسال طلب تفاصيل المكان للحصول على مزيد من المعلومات حول أي من الأماكن الموجودة في الاستجابة.

تبدأ عمليات البحث النصية من خلال استدعاء طريقة 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 الذي يحدّد المستطيل منطقة البحث. أقصى مسافة قُطرية مسموح بها للحدود تبلغ مساحتها حوالي 100000 متر.
    • 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 8th Avenue, New York, NY" تتكون من المكونات التالية: "111" (رقم الشارع)، "الجادة 8" (المسار)، "نيويورك" (المدينة) و"NY" (الولاية الأمريكية).

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

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

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

  • global_code هو رمز منطقة مكوّن من 4 أحرف ورمز محلي من 6 أحرف أو أكثر. (849VCWC8+R9).
  • compound_code هو رمز محلي مكوَّن من 6 أحرف أو أكثر مع موقع جغرافي فاضح. (CWC8+R9، ماونتن فيو، كاليفورنيا، الولايات المتحدة الأمريكية). ويُرجى عدم تحليل هذا المحتوى آليًا.
  عادةً ما يتم عرض كل من الرمز العام والرمز المركب. ومع ذلك، إذا كانت النتيجة في موقع ناءٍ (على سبيل المثال، محيط أو صحراء) لا يمكن عرض سوى الرمز العالمي.
• html_attributions: مصفوفة من الإحالات التي يجب عليك عند عرض نتائج البحث. يحتوي كل إدخال في الصفيف على نص HTML لإحالة واحدة. ملاحظة: هذه تجميع كل الإشارات المتعلقة باستجابة البحث بالكامل. الكل لذلك يحتوي PlaceResult عنصر في الاستجابة على قائمتي تحديد مصدر متطابقة
• تعرض icon عنوان URL لرمز PNG ملوّن 71 بكسل × 71 بكسل.
• تعرض الدالة icon_mask_base_uri عنوان URL الأساسي لعنصر غير ملوّن بدون امتداد .svg أو .png.
• تعرض icon_background_color رمز اللون السداسي العشري التلقائي لـ فئة المكان.
• name: اسم المكان
• قد يحتوي opening_hours على المعلومات التالية:
  • open_now هي قيمة منطقية تشير إلى ما إذا كان المكان مفتوحة في الوقت الحالي (متوقّفة نهائيًا في مكتبة الأماكن، أو واجهة برمجة تطبيقات JavaScript للخرائط، استخدم utc_offset_minutes بدلاً من ذلك).
• place_id هو معرِّف نصي يعرّف بشكل فريد الْمَكَانْ. لاسترداد معلومات عن المكان، يُرجى إدخال هذا المعرّف في تفاصيل المكان طلبك. مزيد من المعلومات حول كيفية الإشارة إلى مكان مع معرّف مكان.
• يحتوي مقياس "rating" على تقييم المكان من 0.0 إلى 5.0، استنادًا إلى حول مراجعات المستخدمين المجمَّعة
• types صفيف من أنواعه المتعلقة بهذا المكان (مثل ["political", "locality"] أو ["restaurant", "lodging"]). قد تحتوي هذه الصفيفة على قيم متعددة أو قد فارغ. قد يتم طرح قيم جديدة بدون إشعار مسبق. اطّلِع على قائمة الأنواع المتوافقة.
• vicinity: عنوان مبسَّط للمكان، يتضمّن اسم الشارع ورقم الشارع والمنطقة المحلية، ولكن لا الإقليم/الولاية، أو الرمز البريدي، أو البلد. على سبيل المثال، شركة 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

ملاحظة: اطّلِع على الدليل حول استخدام TypeScript و"خرائط Google".

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

ملاحظة: يتم تجميع رمز JavaScript من مقتطف TypeScript.

الاطّلاع على مثال

تجربة "عيّنة"

JSFiddle.net Google Cloud Shell

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

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

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

يتم طلب تفاصيل المكان من خلال الاتصال بمقدّم الخدمة طريقة 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);
  }
}

الاطّلاع على مثال

يمكنك طلب place_id لمكان معيّن، مجانًا لإجراء ذلك، يمكنك الاتصال بـ getDetails() وتحديد place_id فقط.

.

الحقول (تفاصيل المكان)

تأخذ المَعلمة fields مصفوفة من السلاسل (أسماء الحقول).

حقلا "الأماكن" opening_hours.open_now وutc_offset في حزم الأماكن لأجهزة iOS، وذلك اعتبارًا من 20 تشرين الثاني (نوفمبر) 2019، وسيتم إيقافها في 20 شباط (فبراير) 2021. مزيد من المعلومات

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

تتطابق الحقول مع Place Details (تفاصيل المكان) النتائج، وتنقسم إلى ثلاث فئات فوترة: أساسية، وجهة اتصال، الأجواء تتم فوترة الحقول الأساسية بالسعر الأساسي، ولن يتم تحصيل أي رسوم إضافية الرسوم. يتم تحصيل الرسوم من حقلَي Contact وAtmosphere بسعر أعلى. الاطّلاع على ورقة الأسعار لمزيد من المعلومات. تكون عمليات تحديد المصدر (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 (متوقّفة نهائيًا في مكتبة الأماكن، وواجهة برمجة تطبيقات JavaScript للخرائط)، utc_offset_minutes، vicinity

التواصل

تشمل فئة جهة الاتصال الحقول التالية:
formatted_phone_number، international_phone_number، opening_hours، website

الأجواء

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

تنبيه: طلبات البحث عن الأماكن وتفاصيل المكان الطلبات لا تعرض نفس الحقول. تعرض طلبات "البحث عن الأماكن" مجموعة فرعية الحقول التي تُرجعها طلبات "تفاصيل المكان". إذا كان الحقل الذي نريدها عن طريق ميزة "البحث عن الأماكن"، فيمكنك استخدام ميزة "البحث عن الأماكن" للحصول على place_id، ثم استخدِم رقم تعريف المكان هذا لإنشاء تفاصيل المكان. .

مزيد من المعلومات حول حقول الأماكن. لمزيد من المعلومات، للحصول على معلومات عن كيفية إصدار فواتير طلبات بيانات الأماكن، راجِع الاستخدام والفوترة:

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

الردود على تفاصيل المكان

رموز الحالة

يحتوي كائن الاستجابة PlacesServiceStatus على حالة وقد تحتوي على معلومات تصحيح الأخطاء لمساعدتك في تعقب سبب فشل طلب تفاصيل المكان. قيم الحالة المحتملة هي:

• INVALID_REQUEST: هذا الطلب غير صالح.
• OK: يحتوي الردّ على نتيجة صالحة.
• OVER_QUERY_LIMIT: تجاوزت صفحة الويب طلبها الحصة.
• NOT_FOUND لم يكن الموقع الجغرافي المُشار إليه في قاعدة بيانات الأماكن.
• REQUEST_DENIED: لا يُسمح لصفحة الويب باستخدام PlacesService.
• UNKNOWN_ERROR: تعذّر تنفيذ طلب PlacesService تمت معالجتها بسبب خطأ في الخادم. قد ينجح الطلب في حال إعادة المحاولة.
• ZERO_RESULTS: لم يتم العثور على نتائج لهذا الطلب.

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

تؤدي مكالمة getDetails() الناجحة إلى إرجاع PlaceResult بالسمات التالية:

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

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

  • types[] هو مصفوفة تشير إلى نوع الخاص بك. اطّلِع على قائمة الأنواع المتوافقة.
  • long_name هو الوصف النصي الكامل أو اسم العنوان كما يعرضه الترميز الجغرافي.
  • "short_name" هو اسم نصي مختصر للعنوان إذا كان متاحًا. على سبيل المثال، مكون العنوان للولاية في ألاسكا قد يكون بها long_name لـ "ألاسكا" و short_name من "AK" باستخدام الاختصار البريدي المكون من حرفين.

  يُرجى الاطّلاع على الحقائق التالية حول address_components[]. الصفيفة:

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

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

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

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

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

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

  • global_code هو رمز منطقة مكوّن من 4 أحرف ورمز محلي من 6 أحرف أو أكثر. (849VCWC8+R9).
  • compound_code هو رمز محلي مكوَّن من 6 أحرف أو أكثر مع موقع جغرافي فاضح. (CWC8+R9، ماونتن فيو، كاليفورنيا، الولايات المتحدة الأمريكية). ويُرجى عدم تحليل هذا المحتوى آليًا.
  عادةً ما يتم عرض كل من الرمز العام والرمز المركب. ومع ذلك، إذا كانت النتيجة في موقع ناءٍ (على سبيل المثال، محيط أو صحراء) لا يمكن عرض سوى الرمز العالمي.
• html_attributions: نص الإحالة الذي سيتم عرضه نتيجة البحث لهذا المكان.
• icon: عنوان URL يؤدي إلى مورد صور يمكن استخدامه تمثّل نوع هذا المكان.
• يحتوي النطاق international_phone_number على رقم الهاتف الخاص بالمكان رقم بتنسيق دولي. يشمل التنسيق الدولي البلد ويبدأ بعلامة الجمع (+). على سبيل المثال، international_phone_number في مدينة سيدني بأستراليا هو [phone].
• name: اسم المكان
• utc_offset تمت إزالتها في مكتبة الأماكن، واجهة برمجة تطبيقات JavaScript للخرائط، استخدِم utc_offset_minutes بدلاً من ذلك.
• يحتوي utc_offset_minutes على عدد الدقائق الذي تختلف المنطقة الزمنية الحالية للمكان عن التوقيت العالمي المنسَّق (UTC). على سبيل المثال، بالنسبة للأماكن في سيدني، أستراليا خلال نظام التوقيت الصيفي، سيكون هذا الوقت 660 (أكثر من 11 ساعة) من التوقيت العالمي المنسَّق (UTC)، وللأماكن في كاليفورنيا خارج التوقيت الصيفي سيكون -480 (-8 ساعات من التوقيت العالمي المتفق عليه).
• يحتوي opening_hours على المعلومات التالية:
  • open_now (متوقّف نهائيًا في مكتبة الأماكن، وواجهة برمجة تطبيقات JavaScript للخرائط؛ استخدام opening_hours.isOpen() بدلاً من ذلك. يمكنك مشاهدة هذا الفيديو لمعرفة كيفية الاستخدام. isOpen مع تفاصيل المكان). قيمة منطقية تشير إلى ما إذا كان المكان مفتوحًا في الوقت.
  • periods[] هي مصفوفة من الفترات الافتتاحية تغطي سبعة أيام، بدءًا من الأحد، بترتيب زمني. كل فترة تحتوي على:
    • يحتوي open على عنصرَي اليوم والوقت. يصف متى يفتح المكان:
      • day رقم من 0 إلى 6 (وفقًا للأيام) من أيام الأسبوع، بدءًا من يوم الأحد. على سبيل المثال، تعني 2 الثلاثاء
      • قد يحتوي time على وقت من اليوم بتنسيق 24 ساعة (تظهر القيم في النطاق 0000-2359). تشير رسالة الأشكال البيانية سيتم الإبلاغ عن time حسب المنطقة الزمنية للمكان.
    • قد يحتوي close على زوج من عناصر اليوم والوقت. تصف متى يُغلق المكان. ملاحظة: إذا كان المكان مفتوحًا دائمًا، فإن قسم close سيتم يكون مفقودًا من الإجابة. يمكن أن تعتمد التطبيقات على يتم تمثيلها كنقطة open وتحتوي على day بقيمة 0 وtime بقيمة 0000، ولا close.
  • weekday_text عبارة عن صفيف من سبع سلاسل تمثل ساعات العمل المنسقة لكل يوم من أيام الأسبوع. إذا تم تحديد مَعلمة language في تفاصيل المكان. ستُجري خدمة الأماكن تنسيقًا لساعات العمل وأقلمَتها. بشكل مناسب لتلك اللغة. يشير ترتيب العناصر في هذه تعتمد المصفوفة على مَعلمة language. بعض اللغات يبدأ الأسبوع يوم الاثنين بينما يبدأ البعض الآخر يوم الأحد.
• permanently_closed (متوقّفة نهائيًا) علامة منطقية تشير إلى ما إذا كان المكان قد توقّف عن العمل أم لا نهائيًا أو مؤقتًا (القيمة true). عدم الاستخدام permanently_closed بدلاً من ذلك، استخدِم business_status. للحصول على الحالة التشغيلية للشركات.
• photos[]: مصفوفة من عناصر PlacePhoto يمكن استخدام PlacePhoto للحصول على صورة باستخدام getUrl()، أو يمكنك فحص الكائن بحثًا عن القيم التالية:
  • height: الحد الأقصى لارتفاع الصورة بالبكسل.
  • width: الحد الأقصى لعرض الصورة بالبكسل.
  • html_attributions: نص الإحالة المطلوب عرضه مع صورة هذا المكان.
• place_id: معرّف نصي يعرّف بشكلٍ فريد المكان ويمكن استخدامها لاسترداد المعلومات حول المكان من خلال تفاصيل المكان . مزيد من المعلومات حول كيفية الإشارة إلى مكان مع معرّف مكان.
• rating: تقييم المكان من 0.0 إلى 5.0 استنادًا إلى مراجعات المستخدمين المجمَّعة
• reviews عبارة عن مصفوفة تضمّ ما يصل إلى خمس مراجعات. كل مراجعة يتكون من عدة مكونات:
  • يحتوي aspects[] على صفيف من PlaceAspectRating، يوفّر كل منها تصنيف سمة واحدة للمؤسسة. الكائن الأول في الصفيفة يُعد الجانب الأساسي. على كل تعريف "PlaceAspectRating" على أنّه:
    • type اسم الجانب الذي يتم تقييمه. تتوفّر الأنواع التالية: appeal atmosphere، decor، facilities، food، overall، quality وservice
    • rating تقييم المستخدم لهذا المحتوى بالتحديد الجانب، من 0 إلى 3.
  • author_name اسم المستخدم الذي أرسل المراجعة. وتُنسَب المراجعات المجهولة الهوية إلى "مستخدم Google". إذا مَعلمة اللغة، ثم تظهر العبارة "مستخدم Google" سوف لإرجاع سلسلة مترجمة.
  • author_url عنوان URL إلى الملف الشخصي للمستخدمين في +Google، إذا المتوفرة.
  • language رمز لغة مجموعة مهندسي شبكة الإنترنت (IETF) يشير إلى اللغة المستخدم في مراجعة المستخدم. يحتوي هذا الحقل على علامة اللغة الرئيسية فقط، وليس العلامة الثانوية التي تشير إلى البلد أو المنطقة. بالنسبة مثلاً، يتم وضع علامة على جميع المراجعات باللغة الإنجليزية على أنّها "en" وليس "en-AU" أو "en-UK" وهكذا
  • rating التقييم العام للمستخدم لهذا المكان هذا النمط عددًا صحيحًا يتراوح من 1 إلى 5.
  • text مراجعة المستخدم عند مراجعة الموقع الجغرافي في أماكن Google، تُعتبر المراجعات النصية اختيارية؛ لذلك، قد يكون هذا الحقل فارغًا.
• types صفيف من أنواعه المتعلقة بهذا المكان (مثل ["political", "locality"] أو ["restaurant", "lodging"]). قد تحتوي هذه الصفيفة على قيم متعددة أو قد فارغ. قد يتم طرح قيم جديدة بدون إشعار مسبق. اطّلِع على قائمة الأنواع المتوافقة.
• url: عنوان URL لصفحة Google الرسمية لهذا الْمَكَانْ. هذه هي الصفحة المملوكة لـ Google والتي تحتوي على أفضل المعلومات المتوفرة حول المكان. يجب أن تشتمل التطبيقات على رابط إلى هذه الصفحة على أي شاشة تعرض نتائج تفصيلية حول المكان إلى المستخدم.
• vicinity: عنوان مبسَّط للمكان، يتضمّن اسم الشارع ورقم الشارع والمنطقة المحلية، ولكن لا الإقليم/الولاية، أو الرمز البريدي، أو البلد. على سبيل المثال، شركة Google في مدينة سيدني، قيمة مكتب أستراليا vicinity هي 5/48 Pirrama Road, Pyrmont. يتم إرجاع السمة vicinity فقط. لإجراء بحث عن الأجهزة المجاورة.
• يسرد website الموقع الإلكتروني الموثوق لهذا المكان، مثل كشركة الرئيسية.

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

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

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

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

الشكل 1: معلومات عن تفاصيل المكان تتضمّن خمسة أشكال مختلفة من الأحجام

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

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

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

ملاحظة: تتوفّر أرقام تعريف الأماكن أيضًا من خلال Places API. يشير رقم تعريف المكان الواحد إلى مكان واحد فقط، ولكن يمكن أن يتضمّن المكان عدة أماكن. بأرقام تعريف الأماكن. لمزيد من المعلومات، يُرجى الاطّلاع على نظرة عامة على رقم تعريف المكان

يتم إعفاء أرقام تعريف الأماكن من قيود التخزين المؤقت المذكورة. في الفقرة 3.2.3(ب) من بنود خدمة Google Maps Platform وبالتالي، يمكنك تخزين قيم رقم تعريف الأماكن لاستخدامها في وقت لاحق. بالنسبة أفضل الممارسات عند تخزين معرفات الأماكن، فراجع نظرة عامة على رقم تعريف المكان.

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