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

البحث النصي (جديد)

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

تفيد هذه الخدمة بشكل خاص في إجراء طلبات بحث غامضة عن العناوين في نظام آلي، وقد تتطابق المكونات التي لا تتضمّن عناوين في السلسلة مع الأنشطة التجارية والعناوين أيضًا. ومن الأمثلة على طلبات البحث عن العناوين الغامضة العناوين ذات التنسيق السيئ أو الطلبات التي تتضمّن مكونات غير مرتبطة بالعناوين، مثل أسماء الأنشطة التجارية. قد لا تعرض الطلبات مثل أول مثالين في الجدول التالي أي نتائج ما لم يتم تحديد موقع جغرافي - مثل المنطقة أو القيود المفروضة على الموقع الجغرافي أو الانحياز في الموقع الجغرافي.

"4 شارع القدس، حدائق الأهرام، الجيزة"	العديد من "هاي ستريت" في المملكة المتحدة، والعديد من "الشوارع الرئيسية" في الولايات المتحدة. لا يعرض طلب البحث النتائج المرغوبة ما لم يتم ضبط قيود على الموقع الجغرافي.
"مطعم مطاعم دبي"	عدة مواقع جغرافية لـ "ChainRestaurant" في نيويورك، بدون عنوان شارع أو حتى اسم شارع.
"4 شارع القدس، حدائق الأهرام، الجيزة" أو "4 شارع القدس، حدائق الأهرام"	هناك اسم "هاي ستريت" واحد فقط في مدينة إيشر بالمملكة المتحدة، وشارع واحد فقط في مدينة "بليسانتون" في الولايات المتحدة.
"UniqueRestaurantName دبي"	مؤسسة واحدة فقط تحمل هذا الاسم في نيويورك، ولا حاجة للتمييز بين عنوان الشارع
"مطاعم الكباب في دبي"	يحتوي طلب البحث هذا على الموقع الجغرافي المفروض عليه، و "مطاعم البيتزا" هو نوع مكان محدد جيدًا. تعرض نتائج متعددة.
"+1 514-670-8700"	يحتوي طلب البحث هذا على رقم هاتف. ويعرض نتائج متعددة للأماكن المرتبطة برقم الهاتف هذا. ملاحظة: للحصول على أفضل النتائج عند البحث على رقم هاتف، يجب تضمين رمز البلد متبوعًا بمسافة، وضبط المعلَمة `regionCode` لتتوافق مع رمز البلد.

يتيح لك "مستكشف واجهة برمجة التطبيقات" إجراء طلبات مباشرة لتتمكن من الإلمام بواجهة برمجة التطبيقات وخيارات واجهة برمجة التطبيقات:

جرِّبه الآن

طلبات البحث النصي

طلب البحث النصي هو طلب HTTP POST بالنموذج التالي:

https://places.googleapis.com/v1/places:searchText

مرِّر جميع المعلمات في نص طلب JSON أو في العناوين كجزء من طلب POST. مثال:

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.priceLevel' \
'https://places.googleapis.com/v1/places:searchText'

إجابات البحث النصي (جديد)

يعرض البحث النصي (جديد) كائن 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.id، places.name^*
  
  ^* يحتوي الحقل places.name على المكان اسم المورد في النموذج: places/PLACE_ID. استخدِم places.displayName للوصول إلى الاسم النصي للمكان.
- تؤدي الحقول التالية إلى ظهور رمز التخزين التعريفي للبحث النصي (الأساسي):
  places.accessibilityOptions، places.addressComponents، places.adrFormatAddress، places.businessStatus، places.displayName، places.formattedAddress، places.googleMapsUri، places.iconBackgroundColor، places.iconMaskBaseUri، places.location، places.photos، places.plusCode، places.primaryType، places.primaryTypeDisplayName، places.shortFormattedAddress، places.subDestinations، places.types، places.utcOffsetMinutes، places.viewport
- تؤدي الحقول التالية إلى ظهور رمز التخزين التعريفي للبحث النصي (متقدم):
  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
