مرجع واجهة برمجة التطبيقات بتنسيق XML

تشير هذه الصفحة إلى إصدار XML من واجهة Custom Search JSON API، وهو متاح فقط لعملاء Google Site Search.

1. نظرة عامة
2. تنسيق طلب "محرك البحث المبرمَج"
   1. نظرة عامة على الطلبات
   2. عبارات طلب البحث
   3. مَعلمات الطلب
      1. أمثلة على طلبات البحث على الويب
      2. تعريفات مَعلمات طلب البحث في WebSearch
      3. البحث المتقدّم
      4. مَعلمات طلب البحث المتقدّم
      5. عبارات البحث الخاصة
      6. أمثلة على طلبات البحث بالصور
      7. مَعلمات طلب البحث في "بحث الصور"
      8. حدود الطلب
   4. تكييف طريقة عرض طلبات البحث والنتائج مع اللغات المختلفة
      1. ترميز الأحرف
      2. لغات الواجهة
      3. البحث باللغة الصينية المبسَّطة والصينية التقليدية
   5. فلترة النتائج
      1. الفلترة التلقائية لنتائج البحث
      2. فلترة النتائج حسب اللغة والبلد
      3. فلترة المحتوى المخصّص للبالغين باستخدام "البحث الآمن"
3. نتائج XML
   1. ملف DTD لنتائج XML من Google
   2. لمحة عن ردّ XML
   3. نتائج XML لطلبات البحث العادية وطلبات البحث عن الصور وطلبات البحث المتقدّمة
      1. البحث العادي/المتقدّم: نموذج طلب بحث ونتيجة بتنسيق XML
      2. البحث العادي/المتقدّم: علامات XML
      3. نتائج XML لطلبات البحث عن الصور
      4. البحث بالصور: نموذج طلب بحث ونتيجة بتنسيق XML
      5. بحث الصور: علامات XML

نظرة عامة

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

لاسترداد نتائج Google WebSearch، يرسل تطبيقك طلب HTTP بسيطًا إلى Google، ثم تعرض Google نتائج البحث بتنسيق XML. تتيح لك النتائج المنسَّقة بتنسيق XML إمكانية تخصيص طريقة عرض نتائج البحث.

تنسيق طلب WebSearch

• نظرة عامة حول الطلب
• عبارات طلب البحث
• مَعلمات الطلب
• أمثلة على طلبات البحث على الويب
• تعريفات مَعلمات طلب البحث على الويب
• أمثلة على طلبات البحث بالصور
• تعريفات مَعلمات طلب البحث في "بحث الصور"
• البحث المتقدّم
  
• البحث المتقدّم معامِلات طلب البحث
• عبارات البحث الخاصة
• حدود الطلب

نظرة عامة حول الطلب

طلب البحث على Google هو أمر GET عادي من HTTP. وتتضمّن مجموعة من المَعلمات ذات الصلة بطلبات البحث. يتم تضمين هذه المَعلمات في عنوان URL للطلب كأزواج اسم=قيمة مفصولة بأحرف العطف اللاتيني (&). تتضمّن المَعلمات بيانات مثل طلب البحث ومعرّف محرّك بحث فريد (cx) يحدّد محرّك البحث الذي يرسل طلب HTTP. تعرض خدمة "بحث الويب" أو "بحث الصور" نتائج بتنسيق XML استجابةً لطلبات HTTP التي ترسلها.

عبارات طلب البحث

تتضمّن معظم طلبات البحث عبارة بحث واحدة أو أكثر، وتظهر عبارة البحث كقيمة مَعلمة في طلب البحث.

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

• الكلمات أو العبارات التي تريد تضمينها أو استبعادها
  • جميع الكلمات في طلب البحث (الإعداد التلقائي)
  • عبارة مطابقة تمامًا في طلب البحث
  • أي كلمة أو عبارة في طلب بحث
• موضع عبارات البحث في المستند
  • في أي مكان في المستند (الإعداد التلقائي)
  • في الروابط في المستند فقط
• القيود المفروضة على المستندات نفسها
  • تضمين أو استبعاد مستندات من أنواع ملفات معيّنة (مثل ملفات PDF أو مستندات Word)
• طلبات البحث الخاصة بعناوين URL التي تعرض معلومات حول عنوان URL معيّن بدلاً من إجراء بحث
  • طلبات البحث التي تعرض معلومات عامة حول عنوان URL، مثل فئة Open Directory أو المقتطف أو اللغة
  • طلبات البحث التي تعرض مجموعة من صفحات الويب التي تتضمّن رابطًا يؤدي إلى عنوان URL
  • طلبات البحث التي تعرض مجموعة من صفحات الويب المشابهة لعنوان URL معيّن

