بحث عن قرب (جديد) يأخذ نوعًا واحدًا أو أكثر من الأماكن، ويعرض قائمة بالأماكن المطابقة داخل المنطقة المحددة. قناع حقل يحدد نوع بيانات واحدًا أو أكثر مطلوبة. لا يتوافق البحث عن قرب (جديد) إلا مع طلبات 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.types
,places.utcOffsetMinutes
,places.viewport
* يحتوي الحقلplaces.name
على المكان اسم المورد بالشكل: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 } }
المعلمات الاختيارية
-
includeTypes/excludedTypes, includePrimaryTypes/excludedPrimaryTypes
للسماح لك بتحديد قائمة بأنواع البيانات من الأنواع الجدول أ المستخدَم لفلترة البيانات نتائج البحث. يمكن تحديد ما يصل إلى 50 نوعًا في كل فئة من فئات القيود.
لا يمكن أن يحتوي المكان إلا على نوع أساسي واحد من الأنواع. الجدول أ المرتبط بها. على سبيل المثال، قد يكون النوع الأساسي
"mexican_restaurant"
أو"steak_house"
استخدامincludedPrimaryTypes
وexcludedPrimaryTypes
لفلترة النتائج على النوع الأساسي للمكان.يمكن أن يحتوي المكان أيضًا على قيم أنواع متعددة من الأنواع الجدول (أ) المرتبطة بها. على سبيل المثال، قد تكون أنواع المطاعم ما يلي:
"seafood_restaurant"
،"restaurant"
،"food"
،"point_of_interest"
،"establishment"
. استخدام "includedTypes
" وexcludedTypes
لفلترة النتائج على قائمة الأنواع المرتبطة مكان.عندما تحدد نوعًا أساسيًا عامًا، مثل
"restaurant"
أو"hotel"
، يمكن أن يحتوي الرد على أماكن من نوع أساسي أكثر تحديدًا من المحدد. على سبيل المثال، يمكنك تحديد تضمين نوع أساسي من"restaurant"
يمكن أن يحتوي الرد بعد ذلك على أماكن من النوع الأساسي"restaurant"
، ولكن يمكن أن يحتوي الردّ أيضًا على أماكن ذات وصف أكثر تحديدًا النوع الأساسي، مثل"chinese_restaurant"
أو"seafood_restaurant"
.إذا تم تحديد عملية بحث مع قيود أنواع متعددة، يتم فقط تحديد الأماكن التي تفي بجميع القيود يتم إرجاعها. على سبيل المثال، إذا حددت
{"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
إلى قناع الحقل. - يمكنك تعديل نص الطلب اختياريًا.
- انقر على الزر تنفيذ. في النافذة المنبثقة، اختَر الحساب الذي تريد استخدامه لتقديم الطلب.
في لوحة "مستكشف واجهة برمجة التطبيقات"، حدد رمز التوسيع،
، لتوسيع نافذة مستكشف واجهة برمجة التطبيقات