نظرة عامة
تعمل الدوال الموجودة في مكتبة الأماكن وواجهة برمجة تطبيقات JavaScript للخرائط على تمكين تطبيقك للبحث عن أماكن (معرَّفة في واجهة برمجة التطبيقات هذه على أنّها منشآت أو مواقع جغرافية أو المواقع أو نقاط الاهتمام البارزة) داخل منطقة محددة، على سبيل المثال، حدود خريطة أو حول نقطة ثابتة.
توفر واجهة Places API ميزة الإكمال التلقائي التي يمكنك استخدامها لمنح تطبيقاتك سلوك البحث المسبق لخرائط Google حقل البحث. عندما يبدأ المستخدم في كتابة عنوان، ستبدأ ميزة الإكمال التلقائي واملأ الباقي. لمزيد من المعلومات، يُرجى الاطّلاع على الإكمال التلقائي ذات الصلة.
الخطوات الأولى
إذا لم تكن معتادًا على استخدام Maps JavaScript API أو JavaScript، ننصحك بمراجعة لغة JavaScript الحصول على مفتاح واجهة برمجة تطبيقات سابقًا لبدء استخدامها
تفعيل واجهات برمجة التطبيقات
قبل استخدام مكتبة الأماكن في واجهة برمجة تطبيقات JavaScript للخرائط، تأكد أولاً تمكين واجهة برمجة تطبيقات الأماكن في وحدة التحكم في Google Cloud، الذي أعددته لواجهة برمجة تطبيقات JavaScript للخرائط.
لعرض قائمة واجهات برمجة التطبيقات المفعّلة:
- الانتقال إلى قسم Google Cloud Console:
- انقر على الزر اختيار مشروع، ثم اختَر المشروع نفسه الذي أعددته. لواجهة برمجة تطبيقات JavaScript للخرائط وانقر على فتح.
- من قائمة واجهات برمجة التطبيقات في لوحة البيانات، ابحث عن Places API:
- إذا ظهرت لك Places API في القائمة، يعني ذلك أنّها ممكَّنة من قبل. إذا كانت واجهة برمجة التطبيقات
غير مُدرجة، فعِّلها:
- في أعلى الصفحة، اختَر تفعيل واجهات برمجة التطبيقات والخدمات (ENABLE APIS AND SERVICES) لعرض علامة التبويب المكتبة بدلاً من ذلك، من القائمة الجانبية اليمنى، انقر على المكتبة.
- ابحث عن Places API، ثم اختَرها من قائمة النتائج.
- انقر على تفعيل. عند انتهاء العملية، تظهر Places API في قائمة واجهات برمجة التطبيقات على لوحة البيانات:
جارٍ تحميل المكتبة
خدمة الأماكن هي مكتبة مستقلة ومنفصلة عن
رمز واجهة برمجة التطبيقات بلغة JavaScript للخرائط. لاستخدام الوظائف الموجودة
من داخل هذه المكتبة، يجب أولاً تحميلها باستخدام libraries
في عنوان URL لتمهيد واجهة برمجة التطبيقات للخرائط:
<script async
src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&libraries=places&callback=initMap">
</script>
يمكنك الاطّلاع على نظرة عامة على المكتبات للاطّلاع على مزيد من المعلومات
إضافة Places API إلى قائمة قيود واجهة برمجة التطبيقات الخاصة بمفتاح واجهة برمجة التطبيقات
يؤدي تطبيق قيود واجهة برمجة التطبيقات على المفاتيح إلى تقييد استخدام مفتاح واجهة برمجة التطبيقات بمفتاح واحد أو أو المزيد من واجهات برمجة التطبيقات أو حزم SDK. سيتم تنفيذ الطلبات المُرسَلة إلى واجهة برمجة التطبيقات أو حزمة تطوير البرامج (SDK) المرتبطة بمفتاح واجهة برمجة التطبيقات. . سيتم تنفيذ الطلبات المُرسَلة إلى واجهة برمجة تطبيقات أو حزمة تطوير برامج (SDK) غير مرتبطة بمفتاح واجهة برمجة التطبيقات. إخفاق. لتقييد استخدام مفتاح واجهة برمجة تطبيقات مع مكتبة الأماكن، وواجهة برمجة تطبيقات JavaScript للخرائط:- انتقِل إلى Google Cloud Console.
- انقر على القائمة المنسدلة للمشروع واختَر المشروع الذي يحتوي على مفتاح واجهة برمجة التطبيقات الذي تريد تأمينه.
- انقر على زر القائمة
. وحدد منصة خرائط Google > بيانات الاعتماد:
- في صفحة بيانات الاعتماد، انقر على اسم واجهة برمجة التطبيقات. الذي تريد تأمينه.
- في صفحة تقييد مفتاح واجهة برمجة التطبيقات وإعادة تسميته، حدِّد القيود التالية:
- القيود المفروضة على واجهة برمجة التطبيقات
- اختَر تقييد المفتاح.
- انقر على تحديد واجهات برمجة التطبيقات واختر كلاً من Maps JavaScript API وPlaces API.
(إذا كانت إحدى واجهات برمجة التطبيقات غير مُدرجة، ستحتاج إلى تفعيلها.)
- انقر على حفظ.
السياسات والحدود القصوى للاستخدام
الحصص
تشارك مكتبة الأماكن حصة استخدام مع Places API كما هو موصوف في وثائق حدود الاستخدام للموقع Places API.
السياسات
عند استخدام مكتبة الأماكن، يجب أن يتوافق استخدام واجهة برمجة تطبيقات JavaScript للخرائط مع السياسات الموضّحة في Places API.
عمليات البحث عن الأماكن
باستخدام خدمة "الأماكن"، يمكنك إجراء الأنواع التالية من عمليات البحث:
- العثور على مكان من طلب البحث مكان استنادًا إلى استعلام نصي (على سبيل المثال، اسم أو عنوان مكان).
- البحث عن مكان باستخدام الهاتف يعرض Number مكانًا استنادًا إلى رقم هاتف.
- البحث عن الأجهزة المجاورة تعرض قائمة بالأماكن المجاورة استنادًا إلى الموقع الجغرافي للمستخدم.
- البحث النصي لعرض قائمة بالأماكن المجاورة استنادًا إلى سلسلة بحث، على سبيل المثال "بيتزا".
- طلبات الحصول على تفاصيل المكان لعرض معلومات أكثر تفصيلاً حول مكان معين، بما في ذلك مراجعات المستخدمين.
ويمكن أن تتضمن المعلومات التي يتم عرضها منشآت — مثل المطاعم والمتاجر والمكاتب - بالإضافة إلى "الموقع الجغرافي" ونتائجها، والتي تشير إلى العناوين والمناطق السياسية مثل البلدات والمدن نقاط الاهتمام.
العثور على طلبات الأماكن
يتيح لك طلب "العثور على مكان" البحث عن مكان إما عن طريق طلب بحث نصي أو رقم هاتفك. هناك نوعان من طلبات "العثور على مكان":
العثور على مكان من طلب البحث
تأخذ ميزة "البحث عن مكان من الاستعلام" إدخالاً نصيًا وتعرض مكانًا. يمكن للإدخال
عبارة عن أي نوع من بيانات الأماكن، مثل اسم النشاط التجاري أو عنوانه. لإجراء
العثور على مكان من طلب البحث، والاتصال بـ PlacesService
findPlaceFromQuery()
على أن يأخذ المعاملين التاليين:
query
(مطلوب) السلسلة النصية المطلوب البحث عنها، على سبيل المثال: "مطعم" أو "123 الشارع الرئيسي". يجب أن يكون هذا اسم مكان، أو عنوانه أو فئة المنشآت الفندقية. ويمكن أن ينتج عن أي نوع آخر من الإدخالات الأخطاء ولا يمكن ضمان عرضها لنتائج صالحة. واجهة برمجة تطبيقات الأماكن ستعرض مطابقات المرشح بناءً على هذه السلسلة وترتّب النتائج بناءً على صلتها بالموضوع المتصورة.fields
(مطلوب) حقل واحد أو أكثر لتحديد أنواع بيانات الأماكن المطلوب عرضها.locationBias
(اختياري) الإحداثيات التي تحدد المنطقة للبحث. يمكن أن يكون هذا أحد التالي:- مجموعة من إحداثيات خطوط العرض/خطوط الطول والعرض يتم تحديدها LatLngLiteral أو كائن LatLng
- الحدود المستطيلة (زوجان من خطوط الطول والعرض أو كائن LatLngBounds)
- النطاق الجغرافي (بالمتر) الذي يرتكز على خط الطول/خط العرض
يجب أيضًا ضبط طريقة معاودة الاتصال على findPlaceFromQuery()
،
لمعالجة كائن النتائج وgoogle.maps.places.PlacesServiceStatus
الاستجابة.
يوضح المثال التالي مكالمة إلى findPlaceFromQuery()
.
عن "متحف الفن المعاصر في أستراليا"، بما في ذلك
الحقلان name
وgeometry
var map; var service; var infowindow; function initMap() { var sydney = new google.maps.LatLng(-33.867, 151.195); infowindow = new google.maps.InfoWindow(); map = new google.maps.Map( document.getElementById('map'), {center: sydney, zoom: 15}); var request = { query: 'Museum of Contemporary Art Australia', fields: ['name', 'geometry'], }; var service = new google.maps.places.PlacesService(map); service.findPlaceFromQuery(request, function(results, status) { if (status === google.maps.places.PlacesServiceStatus.OK) { for (var i = 0; i < results.length; i++) { createMarker(results[i]); } map.setCenter(results[0].geometry.location); } }); }الاطّلاع على مثال
العثور على مكان باستخدام رقم الهاتف
تأخذ ميزة "العثور على مكان من رقم الهاتف" رقم هاتف وتعرض مكانًا. إلى
طلب "العثور على مكان من رقم الهاتف"، اتصل
PlacesService
findPlaceFromPhoneNumber()
على أن يأخذ المعاملين التاليين:
phoneNumber
(مطلوبة) رقم هاتف بتنسيق E.164fields
(مطلوب) حقل واحد أو أكثر لتحديد أنواع بيانات الأماكن المطلوب عرضها.locationBias
(اختياري) الإحداثيات التي تحدد المنطقة بحث. يمكن أن يكون السبب واحدًا مما يلي:- مجموعة من إحداثيات خطوط العرض/خطوط الطول والعرض يتم تحديدها LatLngLiteral أو كائن LatLng
- الحدود المستطيلة (أربع نقاط خطوط الطول/العرض أو كائن LatLngBounds)
- النطاق الجغرافي (بالمتر) الذي يرتكز على خط الطول/خط العرض
يجب أيضًا ضبط طريقة معاودة الاتصال على findPlaceFromPhoneNumber()
،
لمعالجة كائن النتائج وgoogle.maps.places.PlacesServiceStatus
الاستجابة.
الحقول (طرق البحث عن الأماكن)
استخدِم المَعلمة fields
لتحديد مصفوفة من أنواع بيانات الأماكن المطلوب عرضها.
مثلاً: fields: ['formatted_address', 'opening_hours', 'geometry']
استخدِم نقطة عند تحديد قيم مركبة. مثلاً: opening_hours.weekday_text
وتتطابق الحقول مع نتائج البحث عن الأماكن، وهي مقسّمة.
إلى ثلاث فئات فوترة هي "أساسية" و"تواصل" و"أجواء". الحقول الأساسية هي
تحرير الفواتير بالسعر الأساسي، بدون أي رسوم إضافية. الاتصال والأجواء
الحقول بسعر أعلى. الاطّلاع على ورقة الأسعار
لمزيد من المعلومات. تكون عمليات تحديد المصدر (html_attributions
) دائمًا.
يتم إرجاعه مع كل اتصال، بغض النظر عما إذا كان الحقل قد تم
طلبنا.
أساسي
تتضمن الفئة الأساسية الحقول التالية:
business_status
وformatted_address
وgeometry
icon
،icon_mask_base_uri
، icon_background_color
،
name
، permanently_closed
(متوقّفة نهائيًا)،
photos
، place_id
، plus_code
، types
التواصل
تشتمل فئة جهة الاتصال على الحقل التالي:opening_hours
(متوقّفة نهائيًا في مكتبة الأماكن، وواجهة برمجة تطبيقات JavaScript للخرائط. استخدِم طلب "تفاصيل مكان" للحصول على
opening_hours
نتيجة).
الأجواء
تتضمن فئة الغلاف الجوي الحقول التالية: "price_level
" و"rating
" و"user_ratings_total
"
يعمل findPlaceFromQuery()
تأخذ كل طريقة findPlaceFromPhoneNumber()
مجموعة نفس مجموعة
عن الحقول نفسها، ويمكنك عرض الحقول نفسها في ردودها.
تعيين تحيز الموقع (طرق البحث عن الأماكن)
استخدام مَعلمة locationBias
لتقديم نتائج مميّزة في ميزة "العثور على مكان"
في منطقة معينة. يمكنك ضبط locationBias
في ما يلي:
الطرق:
تحيز النتائج إلى منطقة معينة:
locationBias: {lat: 37.402105, lng: -122.081974}
تحديد منطقة مستطيلة للبحث:
locationBias: {north: 37.41, south: 37.40, east: -122.08, west: -122.09}
ويمكنك أيضًا استخدام LatLngBounds.
تحديد نصف قطر للبحث (بالأمتار)، متمركز على منطقة معينة:
locationBias: {radius: 100, center: {lat: 37.402105, lng: -122.081974}}
طلبات البحث في الأماكن القريبة
يتيح لك البحث عن الأماكن القريبة البحث عن الأماكن داخل منطقة محددة عن طريق الكلمة الرئيسية أو النوع. يجب أن يتضمن البحث القريب دائمًا موقعًا جغرافيًا، والذي يمكن أن أن يتم تحديدها بإحدى طريقتين:
-
LatLngBounds
. - مساحة دائرية محددة على أنّها مزيج من
location
خاصية - تحديد مركز الدائرة جسمLatLng
، ونصف قطره، يتم قياسه بالمتر.
يبدأ بحث الأماكن المجاورة بالاتصال
PlacesService
's nearbySearch()
، والتي ستنفّذ
إرجاع صفيف من
عناصر
PlaceResult
يُرجى العلم أنّ السمة nearbySearch()
تستبدل طريقة search()
اعتبارًا من الإصدار 3.9.
service = new google.maps.places.PlacesService(map); service.nearbySearch(request, callback);
تستخدم هذه الطريقة طلبًا يتضمّن الحقول التالية:
- أيّ مما يلي:
bounds
، الذي يجب أن يكون كائنgoogle.maps.LatLngBounds
الذي يحدّد المستطيل منطقة البحث. أقصى مسافة قُطرية مسموح بها للحدود تبلغ مساحتها حوالي 100000 متر.location
وradius
الأول يأخذgoogle.maps.LatLng
، ويأخذ الأخير خط عدد صحيح، يمثل نصف قطر الدائرة بالأمتار. الحد الأقصى نصف القطر المسموح به هو 50000 متر. لاحظ أنه عند تم ضبطrankBy
على DISTANCE، يجب تحديدlocation
ولكن لا يمكنك تحديدradius
أوbounds
.
keyword
(اختياري) - مصطلح يجب مطابقته مقابل جميع الحقول المتاحة، بما في ذلك على سبيل المثال لا الحصر، الاسم والنوع وعنوانها، بالإضافة إلى مراجعات العملاء وغيرها من المحتوى التابع لجهات خارجية.minPriceLevel
وmaxPriceLevel
(اختياري) - يقصر النتائج على تلك الأماكن داخل النطاق المحدد. تتراوح القيم الصالحة بين 0 (الأكثر تكلفة) إلى 4 (الأكثر تكلفة) ضمنًا.- تم إيقاف العمل بميزة "
name
". يعادلkeyword
. القيم في هذا الحقل يتم دمجها مع القيم في الحقلkeyword
وتمريره كجزء من سلسلة البحث نفسها. openNow
(اختيارية) — قيمة منطقية، الإشارة إلى أن خدمة الأماكن يجب أن تعرض فقط تلك الأماكن التي مفتوحة للأعمال في وقت إرسال الاستعلام. أماكن لا تستضيفها تحديد ساعات العمل في قاعدة بيانات أماكن Google لن يتم إذا تم تضمين هذه المعلمة في طلب البحث. الإعداد ما مِن تأثير من "openNow
" إلى "false
".rankBy
(اختيارية) — لتحديد الترتيب النتائج المدرجة. القيم المتاحة:google.maps.places.RankBy.PROMINENCE
(الخيار التلقائي) هذا النمط يقوم الخيار بفرز النتائج بناءً على أهميتها. سيؤدي الترتيب إلى تفضيل الأماكن البارزة ضمن النطاق الجغرافي المحدد على الجوار الأماكن المتطابقة ولكنها أقل بروزًا. يمكن أن يكون البروز حسب ترتيب المكان في فهرس Google، أو الرواج العالمي، وعوامل أخرى. فعندماgoogle.maps.places.RankBy.PROMINENCE
هو محددة، تكون المعلمةradius
مطلوبة.google.maps.places.RankBy.DISTANCE
هذا الخيار تفرز النتائج بترتيب تصاعدي حسب بُعدها عن المحددlocation
(مطلوب). لاحظ أنه لا يمكنك تحديدbounds
و/أوradius
مخصّصة إذا كنت تحديدRankBy.DISTANCE
. عندما تحددRankBy.DISTANCE
، واحد أو أكثر منkeyword
أوname
أوtype
هي مطلوبة.
type
— يحظر نتائج إلى أماكن تطابق النوع المحدد. يمكن تصنيف نوع واحد فقط محددة (إذا تم تقديم أكثر من نوع، فإن جميع الأنواع تتبع النوع الأول من الإدخالات). اطّلع على قائمة والأنواع المتوافقة
يجب عليك أيضًا تمرير طريقة معاودة الاتصال إلى nearbySearch()
، من أجل
التعامل مع كائن النتائج
ردّ google.maps.places.PlacesServiceStatus
var map; var service; var infowindow; function initialize() { var pyrmont = new google.maps.LatLng(-33.8665433,151.1956316); map = new google.maps.Map(document.getElementById('map'), { center: pyrmont, zoom: 15 }); var request = { location: pyrmont, radius: '500', type: ['restaurant'] }; service = new google.maps.places.PlacesService(map); service.nearbySearch(request, callback); } function callback(results, status) { if (status == google.maps.places.PlacesServiceStatus.OK) { for (var i = 0; i < results.length; i++) { createMarker(results[i]); } } }
طلبات البحث النصي
خدمة البحث النصي في أماكن Google هي خدمة ويب تعرض معلومات حول مجموعة من الأماكن استنادًا إلى سلسلة — على سبيل المثال "البيتزا في دبي" أو "متاجر أحذية بالقرب من أوتاوا". تستجيب الخدمة بـ قائمة بالأماكن التي تطابق السلسلة النصية وأي تحيز موقع له النهج التحليلي. ستتضمّن استجابة البحث قائمة بالأماكن. يمكنك إرسال طلب تفاصيل المكان للحصول على مزيد من المعلومات حول أي من الأماكن الموجودة في الاستجابة.
تبدأ عمليات البحث النصية من خلال استدعاء
طريقة textSearch()
لـ PlacesService
service = new google.maps.places.PlacesService(map); service.textSearch(request, callback);
تستخدم هذه الطريقة طلبًا يتضمّن الحقول التالية:
query
(مطلوب) السلسلة النصية التي يمكن البحث، على سبيل المثال: "مطعم" أو "123 الشارع الرئيسي". يجب أن يكون هذا المكان. اسم المنشآت أو عنوانها أو فئة المنشآت. ويمكن لأي نوع آخر من المدخلات إنشاء أخطاء ولا يمكن ضمان عرضها لنتائج صالحة. الأماكن ستعرض خدمة مطابقات المرشح بناءً على هذه السلسلة وتطلب النتائج بناءً على مدى الصلة المتصورة. تصبح هذه المَعلمة اختيارية. إذا كانت معلمةtype
تُستخدم أيضًا في طلب البحث.- بشكل اختياري:
openNow
— قيمة منطقية، الإشارة إلى أن خدمة الأماكن يجب أن تعرض فقط تلك الأماكن التي مفتوحة للأعمال في وقت إرسال الاستعلام. أماكن لا تستضيفها تحديد ساعات العمل في قاعدة بيانات أماكن Google لن يتم إذا تم تضمين هذه المعلمة في طلب البحث. الإعداد ما مِن تأثير من "openNow
" إلى "false
".minPriceLevel
وmaxPriceLevel
— لتقييد النتائج إلى الأماكن الموجودة داخل لمستوى السعر المحدد. تقع القيم الصالحة في نطاق يتراوح بين 0. (الأكثر تكلفة) إلى 4 (الأكثر تكلفة) ضمنًا.- أيّ مما يلي:
bounds
، الذي يجب أن يكون كائنgoogle.maps.LatLngBounds
الذي يحدّد المستطيل منطقة البحث. أقصى مسافة قُطرية مسموح بها للحدود تبلغ مساحتها حوالي 100000 متر.location
وradius
— يمكنك تحيز النتائج إلى دائرة محددة بتمريرlocation
ومَعلمةradius
. سيؤدي هذا إلى ضبط خدمة "الأماكن" لتفضيل عرض النتائج داخل تلك الخدمة دَائِرَة. قد يستمر عرض النتائج خارج المنطقة المحدّدة. يحصل الموقع الجغرافي على كائنgoogle.maps.LatLng
. يأخذ نصف القطر عددًا صحيحًا بسيطًا يمثل نصف قطر الدائرة بالمتر. أقصى نطاق مسموح به هو 50000 متر.
type
— يحصر النتائج بالأماكن المطابقة النوع المحدد. يمكن تحديد نوع واحد فقط (إذا كان هناك أكثر من نوع واحد) النوع، يتم تجاهل جميع الأنواع التي تلي الإدخال الأول). عرض قائمة الأنواع المتوافقة.
يجب أيضًا تمرير طريقة معاودة الاتصال إلى textSearch()
، من أجل
التعامل مع كائن النتائج
ردّ google.maps.places.PlacesServiceStatus
var map; var service; var infowindow; function initialize() { var pyrmont = new google.maps.LatLng(-33.8665433,151.1956316); map = new google.maps.Map(document.getElementById('map'), { center: pyrmont, zoom: 15 }); var request = { location: pyrmont, radius: '500', query: 'restaurant' }; service = new google.maps.places.PlacesService(map); service.textSearch(request, callback); } function callback(results, status) { if (status == google.maps.places.PlacesServiceStatus.OK) { for (var i = 0; i < results.length; i++) { var place = results[i]; createMarker(results[i]); } } }
الردود على البحث
رموز الحالة
يحتوي كائن الاستجابة PlacesServiceStatus
على حالة
وقد تحتوي على معلومات تصحيح الأخطاء لمساعدتك في تعقب
سبب فشل طلب المكان. قيم الحالة المحتملة هي:
INVALID_REQUEST
: هذا الطلب غير صالح.OK
: يحتوي الردّ على نتيجة صالحة.OVER_QUERY_LIMIT
: تجاوزت صفحة الويب طلبها الحصة.REQUEST_DENIED
: لا يُسمح لصفحة الويب باستخدام PlacesService.UNKNOWN_ERROR
: تعذّر تنفيذ طلب PlacesService تمت معالجتها بسبب خطأ في الخادم. قد ينجح الطلب في حال إعادة المحاولة.ZERO_RESULTS
: لم يتم العثور على نتائج لهذا الطلب.
نتائج البحث عن الأماكن
إنّ findPlace()
وnearbySearch()
ترجع الدوال textSearch()
صفيفًا من
PlaceResult
عناصر
قد يتضمّن كل عنصر PlaceResult
السمات التالية:
- وتشير السمة
business_status
إلى النشاط التشغيلي. حالة المكان، إذا كان نشاطًا تجاريًا. يمكن أن تحتوي على إحدى القيم التالية:OPERATIONAL
CLOSED_TEMPORARILY
CLOSED_PERMANENTLY
business_status
. formatted_address
هو سلسلة تحتوي على نص يمكن لشخص عادي قراءته الخاص بهذا المكان. السمةformatted_address
ليست سوى التي تم عرضها للبحث النصي.وغالبًا ما يكون هذا العنوان مكافئًا للعنوان البريدي. لاحظ أن بعض بلاد مثل المملكة المتحدة، فلا تسمح بتوزيع قيم صحيحة عناوين بريدية بسبب قيود الترخيص.
يتكون العنوان بالتنسيق منطقيًا من عنوان واحد أو أكثر . على سبيل المثال، العنوان "111 8th Avenue, New York, NY" تتكون من المكونات التالية: "111" (رقم الشارع)، "الجادة 8" (المسار)، "نيويورك" (المدينة) و"NY" (الولاية الأمريكية).
عدم تحليل العنوان المنسَّق آليًا. بدلاً من ذلك، يجب عليك استخدام مكونات العنوان الفردي، والتي تتضمنها استجابة واجهة برمجة التطبيقات بالإضافة إلى إلى حقل العنوان المنسَّق.
geometry
: المعلومات المتعلّقة بهندسة المكان هذا النمط تتضمن ما يلي:- تقدّم
location
خط العرض وخط الطول للمكان الْمَكَانْ. - تحدد السمة
viewport
إطار العرض المفضل على الخريطة في الحالات التي يستعرضون هذا المكان.
- تقدّم
permanently_closed
(متوقّفة نهائيًا) علامة منطقية تشير إلى ما إذا كان المكان قد توقّف عن العمل أم لا نهائيًا أو مؤقتًا (القيمةtrue
). عدم الاستخدامpermanently_closed
بدلاً من ذلك، استخدِمbusiness_status
. للحصول على الحالة التشغيلية للشركات.plus_code
(الاطّلاع على فتح رمز الموقع الجغرافي ورموز المواقع المفتوحة) هو مرجع موقع مشفر، مشتق من إحداثيات خطوط الطول والعرض، يمثل منطقة: 1/8000 من الدرجة × 1/8000 من الدرجة (حوالي 14 متر × 14 متر عند خط الاستواء) أو أصغر. يمكن استخدام رموز Plus Codes كبديل عناوين الشوارع في أماكن لا توجد فيها هذه الأماكن (حيث تكون المباني غير مرقمة أو غير مرقمة لم تتم تسمية الشوارع).يتم تنسيق رمز Plus Codes كرمز عمومي ورمز مركّب:
global_code
هو رمز منطقة مكوّن من 4 أحرف ورمز محلي من 6 أحرف أو أكثر. (849VCWC8+R9).compound_code
هو رمز محلي مكوَّن من 6 أحرف أو أكثر مع موقع جغرافي فاضح. (CWC8+R9، ماونتن فيو، كاليفورنيا، الولايات المتحدة الأمريكية). ويُرجى عدم تحليل هذا المحتوى آليًا.
html_attributions
: مصفوفة من الإحالات التي يجب عليك عند عرض نتائج البحث. يحتوي كل إدخال في الصفيف على نص HTML لإحالة واحدة. ملاحظة: هذه تجميع كل الإشارات المتعلقة باستجابة البحث بالكامل. الكل لذلك يحتويPlaceResult
عنصر في الاستجابة على قائمتي تحديد مصدر متطابقة- تعرض
icon
عنوان URL لرمز PNG ملوّن 71 بكسل × 71 بكسل. - تعرض الدالة
icon_mask_base_uri
عنوان URL الأساسي لعنصر غير ملوّن بدون امتداد .svg أو .png. - تعرض
icon_background_color
رمز اللون السداسي العشري التلقائي لـ فئة المكان. name
: اسم المكان- قد يحتوي
opening_hours
على المعلومات التالية:open_now
هي قيمة منطقية تشير إلى ما إذا كان المكان مفتوحة في الوقت الحالي (متوقّفة نهائيًا في مكتبة الأماكن، أو واجهة برمجة تطبيقات JavaScript للخرائط، استخدمutc_offset_minutes
بدلاً من ذلك).
place_id
هو معرِّف نصي يعرّف بشكل فريد الْمَكَانْ. لاسترداد معلومات عن المكان، يُرجى إدخال هذا المعرّف في تفاصيل المكان طلبك. مزيد من المعلومات حول كيفية الإشارة إلى مكان مع معرّف مكان.- يحتوي مقياس "
rating
" على تقييم المكان من 0.0 إلى 5.0، استنادًا إلى حول مراجعات المستخدمين المجمَّعة types
صفيف من أنواعه المتعلقة بهذا المكان (مثل["political", "locality"]
أو["restaurant", "lodging"]
). قد تحتوي هذه الصفيفة على قيم متعددة أو قد فارغ. قد يتم طرح قيم جديدة بدون إشعار مسبق. اطّلِع على قائمة الأنواع المتوافقة.vicinity
: عنوان مبسَّط للمكان، يتضمّن اسم الشارع ورقم الشارع والمنطقة المحلية، ولكن لا الإقليم/الولاية، أو الرمز البريدي، أو البلد. على سبيل المثال، شركة Google في مدينة سيدني، قيمة مكتب أسترالياvicinity
هي5/48 Pirrama Road, Pyrmont
.
الوصول إلى النتائج الإضافية
بشكل افتراضي، تعرض كل عملية بحث عن مكان ما يصل إلى 20 نتيجة لكل طلب بحث. ومع ذلك،
كل عملية بحث يمكن أن تعرض ما يصل إلى 60 نتيجة، مقسّمة على ثلاث صفحات.
تتوفّر صفحات إضافية عبر PlaceSearchPagination
.
الخاص بك. من أجل الوصول إلى صفحات إضافية، يجب التقاط
كائن PlaceSearchPagination
من خلال دالة معاودة الاتصال. تشير رسالة الأشكال البيانية
يتم تعريف الكائن PlaceSearchPagination
على أنّه:
hasNextPage
هي سمة منطقية تشير إلى ما إذا كان تتوفّر نتائج البحث.true
عندما تكون هناك سمة إضافية .nextPage()
دالة ستُرجع المجموعة التالية من نتائجك. بعد تنفيذ بحث، يجب الانتظار اثنين ثوانٍ قبل أن تتوفر الصفحة التالية من النتائج.
للاطّلاع على المجموعة التالية من النتائج، يُرجى الاتصال بالرقم nextPage
.
يجب عرض كل صفحة من النتائج قبل عرض الصفحة التالية من
نتائجك. لاحظ أنه يتم احتساب كل عملية بحث كطلب واحد
وحدود الاستخدام.
يوضح المثال أدناه كيفية تغيير دالة الاستدعاء
التقاط كائن PlaceSearchPagination
لتتمكّن من إصدار
طلبات بحث متعددة.
TypeScript
// This example requires the Places library. Include the libraries=places // parameter when you first load the API. For example: // <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places"> function initMap(): void { // Create the map. const pyrmont = { lat: -33.866, lng: 151.196 }; const map = new google.maps.Map( document.getElementById("map") as HTMLElement, { center: pyrmont, zoom: 17, mapId: "8d193001f940fde3", } as google.maps.MapOptions ); // Create the places service. const service = new google.maps.places.PlacesService(map); let getNextPage: () => void | false; const moreButton = document.getElementById("more") as HTMLButtonElement; moreButton.onclick = function () { moreButton.disabled = true; if (getNextPage) { getNextPage(); } }; // Perform a nearby search. service.nearbySearch( { location: pyrmont, radius: 500, type: "store" }, ( results: google.maps.places.PlaceResult[] | null, status: google.maps.places.PlacesServiceStatus, pagination: google.maps.places.PlaceSearchPagination | null ) => { if (status !== "OK" || !results) return; addPlaces(results, map); moreButton.disabled = !pagination || !pagination.hasNextPage; if (pagination && pagination.hasNextPage) { getNextPage = () => { // Note: nextPage will call the same handler function as the initial call pagination.nextPage(); }; } } ); } function addPlaces( places: google.maps.places.PlaceResult[], map: google.maps.Map ) { const placesList = document.getElementById("places") as HTMLElement; for (const place of places) { if (place.geometry && place.geometry.location) { const image = { url: place.icon!, size: new google.maps.Size(71, 71), origin: new google.maps.Point(0, 0), anchor: new google.maps.Point(17, 34), scaledSize: new google.maps.Size(25, 25), }; new google.maps.Marker({ map, icon: image, title: place.name!, position: place.geometry.location, }); const li = document.createElement("li"); li.textContent = place.name!; placesList.appendChild(li); li.addEventListener("click", () => { map.setCenter(place.geometry!.location!); }); } } } declare global { interface Window { initMap: () => void; } } window.initMap = initMap;
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
تتطابق الحقول مع Place Details (تفاصيل المكان)
النتائج، وتنقسم إلى ثلاث فئات فوترة: أساسية، وجهة اتصال،
الأجواء تتم فوترة الحقول الأساسية بالسعر الأساسي، ولن يتم تحصيل أي رسوم إضافية
الرسوم. يتم تحصيل الرسوم من حقلَي Contact وAtmosphere بسعر أعلى. الاطّلاع على ورقة الأسعار
لمزيد من المعلومات. تكون عمليات تحديد المصدر (html_attributions
) دائمًا.
مع كل اتصال، بغض النظر عما إذا كان قد تم طلبه أم لا.
أساسي
تتضمن الفئة الأساسية الحقول التالية:
address_components
وadr_address
وbusiness_status
formatted_address
، geometry
، icon
،
icon_mask_base_uri
، icon_background_color
،name
،
permanently_closed
(متوقّف نهائيًا)،
photo
، place_id
، plus_code
، type
،
url
، utc_offset
(متوقّفة نهائيًا
في مكتبة الأماكن، وواجهة برمجة تطبيقات JavaScript للخرائط)، utc_offset_minutes
،
vicinity
التواصل
تشمل فئة جهة الاتصال الحقول التالية:
formatted_phone_number
، international_phone_number
،
opening_hours
، website
الأجواء
تتضمن فئة الغلاف الجوي الحقول التالية:
price_level
، rating
، reviews
،
user_ratings_total
مزيد من المعلومات حول حقول الأماكن. لمزيد من المعلومات، للحصول على معلومات عن كيفية إصدار فواتير طلبات بيانات الأماكن، راجِع الاستخدام والفوترة:
الردود على تفاصيل المكان
رموز الحالة
يحتوي كائن الاستجابة PlacesServiceStatus
على حالة
وقد تحتوي على معلومات تصحيح الأخطاء لمساعدتك في تعقب
سبب فشل طلب تفاصيل المكان. قيم الحالة المحتملة هي:
INVALID_REQUEST
: هذا الطلب غير صالح.OK
: يحتوي الردّ على نتيجة صالحة.OVER_QUERY_LIMIT
: تجاوزت صفحة الويب طلبها الحصة.NOT_FOUND
لم يكن الموقع الجغرافي المُشار إليه في قاعدة بيانات الأماكن.REQUEST_DENIED
: لا يُسمح لصفحة الويب باستخدام PlacesService.UNKNOWN_ERROR
: تعذّر تنفيذ طلب PlacesService تمت معالجتها بسبب خطأ في الخادم. قد ينجح الطلب في حال إعادة المحاولة.ZERO_RESULTS
: لم يتم العثور على نتائج لهذا الطلب.
نتائج تفاصيل المكان
تؤدي مكالمة getDetails()
الناجحة إلى إرجاع
PlaceResult
بالسمات التالية:
address_components
: مصفوفة تحتوي على البيانات المنفصلة السارية على هذا العنوان.يحتوي كل مكون عنوان عادةً على الحقول التالية:
types[]
هو مصفوفة تشير إلى نوع الخاص بك. اطّلِع على قائمة الأنواع المتوافقة.long_name
هو الوصف النصي الكامل أو اسم العنوان كما يعرضه الترميز الجغرافي.- "
short_name
" هو اسم نصي مختصر للعنوان إذا كان متاحًا. على سبيل المثال، مكون العنوان للولاية في ألاسكا قد يكون بهاlong_name
لـ "ألاسكا" وshort_name
من "AK" باستخدام الاختصار البريدي المكون من حرفين.
يُرجى الاطّلاع على الحقائق التالية حول
address_components[]
. الصفيفة:- قد تحتوي مصفوفة مكونات العنوان على مكونات أكثر من
formatted_address
- ولا تضم الصفيفة بالضرورة جميع الكيانات السياسية التي
على عنوان، بخلاف تلك المدرجة في
formatted_address
لاسترداد جميع الكيانات السياسية التي تحتوي على عنوان محدد، فينبغي عليك استخدام الترميز الجغرافي العكسي، وتمرير خط العرض/خط الطول للعنوان كمعلمة للطلب. - ليس هناك ما يضمن بقاء تنسيق الرد كما هو بين
الطلبات. وعلى وجه الخصوص، فإن عدد
address_components
يختلف بناءً على العنوان المطلوب ويمكن أن يتغير بمرور الوقت العنوان نفسه. يمكن للمكون تغيير موضعه في الصفيف. يمكن أن يتغير نوع المكوِّن. قد يكون مكون معين مفقود في رد لاحق.
- وتشير السمة
business_status
إلى النشاط التشغيلي. حالة المكان، إذا كان نشاطًا تجاريًا. يمكن أن تحتوي على إحدى القيم التالية:OPERATIONAL
CLOSED_TEMPORARILY
CLOSED_PERMANENTLY
business_status
. formatted_address
: عنوان هذا المكان يمكن لشخص عادي قراءتهوغالبًا ما يكون هذا العنوان مكافئًا للعنوان البريدي. لاحظ أن بعض بلاد مثل المملكة المتحدة، فلا تسمح بتوزيع قيم صحيحة عناوين بريدية بسبب قيود الترخيص.
يتكون العنوان بالتنسيق منطقيًا من عنوان واحد أو أكثر . على سبيل المثال، العنوان "111 8th Avenue, New York, NY" تتكون من المكونات التالية: "111" (رقم الشارع)، "الجادة 8" (المسار)، "نيويورك" (المدينة) و"NY" (الولاية الأمريكية).
عدم تحليل العنوان المنسَّق آليًا. بدلاً من ذلك، يجب عليك استخدام مكونات العنوان الفردي، والتي تتضمنها استجابة واجهة برمجة التطبيقات بالإضافة إلى إلى حقل العنوان المنسَّق.
formatted_phone_number
: رقم هاتف المكان، بالتنسيق استنادًا إلى الاصطلاح الإقليمي للرقم.geometry
: المعلومات المتعلّقة بهندسة المكان هذا النمط تتضمن ما يلي:- تقدّم
location
خط العرض وخط الطول للمكان الْمَكَانْ. - تحدد السمة
viewport
إطار العرض المفضل على الخريطة في الحالات التي يستعرضون هذا المكان.
- تقدّم
permanently_closed
(متوقّفة نهائيًا) علامة منطقية تشير إلى ما إذا كان المكان قد توقّف عن العمل أم لا نهائيًا أو مؤقتًا (القيمةtrue
). عدم الاستخدامpermanently_closed
بدلاً من ذلك، استخدِمbusiness_status
. للحصول على الحالة التشغيلية للشركات.plus_code
(الاطّلاع على فتح رمز الموقع الجغرافي ورموز المواقع المفتوحة) هو مرجع موقع مشفر، مشتق من إحداثيات خطوط الطول والعرض، يمثل منطقة: 1/8000 من الدرجة × 1/8000 من الدرجة (حوالي 14 متر × 14 متر عند خط الاستواء) أو أصغر. يمكن استخدام رموز Plus Codes كبديل عناوين الشوارع في أماكن لا توجد فيها هذه الأماكن (حيث تكون المباني غير مرقمة أو غير مرقمة لم تتم تسمية الشوارع).يتم تنسيق رمز Plus Codes كرمز عمومي ورمز مركّب:
global_code
هو رمز منطقة مكوّن من 4 أحرف ورمز محلي من 6 أحرف أو أكثر. (849VCWC8+R9).compound_code
هو رمز محلي مكوَّن من 6 أحرف أو أكثر مع موقع جغرافي فاضح. (CWC8+R9، ماونتن فيو، كاليفورنيا، الولايات المتحدة الأمريكية). ويُرجى عدم تحليل هذا المحتوى آليًا.
html_attributions
: نص الإحالة الذي سيتم عرضه نتيجة البحث لهذا المكان.icon
: عنوان URL يؤدي إلى مورد صور يمكن استخدامه تمثّل نوع هذا المكان.- يحتوي النطاق
international_phone_number
على رقم الهاتف الخاص بالمكان رقم بتنسيق دولي. يشمل التنسيق الدولي البلد ويبدأ بعلامة الجمع (+). على سبيل المثال،international_phone_number
في مدينة سيدني بأستراليا هو+61 2 9374 4000
. name
: اسم المكانutc_offset
تمت إزالتها في مكتبة الأماكن، واجهة برمجة تطبيقات JavaScript للخرائط، استخدِمutc_offset_minutes
بدلاً من ذلك.- يحتوي
utc_offset_minutes
على عدد الدقائق الذي تختلف المنطقة الزمنية الحالية للمكان عن التوقيت العالمي المنسَّق (UTC). على سبيل المثال، بالنسبة للأماكن في سيدني، أستراليا خلال نظام التوقيت الصيفي، سيكون هذا الوقت 660 (أكثر من 11 ساعة) من التوقيت العالمي المنسَّق (UTC)، وللأماكن في كاليفورنيا خارج التوقيت الصيفي سيكون -480 (-8 ساعات من التوقيت العالمي المتفق عليه). - يحتوي
opening_hours
على المعلومات التالية:open_now
(متوقّف نهائيًا في مكتبة الأماكن، وواجهة برمجة تطبيقات JavaScript للخرائط؛ استخدام opening_hours.isOpen() بدلاً من ذلك. يمكنك مشاهدة هذا الفيديو لمعرفة كيفية الاستخدام.isOpen
مع تفاصيل المكان). قيمة منطقية تشير إلى ما إذا كان المكان مفتوحًا في الوقت.periods[]
هي مصفوفة من الفترات الافتتاحية تغطي سبعة أيام، بدءًا من الأحد، بترتيب زمني. كل فترة تحتوي على:- يحتوي
open
على عنصرَي اليوم والوقت. يصف متى يفتح المكان:day
رقم من 0 إلى 6 (وفقًا للأيام) من أيام الأسبوع، بدءًا من يوم الأحد. على سبيل المثال، تعني 2 الثلاثاء- قد يحتوي
time
على وقت من اليوم بتنسيق 24 ساعة (تظهر القيم في النطاق 0000-2359). تشير رسالة الأشكال البيانية سيتم الإبلاغ عنtime
حسب المنطقة الزمنية للمكان.
- قد يحتوي
close
على زوج من عناصر اليوم والوقت. تصف متى يُغلق المكان. ملاحظة: إذا كان المكان مفتوحًا دائمًا، فإن قسمclose
سيتم يكون مفقودًا من الإجابة. يمكن أن تعتمد التطبيقات على يتم تمثيلها كنقطةopen
وتحتوي علىday
بقيمة 0 وtime
بقيمة 0000، ولاclose
.
- يحتوي
weekday_text
عبارة عن صفيف من سبع سلاسل تمثل ساعات العمل المنسقة لكل يوم من أيام الأسبوع. إذا تم تحديد مَعلمةlanguage
في تفاصيل المكان. ستُجري خدمة الأماكن تنسيقًا لساعات العمل وأقلمَتها. بشكل مناسب لتلك اللغة. يشير ترتيب العناصر في هذه تعتمد المصفوفة على مَعلمةlanguage
. بعض اللغات يبدأ الأسبوع يوم الاثنين بينما يبدأ البعض الآخر يوم الأحد.
permanently_closed
(متوقّفة نهائيًا) علامة منطقية تشير إلى ما إذا كان المكان قد توقّف عن العمل أم لا نهائيًا أو مؤقتًا (القيمةtrue
). عدم الاستخدامpermanently_closed
بدلاً من ذلك، استخدِمbusiness_status
. للحصول على الحالة التشغيلية للشركات.photos[]
: مصفوفة من عناصرPlacePhoto
يمكن استخدامPlacePhoto
للحصول على صورة باستخدامgetUrl()
، أو يمكنك فحص الكائن بحثًا عن القيم التالية:height
: الحد الأقصى لارتفاع الصورة بالبكسل.width
: الحد الأقصى لعرض الصورة بالبكسل.html_attributions
: نص الإحالة المطلوب عرضه مع صورة هذا المكان.
place_id
: معرّف نصي يعرّف بشكلٍ فريد المكان ويمكن استخدامها لاسترداد المعلومات حول المكان من خلال تفاصيل المكان . مزيد من المعلومات حول كيفية الإشارة إلى مكان مع معرّف مكان.rating
: تقييم المكان من 0.0 إلى 5.0 استنادًا إلى مراجعات المستخدمين المجمَّعةreviews
عبارة عن مصفوفة تضمّ ما يصل إلى خمس مراجعات. كل مراجعة يتكون من عدة مكونات:- يحتوي
aspects[]
على صفيف منPlaceAspectRating
، يوفّر كل منها تصنيف سمة واحدة للمؤسسة. الكائن الأول في الصفيفة يُعد الجانب الأساسي. على كل تعريف "PlaceAspectRating
" على أنّه:type
اسم الجانب الذي يتم تقييمه. تتوفّر الأنواع التالية:appeal
atmosphere
،decor
،facilities
،food
،overall
،quality
وservice
rating
تقييم المستخدم لهذا المحتوى بالتحديد الجانب، من 0 إلى 3.
author_name
اسم المستخدم الذي أرسل المراجعة. وتُنسَب المراجعات المجهولة الهوية إلى "مستخدم Google". إذا مَعلمة اللغة، ثم تظهر العبارة "مستخدم Google" سوف لإرجاع سلسلة مترجمة.author_url
عنوان URL إلى الملف الشخصي للمستخدمين في +Google، إذا المتوفرة.language
رمز لغة مجموعة مهندسي شبكة الإنترنت (IETF) يشير إلى اللغة المستخدم في مراجعة المستخدم. يحتوي هذا الحقل على علامة اللغة الرئيسية فقط، وليس العلامة الثانوية التي تشير إلى البلد أو المنطقة. بالنسبة مثلاً، يتم وضع علامة على جميع المراجعات باللغة الإنجليزية على أنّها "en" وليس "en-AU" أو "en-UK" وهكذاrating
التقييم العام للمستخدم لهذا المكان هذا النمط عددًا صحيحًا يتراوح من 1 إلى 5.text
مراجعة المستخدم عند مراجعة الموقع الجغرافي في أماكن Google، تُعتبر المراجعات النصية اختيارية؛ لذلك، قد يكون هذا الحقل فارغًا.
- يحتوي
types
صفيف من أنواعه المتعلقة بهذا المكان (مثل["political", "locality"]
أو["restaurant", "lodging"]
). قد تحتوي هذه الصفيفة على قيم متعددة أو قد فارغ. قد يتم طرح قيم جديدة بدون إشعار مسبق. اطّلِع على قائمة الأنواع المتوافقة.url
: عنوان URL لصفحة Google الرسمية لهذا الْمَكَانْ. هذه هي الصفحة المملوكة لـ Google والتي تحتوي على أفضل المعلومات المتوفرة حول المكان. يجب أن تشتمل التطبيقات على رابط إلى هذه الصفحة على أي شاشة تعرض نتائج تفصيلية حول المكان إلى المستخدم.vicinity
: عنوان مبسَّط للمكان، يتضمّن اسم الشارع ورقم الشارع والمنطقة المحلية، ولكن لا الإقليم/الولاية، أو الرمز البريدي، أو البلد. على سبيل المثال، شركة Google في مدينة سيدني، قيمة مكتب أسترالياvicinity
هي5/48 Pirrama Road, Pyrmont
. يتم إرجاع السمةvicinity
فقط. لإجراء بحث عن الأجهزة المجاورة.- يسرد
website
الموقع الإلكتروني الموثوق لهذا المكان، مثل كشركة الرئيسية.
ملاحظة: قد لا تتوفّر التقييمات المتعدّدة الأبعاد. جميع المواقع الجغرافية. إذا كان عدد المراجعات قليل جدًا، سيتم عرض التفاصيل يجب تضمين تقييم قديم على مقياس من 0.0 إلى 5.0 (إذا كان متاحًا) أو لا على الإطلاق.
استخدام المكوِّن "نظرة عامة على المكان"
ملاحظة: يستخدم هذا النموذج مكتبة مفتوحة المصدر. يمكنك الاطّلاع على README للحصول على الدعم والملاحظات المتعلقة بالمكتبة.
جرِّب مكوّنات الويب. استخدم ضع مكوّن الويب "نظرة عامة" للحصول على تفاصيل المكان من خلال تمثيل مرئي.
![صورة تعرض اختلافات في الحجم الصغير جدًا والصغير والمتوسطة والكبير والكبير جدًا
ضع مكوِّن "نظرة عامة" على المكان الذي يظهر استنادًا إلى حقل الحجم الذي أدخله المستخدم.](https://developers.google.cn/static/maps/documentation/javascript/images/place-overview-sizes.png?authuser=6&hl=ar)
الإشارة إلى مكان باستخدام رقم تعريف المكان
إنّ رقم تعريف المكان هو مرجع فريد إلى مكان على "خرائط Google". أرقام تعريف الأماكن المتوفرة في معظم المواقع الجغرافية، بما في ذلك الأنشطة التجارية والمعالم والمنتزهات وتقاطعاتها.
لاستخدام معرّف مكان في تطبيقك، يجب أولاً البحث عن المعرّف، وهو
متاح في PlaceResult
من طلب البحث عن الأماكن أو طلب التفاصيل.
يمكنك بعد ذلك استخدام رقم تعريف المكان للبحث عن
المكان
التفاصيل
يتم إعفاء أرقام تعريف الأماكن من قيود التخزين المؤقت المذكورة. في الفقرة 3.2.3(ب) من بنود خدمة Google Maps Platform وبالتالي، يمكنك تخزين قيم رقم تعريف الأماكن لاستخدامها في وقت لاحق. بالنسبة أفضل الممارسات عند تخزين معرفات الأماكن، فراجع نظرة عامة على رقم تعريف المكان.
var map; function initialize() { // Create a map centered in Pyrmont, Sydney (Australia). map = new google.maps.Map(document.getElementById('map'), { center: {lat: -33.8666, lng: 151.1958}, zoom: 15 }); // Search for Google's office in Australia. var request = { location: map.getCenter(), radius: '500', query: 'Google Sydney' }; var service = new google.maps.places.PlacesService(map); service.textSearch(request, callback); } // Checks that the PlacesServiceStatus is OK, and adds a marker // using the place ID and location from the PlacesService. function callback(results, status) { if (status == google.maps.places.PlacesServiceStatus.OK) { var marker = new google.maps.Marker({ map: map, place: { placeId: results[0].place_id, location: results[0].geometry.location } }); } } google.maps.event.addDomListener(window, 'load', initialize);
صور المكان
تسمح لك ميزة "صورة المكان" بإضافة صور فوتوغرافية عالية الجودة المحتوى إلى موقعك. تتيح لك خدمة الصور الوصول إلى ملايين الصور المخزنة في الأماكن وقاعدة بيانات دليل +Google المحلي. عند الوصول إلى مكان معلومات باستخدام طلب "تفاصيل مكان"، وصورة ومراجعها للمحتوى الفوتوغرافي ذي الصلة. البحث في الأماكن القريبة كما تعرض طلبات البحث النصي أيضًا مرجع صورة واحدًا لكل مكان، عندما ذات صلة. ويمكنك باستخدام خدمة الصور الوصول إلى الصور قم بتغيير حجم الصورة إلى الحجم الأمثل لتطبيقك.
سيتم عرض مصفوفة من PlacePhoto
كائن كجزء من
كائن PlaceResult
لأي getDetails()
،
textSearch()
أو
تم تقديم طلب nearbySearch()
بحق PlacesService
.
ملاحظة: يختلف عدد الصور التي يتم إرجاعها حسب الطلب.
- سيؤدي البحث عن مكان قريب أو البحث النصي إلى عرض واحد على الأكثر
عنصر
PlacePhoto
. - سيعرض طلب التفاصيل ما يصل إلى عشرة عناصر
PlacePhoto
.
يمكنك طلب عنوان URL للصورة المرتبطة من خلال طلب
PlacePhoto.getUrl()
، واجتياز رقم صالح
كائن PhotoOptions
. ما يسمح به الكائن PhotoOptions
تحديد الحد الأقصى للارتفاع والعرض المطلوبين للصورة. إذا كنت
حدّد قيمة لكل من maxHeight
وmaxWidth
،
فستقوم خدمة الصور بتغيير حجم الصورة إلى أصغر من الحجمين، بينما
والحفاظ على نسبة العرض إلى الارتفاع الأصلية.
يقبل مقتطف الرمز التالي كائن مكان ويضيف علامة على الخريطة في حال وجود صورة. تم استبدال صورة العلامة التلقائية بإصدار صغير من الصورة
function createPhotoMarker(place) { var photos = place.photos; if (!photos) { return; } var marker = new google.maps.Marker({ map: map, position: place.geometry.location, title: place.name, icon: photos[0].getUrl({maxWidth: 35, maxHeight: 35}) }); }
يتم الحصول على الصور التي تعرضها خدمة الصور من مجموعة متنوعة من
والمواقع الجغرافية، بما في ذلك مالكي الأنشطة التجارية والصور التي يساهم بها المستخدمون. في معظم
يمكن استخدام هذه الصور بدون نَسب العمل، أو سيتطلب الأمر
تضمين معلومات مرجعية كجزء من الصورة. ومع ذلك، إذا تم إرجاع
يحتوي العنصر photo
على قيمة في
html_attributions
، يجب تضمين
الإحالة في تطبيقك أينما تعرض الصورة.