البحث التلقائي

يجب أن تكون قيم مَعلمات طلب البحث متوافقة مع عنوان URL. يُرجى العِلم أنّه يجب استبدال علامة الجمع ("+") بأي تسلسلات من المسافات البيضاء في طلب البحث. يتم تناول هذا الموضوع بشكل أكبر في قسم التوافق مع عنوان URL من هذا المستند.

يتم إرسال عبارة طلب البحث إلى خدمة WebSearch باستخدام المَعلمة q. في ما يلي مثال على عبارة بحث:

q=horses+cows+pigs

بشكل تلقائي، لا تعرض خدمة "بحث الويب من Google" سوى المستندات التي تتضمّن جميع العبارات الواردة في طلب البحث.

مَعلمات الطلب

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

يجب توفّر ثلاث مَعلمات للطلب:

• يجب ضبط المَعلمة client على google-csbe
• تحدّد المَعلمة output تنسيق نتائج XML المعروضة، ويمكن عرض النتائج مع مرجع إلى تعريف نوع المستند (DTD) من Google (xml) أو بدونه (xml_no_dtd). ننصحك بضبط هذه القيمة على xml_no_dtd. ملاحظة: إذا لم تحدّد هذه المَعلمة، سيتم عرض النتائج بتنسيق HTML بدلاً من XML.
  
• المَعلمة cx التي تمثّل المعرّف الفريد للمحرّك
  

في ما يلي مَعلمات الطلبات الأكثر استخدامًا بخلاف تلك المذكورة أعلاه:

• num: عدد نتائج البحث المطلوبة
• q: عبارات البحث
• start: الفهرس الأوّلي للنتائج

أمثلة على طلبات البحث على الويب

تعرض الأمثلة أدناه طلبَي HTTP من WebSearch لتوضيح كيفية استخدام معلَمات طلب البحث المختلفة، ويمكنك الاطّلاع على تعريفات معلَمات طلب البحث المختلفة في قسمَي تعريفات معلَمات طلب البحث في WebSearch ومعلَمات طلب البحث المتقدّم في هذا المستند.

يطلب هذا الطلب عرض أول 10 نتائج (start=0&num=10) لطلب البحث "red sox" (q=red+sox). يحدّد طلب البحث أيضًا أنّ النتائج يجب أن تكون من مواقع إلكترونية كندية (cr=countryCA) وأن تكون مكتوبة باللغة الفرنسية (lr=lang_fr). وأخيرًا، يحدّد طلب البحث قيمًا للمَعلمات client وoutput وcx، وكلّها مطلوبة.

http://www.google.com/search?
  start=0
  &num=10
  &q=red+sox
  &cr=countryCA
  &lr=lang_fr
  &client=google-csbe
  &output=xml_no_dtd
  &cx=00255077836266642015:u-scht7a-8i

يستخدم هذا المثال بعض مَعلمات طلب البحث المتقدّم لتخصيص طلب البحث بشكل أكبر. يستخدم هذا الطلب المَعلمة as_q (as_q=red+sox) بدلاً من المَعلمة q. يستخدم أيضًا المَعلمة as_eq لاستبعاد أي مستندات تحتوي على الكلمة "Yankees" من نتائج البحث (as_eq=yankees).

http://www.google.com/search?
  start=0
  &num=10
  &as_q=red+sox
  &as_eq=Yankees
  &client=google-csbe
  &output=xml_no_dtd
  &cx=00255077836266642015:u-scht7a-8i  

تعريفات مَعلمات طلب البحث في WebSearch

    <!DOCTYPE GSP SYSTEM "google.dtd">

بحث متقدم

إنّ مَعلمات طلب البحث الإضافية المدرَجة أسفل الصورة ذات صلة بطلبات البحث المتقدّمة. عند إرسال طلب بحث متقدّم، يتم تضمين قيم العديد من المَعلمات (مثل as_eq وas_epq وas_oq وما إلى ذلك) في عبارات البحث. تعرض الصورة صفحة "البحث المتقدّم" من Google. في الصورة، يظهر اسم كل معلَمة من معلَمات البحث المتقدّم مكتوبًا باللون الأحمر داخل الحقل أو بجانبه في الصفحة التي تتوافق مع تلك المعلَمة.

