العثور على مواقع الشركات من أسمائها عبر Python وAPI

للعثور على موقع شركة انطلاقًا من اسمها في Python، أرسل الاسم وأي معلومات متاحة عن البلد إلى Company Name to Domain API من Datablist. تعالج API عملية البحث في الخلفية، ثم تُرجع النطاق وعنوان URL الكامل للموقع.

سأعرض لك أولًا طلب API بسيطًا باستخدام Python. بعد ذلك، سأعيد استخدام الدالة نفسها لملء المواقع المفقودة فقط في قائمة سجلات الشركات، مع الاحتفاظ بعناوين URL الموجودة مسبقًا.

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

💡 ملخص لمن يريد الوصول إلى النتيجة سريعًا

أنشئ دالة واحدة في Python تعثر على المواقع من أسماء الشركات، ثم استخدمها لاستكمال السجلات ذات المواقع الفارغة دون استبدال عناوين URL المعروفة.

• المدخلات: أسماء الشركات مع معلومات اختيارية عن البلد.
• المخرجات: النطاق، وعنوان URL الكامل للموقع، ودرجة الثقة، وحالة النتيجة، وعدد Credits المستخدمة.

إعداد Python ومفتاح Datablist API

في هذا المثال، أستخدم حزمة Requests لإجراء طلبات HTTP متزامنة. ثبّتها داخل بيئة افتراضية:

1python3 -m venv .venv
2source .venv/bin/activate
3python -m pip install requests

ستحتاج أيضًا إلى خطة Datablist Growth، لأن الوصول إلى REST API إحدى ميزات Growth. أنشئ Personal API Key من صفحة Datablist API في حسابك، ثم ضعه في متغير بيئة:

1export DATABLIST_API_KEY="exampleuser-exampleaccount-EXAMPLE_TOKEN_NOT_VALID-2"

🔑 هل لديك API key بالفعل؟ تستخدم المفاتيح القديمة الصيغة auth0|<userId>:<accountId>:<secret>:1، وما زالت مدعومة. واصل استخدام مفتاحك الحالي كما تم إنشاؤه تمامًا؛ فلا حاجة إلى استبداله أو تغيير تنسيقه.

استبدل القيمة التجريبية أعلاه بالمفتاح الذي تم إنشاؤه في صفحة حسابك. تستهلك عمليات البحث عن مواقع الشركات Credits. سأشرح مساري التكلفة، Credit واحدة و2.5 Credits، قبل توسيع نطاق تشغيل السكربت. ويمكنك الاطلاع على القيم الحالية للخطط في صفحة أسعار Datablist.

البحث عن موقع شركة واحدة باستخدام Python

أنشئ ملفًا باسم find_company_websites.py. يرسل السكربت الأسماء، وينتظر اكتمال المهمة، ثم يجلب النتائج ضمن دالة واحدة. يستخدم كل إدخال المعرّف الثابت لسجلك بوصفه inputId، حتى تتمكن من ربط كل نتيجة بالسجل الصحيح، ولو تغيّر ترتيب الاستجابة.

1import json
2import os
3import time
4import uuid
5
6import requests
7
8
9API_BASE_URL = "https://api.datablist.com/v1"
10
11
12def find_domains(companies, api_key):
13    headers = {
14        "Accept": "application/json",
15        "Content-Type": "application/json",
16        "X-API-Key": api_key,
17    }
18    inputs = [
19        {
20            "inputId": company["id"],
21            "data": {
22                "companyName": company["company_name"],
23                "targetCountry": company.get("country", ""),
24            },
25        }
26        for company in companies
27    ]
28    unique_id = f"python-domain-lookup-{uuid.uuid4().hex}"
29    payload = {
30        "enrichmentId": "company-name-to-domain",
31        "uniqueId": unique_id,
32        "settings": {
33            "workflow": "dataset_google",
34            "countryOverwrite": True,
35            "acceptNonRoot": True,
36        },
37        "inputs": inputs,
38    }
39
40    print(f"Task uniqueId: {unique_id}")
41    response = requests.post(
42        f"{API_BASE_URL}/enrichments/tasks",
43        headers=headers,
44        json=payload,
45    )
46    response.raise_for_status()
47    task_id = response.json()["@id"]
48
49    while True:
50        response = requests.get(
51            f"{API_BASE_URL}/enrichments/tasks/{task_id}",
52            headers=headers,
53        )
54        response.raise_for_status()
55        task = response.json()
56        if task["status"] in {"completed", "failed", "stopped"}:
57            break
58        time.sleep(3)
59
60    if task["status"] != "completed":
61        raise RuntimeError(
62            f"Task {task_id} ended with status {task['status']}: {task.get('error')}"
63        )
64
65    results = []
66    cursor = None
67    while True:
68        params = {"limit": 100}
69        if cursor is not None:
70            params["cursor"] = cursor
71
72        response = requests.get(
73            f"{API_BASE_URL}/enrichments/tasks/{task_id}/results",
74            headers=headers,
75            params=params,
76        )
77        response.raise_for_status()
78        page = response.json()
79        results.extend(page["results"])
80        cursor = page.get("nextCursor")
81        if cursor is None:
82            break
83
84    return results
85
86
87api_key = os.environ["DATABLIST_API_KEY"]
88companies = [
89    {
90        "id": "direct-microsoft-us",
91        "company_name": "Microsoft",
92        "country": "US",
93    }
94]
95
96lookup_results = find_domains(companies, api_key)
97for result in lookup_results:
98    print(json.dumps(result, indent=2))

