تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

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

اختيار النظام الأساسي: Android iOS JavaScript خدمة الويب

المطوّرون في المنطقة الاقتصادية الأوروبية

مقدمة

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

بالإضافة إلى المَعلمات المطلوبة، تتيح خدمة "البحث النصي (الجديد)" تحسين طلبات البحث باستخدام مَعلمات اختيارية للحصول على نتائج أفضل.

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

جرِّبه الآن

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

طلب "البحث النصي (جديد)" هو طلب 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.attributions
  places.id
  places.consumerAlert
  places.name^*
  nextPageToken
  places.movedPlace
  places.movedPlaceId
  ^* يحتوي الحقل places.name على اسم المورد الخاص بالمكان بالصيغة: places/PLACE_ID. استخدِم places.displayName في حزمة Pro SKU للوصول إلى الاسم النصي للمكان.
  
  للاطّلاع على قائمة كاملة بالحقول ورموز التخزين التعريفية المرتبطة بها، يُرجى الانتقال إلى حقول بيانات الأماكن (الإصدار الجديد).
- تؤدي الحقول التالية إلى تفعيل رمز التخزين التعريفي لخدمة Text Search Pro:
  places.accessibilityOptions
  places.addressComponents
  places.addressDescriptor^*
  places.adrFormatAddress
  places.businessStatus
  places.containingPlaces
  places.displayName
  places.formattedAddress
  places.googleMapsLinks
  places.googleMapsTypeLabel
  places.googleMapsUri
  places.iconBackgroundColor
  places.iconMaskBaseUri
  places.location
  places.openingDate
  places.photos
  places.plusCode
  places.postalAddress
  places.primaryType
  places.primaryTypeDisplayName
  places.pureServiceAreaBusiness
  places.shortFormattedAddress
  places.searchUri
  places.subDestinations
  places.timeZone
  places.types
  places.utcOffsetMinutes
  places.viewport
  
  ^* تتوفّر واصفات العناوين بشكل عام للعملاء في الهند، وهي تجريبية في أماكن أخرى.
  للحصول على قائمة كاملة بالحقول ورموز التخزين التعريفية المرتبطة بها، يُرجى الاطّلاع على حقول بيانات الأماكن (الجديدة).
- تؤدي الحقول التالية إلى تفعيل رمز التخزين التعريفي الخاص بميزة "البحث النصي" للمؤسسات:
  places.currentOpeningHours
  places.currentSecondaryOpeningHours
  places.internationalPhoneNumber
  places.nationalPhoneNumber
  places.priceLevel
  places.priceRange
  places.rating
  places.regularOpeningHours
  places.regularSecondaryOpeningHours
  places.transitStation
  places.userRatingCount
  places.websiteUri
  للاطّلاع على قائمة كاملة بالحقول ورموز التخزين التعريفية المرتبطة بها، يُرجى الانتقال إلى حقول بيانات الأماكن (الإصدار الجديد).
- تؤدي الحقول التالية إلى تفعيل رمز التخزين التعريفي Text Search Enterprise + Atmosphere:
  places.allowsDogs
  places.curbsidePickup
  places.delivery
  places.dineIn
  places.editorialSummary
  places.evChargeAmenitySummary
  places.evChargeOptions
  places.fuelOptions
  places.generativeSummary
  places.goodForChildren
  places.goodForGroups
  places.goodForWatchingSports
  places.liveMusic
  places.menuForChildren
  places.neighborhoodSummary
  places.parkingOptions
  places.paymentOptions
  places.outdoorSeating
  places.reservable
  places.restroom
  places.reviews
  places.reviewSummary
  routingSummaries^*
  places.servesBeer
  places.servesBreakfast
  places.servesBrunch
  places.servesCocktails
  places.servesCoffee
  places.servesDessert
  places.servesDinner
  places.servesLunch
  places.servesVegetarianFood
  places.servesWine
  places.takeout
  
  ^* "البحث النصي" و"بحث في الجوار" فقط
  للاطّلاع على قائمة كاملة بالحقول ورموز التخزين التعريفية المرتبطة بها، يُرجى الانتقال إلى حقول بيانات الأماكن (الإصدار الجديد).

