Berik kundedata
Legg firmadata til kundelisten din.
Du har en liste med firmanavn, steder eller registernumre og vil legge offisielle firmadata til den. Alt du trenger, er fetch-organization; du trenger ikke søke først.
Match firmaer
Send én forespørsel per kunde med den beste opplysningen du har. Registerdomstol og registernummer er best, fordi de er entydige. Har du ikke dem, bruker du firmanavnet med selskapsform og sted. Eksempelforespørselen vår slår opp Hetzner Online GmbH, Ansbach HRB 6089, via navn og sted.
curl -G "https://handelsregister.ai/api/v1/fetch-organization" \ -H "x-api-key: YOUR_API_KEY" \ --data-urlencode 'q=Hetzner Online GmbH Gunzenhausen'
import requests response = requests.get( "https://handelsregister.ai/api/v1/fetch-organization", headers={"x-api-key": "YOUR_API_KEY"}, params={ "q": "Hetzner Online GmbH Gunzenhausen", }, ) data = response.json()
const url = new URL("https://handelsregister.ai/api/v1/fetch-organization"); url.searchParams.append("q", "Hetzner Online GmbH Gunzenhausen"); const response = await fetch(url, { headers: { "x-api-key": "YOUR_API_KEY" }, }); const data = await response.json();
1{2 "entity_id": "94eb910fef13f94585c48c263fa446d4",3 "name": "Hetzner Online GmbH",4 "status": "ACTIVE",5 "registration": {6 "court": "Ansbach",7 "register_type": "HRB",8 "register_number": "6089"9 },10 "address": {11 "house_number": "25",12 "street": "Industriestraße",13 "postal_code": "91710",14 "city": "Gunzenhausen",15 "county": "Weißenburg-Gunzenhausen",16 "state": "Bayern",17 "country": "DEU",18 "coordinates": {19 "latitude": 49.12483,20 "longitude": 10.7805221 }22 },23 "meta": {24 "request_credit_cost": 5,25 "credits_remaining": 14526 }27}
Sjekk svaret mot dataene dine, for eksempel postnummeret eller stedet i address. Ved vanlige navn kunne det ellers komme tilbake et firma med samme navn.
Lagre entity_id hos kunden din. Alle senere hentinger, dokumenter, Signals og monitorer kjører da på denne identifikatoren.
ai_search=on-default) målrettet for uskarpe oppføringer; den koster 20 kreditter ekstra, også uten treff.
Hent mange firmaer
fetch-organization tillater 60 forespørsler per minutt. Send forespørslene jevnt, den ene etter den andre. Ved HTTP 429 venter du sekundene fra Retry-After. Trenger du mer, tilbyr Enterprise høyere grenser, se Priser.
Gi hver forespørsel en Idempotency-Key, for eksempel kundenummeret. Gjentar du den med samme nøkkel og samme parametere innen 24 timer, koster den ingenting.
Ved HTTP 408 (forespørselen tok for lang tid) belaster API-et ingenting, heller ikke AI-modus. Ved en feil med status 500 eller høyere belastes bare AI-modus, hvis du valgte den. Prøv igjen senere med samme Idempotency-Key.
Skriptet leser kunder.csv med kolonnene id, name, city og register. Kolonnen register inneholder registernummeret med domstol, for eksempel Ansbach HRB 6089, eller ingenting. Skriptet skriver en kopi med entity_id, registerdomstol og registernummer og teller kredittene som er brukt.
import csv import time import requests API = "https://handelsregister.ai/api/v1/fetch-organization" HEADERS = {"x-api-key": "YOUR_API_KEY", "Accept": "application/json"} PER_MINUTE = 60 # grensen for fetch-organization def lookup(row): # Registerdomstol pluss registernummer er entydig; ellers navn og sted q = row["register"] or f'{row["name"]} {row["city"]}' headers = {**HEADERS, "Idempotency-Key": f'kunde-{row["id"]}'} for attempt in range(5): response = requests.get(API, params={"q": q}, headers=headers, timeout=120) if response.status_code == 429: time.sleep(int(response.headers.get("Retry-After", "10"))) elif response.status_code in (408, 500, 502, 503, 504): time.sleep(30 * (attempt + 1)) else: break return response spent = 0 with open("kunder.csv", newline="") as source, open("kunder_beriket.csv", "w", newline="") as target: reader = csv.DictReader(source) writer = csv.DictWriter(target, fieldnames=reader.fieldnames + ["entity_id", "registerdomstol", "registernummer"]) writer.writeheader() for row in reader: response = lookup(row) if response.status_code == 402: print("Ikke nok kreditter, kjøringen stoppet") break data = response.json() spent += data.get("meta", {}).get("request_credit_cost", 0) if response.status_code == 200: registration = data.get("registration") or {} row["entity_id"] = data["entity_id"] row["registerdomstol"] = registration.get("court") row["registernummer"] = f'{registration.get("register_type")} {registration.get("register_number")}' writer.writerow(row) time.sleep(60 / PER_MINUTE) print(f"Brukt: {spent} kreditter")
En ny kjøring innen 24 timer koster ingenting. Svaret har da Idempotency-Status: replayed og request_credit_cost 0.
1{2 "entity_id": "94eb910fef13f94585c48c263fa446d4",3 "name": "Hetzner Online GmbH",4 "meta": {5 "request_credit_cost": 0,6 "credits_remaining": 1457 }8}
enrich, en ferdig berikelse for CSV-, JSON- og Excel-filer.
Hold øye med kostnadene
Anslå på forhånd med prislisten: 5 kreditter per firma for grunndataene, pluss prisen for hver funksjon. Grunndataene koster ved hvert treff. Funksjoner uten data koster ingenting, så de faktiske kostnadene er ofte lavere. Tilleggene er ikke funksjoner: AI-modus koster også uten treff, Sanntid ved hver vellykket henting.
| Hva | Kreditter |
|---|---|
| Firmaprofil med grunndataene | 5 |
| Hver funksjon, bare når den returnerer data | 1 til 80 |
| AI-modus, også uten treff | +20 |
| Sanntid, for hver vellykket live-henting | +10 |
Grense: 60 forespørsler per minutt.
Hva en forespørsel faktisk kostet, står i hvert svar under meta.request_credit_cost.
Hva en forespørsel kostet, står i meta.request_credit_cost, den gjenværende saldoen i meta.credits_remaining. Summer kostnadene underveis, som i skriptet ovenfor.
Før hver forespørsel sjekker API-et om saldoen din dekker den høyest mulige prisen. Gjør den ikke det, svarer API-et med HTTP 402 og belaster ingenting. Skriptet stopper da.
Saldo og forbruk kan du når som helst sjekke gratis via account.
Vanlige fallgruver
- Registernummer uten domstol: Står det bare «HRB 6089» i dataene dine, finner API-et ikke noe firma. Legg til registerdomstolen eller bruk navn og sted.
- Én nøkkel, én forespørsel: Samme
Idempotency-Keymed andre parametere gir HTTP 422. For en endret forespørsel bruker du en ny nøkkel. - Nøkkelformat: Opptil 128 tegn av bokstaver, sifre og
. _ : -er tillatt, med en bokstav eller et siffer først. En nøkkel i annet format ignorerer API-et. Forespørselen kjører da uten denne beskyttelsen. - Tidsavbrudd: Med Sanntid eller mange funksjoner tar en forespørsel lengre tid. Sett tidsavbruddet i klienten din til minst 120 sekunder.