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

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

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

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

نظرة عامة

تتيح الدوال في "مكتبة الأماكن" ضمن 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:

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

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

الحِصص

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

السياسات

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

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

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

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

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

طلبات Find Place (Legacy)

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

Find Place from Query
Find Place from Phone Number

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

تأخذ واجهة برمجة التطبيقات 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);
    }
  });
}

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

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

تأخذ واجهة برمجة التطبيقات 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 لجعل خدمة "العثور على مكان" تفضّل النتائج في منطقة معيّنة. يمكنك ضبط 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 Codes كبديل لعناوين الشوارع في الأماكن التي لا تتوفّر فيها (حيث لا يتم ترقيم المباني أو تسمية الشوارع).
يتم تنسيق رمز Plus Code كرمز عالمي ورمز مركّب:
- ‫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;index.ts

JavaScript

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

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

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

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

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

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

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

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

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

window.initMap = initMap;index.js

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

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

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

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

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

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

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

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

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

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

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

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

يمكنك طلب 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

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

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

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

نظرة عامة

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

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

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

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

الحِصص

السياسات

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

طلبات Find Place (Legacy)

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

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

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

ضبط انحياز الموقع الجغرافي (طرق Find Place)

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

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

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

رموز الحالة

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

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

TypeScript

JavaScript

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

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

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

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

رموز الحالة

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

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

صور المكان

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