مَعلمات طلب البحث المتقدّم

عبارات طلب البحث الخاصة

يتيح محرّك بحث Google على الويب استخدام عدة عبارات طلب بحث خاصة تتيح الوصول إلى إمكانات إضافية في محرّك بحث Google. يجب تضمين عبارات طلب البحث الخاصة هذه في قيمة مَعلمة طلب q. وكما هو الحال مع عبارات البحث الأخرى، يجب أن تكون عبارات البحث الخاصة متوافقة مع عناوين URL. يحتوي عدد من عبارات البحث الخاصة على نقطتَين رأسيتَين (:). يجب أيضًا أن يتم تجاوز هذا الحرف في عنوان URL، وقيمته المتجاوزة في عنوان URL هي %3A.

أمثلة على طلبات البحث عن الصور

تعرض الأمثلة أدناه طلبَي HTTP لصور لتوضيح كيفية استخدام معلَمات طلب البحث المختلفة. يتم تقديم تعريفات لمعلَمات طلب البحث المختلفة في أقسام "تعريفات معلَمات طلب البحث عن الصور" في هذا المستند.

يطلب هذا الطلب أول 5 نتائج (start=0&num=5) لعبارة البحث "قرد" (q=monkey)، من نوع الملف ‎ .png. وأخيرًا، يحدّد طلب البحث قيمًا للمعلمات client وoutput وcx، وكلّها مطلوبة.

http://www.google.com/cse?
  searchtype=image
  start=0
  &num=5
  &q=monkey
  &as_filetype=png
  &client=google-csbe
  &output=xml_no_dtd
  &cx=00255077836266642015:u-scht7a-8i

مَعلمات طلب البحث في "البحث بالصور"

الحدود القصوى المسموح بها للطلبات

يسرد الرسم البياني أدناه القيود المفروضة على طلبات البحث التي ترسلها إلى Google:

تكييف طريقة عرض طلبات البحث والنتائج مع اللغات المختلفة

تتيح لك خدمة "بحث الويب من Google" البحث عن مستندات بلغات متعددة. يمكنك تحديد ترميز الأحرف الذي يجب استخدامه لتفسير طلب HTTP ولترميز استجابة XML (باستخدام مَعلمتَي البحث ie وoe). يمكنك أيضًا فلترة النتائج لتضمين المستندات المكتوبة بلغات معيّنة فقط.

تتناول الأقسام التالية المشاكل المتعلقة بالبحث بلغات متعددة:

• ترميز الأحرف
• لغات الواجهة
• البحث باللغتَين الصينية المبسَّطة والصينية التقليدية

ترميز الأحرف

ترسل الخوادم بيانات، مثل صفحات الويب، إلى برامج وكيل المستخدم، مثل المتصفحات، كسلسلة من وحدات البايت المرمّزة. ثم يفكّ برنامج وكيل المستخدم ترميز وحدات البايت إلى سلسلة من الأحرف. عند إرسال طلبات إلى خدمة WebSearch، يمكنك تحديد أنظمة الترميز لكلّ من طلب البحث واستجابة XML التي تتلقّاها.

يمكنك استخدام مَعلمة الطلب ie لتحديد آلية الترميز للأحرف في طلب HTTP. يمكنك أيضًا استخدام المَعلمة oe لتحديد مخطّط الترميز الذي يجب أن تستخدمه Google لترميز استجابة XML. إذا كنت تستخدم نظام ترميز آخر غير ISO-8859-1 (أو latin1)، يُرجى التأكّد من تحديد القيم الصحيحة للمَعلمتَين ie وoe.

ملاحظة: إذا كنت توفّر وظيفة البحث بلغات متعددة، ننصحك باستخدام قيمة الترميز utf8 (UTF-8) لكل من المَعلمتَين ie وoe.

يُرجى الرجوع إلى الملحق مخططات ترميز الأحرف للاطّلاع على قائمة كاملة بالقيم التي يمكنك استخدامها للمعلمتَين ie وoe.

للحصول على مزيد من المعلومات العامة حول ترميز الأحرف، يُرجى الانتقال إلى http://www.w3.org/TR/REC-html40/charset.html.

لغات الواجهة

يمكنك استخدام مَعلمة طلب البحث hl لتحديد لغة واجهة الرسومات. وقد تؤثر قيمة المَعلمة hl في نتائج بحث XML، خاصةً في طلبات البحث الدولية عندما لا يتم تحديد قيود اللغة (باستخدام المَعلمة lr) بشكل صريح. في مثل هذه الحالات، قد تعزّز المَعلمة hl نتائج البحث باللغة نفسها التي أدخلها المستخدم.