textQuery

السلسلة النصية المطلوب البحث عليها، على سبيل المثال: "مطعم" أو "123 الشارع الرئيسي" أو "أفضل مكان للزيارة في دبي". تعرض واجهة برمجة التطبيقات النتائج المطابِقة المرشحة استنادًا إلى هذه السلسلة، وترتِّب النتائج استنادًا إلى مدى صلتها بالموضوع الذي يتم رصده.

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

includedType

تقتصر النتائج على الأماكن المطابقة للنوع المحدّد والمحدّد في الجدول أ. يمكن تحديد نوع واحد فقط. مثال:
- "includedType":"bar"
- "includedType":"pharmacy"
ملاحظة: يتم عرض القيم في الجدول "ب" في الاستجابة فقط. لا يمكنك استخدام القيم في الجدول "ب" كفلتر.
languageCode

اللغة التي سيتم عرض النتائج بها.
- اطّلِع على قائمة اللغات المتاحة. يعدّل محرّك بحث Google في كثير من الأحيان اللغات المتاحة، لذا قد لا تكون هذه القائمة شاملة.
- وإذا لم يتم توفير languageCode، يتم ضبط واجهة برمجة التطبيقات تلقائيًا على en. وإذا حدّدت رمز لغة غير صالح، ستعرض واجهة برمجة التطبيقات الخطأ INVALID_ARGUMENT.
- تبذل واجهة برمجة التطبيقات قصارى جهدها لتوفير عنوان شارع يسهل قراءته لكل من المستخدم والسكان المحليين. ولتحقيق هذا الهدف، يتم عرض عناوين الشوارع باللغة المحلية، وتحويلها صوتيًا إلى نص يمكن للمستخدم قراءته إذا لزم الأمر، مع مراعاة اللغة المفضَّلة. يتم عرض جميع العناوين الأخرى باللغة المفضّلة. يتم عرض جميع مكوّنات العنوان باللغة نفسها التي يتم اختيارها من المكوّن الأول.
- وإذا لم يكن الاسم متاحًا باللغة المفضّلة، ستستخدم واجهة برمجة التطبيقات أقرب نتيجة مطابقة.
- تؤثر اللغة المفضّلة بشكل طفيف في مجموعة النتائج التي تختار واجهة برمجة التطبيقات عرضها وترتيب عرضها. ويفسّر أداة الترميز الجغرافي الاختصارات بشكل مختلف حسب اللغة، مثل اختصارات أنواع الشوارع أو المرادفات التي قد تكون صالحة في لغة معيّنة وليس بلغة أخرى.
locationBias

لتحديد منطقة للبحث. يمثّل هذا الموقع الجغرافي انحيازًا، أي أنّه يمكن عرض نتائج حول الموقع الجغرافي المحدّد، بما في ذلك النتائج خارج المنطقة المحدّدة.

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

ملاحظة: إذا حذفت كلاً من locationBias وlocationRestriction، ستستخدم واجهة برمجة التطبيقات انحياز عنوان IP تلقائيًا. من خلال انحياز عنوان IP، تستخدم واجهة برمجة التطبيقات عنوان IP للجهاز لانحياز النتائج.

ملاحظة: يمكن إلغاء المَعلمة locationBias إذا كان textQuery يحتوي على موقع جغرافي صريح، مثل Market in Barcelona. وفي هذه الحالة، يتم تجاهل locationBias.

