نظرة عامة
تتيح الوظائف في "مكتبة الأماكن" وواجهة برمجة تطبيقات JavaScript للخرائط لتطبيقك إمكانية البحث عن الأماكن (المحدَّدة في واجهة برمجة التطبيقات هذه على أنّها منشآت أو مواقع جغرافية أو نقاط اهتمام بارزة) مضمّنة في منطقة محدّدة، مثل حدود الخريطة أو حول نقطة ثابتة.
توفّر واجهة Places API ميزة الإكمال التلقائي التي يمكنك استخدامها لمنح تطبيقاتك سلوك بحث مبدئي في حقل البحث في "خرائط Google". عندما يبدأ المستخدم في كتابة عنوان، ستتم تعبئة الباقي من خلال ميزة الإكمال التلقائي. لمزيد من المعلومات، اطّلِع على مستندات الإكمال التلقائي.
الخطوات الأولى
إذا لم تكن على دراية بواجهة برمجة تطبيقات JavaScript للخرائط أو باستخدام JavaScript، ننصحك بمراجعة JavaScript والحصول على مفتاح واجهة برمجة تطبيقات قبل البدء.
تفعيل واجهات برمجة التطبيقات
قبل استخدام مكتبة الأماكن في واجهة برمجة تطبيقات JavaScript للخرائط، تأكّد أولاً من تفعيل واجهة Places API في Google Cloud Console، في المشروع نفسه الذي أعددته لواجهة Maps JavaScript API.
لعرض قائمة واجهات برمجة التطبيقات المفعَّلة:
- انتقِل إلى Google Cloud Console.
- انقر على الزرّ اختيار مشروع، ثم اختَر المشروع نفسه الذي أعددته لواجهة برمجة تطبيقات JavaScript للخرائط وانقر على فتح.
- من قائمة واجهات برمجة التطبيقات في لوحة البيانات، ابحث عن واجهة برمجة تطبيقات الأماكن.
- إذا كنت ترى واجهة برمجة تطبيقات الأماكن في القائمة، يعني ذلك أنه سبق أن تم تفعيلها. إذا لم تكن واجهة برمجة التطبيقات مدرَجة، يمكنك تفعيلها:
- في أعلى الصفحة، انقر على ENABLE APIS AND SERVICES (تفعيل واجهات برمجة التطبيقات والخدمات) لعرض علامة التبويب المكتبة. يمكنك أيضًا اختيار المكتبة من القائمة الجانبية اليمنى.
- ابحث عن Places API، ثم اختَرها من قائمة النتائج.
- انقر على تفعيل. عند انتهاء العملية، تظهر Places API في قائمة واجهات برمجة التطبيقات في لوحة البيانات.
جارٍ تحميل المكتبة
خدمة "الأماكن" هي مكتبة مستقلة عن رمز واجهة برمجة تطبيقات JavaScript لـ "خرائط Google" الرئيسي. لاستخدام الوظائف المضمَّنة
في هذه المكتبة، يجب أولاً تحميلها باستخدام المَعلمة libraries
في عنوان URL الخاص ببدء تشغيل واجهة برمجة تطبيقات "خرائط Google":
<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":- انتقِل إلى Google Cloud Console.
- انقر على القائمة المنسدلة للمشروع واختَر المشروع الذي يحتوي على مفتاح واجهة برمجة التطبيقات الذي تريد تأمينه.
- انقر على زر القائمة واختَر منصة خرائط Google > بيانات الاعتماد.
- في صفحة بيانات الاعتماد، انقر على اسم مفتاح واجهة برمجة التطبيقات الذي تريد تأمينه.
- في صفحة تقييد مفتاح واجهة برمجة التطبيقات وإعادة تسميته، اضبط القيود:
- قيود واجهة برمجة التطبيقات
- اختَر تقييد المفتاح.
- انقر على اختيار واجهات برمجة التطبيقات واختَر كلاً من واجهة برمجة تطبيقات JavaScript للخرائط وواجهة برمجة تطبيقات الأماكن.
(إذا لم تكن أي من واجهتَي برمجة التطبيقات مدرَجة، عليك enable.)
- انقر على حفظ.
الحدود القصوى للاستخدام والسياسات
الحصص
تشارك مكتبة الأماكن حصة استخدام مع Places API على النحو الموضح في مستندات حدود الاستخدام الخاصة بـ Places API.
السياسات
ويجب أن يتوافق استخدام "مكتبة الأماكن" مع "واجهة برمجة تطبيقات JavaScript للخرائط" مع السياسات الموضّحة في "واجهة برمجة تطبيقات الأماكن".
عمليات البحث عن الأماكن
باستخدام خدمة الأماكن، يمكنك إجراء أنواع البحث التالية:
- تعرض دالة البحث عن مكان من طلب البحث مكانًا استنادًا إلى طلب بحث نصي (على سبيل المثال، اسم مكان أو عنوانه).
- تعرض أداة البحث عن مكان من رقم الهاتف مكانًا استنادًا إلى رقم هاتف.
- تعرض ميزة البحث عن قرب قائمة بالأماكن المجاورة استنادًا إلى الموقع الجغرافي للمستخدم.
- البحث النصي يعرض قائمة بالأماكن المجاورة استنادًا إلى سلسلة بحث، على سبيل المثال "بيتزا".
- تعرض طلبات تفاصيل المكان معلومات أكثر تفصيلاً حول مكان معيّن، بما في ذلك مراجعات المستخدمين.
ويمكن أن تشتمل المعلومات التي يتم عرضها على منشآت، مثل مطاعم ومتاجر ومكاتب، بالإضافة إلى نتائج "جغرافي" تشير إلى العناوين والمناطق السياسية مثل البلدات والمدن وغيرها من نقاط الاهتمام.
العثور على طلبات الأماكن
يتيح لك طلب البحث عن مكان البحث عن مكان إما عن طريق الاستعلام النصي أو رقم الهاتف. هناك نوعان من طلبات البحث عن مكان:
العثور على مكان من الاستعلام
تأخذ ميزة "البحث عن مكان" من الاستعلام إدخالاً نصيًا وترجع مكانًا. يمكن أن يكون الإدخال أي نوع من
بيانات المكان، على سبيل المثال اسم نشاط تجاري أو عنوانه. لإنشاء طلب بحث عن مكان من طلب البحث، يمكنك استدعاء طريقة PlacesService
findPlaceFromQuery()
، والتي تأخذ المعلمات التالية:
query
(مطلوبة) سلسلة النص المطلوب البحث عليها، على سبيل المثال: "مطعم" أو "123 Main Street". ويجب أن يكون هذا الحقل اسمًا لمكان أو عنوانًا أو فئة من المنشآت. يمكن أن تؤدي أي أنواع أخرى من الإدخالات إلى حدوث أخطاء، ولا يمكن ضمان عرض نتائج صالحة. ستعرض 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); } }); }عرض مثال
العثور على مكان من رقم الهاتف
تأخذ ميزة "البحث عن مكان" من رقم الهاتف رقم هاتف وترجع إلى مكان. لتقديم طلب "العثور على مكان من رقم الهاتف"، يمكنك استدعاء طريقة PlacesService
findPlaceFromPhoneNumber()
، والتي تأخذ المعلمات التالية:
phoneNumber
(مطلوب) رقم هاتف بتنسيق E.164.fields
(مطلوبة) حقل واحد أو أكثر من الحقول يحدّد أنواع بيانات المكان المطلوب عرضها.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
، ونصف قطر يتم قياسه بالمتر.
يبدأ البحث عن "الأماكن المجاورة" من خلال استدعاء طريقة nearbySearch()
في
PlacesService
، ستعرض مصفوفة من عناصر
PlaceResult
. يُرجى العِلم أنّ الطريقة nearbySearch()
تحلّ محلّ طريقة search()
اعتبارًا من الإصدار 3.9.
service = new google.maps.places.PlacesService(map); service.nearbySearch(request, callback);
تتطلّب هذه الطريقة طلبًا يتضمّن الحقول التالية:
- أيّ ممّا يلي:
bounds
، التي يجب أن تكون كائنgoogle.maps.LatLngBounds
يحدّد منطقة البحث المستطيلة، أو- تمثّل هذه السمة
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" هي خدمة ويب تعرض معلومات عن مجموعة من الأماكن استنادًا إلى سلسلة، على سبيل المثال "فطائر في دبي" أو "متاجر أحذية بالقرب من أوتاوا". وتستجيب الخدمة مع إدراج قائمة بالأماكن التي تتطابق مع السلسلة النصية وأي انحياز تم تحديده للموقع الجغرافي. سيتضمن ردّ البحث قائمة بالأماكن. يمكنك إرسال طلب "تفاصيل المكان" للحصول على مزيد من المعلومات حول أي من الأماكن الواردة في الردّ.
تبدأ عمليات البحث عن النصوص من خلال استدعاء طريقة
textSearch()
لـ PlacesService
.
service = new google.maps.places.PlacesService(map); service.textSearch(request, callback);
تتطلّب هذه الطريقة طلبًا يتضمّن الحقول التالية:
query
(مطلوبة) السلسلة النصية المطلوب البحث عليها، مثل: "مطعم" أو "123 Main Street". ويجب أن يكون اسمًا لمكان أو عنوانًا أو فئة من المنشآت. يمكن أن تؤدي أي أنواع أخرى من الإدخالات إلى حدوث أخطاء، ولا يمكن ضمان عرض نتائج صالحة. ستعرض خدمة "الأماكن" النتائج المطابِقة المرشحة استنادًا إلى هذه السلسلة، ثم ترتّب النتائج استنادًا إلى مدى صلتها بالموضوع. تصبح هذه المَعلمة اختيارية إذا تمّ أيضًا استخدام المَعلمةtype
في طلب البحث.- اختياريًا:
openNow
— قيمة منطقية تشير إلى أنّ خدمة "الأماكن" يجب أن تعرض فقط الأماكن التي تكون مفتوحة لمزاولة النشاط التجاري وقت إرسال طلب البحث لن يتم عرض الأماكن التي لا تحدّد ساعات العمل في قاعدة بيانات "أماكن Google" إذا ضمّنت هذه المعلمة في طلب البحث. وليس هناك أيّ تأثير لضبطopenNow
علىfalse
.minPriceLevel
وmaxPriceLevel
- لحصر النتائج بتلك الأماكن ضمن مستوى السعر المحدّد فقط. تتراوح القيم الصالحة بين 0 (الأقل تكلفة) و4 (الأكثر تكلفة).- أيّ ممّا يلي:
bounds
— كائنgoogle.maps.LatLngBounds
يحدد المستطيل المطلوب البحث فيه، أوlocation
وradius
: يمكنك انحياز النتائج إلى دائرة محدّدة من خلال ضبط معلَمةlocation
وradius
. وسيؤدي هذا إلى تفضيل خدمة "الأماكن" لعرض النتائج داخل تلك الدائرة. وقد يستمر عرض النتائج خارج المنطقة المحددة. يأخذ الموقع الجغرافي عنصرgoogle.maps.LatLng
، ويأخذ نصف القطر عددًا صحيحًا بسيطًا يمثل نصف قطر الدائرة بالمتر. يبلغ الحد الأقصى المسموح به للنطاق الجغرافي 50 ألف متر.
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 شارع السلام، القاهرة"، من العناصر التالية: "111" (رقم الشارع) و"الجادة الثامنة" (المسار) و"نيويورك" (المدينة) و "نيويورك" (الولاية الأمريكية).
لا تحلل العنوان المنسَّق بطريقة آلية. بدلاً من ذلك، عليك استخدام مكوّنات العنوان الفردية التي تتضمّنها استجابة واجهة برمجة التطبيقات بالإضافة إلى حقل العنوان المنسَّق.
geometry
: معلومات عن المكان من حيث الأشكال الهندسية ويشمل ذلك ما يلي:- توفِّر السمة
location
خط العرض وخط الطول للمكان. - تحدّد السمة
viewport
إطار العرض المفضّل على الخريطة عند عرض هذا المكان.
- توفِّر السمة
permanently_closed
(متوقّفة نهائيًا) هي علامة منطقية تشير إلى ما إذا كان قد تم إيقاف المكان نهائيًا أو بشكل مؤقت (القيمةtrue
). لا تستخدمpermanently_closed
. بدلاً من ذلك، استخدِمbusiness_status
للاطّلاع على الحالة التشغيلية للأنشطة التجارية.plus_code
(راجِع رمز الموقع المفتوح ورموز المواقع المفتوحة) هو مرجع موقع مشفّر، يتم اشتقاقه من إحداثيات خط الطول وخط العرض ويمثّل منطقة: 1/8, 000 درجة وزاوية 1/8, 000 درجة من الدرجة (حوالي 14 متر × 14 متر على خط الاستواء) أو أصغر. يمكن استخدام رموز 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
: عنوان مبسّط للمكان، بما في ذلك اسم الشارع ورقم الشارع والمنطقة المحلية، ولكن ليس الإقليم/الولاية أو الرمز البريدي أو البلد. على سبيل المثال، قيمة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
وurl
وutc_offset
و{120/icon
و{19/2} ووواجهة برمجة التطبيقات و/ متوقّفة نهائيًا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 شارع السلام، القاهرة"، من العناصر التالية: "111" (رقم الشارع) و"الجادة الثامنة" (المسار) و"نيويورك" (المدينة) و "نيويورك" (الولاية الأمريكية).
لا تحلل العنوان المنسَّق بطريقة آلية. بدلاً من ذلك، عليك استخدام مكوّنات العنوان الفردية التي تتضمّنها استجابة واجهة برمجة التطبيقات بالإضافة إلى حقل العنوان المنسَّق.
formatted_phone_number
: رقم هاتف المكان، منسَّق وفقًا للاصطلاح الإقليمي.geometry
: معلومات عن المكان من حيث الأشكال الهندسية ويشمل ذلك ما يلي:- توفِّر السمة
location
خط العرض وخط الطول للمكان. - تحدّد السمة
viewport
إطار العرض المفضّل على الخريطة عند عرض هذا المكان.
- توفِّر السمة
permanently_closed
(متوقّفة نهائيًا) هي علامة منطقية تشير إلى ما إذا كان قد تم إيقاف المكان نهائيًا أو بشكل مؤقت (القيمةtrue
). لا تستخدمpermanently_closed
. بدلاً من ذلك، استخدِمbusiness_status
للاطّلاع على الحالة التشغيلية للأنشطة التجارية.plus_code
(راجِع رمز الموقع المفتوح ورموز المواقع المفتوحة) هو مرجع موقع مشفّر، يتم اشتقاقه من إحداثيات خط الطول وخط العرض ويمثّل منطقة: 1/8, 000 درجة وزاوية 1/8, 000 درجة من الدرجة (حوالي 14 متر × 14 متر على خط الاستواء) أو أصغر. يمكن استخدام رموز Plus Codes كبديل لعناوين الشوارع في الأماكن التي لا توجد فيها (حيث لا تكون المباني مرقمة أو لا تتم تسمية الشوارع).يتم تنسيق رمز الموقع المفتوح كرمز عام ورمز مركب:
global_code
هو رمز منطقة مكوّن من 4 أحرف ورمز محلي مكوّن من 6 أحرف أو أكثر (849VCWC8+R9).- يتكوّن
compound_code
من 6 أحرف أو أكثر رمز محلي يشمل موقعًا جغرافيًا صريحًا (CWC8+R9، ماونتن فيو، كاليفورنيا، الولايات المتحدة الأمريكية). يجب عدم تحليل هذا المحتوى آليًا.
html_attributions
: نص تحديد المصدر الذي سيتم عرضه لنتيجة المكان هذه.icon
: عنوان URL لمورد صورة يمكن استخدامه لتمثيل نوع هذا المكان.- يحتوي
international_phone_number
على رقم هاتف المكان بالتنسيق الدولي. يتضمّن التنسيق الدولي رمز البلد، ويبدأ بعلامة الجمع (+). على سبيل المثال،international_phone_number
لمكتب Google في مدينة سيدني بأستراليا هو+61 2 9374 4000
. name
: اسم المكانutc_offset
متوقف نهائيًا في "مكتبة الأماكن" وواجهة برمجة تطبيقات JavaScript للخرائط، ويمكنك استخدامutc_offset_minutes
بدلاً منه.- يتضمّن عمود "
utc_offset_minutes
" عدد الدقائق التي لا يفصل فيها عن المنطقة الزمنية الحالية لهذا المكان عن التوقيت العالمي المنسَّق. على سبيل المثال، بالنسبة إلى الأماكن في مدينة سيدني بأستراليا خلال التوقيت الصيفي، يجب إدخال 660 ساعة (+11 ساعة من التوقيت العالمي المتفق عليه)، وفي الأماكن في كاليفورنيا خارج التوقيت الصيفي، سيكون العدد -480 (-8 ساعات من التوقيت العالمي المنسَّق). - يتضمّن السمة
opening_hours
المعلومات التالية:open_now
(متوقف نهائيًا في مكتبة الأماكن، وواجهة برمجة تطبيقات JavaScript للخرائط، ويمكنك استخدام opening_hours.isOpen() بدلاً من ذلك. يمكنك مشاهدة هذا الفيديو للتعرّف على كيفية استخدام "isOpen
" مع "تفاصيل المكان".) هو قيمة منطقية تشير إلى ما إذا كان المكان مفتوحًا في الوقت الحالي.- تمثّل السمة
periods[]
مصفوفة من فترات الفتح التي تغطي سبعة أيام، بدءًا من يوم الأحد، بترتيب زمني. وتحتوي كل فترة على ما يلي:- يحتوي
open
على عنصرَي اليوم والوقت يحدّدان وقت فتح المكان:day
رقمًا من 0 إلى 6، وفقًا لأيام الأسبوع، بدءًا من يوم الأحد. على سبيل المثال، تعني 2 يوم الثلاثاء.- قد تحتوي السمة
time
على وقت بتنسيق 24 ساعة hhmm (تتراوح القيم بين 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-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 (في حال توفّره) أو عدم تضمين أي تقييم على الإطلاق.
استخدام مكوِّن "نظرة عامة على المكان"
ملاحظة: يستخدم هذا النموذج مكتبة مفتوحة المصدر. يمكنك الاطّلاع على ملف README للحصول على الدعم والملاحظات المتعلقة بالمكتبة.
جرِّب مكوّنات الويب. استخدِم مكوّن الويب نظرة عامة على المكان للحصول على تفاصيل المكان من خلال تمثيل مرئي.
الإشارة إلى مكان باستخدام رقم تعريف المكان
رقم تعريف المكان هو مرجع فريد لمكان على "خرائط 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
، يجب تضمين الإحالة الإضافية في تطبيقك أينما عرض الصورة.