تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

البحث عن قرب (جديد)

اختيار النظام الأساسي: Android iOS JavaScript خدمة الويب

يستخدم طلب البحث عن قرب (جديد) نوعًا واحدًا أو أكثر من الأماكن، ويعرض قائمة بالأماكن المطابقة داخل المنطقة المحدّدة. مطلوب قناع حقل يحدد نوع بيانات واحدًا أو أكثر. لا يتوافق البحث عن قرب (جديد) إلا مع طلبات 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، أو باستخدام عنوان HTTP X-Goog-FieldMask. لا تتوفّر قائمة تلقائية للحقول التي تم إرجاعها في الردّ. إذا حذفت قناع الحقل، فستُرجع الطريقة خطأ.

يُعتبر إخفاء الحقل من الممارسات الجيدة للتصميم لضمان عدم طلب بيانات غير ضرورية، ما يساعد في تجنّب وقت المعالجة ورسوم الفوترة غير الضرورية.

حدِّد قائمة مفصولة بفواصل لأنواع بيانات الأماكن المطلوب عرضها. على سبيل المثال، لاسترداد الاسم المعروض وعنوان المكان.
```
X-Goog-FieldMask: places.displayName,places.formattedAddress
```
ملاحظة: لا يُسمح باستخدام المسافات في أي مكان في قائمة الحقول.

استخدِم * لاسترداد جميع الحقول.
```
X-Goog-FieldMask: *
```
تختار
حرف البدل "*" جميع الحقول. ومع ذلك، يمكن استخدام حرف البدل هذا في مرحلة التطوير، إلا أنّ Google لا تنصح باستخدام قناع حقل الاستجابة لحرف البدل (*) في مرحلة الإنتاج بسبب الكمّ الكبير من البيانات التي يمكن عرضها.

يمكن الاطّلاع على مزيد من الإرشادات حول استخدام places.iconMaskBaseUri وplaces.iconBackgroundColor في قسم رموز الأماكن.

حدِّد حقلاً واحدًا أو أكثر من الحقول التالية:
- تؤدّي الحقول التالية إلى تشغيل رمز التخزين التعريفي لخدمة "البحث عن قرب" (أساسي):
  
  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.subDestinationsplaces.nameplaces.typesplaces.utcOffsetMinutesplaces.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.servesBreakfastplaces.servesBrunchplaces.servesCocktailsplaces.servesCoffeeplaces.servesDessertsplaces.servesDinnerplaces.servesLunchplaces.servesVegetarianFoodplaces.servesWineplaces.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 وincludedPrimaryTypes وexcludedPrimaryTypes من الطلب، سيعرض البحث أماكن لجميع الأنواع من داخل حدود القيود المتعلقة بالمواقع الجغرافية.

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 على قناع الحقل.
يمكنك تعديل نص الطلب اختياريًا.
انقر على الزر تنفيذ. في النافذة المنبثقة، اختَر الحساب الذي تريد استخدامه لتقديم الطلب.
في لوحة "مستكشف واجهات برمجة التطبيقات"، انقر على رمز التوسيع، ، لتوسيع نافذة "مستكشف واجهة برمجة التطبيقات".

البحث عن قرب (جديد)

طلبات البحث عن الأجهزة المجاورة (الجديدة)

ردود البحث عن الأجهزة المجاورة (الجديدة)

المعلمات المطلوبة

FieldMask

locationRestriction

المعلمات الاختيارية

SharedTypes/excludedTypes, includePrimaryTypes/excludedPrimaryTypes

includedTypes

excludedTypes

includedPrimaryTypes

excludedPrimaryTypes

languageCode

maxResultCount

rankPreference

regionCode