DataForSEO
SEO, search-engine results, keyword research, backlinks and AI visibility data.
إعداد مهام ‘Ad Traffic By Keywords’
يضع في قائمة الانتظار توقّعًا للنقرات والظهور والإنفاق لكلمات keywords عند bid ونوع match معيّنين، ويعيد معرّف مهمة id. يضمّ search_partners شبكة شركاء Google. الاستجابة مغلّفة في غلاف DataForSEO: البيانات في tasks[0].result، والنتيجة في tasks[0].status_code — ولا يزال الطلب المرفوض يعيد HTTP 200. هذه نقطة نهاية Google Ads الوحيدة هنا التي لا متغيّر مباشر لها — فالتنبؤ يُوضع في قائمة الانتظار دائمًا. استرجعها عبر get_dataforseo_keywords_gads_ad_traffic_fetch.
مرجع التسعير
- القياس: تكلفة الاستجابة المُبلَّغ عنها.
- تقدير الطلب المرجعي: 0.09 دولار أمريكي.
- مضاعف العميل المرجعي: 1.0. لا تُطبّقه مرة أخرى على مبلغ عميل مسوّى.
بيانات وصفية مرجعية فقط، وليست عرض سعر للحساب ولا سعرًا مضمونًا ولا حدًا للإنفاق. أرصدة الموارد ليست أرصدة Felo. تتبع الرسوم النهائية سجلات فوترة Felo.
- النوع: array (object | null)[]
- bidالنوع: number
الحد الأقصى للمزايدة المخصصة
حقل مطلوب
ستستند البيانات المجمّعة إلى هذه القيمة
وهي تمثل السعر الذي ترغب في دفعه مقابل إعلان؛ فكلما كانت القيمة التي تحددها هنا أعلى، حصلت على قيم أعلى في المقاييس المعادة
تعرّف على المزيد في مقال مركز المساعدة هذا - dateالنوع: string
_from تاريخ بدء نطاق فترة التوقع
حقل مطلوب إذا حددتdate_to
إذا حددتdate_fromوdate_to، فلا حاجة لتحديدdate_interval
الحد الأدنى للقيمة هو تاريخ الغد
يجب ألا تكون القيمة التي تحددها فيdate_fromأبعد منdate_to
صيغة التاريخ:"yyyy-mm-dd"
مثال:"2021-10-30"إذا أعادت نقطة نهاية الحالة القيمةfalseفي الحقلactual_data، فيمكن ضبطdate_fromعلى الشهر قبل الماضي وما قبله؛
إذا أعادت نقطة نهاية الحالة القيمةtrueفي الحقلactual_data، فيمكن ضبطdate_fromعلى الشهر الماضي وما قبله - dateالنوع: string | null
_interval فترة تاريخ التوقع
حقل اختياري
إذا حددتdate_interval، فلا حاجة للإشارة إلىdate_fromوdate_to
القيم الممكنة:next_week،next_month،next_quarter
القيمة الافتراضية:next_month - dateالنوع: string
_to تاريخ انتهاء نطاق فترة التوقع
حقل مطلوب إذا حددتdate_from
إذا حددتdate_fromوdate_to، فلا حاجة لتحديدdate_interval
الحد الأدنى للقيمة هوdate_from+ يوم واحد
الحد الأقصى للقيمة هو اليوم والشهر الحاليان من العام التالي
صيغة التاريخ:"yyyy-mm-dd"
مثال:"2022-10-30" - keywordsالنوع: array string[]
الكلمات المفتاحية
حقل مطلوب
الحد الأقصى لعدد الكلمات المفتاحية التي يمكنك تحديدها: 1000
الحد الأقصى لعدد الأحرف لكل كلمة مفتاحية: 80
الحد الأقصى لعدد الكلمات لكل عبارة مفتاحية: 10
ستُحوَّل الكلمات المفتاحية التي تحددها إلى أحرف صغيرة
ملاحظة 1: قد لا يعيد Google Ads بيانات لبعض مجموعات الكلمات المفتاحية؛
ملاحظة 2: يوفّر Google Ads قيم حجم بحث مجمّعة لمجموعات من الكلمات المفتاحية المتشابهة
للحصول على حجم البحث لكلمات مفتاحية متشابهة، نوصي بإرسال هذه الكلمات في طلبات منفصلة؛
ملاحظة 3: لا يسمح Google Ads باستخدام رموز وأحرف معينة (مثل رموز UTF والرموز التعبيرية)، لذا لا يمكنك استخدامها عند إعداد المهمة؛
لمعرفة المزيد حول الرموز والأحرف التي يمكن استخدامها، راجع هذا المقالتعرّف على قواعد وقيود حقلَي
keywordوkeywordsفي واجهات DataForSEO API في مقال مركز المساعدة - languageالنوع: string | null
_code رمز لغة محرك البحث
حقل اختياري
يمكنك الحصول على قائمة اللغات المتاحة لمحرك البحث معlanguage_codeالخاص بها عبر إرسال طلب منفصل إلىhttps://api.dataforseo.com/v3/keywords_data/google_ads/languages
مثال:en - languageالنوع: string | null
_name الاسم الكامل للغة محرك البحث
حقل اختياري
يمكنك الحصول على قائمة اللغات المتاحة لمحرك البحث معlanguage_nameالخاص بها عبر إرسال طلب منفصل إلىhttps://api.dataforseo.com/v3/keywords_data/google_ads/languages
مثال:English - locationالنوع: integer | null
_code رمز موقع محرك البحث
حقل اختياري
إذا لم تحدد الموقع، فستتلقى نتائج عالمية، أي لجميع المواقع المتاحة؛
إذا استخدمت هذا الحقل، فلا حاجة لتحديدlocation_nameأوlocation_coordinate؛
يمكنك الحصول على قائمة المواقع المتاحة لمحركات البحث معlocation_codeالخاص بها عبر إرسال طلب منفصل إلىhttps://api.dataforseo.com/v3/keywords_data/google_ads/locations
مثال:2840 - locationالنوع: string | null
_coordinate إحداثيات GPS للموقع
حقل اختياري
إذا لم تحدد الموقع، فستتلقى نتائج عالمية، أي لجميع المواقع المتاحة؛
إذا استخدمت هذا الحقل، فلا حاجة لتحديدlocation_nameأوlocation_code؛
يجب تحديد معاملlocation_coordinateبصيغة "latitude,longitude"؛
ستُقدَّم البيانات للبلد الذي تنتمي إليه الإحداثيات المحددة؛
مثال:52.6178549,-155.352142 - locationالنوع: string | null
_name الاسم الكامل لموقع محرك البحث
حقل اختياري
إذا لم تحدد الموقع، فستتلقى نتائج عالمية، أي لجميع المواقع المتاحة؛
إذا استخدمت هذا الحقل، فلا حاجة لتحديدlocation_codeأوlocation_coordinate
يمكنك الحصول على قائمة المواقع المتاحة لمحرك البحث معlocation_nameالخاص بها عبر إرسال طلب منفصل إلىhttps://api.dataforseo.com/v3/keywords_data/google_ads/locations
مثال:London,England,United Kingdom - matchالنوع: string
نوع مطابقة الكلمات المفتاحية
حقل مطلوب
يمكن أن يأخذ القيم التالية:exact،broad،phrase - pingbackالنوع: string | null
_url عنوان URL لإشعار اكتمال المهمة
حقل اختياري
عند اكتمال المهمة، سنُشعرك عبر طلب GET يُرسل إلى عنوان URL الذي حددته
يمكنك استخدام السلسلة ‘$id’ كمتغيّر$idو‘$tag’ كمتغيّر$tagبترميز urlencoded. سنضبط القيم اللازمة قبل إرسال الطلب.
مثال:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
ملاحظة: تُرمَّز الأحرف الخاصة فيpingback_urlبترميز urlencoded;
منها أن الحرف#يُرمَّز إلى%23 - postbackالنوع: string | null
_url عنوان URL لإرسال نتائج المهمة
حقل اختياري
بعد اكتمال المهمة، سنرسل طلب POST بنتائجها مضغوطة بصيغةgzipإلىpostback_urlالذي حددته
يمكنك استخدام السلسلة ‘$id’ كمتغيّر$idو‘$tag’ كمتغيّر$tagبترميز urlencoded. سنضبط القيم اللازمة قبل إرسال الطلب.
مثال:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
ملاحظة: تُرمَّز الأحرف الخاصة فيpostback_urlبترميز urlencoded;
منها أن الحرف#يُرمَّز إلى%23 - sortالنوع: string | null
_by معاملات فرز النتائج
حقل اختياري
استخدم هذه المعاملات لفرز النتائج حسبrelevanceأوaverage_cpcأوcostأوclicksبترتيب تنازلي
القيمة الافتراضية:relevance - tagالنوع: string | null
معرّف مهمة يحدده المستخدم
حقل اختياري
الحد الأقصى للأحرف هو 255
يمكنك استخدام هذا المعامل لتمييز المهمة ومطابقتها مع النتيجة
ستجد قيمةtagالمحددة في كائنdataضمن الاستجابة
- النوع: object | null · Response36Afe1097B20_KeywordsDataGoogleAdsAdTrafficByKeywordsTaskPostResponseInfo200
- النوع: number | null التنسيق: doublecost
إجمالي تكلفة المهام، بالدولار الأمريكي
- النوع: integer | nullstatus
_code رمز الحالة العام يمكنك العثور على القائمة الكاملة لرموز الاستجابة هنا
- النوع: string | nullstatus
_message رسالة معلوماتية عامة يمكنك العثور على القائمة الكاملة للرسائل المعلوماتية العامة هنا
- النوع: array (object | null)[] | nulltasks
مصفوفة المهام
- النوع: object | null · Response36Afe1097B20_KeywordsDataGoogleAdsAdTrafficByKeywordsTaskPostTaskInfo
- costالنوع: number | null التنسيق: double
إجمالي تكلفة المهام، بالدولار الأمريكي
- dataالنوع: object | null
يحتوي على المعاملات نفسها التي حددتها في طلب POST
- propertyالنوع: object | null
Name
- idالنوع: string | null
معرّف المهمة معرّف مهمة فريد في نظامنا بصيغة UUID
- pathالنوع: array (string | null)[] | null
مسار URL
- resultالنوع: object | null
مصفوفة نتائج
في هذه الحالة، ستكون القيمةnull - resultالنوع: integer | null التنسيق: int64
_count عدد العناصر في مصفوفة result
- statusالنوع: integer | null
_code رمز حالة المهمة ينشئه DataForSEO ويمكن أن يقع ضمن النطاق التالي: 10000-60000 يمكنك العثور على القائمة الكاملة لرموز الاستجابة هنا
- statusالنوع: string | null
_message الرسالة المعلوماتية للمهمة يمكنك العثور على القائمة الكاملة للرسائل المعلوماتية العامة هنا
- timeالنوع: string | null
وقت التنفيذ، بالثواني
- النوع: integer | null التنسيق: int64tasks
_count عدد المهام في مصفوفة tasks
- النوع: integer | null التنسيق: int64tasks
_error عدد المهام في مصفوفة tasks التي أُعيدت مع خطأ
- النوع: string | nulltime
إجمالي وقت التنفيذ، بالثواني
- النوع: string | nullversion
الإصدار الحالي من API
application/json - 400
تعذّرت معالجة الطلب. تحقق من معاملات الطلب.
- 401
مطلوب مفتاح API صالح من Felo.
- 402
لا يمكن متابعة الطلب لأن أحد متطلبات الفوترة غير مستوفٍ.
- 403
الحساب غير مصرّح له بهذه العملية.
- 429
تم بلوغ حد الطلبات أو حد الإنفاق.
- 502
تعذّر على الخدمة إكمال الطلب.
- 503
خدمة API أو الفوترة غير متاحة مؤقتًا.
- 504
انتهت مهلة الخدمة أثناء معالجة الطلب.
- default
استجابة خطأ؛ قد تستخدم استجابات المنبع الممرَّرة تنسيقات المزوّد
application/json
curl https://openapi.felo.ai/v1/beta/dataforseo/keywords_data/google_ads/ad_traffic_by_keywords/task_post \
--request POST \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--data '[
{
"language_code": "en",
"location_code": 2840,
"bid": 999,
"match": "exact",
"keywords": [
"seo marketing"
]
}
]'
{
"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
}
]
}