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

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

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

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

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

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

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

جرِّبه الآن

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

طلب البحث النصي هو طلب 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: *
    تختار

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

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

      places.id، places.name*

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

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

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

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

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

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

      places.allowsDogs، places.curbsidePickup، places.delivery، places.dineIn، places.editorialSummary، places.evChargeOptions، places.fuelOptions، places.goodForChildren، places.goodForGroups، places.goodForWatchingSports، places.liveMusic، places.menuForChildren، places.parkingOptions، places.paymentOptions، places.outdoorSeating، places.reservable، places.restroom، places.reviews، places.servesBeer، places.servesBreakfastplaces.servesBrunchplaces.servesCocktailsplaces.servesCoffeeplaces.servesDessertsplaces.servesDinnerplaces.servesLunchplaces.servesVegetarianFoodplaces.servesWineplaces.takeout

  • textQuery

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

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

  • includedType

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

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

  • languageCode

    اللغة التي يتم عرض النتائج بها.

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

  • locationBias

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

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

    حدِّد المنطقة كإطار عرض مستطيل أو دائرة.

    • يتم تحديد الدائرة بنقطة المركز ونصف القطر بالمتر. ويجب أن يتراوح النطاق الجغرافي بين 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

      الفلاتر حسب نوع وصلة شحن المركبات الكهربائية المتوفّرة في مكان معيّن وسيتم استبعاد أي مكان لا يتوافق مع أي من أنواع الموصلات. تشمل أنواع موصلات شحن المركبات الكهربائية المتوافقة شواحن مجمَّعة (تيار متردد وتيار مستمر) وشواحن Tesla وشواحن متوافقة مع GB/T (للشحن السريع للمركبات الكهربائية في الصين) وشواحن منافذ حائط. لمزيد من المعلومات، يُرجى الاطّلاع على المستندات المرجعية.

    • 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 يمكنك تمريره إلى طلب لاحق للوصول إلى الصفحة التالية.

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

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

curl -X POST -d '{
  "textQuery" : "Spicy 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
          }
        ]
      }
    }
  ]
}

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

استخدِم مَعلمة 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. في لوحة "مستكشف واجهة برمجة التطبيقات"، انقر على رمز التوسيع، وسِّع "مستكشف واجهات برمجة التطبيقات".، لتوسيع نافذة مستكشف واجهة برمجة التطبيقات.