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

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

    حدِّد حقلاً واحدًا أو أكثر من الحقول التالية:

    • تؤدي الحقول التالية إلى تنشيط رمز التخزين التعريفي لميزة "البحث عن المنتجات المجاورة" (الأساسية):

      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

    • تؤدي الحقول التالية إلى تنشيط رمز التخزين التعريفي (المفضّل) للبحث عن المنتجات بالقرب منك:

      {2, 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.dineIn, places.editorialSummary, places.evChargeOptions, places.fuelOptions, places.goodForChildren, places.goodForGroups, places.goodForWatchingSports, , places.liveMusic, places.menuForChildren, places.parkingOptions أو places.dineIn, places.editorialSummary, places.allowsDogsplaces.paymentOptionsplaces.outdoorSeatingplaces.reservableplaces.restroomplaces.reviewsplaces.routingSummariesplaces.servesBeerplaces.servesBreakfastplaces.servesBrunchplaces.servesCocktailsplaces.servesCoffeeplaces.servesDessertplaces.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
  }
}

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

  • 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"، ولكنها لا تعمل بشكل أساسي على أنّها "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

جرّب الآن

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

  1. انقر على رمز واجهة برمجة التطبيقات، وسِّع "مستكشف واجهات برمجة التطبيقات".، على يسار الصفحة.
  2. يمكنك اختياريًا توسيع عرض المَعلمات العادية وضبط مَعلمة fields على قناع الحقل.
  3. يمكنك اختياريًا تعديل نص الطلب.
  4. انقر على الزر تنفيذ. في النافذة المنبثقة، اختَر الحساب الذي تريد استخدامه لتقديم الطلب.

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