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

إعداد مهام ‘Google Ads Search Volume’ المباشرة

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

DataForSEO

​

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

DataForSEO العمليات

إعداد مهام ‘Google Ads Search Volume’ المباشرة

​

حجم البحث في Google Ads لقائمة keywords. يعيد keyword وlocation_code وlanguage_code وsearch_partners وcompetition وcompetition_index وsearch_volume وlow_top_of_page_bid وhigh_top_of_page_bid وcpc وmonthly_searches، إضافةً إلى spell عندما يصحّح Google المصطلح. الاستجابة مغلّفة في غلاف DataForSEO: البيانات في tasks[0].result، والنتيجة في tasks[0].status_code — ولا يزال الطلب المرفوض يعيد HTTP 200. هذا رقم حجم البحث الكلاسيكي؛ ولمعرفة مدى تكرار سؤال الناس لمساعد بدلًا من ذلك، استخدم post_dataforseo_ai_keyword_volume_live. تؤدي نظيرتا الإرسال والجلب لهذه النقطة العمل نفسه بشكل غير متزامن، وبالسعر نفسه، للدفعات الأكبر من أن يُنتظر عليها.

مرجع التسعير

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

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

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

      تاريخ بدء النطاق الزمني
      حقل اختياري
      صيغة التاريخ: "yyyy-mm-dd"
      الحد الأدنى للقيمة: 4 سنوات من التاريخ الحالي
      بشكل افتراضي، تُعاد البيانات للـ 12 شهرًا الماضية؛
      ملاحظة: لا يمكن أن يكون التاريخ المحدد أكبر من التاريخ المحدد في date_to و/أو تاريخ الأمس؛ إذا أعادت نقطة نهاية الحالة القيمة false في الحقل actual_data، فيمكن ضبط date_from على الشهر قبل الماضي وما قبله؛
      إذا أعادت نقطة نهاية الحالة القيمة true في الحقل actual_data، فيمكن ضبط date_from على الشهر الماضي وما قبله

    • date_to
      النوع: string | null

      تاريخ انتهاء النطاق الزمني
      حقل اختياري
      ملاحظة: لا يمكن أن يكون التاريخ المحدد أكبر من الشهر الماضي، إذ لا يعيد Google Ads بيانات عن الشهر الحالي؛
      إذا لم تحدد هذا الحقل، فسيُستخدم تاريخ الأمس افتراضيًا
      صيغة التاريخ: "yyyy-mm-dd"
      مثال:
      "2022-11-30"

    • include_adult_keywords
      النوع: boolean | null

      تضمين الكلمات المفتاحية المرتبطة بمحتوى للبالغين
      حقل اختياري
      إذا عُيّن على true، فستُضمَّن الكلمات المفتاحية للبالغين في الاستجابة
      القيمة الافتراضية: false
      لاحظ أن API قد لا يعيد بيانات لهذه الكلمات المفتاحية بسبب قيود Google Ads

    • keywords
      النوع: array string[]

      الكلمات المفتاحية
      حقل مطلوب
      الحد الأقصى لعدد الكلمات المفتاحية التي يمكنك تحديدها: 1000
      الحد الأقصى لعدد الأحرف لكل كلمة مفتاحية: 80
      الحد الأقصى لعدد الكلمات لكل عبارة مفتاحية: 10
      ستُحوَّل الكلمات المفتاحية التي تحددها إلى أحرف صغيرة
      ملاحظة 1: قد لا يعيد Google Ads بيانات لبعض مجموعات الكلمات المفتاحية؛
      ملاحظة 2: يوفّر Google Ads قيم حجم بحث مجمّعة لمجموعات من الكلمات المفتاحية المتشابهة
      للحصول على حجم البحث لكلمات مفتاحية متشابهة، نوصي بإرسال هذه الكلمات في طلبات منفصلة؛
      ملاحظة 3: لا يسمح Google Ads باستخدام رموز وأحرف معينة (مثل رموز UTF والرموز التعبيرية)، لذا لا يمكنك استخدامها عند إعداد المهمة؛
      لمعرفة المزيد حول الرموز والأحرف التي يمكن استخدامها، راجع هذا المقال

      تعرّف على قواعد وقيود حقلَي keyword وkeywords في واجهات DataForSEO API في مقال مركز المساعدة

    • language_code
      النوع: string | null

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

    • language_name
      النوع: string | null

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

    • location_code
      النوع: integer | null

      رمز موقع محرك البحث
      حقل اختياري
      إذا لم تحدد الموقع، فستتلقى نتائج عالمية، أي لجميع المواقع المتاحة؛
      إذا استخدمت هذا الحقل، فلا حاجة لتحديد location_name أو location_coordinate؛
      يمكنك الحصول على قائمة المواقع المتاحة لمحركات البحث مع location_code الخاص بها عبر إرسال طلب منفصل إلى https://api.dataforseo.com/v3/keywords_data/google_ads/locations
      مثال:
      2840

    • location_coordinate
      النوع: string | null

      إحداثيات GPS للموقع
      حقل اختياري
      إذا لم تحدد الموقع، فستتلقى نتائج عالمية، أي لجميع المواقع المتاحة؛
      إذا استخدمت هذا الحقل، فلا حاجة لتحديد location_name أو location_code؛
      يجب تحديد معامل location_coordinate بصيغة "latitude,longitude"؛
      ستُقدَّم البيانات للبلد الذي تنتمي إليه الإحداثيات المحددة؛
      مثال:
      52.6178549,-155.352142

    • location_name
      النوع: string | null

      الاسم الكامل لموقع محرك البحث
      حقل اختياري
      إذا لم تحدد الموقع، فستتلقى نتائج عالمية، أي لجميع المواقع المتاحة؛
      إذا استخدمت هذا الحقل، فلا حاجة لتحديد location_code أو location_coordinate
      يمكنك الحصول على قائمة المواقع المتاحة لمحرك البحث مع location_name الخاص بها عبر إرسال طلب منفصل إلى https://api.dataforseo.com/v3/keywords_data/google_ads/locations
      مثال:
      London,England,United Kingdom

    • search_partners
      النوع: boolean | null

      تضمين شركاء بحث Google
      حقل اختياري
      إذا حددت true، فستُقدَّم النتائج للشبكات المملوكة والمُدارة والموزَّعة عبر Google والمواقع الشريكة التي تستضيف بحث Google؛
      القيمة الافتراضية: false - تُعاد النتائج لمواقع بحث Google

    • sort_by
      النوع: string | null

      معاملات فرز النتائج
      حقل اختياري
      استخدم هذه المعاملات لفرز النتائج حسب relevance أو search_volume أو competition_index أو low_top_of_page_bid أو high_top_of_page_bid بترتيب تنازلي
      القيمة الافتراضية: relevance

    • tag
      النوع: string | null

      معرّف مهمة يحدده المستخدم
      حقل اختياري
      الحد الأقصى للأحرف هو 255
      يمكنك استخدام هذا المعامل لتمييز المهمة ومطابقتها مع النتيجة
      ستجد قيمة tag المحددة في مصفوفة data ضمن الاستجابة