textQuery

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

لا يُفترض استخدام ميزة "البحث النصي" (الجديدة) مع طلبات البحث الغامضة، بما في ذلك ما يلي:

نوع طلب البحث	مثال
عدد كبير جدًا من المفاهيم أو القيود، مثل أسماء أماكن أو طرق أو مدن متعددة في طلب بحث واحد	"شارع ماركت في سان فرانسيسكو، مطار سان خوسيه"
عناصر العنوان البريدي غير الممثّلة على "خرائط Google"	"C/O John Smith 123 Main Street" "P.O. Box 13 San Francisco"
أسماء الأنشطة التجارية أو السلاسل أو الفئات المدمجة مع المواقع الجغرافية التي لا تتوفّر فيها هذه الكيانات	"Tesco بالقرب من دالاس، تكساس"
طلبات البحث الغامضة التي تتضمّن تفسيرات متعددة	"تسليم الشاحن"
الأسماء القديمة التي لم يعُد يتم استخدامها	"ميدلسكس، المملكة المتحدة"
العناصر أو النية غير الجغرافية المكانية	"كم عدد القوارب في ميناء فينتورا؟"
الأسماء غير الرسمية أو المخصّصة	"The Jenga" "The Helter Skelter"
إحداثيات خطوط العرض وخطوط الطول	"37.422131,-122.084801"

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

includeFutureOpeningBusinesses

إذا كانت القيمة true، تعرض هذه السمة الأنشطة التجارية التي من المتوقّع أن تفتح في المستقبل. القيمة التلقائية هي false.

لاسترداد حالة المؤسسة، أدرِج places.businessStatus في قناع حقول الطلب. لاسترداد تاريخ الافتتاح المتوقّع للمؤسسة، أدرِج places.openingDate في قناع حقل الطلب.
includedType

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

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

لتطبيق فلترة النوع على جميع طلبات البحث، اضبط strictTypeFiltering على true.

لا تنطبق هذه المَعلمة على طلبات البحث عن الفنادق أو الطلبات الجيوسياسية (مثل الطلبات ذات الصلة بالمناطق الإدارية أو المواقع أو الرموز البريدية أو المناطق التعليمية أو البلدان).
includePureServiceAreaBusinesses

إذا تم ضبط القيمة على true، سيتضمّن الردّ المؤسسات التي تقدّم خدماتها من خلال الانتقال إلى المواقع الجغرافية للعملاء أو توصيل الخدمة إليهم مباشرةً، ولكنّها لا تمتلك موقعًا جغرافيًا. إذا تم ضبطها على false، تعرض واجهة برمجة التطبيقات الأنشطة التجارية التي لها موقع جغرافي فقط.
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 (متوقّفة نهائيًا)

تم إيقاف هذا الحقل نهائيًا: تم إيقاف هذا الحقل نهائيًا واستبداله بـ pageSize. في حال تحديد كل من maxResultCount وpageSize، سيتم استخدام pageSize وتجاهل maxResultCount.

تحدّد هذه السمة عدد النتائج (بين 1 و20) المطلوب عرضها في كل صفحة. على سبيل المثال، سيؤدي ضبط قيمة maxResultCount على 5 إلى عرض ما يصل إلى 5 نتائج على الصفحة الأولى. إذا كان هناك المزيد من النتائج التي يمكن عرضها من طلب البحث، سيتضمّن الردّ nextPageToken يمكنك تمريره إلى طلب لاحق للوصول إلى الصفحة التالية.

ملاحظة: إذا كانت قيمة maxResultCount هي 0 أو غير محدّدة، ستعرض واجهة برمجة التطبيقات تلقائيًا 20 نتيجة في كل صفحة. إذا كانت قيمة maxResultCount أكبر من 20، لن تعرض واجهة برمجة التطبيقات أكثر من 20 نتيجة في كل صفحة.
evOptions

