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

طلب بحث عن قرب (جديد) يتطلب نوعًا واحدًا أو أكثر من الأماكن، ويعرض قائمة بالأماكن المطابقة داخل المنطقة المحددة. يجب وضع قناع حقل يحدد نوعاً واحدًا أو أكثر من البيانات. ميزة "البحث عن قرب" (ميزة جديدة) تتيح استخدام طلبات 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.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.types، places.typesplaces.nameplaces.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.servesBeer، places.delivery، places.servesBeer،
      ، places.liveMusic،places.reviewsplaces.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
      }
    }

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

  • includeTypes/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

    قائمة بأنواع الأماكن المفصولة بفواصل من الجدول أ المطلوب استبعادها من البحث.

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