نظرة عامة
تتيح دوال "مكتبة الأماكن" و"واجهة برمجة التطبيقات JavaScript" في "خرائط Google" لتطبيقك البحث عن الأماكن (المحدَّدة في واجهة برمجة التطبيقات هذه باعتبارها مؤسسات، أو مواقع جغرافية، أو نقاط اهتمام بارزة) داخل منطقة معيّنة، مثل حدود الخريطة أو حول نقطة ثابتة.
توفّر واجهة برمجة تطبيقات الأماكن ميزة إكمال تلقائي يمكنك استخدامها لمنح مستخدميك إمكانية البحث المسبق عن نوع المحتوى في حقل البحث في "خرائط Google". عندما يبدأ المستخدم في كتابة عنوان، سيتم ملء الإكمال التلقائي الباقي. ولمزيد من المعلومات، يمكنك الاطّلاع على مستندات الإكمال التلقائي.
البدء
إذا لم تكن على دراية بواجهة برمجة تطبيقات JavaScript للخرائط أو باستخدام JavaScript، ننصحك بمراجعة JavaScript والحصول على مفتاح واجهة برمجة تطبيقات قبل البدء.
تفعيل واجهات برمجة التطبيقات
قبل استخدام مكتبة "الأماكن" في واجهة برمجة تطبيقات JavaScript لخدمة "خرائط Google"، تأكّد أولاً من تفعيل واجهة برمجة تطبيقات الأماكن في Google Cloud Console، وذلك في المشروع نفسه الذي أعددته لواجهة برمجة تطبيقات JavaScript للخرائط.
لعرض قائمة بواجهات برمجة التطبيقات المفعّلة:
- انتقِل إلى Google Cloud Console.
- انقر على الزر اختيار مشروع، ثم اختَر المشروع نفسه الذي أعددته لواجهة برمجة تطبيقات JavaScript لتطبيق "خرائط Google" وانقر على فتح.
- من قائمة واجهات برمجة التطبيقات في لوحة البيانات، ابحث عن واجهة برمجة تطبيقات الأماكن.
- إذا ظهرت لك واجهة برمجة تطبيقات الأماكن في القائمة، يعني هذا أنه تم تفعيلها من قبل. إذا لم يتم إدراج واجهة برمجة التطبيقات، عليك تفعيلها:
- في أعلى الصفحة، انقر على تفعيل واجهات برمجة التطبيقات والخدمات لعرض علامة التبويب المكتبة. بدلاً من ذلك، اختَر المكتبة في القائمة اليمنى.
- ابحث عن PLACES API، ثم اختَرها من قائمة النتائج.
- انقر على تفعيل. عند انتهاء العملية، تظهر واجهة برمجة تطبيقات الأماكن في قائمة واجهات برمجة التطبيقات في لوحة البيانات.
جارٍ تحميل المكتبة
خدمة الأماكن هي مكتبة مستقلة، منفصلة عن رمز واجهة برمجة تطبيقات JavaScript للخرائط. لاستخدام الوظائف المضمّنة
في هذه المكتبة، عليك أولاً تحميلها باستخدام المعلَمة libraries
في عنوان URL للتشغيل مع "خرائط Google":
<script async
src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places&callback=initMap">
</script>
راجِع نظرة عامة على المكتبات للحصول على مزيد من المعلومات.
إضافة الأماكن في واجهة برمجة التطبيقات إلى قائمة قيود واجهة برمجة التطبيقات لمفتاح واجهة برمجة التطبيقات
يؤدي فرض قيود واجهة برمجة التطبيقات على مفاتيحك إلى الحد من استخدام مفتاح واجهة برمجة التطبيقات لواحدة أو أكثر من واجهات برمجة التطبيقات أو حِزم تطوير البرامج (SDK). ستتم معالجة الطلبات المرسَلة إلى واجهة برمجة تطبيقات أو حزمة تطوير برامج (SDK) مرتبطة بمفتاح واجهة برمجة التطبيقات. سيتعذّر إرسال الطلبات إلى واجهة برمجة تطبيقات أو حزمة تطوير برامج (SDK) غير مرتبطة بمفتاح واجهة برمجة التطبيقات. لتقييد استخدام مفتاح واجهة برمجة التطبيقات مع "مكتبة الأماكن"، يُرجى اتّباع الخطوات التالية:- انتقِل إلى Google Cloud Console.
- انقر على القائمة المنسدلة للمشروع واختَر المشروع الذي يحتوي على مفتاح واجهة برمجة التطبيقات الذي تريد تأمينه.
- انقر على زر القائمة
واختر منصة خرائط Google > بيانات الاعتماد.
- في صفحة بيانات الاعتماد، انقر على اسم مفتاح واجهة برمجة التطبيقات الذي تريد تأمينه.
- في صفحة تقييد مفتاح واجهة برمجة التطبيقات وإعادة تسميته، اضبط القيود:
- قيود واجهة برمجة التطبيقات
- انقر على تقييد المفتاح.
- انقر على اختيار واجهات برمجة التطبيقات، واختَر واجهة برمجة تطبيقات JavaScript للخرائط وواجهة برمجة تطبيقات الأماكن.
(إذا لم يكن أيٌّ من واجهات برمجة التطبيقات مدرجًا، عليك تفعيله.)
- انقر على حفظ.
الحدود القصوى للاستخدام وسياسات الاستخدام
الحصص
تشارك "مكتبة الأماكن" حصة استخدام مع "واجهة برمجة تطبيقات الأماكن" كما هو موضّح في مستندات "حدود الاستخدام" الخاصة بـ "واجهة برمجة تطبيقات الأماكن".
السياسات
يجب أن يتوافق استخدام "مكتبة الأماكن" مع واجهة برمجة تطبيقات JavaScript لخدمة "خرائط Google"، وذلك وفقًا للسياسات الموضّحة في واجهة برمجة تطبيقات الأماكن.
عمليات البحث عن الأماكن
باستخدام خدمة الأماكن، يمكنك إجراء الأنواع التالية من عمليات البحث:
- تعرض العثور على مكان من طلب البحث مكانًا استنادًا إلى طلب بحث نصي (على سبيل المثال، اسم مكان أو عنوانه).
- يعرض البحث عن مكان من رقم الهاتف مكانًا استنادًا إلى رقم هاتف.
- تعرض ميزة البحث عن أماكن قريبة قائمة بالأماكن المجاورة استنادًا إلى الموقع الجغرافي للمستخدم.
- تعرض ميزة البحث النصي قائمة بالأماكن المجاورة استنادًا إلى سلسلة بحث، على سبيل المثال. "بيتزا"
- تعرض طلبات تفاصيل المكان معلومات أكثر تفصيلاً عن مكان محدّد، بما في ذلك مراجعات المستخدمين.
ويمكن أن تشمل المعلومات التي يتم عرضها مؤسسات، مثل المطاعم والمتاجر والمكاتب، بالإضافة إلى نتائج "ترميز المواقع الجغرافية" التي تشير إلى العناوين والمناطق السياسية، مثل البلدات والمدن، وغيرها من نقاط الاهتمام.
البحث عن طلبات المكان
يتيح لك طلب البحث عن مكان البحث عن مكان ما إما من خلال طلب البحث النصي أو رقم الهاتف. هناك نوعان من طلبات "البحث عن مكان":
البحث عن مكان من طلب البحث
البحث عن مكان من طلب البحث يُدخل إدخالاً نصيًا ويعرض مكانًا يمكن أن يكون الإدخال أي نوع من بيانات المكان، مثل اسم نشاط تجاري أو عنوانه. لإنشاء طلب "بحث عن مكان من طلب بحث"، اطلب طريقة PlacesService
findPlaceFromQuery()
التي تتطلب المعلمات التالية:
query
(مطلوبة) هي السلسلة النصية التي يمكن البحث عنها، على سبيل المثال: "مطعم" أو "123 الشارع الرئيسي". يجب أن يكون هذا الاسم اسم مكان أو عنوانها أو فئةها. يمكن أن تؤدي أي أنواع أخرى من الإدخالات إلى حدوث أخطاء، ولا يمكن ضمان عرض نتائج صالحة. وستعرض الأماكن API المطابقات للمرشحين استنادًا إلى هذه السلسلة وترتّب النتائج استنادًا إلى مدى صلتها بالموضوع.fields
(مطلوب) حقل أو أكثر من الحقول التي تحدّد أنواع بيانات المكان التي يتم عرضها.locationBias
(اختياري) الإحداثيات التي تحدّد المنطقة المطلوب البحث فيها. يمكن أن يكون واحدًا مما يلي:- مجموعة من إحداثيات خط العرض/الخطبة المحدَّدة على أنها LatLngLiteral أو كائن LatLNG
- حدود مستطيلة (زوجان من خطوط العرض/الخط الطول أو كائن LatLNGBounds)
- نصف القُطر (بالمتر) المرتكز على خط العرض/lg
عليك أيضًا تمرير طريقة معاودة الاتصال إلى findPlaceFromQuery()
،
لمعالجة كائن النتائج والردّ على
google.maps.places.PlacesServiceStatus
.
يوضّح المثال التالي مكالمة إلى findPlaceFromQuery()
والبحث عن "متحف الفن المعاصر في أستراليا"، بما في ذلك الحقلين name
وgeometry
.
var map; var service; var infowindow; function initMap() { var sydney = new google.maps.LatLng(-33.867, 151.195); infowindow = new google.maps.InfoWindow(); map = new google.maps.Map( document.getElementById('map'), {center: sydney, zoom: 15}); var request = { query: 'Museum of Contemporary Art Australia', fields: ['name', 'geometry'], }; var service = new google.maps.places.PlacesService(map); service.findPlaceFromQuery(request, function(results, status) { if (status === google.maps.places.PlacesServiceStatus.OK) { for (var i = 0; i < results.length; i++) { createMarker(results[i]); } map.setCenter(results[0].geometry.location); } }); }الاطّلاع على مثال
البحث عن مكان من رقم الهاتف
تعثر خدمة "العثور على المكان" من "رقم الهاتف" على رقم الهاتف وتعرض المكان. لإنشاء طلب "العثور على مكان من رقم الهاتف"، يمكنك استدعاء طريقة findPlaceFromPhoneNumber()
الخاصة بـ PlacesService
، والتي تتطلب المعلمات التالية:
phoneNumber
(مطلوبة) رقم هاتف بتنسيق E.164fields
(مطلوب) حقل أو أكثر من الحقول التي تحدّد أنواع بيانات المكان التي يتم عرضها.locationBias
(اختيارية) الإحداثيات التي تحدّد المنطقة للبحث. يمكن أن يكون واحدًا مما يلي:- مجموعة من إحداثيات خط العرض/الخطبة المحدَّدة على أنها LatLngLiteral أو كائن LatLNG
- حدود مستطيلة (أربعة نقاط خط طول/خط كبير، أو كائن LatLNGBounds)
- نصف القُطر (بالمتر) المرتكز على خط العرض/lg
عليك أيضًا تمرير طريقة معاودة الاتصال إلى 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}
يمكنك أيضًا استخدام LatLungBounds.
حدّد نطاقًا جغرافيًا للبحث (بالمتر). يتم التركيز فيه على منطقة معيّنة:
locationBias: {radius: 100, center: {lat: 37.402105, lng: -122.081974}}
طلبات البحث القريبة
تتيح لك ميزة "البحث عن قرب" إمكانية البحث عن أماكن داخل منطقة محدّدة حسب الكلمة الرئيسية أو النوع. يجب أن تحتوي ميزة "البحث عن مكان قريب" دائمًا على موقع جغرافي يمكن تحديده بإحدى الطريقتَين التاليتَين:
-
LatLngBounds
. - هي مساحة دائرية يتم تحديدها كتركيبة للسمة
location
، مع تحديد مركز الدائرة كعنصرLatLng
، والنطاق الجغرافي، الذي يتم قياسه بالأمتار.
يبدأ البحث عن الأماكن المجاورة باستدعاء طريقة
PlacesService
nearbySearch()
التي تعرض
مصفوفة من العناصر
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
يحدد المستطيل الذي يجب البحث فيه، أو- a
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
: لا يُسمح لصفحة الويب باستخدام خدمة ServiceService.UNKNOWN_ERROR
: تعذّرت معالجة طلب الأماكن في الخدمة بسبب خطأ في الخادم. قد تتم معالجة الطلب بنجاح في حال إعادة المحاولة.ZERO_RESULTS
: لم يتمّ العثور على نتائج لهذا الطلب.
نتائج البحث عن الأماكن
تعرض الدوال findPlace()
وnearbySearch()
وtextSearch()
صفيفًا من
PlaceResult
.
قد يتضمّن كل كائن PlaceResult
السمات التالية:
- تشير السمة
business_status
إلى الحالة التشغيلية للمكان، إذا كان نشاطًا تجاريًا. يمكن أن تتضمّن إحدى القيم التالية:OPERATIONAL
CLOSED_TEMPORARILY
CLOSED_PERMANENTLY
business_status
. formatted_address
هي سلسلة تحتوي على العنوان الجغرافي القابل للقراءة لهذا المكان. لا يتم عرض السمةformatted_address
سوى للبحث النصي.غالبًا ما يعادل هذا العنوان العنوان البريدي. لاحِظ أن بعض البلدان، مثل المملكة المتحدة، لا تسمح بتوزيع العناوين البريدية الصحيحة بسبب قيود الترخيص.
يتكون العنوان المنسّق بشكل منطقي من واحد أو أكثر من مكوّنات العنوان. على سبيل المثال، يتألف العنوان "111 شارع 8، نيويورك، نيويورك" من المكوّنات التالية: "111" (رقم الشارع)، و"شارع 8" (المسار) و"نيويورك" (المدينة) و "نيويورك" (ولاية الولايات المتحدة).
لا يمكنك تحليل العنوان الذي تم تنسيقه آليًا. وبدلاً من ذلك، عليك استخدام مكوّنات العنوان الفردي التي تتضمّنها استجابة واجهة برمجة التطبيقات بالإضافة إلى حقل العنوان المنسَّق.
geometry
: المعلومات المتعلقة بهندسية المكان ويشمل ذلك:- تعرض السمة
location
خط العرض وخط الطول للمكان. - يحدِّد
viewport
إطار العرض المفضّل على الخريطة عند عرض هذا المكان.
- تعرض السمة
permanently_closed
(متوقّفة نهائيًا) هي علامة منطقية تشير إلى ما إذا كان المكان قد تمّ إيقافه نهائيًا أو بشكل مؤقت (القيمةtrue
). لا تستخدمpermanently_closed
. بدلاً من ذلك، يمكنك استخدامbusiness_status
للاطّلاع على الحالة التشغيلية للأنشطة التجارية.plus_code
(اطّلِع على رمز الموقع الجغرافي المفتوح ورموز Plus Codes) هو مرجع الموقع الجغرافي المُشفَّر الذي يشتق من إحداثيات خطوط الطول والعرض، ويمثِّل منطقة: 1/8000 درجة من الدرجة بمقدار 1/8000 درجة من الدرجة (حوالي 14 × 14 متر في خط الاستواء) أو أصغر. يمكن استخدام رموز Plus Codes لاستبدال عناوين الشوارع في الأماكن التي لا تتوفّر فيها (حيث لا تكون المباني مرقّمة أو لا تتم تسمية الشوارع بها).يتم تنسيق رمز Plus Codes كرمز عام ورمز مركّب:
global_code
هو رمز منطقة مكوّن من 4 أحرف ورمز محلي مكوّن من 6 أحرف أو أكثر (849VCWC8+R9).compound_code
عبارة عن رمز محلي يتألف من 6 أحرف أو أكثر ويتضمّن موقعًا جغرافيًا فاضحًا (CWC8+R9 و Mountain View وCA وUSA). لا يجوز تحليل هذا المحتوى آليًا.
html_attributions
: مصفوفة من الإحالات التي يجب عرضها عند عرض نتائج البحث. يحتوي كل إدخال في المصفوفة على نص HTML لتحديد مصدر واحد. ملاحظة: يتضمن هذا التقرير تجميعًا كاملاً لكل عمليات تحديد المصدر في استجابة البحث بالكامل. وبالتالي، تحتوي جميع عناصرPlaceResult
في الاستجابة على قوائم إحالة متطابقة.- يعرض
icon
عنوان URL لرمز ملوّن 71 × 71 بكسل بتنسيق PNG. - تعرض
icon_mask_base_uri
عنوان URL الأساسي لرمز غير ملوّن، باستثناء الإضافة .svg أو .png. - تعرض
icon_background_color
رمز لون HEX التلقائي لفئة المكان. 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
تتوافق الحقول مع نتائج
تفاصيل المكان، وتنقسم إلى ثلاث فئات فوترة: "أساسي" و"جهة اتصال" و"الأجواء". يتم إصدار فواتير للحقول الأساسية بالسعر الأساسي، بدون أي رسوم إضافية. يتم تحصيل الرسوم من حقلَي "جهة الاتصال" و"الأجواء" بمعدّل أعلى. اطّلِع على ورقة الأسعار
للحصول على مزيد من المعلومات. تُعرَض دائمًا الإحالات (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
(0}}الإصدار الثاني
}}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
: لا يُسمح لصفحة الويب باستخدام خدمة ServiceService.UNKNOWN_ERROR
: تعذّرت معالجة طلب الأماكن في الخدمة بسبب خطأ في الخادم. قد تتم معالجة الطلب بنجاح في حال إعادة المحاولة.ZERO_RESULTS
: لم يتمّ العثور على نتائج لهذا الطلب.
نتائج التفاصيل حول المكان
تعرض استدعاء getDetails()
الناجح
عنصر
PlaceResult
مع السمات التالية:
address_components
: مصفوفة تحتوي على المكوّنات المنفصلة الملائمة لهذا العنوان.يحتوي كل مكوِّن عنوان عادةً على الحقول التالية:
types[]
هي مصفوفة تشير إلى type لمكوّن العنوان. اطّلِع على قائمة الأنواع المتوافقة.long_name
هي الوصف النصي الكامل أو اسم مكوّن العنوان كما هو وارد في برنامج Geocoder.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 شارع 8، نيويورك، نيويورك" من المكوّنات التالية: "111" (رقم الشارع)، و"شارع 8" (المسار) و"نيويورك" (المدينة) و "نيويورك" (ولاية الولايات المتحدة).
لا يمكنك تحليل العنوان الذي تم تنسيقه آليًا. وبدلاً من ذلك، عليك استخدام مكوّنات العنوان الفردي التي تتضمّنها استجابة واجهة برمجة التطبيقات بالإضافة إلى حقل العنوان المنسَّق.
formatted_phone_number
: رقم هاتف المكان، مُنسَّق وفقًا للاتفاقية الإقليمية الخاصة بالرقمgeometry
: المعلومات المتعلقة بهندسية المكان ويشمل ذلك:- تعرض السمة
location
خط العرض وخط الطول للمكان. - يحدِّد
viewport
إطار العرض المفضّل على الخريطة عند عرض هذا المكان.
- تعرض السمة
permanently_closed
(متوقّفة نهائيًا) هي علامة منطقية تشير إلى ما إذا كان المكان قد تمّ إيقافه نهائيًا أو بشكل مؤقت (القيمةtrue
). لا تستخدمpermanently_closed
. بدلاً من ذلك، يمكنك استخدامbusiness_status
للاطّلاع على الحالة التشغيلية للأنشطة التجارية.plus_code
(اطّلِع على رمز الموقع الجغرافي المفتوح ورموز Plus Codes) هو مرجع الموقع الجغرافي المُشفَّر الذي يشتق من إحداثيات خطوط الطول والعرض، ويمثِّل منطقة: 1/8000 درجة من الدرجة بمقدار 1/8000 درجة من الدرجة (حوالي 14 × 14 متر في خط الاستواء) أو أصغر. يمكن استخدام رموز Plus Codes لاستبدال عناوين الشوارع في الأماكن التي لا تتوفّر فيها (حيث لا تكون المباني مرقّمة أو لا تتم تسمية الشوارع بها).يتم تنسيق رمز Plus Codes كرمز عام ورمز مركّب:
global_code
هو رمز منطقة مكوّن من 4 أحرف ورمز محلي مكوّن من 6 أحرف أو أكثر (849VCWC8+R9).compound_code
عبارة عن رمز محلي يتألف من 6 أحرف أو أكثر ويتضمّن موقعًا جغرافيًا فاضحًا (CWC8+R9 و Mountain View وCA وUSA). لا يجوز تحليل هذا المحتوى آليًا.
html_attributions
: نص الإحالة الذي سيتم عرضه لنتائج هذه المكانicon
: عنوان URL إلى مورد صورة يمكن استخدامه لتمثيل نوع هذا المكان.- يحتوي
international_phone_number
على رقم هاتف المكان بالتنسيق الدولي. ويتضمّن التنسيق الدولي رمز البلد، مسبوقًا بعلامة الجمع (+). على سبيل المثال،international_phone_number
في مكتب Google في مدينة سيدني في أستراليا هو+61 2 9374 4000
. name
: اسم المكانutc_offset
متوقّفة نهائيًا في "مكتبة الأماكن" وMaps JavaScript API، استخدِم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
على وقت من اليوم بتنسيق hhmm 24 ساعة (تتراوح القيم بين 0000 و2359). سيتم الإبلاغ عنtime
في المنطقة الزمنية للمكان.
- قد تحتوي السمة
close
على زوج من العناصر اليومية والوقت عند إغلاق المكان. ملاحظة: إذا كان أحد الأماكن مفتوحًا دائمًا، لن يتوفّر القسمclose
في الرد. يمكن أن تعتمد التطبيقات على أن تكون مفتوحة دائمًا كفترةopen
تحتوي علىday
بالقيمة 0 وtime
بالقيمة 0000، وليسclose
.
- تحتوي السمة
- تمثّل السمة
weekday_text
مصفوفة من سبعة سلاسل تمثّل ساعات العمل المنسّقة لكل يوم من أيام الأسبوع. إذا تم تحديد مَعلمةlanguage
في طلب تفاصيل المكان، ستعمل خدمة "الأماكن" على تنسيق ساعات العمل وترجمتها على نحو مناسب لتلك اللغة. ويعتمد ترتيب العناصر في هذه المصفوفة على المعلَمةlanguage
. وبعض اللغات تبدأ الأسبوع يوم الاثنين بينما تبدأ اللغات الأخرى يوم الأحد.
permanently_closed
(متوقّفة نهائيًا) هي علامة منطقية تشير إلى ما إذا كان المكان قد تمّ إيقافه نهائيًا أو بشكل مؤقت (القيمةtrue
). لا تستخدمpermanently_closed
. بدلاً من ذلك، يمكنك استخدامbusiness_status
للاطّلاع على الحالة التشغيلية للأنشطة التجارية.photos[]
: مصفوفة منPlacePhoto
عنصر. ويمكن استخدام السمةPlacePhoto
للحصول على صورة باستخدام الطريقةgetUrl()
، أو يمكنك فحص العنصر بحثًا عن القيم التالية:height
: الحد الأقصى لطول الصورة بالبكسل.width
: الحد الأقصى لعرض الصورة بالبكسل.html_attributions
: نص الإحالة الذي سيتم عرضه مع صورة هذا المكان.
place_id
: معرِّف نصي يحدِّد مكانًا فريدًا ويمكن استخدامه لاسترداد المعلومات عن المكان من خلال طلب تفاصيل المكان. اطّلِع على مزيد من المعلومات حول كيفية الإشارة إلى مكان باستخدام رقم تعريف المكان.rating
: تقييم المكان من 0.0 إلى 5.0، استنادًا إلى مراجعات المستخدمين المجمّعةreviews
مصفوفة من خمس مراجعات كحد أقصى. تتكوّن كل مراجعة من عدة مكوّنات:- يحتوي الحقل
aspects[]
على صفيف منPlaceAspectRating
عنصر، يقدّم كل منها تقييمًا لسمة واحدة من المبنى. ويُعتبر العنصر الأول في المصفوفة السمة الأساسية. يتم تعريف كلPlaceAspectRating
على النحو التالي:type
اسم الجانب الذي يتم تقييمه. تتوفّر الأنواع التالية:appeal
وatmosphere
وdecor
وfacilities
وfood
وoverall
وquality
وservice
.rating
تمثّل هذه السمة تقييم المستخدم لهذا الجانب بالتحديد، من 0 إلى 3.
author_name
اسم المستخدم الذي أرسل المراجعة. وتُنسب المراجعات المجهولة المصدر إلى "مستخدم Google". في حال ضبط معلَمة لغة، ستعرض العبارة "مستخدم Google" سلسلة مترجَمة.author_url
عنوان URL الذي ينقل إلى الملف الشخصي للمستخدمين في Google+ ، في حال توفّره.language
رمز لغة مجموعة مهندسي شبكة الإنترنت (IETF) يشير إلى اللغة المستخدمة في مراجعة المستخدم. يحتوي هذا الحقل على علامة اللغة الرئيسية فقط، وليس العلامة الثانوية التي تشير إلى البلد أو المنطقة. على سبيل المثال، تم وضع علامة على جميع المراجعات باللغة الإنجليزية على أنّها "en"، وليس "en-AU" أو "en-UK" وما إلى ذلك.rating
هو التقييم العام للمستخدم لهذا المكان. هذا عدد صحيح يتراوح بين 1 و5.text
: مراجعة المستخدم وعند مراجعة أحد المواقع الجغرافية في "أماكن Google"، تُعتبر المراجعات النصية اختيارية، وبالتالي قد يكون هذا الحقل فارغًا.
- يحتوي الحقل
types
مصفوفة من الأنواع لهذا المكان (على سبيل المثال،["political", "locality"]
أو["restaurant", "lodging"]
: قد تحتوي هذه المصفوفة على قيم متعدّدة، أو قد تكون فارغة. قد يتم تقديم قيم جديدة بدون إشعار مسبق. اطّلِع على قائمة الأنواع المتوافقة.url
: عنوان URL لصفحة Google الرسمية لهذا المكان. هذه هي الصفحة التي تملكها Google وتحتوي على أفضل المعلومات المتاحة حول المكان. يجب أن تتضمّن التطبيقات رابطًا أو يؤدي إلى هذه الصفحة على أي شاشة تعرض نتائج تفصيلية حول المكان للمستخدم.vicinity
: عنوان مبسّط للمكان، بما في ذلك اسم الشارع ورقمه ومنطقته المحلية، ولكن ليس المقاطعة/الولاية أو الرمز البريدي أو البلد على سبيل المثال، لدى مكتب Google في "سيدني"، قيمةvicinity
هي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}) }); }
يتم الحصول على الصور التي تعرضها خدمة "صور Google" من مجموعة متنوعة من
المواقع الجغرافية، بما في ذلك مالكو الأنشطة التجارية والصور التي يساهم بها المستخدمون. وفي معظم الحالات، يمكن استخدام هذه الصور بدون إحالة أو سيتم تضمين الإحالة المطلوبة كجزء من الصورة. أما إذا كان العنصر photo
المعروض يتضمن قيمة في الحقل html_attributions
، فيجب تضمين الإسناد الإضافي في تطبيقك حيثما تعرض الصورة.