Felo API PlatformFelo API Platform
جميع endpoints الخاصة بـ DataForSEO
v0.2.0-beta
OpenAPI 3.1.0

إعداد مهام Google Organic SERP

Felo API Support
MIT
الخادم:https://openapi.felo.ai
مكتبات العملاء
Shell Curl

DataForSEO

​

SEO, search-engine results, keyword research, backlinks and AI visibility data.

DataForSEO العمليات

إعداد مهام Google Organic SERP

​

يضع النتائج المرتّبة لكلمة مفتاحية على Google في قائمة الانتظار، ويعيد id للمهمة في tasks[0].id. الاستجابة مغلّفة في غلاف DataForSEO: البيانات في tasks[0].result، والنتيجة في tasks[0].status_code — ولا يزال الطلب المرفوض يعيد HTTP 200. النظير المباشر يجيب فورًا وهو أبسط لاستعلام واحد؛ استخدم قائمة الانتظار عندما تتجاوز الدفعة عمر استدعاء أداة واحد.

مرجع التسعير

  • القياس: تكلفة الاستجابة المُبلَّغ عنها.
  • تقدير الطلب المرجعي: 0.02 دولار أمريكي.
  • مضاعف العميل المرجعي: 1.0. لا تُطبّقه مرة أخرى على مبلغ عميل مسوّى.

بيانات وصفية مرجعية فقط، وليست عرض سعر للحساب ولا سعرًا مضمونًا ولا حدًا للإنفاق. أرصدة الموارد ليست أرصدة Felo. تتبع الرسوم النهائية سجلات فوترة Felo.

