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

اختيار النظام الأساسي: Android iOS JavaScript Web Service

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

مقدمة

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

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

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

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

طلب البحث النصي (جديد) هو طلب HTTP POST بالصيغة التالية:

https://places.googleapis.com/v1/places:searchText

مرِّر جميع المَعلمات في نص طلب JSON أو في العناوين كجزء من طلب POST. على سبيل المثال:

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.priceLevel' \
'https://places.googleapis.com/v1/places:searchText'

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

تعرض خدمة "البحث النصي" (جديدة) عنصر JSON كاستجابة. في الردّ:

  • تحتوي المصفوفة places على جميع الأماكن المطابقة.
  • يتم تمثيل كل مكان في المصفوفة بكائن Place. يحتوي العنصر Place على معلومات مفصّلة حول مكان واحد.
  • تحدّد FieldMask التي تم تمريرها في الطلب قائمة الحقول المعروضة في الكائن Place.
  • لا نضمن أن تكون قائمة الأماكن التي يتم عرضها متسقة مع الطلبات المتطابقة.

يكون عنصر JSON الكامل بالشكل التالي:

{
  "places": [
    {
      object (Place)
    }
  ]
}

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

  • FieldMask

    حدِّد قائمة الحقول التي سيتم عرضها في الاستجابة من خلال إنشاء قناع حقل الاستجابة. مرِّر قناع حقل الاستجابة إلى الطريقة باستخدام مَعلمة عنوان URL $fields أو fields، أو باستخدام عنوان HTTP X-Goog-FieldMask. لا توجد قائمة تلقائية بالحقول التي يتم عرضها في الردّ. إذا حذفت قناع الحقل، ستعرض الطريقة رسالة خطأ.

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

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

    X-Goog-FieldMask: places.displayName,places.formattedAddress

    استخدِم * لاسترداد جميع الحقول.

    X-Goog-FieldMask: *

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

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

      places.attributions
      places.id
      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.googleMapsUri
      places.iconBackgroundColor
      places.iconMaskBaseUri
      places.location
      places.photos
      places.plusCode
      places.postalAddress
      places.primaryType
      places.primaryTypeDisplayName
      places.pureServiceAreaBusiness
      places.shortFormattedAddress
      places.searchUri
      places.subDestinations
      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.userRatingCount
      places.websiteUri

    • تؤدي الحقول التالية إلى تفعيل رمز التخزين التعريفي "بحث نصي" للمؤسسات + "الغلاف الجوي":

      places.allowsDogs
      places.curbsidePickup
      places.delivery
      places.dineIn
      places.editorialSummary
      places.evChargeAmenitySummary
      places.evChargeOptions
      places.fuelOptions
      places.generativeSummary
      places.goodForChildren
      places.goodForGroups
      places.goodForWatchingSports
      places.liveMusic
      places.menuForChildren
      places.neighborhoodSummary
      places.parkingOptions
      places.paymentOptions
      places.outdoorSeating
      places.reservable
      places.restroom
      places.reviews
      places.reviewSummary
      routingSummaries*
      places.servesBeer
      places.servesBreakfast
      places.servesBrunch
      places.servesCocktails
      places.servesCoffee
      places.servesDessert
      places.servesDinner
      places.servesLunch
      places.servesVegetarianFood
      places.servesWine
      places.takeout

      * "البحث النصي" و"البحث في مكان قريب" فقط

  • textQuery

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

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

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

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

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

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

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

  • evOptions

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

    • connectorTypes

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

      • لفلترة النتائج حسب موصّل متوافق معيّن، اضبط قيمة connectorTypes على تلك القيمة. على سبيل المثال، للعثور على موصلات من النوع 1‏ J1772، اضبط connectorTypes على EV_CONNECTOR_TYPE_J1772.
      • لفلترة النتائج حسب الموصلات غير المتوافقة، اضبط connectorTypes على EV_CONNECTOR_TYPE_OTHER.
      • لفلترة النتائج حسب أي نوع من الموصلات التي يمكن توصيلها بمقبس الحائط، اضبط connectorTypes على EV_CONNECTOR_TYPE_UNSPECIFIED_WALL_OUTLET.
      • لفلترة النتائج حسب أي نوع من أنواع الموصلات، اضبط connectorTypes على EV_CONNECTOR_TYPE_UNSPECIFIED أو لا تضبط قيمة لـ connectorTypes.

    • minimumChargingRateKw

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

  • minRating

    يحصر النتائج في تلك التي يكون متوسط تقييم المستخدمين لها أكبر من هذا الحد أو يساويه. يجب أن تتراوح القيم بين 0.0 و5.0 (بما يشمل هذين الرقمَين) بزيادات قدرها 0.5. على سبيل المثال: 0 و0.5 و1.0 و... و5.0 شاملةً. يتم تقريب القيم إلى أقرب 0.5. على سبيل المثال، تؤدي القيمة 0.6 إلى استبعاد جميع النتائج التي تقل تقييماتها عن 1.0.

  • openNow

    إذا كانت القيمة true، يجب عرض الأماكن المفتوحة فقط عند إرسال طلب البحث. إذا كانت القيمة false، يتم عرض جميع الأنشطة التجارية بغض النظر عن حالة النشاط التجاري. يتم عرض الأماكن التي لا تحدّد ساعات العمل في قاعدة بيانات "أماكن Google" إذا ضبطت هذه المَعلمة على false.

  • pageSize

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

  • 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. عندما تكون القيمة false، وهي القيمة التلقائية، يمكن أن تتضمّن الاستجابة أماكن لا تتطابق مع الأنواع المحدّدة.

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

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