ننصحك بضبط المَعلمة hl بشكل صريح في نتائج البحث لضمان اختيار Google لنتائج البحث الأعلى جودة لكل طلب بحث.

يُرجى الاطّلاع على قسم لغات واجهة المستخدم المتاحة للحصول على قائمة كاملة بالقيم الصالحة للمعلمة hl.

البحث عن مستندات مكتوبة بلغات معيّنة

يمكنك استخدام مَعلمة طلب البحث lr لحصر نتائج البحث على المستندات المكتوبة بلغة معيّنة أو مجموعة من اللغات.

يتوافق المَعلمة lr مع عوامل التشغيل المنطقية لتتيح لك تحديد لغات متعددة يجب تضمينها (أو استبعادها) من نتائج البحث.

توضّح الأمثلة التالية كيف يمكنك استخدام عوامل التشغيل المنطقية لطلب مستندات بلغات مختلفة.

بالنسبة إلى المستندات المكتوبة باللغة اليابانية:

lr=lang_jp

بالنسبة إلى المستندات المكتوبة باللغة الإيطالية أو الألمانية:

lr=lang_it|lang_de

بالنسبة إلى المستندات غير المكتوبة باللغة الهنغارية أو التشيكية:

lr=(-lang_hu).(-lang_cs)

يُرجى الاطّلاع على قسم قيم مجموعة اللغات للحصول على قائمة كاملة بالقيم المحتملة للمَعلمة lr وقسم عوامل التشغيل المنطقية للحصول على مناقشة كاملة حول استخدام عوامل التشغيل هذه.

البحث باللغة الصينية المبسّطة والتقليدية

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

لاستخدام هذه الميزة، اتّبِع الخطوات التالية:

1. اضبط مَعلمة الطلب c2coff على 0
   و
2. نفّذ أيًا مما يلي:
   • لا تضبط مَعلمة الطلب lr
     أو
   • اضبط مَعلمة الطلب lr على lr=lang_zh-TW|lang_zh-CN

يوضّح المثال التالي مَعلمات طلب البحث التي يجب تضمينها في طلب للحصول على نتائج باللغتَين الصينية المبسّطة والصينية التقليدية. (يُرجى العِلم أنّ المعلومات الإضافية المطلوبة، مثل العميل، غير مضمّنة في المثال).

search?hl=zh-CN
    &lr=lang_zh-TW|lang_zh-CN
    &c2coff=0

فلترة النتائج

يوفّر "بحث الويب من Google" عددًا من الطرق لفلترة نتائج البحث:

• الفلترة التلقائية لنتائج البحث
• فلترة النتائج حسب اللغة والبلد
• فلترة المحتوى المخصّص للبالغين باستخدام "البحث الآمن"

الفلترة التلقائية لنتائج البحث

سعيًا إلى توفير أفضل نتائج بحث ممكنة، يستخدِم محرك بحث Google الطريقتين التاليتين لإجراء فلترة تلقائية لنتائج البحث غير المرغوب فيها عمومًا:

• المحتوى المكرّر: إذا احتوت مستندات متعددة على المعلومات نفسها، سيتم عندئذ تضمين المستند الأكثر صلة من هذه المجموعة في نتائج البحث.

• تعدد الاستضافة: إذا ظهرت عدّة نتائج بحث من الموقع الإلكتروني نفسه، قد لا يعرِض محرك بحث Google كل النتائج من ذلك الموقع أو قد يعرِضها بترتيب أدنى من الترتيب الذي كان من المفترض أن تظهر به.
  

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

فلترة حسب اللغة والبلد

تعرِض خدمة "بحث الويب من Google" النتائج من فهرس رئيسي لجميع مستندات الويب، ويحتوي هذا الفهرس على مجموعات فرعية من المستندات التي يتم تجميعها حسب سمات معيَّنة، بما في ذلك اللغة والبلد الأصلي.

يمكنك استخدام مَعلمتَي طلب البحث lr وcr لحصر نتائج البحث على المجموعات الفرعية من المستندات المكتوبة بلغات معيَّنة أو الصادرة من بلدان معيَّنة، على التوالي.

تحدِّد خدمة "بحث الويب من Google" لغة المستند من خلال تحليل ما يلي:

