حزمة أدوات Places UI Kit: هي مكتبة جاهزة للاستخدام تتيح للمطوّرين إمكانية التخصيص والتحكّم. ننصحك بتجربتها ومشاركة ملاحظاتك حول تجربتك مع حزمة واجهة المستخدم.

تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

المطوّرون في المنطقة الاقتصادية الأوروبية

نظرة عامة

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

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

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

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

تحميل المكتبة

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

<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) غير مرتبطة بمفتاح واجهة برمجة التطبيقات. لتقييد استخدام مفتاح واجهة برمجة التطبيقات مع Places Library في Maps JavaScript API، اتّبِع الخطوات التالية:

انتقِل إلى وحدة تحكّم Google Cloud.
انقر على القائمة المنسدلة الخاصة بالمشروع واختَر المشروع الذي يحتوي على مفتاح واجهة برمجة التطبيقات الذي تريد تأمينه.
انقر على زر القائمة واختَر Google Maps Platform > بيانات الاعتماد.
في صفحة بيانات الاعتماد، انقر على اسم مفتاح واجهة برمجة التطبيقات الذي تريد تأمينه.
في صفحة تقييد مفتاح واجهة برمجة التطبيقات وإعادة تسميته، اضبط القيود على النحو التالي:
- قيود واجهة برمجة التطبيقات
انقر على حفظ.

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

الحصص

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

السياسات

يجب أن يكون استخدام Places Library وMaps JavaScript API متوافقًا مع السياسات الموضّحة لواجهة Places API.

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

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

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

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

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

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

Find Place from Query
العثور على مكان من رقم الهاتف

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

تتلقّى طريقة Find Place from Query إدخالاً نصيًا وتعرض مكانًا. يمكن أن يكون الإدخال أي نوع من بيانات "الأماكن"، مثل اسم نشاط تجاري أو عنوان. لإجراء طلب Find Place from Query، استدعِ طريقة PlacesServicefindPlaceFromQuery() التي تتضمّن المَعلمات التالية:

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

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

يعرض المثال التالي طلبًا إلى findPlaceFromQuery()، يبحث عن "متحف الفن المعاصر في أستراليا"، ويتضمّن الحقلَين name وgeometry.

var map;
var service;
var infowindow;

function initMap() {
  var sydney = new google.maps.LatLng(-33.867, 151.195);

  infowindow = new google.maps.InfoWindow();

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

  var request = {
    query: 'Museum of Contemporary Art Australia',
    fields: ['name', 'geometry'],
  };

  var service = new google.maps.places.PlacesService(map);

  service.findPlaceFromQuery(request, function(results, status) {
    if (status === google.maps.places.PlacesServiceStatus.OK) {
      for (var i = 0; i < results.length; i++) {
        createMarker(results[i]);
      }
      map.setCenter(results[0].geometry.location);
    }
  });
}

عرض مثال

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

تتلقّى خدمة "العثور على مكان من رقم الهاتف" رقم هاتف وتعرض مكانًا. لإجراء طلب Find Place from Phone Number، استدعِ طريقة findPlaceFromPhoneNumber() الخاصة بفئة PlacesService، والتي تتضمّن المَعلمات التالية:

‫phoneNumber (مطلوب) رقم هاتف بتنسيق E.164
fields (مطلوب) حقل واحد أو أكثر من الحقول التي تحدّد أنواع بيانات "الأماكن" المطلوب عرضها.
locationBias (اختياري) إحداثيات تحدّد المنطقة المطلوب البحث فيها. يمكن أن يكون أحد ما يلي:
- مجموعة من إحداثيات خطوط الطول والعرض المحدّدة على النحو التالي: LatLngLiteral أو كائن LatLng
- حدود مستطيلة (أربع نقاط خطوط طول/عَرض أو كائن LatLngBounds)
- نصف القطر (بالمتر) في منتصف خط العرض/خط الطول

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

الحقول (طُرق Find Place)

استخدِم المَعلمة 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
(تم إيقافه نهائيًا في Places Library ضِمن Maps JavaScript API. استخدِم طلب تفاصيل المكان للحصول على opening_hours النتائج).

الغلاف الجوي

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

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

ضبط الموقع الجغرافي المفضّل (طُرق Find Place)

استخدِم المَعلمة locationBias لجعل خدمة Find Place تفضّل النتائج في منطقة معيّنة. يمكنك ضبط 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}}