الجسم
application/json
  • النوع: array (object | null)[]
    • browser_screen_height
      النوع: integer | null

      ارتفاع شاشة المتصفح

      حقل اختياري

      يمكنك تعيين ارتفاع مخصص لشاشة المتصفح لحساب ترتيب البكسل لجهاز معيّن؛

      يمكن تحديده ضمن النطاق التالي: 240-9999؛

      القيمة الافتراضية:

      1080 لـdesktop؛

      640 لـmobile على android؛

      812 لـmobile على iOS؛

      ملاحظة: لاستخدام هذا المعامل، عيّن calculate_rectangles على true

    • browser_screen_resolution_ratio
      النوع: integer | null

      عامل تحجيم شاشة المتصفح

      حقل اختياري

      يمكنك تعيين عامل تحجيم مخصص لشاشة المتصفح لحساب ترتيب البكسل لجهاز معيّن؛

      يمكن تحديده ضمن النطاق التالي: 0.5-3؛

      القيمة الافتراضية:

      1 لـdesktop؛

      3 لـmobile على android؛

      3 لـmobile على iOS؛

      ملاحظة: لاستخدام هذا المعامل، عيّن calculate_rectangles على true

    • browser_screen_width
      النوع: integer | null التنسيق: int64

      عرض شاشة المتصفح

      حقل اختياري

      يمكنك تعيين عرض مخصص لشاشة المتصفح لحساب ترتيب البكسل لجهاز معيّن؛

      يمكن تحديده ضمن النطاق التالي: 240-9999؛

      القيمة الافتراضية:

      1920 لـdesktop؛

      360 لـmobile على android؛

      375 لـmobile على iOS؛

      ملاحظة: لاستخدام هذا المعامل، عيّن calculate_rectangles على true

    • calculate_rectangles
      النوع: boolean | null

      حساب ترتيب البكسل لعناصر SERP في النتائج المتقدمة

      حقل اختياري

      يشير ترتيب البكسل إلى المسافة بين مقتطف النتيجة والزاوية العلوية اليسرى للشاشة؛

      زُر مركز المساعدة لمعرفة المزيد>>

      افتراضيًا، يُضبط المعامل على false

      ملاحظة: ستُفرض عليك رسوم إضافية بقيمة 0.0006 دولار أمريكي لاستخدام هذا المعامل

    • depth
      النوع: integer | null

      عمق التحليل

      حقل اختياري

      عدد النتائج في SERP

      القيمة الافتراضية: 10

      القيمة القصوى: 700


      ستُحتسب رسوم حسابك لكل SERP يحتوي على ما يصل إلى 10 نتائج؛

      قد يؤدي تعيين عمق أكبر من 10 إلى رسوم إضافية إذا أعاد محرك البحث أكثر من 10 نتائج؛

      يمكن حساب التكلفة في صفحة الأسعار.

    • device
      النوع: string | null

      نوع الجهاز

      حقل اختياري

      إعادة النتائج لنوع جهاز محدد

      يمكن أن تأخذ القيم:desktop، mobile

      القيمة الافتراضية: desktop

    • expand_ai_overview
      النوع: boolean | null

      توسيع نظرة AI العامة

      حقل اختياري

      اضبطه على true لتوسيع عنصر ai_overview؛

      القيمة الافتراضية: false؛

      ملاحظة: ينطبق هذا المعامل فقط على نتائج المهام بصيغة HTML

    • find_targets_in
      النوع: array string[] | null

      أنواع عناصر SERP للتحقق من الأهداف

      حقل اختياري

      لتفعيل هذا المعامل، يجب أيضًا تفعيل stop_crawl_on_match

      يحدد أنواع عناصر SERP التي يجب التحقق فيها بحثًا عن مطابقات الأهداف

      إذا لم يُحدد، تُفحص جميع عناصر المستوى الأول التي تحتوي على حقلي url وdomain بحثًا عن الأهداف

      القيم الممكنة: organic، paid، local_pack، featured_snippet، events، google_flights، images، jobs، knowledge_graph، local_service، map، scholarly_articles، third_party_reviews، twitter

      ملاحظة: لا يمكن أن يحتوي على أنواع العناصر نفسها الموجودة في ignore_targets_in

      مثال:

      "find_targets_in": ["organic", "featured_snippet"]

      اعرف المزيد عن هذا المعامل في مركز المساعدة

    • group_organic_results
      النوع: boolean | null

      عرض النتائج ذات الصلة

      حقل اختياري

      إذا ضُبط على true، سيُقدَّم عنصر related_result في الاستجابة كمقتطف من نتيجة organic الأصلية التابعة له؛

      إذا ضُبط على false، سيُقدَّم عنصر related_result كنتيجة organic منفصلة؛

      القيمة الافتراضية: true

    • ignore_targets_in
      النوع: array string[] | null

      أنواع عناصر SERP المستبعدة من البحث عن الأهداف

      حقل اختياري

      لتفعيل هذا المعامل، يجب أيضًا تفعيل stop_crawl_on_match

      يحدد أنواع عناصر SERP التي يجب استبعادها عند البحث عن مطابقات الأهداف

      القيم الممكنة: organic، paid، local_pack، featured_snippet، events، google_flights، images، jobs، knowledge_graph، local_service، map، scholarly_articles، third_party_reviews، twitter

      ملاحظة: لا يمكن أن يحتوي على أنواع العناصر نفسها الموجودة في find_targets_in

      مثال:

      "ignore_targets_in": ["paid", "images"]

      اعرف المزيد عن هذا المعامل في مركز المساعدة

    • keyword
      النوع: string

      الكلمة المفتاحية

      حقل مطلوب

      يمكنك تحديد حتى 700 حرف في حقل keyword

      ستُفكّ جميع ترميزات %## (وسيُفكّ الحرف ‘+’ إلى مسافة)

      إذا كنت بحاجة إلى استخدام الحرف “%” في keyword، فحدده بالشكل “%25”؛

      إذا كنت بحاجة إلى استخدام الحرف “+” في keyword، فحدده بالشكل “%2B”؛

      إذا كانت هذه الكلمة تحتوي على معاملات مثل ‘allinanchor:’، ‘allintext:’، ‘allintitle:’، ‘allinurl:’، ‘cache:’، ‘define:’، ‘filetype:’، ‘id:’، ‘inanchor:’، ‘info:’، ‘intext:’، ‘intitle:’، ‘inurl:’، ‘link:’، ‘site:’، فستُضرب تكلفة كل مهمة في 5

      اعرف المزيد عن قواعد وقيود حقلي keyword وkeywords في واجهات DataForSEO في مقالة مركز المساعدة هذه

    • language_code
      النوع: string

      رمز لغة محرك البحث

      حقل مطلوب إذا لم تحدد language_name

      إذا استخدمت هذا الحقل، فلا حاجة لتحديد language_name

      يمكنك الحصول على قائمة اللغات المتاحة لمحرك البحث مع language_code الخاص بها عبر إرسال طلب منفصل إلى https://api.dataforseo.com/v3/serp/google/languages

      مثال:

      en

    • language_name
      النوع: string

      الاسم الكامل للغة محرك البحث

      حقل مطلوب إذا لم تحدد language_code

      إذا استخدمت هذا الحقل، فلا حاجة لتحديد language_code

      يمكنك الحصول على قائمة اللغات المتاحة لمحرك البحث مع language_name الخاص بها عبر إرسال طلب منفصل إلى https://api.dataforseo.com/v3/serp/google/languages

      مثال:

      English

    • load_async_ai_overview
      النوع: boolean | null

      تحميل نظرة AI العامة بشكل غير متزامن

      حقل اختياري

      اضبطه على true للحصول على عناصر ai_overview في نتائج SERP حتى إذا حُمّلت بشكل غير متزامن؛

      إذا ضُبط على false، فلن تحصل إلا على عناصر ai_overview من ذاكرة التخزين المؤقت؛

      القيمة الافتراضية: false

      ملاحظة: ستُفرض عليك رسوم إضافية بقيمة 0.0006 دولار أمريكي لاستخدام هذا المعامل؛

      إذا كان العنصر غائبًا أو يحتوي على "asynchronous_ai_overview": false، فستُعاد كل الرسوم الإضافية إلى رصيد حسابك

    • location_code
      النوع: integer

      رمز موقع محرك البحث

      حقل مطلوب إذا لم تحدد location_name أو location_coordinate

      إذا استخدمت هذا الحقل، فلا حاجة لتحديد location_name أو location_coordinate

      يمكنك الحصول على قائمة المواقع المتاحة لمحركات البحث مع location_code الخاص بها عبر إرسال طلب منفصل إلى https://api.dataforseo.com/v3/serp/google/locations

      مثال:

      2840

    • location_coordinate
      النوع: string

      إحداثيات GPS للموقع

      حقل مطلوب إذا لم تحدد location_name أو location_code

      إذا استخدمت هذا الحقل، فلا حاجة لتحديد location_name أو location_code

      يجب تحديد معامل location_coordinate بصيغة "latitude,longitude,radius"

      الحد الأقصى لعدد المنازل العشرية في "latitude" و"longitude": 7

      الحد الأدنى لقيمة "radius": 199 (مم)

      الحد الأقصى لقيمة "radius": 199999 (مم)

      مثال:

      53.476225,-2.243572,200

    • location_name
      النوع: string

      الاسم الكامل لموقع محرك البحث

      حقل مطلوب إذا لم تحدد location_code أو location_coordinate

      إذا استخدمت هذا الحقل، فلا حاجة لتحديد location_code أو location_coordinate

      يمكنك الحصول على قائمة المواقع المتاحة لمحرك البحث مع location_name الخاص بها عبر إرسال طلب منفصل إلى https://api.dataforseo.com/v3/serp/google/locations

      مثال:

      London,England,United Kingdom

    • match_type
      النوع: string

      نوع مطابقة الهدف

      حقل مطلوب إذا حُدد stop_crawl_on_match

      نوع المطابقة لقيمة match_value

      القيم الممكنة:

      domain – نطاق أو نطاق فرعي محدد

      with_subdomains – النطاق الرئيسي والنطاقات الفرعية

      wildcard – نمط حرف البدل

    • match_value
      النوع: string

      قيمة النطاق أو النطاق الفرعي أو حرف البدل المستهدف

      حقل مطلوب إذا حُدد stop_crawl_on_match

      حدد نطاقًا أو نطاقًا فرعيًا أو قيمة حرف بدل مستهدفة؛

      ملاحظة: يجب تحديد النطاق أو النطاق الفرعي دون بروتوكول طلب؛

      مثال: "match_value": "dataforseo.com"،

      "match_value": "/blog/post-*"

    • max_crawl_pages
      النوع: integer | null

      حد زحف الصفحات

      حقل اختياري

      عدد صفحات نتائج البحث المراد الزحف إليها

      القيمة القصوى: 100

      ملاحظة: ستُحتسب عليك رسوم عن كل صفحة تُزحف (10 نتائج عضوية لكل صفحة)؛

      اعرف المزيد عن التسعير في صفحة الأسعار؛

      ملاحظة#2: المعاملان max_crawl_pages وdepth يكمّل أحدهما الآخر؛

      تعرّف على المزيد في مركز المساعدة

    • os
      النوع: string | null

      نظام تشغيل الجهاز

      حقل اختياري

      إذا حددت desktop في حقل device، فاختر من القيم التالية: windows، macos

      القيمة الافتراضية: windows

      إذا حددت mobile في حقل device، فاختر من القيم التالية: android، ios

      القيمة الافتراضية: android

    • people_also_ask_click_depth
      النوع: integer | null

      النقرات على العنصر المقابل

      حقل اختياري

      حدد عمق النقر على عنصر people_also_ask للحصول على عناصر people_also_ask_element إضافية؛

      ملاحظة ستُحتسب على حسابك 0.00015 دولار إضافية عن كل نقرة بغض النظر عن أولوية المهمة؛

      إذا كان العنصر غائبًا أو نفّذنا نقرات أقل مما حددت، فستُعاد كل الرسوم الإضافية إلى رصيد حسابك

      القيم الممكنة: من 1 إلى 4

    • pingback_url
      النوع: string | null

      عنوان URL لإشعار اكتمال المهمة

      حقل اختياري

      عند اكتمال المهمة، سنُشعرك عبر طلب GET يُرسل إلى عنوان URL الذي حددته

      يمكنك استخدام السلسلة ‘$id’ كمتغيّر $id و‘$tag’ كمتغيّر $tag بترميز urlencoded. سنضبط القيم اللازمة قبل إرسال الطلب.

      مثال:

      http://your-server.com/pingscript?id=$id

      http://your-server.com/pingscript?id=$id&tag=$tag

      ملاحظة: تُرمَّز الأحرف الخاصة في pingback_url بترميز urlencoded؛

      منها أن الحرف # يُرمَّز إلى %23


      تعرّف على المزيد في مركز المساعدة

    • postback_data
      النوع: string

      نوع بيانات postback_url

      حقل مطلوب إذا حددت postback_url

      يطابق نوع البيانات الذي سيُرسل إلى خادمك

      القيم الممكنة:

      regular، advanced، html

    • postback_url
      النوع: string | null

      عنوان URL لإرسال نتائج المهمة

      حقل اختياري

      بعد اكتمال المهمة، سنرسل طلب POST بنتائجها مضغوطة بصيغة gzip إلى postback_url الذي حددته

      يمكنك استخدام السلسلة ‘$id’ كمتغيّر $id و‘$tag’ كمتغيّر $tag بترميز urlencoded. سنضبط القيم اللازمة قبل إرسال الطلب

      مثال:

      http://your-server.com/postbackscript?id=$id

      http://your-server.com/postbackscript?id=$id&tag=$tag

      ملاحظة: تُرمَّز الأحرف الخاصة في postback_url بترميز urlencoded;

      منها أن الحرف # يُرمَّز إلى %23


      تعرّف على المزيد في مركز المساعدة

    • priority
      النوع: integer | null

      أولوية المهمة

      حقل اختياري

      يمكن أن تأخذ القيم التالية:

      1 – أولوية تنفيذ عادية (تُضبط افتراضيًا)؛

      2 – أولوية تنفيذ عالية


      ستُحتسب عليك رسوم إضافية للمهام ذات أولوية التنفيذ العالية.

      يمكن حساب التكلفة في صفحة الأسعار.

    • remove_from_url
      النوع: array string[] | null

      إزالة معاملات محددة من عناوين URL

      حقل اختياري

      باستخدام هذا الحقل، يمكنك تحديد ما يصل إلى 10 معاملات لإزالتها من عناوين URL في النتيجة

      مثال:

      "remove_from_url": ["srsltid"]

    • se_domain
      النوع: string | null

      نطاق محرك البحث

      حقل اختياري

      نختار نطاق محرك البحث المناسب تلقائيًا وفقًا للموقع واللغة التي تحددها

      ومع ذلك، يمكنك تعيين نطاق محرك بحث مخصص في هذا الحقل

      مثال:

      google.co.uk, google.com.au, google.de، إلخ.

    • search_param
      النوع: string | null

      معاملات إضافية لاستعلام البحث

      حقل اختياري

      احصل على قائمة المعاملات المتاحة والتفاصيل الإضافية هنا


      ملاحظة: معاملات محرك البحث التالية غير مدعومة وسيُلغى ضبطها تلقائيًا إذا حُددت: lr، cr، as_qdr، as_sitesearch، as_occt، as_filetype.
    • stop_crawl_on_match
      النوع: array (object | null)[] | null

      مصفوفة أهداف لإيقاف الزحف حقل اختياري إذا حُددت، ستحتوي الاستجابة على نتائج SERP حتى القيمة المطابقة المحددة وشاملة إياها؛ يمكنك تحديد ما يصل إلى 10 قيم هدف في هذه المصفوفة مثال: "stop_crawl_on_match":[{"match_value":"dataforseo.com","match_type":"with_subdomains"}] تعرّف على المزيد حول هذا المعامل في مركز المساعدة - https://dataforseo.com/help-center/using-the-stop_crawl_on_match-parameter-in-serp-api ستُحتسب رسوم على حسابك عن كل SERP يُزحف عبر الأهداف المحددة

      • match_type
        النوع: string | null

        نوع مطابقة الهدف حقل مطلوب إذا حُدد stop_crawl_on_match؛ نوع المطابقة لقيمة match_value القيم الممكنة: domain، with_subdomains، wildcard

      • match_value
        النوع: string | null

        النطاق الهدف أو قيمة wildcard حقل مطلوب إذا حُدد stop_crawl_on_match؛ حدد نطاقًا هدفًا أو قيمة wildcard؛ ملاحظة: يجب تحديد اسم النطاق دون بروتوكول طلب؛ مثال: dataforseo.com

    • tag
      النوع: string | null

      معرّف مهمة يعرّفه المستخدم

      حقل اختياري

      حد الأحرف 255

      يمكنك استخدام هذا المعامل لتعريف المهمة ومطابقتها مع النتيجة

      ستجد قيمة tag المحددة في كائن data في الاستجابة

    • target_search_mode
      النوع: string | null

      وضع مطابقة الأهداف

      حقل اختياري

      لتفعيل هذا المعامل، يجب أيضًا تفعيل stop_crawl_on_match

      يحدد كيف يتوقف الزحف عند تحديد أهداف متعددة في stop_crawl_on_match

      القيم الممكنة: all، any

      all – لا يتوقف الزحف إلا عند العثور على جميع الأهداف المحددة

      any – يتوقف الزحف عند العثور على أي هدف واحد

      القيمة الافتراضية: any

      تعرّف على المزيد حول هذا المعامل في مركز المساعدة

    • url
      النوع: string | null

      عنوان URL المباشر لاستعلام البحث

      حقل اختياري

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

      مثال:

      https://www.google.co.uk/search?q=%20rank%20tracker%20api&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS


      ملاحظة: معاملات محرك البحث التالية غير مدعومة وسيُلغى ضبطها تلقائيًا إذا حُددت في عنوان URL: lr، cr، as_qdr، as_sitesearch، as_occt، as_filetype.