• نطاق المستوى الأعلى (TLD) لعنوان URL في المستند
• العلامات الوصفية للغة داخل المستند
• اللغة الأساسية المستخدَمة في النص الأساسي للمستند

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

تحدِّد خدمة "بحث الويب من Google" بلد المستند من خلال تحليل ما يلي:

• نطاق المستوى الأعلى (TLD) لعنوان URL في المستند
• الموقع الجغرافي لعنوان IP الخاص بخادم الويب

يُرجى أيضًا الاطّلاع على تعريف المَعلمة cr وقيم مجموعة البلدان التي يمكن استخدامها كقيم للمَعلمة cr للحصول على مزيد من المعلومات حول حصر النتائج حسب بلد المنشأ.

ملاحظة: يمكنك الجمع بين قيَم اللغات وقيَم البلدان لتخصيص نتائج البحث. على سبيل المثال، يمكنك طلب مستندات مكتوبة باللغة الفرنسية ومنشورة في فرنسا أو كندا، أو يمكنك طلب مستندات منشورة في هولندا وغير مكتوبة باللغة الإنجليزية. تتيح المَعلمتان lr وcr استخدام عوامل التشغيل المنطقية.

فلترة المحتوى المخصّص للبالغين باستخدام ميزة "البحث الآمن"

لا يريد العديد من عملاء Google عرض نتائج بحث عن مواقع إلكترونية تتضمّن محتوًى للبالغين. وباستخدام فلتر "البحث الآمن"، يمكنك فحص نتائج البحث التي تتضمّن محتوًى للبالغين وإزالتها. وتستخدم فلاتر Google تكنولوجيا خاصة للتحقّق من الكلمات الرئيسية والعبارات وعناوين URL. ومع أنّ أي فلتر لا يكون دقيقًا بنسبة 100%، سيزيل فلتر "البحث الآمن" الغالبية العظمى من المحتوى المخصّص للبالغين من نتائج البحث.

تسعى Google إلى إبقاء ميزة "البحث الآمن" محدّثة وشاملة قدر الإمكان من خلال الزحف المستمر إلى الويب وتضمين التعديلات الواردة من اقتراحات المستخدمين.

تتوفّر ميزة "البحث الآمن" باللغات التالية:

يمكنك تعديل درجة فلترة Google لنتائجك من حيث محتوى البالغين باستخدام مَعلمة طلب البحث safe. يوضّح الجدول التالي إعدادات "البحث الآمن" من Google ومدى تأثير هذه الإعدادات في نتائج البحث:

إذا كانت ميزة "البحث الآمن" مفعّلة وعثرت على مواقع إلكترونية تتضمّن محتوًى مسيئًا في نتائج البحث، يُرجى إرسال عنوان URL الخاص بالموقع الإلكتروني إلى safesearch@google.com، وسنتولّى التحقيق في الأمر.

نتائج XML

• ملف تعريف نوع المستند (DTD) الخاص بنتائج Google XML
• لمحة عن ردّ XML
• XML نتائج طلبات البحث العادية والمتقدّمة
• البحث العادي/المتقدّم: نموذج طلب بحث ونتيجة بتنسيق XML
• البحث العادي/المتقدّم: علامات XML

Google XML Results DTD

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

يوضّح هذا المستند جوانب DTD ذات الصلة بـ WebSearch. عند الاطّلاع على تعريف نوع المستند، إذا كنت تعمل على WebSearch، يمكنك تجاهل العلامات والسمات غير الموضّحة هنا بدون قلق. إذا كان التعريف يختلف بين DTD والمستندات، سيتم توضيح ذلك في هذا المستند.

يمكن أن تعرض Google نتائج XML مع الإشارة إلى أحدث ملف DTD أو بدونها. إنّ تعريف نوع المستند هو دليل يساعد مشرفي البحث ومحلّلات XML في فهم نتائج XML من Google. بما أنّ قواعد XML الخاصة بـ Google قد تتغيّر من حين لآخر، عليك عدم ضبط المحلّل اللغوي لاستخدام تعريف نوع المستند (DTD) من أجل التحقّق من صحة كل نتيجة XML.

بالإضافة إلى ذلك، يجب عدم ضبط محلّل XML على استرداد تعريف نوع المستند (DTD) في كل مرة ترسل فيها طلب بحث، لأنّ Google لا يحدّث تعريف نوع المستند إلا نادرًا، وتتسبّب هذه الطلبات في حدوث تأخير غير ضروري وتفرض متطلبات غير ضرورية على النطاق الترددي.