الاستجابات
  • 200
    النوع: object | null · Response36Afe1097B20_KeywordsDataGoogleAdsSearchVolumeLiveResponseInfo
    • cost
      النوع: number | null التنسيق: double

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

    • status_code
      النوع: integer | null

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

    • status_message
      النوع: string | null

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

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

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

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

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

        • data
          النوع: object | null

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

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

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

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

          مسار URL

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

          مصفوفة نتائج

          • competition
            النوع: string | null

            المنافسة
            تمثّل مقدار المنافسة النسبي المرتبط بالكلمة المفتاحية المحددة في SERP المدفوعة فقط؛
            تستند هذه القيمة إلى بيانات Google Ads ويمكن أن تأخذ القيم التالية: HIGH، MEDIUM، LOW؛
            إذا لم تكن هناك بيانات، تكون القيمة null؛
            اعرف المزيد عن هذا المقياس في مقالة مركز المساعدة هذه

          • competition_index
            النوع: integer | null

            المنافسة
            تمثّل مقدار المنافسة النسبي المرتبط بالكلمة المفتاحية المحددة في SERP المدفوعة فقط؛
            تستند هذه القيمة إلى بيانات Google Ads ويمكن أن تتراوح بين 0 و100 (شاملةً الطرفين)؛
            إذا لم تكن هناك بيانات، تكون القيمة null؛
            اعرف المزيد عن هذا المقياس في مقالة مركز المساعدة هذه

          • cpc
            النوع: number | null

            تكلفة النقرة
            تشير إلى المبلغ المدفوع (بالدولار الأمريكي) مقابل كل نقرة على الإعلان المعروض لكلمة مفتاحية معينة

          • high_top_of_page_bid
            النوع: number | null

            أقصى مزايدة لعرض الإعلان في أعلى الصفحة الأولى
            تشير إلى قيمة أكبر من نحو 80% من أدنى المزايدات التي عُرضت عندها الإعلانات (استنادًا إلى إحصاءات Google Ads للمعلنين)؛
            قد تختلف القيمة حسب الموقع المحدد في طلب POST

          • keyword
            النوع: string | null

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

          • language_code
            النوع: string | null

            رمز اللغة في مصفوفة POST
            فإذا لم تكن هناك بيانات، تكون القيمة null

          • location_code
            النوع: integer | null

            رمز الموقع في مصفوفة POST
            فإذا لم تكن هناك بيانات، تكون القيمة null

          • low_top_of_page_bid
            النوع: number | null

            أدنى مزايدة لعرض الإعلان في أعلى الصفحة الأولى
            تشير إلى قيمة أكبر من نحو 20% من أدنى المزايدات التي عُرضت عندها الإعلانات (استنادًا إلى إحصاءات Google Ads للمعلنين)؛
            قد تختلف القيمة حسب الموقع المحدد في طلب POST

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

            عمليات البحث الشهرية
            تمثّل العدد (التقريبي) لعمليات البحث على فكرة الكلمة المفتاحية هذه (كما هو متاح للأشهر الاثني عشر الماضية افتراضيًا)، موجّهة إلى المواقع الجغرافية المحددة؛
            إذا لم تكن هناك بيانات، تكون القيمة_nulln

            • month
              النوع: integer | null

              الشهر

            • search_volume
              النوع: integer | null

              متوسط معدل حجم البحث الشهري

            • year
              النوع: integer | null

              السنة

          • search_partners
            النوع: boolean | null

            تشير إلى ما إذا كانت بيانات شبكات الشركاء مضمنة في الاستجابة

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

            متوسط معدل حجم البحث الشهري؛
            يمثّل العدد (التقريبي) لعمليات البحث عن فكرة الكلمة المفتاحية المحددة إما على google.com أو على google.com والشركاء، وفقًا لاستهداف المستخدم؛
            إذا لم تكن هناك بيانات، تكون القيمة_nulln

          • spell
            النوع: string | null

            الهجاء الصحيح للكلمة المفتاحية
            ملاحظة:إذا بدت الكلمة المفتاحية في طلب POST مكتوبة خطأً، فستُعاد البيانات للكلمة المفتاحية المكتوبة بشكل صحيح؛
            نستخدم وظيفة Google Ads API للتحقق من هجاء الكلمات المفتاحية والتحقق منه، اعرف المزيد من هذا الرابط

        • 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/keywords_data/google_ads/search_volume/live
curl https://openapi.felo.ai/v1/beta/dataforseo/keywords_data/google_ads/search_volume/live \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '[
  {
    "location_code": 2840,
    "keywords": [
      "buy laptop",
      "cheap laptops for sale",
      "purchase laptop"
    ],
    "date_from": "2021-08-01",
    "search_partners": true
  }
]'

{
  "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": [
        {
          "keyword": null,
          "spell": null,
          "location_code": null,
          "language_code": null,
          "search_partners": null,
          "competition": null,
          "competition_index": null,
          "search_volume": null,
          "low_top_of_page_bid": null,
          "high_top_of_page_bid": null,
          "cpc": null,
          "monthly_searches": [
            {
              "year": null,
              "month": null,
              "search_volume": null
            }
          ]
        }
      ]
    }
  ]
}

عملية ناجحة

Setting Live ‘Google Ads Search Volume’ Tasks