الاستجابات
  • 200
    النوع: object | null · Response36Afe1097B20_SerpGoogleOrganicTaskPostResponseInfo
    • cost
      النوع: number | null التنسيق: double

      إجمالي تكلفة المهام، بالدولار الأمريكي

    • status_code
      النوع: integer | null

      رمز الحالة العام يمكنك العثور على القائمة الكاملة لرموز الاستجابة هنا

    • status_message
      النوع: string | null

      رسالة معلوماتية عامة يمكنك العثور على القائمة الكاملة للرسائل المعلوماتية العامة هنا

    • tasks
      النوع: array (object | null)[] | null

      مصفوفة المهام

      • النوع: object | null · Response36Afe1097B20_SerpGoogleOrganicTaskPostTaskInfo
        • cost
          النوع: number | null التنسيق: double

          إجمالي تكلفة المهام، بالدولار الأمريكي

        • data
          النوع: object | null

          يحتوي على المعاملات نفسها التي حددتها في طلب POST

          • propertyName
            النوع: object | null
        • id
          النوع: string | null

          معرّف المهمة معرّف مهمة فريد في نظامنا بصيغة UUID

        • path
          النوع: array (string | null)[] | null

          مسار URL

        • result
          النوع: object | null

          مصفوفة نتائج
          في هذه الحالة، ستكون القيمة null

        • result_count
          النوع: integer | null التنسيق: int64

          عدد العناصر في مصفوفة result

        • status_code
          النوع: integer | null

          رمز حالة المهمة ينشئه DataForSEO ويمكن أن يقع ضمن النطاق التالي: 10000-60000 يمكنك العثور على القائمة الكاملة لرموز الاستجابة هنا

        • status_message
          النوع: string | null

          الرسالة المعلوماتية للمهمة يمكنك العثور على القائمة الكاملة للرسائل المعلوماتية العامة هنا

        • time
          النوع: string | null

          وقت التنفيذ، بالثواني

    • tasks_count
      النوع: integer | null التنسيق: int64

      عدد المهام في مصفوفة tasks

    • tasks_error
      النوع: integer | null التنسيق: int64

      عدد المهام في مصفوفة tasks التي أُعيدت مع خطأ

    • time
      النوع: string | null

      إجمالي وقت التنفيذ، بالثواني

    • version
      النوع: string | null

      الإصدار الحالي من API

    application/json
  • 400

    تعذّرت معالجة الطلب. تحقق من معاملات الطلب.

  • 401

    مطلوب مفتاح API صالح من Felo.

  • 402

    لا يمكن متابعة الطلب لأن أحد متطلبات الفوترة غير مستوفٍ.

  • 403

    الحساب غير مصرّح له بهذه العملية.

  • 429

    تم بلوغ حد الطلبات أو حد الإنفاق.

  • 502

    تعذّر على الخدمة إكمال الطلب.

  • 503

    خدمة API أو الفوترة غير متاحة مؤقتًا.

  • 504

    انتهت مهلة الخدمة أثناء معالجة الطلب.

  • default

    استجابة خطأ؛ قد تستخدم استجابات المنبع الممرَّرة تنسيقات المزوّد

    application/json
Request Example for post/v1/beta/dataforseo/serp/google/organic/task_post
curl https://openapi.felo.ai/v1/beta/dataforseo/serp/google/organic/task_post \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '[
  {
    "language_code": "en",
    "location_code": 2840,
    "keyword": "albert einstein"
  },
  {
    "language_name": "English",
    "location_name": "United States",
    "keyword": "albert einstein",
    "priority": 2,
    "tag": "some_string_123",
    "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
  },
  {
    "url": "https://www.google.co.uk/search?q=albert%20einstein&hl=en&gl=GB&uule=w+CAIQIFISCXXeIa8LoNhHEZkq1d1aOpZS",
    "postback_data": "html",
    "postback_url": "https://your-server.com/postbackscript"
  }
]'

{
  "version": null,
  "status_code": null,
  "status_message": null,
  "time": null,
  "cost": null,
  "tasks_count": null,
  "tasks_error": null,
  "tasks": [
    {
      "id": null,
      "status_code": null,
      "status_message": null,
      "time": null,
      "cost": null,
      "result_count": null,
      "path": [
        null
      ],
      "data": null,
      "result": null
    }
  ]
}

عملية ناجحة

Setting Google Organic SERP Tasks