Bedrijfswebsites vinden op naam met Python en API

Om vanuit een bedrijfsnaam een bedrijfswebsite te vinden in Python, stuur je de naam en eventuele landinformatie naar Datablists Company Name to Domain API. De API verwerkt de zoekopdracht op de achtergrond en retourneert vervolgens het domein en de volledige website-URL.

Eerst laat ik je een eenvoudige Python API-request zien. Daarna hergebruik ik dezelfde functie om alleen de ontbrekende websites in een lijst met bedrijfsrecords aan te vullen, zonder bestaande URL's te overschrijven.

Werk je liever met een spreadsheetachtige interface? Volg dan de handleiding om in bulk bedrijfswebsites op naam te vinden.

💡 Samenvatting voor wie weinig tijd heeft

Bouw één Python-functie die websites bij bedrijfsnamen vindt en gebruik deze om records met een leeg websiteveld aan te vullen zonder bekende URL's te vervangen.

• Input: bedrijfsnamen met optionele landinformatie.
• Output: domein, volledige website-URL, betrouwbaarheid, resultaatstatus en verbruikte credits.

Python en je Datablist API-key instellen

Voor dit voorbeeld gebruik ik het Requests-package om synchrone HTTP-calls uit te voeren. Installeer het in een virtual environment:

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

Je hebt ook een Datablist Growth-abonnement nodig, omdat toegang tot de REST API een Growth-feature is. Maak een Personal API Key aan via de API-accountpagina van Datablist en sla deze vervolgens op in een environment variable:

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

🔑 Heb je al een API-key? Oudere keys gebruiken auth0|<userId>:<accountId>:<secret>:1. Deze blijven ondersteund. Blijf je bestaande key precies gebruiken zoals deze is gegenereerd; je hoeft hem niet te vervangen of opnieuw te formatteren.

Vervang de voorbeeldwaarde hierboven door de key die op je accountpagina is gegenereerd. Zoekopdrachten naar bedrijfswebsites verbruiken credits. Voordat we het script opschalen, leg ik uit wanneer een zoekopdracht 1 of 2,5 credits kost. De actuele abonnementsgegevens vind je op de prijzenpagina van Datablist.

Eén bedrijfswebsite opzoeken met Python

Maak een bestand met de naam find_company_websites.py. Het script verstuurt de namen, wacht tot de taak klaar is en haalt de resultaten op binnen één functie. Voor elke input wordt je vaste record-ID als inputId gebruikt. Zo kun je ieder resultaat aan het juiste record koppelen, zelfs als de volgorde van de response verandert.

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))

Voer het script uit in de terminal waarin je de key hebt geëxporteerd:

1python find_company_websites.py

Dit is het resultaat voor Microsoft:

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

Gebruik inputId om dit resultaat aan het oorspronkelijke record te koppelen. status heeft de waarde success, no_result, error of skipped. Een geslaagd resultaat kan companyDomain, de volledige companyUrl en domainConfidence bevatten. creditsUsed toont hoeveel credits voor deze input zijn afgeschreven, terwijl error een fout op itemniveau toelicht.

De functie voert achtereenvolgens drie soorten API-calls uit.

Eerst wordt de zoekopdracht verstuurd. De payload bevat de instellingen en bedrijfsrecords. De POST-call retourneert 202 Accepted; @id is de taak-ID die voor de volgende calls nodig is:

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"]

Als DATABLIST_API_KEY niet is ingesteld, geeft Python tijdens het opvragen van de environment variable een KeyError voordat een HTTP-request wordt uitgevoerd. Exporteer de variabele en voer het script opnieuw uit. Bevat de variabele een ongeldige key, dan bereikt de POST-call de API en wordt HTTP 401 geretourneerd. Kopieer een actuele Personal API Key van je accountpagina en vervang de ongeldige waarde.

Vervolgens wordt de taak gepolld. De POST-call start de verwerking op de achtergrond. Daarom leest het script de taak elke drie seconden uit, totdat deze de status completed, failed of stopped bereikt:

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)

Als de taak mislukt doordat er onvoldoende credits beschikbaar zijn, bevat de foutmelding de reden credits_error. Voeg credits toe of wacht tot je maandelijkse credits worden vernieuwd. Controleer eventuele resultaten die al zijn geretourneerd en verstuur daarna alleen de onafgeronde inputs in een nieuwe taak.

Tot slot worden alle resultaatpagina's opgehaald. Iedere response voegt resultaten aan de lijst toe en levert de cursor voor het volgende request:

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

De functie blijft pagina's ophalen totdat nextCursor gelijk is aan null.

Het script toont de gegenereerde uniqueId vóór de POST-call. Valt de verbinding weg voordat je de response voor het aanmaken van de taak ontvangt, vraag dan eerst je takenlijst op om de status te controleren voordat je een nieuwe taak aanmaakt:

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"

Zoek de taak waarvan de uniqueId overeenkomt met de door het script gegenereerde waarde en kopieer vervolgens de @id. Het endpoint voor de takenlijst kan filteren op enrichmentId, maar niet op uniqueId. Gebruik de @id met dezelfde status- en resultaat-URL's als in het script. Blijf pollen als de taak nog actief is. Is de taak gestopt of mislukt, controleer dan eerst of er deelresultaten zijn voordat je de inputs opnieuw verstuurt.

Datasetmatching en de landafhankelijke fallback

Het script gebruikt dataset_google, de aanbevolen standaardinstelling. Datablist controleert eerst zijn bedrijfsdatasets. Ontbreekt een match of zijn de resultaten tegenstrijdig, dan kan Google als fallback worden gebruikt. Mogelijke matches worden gecontroleerd voordat er een betrouwbaarheidsniveau wordt geretourneerd.