شغّله من نافذة Terminal نفسها التي صدّرت فيها المفتاح:

1python find_company_websites.py

هذه نتيجة Microsoft:

{
  "inputId": "direct-microsoft-us",
  "status": "success",
  "outputs": {
    "companyUrl": "https://microsoft.com",
    "companyDomain": "microsoft.com",
    "domainConfidence": "High"
  },
  "creditsUsed": "1",
  "error": null
}

استخدم inputId لربط هذه النتيجة بالسجل الأصلي. تكون قيمة status واحدة من success أو no_result أو error أو skipped. وقد تتضمن النتيجة الناجحة companyDomain وعنوان companyUrl الكامل وdomainConfidence. يوضح creditsUsed التكلفة الخاصة بهذا الإدخال، بينما يشرح error سبب تعذّر معالجة عنصر بعينه.

تُجري الدالة ثلاثة أنواع من استدعاءات API بالترتيب.

أولًا، ترسل طلب البحث. تتضمن الحمولة الإعدادات وسجلات الشركات. يعيد طلب POST الاستجابة 202 Accepted، ويكون @id هو معرّف المهمة الذي تحتاج إليه الاستدعاءات التالية:

1response = requests.post(
2    f"{API_BASE_URL}/enrichments/tasks",
3    headers=headers,
4    json=payload,
5)
6response.raise_for_status()
7task_id = response.json()["@id"]

إذا لم يكن DATABLIST_API_KEY مضبوطًا، فسيُطلق Python الخطأ KeyError عند محاولة قراءة متغير البيئة، قبل إجراء أي طلب HTTP. صدّر المتغير ثم شغّل السكربت مجددًا. وإذا كان المتغير يحتوي على مفتاح غير صالح، فسيصل طلب POST إلى API ويعيد خطأ HTTP 401. انسخ Personal API Key حاليًا من صفحة حسابك واستبدل به القيمة غير الصالحة.

ثانيًا، تستعلم عن حالة المهمة دوريًا. يبدأ طلب POST المعالجة في الخلفية، لذلك يقرأ السكربت حالة المهمة كل ثلاث ثوانٍ إلى أن تصبح completed أو failed أو stopped:

1while True:
2    response = requests.get(
3        f"{API_BASE_URL}/enrichments/tasks/{task_id}",
4        headers=headers,
5    )
6    response.raise_for_status()
7    task = response.json()
8    if task["status"] in {"completed", "failed", "stopped"}:
9        break
10    time.sleep(3)

إذا فشلت المهمة لعدم توفر Credits، فسيكون سبب الخطأ credits_error. أضف Credits أو انتظر تجدد رصيدك الشهري، وراجع أي نتائج أُعيدت بالفعل، ثم أرسل المدخلات غير المكتملة فقط ضمن مهمة جديدة.

ثالثًا، تجلب جميع صفحات النتائج. تضيف كل استجابة النتائج إلى القائمة، وتوفر المؤشر اللازم للطلب التالي:

1results.extend(page["results"])
2cursor = page.get("nextCursor")
3if cursor is None:
4    break

تواصل الدالة جلب الصفحات حتى تصبح قيمة nextCursor مساوية لـ null.

يطبع السكربت قيمة uniqueId التي تم إنشاؤها قبل طلب POST. إذا انقطع الاتصال قبل تلقي استجابة إنشاء المهمة، فاعرض قائمة مهامك أولًا للتحقق من حالتها قبل إنشاء مهمة أخرى:

1curl --get "https://api.datablist.com/v1/enrichments/tasks" \
2  --header "X-API-Key: $DATABLIST_API_KEY" \
3  --data-urlencode "enrichmentId=company-name-to-domain"

