يستخدم طلب البحث عن قرب (جديد) نوعًا واحدًا أو أكثر من الأماكن، ويعرض قائمة بالأماكن المطابقة داخل المنطقة المحدّدة. مطلوب قناع حقل يحدد نوع بيانات واحدًا أو أكثر. لا يتوافق البحث عن قرب (جديد) إلا مع طلبات 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.attributions
،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.name
places.types
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.reviews
،places.servesBeer
،places.servesBreakfast
places.servesBrunch
places.servesCocktails
places.servesCoffee
places.servesDessert
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 } }
المعلمات الاختيارية
-
SharedTypes/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
على قناع الحقل. - يمكنك تعديل نص الطلب اختياريًا.
- انقر على الزر تنفيذ. في النافذة المنبثقة، اختَر الحساب الذي تريد استخدامه لتقديم الطلب.
في لوحة "مستكشف واجهات برمجة التطبيقات"، انقر على رمز التوسيع، ، لتوسيع نافذة "مستكشف واجهة برمجة التطبيقات".