补全客户数据

为你的客户列表补充企业数据。

1

匹配公司

curl -G "https://handelsregister.ai/api/v1/fetch-organization" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode 'q=Hetzner Online GmbH Gunzenhausen'
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}
200 · 示例响应:按名称和城市匹配(节选)
如果 API 没有找到公司,你会收到 HTTP 404。不使用 AI 模式时,这不收费。将该客户标记为待复核。对模糊条目有选择地使用 AI 模式(ai_search=on-default);它额外收取 20 积分,即使没有匹配。
2

获取大量公司

Python 脚本
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  # fetch-organization 的限制


def lookup(row):
    # 登记法院加登记号是唯一的;否则用名称和城市
    q = row["register"] or f'{row["name"]} {row["city"]}'
    headers = {**HEADERS, "Idempotency-Key": f'customer-{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("customers.csv", newline="") as source, open("customers_enriched.csv", "w", newline="") as target:
    reader = csv.DictReader(source)
    writer = csv.DictWriter(target, fieldnames=reader.fieldnames + ["entity_id", "register_court", "register_number"])
    writer.writeheader()
    for row in reader:
        response = lookup(row)
        if response.status_code == 402:
            print("积分不足,运行已停止")
            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["register_court"] = registration.get("court")
            row["register_number"] = f'{registration.get("register_type")} {registration.get("register_number")}'
        writer.writerow(row)
        time.sleep(60 / PER_MINUTE)

print(f"已用:{spent} 积分")
1{2  "entity_id": "94eb910fef13f94585c48c263fa446d4",3  "name": "Hetzner Online GmbH",4  "meta": {5    "request_credit_cost": 0,6    "credits_remaining": 1457  }8}
200 · 示例响应:使用相同 Idempotency-Key 的重复请求(节选)
Python SDK 附带 enrich,可对 CSV、JSON 和 Excel 文件进行现成的数据补全。
3

控制费用

费用和限制
项目 积分
含基本数据的公司档案 5
每个功能,仅在返回数据时 1 至 80
AI 模式,即使没有匹配结果 +20
实时模式,每次成功的实时获取 +10

限制:每分钟 60 次请求。 一次请求实际消耗的积分,见每个响应中的 meta.request_credit_cost。

常见陷阱

继续阅读