Landinformatie helpt bij dubbelzinnige namen. In dit voorbeeld leverde dezelfde bedrijfsnaam verschillende resultaten op:

• Mercury met US retourneerde shipmercury.com en https://www.shipmercury.com/.
• Mercury met IE retourneerde mercuryeng.com en http://www.mercuryeng.com.

Beide resultaten hadden een High confidence. Landinformatie helpt de zoekfunctie onderscheid te maken tussen bedrijven met dezelfde naam. De confidence helpt je bepalen welke resultaten handmatig moeten worden gecontroleerd.

Als de juiste match ook afhangt van de branche, bedrijfsgrootte of andere zakelijke context, gebruik dan de AI Agent research-workflow. Voeg deze informatie aan de AI Agent-prompt toe, zodat de Agent met uitgebreidere bedrijfscontext naar het bedoelde bedrijf kan zoeken.

Alleen ontbrekende websites in records aanvullen

Nu find_domains() een website op basis van een bedrijfsnaam kan vinden, kun je de functie hergebruiken om alleen ontbrekende websites in je bedrijfsrecords aan te vullen. Records die al een website bevatten, slaan de API over. Hun waarden blijven daardoor ongewijzigd en ze verbruiken geen credits.

Vervang in find_company_websites.py alles vanaf companies = [ tot en met de laatste print-loop door het onderstaande blok. Laat de toewijzing aan api_key erboven staan. De controle op lege waarden verwerkt None, een lege string en alleen spaties. Als alle websites al zijn ingevuld, wordt er geen API-call uitgevoerd.

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))

De code indexeert de resultaten op inputId en loopt daarna in de oorspronkelijke volgorde door de records. Het object website_lookup bewaart naast ieder verwerkt record de uitkomst en de gegevens voor controle, inclusief mislukte of ontbrekende resultaten.

Voor crm-001 retourneert website_is_missing() de waarde False, omdat de URL van Microsoft al aanwezig is. Het record wordt niet aan records_to_lookup toegevoegd en bereikt de API dus nooit. Tijdens het samenvoegen blijft de website behouden en wordt de status vastgelegd als not_requested.

Bij crm-002 is het websiteveld leeg. Het request verstuurt de bakkerij daarom met inputId: crm-002. De API retourneert dezelfde inputId. results_by_id gebruikt deze om het juiste resultaat te vinden, waarna de merge https://boulangerie-du-palais-lyon.eatbu.com in dat record opslaat zonder afhankelijk te zijn van de volgorde van de resultaten.

De bakkerij gebruikt een bedrijfsspecifiek subdomein: boulangerie-du-palais-lyon.eatbu.com. Bewaar deze waarde in plaats van hem terug te brengen tot eatbu.com en sla het exacte adres uit companyUrl op. Dankzij de instelling acceptNonRoot: true is ook een gehoste bedrijfspagina toegestaan waarvan het adres na de hostnaam nog een pad bevat. In beide gevallen is de volledige URL dus belangrijk.

Ook een voltooide taak kan items met de status no_result, error of skipped bevatten. In het voorbeeld wordt website alleen gewijzigd als de status success is en companyUrl aanwezig is. Bij no_result blijft het websiteveld leeg en blijft de status zichtbaar in website_lookup. Controleer eerst de bedrijfsnaam en het land. Is een van beide onjuist, corrigeer de waarde dan en verstuur dat record in een nieuwe taak. Laat het websiteveld anders leeg, zodat duidelijk blijft dat het handmatig moet worden gecontroleerd.

Credits voor zoekopdrachten vooraf berekenen

Alle vijf de zoekopdrachten uit het voorbeeld retourneerden success met High confidence en verbruikten samen 5 credits.

Een zoekopdracht die via de dataset wordt opgelost, kost 1 credit. Een zoekopdracht die met Google wordt verwerkt, kost 2,5 credits. Je betaalt alleen voor het gebruikte pad, niet voor beide. Voor 1.000 inputs betekent dit 1.000 credits als alles via de dataset wordt gevonden, of 2.500 credits als alles Google gebruikt. Dit zijn planningsscenario's en geen garantie dat iedere zoekopdracht slaagt.

Verschuif de slider om het creditverbruik voor jouw lijst te vergelijken.

Bij $20 voor 20.000 credits kosten deze scenario's respectievelijk $1 en $2,50. Het Growth-abonnement staat hier los van en bevat momenteel 20.000 maandelijkse credits, die vóór extra gekochte credits worden gebruikt. Controleer de actuele prijzen, omdat abonnements- en pakketwaarden kunnen veranderen.

Eén taak accepteert maximaal 10.000 inputs, met een limiet van 16 KiB per input en 10 MiB per request. Dit voorbeeld gebruikt blokkerende Requests-calls om één kleine asynchrone Datablist-taak te versturen, te pollen en de resultaten ervan op te halen. De onderhouden repository bevat ook voorbeelden voor CSV-batching en non-blocking clients.

Volgende stappen

Zodra je hebt gecontroleerd dat een geretourneerde website bij het bedoelde bedrijf hoort, kun je het Impressum scrapen met Python. Zo voeg je juridische bedrijfsgegevens en de URL van de juridische bronpagina aan hetzelfde leveranciersrecord toe. Houd de controle van de websitematch gescheiden van deze latere extractie.

Vervang de voorbeeldrecords door een kleine selectie uit je eigen data. Voer daarna het script uit en controleer de samengevoegde records. Gebruik vaste ID's en landinformatie en schaal pas op nadat je hebt bevestigd dat het script bekende websites behoudt en de juiste lege velden invult. Je kunt beginnen met de onderhouden Company Name to Domain API-voorbeelden op GitHub als je het downloadbare script, CSV-batching of een asynchrone versie wilt gebruiken.