تحدّد هذه السمة المَعلمات اللازمة لتحديد وصلات شحن المركبات الكهربائية المتاحة ومعدّلات الشحن.
- connectorTypes
  
  تتم الفلترة حسب نوع وصلة شحن المركبات الكهربائية المتوفرة في مكان معيّن. سيتم استبعاد أي مكان لا يتوافق مع أي من أنواع الموصلات. تشمل أنواع موصلات شحن المركبات الكهربائية المتوافقة الشواحن المجمّعة (تيار متردد وتيار مباشر) وشواحن Tesla والشواحن المتوافقة مع معيار GB/T (للشحن السريع للمركبات الكهربائية في الصين) وشواحن مقابس الحائط. لمزيد من المعلومات، يُرجى الاطّلاع على المستندات المرجعية.
  - لفلترة النتائج بحثًا عن موصل متوافق معيّن، اضبط connectorTypes على هذه القيمة. على سبيل المثال، للعثور على موصلات من النوع 1 J1772، اضبط connectorTypes على EV_CONNECTOR_TYPE_J1772.
  - لفلترة النتائج حسب الموصلات غير المتوافقة، اضبط قيمة connectorTypes على EV_CONNECTOR_TYPE_OTHER.
  - لفلترة النتائج حسب أي نوع من الموصلات التي يمكن توصيلها بمقبس الحائط، اضبط قيمة connectorTypes على EV_CONNECTOR_TYPE_UNSPECIFIED_WALL_OUTLET.
  - لفلترة النتائج لأي نوع موصِّل، اضبط connectorTypes على EV_CONNECTOR_TYPE_UNSPECIFIED أو لا تضبط قيمة لـ connectorTypes.
- minimumChargingRateKw
  
  تفلتر هذه السمة الأماكن حسب الحد الأدنى لمعدّل شحن المركبات الكهربائية بالكيلوواط (kW). ويتم استبعاد أي أماكن توفّر معدّل شحن أقل من الحد الأدنى لمعدّل الشحن. على سبيل المثال، للعثور على شواحن مركبات كهربائية تبلغ معدلات شحنها 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، يتم عرض جميع المؤسسات بغض النظر عن حالة فتحها. يتم عرض الأماكن التي لا تحدّد ساعات العمل في قاعدة بيانات "أماكن Google" إذا ضبطت هذه المَعلمة على false.

لا تنطبق هذه المَعلمة على طلبات البحث عن الفنادق أو الطلبات الجيوسياسية (مثل الطلبات ذات الصلة بالمناطق الإدارية أو المواقع أو الرموز البريدية أو المناطق التعليمية أو البلدان).
pageSize

تحدّد هذه السمة عدد النتائج (بين 1 و20) المطلوب عرضها في كل صفحة. على سبيل المثال، سيؤدي ضبط قيمة pageSize على 5 إلى عرض ما يصل إلى 5 نتائج على الصفحة الأولى. إذا كان هناك المزيد من النتائج التي يمكن عرضها من طلب البحث، سيتضمّن الردّ nextPageToken يمكنك تمريره إلى طلب لاحق للوصول إلى الصفحة التالية.

ملاحظة: إذا كانت قيمة pageSize هي 0 أو غير محدّدة، ستعرض واجهة برمجة التطبيقات 20 نتيجة تلقائيًا في كل صفحة. إذا كانت قيمة pageSize أكبر من 20، لن تعرض واجهة برمجة التطبيقات أكثر من 20 نتيجة في كل صفحة.
pageToken

تحدّد هذه السمة nextPageToken من نص الردّ الخاص بالصفحة السابقة.
priceLevels

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

يمكن توقُّع مستويات الأسعار للأماكن من الأنواع التالية:
لن يتم تضمين الأماكن من الأنواع غير المتوافقة في الردّ إذا تم تحديد priceLevels.

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

على سبيل المثال:
```
"priceLevels":["PRICE_LEVEL_INEXPENSIVE", "PRICE_LEVEL_MODERATE"]
```
ملاحظة: لا يُسمح باستخدام PRICE_LEVEL_FREE في الطلب. ويتم استخدامها فقط لتعبئة الردّ.

لا تنطبق هذه المَعلمة على طلبات البحث عن الفنادق أو الطلبات الجيوسياسية (مثل الطلبات ذات الصلة بالمناطق الإدارية أو المواقع أو الرموز البريدية أو المناطق التعليمية أو البلدان).
rankPreference

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

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

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

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

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