تنصحك Google باستخدام تنسيق الإخراج xml_no_dtd للحصول على نتائج بتنسيق XML. إذا حدّدت تنسيق xml للإخراج في طلب البحث، سيكون الاختلاف الوحيد هو تضمين السطر التالي في نتائج XML:

<!DOCTYPE GSP SYSTEM "google.dtd">

يمكنك الوصول إلى أحدث إصدار من DTD على الرابط http://www.google.com/google.dtd.

يُرجى العلم أنّه قد لا تكون بعض الميزات في تعريف نوع المستند متوفرة أو متاحة في الوقت الحالي.

لمحة عن استجابة XML

• جميع قيم العناصر هي HTML صالح ومناسب للعرض، ما لم يُذكر خلاف ذلك في تعريفات علامات XML.
• بعض قيم العناصر هي عناوين URL يجب ترميزها بتنسيق HTML قبل عرضها.
• يجب أن يتجاهل محلّل XML السمات والعلامات غير الموثّقة، ما يسمح لتطبيقك بمواصلة العمل بدون تعديل إذا أضافت Google المزيد من الميزات إلى مخرجات XML.
• يجب تخطّي بعض الأحرف عند تضمينها كقيم في علامات XML. على معالج XML تحويل هذه العناصر إلى الأحرف المناسبة. في حال عدم تحويل الكيانات بشكل سليم، قد يعرض المتصفّح، على سبيل المثال، الرمز & على النحو "&". تتضمّن مستندات معيار XML هذه الأحرف، ويتم عرضها في الجدول أدناه:

  حرف	النماذج التي تم تجاهل تنسيقها	الكيان	رمز الأحرف
  علامة العطف	&	&	&
  علامة الاقتباس المفردة	'	'	'
  علامة الاقتباس المزدوجة	"	"	"
  علامة "أكبر من"	>	>	>
  علامة &quot;أقل من&quot;	<	&lt;	&#60;

نتائج XML لطلبات البحث العادية والمتقدّمة

البحث العادي/المتقدّم: نموذج طلب بحث ونتيجة XML

يطلب نموذج طلب WebSearch هذا الحصول على 10 نتائج (num=10) حول عبارة البحث "socer" (q=socer)، وهي كلمة "soccer" مكتوبة بشكل خاطئ عن قصد في هذا المثال.

http://www.google.com/search?
    q=socer
    &hl=en
    &start=10
    &num=10
    &output=xml
    &client=google-csbe
    &cx=00255077836266642015:u-scht7a-8i 

يؤدي هذا الطلب إلى ظهور نتيجة XML أدناه. يُرجى العِلم أنّ نتيجة XML تتضمّن عدة تعليقات للإشارة إلى مواضع ظهور علامات معيّنة غير مضمّنة في النتيجة.

<?xml version="1.0" encoding="ISO-8859-1" standalone="no" ?>

<GSP VER="3.2">
   <TM>0.452923</TM>
   <Q>socer</Q>

<PARAM name="cx" value="00255077836266642015:u-scht7a-8i" original_value="00255077836266642015%3Au-scht7a-8i"/>
   <PARAM name="hl" value="en" original_value="en"/>
   <PARAM name="q" value="socer" original_value="socer"/>
   <PARAM name="output" value="xml" original_value="xml"/>
   <PARAM name="client" value="google-csbe" original_value="google-csbe"/>
   <PARAM name="num" value="10" original_value="10"/>
   <Spelling>
      <Suggestion q="soccer"><b><i>soccer</i></b></Suggestion>
   </Spelling>
   <Context>

