طلب بحث عن قرب (جديد) يتطلب نوعًا واحدًا أو أكثر من الأماكن، ويعرض قائمة بالأماكن المطابقة داخل المنطقة المحددة. يجب وضع قناع حقل يحدد نوعاً واحدًا أو أكثر من البيانات. ميزة "البحث عن قرب" (ميزة جديدة) تتيح استخدام طلبات POST فقط.
يتيح لك "مستكشف واجهة برمجة التطبيقات" إجراء طلبات مباشرة لتتمكن من الإلمام بواجهة برمجة التطبيقات وخيارات واجهة برمجة التطبيقات:
جرِّبه الآنجرِّب العرض التوضيحي التفاعلي لمشاهدة نتائج البحث عن قرب (جديدة) المعروضة على خريطة.
طلبات البحث عن قرب (جديدة)
طلب البحث عن قرب (جديد) هو طلب HTTP POST إلى عنوان URL بالنموذج:
https://places.googleapis.com/v1/places:searchNearby
مرِّر جميع المعلمات في نص طلب JSON أو في العناوين كجزء من طلب POST. مثال:
curl -X POST -d '{ "includedTypes": ["restaurant"], "maxResultCount": 10, "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965}, "radius": 500.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName" \ https://places.googleapis.com/v1/places:searchNearby
ردود البحث عن قرب (جديدة)
يعرض البحث عن قرب (جديد) كائن JSON كاستجابة. في الرد:
- تحتوي مصفوفة
places
على جميع الأماكن المطابقة. - يتم تمثيل كل مكان في المصفوفة بكائن
Place
. يحتوي الكائنPlace
على معلومات مفصّلة حول مكان واحد. - يحدِّد حقل FieldMask الذي تم تمريره في الطلب قائمة الحقول التي يتم عرضها في الكائن
Place
.
ويكون كائن JSON الكامل على النحو التالي:
{ "places": [ { object (Place) } ] }
المعلمات المطلوبة
-
FieldMask
حدِّد قائمة الحقول المطلوب عرضها في الرد من خلال إنشاء قناع حقل الاستجابة. مرِّر قناع حقل الاستجابة إلى الطريقة باستخدام معلَمة عنوان URL
$fields
أوfields
أو باستخدام عنوان HTTPX-Goog-FieldMask
. ليست هناك قائمة تلقائية بالحقول المعروضة في الاستجابة. إذا حذفت قناع الحقل، ستعرض الطريقة خطأ.يُعدّ إخفاء الحقول ممارسة تصميم جيدة لضمان عدم طلب بيانات غير ضرورية، ما يساعد على تجنّب وقت المعالجة غير الضروري ورسوم الفوترة.
حدد قائمة مفصولة بفواصل لأنواع بيانات الأماكن المطلوب عرضها. على سبيل المثال، لاسترداد الاسم المعروض وعنوان المكان.
X-Goog-FieldMask: places.displayName,places.formattedAddress
استخدِم
*
لاسترداد جميع الحقول.X-Goog-FieldMask: *
حدِّد واحدًا أو أكثر من الحقول التالية:
تؤدي الحقول التالية إلى ظهور رمز التخزين التعريفي للبحث عن قرب (الأساسي):
places.accessibilityOptions
،places.addressComponents
،places.adrFormatAddress
،places.businessStatus
،places.displayName
،places.formattedAddress
،places.googleMapsUri
،places.iconBackgroundColor
،places.iconMaskBaseUri
،places.id
،places.location
،places.name
*،places.photos
،places.plusCode
،places.primaryType
،places.primaryTypeDisplayName
،places.shortFormattedAddress
،places.subDestinations
,places.types
،places.types
،places.types
places.name
places.utcOffsetMinutes
places.viewport
places/PLACE_ID
استخدِمplaces.displayName
للوصول إلى الاسم النصي للمكان.تؤدي الحقول التالية إلى ظهور رمز التخزين التعريفي للبحث عن قرب (متقدم):
places.currentOpeningHours
،places.currentSecondaryOpeningHours
،places.internationalPhoneNumber
،places.nationalPhoneNumber
،places.priceLevel
،places.rating
،places.regularOpeningHours
،places.regularSecondaryOpeningHours
،places.userRatingCount
،places.websiteUri
.تؤدي الحقول التالية إلى ظهور رمز التخزين التعريفي لميزة "البحث عن قرب" (المُفضَّل):
places.allowsDogs
،places.curbsidePickup
،places.delivery
،places.dineIn
،places.editorialSummary
،places.evChargeOptions
،places.fuelOptions
،places.goodForChildren
،places.goodForGroups
،places.goodForWatchingSports
،places.liveMusic
،places.menuForChildren
،places.parkingOptions
،places.paymentOptions
،places.outdoorSeating
،places.reservable
،places.restroom
،places.servesBeer
،places.delivery
،places.servesBeer
،
،places.liveMusic
،places.reviews
places.servesBreakfast
places.servesBrunch
places.servesCocktails
places.servesCoffee
places.servesDesserts
places.servesDinner
places.servesLunch
places.servesVegetarianFood
places.servesWine
places.takeout
-
locationRestriction
المنطقة المطلوب البحث عنها كدائرة، يتم تحديدها بواسطة نقطة المركز ونصف القطر بالمتر. يجب أن يتراوح النطاق الجغرافي بين 0.0 و50000.0، بشكل شامل. النطاق الجغرافي الافتراضي هو 0.0. ويجب ضبطها في طلبك على قيمة أكبر من 0.0.
على سبيل المثال:
"locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 500.0 } }
المعلمات الاختيارية
-
includeTypes/excludedTypes، وincludePrimaryTypes/excludedPrimaryTypes
تتيح لك هذه الميزة تحديد قائمة بأنواع من أنواع الجدول أ المستخدَم لفلترة نتائج البحث. ويمكن تحديد ما يصل إلى 50 نوعًا في كل فئة من فئات القيود المفروضة على الأنواع.
يمكن أن يكون للمكان نوع أساسي واحد من أنواع الجدول أ المرتبطة به. على سبيل المثال، قد يكون النوع الأساسي
"mexican_restaurant"
أو"steak_house"
. استخدِمincludedPrimaryTypes
وexcludedPrimaryTypes
لفلترة النتائج على النوع الأساسي للمكان.يمكن أن يحتوي المكان أيضًا على قيم أنواع متعددة من أنواع الجدول أ المرتبط به. على سبيل المثال، قد يكون لمطعم الأنواع التالية:
"seafood_restaurant"
و"restaurant"
و"food"
و"point_of_interest"
و"establishment"
. يمكنك استخدامincludedTypes
وexcludedTypes
لفلترة النتائج على قائمة الأنواع المرتبطة بمكان معيّن.إذا تم تحديد عملية بحث باستخدام عدة قيود على الأنواع، لن يتم عرض سوى الأماكن التي تستوفي جميع هذه القيود. على سبيل المثال، إذا حدّدت
{"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}
، تقدّم الأماكن التي تم إرجاعها خدمات"restaurant"
ذات الصلة، ولكنها لا تعمل بشكل أساسي بصفتها"steak_house"
.includedTypes
قائمة مفصولة بفواصل بأنواع الأماكن من الجدول أ للبحث عنها. إذا تم حذف هذه المَعلمة، يتم عرض الأماكن من جميع الأنواع.
excludedTypes
قائمة بأنواع الأماكن المفصولة بفواصل من الجدول أ المطلوب استبعادها من البحث.
إذا حدّدت كلاً من
includedTypes
( مثل"school"
) والسمةexcludedTypes
(مثل"primary_school"
) في الطلب، سيشمل الرد أماكن يتم تصنيفها على أنّها"school"
وليس"primary_school"
. يتضمن الرد أماكن تتطابق مع مكان واحد على الأقل منincludedTypes
ولا شيء منexcludedTypes
.في حال وجود أي أنواع متعارضة، مثل ظهور نوع معيّن في كل من
includedTypes
وexcludedTypes
، يتم عرض الخطأINVALID_REQUEST
.includedPrimaryTypes
قائمة بأنواع الأماكن الأساسية مفصولة بفواصل من الجدول أ لتضمينها في البحث.
excludedPrimaryTypes
قائمة بأنواع الأماكن الأساسية مفصولة بفواصل من الجدول أ المطلوب استبعادها من البحث.
وفي حال وجود أي أنواع أساسية متعارضة، مثل ظهور نوع معيّن في كل من
includedPrimaryTypes
وexcludedPrimaryTypes
، يتم عرض الخطأINVALID_ARGUMENT
. -
languageCode
اللغة التي سيتم عرض النتائج بها.
- اطّلِع على قائمة اللغات المعتمَدة. يعدّل محرّك بحث Google غالبًا اللغات المتاحة، لذا قد لا تكون هذه القائمة شاملة.
- وإذا لم يتم توفير
languageCode
، يتم ضبط واجهة برمجة التطبيقات تلقائيًا علىen
. وإذا حدّدت رمزًا غير صالح للغة، ستعرض واجهة برمجة التطبيقات الخطأINVALID_ARGUMENT
. - تبذل واجهة برمجة التطبيقات قصارى جهدها لتوفير عنوان شارع يمكن لكل من المستخدم والمحلي قراءته. ولتحقيق هذا الهدف، يتم عرض عناوين الشوارع باللغة المحلية، وتحويلها صوتيًا إلى نص برمجي يمكن للمستخدم قراءته عند الضرورة، مع مراعاة اللغة المفضَّلة. ويتم عرض جميع العناوين الأخرى باللغة المفضّلة. يتم عرض جميع مكوّنات العنوان باللغة نفسها التي يتم اختيارها من المكوّن الأول.
- وإذا لم يكن الاسم متاحًا باللغة المفضّلة، ستستخدم واجهة برمجة التطبيقات أقرب تطابق.
- تؤثر اللغة المفضّلة بشكل طفيف في مجموعة النتائج التي تختار واجهة برمجة التطبيقات عرضها وترتيب عرضها. ويفسّر أداة الترميز الجغرافي الاختصارات بشكل مختلف حسب اللغة، مثل اختصارات أنواع الشوارع أو المرادفات التي قد تكون صالحة بلغة معيّنة وليس بلغة أخرى.
-
maxResultCount
تحدّد هذه السمة الحد الأقصى لعدد نتائج الأماكن المطلوب عرضها. ويجب أن تتراوح القيمة بين 1 و20 (الخيار التلقائي).
-
rankPreference
تمثّل هذه السمة نوع الترتيب المطلوب استخدامه. إذا تم حذف هذه المَعلمة، يتم ترتيب النتائج حسب مدى رواجها. يمكن أن يكون أحد الأنواع التالية:
POPULARITY
(الخيار التلقائي) لترتيب النتائج استنادًا إلى مدى رواجها.- يتيح لك الخيار
DISTANCE
ترتيب النتائج تصاعديًا حسب بُعدها عن الموقع الجغرافي المحدّد.
-
regionCode
تمثّل هذه السمة رمز المنطقة المستخدَم لتنسيق الردّ، ويتم تحديده كقيمة لرمز CLDR مكوَّن من حرفين. لا تتوفّر قيمة تلقائية.
وإذا كان اسم البلد في الحقل
formattedAddress
في الردّ يتطابق معregionCode
، سيتم حذف رمز البلد منformattedAddress
. ليس لهذه المَعلمة أي تأثير علىadrFormatAddress
، الذي يتضمّن دائمًا اسم البلد، أو علىshortFormattedAddress
الذي لا يتضمّنه مطلقًا.وتكون معظم رموز CLDR متطابقة مع رموز ISO 3166-1، مع بعض الاستثناءات الملحوظة. على سبيل المثال، نطاق المستوى الأعلى الذي يتم ترميزه حسب البلد (ccTLD) في المملكة المتحدة هو "uk" (.co.uk)، في حين أنّ رمز ISO 3166-1 هو "gb" (من الناحية الفنية لكيان "المملكة المتحدة لبريطانيا العظمى وأيرلندا الشمالية"). يمكن أن تؤثر المَعلمة في النتائج استنادًا إلى القانون الساري.
أمثلة على البحث عن أماكن قريبة (جديدة)
العثور على أماكن من نوع واحد
يوضح المثال التالي طلب بحث عن قرب (جديد) للأسماء المعروضة
لجميع المطاعم ضمن نطاق جغرافي قدره 500 متر، والذي تم تحديده بواسطة circle
:
curl -X POST -d '{ "includedTypes": ["restaurant"], "maxResultCount": 10, "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965}, "radius": 500.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName" \ https://places.googleapis.com/v1/places:searchNearby
يُرجى العِلم أنّ عنوان X-Goog-FieldMask
يوضِّح أنّ الاستجابة تحتوي على حقول البيانات التالية: places.displayName
.
تكون الرد
بعد ذلك في النموذج:
{ "places": [ { "displayName": { "text": "La Mar Cocina Peruana", "languageCode": "en" } }, { "displayName": { "text": "Kokkari Estiatorio", "languageCode": "en" } }, { "displayName": { "text": "Harborview Restaurant & Bar", "languageCode": "en" } }, ... }
أضِف المزيد من أنواع البيانات إلى قناع الحقل لعرض معلومات إضافية.
على سبيل المثال، يمكنك إضافة places.formattedAddress,places.types,places.websiteUri
لتضمين
عنوان المطعم ونوعه وعنوان الويب في الرد:
curl -X POST -d '{ "includedTypes": ["restaurant"], "maxResultCount": 10, "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965}, "radius": 500.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName,places.formattedAddress,places.types,places.websiteUri" \ https://places.googleapis.com/v1/places:searchNearby
أصبح الرد الآن في النموذج:
{ "places": [ { "types": [ "seafood_restaurant", "restaurant", "food", "point_of_interest", "establishment" ], "formattedAddress": "PIER 1 1/2 The Embarcadero N, San Francisco, CA 94105, USA", "websiteUri": "http://lamarsf.com/", "displayName": { "text": "La Mar Cocina Peruana", "languageCode": "en" } }, { "types": [ "greek_restaurant", "meal_takeaway", "restaurant", "food", "point_of_interest", "establishment" ], "formattedAddress": "200 Jackson St, San Francisco, CA 94111, USA", "websiteUri": "https://kokkari.com/", "displayName": { "text": "Kokkari Estiatorio", "languageCode": "en" } }, ... }
العثور على أماكن من أنواع متعددة
يوضح المثال التالي طلب بحث عن قرب (جديد) للأسماء المعروضة
لجميع المتاجر الصغيرة ومتاجر الخمور ضمن نصف قطر يبلغ 1000 متر من
circle
المحدد:
curl -X POST -d '{ "includedTypes": ["liquor_store", "convenience_store"], "maxResultCount": 10, "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 1000.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName,places.primaryType,places.types" \ https://places.googleapis.com/v1/places:searchNearbyيضيف هذا المثال
places.primaryType
وplaces.types
إلى قناع الحقل بحيث يتضمن الرد معلومات النوع حول كل مكان، ويسهل اختيار المكان المناسب من النتائج.
استبعاد نوع مكان من عملية بحث
يوضح المثال التالي طلب بحث عن قرب (جديد) لجميع الأماكن
من النوع "school"
، باستثناء جميع الأماكن من النوع "primary_school"
، مع ترتيب النتائج
حسب المسافة:
curl -X POST -d '{ "includedTypes": ["school"], "excludedTypes": ["primary_school"], "maxResultCount": 10, "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 1000.0 } }, "rankPreference": "DISTANCE" }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName" \ https://places.googleapis.com/v1/places:searchNearby
البحث عن جميع الأماكن بالقرب من منطقة ما، مع ترتيبها حسب المسافة
يوضح المثال التالي طلب بحث عن قرب (جديد) لأماكن بالقرب من نقطة ما في وسط مدينة سان فرانسيسكو. في هذا المثال، يمكنك تضمين المعلمة rankPreference
لترتيب النتائج حسب المسافة:
curl -X POST -d '{ "maxResultCount": 10, "rankPreference": "DISTANCE", "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 1000.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName" \ https://places.googleapis.com/v1/places:searchNearby
تجربة
يتيح لك "مستكشف واجهة برمجة التطبيقات" تقديم طلبات نموذجية حتى تتمكّن من التعرّف على خيارات واجهة برمجة التطبيقات وواجهة برمجة التطبيقات
- انقر على رمز واجهة برمجة التطبيقات على الجانب الأيسر من الصفحة.
- يمكنك اختياريًا توسيع قسم عرض المَعلمات العادية وضبط المَعلمة
fields
على قناع الحقل. - يمكنك اختياريًا تعديل نص الطلب.
- انقر على الزر تنفيذ. في النافذة المنبثقة، اختَر الحساب الذي تريد استخدامه لتقديم الطلب.
في لوحة "مستكشف واجهة برمجة التطبيقات"، انقر على رمز التوسيع، ، لتوسيع نافذة "مستكشف واجهة برمجة التطبيقات".