تمت ترجمة هذه الصفحة بواسطة 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.containingPlaces، places.displayName، places.formattedAddress، places.googleMapsLinks^*، places.googleMapsUri، places.iconBackgroundColor، places.iconMaskBaseUri، places.id، places.location، places.name^**، places.photos، places.plusCode، places.primaryType، places.primaryTypeDisplayName، places.pureServiceAreaBusiness، places.shortFormattedAddress، places.subDestinations، places.types، places.utcOffsetMinutes، places.viewport
  
  ^* الحقل places.googleMapsLinks في مرحلة المعاينة التمهيدية للإصدار العلني ولا يتم تحصيل رسوم، أي أنّ الفوترة هي 0 دولار أمريكي مقابل الاستخدام أثناء المعاينة.
  
  ^** يحتوي الحقل places.name على اسم المورد للمكان على النحو التالي: places/PLACE_ID. استخدِم places.displayName للوصول إلى الاسم النصي للمكان.
- تؤدي الحقول التالية إلى تنشيط رمز التخزين التعريفي لميزة "البحث عن المنتجات بالقرب منك" (المتقدّمة):
  
  places.currentOpeningHours، places.currentSecondaryOpeningHours، places.internationalPhoneNumber، places.nationalPhoneNumber، places.priceLevel، places.priceRange، 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.routingSummaries،^* 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
  }
}
```

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

includedTypes/excludedTypes، وincludedPrimaryTypes/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"، ولكنّها لا تعمل primarily ك"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، مع بعض الاستثناءات البارزة. على سبيل المثال، رمز المستوى الأعلى للمنطقة الجغرافية للمملكة المتحدة هو "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"
      }
    },
...
}

العثور على أماكن من أنواع متعدّدة

يعرض المثال التالي طلب بحث عن الأماكن المجاورة (جديد) للحصول على الأسماء المعروضة لجميع متاجر البيع بالتجزئة ومتاجر الخمور ضمن نطاق جغرافي يبلغ 1,000 متر من 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

جرّب الآن

يتيح لك "مستكشف واجهات برمجة التطبيقات" إنشاء نماذج طلبات لكي تتمكّن من التعرّف على واجهة برمجة التطبيقات وخياراتها.

انقر على رمز واجهة برمجة التطبيقات api على يسار الصفحة.
يمكنك اختياريًا تعديل مَعلمات الطلب.
انقر على الزر تنفيذ. في مربّع الحوار، اختَر الحساب الذي تريد استخدامه لتقديم الطلب.
في لوحة "مستكشف واجهات برمجة التطبيقات"، انقر على رمز ملء الشاشة fullscreen لتوسيع نافذة "مستكشف واجهات برمجة التطبيقات".

البحث في الأماكن القريبة (ميزة جديدة)

طلبات "البحث عن مكان قريب" (جديد)

ردود "بحث في الأماكن القريبة" (جديد)

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

FieldMask

locationRestriction

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

includedTypes/excludedTypes، وincludedPrimaryTypes/excludedPrimaryTypes

includedTypes

excludedTypes

includedPrimaryTypes

excludedPrimaryTypes

languageCode

maxResultCount

rankPreference

regionCode