<title>Sample Vacation CSE</title>
    <Facet>
      <FacetItem>
        <label>restaurants</label>
        <anchor_text>restaurants</anchor_text>
      </FacetItem>
      <FacetItem>
        <label>wineries</label>
        <anchor_text>wineries</anchor_text>
      </FacetItem>
    </Facet>
    <Facet>
      <FacetItem>
        <label>golf_courses</label>
        <anchor_text>golf courses</anchor_text>
      </FacetItem>
    </Facet>
    <Facet>
     <FacetItem>
        <label>hotels</label>
        <anchor_text>hotels</anchor_text>
      </FacetItem>
    </Facet>
    <Facet>
      <FacetItem>
        <label>nightlife</label>
        <anchor_text>nightlife</anchor_text>
      </FacetItem>
    </Facet>
    <Facet>
      <FacetItem>
        <label>soccer_sites</label>
        <anchor_text>soccer sites</anchor_text>
      </FacetItem>
    </Facet>
   </Context>
   <RES SN="1" EN="10">
      <M>6080</M>
      /*
       * The FI tag after the comment indicates that the result
       * set has been filtered. If the number of results were exact, the
       * FI tag would be replaced by an XT tag in the same format.
       */
      <FI />
      <NB>
         /*
          * Since the request is for the first page of results, the PU tag,
          * which contains a link to the previous page of search results,
          * is not included in this XML result. If the sample result did include
          * a previous page of results, it would be listed here, in the same format
          * as the NU tag on the following line
          */
         <NU>/search?q=socer&hl=en&lr=&ie=UTF-8&output=xml&client=test&start=10&sa=N</NU>
      </NB>
      <R N="1">
         <U>http://www.soccerconnection.net/</U>
         <UE>http://www.soccerconnection.net/</UE>
         <T>SoccerConnection.net</T>
              <CRAWLDATE>May 21, 2007</CRAWLDATE>
         <S><b>soccer</b>; players; coaches; ball; world cup;<b>...</b></S>
  <Label>transcodable_pages</Label>
    <Label>accessible</Label>
         <Label>soccer_sites</Label>
         <LANG>en</LANG>
         <HAS>
            <DI>
               <DT>SoccerConnection.net</DT>
               <DS>Post your <b>soccer</b> resume directly on the Internet.</DS>
            </DI>
            <L/>
            <C SZ="8k" CID="kWAPoYw1xIUJ"/>
            <RT/>
         </HAS>
      </R>
      /*
       * The result includes nine more results, each enclosed by an R tag.
       */
   </RES>
</GSP>

البحث العادي/المتقدّم: علامات XML

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

تم إدراج علامات XML أدناه أبجديًا حسب اسم العلامة، ويتضمّن كل تعريف علامة وصفًا للعلامة ومثالاً يوضّح كيفية ظهور العلامة في نتيجة XML وتنسيق محتوى العلامة. إذا كانت العلامة الفرعية تابعة لعلامة XML أخرى أو إذا كانت العلامة تتضمّن علامات فرعية أو سمات خاصة بها، يتم توفير هذه المعلومات أيضًا في جدول تعريف العلامة.

قد تظهر رموز معيّنة بجانب بعض العلامات الفرعية في التعريفات أدناه. ستجد أدناه هذه الرموز ومعانيها:

This example uses the refinement label golf_courses to
filter search results about Palm Springs:
    q=Palm+Springs+more:golf_courses

The URL-escaped version of this query is:
    q=Palm+Springs+more%3Agolf_courses

نتائج XML لطلبات البحث بالصور

يطلب نموذج طلب الصورة هذا 5 نتائج (num=5) حول عبارة البحث "قرد" (q=monkey).

http://www.google.com/cse?
  searchtype=image
  &num=2
  &q=monkey
  &client=google-csbe
  &output=xml_no_dtd
  &cx=00255077836266642015:u-scht7a-8i

يؤدي هذا الطلب إلى ظهور نتيجة XML أدناه.

