البحث عن الأماكن وتفاصيلها (الإصدار القديم)

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

نظرة عامة

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

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

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

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

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

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

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

الحِصص

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

السياسات

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

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

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

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

طلبات Find Place (Legacy)

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

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

تأخذ واجهة برمجة التطبيقات Find Place من Query إدخالاً نصيًا وتعرض مكانًا. يمكن أن يكون الإدخال أي نوع من بيانات المكان، مثل اسم المؤسسة أو عنوانها. لإجراء طلب "العثور على مكان من طلب البحث"، استخدِم طريقة findPlaceFromQuery() في PlacesService التي تتطلّب المَعلمات التالية:

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

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

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

الأساسية

تتضمّن الفئة "الأساسية" الحقول التالية:
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 لجعل خدمة "العثور على مكان" تفضّل النتائج في منطقة معيّنة. يمكنك ضبط locationBias بالطرق التالية:

توجيه النتائج إلى منطقة معيّنة:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    • ‫global_code هو رمز منطقة مكوّن من 4 أحرف ورمز محلي مكوّن من 6 أحرف أو أكثر (849VCWC8+R9).
    • ‫compound_code هو رمز محلي يتألف من 6 أحرف أو أكثر مع موقع جغرافي صريح (CWC8+R9, Mountain View, CA, USA). لا تحلّل هذا المحتوى آليًا.
    عادةً ما يتم عرض كل من الرمز العالمي والرمز المركّب. ومع ذلك، إذا كانت النتيجة في موقع جغرافي بعيد (مثل محيط أو صحراء)، قد يتم عرض الرمز العالمي فقط.
  • ‫html_attributions: مصفوفة من المصادر التي يجب عرضها عند عرض نتائج البحث يحتوي كل إدخال في المصفوفة على نص HTML لجهة واحدة. ملاحظة: هذا تجميع لجميع مصادر ردّ البحث بالكامل. وبالتالي، تحتوي جميع عناصر PlaceResult في الاستجابة على قوائم تحديد مصدر متطابقة.
  • تعرض السمة icon عنوان URL لرمز PNG ملوّن بحجم 71 × 71 بكسل.
  • تعرض السمة icon_mask_base_uri الجزء الأساسي من عنوان URL لرمز غير ملوّن، باستثناء الامتداد ‎ .svg أو ‎ .png.
  • تعرض السمة icon_background_color رمز اللون الست عشري التلقائي لفئة المكان.
  • 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: عنوان مبسّط للمكان، بما في ذلك اسم الشارع ورقم الشارع والمنطقة، ولكن ليس المقاطعة/الولاية أو الرمز البريدي أو البلد. على سبيل المثال، قيمة vicinity لمكتب Google في سيدني، أستراليا هي 5/48 Pirrama Road, Pyrmont.

الوصول إلى نتائج بحث إضافية

بشكل تلقائي، يعرض كل البحث عن الأماكن ما يصل إلى 20 نتيجة لكل طلب بحث. ومع ذلك، يمكن أن يعرض كل بحث ما يصل إلى 60 نتيجة، مقسّمة على ثلاث صفحات. تتوفّر صفحات إضافية باستخدام الكائن PlaceSearchPagination. للوصول إلى صفحات إضافية، عليك تسجيل الكائن PlaceSearchPagination باستخدام دالّة رد الاتصال. يتم تعريف العنصر PlaceSearchPagination على النحو التالي:

  • ‫hasNextPage هي سمة منطقية تشير إلى ما إذا كانت هناك نتائج إضافية متاحة. true عندما تكون هناك صفحة نتائج إضافية.
  • nextPage() دالة تعرض المجموعة التالية من النتائج بعد تنفيذ عملية بحث، عليك الانتظار لمدة ثانيتين قبل أن تصبح الصفحة التالية من النتائج متاحة.

