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

اختيار النظام الأساسي: نظام التشغيل 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.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.utcOffsetMinutes, places.viewport

      * يحتوي الحقل places.name على المكان اسم المورد بالشكل: 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.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
  }
}

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

  • includeTypes/excludedTypes, includePrimaryTypes/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. في لوحة "مستكشف واجهة برمجة التطبيقات"، حدد رمز التوسيع، وسِّع "مستكشف واجهات برمجة التطبيقات".، لتوسيع نافذة مستكشف واجهة برمجة التطبيقات