يعرض المثال التالي طلبًا باستخدام Text Search (New) للبحث عن "أطعمة نباتية حارة في سيدني، أستراليا":

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 اللتين تحدّدان حدود المنطقة.

يعرض المثال التالي طلبًا باستخدام Text Search (New) للبحث عن "طعام نباتي" في مدينة نيويورك. لا يعرض هذا الطلب سوى أول 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

يعرض المثال التالي طلبًا باستخدام Text Search (New) للبحث عن "طعام نباتي" مع تحديد الموقع الجغرافي ضمن مسافة 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 type 1، مع حدّ أدنى لمعدّل الشحن يبلغ 10 كيلوواط في ماونتن فيو، كاليفورنيا. يتم عرض أربع نتائج فقط.

curl -X POST -d '{
    "textQuery": "EV Charging Station Mountain View",
    "pageSize": 4,
    "evOptions": {
      "minimumChargingRateKw": 10,
      "connectorTypes": ["EV_CONNECTOR_TYPE_J1772","EV_CONNECTOR_TYPE_TESLA"]
    }
  }' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H "X-Goog-FieldMask: places.displayName,places.evChargeOptions" \
'https://places.googleapis.com/v1/places:searchText'

يعرض الطلب الردّ التالي:

{
  "places": [
    {
      "displayName": {
        "text": "EVgo Charging Station",
        "languageCode": "en"
      },
      "evChargeOptions": {
        "connectorCount": 16,
        "connectorAggregation": [
          {
            "type": "EV_CONNECTOR_TYPE_CHADEMO",
            "maxChargeRateKw": 100,
            "count": 8,
            "availableCount": 5,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 100,
            "count": 2,
            "availableCount": 2,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 350,
            "count": 6,
            "availableCount": 3,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          }
        ]
      }
    },
    {
      "displayName": {
        "text": "EVgo Charging Station",
        "languageCode": "en"
      },
      "evChargeOptions": {
        "connectorCount": 6,
        "connectorAggregation": [
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 100,
            "count": 4,
            "availableCount": 3,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 350,
            "count": 2,
            "availableCount": 0,
            "outOfServiceCount": 2,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          }
        ]
      }
    },
    {
      "displayName": {
        "text": "EVgo Charging Station",
        "languageCode": "en"
      },
      "evChargeOptions": {
        "connectorCount": 5,
        "connectorAggregation": [
          {
            "type": "EV_CONNECTOR_TYPE_J1772",
            "maxChargeRateKw": 3.5999999046325684,
            "count": 1,
            "availableCount": 0,
            "outOfServiceCount": 1,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CHADEMO",
            "maxChargeRateKw": 50,
            "count": 2,
            "availableCount": 0,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 50,
            "count": 2,
            "availableCount": 0,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          }
        ]
      }
    },
    {
      "displayName": {
        "text": "Electric Vehicle Charging Station",
        "languageCode": "en"
      },
      "evChargeOptions": {
        "connectorCount": 10,
        "connectorAggregation": [
          {
            "type": "EV_CONNECTOR_TYPE_OTHER",
            "maxChargeRateKw": 210,
            "count": 10
          }
        ]
      }
    }
  ]
}

البحث عن الأنشطة التجارية ضمن منطقة الخدمة

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

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

curl -X POST -d '{
  "textQuery" : "plumber San Francisco",
  "includePureServiceAreaBusinesses": true
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress' \
'https://places.googleapis.com/v1/places:searchText'

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  1. انقر على رمز واجهة برمجة التطبيقات api في يسار الصفحة.

  2. عدِّل مَعلمات الطلب اختياريًا.

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

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