حدِّد المنطقة على أنّها إطار عرض مستطيل أو كدائرة.
- يتم تحديد الدائرة من خلال نقطة المركز ونصف القطر بالمتر. ويجب أن يتراوح النطاق الجغرافي بين 0.0 و50000.0، بشكل شامل. النطاق الجغرافي الافتراضي هو 0.0. مثال:
```
"locationBias": {
  "circle": {
    "center": {
      "latitude": 37.7937,
      "longitude": -122.3965
    },
    "radius": 500.0
  }
}
```
- المستطيل هو إطار عرض لخطوط الطول والعرض، ويتم تمثيله كنقطتين مائلتين قبالة النقطتَين المنخفضة والمرتفعة. وتمثل النقطة المنخفضة الزاوية الجنوبية الغربية من المستطيل، بينما تمثل النقطة الأعلى الزاوية الشمالية الشرقية من المستطيل.
  
  ويُعدّ إطار العرض منطقة مغلقة، ما يعني أنّه يشمل حدوده. يجب أن تتراوح حدود خطوط العرض بين -90 و90 درجة، كما يجب أن تتراوح حدود خطوط الطول بين -180 و180 درجة، بما في ذلك:
  - إذا كانت low = high، يتكوّن إطار العرض من نقطة واحدة فقط.
  - إذا كانت قيمة low.longitude > high.longitude، يتم عكس نطاق خط الطول (يتجاوز إطار العرض خط الطول 180 درجة).
  - إذا كانت low.longitude = -180 درجة وhigh.longitude = 180 درجة، سيتضمّن إطار العرض جميع خطوط الطول.
  - إذا كان low.longitude = 180 درجة وhigh.longitude = -180 درجة، يكون نطاق خط الطول فارغًا.
  - إذا كانت القيمة low.latitude > high.latitude، يكون نطاق خط العرض فارغًا.
  يجب تعبئة كل من الحقلين المنخفض والمرتفعين، ولا يمكن أن يكون المربّع الممثل فارغًا. يؤدي إطار العرض الفارغ إلى حدوث خطأ.
  
  على سبيل المثال، يحتوي إطار العرض هذا على مدينة نيويورك بالكامل:
```
"locationBias": {
  "rectangle": {
    "low": {
      "latitude": 40.477398,
      "longitude": -74.259087
    },
    "high": {
      "latitude": 40.91618,
      "longitude": -73.70018
    }
  }
}
```
locationRestriction

لتحديد منطقة للبحث. ولن يتم عرض النتائج خارج المنطقة المحدّدة. حدِّد المنطقة على أنّها إطار عرض مستطيل. راجِع وصف locationBias للحصول على معلومات عن تحديد إطار العرض.

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

ملاحظة: إذا حذفت كلاً من locationBias وlocationRestriction، ستستخدم واجهة برمجة التطبيقات انحياز عنوان IP تلقائيًا. من خلال انحياز عنوان IP، تستخدم واجهة برمجة التطبيقات عنوان IP للجهاز لانحياز النتائج.
maxResultCount

تحدّد هذه السمة الحد الأقصى لعدد نتائج الأماكن المطلوب عرضها. ويجب أن تتراوح القيمة بين 1 و20 (الخيار التلقائي).
evOptions

تحدِّد هذه السياسة معلَمات لتحديد موصِّلات شحن المركبات الكهربائية ومعدّلات الشحن المتاحة.
- connectorTypes
  
  الفلترة حسب نوع موصّل شحن المركبة الكهربائية المتاح في مكان معيّن وسيتم استبعاد المكان الذي لا يتيح أيًا من أنواع الموصلات. تشمل أنواع موصِّلات شحن المركبات الكهربائية المتوافقة شواحن مدمجة (AC وDC) وشواحن Tesla وشواحن متوافقة مع غيغابايت/T (للشحن السريع للمركبات الكهربائية في الصين) وشواحن مقابس حائط. لمزيد من المعلومات، يمكنك الاطّلاع على المستندات المرجعية.
- minimumChargingRateKw
  
  فلترة الأماكن حسب الحدّ الأدنى لمعدّل شحن المركبة الكهربائية بالكيلوواط (كيلوواط) تتم فلترة أي أماكن تشحن فيها الشحنات أقل من الحدّ الأدنى لمعدّل الشحن. على سبيل المثال، للعثور على شواحن مركبات كهربائية بمعدّلات شحن لا تقل عن 10 كيلوواط، يمكنك ضبط هذه المعلَمة على "10".
minRating

