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

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

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

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

"10 High Street, UK" أو "123 الشارع الرئيسي، الولايات المتحدة" العديد من متاجر "هاي ستريت" في المملكة المتحدة العديد من "الشوارع الرئيسية" في الولايات المتحدة. لا يعرض طلب البحث نتائج مرغوبة ما لم يكن تقييد الموقع تعيين.
"مطعم تابع لسلسلة في نيويورك" عدة "مطعم تابع لسلسلة" المختلفة في نيويورك؛ لا يوجد عنوان شارع أو حتى اسم الشارع.
"10 High Street, Escher UK" أو "123 الشارع الرئيسي, بليسانتون الولايات المتحدة" شارع "هاي ستريت" واحد فقط في مدينة إيشر بالمملكة المتحدة؛ "شارع رئيسي" واحد فقط في مدينة بليسانتون بولاية كاليفورنيا الأمريكية.
"UniqueRestaurantName في نيويورك" مؤسسة واحدة فقط بهذا الاسم في نيويورك؛ لا يوجد عنوان شارع اللازمة للتمييز.
"مطاعم البيتزا في دبي" يتضمن طلب البحث هذا قيود الموقع، و"مطاعم البيتزا" CANNOT TRANSLATE نوع مكان محدد جيدًا. ويؤدي إلى إرجاع نتائج متعددة.
" +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.attributions, places.id, places.name*، nextPageToken

      * يحتوي الحقل 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.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"

  • 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

    تحدّد مَعلمات تحديد المركبة الكهربائية المتوفّرة (EV) موصلات الشحن ومعدّلات الشحن

    • connectorTypes

      الفلاتر حسب نوع وصلة شحن المركبات الكهربائية المتوفّرة في مكان معيّن حاسمة المكان الذي لا يدعم أي نوع من أنواع الموصلات سيتم تصفيته . تشمل أنواع موصلات شحن المركبات الكهربائية المتوافقة كلاً من (AC وDC) شواحن، وشواحن 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 من أجل ابحث عن أماكن تتوفّر فيها شواحن ومتوافقة مع مركبتك الكهربائية.

يوضح المثال التالي طلبًا لشحن مركبة كهربائية من النوع 1 لـ Tesla وJ1772 الموصلات التي يكون الحد الأدنى لمعدل شحنها 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. في لوحة "مستكشف واجهة برمجة التطبيقات"، حدد رمز التوسيع، وسِّع "مستكشف واجهات برمجة التطبيقات".، لتوسيع نافذة مستكشف واجهة برمجة التطبيقات