أمثلة على "البحث النصي" (جديد)

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

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

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 بمثابة تحديد المنطقة التي يجب أن تكون النتائج قريبة منها ولكن يمكن أن تكون خارجها.

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

حصر المنطقة باستخدام locationRestriction

استخدِم المَعلمة locationRestriction لحصر نتائج طلب البحث على منطقة معيّنة. في نص الطلب، حدِّد قيم خطوط العرض والطول low وhigh التي تحدّد حدود المنطقة.

يوضّح المثال التالي طلب "بحث نصي (جديد)" عن "طعام نباتي" في مدينة نيويورك. يعرض هذا الطلب أول 10 نتائج فقط للأماكن المفتوحة.

curl -X POST -d '{
  "textQuery" : "vegetarian food",
  "pageSize" : "10",
  "locationRestriction": {
    "rectangle": {
      "low": {
        "latitude": 40.477398,
        "longitude": -74.259087
      },
      "high": {
        "latitude": 40.91618,
        "longitude": -73.70018
      }
    }
  }
}' \
  -H 'Content-Type: application/json' \
  -H 'X-Goog-Api-Key: API_KEY' \
  -H 'X-Goog-FieldMask: places.id,places.formattedAddress' \
  'https://places.googleapis.com/v1/places:searchText'

تحديد منطقة باستخدام locationBias

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

curl -X POST -d '{
  "textQuery" : "vegetarian food",
  "openNow": true,
  "pageSize": 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 للبحث عن أماكن تتوفّر فيها شواحن متوافقة مع مركبتك الكهربائية.

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

curl -X POST -d '{
    "textQuery": "EV Charging Station Mountain View",
    "pageSize": 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
          }
        ]
      }
    }
  ]
}

البحث عن المؤسسات ضمن منطقة الخدمة

استخدِم المَعلمة includePureServiceAreaBusinesses للبحث عن مؤسسات ليس لها عنوان جغرافي للخدمة (على سبيل المثال، خدمة تنظيف متنقلة أو شاحنة طعام).

يعرض المثال التالي طلبًا لسبّاكين في القاهرة:

curl -X POST -d '{
  "textQuery" : "plumber San Francisco",
  "includePureServiceAreaBusinesses": true
}' \
-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'

في الردّ، لا تتضمّن المؤسسات التي ليس لديها عنوان خدمة فعلي الحقل formattedAddress:

