نظرة عامة
تتيح الوظائف في "مكتبة الأماكن" وواجهة برمجة تطبيقات JavaScript للخرائط لتطبيقك إمكانية البحث عن الأماكن (التي يتم تعريفها في واجهة برمجة التطبيقات هذه على أنّها منشآت أو مواقع جغرافية أو نقاط اهتمام بارزة) في منطقة محدّدة، مثل حدود الخريطة أو حول نقطة ثابتة.
توفّر واجهة برمجة تطبيقات الأماكن ميزة الإكمال التلقائي التي يمكنك استخدامها لمنح تطبيقاتك سلوك البحث المسبق كما يلي في حقل البحث في "خرائط Google". عندما يبدأ المستخدم في كتابة عنوان، سيتم ملء باقي العناوين من خلال ميزة الإكمال التلقائي. للاطّلاع على مزيد من المعلومات، راجِع مستندات الإكمال التلقائي.
البدء
إذا لم تكن على دراية بواجهة برمجة تطبيقات JavaScript للخرائط أو بلغة JavaScript، ننصحك بمراجعة JavaScript والحصول على مفتاح واجهة برمجة تطبيقات قبل البدء.
تفعيل واجهات برمجة التطبيقات
قبل استخدام مكتبة الأماكن في واجهة برمجة تطبيقات JavaScript للخرائط، تأكَّد أولاً من تفعيل واجهة Places API في Google Cloud Console في المشروع نفسه الذي أعددته لـ Maps JavaScript API.
للاطّلاع على قائمة واجهات برمجة التطبيقات المفعَّلة:
- انتقِل إلى Google Cloud Console.
- انقر على الزر اختيار مشروع، ثم اختَر المشروع نفسه الذي أعددته لواجهة برمجة تطبيقات JavaScript للخرائط وانقر على فتح.
- من قائمة واجهات برمجة التطبيقات في لوحة البيانات، ابحث عن Places API.
- إذا رأيت واجهة برمجة تطبيقات الأماكن في القائمة، فهي مُفعَّلة من قبل. إذا لم تكن واجهة برمجة التطبيقات مدرَجة، فعِّلها:
- في أعلى الصفحة، انقر على تفعيل واجهات برمجة التطبيقات والخدمات لعرض علامة التبويب المكتبة. ويمكنك بدلاً من ذلك اختيار المكتبة من القائمة الجانبية اليمنى.
- ابحث عن Places API، ثم اختَرها من قائمة النتائج.
- انقر على تفعيل. عند انتهاء العملية، تظهر Places API في قائمة واجهات برمجة التطبيقات ضمن لوحة البيانات.
جارٍ تحميل المكتبة
خدمة الأماكن هي مكتبة مستقلة عن الرموز الرئيسية لواجهة برمجة تطبيقات JavaScript للخرائط. لاستخدام الوظائف المضمّنة
في هذه المكتبة، يجب أولاً تحميلها باستخدام المَعلمة libraries
في عنوان URL للتشغيل في API للخرائط:
<script async
src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places&callback=initMap">
</script>
للحصول على مزيد من المعلومات، يمكنك الاطّلاع على نظرة عامة على المكتبات.
إضافة Places API إلى قائمة قيود واجهة برمجة التطبيقات الخاصة بمفتاح واجهة برمجة التطبيقات
يؤدي تطبيق قيود واجهة برمجة التطبيقات على مفاتيحك إلى تقييد استخدام مفتاح واجهة برمجة التطبيقات على واجهة برمجة تطبيقات أو حزمة تطوير برامج (SDK) واحدة أو أكثر. وستتم معالجة الطلبات المُرسَلة إلى واجهة برمجة التطبيقات أو حزمة تطوير البرامج (SDK) المرتبطة بمفتاح واجهة برمجة التطبيقات. لن يتم إرسال الطلبات إلى واجهة برمجة تطبيقات أو حزمة تطوير برامج (SDK) غير مرتبطة بمفتاح واجهة برمجة التطبيقات. لحظر مفتاح واجهة برمجة تطبيقات لاستخدامه مع "مكتبة الأماكن" أو واجهة برمجة تطبيقات JavaScript للخرائط:- انتقِل إلى Google Cloud Console.
- انقر على القائمة المنسدلة للمشروع واختَر المشروع الذي يحتوي على مفتاح واجهة برمجة التطبيقات الذي تريد تأمينه.
- انقر على زر القائمة
واختَر منصة خرائط Google > بيانات الاعتماد.
- في صفحة بيانات الاعتماد، انقر على اسم مفتاح واجهة برمجة التطبيقات الذي تريد تأمينه.
- في صفحة تقييد مفتاح واجهة برمجة التطبيقات وإعادة تسميته، اضبط القيود:
- قيود واجهة برمجة التطبيقات
- اختَر تقييد المفتاح.
- انقر على اختيار واجهات برمجة التطبيقات واختر كل من واجهة برمجة تطبيقات JavaScript للخرائط وواجهة برمجة تطبيقات الأماكن.
(إذا لم تكن أي من واجهتَي برمجة التطبيقات مُدرَجة، عليك enable).
- انقر على حفظ.
الحدود القصوى للاستخدام والسياسات
الحصص
تشارك مكتبة الأماكن حصة استخدام مع واجهة برمجة تطبيقات الأماكن كما هو موضح في مستندات حدود الاستخدام الخاصة بواجهة برمجة تطبيقات الأماكن.
السياسات
عند استخدام "مكتبة الأماكن"، يجب أن يكون استخدام واجهة برمجة تطبيقات JavaScript للخرائط متوافقًا مع السياسات الموضّحة في واجهة برمجة تطبيقات الأماكن.
عمليات البحث عن الأماكن
من خلال خدمة الأماكن، يمكنك إجراء الأنواع التالية من عمليات البحث:
- تعرض دالة البحث عن مكان من طلب البحث مكانًا استنادًا إلى طلب بحث نصي (مثل اسم مكان أو عنوانه).
- تؤدي دالة البحث عن مكان من رقم الهاتف إلى عرض مكان استنادًا إلى رقم هاتف.
- تعرض ميزة البحث عن قرب قائمة بالأماكن المجاورة استنادًا إلى الموقع الجغرافي للمستخدم.
- تعرض ميزة البحث النصي قائمة بالأماكن المجاورة استنادًا إلى سلسلة بحث، مثل: "بِيتْزَا".
- تعرض طلبات تفاصيل المكان معلومات أكثر تفصيلاً حول مكان معيّن، بما في ذلك مراجعات المستخدمين.
ويمكن أن تشمل المعلومات التي يتم عرضها منشآت، مثل مطاعم ومتاجر ومكاتب، بالإضافة إلى نتائج "الجغرافيا الجغرافية" التي تشير إلى العناوين والمناطق السياسية مثل البلدات والمدن وغيرها من نقاط الاهتمام.
العثور على طلبات الأماكن
يتيح لك طلب "العثور على مكان" البحث عن مكان إما عن طريق الاستعلام النصي أو رقم الهاتف. هناك نوعان من طلب العثور على مكان:
العثور على مكان من الاستعلام
يأخذ خيار "بحث عن مكان" من الاستعلام إدخالاً نصيًا ويعرض مكانًا. يمكن أن يكون الإدخال أي نوع من
بيانات المكان، على سبيل المثال اسم النشاط التجاري أو عنوانه. لإنشاء
طريقة بحث عن مكان من طلب البحث، عليك استدعاء طريقة
findPlaceFromQuery()
PlacesService
، والتي تأخذ المَعلمات التالية:
query
(مطلوبة) السلسلة النصية المطلوب البحث عليها، على سبيل المثال: "مطعم" أو "123 الشارع الرئيسي". ويجب أن يكون هذا الحقل اسمًا لمكان أو عنوانًا أو فئة من المنشآت. يمكن أن تؤدي أي أنواع أخرى من الإدخالات إلى حدوث أخطاء ولا يمكن ضمان عرض نتائج صالحة لها. ستعرض واجهة Places API مطابقات مرشحة بناءً على هذه السلسلة وترتّب النتائج استنادًا إلى مدى صلتها بالموضوع المطلوب.fields
(مطلوبة) يحدّد حقل واحد أو أكثر أنواع بيانات الأماكن المطلوب عرضها.locationBias
(اختياري) الإحداثيات التي تحدد المنطقة المطلوب البحث فيها. يمكن أن يكون ذلك مما يلي:- مجموعة من إحداثيات خطوط الطول والعرض المحدَّدة على شكل LatLngLiteral أو كائن LatLng
- حدود مستطيلة (زوجان من خطوط الطول/العرض، أو كائن LatLngBounds)
- نصف القُطر (بالمتر) المتمركز على خط الطول/خط العرض
يجب أيضًا ضبط طريقة استدعاء إلى findPlaceFromQuery()
لمعالجة كائن النتائج والاستجابة google.maps.places.PlacesServiceStatus
.
يعرض المثال التالي مكالمة إلى findPlaceFromQuery()
، ويتم البحث عن "متحف الفن المعاصر في أستراليا"، بما في ذلك الحقلَين
name
وgeometry
.
var map; var service; var infowindow; function initMap() { var sydney = new google.maps.LatLng(-33.867, 151.195); infowindow = new google.maps.InfoWindow(); map = new google.maps.Map( document.getElementById('map'), {center: sydney, zoom: 15}); var request = { query: 'Museum of Contemporary Art Australia', fields: ['name', 'geometry'], }; var service = new google.maps.places.PlacesService(map); service.findPlaceFromQuery(request, function(results, status) { if (status === google.maps.places.PlacesServiceStatus.OK) { for (var i = 0; i < results.length; i++) { createMarker(results[i]); } map.setCenter(results[0].geometry.location); } }); }عرض مثال
العثور على مكان من رقم الهاتف
تأخذ ميزة "العثور على المكان" من رقم الهاتف رقم هاتف وترجع مكانًا. لتقديم طلب "العثور على مكان" من رقم الهاتف، اتصل بطريقة 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 الشارع الرئيسي". ويجب أن يكون هذا الحقل اسمًا لمكان أو عنوانًا أو فئة من المنشآت. يمكن أن تؤدي أي أنواع أخرى من الإدخالات إلى حدوث أخطاء ولا يمكن ضمان عرض نتائج صالحة لها. ستعرض خدمة "الأماكن" النتائج المطابِقة المرشحة استنادًا إلى هذه السلسلة، كما ترتّب النتائج استنادًا إلى مدى صلتها بالموضوع المطلوب. وتصبح هذه المَعلمة اختيارية في حال استخدام المَعلمةtype
أيضًا في طلب البحث.- يمكنك اختياريًا إجراء ما يلي:
openNow
- قيمة منطقية تشير إلى أنّه يجب أن تعرض خدمة "الأماكن" الأماكن المفتوحة للنشاط التجاري فقط في وقت إرسال طلب البحث. ولن يتم عرض الأماكن التي لا تحدّد ساعات العمل في قاعدة بيانات أماكن Google في حال تضمين هذه المعلمة في طلب البحث. وليس هناك أي تأثير لضبطopenNow
علىfalse
.minPriceLevel
وmaxPriceLevel
— لحصر النتائج بالأماكن التي ضمن مستوى السعر المحدّد فقط وتتراوح القيم الصالحة بين 0 (الأقل تكلفة) و4 (الأكثر تكلفة) ضمنًا.- أيّ ممّا يلي:
bounds
: عنصرgoogle.maps.LatLngBounds
يحدّد المستطيل المطلوب البحث فيه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 Africa, New York, NY" من المكونات التالية: "111" (رقم الشارع) و"8th Street" (المسار) و"New York" (المدينة) و "NY" (ولاية الولايات المتحدة).
لا تحلّل العنوان المنسَّق آليًا. بدلاً من ذلك، عليك استخدام عناصر العنوان الفردية التي يتضمّنها ردّ واجهة برمجة التطبيقات بالإضافة إلى حقل العنوان المنسَّق.
geometry
: معلومات تتعلّق بهندسة المكان ويشمل ذلك:- تقدّم السمة
location
خط العرض وخط الطول للمكان. - تحدّد السمة
viewport
إطار العرض المفضّل على الخريطة عند عرض هذا المكان.
- تقدّم السمة
permanently_closed
(متوقف نهائيًا) هي علامة منطقية تشير إلى ما إذا كان المكان قد تم إغلاقه نهائيًا أم بشكل مؤقت (القيمةtrue
). لا تستخدم السمةpermanently_closed
. بدلاً من ذلك، استخدِمbusiness_status
للاطّلاع على الحالة التشغيلية للأنشطة التجارية.plus_code
(راجِع Open Location Code (رمز الموقع الجغرافي المفتوح) وplus Codes) هو مرجع موقع جغرافي مشفّر، يتم اشتقاقه من إحداثيات خطوط الطول والعرض، ويمثّل مساحة: 1/8, 000 درجة مضروبة في 1/8, 000 درجة من الدرجة (حوالي 14 متر x 14 متر عند خط الاستواء) أو أقل. يمكن استخدام رموز المواقع المفتوحة كبديل لعناوين الشوارع في الأماكن التي لا تتوفر فيها (حيث لا تكون المباني مرقمة أو لا تتم تسمية الشوارع).يتم تنسيق رمز الموقع المفتوح كرمز عام ورمز مركب:
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
و/2} وutc_offset
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 Africa, New York, NY" من المكونات التالية: "111" (رقم الشارع) و"8th Street" (المسار) و"New York" (المدينة) و "NY" (ولاية الولايات المتحدة).
لا تحلّل العنوان المنسَّق آليًا. بدلاً من ذلك، عليك استخدام عناصر العنوان الفردية التي يتضمّنها ردّ واجهة برمجة التطبيقات بالإضافة إلى حقل العنوان المنسَّق.
formatted_phone_number
: رقم هاتف المكان، منسَّق وفقًا للمؤتمر الإقليمي للرقم.geometry
: معلومات تتعلّق بهندسة المكان ويشمل ذلك:- تقدّم السمة
location
خط العرض وخط الطول للمكان. - تحدّد السمة
viewport
إطار العرض المفضّل على الخريطة عند عرض هذا المكان.
- تقدّم السمة
permanently_closed
(متوقف نهائيًا) هي علامة منطقية تشير إلى ما إذا كان المكان قد تم إغلاقه نهائيًا أم بشكل مؤقت (القيمةtrue
). لا تستخدم السمةpermanently_closed
. بدلاً من ذلك، استخدِمbusiness_status
للاطّلاع على الحالة التشغيلية للأنشطة التجارية.plus_code
(راجِع Open Location Code (رمز الموقع الجغرافي المفتوح) وplus Codes) هو مرجع موقع جغرافي مشفّر، يتم اشتقاقه من إحداثيات خطوط الطول والعرض، ويمثّل مساحة: 1/8, 000 درجة مضروبة في 1/8, 000 درجة من الدرجة (حوالي 14 متر x 14 متر عند خط الاستواء) أو أقل. يمكن استخدام رموز المواقع المفتوحة كبديل لعناوين الشوارع في الأماكن التي لا تتوفر فيها (حيث لا تكون المباني مرقمة أو لا تتم تسمية الشوارع).يتم تنسيق رمز الموقع المفتوح كرمز عام ورمز مركب:
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 ساعة (تتراوح القيم بين 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
، يجب تضمين الإحالة الإضافية في تطبيقك أينما عرضت الصورة.