顧客データを補完する
顧客リストに企業データを追加する。
企業名、所在地、登記番号のリストがあり、そこに公式の企業データを加えたいとします。必要なのはfetch-organizationだけで、事前の検索は不要です。
企業を照合する
顧客ごとに、手元にある最良の情報で1回ずつリクエストを送ります。一意である登記裁判所と登記番号が最適です。それがなければ、法的形態付きの企業名と所在地を使います。例のリクエストでは、Hetzner Online GmbH（Ansbach HRB 6089）を名称と所在地で検索しています。
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}
レスポンスを自社データと照らし合わせてください。例えばaddressの郵便番号や所在地です。よくある名称では、同名の別企業が返ることもあります。
entity_idを顧客と一緒に保存してください。以降の取得、書類、Signals、モニターはすべてこの識別子で動きます。
ai_search=on-default）を選択的に使ってください。一致がなくても 20 クレジット が追加でかかります。
多数の企業を取得する
fetch-organizationでは 1分あたり 60 リクエスト が許可されています。リクエストは均等に、1つずつ順に送ってください。HTTP 429の場合は、Retry-Afterの秒数だけ待ちます。それ以上が必要なら、Enterpriseでより高い制限が利用できます。料金を参照。
各リクエストにIdempotency-Key（例えば顧客番号）を付けてください。24時間以内に同じキーと同じパラメータで繰り返しても、料金はかかりません。
HTTP 408（リクエストに時間がかかりすぎた）の場合、APIはAIモードも含めて何も課金しません。ステータス500以上のエラーの場合は、AIモードを選んでいればAIモードのみ課金されます。後で同じIdempotency-Keyでもう一度試してください。
スクリプトは、列id、name、city、registerを持つcustomers.csvを読み込みます。列registerには、Ansbach HRB 6089のように裁判所付きの登記番号が入るか、空です。スクリプトはentity_id、登記裁判所、登記番号を加えたコピーを書き出し、使用したクレジットを集計します。
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} クレジット")
24時間以内の2回目の実行は無料です。そのときレスポンスにはIdempotency-Status: replayedと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が付いています。
コストを把握する
料金表で事前に見積もってください：基本データは企業1社あたり 5 クレジット、それに各機能の料金が加わります。基本データは一致するたびにかかります。データのない機能は無料なので、実際のコストはそれより低くなることがよくあります。追加料金は機能ではありません。AIモードは一致がなくても、リアルタイムは取得が成功するたびにかかります。
| 内容 | クレジット |
|---|---|
| 基本データ付きの企業プロフィール | 5 |
| 各機能（データを返した場合のみ） | 1～80 |
| AIモード（一致がなくても課金） | +20 |
| リアルタイム（ライブ取得が成功するごとに） | +10 |
制限：1分あたり 60 リクエスト。
リクエストに実際にかかったコストは、すべてのレスポンスの meta.request_credit_cost にあります。
リクエストのコストはmeta.request_credit_costに、残りの残高はmeta.credits_remainingにあります。上のスクリプトのように、コストを順に合計してください。
APIは各リクエストの前に、残高が最大限の料金をまかなえるかを確認します。足りない場合はHTTP 402を返し、何も課金しません。その場合スクリプトは停止します。
残高と利用状況は、accountでいつでも無料で確認できます。
よくある落とし穴
- 裁判所なしの登記番号：データに「HRB 6089」しかない場合、APIは企業を見つけられません。登記裁判所を加えるか、名称と所在地を使ってください。
- 1つのキーに1つのリクエスト：同じ
Idempotency-Keyで異なるパラメータを指定するとHTTP 422が返ります。変更したリクエストには新しいキーを使ってください。 - キーの形式：英字、数字、
. _ : -からなる最大128文字で、英字か数字で始まるものが使えます。それ以外の形式のキーはAPIに無視され、リクエストはこの保護なしで実行されます。 - タイムアウト：リアルタイムや多数の機能を使うと、リクエストに時間がかかります。クライアントのタイムアウトを120秒以上に設定してください。