<GSP VER="3.2">
  <TM>0.395037</TM>
  <Q>monkeys</Q>

  <PARAM name="cx" value="011737558837375720776:mbfrjmyam1g" original_value="011737558837375720776:mbfrjmyam1g" url_<escaped_value="011737558837375720776%3Ambfrjmyam1g" js_escaped_value="011737558837375720776:mbfrjmyam1g"/>
  <PARAM name="client" value="google-csbe" original_value="google-csbe" url_escaped_value="google-csbe" js_escaped_value="google-csbe"/>
  <PARAM name="q" value="monkeys" original_value="monkeys" url_escaped_value="monkeys" js_escaped_value="monkeys"/>
  <PARAM name="num" value="2" original_value="2" url_escaped_value="2" js_escaped_value="2"/>
  <PARAM name="output" value="xml_no_dtd" original_value="xml_no_dtd" url_escaped_value="xml_no_dtd" js_escaped_value="xml_no_dtd"/>
  <PARAM name="adkw" value="AELymgUP4VYSok20wy9SeYczEZ5UXxpBmRsJH4oC4aXhVuZgwGKuponcNXjrYkkw2bRv1BylIm89ndJ-Q4vxvyW0tcbiqipcQC9op_cBG84T12WMvX8660A" original_value="AELymgUP4VYSok20wy9SeYczEZ5UXxpBmRsJH4oC4aXhVuZgwGKuponcNXjrYkkw2bRv1BylIm89ndJ-Q4vxvyW0tcbiqipcQC9op_cBG84T12WMvX8660A" url_escaped_value="AELymgUP4VYSok20wy9SeYczEZ5UXxpBmRsJH4oC4aXhVuZgwGKuponcNXjrYkkw2bRv1BylIm89ndJ-Q4vxvyW0tcbiqipcQC9op_cBG84T12WMvX8660A" js_escaped_value="AELymgUP4VYSok20wy9SeYczEZ5UXxpBmRsJH4oC4aXhVuZgwGKuponcNXjrYkkw2bRv1BylIm89ndJ-Q4vxvyW0tcbiqipcQC9op_cBG84T12WMvX8660A"/>
  <PARAM name="hl" value="en" original_value="en" url_escaped_value="en" js_escaped_value="en"/>
  <PARAM name="oe" value="UTF-8" original_value="UTF-8" url_escaped_value="UTF-8" js_escaped_value="UTF-8"/>
  <PARAM name="ie" value="UTF-8" original_value="UTF-8" url_escaped_value="UTF-8" js_escaped_value="UTF-8"/>
  <PARAM name="boostcse" value="0" original_value="0" url_escaped_value="0" js_escaped_value="0"/>

  <Context>
    <title>domestigeek</title>
  </Context>

  <ARES/>
  <RES SN="1" EN="2">
    <M>2500000</M>
    <NB>
      <NU>/images?q=monkeys&num=2&hl=en&client=google-csbe&cx=011737558837375720776:mbfrjmyam1g&boostcse=0&output=xml_no_dtd
        &ie=UTF-8&oe=UTF-8&tbm=isch&ei=786oTsLiJaaFiALKrPChBg&start=2&sa=N
      </NU>
    </NB>
    <RG START="1" SIZE="2"/>
      <R N="1" MIME="image/jpeg">
        <RU>http://www.flickr.com/photos/fncll/135465558/</RU>
        <U>
          http://farm1.static.flickr.com/46/135465558_123402af8c.jpg
        </U>
        <UE>
          http://farm1.static.flickr.com/46/135465558_123402af8c.jpg
        </UE>
        <T>Computer <b>Monkeys</b> | Flickr - Photo Sharing!</T>
        <RK>0</RK>
        <BYLINEDATE>1146034800</BYLINEDATE>
        <S>Computer <b>Monkeys</b> | Flickr</S>
        <LANG>en</LANG>
        <IMG WH="500" HT="305" IID="ANd9GcQARKLwzi-t4lpWi2AERV3kJb4ansaQzTn3MNDZR9fD_JDiktPKByKUBLs">
          <SZ>88386</SZ>
          <IN/>
        </IMG>
        <TBN TYPE="0" WH="130" HT="79" URL="http://t0.gstatic.com/images?q=tbn:ANd9GcQARKLwzi-
t4lpWi2AERV3kJb4ansaQzTn3MNDZR9fD_JDiktPKByKUBLs"/>
      </R>
      <R N="2" MIME="image/jpeg">
        <RU>
          http://www.flickr.com/photos/flickerbulb/187044366/
        </RU>
        <U>
          http://farm1.static.flickr.com/73/187044366_506a1933f4.jpg
        </U>
        <UE>
          http://farm1.static.flickr.com/73/187044366_506a1933f4.jpg
        </UE>
        <T>
          one. ugly. <b>monkey</b>. | Flickr - Photo Sharing!
        </T>
        <RK>0</RK>
        <BYLINEDATE>1152514800</BYLINEDATE>
        <S>one. ugly. <b>monkey</b>.</S>
        <LANG>en</LANG>
        <IMG WH="400" HT="481" IID="ANd9GcQ3Qom0bYbee4fThCQVi96jMEwMU6IvVf2b8K5vERKVw-
           EF4tQQnDDKOq0"><SZ>58339</SZ>
          <IN/>
        </IMG>
        <TBN TYPE="0" WH="107" HT="129" URL="http://t1.gstatic.com/images?q=tbn:ANd9GcQ3Qom0bYbee4fThCQ
          Vi96jMEwMU6IvVf2b8K5vERKVw-EF4tQQnDDKOq0"/>
      </R>
  </RES>
</GSP>

"بحث الصور": علامات XML

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

قد تظهر رموز معيّنة بجانب بعض العلامات الفرعية في التعريفات أدناه. ستجد أدناه هذه الرموز ومعانيها: