مقدمة
تعرض خدمة Text Search (New) معلومات عن مجموعة من الأماكن استنادًا إلى سلسلة نصية (على سبيل المثال، "بيتزا في القاهرة" أو "متاجر أحذية بالقرب من الرياض" أو "شارع التحرير 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'استجابات البحث النصي (الجديد)
تعرض خدمة البحث النصي (New) عنصر JSON كاستجابة. في الردّ:
- تحتوي مصفوفة
placesعلى جميع الأماكن المطابقة. - يتم تمثيل كل مكان في المصفوفة بواسطة عنصر
Place. يحتوي العنصرPlaceعلى معلومات تفصيلية حول مكان واحد. - يحدّد FieldMask الذي تم تمريره في الطلب قائمة الحقول التي يتم عرضها في كائن
Place. - لا نضمن أن تكون قائمة الأماكن المعروضة متسقة مع الطلبات المتطابقة.
يكون عنصر JSON الكامل على النحو التالي:
{
"places": [
{
object (Place)
}
]
}المعلمات المطلوبة
-
FieldMask
حدِّد قائمة الحقول التي تريد عرضها في الردّ من خلال إنشاء قناع حقل ردّ. مرِّر قناع حقل الاستجابة إلى الطريقة باستخدام مَعلمة عنوان URL
$fieldsأوfields، أو باستخدام عنوان HTTPX-Goog-FieldMask. لا تتوفّر قائمة تلقائية بالحقول المعروضة في الردّ. إذا حذفت قناع الحقل، ستعرض الطريقة خطأ.يُعدّ إخفاء الحقول من الممارسات الجيدة في التصميم لضمان عدم طلب بيانات غير ضرورية، ما يساعد في تجنُّب وقت المعالجة ورسوم الفوترة غير الضرورية.
حدِّد قائمة قيم مفصولة بفاصلة لأنواع بيانات الأماكن التي تريد عرضها. على سبيل المثال، لاسترداد الاسم المعروض وعنوان المكان.
X-Goog-FieldMask: places.displayName,places.formattedAddress
استخدِم
*لاسترداد جميع الحقول.X-Goog-FieldMask: *
حدِّد حقلاً واحدًا أو أكثر من الحقول التالية:
تؤدي الحقول التالية إلى تفعيل رمز التخزين التعريفي (SKU) لخدمة Text Search Essentials (المعرّف فقط):
places.attributions
places.id
places.consumerAlert
places.name*
nextPageToken
places.movedPlace
places.movedPlaceId* يحتوي الحقل
places.nameعلى اسم المورد الخاص بالمكان بالصيغة:places/PLACE_ID. استخدِمplaces.displayNameفي رمز التخزين التعريفي Pro للوصول إلى الاسم النصي للمكان.للحصول على قائمة كاملة بالحقول ورموز التخزين التعريفية المرتبطة بها، يُرجى الاطّلاع على حقول بيانات الأماكن (الجديدة).
تؤدي الحقول التالية إلى تفعيل رمز التخزين التعريفي لميزة 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
سلسلة النص المطلوب البحث عنها على سبيل المثال، "مطعم" أو "شارع الحمراء" أو "أفضل مكان للزيارة في بيروت". تعرض واجهة برمجة التطبيقات المطابقات المرشحة استنادًا إلى هذه السلسلة وترتب النتائج استنادًا إلى مدى صلتها بالموضوع.
لا تهدف خدمة Text Search (New) إلى معالجة طلبات البحث الغامضة، بما في ذلك ما يلي:
نوع طلب البحث مثال عدد كبير جدًا من المفاهيم أو القيود، مثل أسماء أماكن أو طرق أو مدن متعددة في طلب بحث واحد "Market Street San Francisco San Jose Airport" عناصر العنوان البريدي غير الممثَّلة على "خرائط Google" "C/O John Smith 123 Main Street"
"P.O. Box 13 San Francisco"أسماء الأنشطة التجارية أو السلاسل أو الفئات المدمجة مع المواقع الجغرافية التي لا تتوفّر فيها هذه الكيانات "Tesco بالقرب من دالاس، تكساس" طلبات البحث الغامضة التي تحتمل تفسيرات متعددة "تسليم الشاحن" الأسماء السابقة التي لم تعُد مستخدَمة "Middlesex United Kingdom" عناصر أو نية غير مرتبطة بالموقع الجغرافي "كم عدد القوارب في ميناء فينتورا؟" الأسماء غير الرسمية أو المخصّصة "The Jenga"
"The Helter Skelter"إحداثيات خطوط العرض وخطوط الطول "37.422131,-122.084801"
المعلمات الاختيارية
-
includeFutureOpeningBusinesses
إذا كانت القيمة
true، يتم عرض المؤسسات التي من المتوقّع افتتاحها في المستقبل. القيمة التلقائية هيfalse.
لاسترداد حالة المؤسسة، يُرجى تضمينplaces.businessStatusفي قناع حقل الطلب. لاسترداد تاريخ الافتتاح المتوقّع للنشاط التجاري، أدرِجplaces.openingDateفي قناع حقل الطلب. -
includedType
يؤدي إلى تحيز النتائج إلى الأماكن التي تطابق النوع المحدّد في الجدول "أ". يمكنك تحديد نوع واحد فقط. على سبيل المثال:
"includedType":"bar""includedType":"pharmacy"
يطبّق البحث النصي (الجديد) فلترة الأنواع على طلبات بحث معيّنة، حسب مدى ملاءمتها. على سبيل المثال، قد لا يتم تطبيق فلترة النوع على طلبات البحث عن عناوين محدّدة ("شارع النصر 123")، ولكن يتم تطبيق فلترة النوع دائمًا تقريبًا على طلبات البحث عن فئات ("متاجر قريبة" أو "مراكز تسوّق").
لتطبيق فلترة النوع على جميع طلبات البحث، اضبط
strictTypeFilteringعلىtrue. -
includePureServiceAreaBusinesses
في حال ضبط هذه المَعلمة على
true، يتضمّن الردّ المؤسسات التي تقدّم خدماتها من خلال الانتقال إلى المواقع الجغرافية للعملاء أو توصيل الخدمة إليهم مباشرةً، ولكنّها لا تمتلك موقعًا جغرافيًا يمكن للعملاء زيارته. إذا تم ضبطها علىfalse، ستعرض واجهة برمجة التطبيقات الأنشطة التجارية التي لها موقع جغرافي فقط. languageCode
اللغة التي سيتم عرض النتائج بها
- اطّلِع على قائمة اللغات المتاحة. تعدّل Google اللغات المتاحة بشكل متكرر، لذا قد لا تكون هذه القائمة شاملة.
-
في حال عدم توفير
languageCode، يتم ضبط واجهة برمجة التطبيقات تلقائيًا علىen. إذا حدّدت رمز لغة غير صالح، ستعرض واجهة برمجة التطبيقات الخطأINVALID_ARGUMENT. - تبذل واجهة برمجة التطبيقات قصارى جهدها لتوفير عنوان شارع يمكن قراءته لكل من المستخدم والسكان المحليين. لتحقيق هذا الهدف، تعرض عناوين الشوارع باللغة المحلية، وتتم كتابتها بأحرف أبجدية أخرى يمكن للمستخدم قراءتها إذا لزم الأمر، مع مراعاة اللغة المفضّلة. ويتم عرض جميع العناوين الأخرى باللغة المفضّلة. يتم عرض جميع مكوّنات العنوان باللغة نفسها، والتي يتم اختيارها من المكوّن الأول.
- إذا لم يكن الاسم متاحًا باللغة المفضّلة، تستخدم واجهة برمجة التطبيقات أقرب نتيجة مطابقة.
- تؤثر اللغة المفضّلة بشكل بسيط في مجموعة النتائج التي تختار واجهة برمجة التطبيقات عرضها، وفي ترتيب عرضها. تفسّر أداة الترميز الجغرافي الاختصارات بشكل مختلف حسب اللغة، مثل اختصارات أنواع الشوارع أو المرادفات التي قد تكون صالحة في لغة واحدة ولكن ليس في لغة أخرى.
locationBias
تحدّد هذه السمة منطقة للبحث. يُعدّ هذا الموقع الجغرافي بمثابة تحيّز، ما يعني أنّه يمكن عرض النتائج حول الموقع الجغرافي المحدّد، بما في ذلك النتائج خارج المنطقة المحدّدة.
يمكنك تحديد
locationRestrictionأوlocationBias، ولكن ليس كليهما. يمكنك اعتبارlocationRestrictionعلى أنّها تحدّد المنطقة التي يجب أن تكون النتائج ضمنها، و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على أنّها تحدّد المنطقة التي من المرجّح أن تكون النتائج داخلها أو بالقرب منها ولكن يمكن أن تكون خارجها.evOptions
تحدّد هذه السمة مَعلمات لتحديد وصلات شحن المركبات الكهربائية المتاحة ومعدّلات الشحن.
connectorTypes
تتم الفلترة حسب نوع وصلة شحن المركبات الكهربائية المتاحة في مكان معيّن. سيتم استبعاد أي مكان لا يتوافق مع أي من أنواع الموصلات. تشمل أنواع موصلات شحن المركبات الكهربائية المتوافقة الشواحن المجمّعة (التي تعمل بالتيار المتردد والتيار المستمر) وشواحن Tesla والشواحن المتوافقة مع معيار GB/T (للشحن السريع للمركبات الكهربائية في الصين) وشواحن مقابس الحائط. لمزيد من المعلومات، يُرجى الاطّلاع على المستندات المرجعية.
- لفلترة النتائج بحثًا عن موصل متوافق معيّن، اضبط
connectorTypesعلى هذه القيمة. على سبيل المثال، للعثور على موصلات J1772 من النوع 1، اضبطconnectorTypesعلىEV_CONNECTOR_TYPE_J1772. - لفلترة النتائج الخاصة بالموصلات غير المتوافقة، اضبط
connectorTypesعلىEV_CONNECTOR_TYPE_OTHER. - لفلترة النتائج حسب أي نوع موصِّل يمثّل مقبس حائط، اضبط
connectorTypesعلىEV_CONNECTOR_TYPE_UNSPECIFIED_WALL_OUTLET. - لفلترة النتائج لأي نوع موصِّل، اضبط
connectorTypesعلىEV_CONNECTOR_TYPE_UNSPECIFIEDأو لا تضبط قيمة لـconnectorTypes.
- لفلترة النتائج بحثًا عن موصل متوافق معيّن، اضبط
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، يتم عرض جميع المؤسسات بغض النظر عن حالة فتحها. يتم عرض الأماكن التي لا تحدّد ساعات العمل في قاعدة بيانات "الأماكن على Google" إذا ضبطت هذه المَعلمة علىfalse.pageSize
تحدّد عدد النتائج التي سيتم عرضها في كل صفحة، على أن يتراوح بين 1 و20. على سبيل المثال، يؤدي ضبط قيمة
pageSizeعلى 5 إلى عرض ما يصل إلى 5 نتائج في الصفحة الأولى. إذا كان بإمكان طلب البحث عرض المزيد من النتائج، سيتضمّن الردّnextPageTokenيمكنك تمريره في طلب لاحق للوصول إلى الصفحة التالية.يحلّ هذا الحقل محلّ الحقل
maxResultCountالذي تم إيقافه نهائيًا. إذا حدّدت كلاً منpageSizeوmaxResultCount، ستستخدم واجهة برمجة التطبيقاتpageSizeوتتجاهلmaxResultCount.pageToken
يحدّد
nextPageTokenمن نص الاستجابة للصفحة السابقة.-
priceLevels
يمكنك حصر البحث على الأماكن التي تم وضع علامة عليها بمستويات أسعار معيّنة. الإعداد التلقائي هو اختيار جميع مستويات الأسعار.
يمكن توقّع مستويات الأسعار للأماكن من الأنواع التالية:
لن يتم تضمين الأماكن من الأنواع غير المتوافقة في الردّ في حال تحديد
priceLevels.حدِّد مصفوفة من قيمة واحدة أو أكثر يحدّدها
PriceLevel.على سبيل المثال:
"priceLevels":["PRICE_LEVEL_INEXPENSIVE", "PRICE_LEVEL_MODERATE"]
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فقط. عند ضبطها على "خطأ"، وهو الإعداد التلقائي، يمكن أن يحتوي الردّ على أماكن لا تتطابق مع الأنواع المحدّدة.
أمثلة على البحث النصي (جديد)
العثور على مكان باستخدام سلسلة طلب البحث
يوضّح المثال التالي طلب "بحث نصي (جديد)" عن "طعام نباتي حار في سيدني، أستراليا":
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" } }, ... ] }
أضِف المزيد من أنواع البيانات إلى قناع الحقل لعرض معلومات إضافية.
على سبيل المثال، أضِف 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
استخدِم المَعلمة 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" }, ... ] } }, { "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" } ] } }, ... ] }
البحث عن مؤسسات ضمن منطقة الخدمة
استخدِم المَعلمة 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" } }, { "displayName": { "text": "Starboy Plumbing Inc.", "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" }, ... ], "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" }, ... ], "nextPageToken": "AeCrKXvPd6uUy-oj96W2OaqEe2pUD8QTxOM8-sKfUcFsC9t2Wey5qivrKGoGSxcZnyc7RPmaFfAktslrKbUh31ZDTkL0upRmaxA7c_c" }
الحصول على واصفات العناوين
توفّر واصفات العناوين معلومات علائقية عن الموقع الجغرافي لمكان معيّن، بما في ذلك المعالم القريبة والمناطق المحيطة.
يعرض المثال التالي طلب "البحث النصي (الجديد)" عن أماكن بالقرب من مركز تسوّق في سان خوسيه. في هذا المثال، يمكنك تضمين 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 }, ... ], "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" }, ... ] } }, ... ] }
العثور على الأنشطة التجارية التي ستفتح في المستقبل
يعرض المثال التالي طلب "البحث النصي (الجديد)" عن الأنشطة التجارية التي سيتم افتتاحها في المستقبل في نيو ميدوز، أيداهو:
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. يمكنك تمرير هذا الرمز المميّز إلى حزمة تطوير البرامج (SDK) للتنقّل (المتاحة لنظامَي التشغيل 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 على يسار الصفحة.
يمكنك تعديل مَعلمات الطلب إذا أردت.
انقر على الزر تنفيذ. في مربّع الحوار، اختَر الحساب الذي تريد استخدامه لتقديم الطلب.
في لوحة "مستكشف واجهات برمجة التطبيقات"، انقر على رمز ملء الشاشة ملء الشاشة لتوسيع نافذة "مستكشف واجهات برمجة التطبيقات".