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

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

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

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

"10 High Street, UK" أو "123 Main Street, US" شوارع رئيسية متعددة في المملكة المتحدة، شوارع رئيسية متعددة في الولايات المتحدة لا يعرض طلب البحث النتائج المطلوبة ما لم يتم تحديد قيد على الموقع الجغرافي.
"ChainRestaurant New York" مواقع جغرافية متعدّدة لخدمة "ChainRestaurant" في نيويورك، بدون عنوان شارع أو حتى اسم شارع
"10 High Street, Escher UK" أو "123 Main Street, Pleasanton US" هناك شارع واحد فقط يُسمى "High Street" في مدينة Escher بالمملكة المتحدة، وشارع واحد فقط يُسمى "Main Street" في مدينة Pleasanton بولاية كاليفورنيا الأمريكية.
"UniqueRestaurantName New York" هناك مؤسسة واحدة فقط بهذا الاسم في القاهرة، ولا حاجة إلى عنوان شارع للتمييز بينها وبين غيرها.
"مطاعم بيتزا في القاهرة" يحتوي طلب البحث هذا على قيود الموقع الجغرافي، و "مطاعم البيتزا" هو نوع مكان محدّد بوضوح. ويعرض نتائج متعدّدة.
"‎+1 514-670-8700"

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

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

جرِّبه الآن

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

طلب البحث عن نص هو طلب POST لبروتوكول HTTP بالشكل التالي:

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: *

    حدِّد حقلًا واحدًا أو أكثر من الحقول التالية:

    • تؤدي الحقول التالية إلى تنشيط بحث النص (رقم التعريف فقط) لرموز التخزين التعريفية:

      places.attributions، places.id، places.name*، nextPageToken

      * يحتوي الحقل places.name على مكان اسم المورد في الشكل: places/PLACE_ID. استخدِم places.displayName للوصول إلى الاسم النصي للمكان.

    • تؤدي الحقول التالية إلى تنشيط رمز التخزين التعريفي للبحث النصي (أساسي):

      places.accessibilityOptions، places.addressComponents، places.adrFormatAddress، places.businessStatus، places.containingPlaces، places.displayName، places.formattedAddress، places.googleMapsLinks*، places.googleMapsUri، places.iconBackgroundColor، places.iconMaskBaseUri، places.location، places.photos، places.plusCode، places.primaryType، places.primaryTypeDisplayName، places.pureServiceAreaBusiness، places.shortFormattedAddress، places.subDestinations، places.types، places.utcOffsetMinutes، places.viewport

      * يُرجى العِلم أنّ الحقل places.googleMapsLinks في مرحلة معاينة الإصدار العلني ولا يتم تحصيل أي رسوم، أي أنّ الفوترة ستكون 0 دولار أمريكي مقابل الاستخدام أثناء مرحلة المعاينة.

    • تؤدي الحقول التالية إلى تنشيط رمز التخزين التعريفي للبحث النصي (المتقدّم):

      places.currentOpeningHours، places.currentSecondaryOpeningHours، places.internationalPhoneNumber، places.nationalPhoneNumber، places.priceLevel، places.priceRange، places.rating، places.regularOpeningHours، places.regularSecondaryOpeningHours، places.userRatingCount، places.websiteUri

    • تؤدي الحقول التالية إلى تنشيط رمز التخزين التعريفي (المفضّل) للبحث النصي:

      places.allowsDogs places.curbsidePickup places.delivery places.dineIn places.editorialSummary places.evChargeOptions places.fuelOptions places.goodForChildren places.goodForGroups places.goodForWatchingSports places.liveMusic places.menuForChildren places.parkingOptions places.paymentOptions places.outdoorSeating places.reservable places.restroom places.reviews places.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 شارع رئيسي" أو "أفضل مكان للزيارة في القاهرة". تعرض واجهة برمجة التطبيقات المطابقات المحتمَلة استنادًا إلى هذه السلسلة وترتيب النتائج استنادًا إلى مدى صلتها بالمعلومات المطلوبة.

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

  • includedType

    لحصر النتائج بالأماكن التي تتطابق مع النوع المحدّد في الجدول "أ" يمكن تحديد نوع واحد فقط. على سبيل المثال:

    • "includedType":"bar"
    • "includedType":"pharmacy"

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

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

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

  • evOptions

    تحدّد المَعلمات لتحديد قوابس شحن المركبات الكهربائية المتاحة ومعدّلات الشحن.

    • connectorTypes

      الفلترة حسب نوع موصل شحن المركبات الكهربائية المتاح في مكان معيّن سيتم فلترة المكان الذي لا يتيح استخدام أي من أنواع الموصّلات. تشمل أنواع موصلات شحن المركبات الكهربائية المتوافقة شواحن AC وDC المدمجة وشواحن Tesla وشواحن متوافقة مع معيار GB/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، أعرض جميع الأنشطة التجارية بغض النظر عن حالة الفتح. يتم عرض الأماكن التي لا تحدّد ساعات العمل في قاعدة بيانات "أماكن Google" إذا ضبطت هذه المَعلمة على false.

  • pageSize

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

  • pageToken

    تُحدِّد nextPageToken من نص الاستجابة للصفحة السابقة.

  • priceLevels

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

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

    على سبيل المثال:

    "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

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

حصر المنطقة باستخدام 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"
}

جرّب الآن

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

  1. انقر على رمز واجهة برمجة التطبيقات وسِّع "مستكشف واجهات برمجة التطبيقات". على يسار الصفحة.

  2. يمكنك اختياريًا توسيع عرض المَعلمات العادية وضبط مَعلمة fields على قناع الحقل.

  3. يمكنك اختياريًا تعديل نص الطلب.

  4. انقر على الزر تنفيذ. في مربّع الحوار المنبثق، اختَر الحساب الذي تريد استخدامه لتقديم الطلب.

  5. في لوحة "مستكشف واجهات برمجة التطبيقات"، انقر على رمز التوسيع، وسِّع "مستكشف واجهات برمجة التطبيقات".، لتوسيع نافذة "مستكشف واجهات برمجة التطبيقات".