ابحث عن المهمة التي تتطابق قيمة uniqueId فيها مع القيمة التي أنشأها السكربت، ثم انسخ @id الخاص بها. تتيح لك نقطة نهاية القائمة التصفية حسب enrichmentId، ولكن ليس حسب uniqueId. استخدم @id مع عناوين URL نفسها التي يستخدمها السكربت للحالة والنتائج. إذا كانت المهمة لا تزال نشطة، فواصل الاستعلام عن حالتها. وإذا توقفت أو فشلت، فتحقق من النتائج الجزئية قبل إعادة إرسال المدخلات.

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

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

تساعد معلومات البلد على تمييز الأسماء المتشابهة. في هذا المثال، أعطى اسم الشركة نفسه نتائج مختلفة:

• أعادت Mercury مع US النطاق shipmercury.com والعنوان https://www.shipmercury.com/.
• أعادت Mercury مع IE النطاق mercuryeng.com والعنوان http://www.mercuryeng.com.

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

عندما تعتمد المطابقة أيضًا على القطاع أو حجم الشركة أو معلومات تجارية أخرى، استخدم مسار بحث AI Agent. أضف هذه التفاصيل إلى Prompt الخاص بـ AI Agent ليتمكن من البحث عن الشركة المقصودة استنادًا إلى سياق تجاري أغنى.

ملء المواقع المفقودة فقط في سجلات تطبيقك

بعد أن أصبحت find_domains() قادرة على العثور على موقع من اسم الشركة، أعد استخدامها لملء المواقع المفقودة فقط في سجلات شركاتك. تتجاوز السجلات التي تحتوي على موقع بالفعل استدعاء API، وبذلك تبقى قيمها دون تغيير ولا تستهلك أي Credits للبحث.