للاطّلاع على المجموعة التالية من النتائج، يمكنك استدعاء nextPage. ويجب عرض كل صفحة من النتائج قبل عرض الصفحة التالية من النتائج. يُرجى العِلم أنّ كل عملية بحث تُحتسب كطلب واحد ضمن حدود الاستخدام.

يوضّح المثال أدناه كيفية تغيير دالّة ردّ الاتصال لالتقاط عنصر PlaceSearchPagination، لكي تتمكّن من إصدار طلبات بحث متعدّدة.

TypeScript

// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">

function initMap(): void {
  // Create the map.
  const pyrmont = { lat: -33.866, lng: 151.196 };
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      center: pyrmont,
      zoom: 17,
      mapId: "8d193001f940fde3",
    } as google.maps.MapOptions
  );

  // Create the places service.
  const service = new google.maps.places.PlacesService(map);
  let getNextPage: () => void | false;
  const moreButton = document.getElementById("more") as HTMLButtonElement;

  moreButton.onclick = function () {
    moreButton.disabled = true;

    if (getNextPage) {
      getNextPage();
    }
  };

  // Perform a nearby search.
  service.nearbySearch(
    { location: pyrmont, radius: 500, type: "store" },
    (
      results: google.maps.places.PlaceResult[] | null,
      status: google.maps.places.PlacesServiceStatus,
      pagination: google.maps.places.PlaceSearchPagination | null
    ) => {
      if (status !== "OK" || !results) return;

      addPlaces(results, map);
      moreButton.disabled = !pagination || !pagination.hasNextPage;

      if (pagination && pagination.hasNextPage) {
        getNextPage = () => {
          // Note: nextPage will call the same handler function as the initial call
          pagination.nextPage();
        };
      }
    }
  );
}

