البحث في الأماكن

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

يمكنك استدعاء search_places من خلال خادم MCP أو كطريقة REST لـ searchText. توضّح هذه الصفحة خيارات الطلب، بما في ذلك خيارات Pro، ومحتوى الردّ، وكيفية فوترة الطلبات. للاطّلاع على المخططات الكاملة، يُرجى مراجعة مرجع MCP لـ search_places ومرجع REST لـ searchText.

خيارات الطلب

يضبط النموذج اللغوي الكبير هذه الخيارات عند استدعاء الأداة، استنادًا إلى طلب المستخدم ووصف الأداة. يمكنك التأثير في الخيارات التي يستخدمها النموذج من خلال تعليماتك الخاصة، راجِع التحكّم في استخدام Pro.

يوضّح الجدول التالي خيارات الطلبات في search_places:

خيارات Pro

هناك خياران لتحديد رمز التخزين التعريفي لـ Maps Grounding Pro. يتم تحصيل رسوم الطلب الذي يستخدم أيًا منهما أو كليهما ضمن رمز التخزين التعريفي Pro:

أما الطلبات التي لا تستخدم أيًا من الخيارَين، بما في ذلك الطلبات التي تتضمّن page_size من 1 إلى 5، فتتم فوترتها ضمن رمز التخزين التعريفي Essentials.

تفاصيل المكان الموسّعة

اضبط include_extended_details على true عندما يتطلّب طلب المستخدم إحصاءات نوعية أو ظروف في الوقت الفعلي أو سمات متخصّصة، مثل:

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

تعتمد الإحصاءات في الملخّص على طلب البحث والبيانات المتاحة لكل مكان. لا يظهر كل نوع من الإحصاءات في كل ردّ.

اترك القيمة false (القيمة التلقائية) لعمليات البحث العادية: المأكولات أو أنواع المتاجر، والعناوين، ومعلومات الاتصال، وساعات العمل، ووسائل الراحة العادية. تستغرق الطلبات التي تتضمّن تفاصيل موسّعة وقتًا أطول لإكمالها.

لا تؤدي التفاصيل الإضافية إلى تغيير بنية الردّ. وبدونها، يصف الملخّص كل مكان في جملة أو جملتَين. من خلال هذه الميزة، يحصل كل مكان على وصف أطول يستند إلى المزيد من بيانات "خرائط Google"، بما في ذلك الإحصاءات من المراجعات. تكون إدخالات places المنظَّمة هي نفسها لكل من رمزَي التخزين التعريفي.

مثال

يطلب طلب MCP التالي ما يصل إلى 8 أماكن مع تفاصيل موسّعة. ويتم تحصيل رسومها ضمن رمز التخزين التعريفي Pro:

{
  "method": "tools/call",
  "params": {
    "name": "search_places",
    "arguments": {
      "text_query": "date night Italian restaurants in Chicago",
      "page_size": 8,
      "include_extended_details": true
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}

يرسل المثال التالي الطلب نفسه إلى طريقة REST‏ searchText:

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-d '{
  "textQuery": "date night Italian restaurants in Chicago",
  "pageSize": 8,
  "includeExtendedDetails": true
}' \
"https://mapstools.googleapis.com/v1:searchText"

استبدِل API_KEY بمفتاح واجهة برمجة التطبيقات.

بدون تفاصيل موسّعة، يصف الملخّص كل مكان في جملة أو جملتَين:

مطعم إيطالي [0] (4.6★ (1,250) · 123 W Example St · $$$) A neighborhood trattoria known for handmade pasta and a long wine list.

With extended details, the summary adds what reviewers highlight and practical tips:

Example Trattoria [0] (4.6★ (1,250) · 123 W Example St · $$$) مطعم حميمي على ضوء الشموع يصفه المراجعون بأنّه رومانسي ولكن صاخب في عطلات نهاية الأسبوع. وتشمل الأطباق المميّزة تالياتيلي آل راغو وبوراتا وتيراميسو. يُنصح بالحجز مسبقًا، إذ قد يضطر الزبائن الذين يأتون بدون حجز إلى الانتظار لمدة تتراوح بين 30 و45 دقيقة مساء الجمعة والسبت، كما أنّ مواقف السيارات في الشارع محدودة.

الردّ

يحتوي الردّ على الحقول التالية:

• ‫summary: ملخّص بلغة طبيعية لنتائج البحث قد يحتوي على اقتباسات مستندة إلى الصفر، مثل [0]، والتي يتم ربطها بالإدخالات في places.
• ‫places[]: الأماكن المذكورة في الملخّص يتضمّن كل مكان ما يلي:
  • ‫place: اسم المورد الخاص بالمكان، بالتنسيق places/{id}
  • ‫id: تمثّل هذه السمة رقم تعريف المكان. ويمكنك استخدامها مع واجهات برمجة التطبيقات الأخرى في "منصة خرائط Google"، مثل عرض المكان على خريطة.
  • ‫location: تشير إلى إحداثيات خط العرض/خط الطول للمكان.
  • ‫googleMapsLinks: روابط إلى "خرائط Google" للمكان (placeUrl) والاتجاهات (directionsUrl) والمراجعات (reviewsUrl) والصور (photosUrl) وكتابة مراجعة (writeAReviewUrl)
  • attribution: مصدر المعلومات الذي يجب عرضه مع المكان يُرجى الاطّلاع على متطلبات الإسناد.
• ‫contentToken: رمز مميّز لعرض البيانات بشكل مرئي باستخدام الذكاء الاصطناعي الوكيل (نسخة حصرية) يتيح لك عرض الأماكن في الردّ باستخدام حزمة أدوات "خرائط Google" الجاهزة للأماكن بدون أي تكلفة إضافية يتم عرض هذه الحالة عندما يتضمّن الردّ مكانًا واحدًا على الأقل.

يتضمّن الردّ البنية نفسها لكلّ من رموز التخزين التعريفية وMCP وREST. للاطّلاع على تفاصيل الحقول، يُرجى مراجعة مرجع search_places.

الفوترة والحصص

كل طلب من search_places هو حدث واحد قابل للفوترة:

• يتم إصدار فاتورة بالطلبات التي لا تستخدم أيّ خيارات Pro ضمن رمز التخزين التعريفي لـ Maps Grounding Essentials.
• يتم تحرير فاتورة للطلب الذي يستخدم خيار Pro ضمن رمز التخزين التعريفي لـ Maps Grounding Pro. ولا يؤدي استخدام كلا الخيارَين في طلب واحد إلى تغيير الرسوم. للاطّلاع على أسعار Pro، يُرجى مراجعة مقارنة بين Essentials وPro و"استخدام خرائط Google كمصدر".

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

تبلغ حصة search_places ‏300 طلب بحث في الدقيقة لكل مشروع، وتتم مشاركتها من خلال كل من رمزَي التخزين التعريفيَين. للاطّلاع على الأسعار، يُرجى مراجعة جدول الأسعار الرئيسي وجدول الأسعار في الهند.