{
  "places": [
    {
      "formattedAddress": "3450 Sacramento St #204, San Francisco, CA 94118, USA",
      "displayName": {
        "text": "Advanced Plumbing & Drain",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "1455 Bancroft Ave, San Francisco, CA 94124, USA",
      "displayName": {
        "text": "Magic Plumbing Heating & Cooling",
        "languageCode": "en"
      }
    },
    /.../
    {
      "displayName": {
        "text": "Starboy Plumbing Inc.",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "78 Dorman Ave, San Francisco, CA 94124, USA",
      "displayName": {
        "text": "Cabrillo Plumbing, Heating & Air",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "540 Barneveld Ave # D, San Francisco, CA 94124, USA",
      "displayName": {
        "text": "Mr. Rooter Plumbing of San Francisco",
        "languageCode": "en"
      }
    },
    /.../
    {
      "displayName": {
        "text": "Pipeline Plumbing",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "350 Bay St #100-178, San Francisco, CA 94133, USA",
      "displayName": {
        "text": "One Source Plumbing and Rooter",
        "languageCode": "en"
      }
    },
    /.../
  ]
}

تحديد عدد النتائج التي سيتم عرضها في كل صفحة

استخدِم المَعلمة pageSize لتحديد عدد النتائج المطلوب عرضها في كل صفحة. توفّر المَعلمة nextPageToken في نص الاستجابة رمزًا مميزًا يمكن استخدامه في الطلبات اللاحقة للوصول إلى الصفحة التالية من النتائج.

يوضّح المثال التالي طلبًا للبحث عن "بيتزا في القاهرة" مع حصر النتائج بـ 5 نتائج لكل صفحة:

 curl -X POST -d '{
  "textQuery": "pizza in New York",
  "pageSize": 5
  }' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H "X-Goog-FieldMask: places.id,nextPageToken" \
'https://places.googleapis.com/v1/places:searchText'

{
  "places": [
    {
      "id": "ChIJifIePKtZwokRVZ-UdRGkZzs"
    },
    {
      "id": "ChIJPxPd_P1YwokRfzLhSiACEoU"
    },
    {
      "id": "ChIJrXXKn5NZwokR78g0ipCnY60"
    },
    {
      "id": "ChIJ6ySICVZYwokR9rIK8HjXhzE"
    },
    {
      "id": "ChIJ6xvs94VZwokRnT1D2lX2OTw"
    }
  ],
  "nextPageToken": "AeCrKXsZWzNVbPzO-MRWPu52jWO_Xx8aKwOQ69_Je3DxRpfdjClq8Ekwh3UcF2h2Jn75kL6PtWLGV4ecQri-GEUKN_OFpJkdVc-JL4Q"
}

للوصول إلى صفحة النتائج التالية، استخدِم pageToken لتمرير nextPageToken في نص الطلب:

 curl -X POST -d '{
  "textQuery": "pizza in New York",
  "pageSize": 5,
  "pageToken": "AeCrKXsZWzNVbPzO-MRWPu52jWO_Xx8aKwOQ69_Je3DxRpfdjClq8Ekwh3UcF2h2Jn75kL6PtWLGV4ecQri-GEUKN_OFpJkdVc-JL4Q"
  }' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H "X-Goog-FieldMask: places.id,nextPageToken" \
'https://places.googleapis.com/v1/places:searchText'

{
  "places": [
    {
      "id": "ChIJL-LN1N1ZwokR8K2jACu6Ydw"
    },
    {
      "id": "ChIJjaD94kFZwokR-20CXqlpy_4"
    },
    {
      "id": "ChIJ6ffdpJNZwokRmcafdROM5q0"
    },
    {
      "id": "ChIJ8Q2WSpJZwokRQz-bYYgEskM"
    },
    {
      "id": "ChIJ8164qwFZwokRhplkmhvq1uE"
    }
  ],
  "nextPageToken": "AeCrKXvPd6uUy-oj96W2OaqEe2pUD8QTxOM8-sKfUcFsC9t2Wey5qivrKGoGSxcZnyc7RPmaFfAktslrKbUh31ZDTkL0upRmaxA7c_c"
}

الحصول على أوصاف العناوين

توفّر أوصاف العناوين معلومات ذات صلة بالموقع الجغرافي لمكان معيّن، بما في ذلك المعالم القريبة والمناطق التي يقع فيها.

يعرض المثال التالي طلبًا باستخدام Text Search (New) للبحث عن أماكن بالقرب من مركز تسوّق في سان خوسيه. في هذا المثال، يمكنك تضمين addressDescriptors في قناع الحقل:

curl -X POST -d '{
  "textQuery": "clothes",
  "maxResultCount": 5,
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.321328,
        "longitude": -121.946275
      }
    }
  },
  "rankPreference":"RANK_PREFERENCE_UNSPECIFIED"
}' \
-H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName,places.addressDescriptor" \
https://places.googleapis.com/v1/places:searchText