في find_company_websites.py، استبدل كل شيء بدءًا من companies = [ وحتى حلقة الطباعة الأخيرة بالكتلة أدناه. احتفظ بتعيين api_key الموجود فوقها. يتعامل فحص الحقل الفارغ مع None والسلسلة الفارغة والمسافات. ولا يُجرى أي استدعاء API عندما تكون جميع المواقع مملوءة.

1records = [
2    {
3        "id": "crm-001",
4        "company_name": "Microsoft",
5        "country": "US",
6        "website": "https://www.microsoft.com",
7    },
8    {
9        "id": "crm-002",
10        "company_name": "boulangerie du palais lyon",
11        "country": "FR",
12        "website": "",
13    },
14    {
15        "id": "crm-003",
16        "company_name": "Mercury Engineering",
17        "country": "IE",
18        "website": None,
19    },
20    {
21        "id": "crm-004",
22        "company_name": "Mercury",
23        "country": "US",
24        "website": "   ",
25    },
26    {
27        "id": "crm-005",
28        "company_name": "Datablist",
29        "country": "FR",
30        "website": "https://www.datablist.com",
31    },
32    {
33        "id": "crm-006",
34        "company_name": "Mercury",
35        "country": "IE",
36        "website": None,
37    },
38]
39
40
41def website_is_missing(value):
42    return not isinstance(value, str) or not value.strip()
43
44
45records_to_lookup = [
46    record for record in records if website_is_missing(record.get("website"))
47]
48lookup_results = (
49    find_domains(records_to_lookup, api_key) if records_to_lookup else []
50)
51results_by_id = {result["inputId"]: result for result in lookup_results}
52
53for record in records:
54    if not website_is_missing(record.get("website")):
55        record["website_lookup"] = {"status": "not_requested"}
56        continue
57
58    result = results_by_id.get(record["id"])
59    if result is None:
60        record["website_lookup"] = {
61            "status": "missing_result",
62            "domain": None,
63            "confidence": None,
64            "credits": None,
65            "error": {
66                "code": "missing_result",
67                "message": "No result was returned for this inputId.",
68            },
69        }
70        continue
71
72    outputs = result.get("outputs") or {}
73    if result["status"] == "success" and outputs.get("companyUrl"):
74        record["website"] = outputs["companyUrl"]
75
76    record["website_lookup"] = {
77        "status": result["status"],
78        "domain": outputs.get("companyDomain"),
79        "confidence": outputs.get("domainConfidence"),
80        "credits": result.get("creditsUsed"),
81        "error": result.get("error"),
82    }
83
84print(json.dumps(records, indent=2))

يفهرس الكود النتائج حسب inputId، ثم يمر على السجلات الأصلية بالترتيب. يحتفظ الكائن website_lookup بالنتيجة وتفاصيل المراجعة بجوار كل سجل تمت محاولة معالجته، بما في ذلك النتائج غير الناجحة أو المفقودة.

بالنسبة إلى crm-001، تعيد website_is_missing() القيمة False لأن عنوان Microsoft موجود بالفعل. لا يُضاف السجل إلى records_to_lookup، ولذلك لا تستلمه API مطلقًا. تحافظ عملية الدمج على موقعه وتسجل الحالة not_requested.

بالنسبة إلى crm-002، يكون حقل الموقع فارغًا، لذلك يرسل الطلب المخبز مع inputId: crm-002. تعيد API قيمة inputId نفسها، ويستخدمها results_by_id للعثور على النتيجة الصحيحة. بعد ذلك، تكتب عملية الدمج https://boulangerie-du-palais-lyon.eatbu.com في ذلك السجل دون الاعتماد على ترتيب النتائج.

يستخدم المخبز نطاقًا فرعيًا خاصًا بالنشاط التجاري، وهو boulangerie-du-palais-lyon.eatbu.com. احتفظ بهذه القيمة بدل اختصارها إلى eatbu.com، واحفظ العنوان الدقيق الموجود في companyUrl. يسمح الإعداد acceptNonRoot: true أيضًا بصفحة نشاط تجاري مستضافة يتضمن عنوانها مسارًا بعد اسم المضيف، لذلك يبقى عنوان URL الكامل مهمًا في الحالتين.

قد تتضمن المهمة المكتملة عناصر بحالة no_result أو error أو skipped. لا يغيّر المثال قيمة website إلا عندما تكون الحالة success ويكون companyUrl موجودًا. عند ظهور no_result، يظل الموقع فارغًا وتبقى الحالة ظاهرة في website_lookup. تحقق أولًا من اسم الشركة والبلد. إذا كان أحد الإدخالين خاطئًا، فصححه وأرسل ذلك السجل ضمن مهمة جديدة. وإلا، فاترك الموقع الفارغ ظاهرًا للمراجعة اليدوية.

تقدير Credits قبل توسيع نطاق السكربت

أعادت عمليات البحث الخمس في المثال الحالة success بدرجة ثقة High، واستهلكت 5 Credits إجمالًا.

تكلّف عملية البحث التي تُحسم عبر قاعدة البيانات Credit واحدة. أما العملية التي تُعالج باستخدام Google فتكلف 2.5 Credits. أنت تدفع مقابل المسار المستخدم، وليس كليهما. بالنسبة إلى 1,000 إدخال، يعني ذلك 1,000 Credit إذا حُسمت جميعها عبر قاعدة البيانات، أو 2,500 Credit إذا استخدمت جميعها Google. هذه سيناريوهات للتخطيط، وليست ضمانًا لنجاح كل عملية بحث.

حرّك شريط التمرير لمقارنة استهلاك Credits لقائمتك.

عند دفع 20 دولارًا مقابل 20,000 Credit، تبلغ تكلفة هذين السيناريوهين دولارًا واحدًا و2.50 دولار. اشتراك Growth منفصل، ويتضمن حاليًا 20,000 Credit شهريًا تُستخدم قبل الأرصدة الإضافية. راجع الأسعار الحالية، لأن قيم الخطط والباقات قد تتغير.

تقبل المهمة الواحدة ما يصل إلى 10,000 إدخال، بحد أقصى 16 KiB لكل إدخال و10 MiB لكل طلب. يستخدم هذا المثال استدعاءات Requests حاجبة لإرسال مهمة Datablist صغيرة وغير متزامنة، والاستعلام عن حالتها، وجلب نتائجها. ويتضمن المستودع الذي تتم صيانته أيضًا أمثلة على معالجة ملفات CSV على دفعات وClients غير حاجبة.

الخطوات التالية

بعد التأكد من أن الموقع المُعاد يخص النشاط التجاري المقصود، يمكنك استخراج صفحة Impressum باستخدام Python لإضافة البيانات القانونية للشركة وعنوان URL لصفحة المصدر القانونية إلى سجل المورّد نفسه. أبقِ مراجعة مطابقة الموقع منفصلة عن عملية الاستخراج اللاحقة.

استبدل السجلات التجريبية بعينة صغيرة من بياناتك، ثم شغّل السكربت وافحص السجلات بعد دمج النتائج. احتفظ بمعرّفات ثابتة ومعلومات البلد، ولا توسّع نطاق التشغيل إلا بعد التأكد من أن السكربت يحافظ على المواقع المعروفة ويملأ الحقول الفارغة المتوقعة. ويمكنك البدء من أمثلة Company Name to Domain API التي تتم صيانتها على GitHub إذا أردت سكربتًا قابلًا للتنزيل، أو معالجة ملفات CSV على دفعات، أو إصدارًا غير متزامن.