يحصر خيار النتائج فقط المستخدمين الذين يزيد متوسط تقييمهم عن الحدّ الأقصى المسموح به أو مساويًا له. يجب أن تتراوح القيم بين 0.0 و5.0 (شاملةً) بزيادات 0.5. على سبيل المثال: 0، 0.5، 1.0، ... ، 5.0 بشكل شامل. ويتم تقريب القيم إلى أقرب 0.5. على سبيل المثال، تؤدي القيمة 0.6 إلى إزالة جميع النتائج ذات التقييم الأقل من 1.0.
openNow

إذا كانت السمة true، يجب عرض الأماكن المفتوحة للنشاط التجاري فقط في وقت إرسال طلب البحث. إذا تم عرض false، سيتم عرض جميع الأنشطة التجارية بغض النظر عن الحالة "مفتوح". في حال ضبط هذه المعلَمة على false، يتم عرض الأماكن التي لا تحدّد ساعات العمل في قاعدة بيانات "أماكن Google".
priceLevels

حصر عملية البحث على الأماكن التي تم وضع علامة عليها بمستويات أسعار معيّنة. يكون الخيار التلقائي هو اختيار جميع مستويات السعر.

حدِّد مصفوفة من قيمة أو أكثر من القيم التي تم تحديدها بواسطة السمة PriceLevel.

ملاحظة: PRICE_LEVEL_FREE غير مسموح به في الطلب. ويتم استخدامه لملء الرد فقط.

مثال:
```
"priceLevels":["PRICE_LEVEL_INEXPENSIVE", "PRICE_LEVEL_MODERATE"]
```
rankPreference

تحدّد هذه السمة كيفية ترتيب النتائج في الردّ استنادًا إلى نوع طلب البحث:
- بالنسبة إلى طلب بحث فئوي مثل "مطاعم في مدينة نيويورك"، يكون RELEVANCE (ترتيب النتائج حسب مدى صلة البحث بموضوع البحث) هو الخيار التلقائي. يمكنك ضبط السمة rankPreference على RELEVANCE أو DISTANCE (ترتيب النتائج حسب المسافة).
- بالنسبة إلى طلب بحث غير فئوي مثل "Mountain View, CA"، ننصحك بترك rankPreference بدون ضبط.
regionCode

تمثّل هذه السمة رمز المنطقة المستخدَم لتنسيق الردّ، ويتم تحديده كقيمة لرمز CLDR مكوَّن من حرفين. ويمكن أن يكون لهذه المَعلمة أيضًا تأثير متحيز في نتائج البحث. لا تتوفّر قيمة تلقائية.

وإذا كان اسم البلد في الحقل formattedAddress في الردّ يتطابق مع regionCode، سيتم حذف رمز البلد من formattedAddress. وليس لهذه المَعلمة أي تأثير في adrFormatAddress، الذي يتضمّن دائمًا اسم البلد عند توفّره، أو على shortFormattedAddress الذي لا يتضمّنه مطلقًا.

تتطابق معظم رموز CLDR مع رموز ISO 3166-1، مع بعض الاستثناءات الملحوظة. على سبيل المثال، نطاق المستوى الأعلى الذي يتم ترميزه حسب البلد (ccTLD) في المملكة المتحدة هو "uk" (.co.uk)، في حين أنّ رمز ISO 3166-1 هو "gb" (من الناحية الفنية لكيان "المملكة المتحدة لبريطانيا العظمى وأيرلندا الشمالية"). يمكن أن تؤثر المَعلمة في النتائج استنادًا إلى القانون الساري.
strictTypeFiltering

تُستخدَم مع المَعلمة includeType. وعند ضبطها على true، لن يتم عرض سوى الأماكن التي تطابق الأنواع المحدّدة في includeType. أما إذا كانت الإجابة "خطأ"، فالإعداد التلقائي لها يمكن أن يتضمّن أماكن لا تتطابق مع الأنواع المحدّدة.

أمثلة على البحث النصي

