واجهة API لتدقيق SEO بلغة Python: دقّق قائمة مواقع وصدّرها إلى CSV
برنامج Python جاهز للعمل مع واجهة API لتدقيق SEO من SEOReport: أرسل قائمة مواقع، وتابع حالة كل تقرير حتى يجهز، وصدّر النتائج إلى ملف CSV واحد.
لتدقيق قائمة مواقع باستخدام Python، تحتاج إلى ثلاثة استدعاءات إلى REST API من SEOReport لكل موقع: إنشاء تقرير، ثم الاستعلام عن حالته حتى لا يعود في قائمة الانتظار أو قيد التشغيل، ثم قراءة النتيجة المكتملة. يفعل البرنامج النصي أدناه ذلك لقائمة نطاقات في ملف نصي عادي، ويُبقي بضعة تقارير قيد التشغيل في الوقت نفسه، وينتظر بين الاستعلامات المدة التي تطلبها الواجهة، وينتج صفًّا واحدًا في ملف CSV لكل نتيجة فاشلة أو تحذيرية. ويتطلب Python 3.8 أو أحدث، والحزمة requests، ومفتاح API من خطة مدفوعة.
كل نقطة نهاية وكل حقل مستخدم هنا إما مذكور في صفحة المطورين ومرجع API، وإما جزء من JSON الذي تعيده نقطة نهاية النتيجة. وقد طابقنا أسماء الحقول مع تلك البيانات في أكتوبر 2026.
ما تحتاجه قبل الطلب الأول
الوصول إلى API مرتبط بالحساب. تُنشئ المفتاح في إعدادات حسابك بمجرد أن تكون لديك خطة، ويعمل المفتاح نفسه مع REST ومع خادم MCP. ويُرسَل مع كل طلب بوصفه رمزًا من نوع Bearer:
Authorization: Bearer YOUR_API_KEY
لا تضع المفتاح داخل البرنامج النصي نفسه. صدّره متغيرَ بيئة واقرأه عند بدء التشغيل:
export SEOREPORT_API_KEY="your key from account settings"pip install requests
ثمة حقيقتان عن الأرصدة تحددان طريقة بناء القائمة. كل موقع جديد تدقّقه عبر API يستهلك رصيدًا من خطتك، تمامًا كما يحدث على الموقع الإلكتروني. أما تشغيل موقع لديك تقرير عنه بالفعل فلا يستهلك رصيدًا آخر. وقبل أي دفعة كبيرة، قارن عدد المواقع الجديدة في القائمة بما تبقى في خطتك؛ فالبرنامج يتوقف عن الإرسال حين تنفد الأرصدة ويظل يصدّر ما اكتمل، لكن الأفضل أن تعرف ذلك مسبقًا.
المُدخل ملف نصي فيه موقع واحد في كل سطر:
example.comexample.orgshop.example.net
أرسل كل موقع بعنوان صفحته الرئيسية. فالواجهة تقرأ عنوان URL الذي ترسله: النطاق المجرد أو الصفحة الرئيسية يحصل على تدقيق للموقع يشمل الصفحة الرئيسية والصفحات التي تدرجها خريطة موقعه وتلك التي تشير إليها روابطه الداخلية، أما العنوان الذي يتضمن مسارًا فيُدقَّق صفحةً واحدة بمفردها. ولمجموعة من المواقع، النطاقات المجردة هي ما تحتاجه.
كيف تتكامل الاستدعاءات
Diagram source
sequenceDiagram
participant S as برنامج Python
participant A as واجهة SEOReport API
S->>A: POST /api/v1/reports مع عنوان الموقع
A-->>S: report.jobId و report.status
loop حتى لا تكون الحالة queued أو running
S->>A: GET /api/v1/reports/jobId
A-->>S: report.status و pollAfterMs
end
S->>A: GET /api/v1/reports/jobId/result
A-->>S: الدرجة والنتائج الكاملة
S->>S: إضافة النتائج الفاشلة والتحذيرية إلى ملف CSVيعود استدعاء الإرسال سريعًا بمعرّف مهمة. ويخبرك استدعاء الحالة بموضع التقرير: queued، ثم running، ثم completed أو failed. وتحمل كل استجابة للحالة أيضًا pollAfterMs، وهو عدد الميلي ثانية التي تقترح الواجهة انتظارها قبل الاستعلام مجددًا. وما دام التقرير قيد التشغيل تكون القيمة بضع ثوانٍ، وتنخفض إلى 0 حين يكتمل التقرير. وتكتمل معظم التقارير في أقل من دقيقة.
الخطوة 1: أرسل كل موقع وتعامل مع حالات الرفض
ترسل دالة الإرسال عنوان URL وتعيد معرّف المهمة. وتقرر كذلك ما يجب فعله حين ترفض الواجهة، لأن برنامج الدفعات يجب أن يميّز بين «تمهّل» و«توقّف» و«تجاوز هذا الموقع».
"""Audit a list of sites with the SEOReport API and export the findings to CSV."""import csvimport osimport sysimport timeimport requestsBASE = "https://seoreport.dev/api/v1/reports"IN_FLIGHT = 5 # reports running at the same timeSUBMIT_PAUSE = 2 # seconds between submissionsMAX_WAIT = 600 # seconds before a report that never finishes is recordedCSV_FIELDS = ["site", "audited_url", "audited_at", "score", "status", "area","finding", "why_it_matters", "fix", "note", "job_id"]session = requests.Session()session.headers["Authorization"] = "Bearer " + os.environ["SEOREPORT_API_KEY"]class OutOfCredits(Exception):"""The account cannot run another new site, so stop submitting."""def submit(site, attempts=3):"""Create a report for one site. Returns (job_id, None) or (None, error)."""for _ in range(attempts):resp = session.post(BASE, json={"url": site}, timeout=60)if resp.status_code == 503:time.sleep(int(resp.headers.get("Retry-After", "30")))continuebody = resp.json()if resp.status_code == 402:raise OutOfCredits(body["error"])if not body.get("success"):return None, f"HTTP {resp.status_code}: {body.get('error')}"return body["report"]["jobId"], Nonereturn None, f"HTTP {resp.status_code} after {attempts} attempts"
ولكل رمز استجابة تتعامل معه الدالة معنى مختلف بالنسبة إلى الدفعة:
Diagram source
flowchart TD
A["POST /api/v1/reports"] --> B{"رمز حالة HTTP"}
B -->|"201"| C["احتفظ بـ report.jobId وابدأ الاستعلام عن الحالة"]
B -->|503| D["انتظر ثم أعد الإرسال، حتى 3 محاولات"]
B -->|"402"| E["نفدت الأرصدة أو لا توجد خطة: أوقف الإرسال"]
B -->|"429، أو خطأ آخر"| F["سجّل الخطأ لهذا الموقع وتابع"]يعني الرمز 402 أن الحساب لا يستطيع الآن تشغيل موقع جديد آخر، فكل إرسال لاحق سيفشل بالطريقة نفسها. لذا يتوقف البرنامج عن الإرسال، ويترك التقارير الجارية تكتمل، ويسجّل بقية القائمة على أنها لم تُدقَّق مع رسالة الواجهة، فيبقى ملف CSV حاويًا كل ما اكتمل. ويعني الرمز 503 أن الخدمة لم تستطع قبول التقرير في تلك اللحظة، فينتظر البرنامج ويعيد إرسال الموقع نفسه، ملتزمًا بترويسة Retry-After إن أرسلتها الواجهة، ومنتظرًا 30 ثانية إن لم ترسلها؛ وبعد 3 مرات من الرفض يسجّل الموقع ويتابع. ولا يُعاد إرسال طلب أعاد 429. فإذا كان مصدره أحد حدود تدقيق الصفحات، بيّن الحقل code أيّ حدّ هو، PAGE_AUDIT_HOURLY_LIMIT أو PAGE_AUDIT_DAILY_LIMIT، وأعطت الترويسة Retry-After عدد الثواني المتبقية حتى يُرفع، وقد يقارب ذلك ساعة كاملة أو يومًا كاملًا، لذا يسجّل البرنامج الرسالة وينتقل إلى ما بعدها بدل الانتظار. وأي خطأ آخر، كعنوان ليس موقعًا عامًّا صالحًا، يخص ذلك الموقع وحده: فيسجّله البرنامج ويتابع.
الخطوة 2: استعلم بتأنٍّ وأبقِ بضعة تقارير قيد التشغيل
إرسال 50 موقعًا دفعةً واحدة ثم الاستعلام عن حالة الـ50 كلها كل ثانية هو النمط الذي ينبغي تجنّبه. فالدالة أدناه لا تُبقي أكثر من IN_FLIGHT تقارير قيد التشغيل، وتتوقف قليلًا بين عمليات الإرسال، وتنتظر بين جولات الاستعلام المدة التي تقترحها الواجهة.
def get_status(job_id):resp = session.get(f"{BASE}/{job_id}", timeout=60)resp.raise_for_status()return resp.json()def audit(sites):"""Submit every site, keep IN_FLIGHT running, return one outcome per site."""pending, running, done = list(sites), {}, []while pending or running:while pending and len(running) < IN_FLIGHT:site = pending.pop(0)try:job_id, error = submit(site)except OutOfCredits as exc:done += [{"site": s, "job_id": "", "error": str(exc)} for s in [site] + pending]pending = []breakif error:done.append({"site": site, "job_id": "", "error": error})else:running[job_id] = (site, time.monotonic())time.sleep(SUBMIT_PAUSE)wait = 0for job_id, (site, started) in list(running.items()):envelope = get_status(job_id)state = envelope["report"]["status"]error = Noneif state in ("queued", "running"):if time.monotonic() - started < MAX_WAIT:wait = max(wait, envelope["pollAfterMs"] / 1000)continueerror = f"still {state} after {MAX_WAIT} seconds"elif state != "completed":detail = envelope.get("error") or {}error = f"{state}: {detail.get('code', '')} {detail.get('message', '')}".strip()del running[job_id]done.append({"site": site, "job_id": job_id, "error": error})if running:time.sleep(max(wait, 3))return done
اعتبر كل حالة غير queued وrunning حالة نهائية، ولا تعتبر نجاحًا إلا completed. والثابت MAX_WAIT حدّ أمان وليس مدة متوقعة: فمعظم التقارير تكتمل قبله بكثير، وهو لا يفعل سوى منع تقرير لا يكتمل أبدًا من إبقاء الدفعة كلها مفتوحة. وحين يفشل تشغيل ما، تحمل استجابة الحالة كائن error فيه code وmessage وعلامة retryable. ورموز مثل DNS_FAILURE وCRAWLER_BLOCKED وTLS_ERROR تصف الموقع نفسه: لم يُحَلّ اسم النطاق، أو رفضت قاعدةٌ لمكافحة البرامج الآلية الطلب، أو فشل الاتصال الآمن. وإعادة المحاولة تعطي الإجابة نفسها، وهذه الإجابة بحد ذاتها جديرة بأن توضع أمام مالك الموقع. وتستخدم وصفتنا لمسار CI كائن error نفسه للتمييز بين نشرٍ معطوب وتدقيقٍ تعذّر تشغيله.
الخطوة 3: اقرأ النتائج واكتب ملف CSV
حين يكتمل التقرير، يعيد GET /api/v1/reports/{id}/result النتيجة الكاملة. وداخل report، تهمّ أربعة أجزاء في التصدير:
targetUrlهو العنوان الذي دُقِّق فعلًا. فإن كان مُدخلك يعيد التوجيه إلى مضيف آخر ضمن النطاق نفسه، كالانتقال من النطاق المجرد إلىwww، فإن التدقيق يتبعه، لذا احتفظ بمُدخلك وبهذه القيمة معًا.- يبيّن الحقل
auditedAtمتى جرى التدقيق، ويكتبه البرنامج في العمودaudited_at. score.overallهي الدرجة من 0 إلى 100 لذلك الموقع في ذلك اليوم.view.sectionsقائمة بأقسام التقرير. والقسم الذي قيمةkeyفيه هيfull_findingsيحتوي علىdetail.findings، وفيه كائن واحد لكل نتيجة.
تحمل كل نتيجة status (fail أو warn أو pass أو info)، وareaLabel الذي يسمّي جزء الموقع المعني، وtitle، وشرحًا في whyItMatters، وللنتائج الفاشلة والتحذيرية حقل fix. والنص بلغة التقرير. أما الأدلة الخاصة بالموقع، كعناوين URL المتأثرة، فموجودة في التقرير الكامل لا في هذه الحقول، ولهذا يحفظ القسم الأخير من هذه المقالة نسخة منه بجانب ملف CSV.
def read_findings(job_id):resp = session.get(f"{BASE}/{job_id}/result", timeout=60)resp.raise_for_status()report = resp.json()["report"]section = next((s for s in report["view"]["sections"] if s["key"] == "full_findings"), None)if section is None or section["detail"] is None:state = section["state"] if section else "missing"raise RuntimeError(f"findings section is {state}")return report, section["detail"]["findings"]def export(outcomes, path):with open(path, "w", newline="", encoding="utf-8") as fh:writer = csv.DictWriter(fh, fieldnames=CSV_FIELDS)writer.writeheader()for item in outcomes:if item["error"]:writer.writerow({"site": item["site"], "status": "not_audited","note": item["error"], "job_id": item["job_id"]})continuetry:report, findings = read_findings(item["job_id"])except (RuntimeError, requests.HTTPError) as exc:writer.writerow({"site": item["site"], "status": "unreadable","note": str(exc), "job_id": item["job_id"]})continuefor finding in findings:if finding["status"] not in ("fail", "warn"):continuewriter.writerow({"site": item["site"],"audited_url": report["targetUrl"],"audited_at": report["auditedAt"],"score": report["score"]["overall"],"status": finding["status"],"area": finding["areaLabel"],"finding": finding["title"],"why_it_matters": finding["whyItMatters"],"fix": finding["fix"],"job_id": item["job_id"],})if __name__ == "__main__":with open(sys.argv[1], encoding="utf-8") as fh:sites = [line.strip() for line in fh if line.strip()]export(audit(sites), sys.argv[2])
شغّله مع قائمة المُدخلات ومسار ملف المخرجات:
python audit_sites.py sites.txt findings.csv
المواقع التي تعثّرت تبقى في الملف. فالموقع الذي تعذّر تدقيقه يحصل على صف واحد بالقيمة not_audited مع السبب في note، والتقرير المكتمل الذي تعذّرت قراءة نتائجه يحصل على صف واحد بالقيمة unreadable. صفِّ الملف على هاتين القيمتين قبل مشاركته: فملف CSV أسقط موقعًا بصمت سيبدو وكأن ذلك الموقع خالٍ من المشكلات.
كم صفًّا تتوقع
توقّع صفوفًا لكل موقع تقريبًا. ففي 249 موقعًا خارجيًا دقّقها SEOReport بين 23 أغسطس و4 أكتوبر 2026، رصد التقرير الوسيط 14 مشكلة مميزة (نتائج فاشلة أو تحذيرية)؛ وكان لدى ربع المواقع 17 مشكلة أو أكثر، ولم يخلُ أي موقع من المشكلات.
ضرب هذا الوسيط في طول قائمتك يعطي تقديرًا أوليًا معقولًا لحجم الملف: فقائمة من 40 موقعًا قريبة من الوسيط تبلغ نحو 560 صفًّا. وهذا أكثر من أن يُقرأ سطرًا سطرًا، ولهذا وُجد العمودان area وfinding. رتّب حسب finding فتظهر معًا المشكلات المتكررة عبر مجموعة المواقع:
import csvfrom collections import Counterwith open("findings.csv", encoding="utf-8") as fh:rows = [r for r in csv.DictReader(fh) if r["status"] == "fail"]for title, count in Counter(r["finding"] for r in rows).most_common(10):print(f"{count:>3} {title}")
حين تفشل نتيجة واحدة في 12 من 40 موقعًا، ابحث أولًا عن سبب مشترك: فقالب أو إضافة أو نموذج استضافة مشترك قد يحوّل 12 مشكلة إلى 1 إصلاح يُطبَّق 12 مرة. والمقارنة صحيحة لأن كل موقع في الملف فُحص بالمنهج نفسه، والعمود audited_at يبيّن متى. أما تغطية القدر نفسه عبر جلسات محادثة مع الذكاء الاصطناعي فتتطلب محادثات منفصلة كثيرة، تبدأ كل منها من الصفر؛ ويستعرض هذا التحليل لموقع من 500 صفحة الحساب بالتفصيل.
احتفظ بالتقرير الكامل بجانب ملف CSV
ملف CSV أداة عمل. أما للأرشفة، أو لإرسال التشخيص الكامل إلى مالك الموقع، فنزّل كل تقرير بالصيغة التي تحتاجها: pdf أو md أو txt أو json.
def save_report(job_id, path, fmt="pdf"):resp = session.get(f"{BASE}/{job_id}/download", params={"format": fmt}, timeout=120)resp.raise_for_status()with open(path, "wb") as fh:fh.write(resp.content)
يتضمن ملف PDF صفحة غلاف، والملخص التنفيذي المُعدّ بالذكاء الاصطناعي، وتفصيل الفئات، والنتائج الكاملة. ويشرح دليلنا ماذا يتضمن تقرير SEO المزوّد بالدرجات كيف تقرأ كل جزء.
ولمواصلة متابعة المواقع نفسها بعد التصدير الأول، سجّلها في المراقبة الأسبوعية عبر PUT /api/v1/monitors، مرسلًا {"url": ..., "alertEmail": ...} لكل منها. والمراقبة مشمولة في الخطط المدفوعة، ولا تستهلك أرصدة التقارير، ولا ترسل بريدًا إلى عنوان التنبيه إلا حين تظهر نتيجة جديدة حرجة أو عالية الخطورة، أو تُحل نتيجة حرجة، أو تنتقل الدرجة إلى نطاق مختلف.
أسئلة شائعة
هل يستهلك تشغيل البرنامج مرة أخرى أرصدة من جديد؟
ليس للمواقع التي لديك تقارير عنها بالفعل. فحين يكون للموقع تقرير قائم، قد تعيد الواجهة ذلك التقرير بدلًا من تشغيل تدقيق جديد، لذا راجع العمود audited_at قبل أن تعامل ملف CSV ثانيًا على أنه قياس جديد. أما المراقبة الأسبوعية فتُجري دائمًا تدقيقًا جديدًا، ما يجعلها الأداة الأنسب لمتابعة التغيّر بمرور الوقت.
هل يمكنني تدقيق صفحات محددة بدلًا من مواقع كاملة؟
نعم. ضع في ملف المُدخلات عناوين URL كاملة بمساراتها، فيُدقَّق كل منها صفحةً واحدة. ولتدقيق الصفحات حدود خاصة بالساعة وباليوم. وحين تبلغ أحدها، تستجيب الواجهة بالرمز 429، فيسجّل البرنامج كل صفحة متبقية على أنها لم تُدقَّق مع رسالة الواجهة، لتتمكن من تشغيلها لاحقًا. وللحصول على رؤية شاملة للموقع، التزم بعناوين الصفحات الرئيسية.
لماذا يختلف العنوان المدقَّق عن العنوان الموجود في قائمتي؟
قبل التدقيق، تتبع الواجهة إعادة التوجيه التي تبقى ضمن النطاق نفسه، لذا قد يُدقَّق example.com بوصفه www.example.com. أما إعادة التوجيه إلى نطاق مختلف فلا تُتبع بصمت: إذ يحتفظ التدقيق بعنوانك ويُبلغ عن إعادة التوجيه بوصفها نتيجة. احتفظ بالعمود site للربط مع سجلاتك، وبالعمود audited_url لقراءة النتائج.
هل يستطيع وكيل ذكاء اصطناعي القيام بذلك بدلًا من برنامج نصي؟
نعم. فالمفتاح نفسه يربط أي وكيل يدعم MCP بخادم MCP، الذي يوفّر create_report وget_report_status وget_report؛ ويشرح دليل إعداد الوكلاء طريقة الضبط. والبرنامج النصي أنسب لقائمة ثابتة تُشغَّل وفق جدول، لأنه يعمل بالطريقة نفسها في كل مرة ويترك ملفًا يمكنك مقارنته. أما الوكيل فيناسب من يريد طرح أسئلة متابعة حول نتائج موقع واحد.
هل يُظهر ملف CSV كيف فهرس Google كل موقع؟
لا. يدقّق SEOReport ما قدّمه كل موقع وقت التدقيق، من الخارج، ولا يقرأ بيانات Search Console. استخدم Search Console لترى ما قرّره Google بشأن عنوان URL، والنتائج لترى ما في الموقع مما قد يكون سببًا لذلك.
احصل على التشخيص الكامل لموقعك
تقرير مدعوم بالأدلة وخطة عمل مرتبة حسب الأولوية، ضمن خطة بأرصدة شهرية.