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

اختيار النظام الأساسي: 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

جرّب الآن

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

1. انقر على رمز واجهة برمجة التطبيقات api على يسار الصفحة.

2. يمكنك اختياريًا تعديل مَعلمات الطلب.

3. انقر على الزر تنفيذ. في مربّع الحوار، اختَر الحساب الذي تريد استخدامه لتقديم الطلب.

4. في لوحة "مستكشف واجهات برمجة التطبيقات"، انقر على رمز ملء الشاشة fullscreen لتوسيع نافذة "مستكشف واجهات برمجة التطبيقات".