تتضمّن الاستجابة المكان المحدّد في الطلب، وقائمة بالمعالم القريبة ومسافتها عن المكان، وقائمة بالمناطق وعلاقة الاحتواء الخاصة بها بالمكان:

  {
  "places": [
    {
      "displayName": {
        "text": "Urban Outfitters",
        "languageCode": "en"
      },
      "addressDescriptor": {
        "landmarks": [
          {
            "name": "places/ChIJVVVVUB7Lj4ARXyb4HFVDV8s",
            "placeId": "ChIJVVVVUB7Lj4ARXyb4HFVDV8s",
            "displayName": {
              "text": "Westfield Valley Fair",
              "languageCode": "en"
            },
            "types": [
              "clothing_store",
              "department_store",
              "establishment",
              "food",
              "movie_theater",
              "point_of_interest",
              "restaurant",
              "shoe_store",
              "shopping_mall",
              "store"
            ],
            "spatialRelationship": "WITHIN",
            "straightLineDistanceMeters": 133.72855
          },
          {
            "name": "places/ChIJ62_oCR7Lj4AR_MGWkSPotD4",
            "placeId": "ChIJ62_oCR7Lj4AR_MGWkSPotD4",
            "displayName": {
              "text": "Nordstrom",
              "languageCode": "en"
            },
            "types": [
              "clothing_store",
              "department_store",
              "establishment",
              "point_of_interest",
              "shoe_store",
              "store"
            ],
            "straightLineDistanceMeters": 250.99161
          },
          {
            "name": "places/ChIJ8WvuSB7Lj4ARFyHppkxDRQ4",
            "placeId": "ChIJ8WvuSB7Lj4ARFyHppkxDRQ4",
            "displayName": {
              "text": "Macy's",
              "languageCode": "en"
            },
            "types": [
              "clothing_store",
              "department_store",
              "establishment",
              "point_of_interest",
              "store"
            ],
            "straightLineDistanceMeters": 116.24196
          },
          {
            "name": "places/ChIJ9d3plB_Lj4ARzyaU5bn80WY",
            "placeId": "ChIJ9d3plB_Lj4ARzyaU5bn80WY",
            "displayName": {
              "text": "Bank of America Financial Center",
              "languageCode": "en"
            },
            "types": [
              "bank",
              "establishment",
              "finance",
              "point_of_interest"
            ],
            "straightLineDistanceMeters": 121.61515
          },
          {
            "name": "places/ChIJaXCjxvXLj4ARCPmQpvJ52Lw",
            "placeId": "ChIJaXCjxvXLj4ARCPmQpvJ52Lw",
            "displayName": {
              "text": "Bloomingdale's",
              "languageCode": "en"
            },
            "types": [
              "clothing_store",
              "department_store",
              "establishment",
              "furniture_store",
              "home_goods_store",
              "point_of_interest",
              "shoe_store",
              "store"
            ],
            "straightLineDistanceMeters": 81.32396
          }
        ],
        "areas": [
          {
            "name": "places/ChIJb3F-EB7Lj4ARnHApQ_Hu1gI",
            "placeId": "ChIJb3F-EB7Lj4ARnHApQ_Hu1gI",
            "displayName": {
              "text": "Westfield Valley Fair",
              "languageCode": "en"
            },
            "containment": "WITHIN"
          },
          {
            "name": "places/ChIJXYuykB_Lj4AR1Ot8nU5q26Q",
            "placeId": "ChIJXYuykB_Lj4AR1Ot8nU5q26Q",
            "displayName": {
              "text": "Valley Fair",
              "languageCode": "en"
            },
            "containment": "WITHIN"
          },
          {
            "name": "places/ChIJtYoUX2DLj4ARKoKOb1G0CpM",
            "placeId": "ChIJtYoUX2DLj4ARKoKOb1G0CpM",
            "displayName": {
              "text": "Central San Jose",
              "languageCode": "en"
            },
            "containment": "WITHIN"
          }
        ]
      }
    },
    /.../
  ]
}

العثور على أنشطة تجارية ستفتح في المستقبل

يعرض المثال التالي طلبًا باستخدام Text Search (New) للبحث عن مؤسسات ستفتح في المستقبل في New Meadows، أيداهو:

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.id,places.displayName,places.businessStatus,places.openingDate" \
-d '{
  "textQuery": "Roberts Greenhouse and Tree Farm",
  "includeFutureOpeningBusinesses": true,
  "maxResultCount": 20,
  "locationBias": {
    "circle": {
      "center": {"latitude": 44.9755100, "longitude": -116.2842180},
      "radius": 20
    }
  }
}' \
"https://places.googleapis.com/v1/places:searchText"

يتضمّن الردّ المؤسسات التي سيتم افتتاحها في المستقبل، بالإضافة إلى حالة المؤسسة وتاريخ الافتتاح المتوقّع:

