تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

طلب بحث عن قرب (جديد) يتطلب نوعًا واحدًا أو أكثر من الأماكن، ويعرض قائمة بالأماكن المطابقة داخل المنطقة المحددة. يجب وضع قناع حقل يحدد نوعاً واحدًا أو أكثر من البيانات. ميزة "البحث عن قرب" (ميزة جديدة) تتيح استخدام طلبات 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.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.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 و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، مع بعض الاستثناءات الملحوظة. على سبيل المثال، نطاق المستوى الأعلى الذي يتم ترميزه حسب البلد (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

تجربة

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

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

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

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

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

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

FieldMask

locationRestriction

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

includeTypes/excludedTypes، وincludePrimaryTypes/excludedPrimaryTypes

includedTypes

excludedTypes

includedPrimaryTypes

excludedPrimaryTypes

languageCode

maxResultCount

rankPreference

regionCode