function addPlaces(
  places: google.maps.places.PlaceResult[],
  map: google.maps.Map
) {
  const placesList = document.getElementById("places") as HTMLElement;

  for (const place of places) {
    if (place.geometry && place.geometry.location) {
      const image = {
        url: place.icon!,
        size: new google.maps.Size(71, 71),
        origin: new google.maps.Point(0, 0),
        anchor: new google.maps.Point(17, 34),
        scaledSize: new google.maps.Size(25, 25),
      };

      new google.maps.Marker({
        map,
        icon: image,
        title: place.name!,
        position: place.geometry.location,
      });

      const li = document.createElement("li");

      li.textContent = place.name!;
      placesList.appendChild(li);

      li.addEventListener("click", () => {
        map.setCenter(place.geometry!.location!);
      });
    }
  }
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;

JavaScript

// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">
function initMap() {
  // Create the map.
  const pyrmont = { lat: -33.866, lng: 151.196 };
  const map = new google.maps.Map(document.getElementById("map"), {
    center: pyrmont,
    zoom: 17,
    mapId: "8d193001f940fde3",
  });
  // Create the places service.
  const service = new google.maps.places.PlacesService(map);
  let getNextPage;
  const moreButton = document.getElementById("more");

  moreButton.onclick = function () {
    moreButton.disabled = true;
    if (getNextPage) {
      getNextPage();
    }
  };

  // Perform a nearby search.
  service.nearbySearch(
    { location: pyrmont, radius: 500, type: "store" },
    (results, status, pagination) => {
      if (status !== "OK" || !results) return;

      addPlaces(results, map);
      moreButton.disabled = !pagination || !pagination.hasNextPage;
      if (pagination && pagination.hasNextPage) {
        getNextPage = () => {
          // Note: nextPage will call the same handler function as the initial call
          pagination.nextPage();
        };
      }
    },
  );
}

function addPlaces(places, map) {
  const placesList = document.getElementById("places");

  for (const place of places) {
    if (place.geometry && place.geometry.location) {
      const image = {
        url: place.icon,
        size: new google.maps.Size(71, 71),
        origin: new google.maps.Point(0, 0),
        anchor: new google.maps.Point(17, 34),
        scaledSize: new google.maps.Size(25, 25),
      };

      new google.maps.Marker({
        map,
        icon: image,
        title: place.name,
        position: place.geometry.location,
      });

      const li = document.createElement("li");

      li.textContent = place.name;
      placesList.appendChild(li);
      li.addEventListener("click", () => {
        map.setCenter(place.geometry.location);
      });
    }
  }
}

window.initMap = initMap;
الاطّلاع على مثال

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

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

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

يتم طلب تفاصيل المكان من خلال استدعاء طريقة getDetails() الخاصة بالخدمة.

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

تتلقّى هذه الطريقة طلبًا يحتوي على placeId لمكان معيّن وحقول تشير إلى أنواع بيانات الأماكن المطلوب عرضها. مزيد من المعلومات عن كيفية الإشارة إلى مكان باستخدام رقم تعريف المكان

وتتطلّب أيضًا طريقة رد اتصال، والتي يجب أن تعالج رمز الحالة الذي تم تمريره في استجابة google.maps.places.PlacesServiceStatus، بالإضافة إلى عنصر google.maps.places.PlaceResult.

var request = {
  placeId: 'ChIJN1t_tDeuEmsRUsoyG83frY4',
  fields: ['name', 'rating', 'formatted_phone_number', 'geometry']
};

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

function callback(place, status) {
  if (status == google.maps.places.PlacesServiceStatus.OK) {
    createMarker(place);
  }
}

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

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

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

استخدِم المَعلمة fields لتحديد مصفوفة من أنواع بيانات الأماكن المطلوب عرضها. على سبيل المثال: fields: ['address_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

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

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

رموز حالة تفاصيل المكان

يحتوي كائن الاستجابة 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 كبديل لعناوين الشوارع في الأماكن التي لا تتوفّر فيها (حيث لا يتم ترقيم المباني أو تسمية الشوارع).

    يتم تنسيق رمز 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 تم إيقاف هذه السمة نهائيًا في Places Library ضمن Maps JavaScript API، لذا يُرجى استخدام utc_offset_minutes بدلاً منها.
  • يحتوي utc_offset_minutes على عدد الدقائق التي تختلف بها المنطقة الزمنية الحالية لهذا المكان عن التوقيت العالمي المنسق (UTC). على سبيل المثال، بالنسبة إلى الأماكن في سيدني، أستراليا، خلال نظام التوقيت الصيفي، ستكون هذه القيمة 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 في طلب "تفاصيل المكان"، ستعمل "خدمة الأماكن" على تنسيق ساعات العمل وترجمتها بشكل مناسب لتلك اللغة. يعتمد ترتيب العناصر في هذه المصفوفة على المَعلمة 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 مراجعة المستخدم. عند مراجعة موقع جغرافي باستخدام &quot;أماكن Google&quot;، تُعتبر المراجعات النصية اختيارية، لذلك قد يكون هذا الحقل فارغًا.
  • ‫types مصفوفة من الأنواع لهذا المكان (مثل ["political", "locality"] أو ["restaurant", "lodging"]). قد تحتوي هذه المصفوفة على قيم متعددة أو قد تكون فارغة. قد يتم تقديم قيم جديدة بدون إشعار مسبق. اطّلِع على قائمة الأنواع المتوافقة.
  • ‫url: عنوان URL لصفحة Google الرسمية لهذا المكان هذه هي الصفحة المملوكة لشركة Google والتي تحتوي على أفضل المعلومات المتاحة عن المكان. يجب أن تتضمّن التطبيقات رابطًا يؤدي إلى هذه الصفحة أو أن تدمجها في أي شاشة تعرض نتائج تفصيلية عن المكان للمستخدم.
  • vicinity: عنوان مبسّط للمكان، بما في ذلك اسم الشارع ورقم الشارع والمنطقة، ولكن ليس المقاطعة/الولاية أو الرمز البريدي أو البلد. على سبيل المثال، قيمة vicinity لمكتب Google في سيدني، أستراليا هي 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، يجب تضمين معلومات تحديد المصدر الإضافية في تطبيقك أينما تعرض الصورة.