{
  "places": [
    {
      "id": "ChIJp1-VoKWJplQRMz8g-7Wa3Do",
      "businessStatus": "FUTURE_OPENING",
      "displayName": {
        "text": "Roberts Greenhouse and Tree Farm",
        "languageCode": "en"
      },
      "openingDate": {
        "year": 2026,
        "month": 4,
        "day": 15
      }
    }
  ]
}

الحصول على معلومات عن محطات النقل العام

يمكنك استخدام Text Search (New) للعثور على محطات النقل العام. يتضمّن نص الرد معلومات عن المحطة، بما في ذلك اسم المحطة ومؤسسات النقل العام التابعة لها وخطوط النقل العام التي تخدم المحطة. بالإضافة إلى ذلك، يتضمّن الرد رمز مركبة وألوانًا يمكنك استخدامها لعرض معلومات محطة النقل العام.

يوضّح المثال التالي طلبًا بشأن "محطة غراند سنترال":

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.id,places.displayName,places.transitStation" \
-d '{
  "textQuery": "Grand Central Station"
}' \
"https://places.googleapis.com/v1/places:searchText"

يتضمّن نص الاستجابة معلومات عن كل محطة ضمن نصف القطر، والخطوط التي تخدمها المحطة، والتنبيهات الصادرة عن مؤسسات النقل العام في تلك المحطة، ومعلومات المغادرة:

{
  "places": [
    {
      "id": "ChIJhRwB-yFawokRi0AhGH87UTc",
      "displayName": {
        "text": "Grand Central",
        "languageCode": "en"
      },
      "transitStation": {
        "displayName": {
          "text": "Grand Central",
          "languageCode": "en"
        },
        "agencies": [
          {
            "displayName": {
              "text": "Metro-North Railroad",
              "languageCode": "en"
            },
            "url": "http://www.mta.info/mnr",
            "lines": [
              {
                "id": "ChIJOXpD29y2wokRryDO0CocwK0",
                "vehicleType": "HEAVY_RAIL",
                "displayName": {
                  "text": "Harlem",
                  "languageCode": "en"
                },
                "textColor": "#FFFFFF",
                "backgroundColor": "#0061AA",
                "vehicleIcon": {
                  "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/rail2.svg"
                },
                "alerts": [
                  {
                    "effect": "OTHER",
                    "texts": [
                      {
                        "headline": {
                          "text": "Information",
                          "languageCode": "en"
                        },
                        "summary": {
                          "text": "Temporary platforms are in place at Botanical Garden, Williams Bridge, and Woodlawn for northbound travel. Build in extra travel time to reach the platform.",
                          "languageCode": "en"
                        },
                        "fullDescription": {
                          "text": "What's Happening? We are renovating some Harlem Line stations in the Bronx. Learn more about the project here.",
                          "languageCode": "en"
                        }
                      }
                    ],
                    "detailsUrls": [
                      {
                        "url": "https://new.mta.info/"
                      }
                    ],
                    "cause": "OTHER_CAUSE",
                    "startTime": "2026-04-16T04:00:00Z",
                    "endTime": "2026-12-01T04:45:00Z",
                    "attribution": {
                      "link": {
                        "text": "new.mta.info",
                        "url": "https://new.mta.info/"
                      }
                    },
                    "createTime": "2026-05-15T22:39:30Z",
                    "severityLevel": "INFO"
                  }
                ]
              },
              ...
            ]
          },
          ...
        ]
        "stops": [
          {
            "id": "ChIJOfdrigFZwokRJPllLwfPrJY",
            "location": {
              "latitude": 40.752823,
              "longitude": -73.977195999999992
            },
            "wheelchairAccessibleEntrance": true
          }
        ],
        "departureBoards": [
          {
            "displayType": "TIME_CENTRIC",
            "rows": [
              {
                "departures": [
                  {
                    "timedDeparture": {
                      "scheduledTime": "2026-05-15T22:42:00Z",
                      "timingType": "SCHEDULED",
                      "predictedTime": "2026-05-15T22:42:00Z",
                      "updateTime": "2026-05-15T22:38:50Z"
                    },
                    "originallyScheduledStopId": "ChIJOfdrigFZwokRJPllLwfPrJY",
                    "lineId": "ChIJAfBuQhwg6IkRYnFpClHxFrM"
                  }
                ]
              },
              ...
            ]
          }
        ]
      }
    },
    {
      "id": "ChIJ_4EAi-pZwokRWe5T1JmmWmc",
      "displayName": {
        "text": "Grand Central Station",
        "languageCode": "en"
      }
    }
  ]
}