البحث عن مكان من خلال سلسلة طلب البحث

يوضح المثال التالي طلب بحث نصي عن "الطعام النباتي الحار في سيدني، أستراليا":

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress' \
'https://places.googleapis.com/v1/places:searchText'

يُرجى العِلم أنّ عنوان X-Goog-FieldMask يوضِّح أنّ الاستجابة تحتوي على حقول البيانات التالية: places.displayName,places.formattedAddress. يكون الرد بعد ذلك على النحو التالي:

{
  "places": [
    {
      "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia",
      "displayName": {
        "text": "Mother Chu's Vegetarian Kitchen",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "175 First Ave, Five Dock NSW 2046, Australia",
      "displayName": {
        "text": "Veggo Sizzle - Vegan & Vegetarian Restaurant, Five Dock, Sydney",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "29 King St, Sydney NSW 2000, Australia",
      "displayName": {
        "text": "Peace Harmony",
        "languageCode": "en"
      }
    },
    ...
  ]
}

أضِف المزيد من أنواع البيانات إلى قناع الحقل لعرض معلومات إضافية. على سبيل المثال، يمكنك إضافة places.types,places.websiteUri لتضمين نوع المطعم وعنوان الويب في الرد:

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-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:searchText'

يكون الرد الآن بالنموذج:

{
  "places": [
    {
      "types": [
        "vegetarian_restaurant",
        "vegan_restaurant",
        "chinese_restaurant",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia",
      "websiteUri": "http://www.motherchusvegetarian.com.au/",
      "displayName": {
        "text": "Mother Chu's Vegetarian Kitchen",
        "languageCode": "en"
      }
    },
    {
      "types": [
        "vegan_restaurant",
        "thai_restaurant",
        "vegetarian_restaurant",
        "indian_restaurant",
        "italian_restaurant",
        "american_restaurant",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "175 First Ave, Five Dock NSW 2046, Australia",
      "websiteUri": "http://www.veggosizzle.com.au/",
      "displayName": {
        "text": "Veggo Sizzle - Vegan & Vegetarian Restaurant, Five Dock, Sydney",
        "languageCode": "en"
      }
    },
    ...
  ]
}

فلترة الأماكن حسب مستوى السعر

استخدم خيار priceLevel لتصفية النتائج إلى مطاعم غير مكلفة أو باهظة الثمن:

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia",
  "priceLevels":["PRICE_LEVEL_INEXPENSIVE", "PRICE_LEVEL_MODERATE"]
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.priceLevel' \
'https://places.googleapis.com/v1/places:searchText'

يستخدم هذا المثال أيضًا العنوان X-Goog-FieldMask لإضافة حقل بيانات places.priceLevel إلى الاستجابة، بحيث يكون بالتنسيق التالي:

{
  "places": [
    {
      "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia",
      "priceLevel": "PRICE_LEVEL_MODERATE",
      "displayName": {
        "text": "Mother Chu's Vegetarian Kitchen",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "115 King St, Newtown NSW 2042, Australia",
      "priceLevel": "PRICE_LEVEL_MODERATE",
      "displayName": {
        "text": "Green Mushroom",
        "languageCode": "en"
      }
    },
    ...
  ]
}

أضِف خيارات أخرى لتحسين البحث، مثل includedType وminRating وrankPreference وopenNow وغيرها من المَعلمات الموضّحة في المَعلمات الاختيارية.

البحث عن أماكن في منطقة

استخدِم السمة locationRestriction أو السمة locationBias ولكن ليس كليهما لحصر عملية البحث بمنطقة معيّنة. يمكن اعتبار locationRestriction أنّه يحدّد المنطقة التي يجب أن تكون النتائج فيها، وlocationBias على أنّه يحدّد المنطقة التي يجب أن تكون النتائج قريبة منها، ولكن يمكن أن تكون خارجها.

ملاحظة: عند استخدام locationBias، يمكنك تحديد المنطقة كإطار عرض مستطيل أو دائرة. بالنسبة إلى locationRestriction، يمكنك تحديد المنطقة على أنّها إطار عرض مستطيل.

يوضح المثال التالي طلب بحث نصي عن "الطعام النباتي الحار" متحيزًا ليكون على بعد 500 متر من نقطة ما في وسط مدينة سان فرانسيسكو. يعرض هذا الطلب أول 10 نتائج فقط للأماكن المفتوحة.

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food",
  "openNow": true,
  "maxResultCount": 10,
  "locationBias": {
    "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' \
'https://places.googleapis.com/v1/places:searchText'

البحث عن شواحن مركبات كهربائية باستخدام الحدّ الأدنى لمعدل الشحن

استخدِم minimumChargingRateKw وconnectorTypes للبحث عن أماكن تتوفّر فيها شواحن متوافقة مع مركبتك الكهربائية.

يوضح المثال التالي طلبًا لموصلات شحن للمركبات الكهربائية من النوع 1 Tesla وJ1772 من النوع 1 بحد أدنى لمعدّل شحن يبلغ 10 كيلوواط في ماونتن فيو، كاليفورنيا. يتم إرجاع أربع نتائج فقط.

curl -X POST -d '{
    "textQuery": "EV Charging Station Mountain View",
    "maxResultCount": 4,
    "evOptions": {
      "minimumChargingRateKw": 10,
      "connectorTypes": ["EV_CONNECTOR_TYPE_J1772","EV_CONNECTOR_TYPE_TESLA"]
    }
  }' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H "X-Goog-FieldMask: places.displayName,places.evChargeOptions" \
'https://places.googleapis.com/v1/places:searchText'

يعرض الطلب الرد التالي:

{
  "places": [
    {
      "displayName": {
        "text": "EVgo Charging Station",
        "languageCode": "en"
      },
      "evChargeOptions": {
        "connectorCount": 16,
        "connectorAggregation": [
          {
            "type": "EV_CONNECTOR_TYPE_CHADEMO",
            "maxChargeRateKw": 100,
            "count": 8,
            "availableCount": 5,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 100,
            "count": 2,
            "availableCount": 2,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 350,
            "count": 6,
            "availableCount": 3,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          }
        ]
      }
    },
    {
      "displayName": {
        "text": "EVgo Charging Station",
        "languageCode": "en"
      },
      "evChargeOptions": {
        "connectorCount": 6,
        "connectorAggregation": [
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 100,
            "count": 4,
            "availableCount": 3,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 350,
            "count": 2,
            "availableCount": 0,
            "outOfServiceCount": 2,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          }
        ]
      }
    },
    {
      "displayName": {
        "text": "EVgo Charging Station",
        "languageCode": "en"
      },
      "evChargeOptions": {
        "connectorCount": 5,
        "connectorAggregation": [
          {
            "type": "EV_CONNECTOR_TYPE_J1772",
            "maxChargeRateKw": 3.5999999046325684,
            "count": 1,
            "availableCount": 0,
            "outOfServiceCount": 1,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CHADEMO",
            "maxChargeRateKw": 50,
            "count": 2,
            "availableCount": 0,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 50,
            "count": 2,
            "availableCount": 0,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          }
        ]
      }
    },
    {
      "displayName": {
        "text": "Electric Vehicle Charging Station",
        "languageCode": "en"
      },
      "evChargeOptions": {
        "connectorCount": 10,
        "connectorAggregation": [
          {
            "type": "EV_CONNECTOR_TYPE_OTHER",
            "maxChargeRateKw": 210,
            "count": 10
          }
        ]
      }
    }
  ]
}

تجربة

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

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

البحث النصي (جديد)

طلبات البحث النصي

إجابات البحث النصي (جديد)

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

FieldMask

textQuery

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

includedType

languageCode

locationBias

locationRestriction

maxResultCount

evOptions

connectorTypes

minimumChargingRateKw

minRating

openNow

priceLevels

rankPreference

regionCode

strictTypeFiltering