طلبات البحث في الجوار

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

a LatLngBounds.
منطقة دائرية يتم تحديدها من خلال الجمع بين السمة location التي تحدّد مركز الدائرة ككائن LatLng ونصف القطر الذي يتم قياسه بالأمتار

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

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

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

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

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

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

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

‫query (مطلوب) سلسلة النص المطلوب البحث فيها، مثلاً: "مطعم" أو "123 شارع رئيسي". يجب أن يكون اسم مكان أو عنوانًا أو فئة من المؤسسات. يمكن أن تؤدي أي أنواع أخرى من الإدخالات إلى حدوث أخطاء، ولا نضمن عرض نتائج صالحة. ستعرض خدمة "الأماكن" نتائج مطابقة محتملة استنادًا إلى هذه السلسلة، كما سترتّب النتائج حسب مدى صلتها بموضوع البحث. تصبح هذه المَعلمة اختيارية إذا تم استخدام المَعلمة type أيضًا في طلب البحث.
اختياريًا:
- openNow: قيمة منطقية تشير إلى أنّ خدمة "أماكن Google" يجب أن تعرض فقط الأماكن المفتوحة في وقت إرسال طلب البحث. لن يتم عرض الأماكن التي لم تحدّد ساعات عملها في قاعدة بيانات Google Places إذا تضمّنت هذه المَعلمة في طلب البحث. لن يكون لضبط openNow على false أي تأثير.
- ‫minPriceLevel وmaxPriceLevel — لحصر النتائج بالأماكن التي تندرج ضمن فئة السعر المحدّدة فقط تتراوح القيم الصالحة من 0 (الأكثر توفيرًا) إلى 4 (الأكثر تكلفةً).
- أيّ مما يلي:
  - bounds، الذي يجب أن يكون كائن google.maps.LatLngBounds يحدّد مساحة البحث المستطيلة. الحدّ الأقصى للمسافة القطرية المسموح بها لمنطقة الحدود يبلغ 100,000 متر تقريبًا.
  - 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: لا يُسمح لصفحة الويب باستخدام 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" (رقم الشارع) و"8th Avenue" (الطريق) و"New York" (المدينة) و "NY" (ولاية الولايات المتحدة).

لا تحلّل العنوان المنسّق آليًا. بدلاً من ذلك، عليك استخدام مكوّنات العنوان الفردية التي تتضمّنها استجابة واجهة برمجة التطبيقات بالإضافة إلى حقل العنوان المنسّق.
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، ماونتن فيو، كاليفورنيا، الولايات المتحدة الأمريكية). لا تحلّل هذا المحتوى آليًا.
يتم عادةً عرض كل من الرمز العالمي والرمز المركّب. ومع ذلك، إذا كانت النتيجة في موقع بعيد (مثل محيط أو صحراء)، قد يتم عرض الرمز العالمي فقط.
‫html_attributions: مصفوفة من بيانات المصدر التي يجب عرضها عند عرض نتائج البحث. يحتوي كل إدخال في المصفوفة على نص HTML خاص بمصدر واحد. ملاحظة: هذا هو تجميع لكل مصادر البيانات الخاصة برد البحث بأكمله. لذلك، تحتوي جميع عناصر PlaceResult في الرد على قوائم تحديد المصدر المتطابقة.
تعرض icon عنوان URL لرمز PNG ملوّن بحجم 71 × 71 بكسل.
تعرض icon_mask_base_uri عنوان URL الأساسي لرمز غير ملوّن، بدون اللاحقة .svg أو .png.
تعرض icon_background_color رمز اللون السداسي العشري التلقائي لفئة المكان.
name: اسم المكان
قد يحتوي opening_hours على المعلومات التالية:
- ‫open_now هي قيمة منطقية تشير إلى ما إذا كان المكان مفتوحًا في الوقت الحالي (تم إيقافها نهائيًا في Places Library في Maps JavaScript API، يُرجى استخدام 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

عرض مثال

تجربة عيّنة

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 مصفوفة من السلاسل (أسماء الحقول).

استخدِم المَعلمة 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 (متوقّف نهائيًا في Places Library وMaps JavaScript API) وutc_offset_minutes وvicinity

التواصل

تتضمّن فئة "جهة الاتصال" الحقول التالية:
formatted_phone_number وinternational_phone_number opening_hours وwebsite

الغلاف الجوي

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

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

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

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

رموز الحالة

يحتوي عنصر الاستجابة 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" (رقم الشارع) و"8th Avenue" (الطريق) و"New York" (المدينة) و "NY" (ولاية الولايات المتحدة).

لا تحلّل العنوان المنسّق آليًا. بدلاً من ذلك، عليك استخدام مكوّنات العنوان الفردية التي تتضمّنها استجابة واجهة برمجة التطبيقات بالإضافة إلى حقل العنوان المنسّق.
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، ماونتن فيو، كاليفورنيا، الولايات المتحدة الأمريكية). لا تحلّل هذا المحتوى آليًا.
يتم عادةً عرض كل من الرمز العالمي والرمز المركّب. ومع ذلك، إذا كانت النتيجة في موقع بعيد (مثل محيط أو صحراء)، قد يتم عرض الرمز العالمي فقط.
html_attributions: نص الإحالة الذي سيتم عرضه لنتيجة المكان هذه.
‫icon: عنوان URL لمورد صورة يمكن استخدامه لتمثيل نوع هذا المكان.
يمثّل international_phone_number رقم الهاتف الخاص بالمكان بالتنسيق الدولي. يتضمّن التنسيق الدولي رمز البلد، ويسبقه علامة الجمع (+). على سبيل المثال، international_phone_number لمكتب Google في سيدني، أستراليا هو +61 2 9374 4000.
name: اسم المكان
utc_offset تم إيقافها نهائيًا في Places Library ضِمن Maps JavaScript API، يُرجى استخدام utc_offset_minutes بدلاً منها.
يحتوي utc_offset_minutes على عدد الدقائق التي ينحرف بها التوقيت الحالي لهذا المكان عن التوقيت العالمي المتفق عليه. على سبيل المثال، بالنسبة إلى الأماكن في سيدني، أستراليا خلال التوقيت الصيفي، سيكون هذا الرقم 660 (أي 11 ساعة إضافية عن التوقيت العالمي المنسَّق)، وبالنسبة إلى الأماكن في كاليفورنيا خارج التوقيت الصيفي، سيكون هذا الرقم -480 (أي 8 ساعات أقل من التوقيت العالمي المنسَّق).
يتضمّن opening_hours المعلومات التالية:
- open_now (تم إيقافه نهائيًا في Places Library ضِمن Maps JavaScript API، لذا يُرجى استخدام opening_hours.isOpen() بدلاً منه. لمعرفة كيفية استخدام isOpen مع "تفاصيل المكان"، يمكنك الاطّلاع على فيديو "كيفية الحصول على ساعات العمل في Places API" .) ‫`open_now` هي قيمة منطقية تشير إلى ما إذا كان المكان مفتوحًا في الوقت الحالي.
- ‫periods[] هي مصفوفة من فترات العمل التي تغطي سبعة أيام، بدءًا من الأحد، بالترتيب الزمني. تحتوي كل فترة على ما يلي:
  - تحتوي السمة open على زوج من عناصر اليوم والوقت التي توضّح وقت فتح المكان:
    - day رقم من 0 إلى 6، يتوافق مع أيام الأسبوع، بدءًا من الأحد. على سبيل المثال، يعني الرقم 2 يوم الثلاثاء.
    - قد يحتوي time على وقت من اليوم بتنسيق hhmm على مدار 24 ساعة (تتراوح القيم بين 0000 و2359). سيتم عرض time بالمنطقة الزمنية للمكان.
  - قد يحتوي close على زوج من عناصر اليوم والوقت التي تصف وقت إغلاق المكان. ملاحظة: إذا كان المكان مفتوحًا دائمًا، لن يظهر القسم close في الرد. يمكن أن تعتمد التطبيقات على تمثيل فترة open التي تحتوي على day بالقيمة 0 وtime بالقيمة 0000، بدون close، على أنّها فترة مفتوحة دائمًا.
- ‫weekday_text هي مصفوفة من سبع سلاسل تمثّل ساعات العمل المنسّقة لكل يوم من أيام الأسبوع. إذا تم تحديد المَعلمة language في طلب "تفاصيل المكان"، ستنسّق خدمة "أماكن Google" ساعات العمل وتترجمها بشكل مناسب لتلك اللغة. يعتمد ترتيب العناصر في هذه المصفوفة على المَعلمة 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 Places، تُعتبر المراجعات النصية اختيارية، وبالتالي قد يكون هذا الحقل فارغًا.
types مصفوفة تتضمّن أنواع هذا المكان (مثل ["political", "locality"] أو ["restaurant", "lodging"]). قد تحتوي هذه المصفوفة على قيم متعدّدة، أو قد تكون فارغة. قد يتم تقديم قيم جديدة بدون إشعار مسبق. اطّلِع على قائمة الأنواع المتوافقة.
‫url: عنوان URL لصفحة Google الرسمية الخاصة بهذا المكان هذه هي الصفحة المملوكة من Google والتي تحتوي على أفضل المعلومات المتاحة حول المكان. يجب أن تتضمّن التطبيقات رابطًا يؤدي إلى هذه الصفحة أو أن تدمجها في أي شاشة تعرض نتائج تفصيلية حول المكان للمستخدم.
‫vicinity: عنوان مبسط للمكان، يشمل اسم الشارع ورقم الشارع والمنطقة، ولكن لا يشمل المقاطعة/الولاية أو الرمز البريدي أو البلد. على سبيل المثال، يملك مكتب Google في سيدني، أستراليا، قيمة vicinity تبلغ 5/48 Pirrama Road, Pyrmont. لا يتم عرض الخاصية vicinity إلا عند إجراء بحث بالقرب مني.
تعرض السمة website الموقع الإلكتروني الموثوق لهذا المكان، مثل الصفحة الرئيسية لنشاط تجاري.

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

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

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

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

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

var map;

function initialize() {
  // Create a map centered in Pyrmont, Sydney (Australia).
  map = new google.maps.Map(document.getElementById('map'), {
    center: {lat: -33.8666, lng: 151.1958},
    zoom: 15
  });

  // Search for Google's office in Australia.
  var request = {
    location: map.getCenter(),
    radius: '500',
    query: 'Google Sydney'
  };

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

// Checks that the PlacesServiceStatus is OK, and adds a marker
// using the place ID and location from the PlacesService.
function callback(results, status) {
  if (status == google.maps.places.PlacesServiceStatus.OK) {
    var marker = new google.maps.Marker({
      map: map,
      place: {
        placeId: results[0].place_id,
        location: results[0].geometry.location
      }
    });
  }
}

google.maps.event.addDomListener(window, 'load', initialize);

صور المكان

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

سيتم عرض مصفوفة من عناصر PlacePhoto كجزء من الكائن PlaceResult لأي طلب getDetails() أو textSearch() أو nearbySearch() يتم إجراؤه مقابل PlacesService.

ملاحظة: يختلف عدد الصور التي يتم عرضها حسب الطلب.

ستعرض ميزة "البحث القريب" أو ميزة "البحث النصي" عنصر PlacePhoto واحدًا على الأكثر.
سيعرض طلب "التفاصيل" ما يصل إلى عشرة عناصر PlacePhoto.

يمكنك طلب عنوان URL للصورة المرتبطة عن طريق استدعاء طريقة PlacePhoto.getUrl() وتمرير عنصر PhotoOptions صالح. استخدِم عنصر PhotoOptions لتحديد الحدّ الأقصى لارتفاع الصورة وعرضها. إذا حدّدت قيمة لكل من maxHeight وmaxWidth، ستغيّر خدمة الصور حجم الصورة إلى الحجم الأصغر من بين الحجمين، مع الحفاظ على نسبة العرض إلى الارتفاع الأصلية.

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

function createPhotoMarker(place) {
  var photos = place.photos;
  if (!photos) {
    return;
  }

  var marker = new google.maps.Marker({
    map: map,
    position: place.geometry.location,
    title: place.name,
    icon: photos[0].getUrl({maxWidth: 35, maxHeight: 35})
  });
}

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

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

نظرة عامة

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

تحميل المكتبة

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

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

الحصص

السياسات

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

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

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

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

الحقول (طُرق Find Place)

ضبط الموقع الجغرافي المفضّل (طُرق Find Place)

طلبات البحث في الجوار

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

الردود على طلبات البحث

رموز الحالة

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

الاطّلاع على نتائج إضافية

TypeScript

JavaScript

تجربة عيّنة

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

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

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

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

رموز الحالة

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

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

صور المكان

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