يمكنك طلب الحصول على نقاط دخول ونقاط تنقّل لوجهة معيّنة. تحدّد المداخل نقاط الدخول والخروج من مكان معيّن (على سبيل المثال، بوابات مختلفة في مطار أو مركز تجاري). تحدّد نقاط التنقّل المواقع الجغرافية على جانب الطريق التي يجب أن ينتهي عندها التنقّل، وهو أمر مفيد لتوجيه المستخدمين إلى الجانب الصحيح من الطريق أو إلى نقطة نزول محدّدة.

تعرض نقاط التنقّل navigationPointToken. يمكنك تمرير هذا الرمز المميّز إلى حزمة تطوير البرامج للتنقّل (المتاحة على Android أو iOS) أو إلى Routes API لتوجيه السائقين إلى هذا الموقع الجغرافي المحدّد. لمزيد من المعلومات، يُرجى الاطّلاع على رموز نقاط التنقّل.

يعرض المثال التالي طلب "بحث نصي (جديد)" عن "مطار سان فرانسيسكو الدولي" يتضمّن entrances وnavigationPoints في قناع الحقل:

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.id,places.displayName,places.entrances,places.navigationPoints" \
-d '{
  "textQuery": "San Francisco International Airport",
  "pageSize": 1
}' \
"https://places.googleapis.com/v1/places:searchText"

يتضمّن الردّ مداخل المكان ونقاط التنقّل فيه:

{
  "places": [
    {
      "id": "ChIJVVVVVYx3j4ARP-3NGldc8qQ",
      "displayName": {
        "text": "San Francisco International Airport",
        "languageCode": "en"
      },
      "entrances": [
        {
          "location": {
            "latitude": 37.6172154,
            "longitude": -122.3839724
          }
        },
        {
          "location": {
            "latitude": 37.6174073,
            "longitude": -122.384196
          }
        },
        ...
      ],
      "navigationPoints": [
        {
          "navigationPointToken": "ChIJoioBjMLOQkAR0A3yH_eYXsA...",
          "displayName": {
            "text": "International Terminal Departures Level",
            "languageCode": "en"
          },
          "location": {
            "latitude": 37.6153121,
            "longitude": -122.3900833
          },
          "travelModes": ["WALK"]
        },
        {
          "navigationPointToken": "ChIJy5JKws_OQkAROx0jNN2YXsA...",
          "displayName": {
            "text": "Domestic Garage - SFO Short Term Parking",
            "languageCode": "en"
          },
          "location": {
            "latitude": 37.6157153,
            "longitude": -122.3885012
          },
          "travelModes": ["DRIVE", "WALK"],
          "usages": ["PARKING"]
        },
        ...
      ]
    }
  ]
}

جرِّبها الآن.

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

انقر على رمز واجهة برمجة التطبيقات api على يسار الصفحة.
يمكنك تعديل مَعلمات الطلب إذا أردت.
انقر على الزر تنفيذ. في مربّع الحوار، اختَر الحساب الذي تريد استخدامه لتقديم الطلب.
في لوحة "مستكشف واجهات برمجة التطبيقات"، انقر على رمز ملء الشاشة fullscreen لتوسيع نافذة "مستكشف واجهات برمجة التطبيقات".

البحث النصي (جديد) تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

مقدمة

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

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

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

FieldMask

textQuery

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

includeFutureOpeningBusinesses

includedType

includePureServiceAreaBusinesses

languageCode

locationBias

locationRestriction

maxResultCount (متوقّفة نهائيًا)

evOptions

connectorTypes

minimumChargingRateKw

minRating

openNow

pageSize

pageToken

priceLevels

rankPreference

regionCode

strictTypeFiltering