회사 목록 만들기
검색 및 내보내기로 업종, 지역, 규모 등으로 회사를 필터링하세요.
search-organizations는 이름 대신 특성으로 회사를 찾아요. 필터를 조합하고, KPI로 정렬하고, 결과 페이지를 넘겨요. 목록을 파일로 받으려면 웹 앱에서 내보내요.
필터 조합
필터는 파라미터 filters에 JSON 객체로 넣어요. 모든 필터가 함께 적용돼요. 한 필터에 여러 값을 주면 그중 하나만 맞아도 돼요.
curl -G "https://handelsregister.ai/api/v1/search-organizations" \ -H "x-api-key: YOUR_API_KEY" \ --data-urlencode 'filters={"legal_form_code":"GmbH","city":"Gunzenhausen","active":true}' \ --data-urlencode 'limit=5'
import requests response = requests.get( "https://handelsregister.ai/api/v1/search-organizations", headers={"x-api-key": "YOUR_API_KEY"}, params={ "filters": "{\"legal_form_code\":\"GmbH\",\"city\":\"Gunzenhausen\",\"active\":true}", "limit": "5", }, ) data = response.json()
const url = new URL("https://handelsregister.ai/api/v1/search-organizations"); url.searchParams.append("filters", "{\"legal_form_code\":\"GmbH\",\"city\":\"Gunzenhausen\",\"active\":true}"); url.searchParams.append("limit", "5"); const response = await fetch(url, { headers: { "x-api-key": "YOUR_API_KEY" }, }); const data = await response.json();
1{2 "results": [3 {4 "entity_id": "0100d4d86f3f26fceac3a833db59d700",5 "name": "Beyer Grundstücksverwaltungs-GmbH",6 "registration": {7 "court": "Ansbach",8 "register_type": "HRB",9 "register_number": "3635"10 },11 "address": {12 "house_number": "42",13 "street": "Nürnberger Str.",14 "postal_code": "91710",15 "city": "Gunzenhausen",16 "county": "Weißenburg-Gunzenhausen",17 "state": "Bayern",18 "country": "DEU",19 "coordinates": {20 "latitude": 49.11954,21 "longitude": 10.7591822 }23 },24 "seat": {25 "city": "Gunzenhausen"26 },27 "registration_date": "2003-04-15T00:00:00",28 "purpose": "Die Beteiligung als persönlich haftende Gesellschafterin an der Beyer Grundbesitz GmbH & Co. KG sowie die Geschäftsführung dieser Kommanditgesellschaft. Unternehmensgegenstand dieser Kommanditgesellschaft ist die Verwaltung eigenen Vermögens, insbesondere der Erwerb, die Verwaltung, die Bebauung und die Verwertung von Grundbesitz, jedoch mit Ausnahme von Tätigkeiten, die einer Genehmigung nach § 34 c GewO bedürfen.",29 "_match_context": [],30 "status_normalized": "ACTIVE"31 },32 {33 "entity_id": "0269de827eef8cae201195e4966886c3",34 "name": "Martin Bosch GmbH",35 "registration": {36 "court": "Ansbach",37 "register_type": "HRB",38 "register_number": "5034"39 },40 "address": {41 "house_number": "14 A",42 "street": "Auweg",43 "postal_code": "91710",44 "city": "Gunzenhausen",45 "county": "Weißenburg-Gunzenhausen",46 "state": "Bayern",47 "country": "DEU",48 "coordinates": {49 "latitude": 49.11129,50 "longitude": 10.7580151 }52 },53 "seat": {54 "city": "Gunzenhausen"55 },56 "registration_date": "2010-09-23T00:00:00",57 "purpose": "Gegenstand des Unternehmens ist - der Vertrieb und die Montage von Waren aller Art, insbesondere von Photovoltaikanlagen, Bauteilen nach DIN vorwiegend von Fenstern und Türen, - die Erbringung von Dienstleistungen und Vertriebsunterstützung im Bereich von Sport und Freizeitartikeln, - die Erbringung von Bauleistungen aller Art, insbesondere im Bereich Wohnbau, und zwar auch Leistungen im Sinne des § 34 c Abs. 1 Nr. 3. GewO, d.h. gewerbsmäßige Vorbereitung oder Durchführung von Bauvorhaben als Ba …",58 "_match_context": [],59 "status_normalized": "ACTIVE"60 },61 {62 "entity_id": "072223d1d792f9295175f80dded04545",63 "name": "König & Reuß Softwarelösungen GmbH",64 "registration": {65 "court": "Ansbach",66 "register_type": "HRB",67 "register_number": "5881"68 },69 "address": {70 "house_number": "6",71 "street": "Kirchenplatz",72 "postal_code": "91710",73 "city": "Gunzenhausen",74 "county": "Weißenburg-Gunzenhausen",75 "state": "Bayern",76 "country": "DEU",77 "coordinates": {78 "latitude": 49.11263,79 "longitude": 10.7553280 }81 },82 "seat": {83 "city": "Gunzenhausen"84 },85 "registration_date": "2014-07-15T00:00:00",86 "purpose": "Die Entwicklung und der Vertrieb von Software, die Organisationsberatung für EDV-Lösungen, EDV-Schulungen sowie der damit zusammenhängende An- und Verkauf von Hardware.",87 "_match_context": [],88 "status_normalized": "ACTIVE"89 },90 {91 "entity_id": "078582ddfc9526b6405289afa26b66f5",92 "name": "Wolfgang Seifert GmbH",93 "registration": {94 "court": "Ansbach",95 "register_type": "HRB",96 "register_number": "7369"97 },98 "address": {99 "house_number": "1",100 "street": "Brechhausstr.",101 "postal_code": "91710",102 "city": "Gunzenhausen",103 "county": "Weißenburg-Gunzenhausen",104 "state": "Bayern",105 "country": "DEU",106 "coordinates": {107 "latitude": 49.12887,108 "longitude": 10.7468109 }110 },111 "seat": {112 "city": "Gunzenhausen"113 },114 "registration_date": "2020-12-07T00:00:00",115 "purpose": "Die Ausführung von Isolierarbeiten sowie der Betrieb eines Getränkemarktes.",116 "_match_context": [],117 "status_normalized": "ACTIVE"118 },119 {120 "entity_id": "08764e95299e20f75f873d9497eab723",121 "name": "Zimmerei Ortner GmbH",122 "registration": {123 "court": "Ansbach",124 "register_type": "HRB",125 "register_number": "7994"126 },127 "address": {128 "house_number": "22",129 "street": "Hauptstr.",130 "postal_code": "91710",131 "city": "Gunzenhausen",132 "county": "Weißenburg-Gunzenhausen",133 "state": "Bayern",134 "country": "DEU",135 "coordinates": {136 "latitude": 49.10797,137 "longitude": 10.73341138 }139 },140 "seat": {141 "city": "Gunzenhausen"142 },143 "registration_date": "2022-12-19T00:00:00",144 "purpose": "Der Betrieb einer Zimmerei sowie die Durchführung von Dachdeckerarbeiten, Trockenbauarbeiten und Holzbauarbeiten aller Art.",145 "_match_context": [],146 "status_normalized": "ACTIVE"147 }148 ],149 "total": 239,150 "total_exact": false,151 "total_relation": "upper_bound",152 "meta": {153 "request_credit_cost": 1,154 "credits_remaining": 145155 }156}
| 특성 | 필터 |
|---|---|
| 지역 |
state, county, city, postal_code; 반경은 location_coordinates와 location_max_distance_km |
| 업종 |
industry_code, 62.10.1 같은 WZ 2025의 다섯 자리 코드, 목록도 가능 |
| 법적 형태 |
legal_form_code, 예: GmbH, AG, UG (haftungsbeschränkt) |
| 상태 |
status(ACTIVE, INSOLVENT …) 또는 active(true, false) |
| 규모 |
재무상태표 기준 company_size_category, 직원 수 기준 emp_size_category: micro, small, medium, large |
| KPI |
범위가 담긴 financial_filters, 예: {"emp_count": {"gte": 50}} |
| 등기 |
registration_date_from, registration_date_to |
| Pro부터 |
owner_filters, ownership_filters, executive_filters, lifecycle_filters: 주주, 소유 구조, 경영진, 파산 |
모든 필터와 값은 search-organizations에 있어요. total은 대개 결과 수의 상한이에요. 결과가 10,000개 이상이면 추정치예요.
정렬
sort와 order로 순서를 정해요. 예: 매출, 직원 수, 총자산, 등기일 순. 값이 없는 회사는 맨 뒤에 와요. 예시는 군(Landkreis) 안에서 직원 50명 이상인 GmbH를 찾아 매출순으로 정렬해요.
curl -G "https://handelsregister.ai/api/v1/search-organizations" \ -H "x-api-key: YOUR_API_KEY" \ --data-urlencode 'filters={"county":"Weißenburg-Gunzenhausen","legal_form_code":"GmbH","status":"ACTIVE","financial_filters":{"emp_count":{"gte":50}}}' \ --data-urlencode 'sort=revenue' \ --data-urlencode 'order=desc' \ --data-urlencode 'limit=5' \ --data-urlencode 'match_context=1'
import requests response = requests.get( "https://handelsregister.ai/api/v1/search-organizations", headers={"x-api-key": "YOUR_API_KEY"}, params={ "filters": "{\"county\":\"Weißenburg-Gunzenhausen\",\"legal_form_code\":\"GmbH\",\"status\":\"ACTIVE\",\"financial_filters\":{\"emp_count\":{\"gte\":50}}}", "sort": "revenue", "order": "desc", "limit": "5", "match_context": "1", }, ) data = response.json()
const url = new URL("https://handelsregister.ai/api/v1/search-organizations"); url.searchParams.append("filters", "{\"county\":\"Weißenburg-Gunzenhausen\",\"legal_form_code\":\"GmbH\",\"status\":\"ACTIVE\",\"financial_filters\":{\"emp_count\":{\"gte\":50}}}"); url.searchParams.append("sort", "revenue"); url.searchParams.append("order", "desc"); url.searchParams.append("limit", "5"); url.searchParams.append("match_context", "1"); const response = await fetch(url, { headers: { "x-api-key": "YOUR_API_KEY" }, }); const data = await response.json();
1{2 "results": [3 {4 "entity_id": "94eb910fef13f94585c48c263fa446d4",5 "name": "Hetzner Online GmbH",6 "registration": {7 "court": "Ansbach",8 "register_type": "HRB",9 "register_number": "6089"10 },11 "address": {12 "house_number": "25",13 "street": "Industriestraße",14 "postal_code": "91710",15 "city": "Gunzenhausen",16 "county": "Weißenburg-Gunzenhausen",17 "state": "Bayern",18 "country": "DEU",19 "coordinates": {20 "latitude": 49.12483,21 "longitude": 10.7805222 }23 },24 "seat": {25 "city": "Gunzenhausen"26 },27 "registration_date": "2015-07-28T00:00:00",28 "purpose": "Die Durchführung von Internet- und Netzwerkdienstleistungen, das Erstellen und Vertreiben von Software, der Handel mit Hard- und Software, der Betrieb einer Werbeagentur,darüber hinaus der Im- und Export von Waren aller Art, soweit sie keiner Einfuhr- oder Ausfuhrbeschränkung unterliegen und soweit keine Genehmigungen erforderlich sind.",29 "_match_context": {30 "financial": {31 "emp_count": 340,32 "year": 202333 },34 "legal_form": {35 "name": "Gesellschaft mit beschränkter Haftung",36 "category": "capital_company",37 "liability_type": "limited"38 }39 },40 "status_normalized": "ACTIVE"41 },42 {43 "entity_id": "e937d0eb0d9b938afaae55808a066400",44 "name": "Auto Bierschneider GmbH",45 "registration": {46 "court": "Ansbach",47 "register_type": "HRB",48 "register_number": "3953"49 },50 "address": {51 "house_number": "23",52 "street": "Dettenheimer Str.",53 "postal_code": "91781",54 "city": "Weißenburg i. Bay.",55 "county": "Weißenburg-Gunzenhausen",56 "state": "Bayern",57 "country": "DEU",58 "coordinates": {59 "latitude": 49.00163,60 "longitude": 10.9519861 }62 },63 "seat": {64 "city": "Weißenburg i. Bay."65 },66 "registration_date": "2005-03-22T00:00:00",67 "purpose": "Die Reparatur und der Handel mit Kraftfahrzeugen aller Art.",68 "_match_context": {69 "financial": {70 "emp_count": 263,71 "year": 202472 },73 "legal_form": {74 "name": "Gesellschaft mit beschränkter Haftung",75 "category": "capital_company",76 "liability_type": "limited"77 }78 },79 "status_normalized": "ACTIVE"80 },81 {82 "entity_id": "7bde1c2520a00de2e67da1237163c629",83 "name": "Hasselbacher GmbH Metallrecycling",84 "registration": {85 "court": "Ansbach",86 "register_type": "HRB",87 "register_number": "3865"88 },89 "address": {90 "house_number": "24",91 "street": "Treuchtlinger Str.",92 "postal_code": "91781",93 "city": "Weißenburg i.Bay.",94 "county": "Weißenburg-Gunzenhausen",95 "state": "Bayern",96 "country": "DEU",97 "coordinates": {98 "latitude": 49.01128,99 "longitude": 10.95407100 }101 },102 "seat": {103 "city": "Weißenburg i. Bay."104 },105 "registration_date": "2004-10-05T00:00:00",106 "purpose": "Das Metallrecycling sowie der Schrott- und Metallgroßhandel.",107 "_match_context": {108 "financial": {109 "emp_count": 50,110 "year": 2024111 },112 "legal_form": {113 "name": "Gesellschaft mit beschränkter Haftung",114 "category": "capital_company",115 "liability_type": "limited"116 }117 },118 "status_normalized": "ACTIVE"119 },120 {121 "entity_id": "3d495cff8ca2f1e8e717d8ff1317f61d",122 "name": "KTX GmbH",123 "registration": {124 "court": "Ansbach",125 "register_type": "HRB",126 "register_number": "5941"127 },128 "address": {129 "house_number": "34",130 "street": "Dettenheimer Strasse",131 "postal_code": "91781",132 "city": "Weißenburg",133 "county": "Weißenburg-Gunzenhausen",134 "state": "Bayern",135 "country": "DEU",136 "coordinates": {137 "latitude": 49.00551,138 "longitude": 10.95048139 }140 },141 "seat": {142 "city": "Weißenburg"143 },144 "registration_date": "2014-11-24T00:00:00",145 "purpose": "Die Entwicklung von technischen Problemlösungen auf dem Gebiet der Kunststoffindustrie, die Herstellung, Weiterverarbeitung und der Vertrieb von Kunststoffartikeln aller Art, insbesondere, aber nicht nur, für die Automobilindustrie.",146 "_match_context": {147 "financial": {148 "emp_count": 664,149 "year": 2024150 },151 "legal_form": {152 "name": "Gesellschaft mit beschränkter Haftung",153 "category": "capital_company",154 "liability_type": "limited"155 }156 },157 "status_normalized": "ACTIVE"158 },159 {160 "entity_id": "c95348029f78b1a5162a365a46e772a3",161 "name": "GUTMANN GmbH",162 "registration": {163 "court": "Ansbach",164 "register_type": "HRB",165 "register_number": "3621"166 },167 "address": {168 "house_number": "57",169 "street": "Nürnberger Straße",170 "postal_code": "91781",171 "city": "Weißenburg",172 "county": "Weißenburg-Gunzenhausen",173 "state": "Bayern",174 "country": "DEU",175 "coordinates": {176 "latitude": 49.04067,177 "longitude": 10.96989178 }179 },180 "seat": {181 "city": "Weißenburg i. Bay."182 },183 "registration_date": "2003-03-19T00:00:00",184 "purpose": "Die Produktion von Erzeugnissen aller Art und der Handel und Vertrieb von Produkten aller Art; insbesondere die Be- und Verarbeitung von Metall, Holz und Kunststoff.",185 "_match_context": {186 "financial": {187 "emp_count": 356,188 "year": 2024189 },190 "legal_form": {191 "name": "Gesellschaft mit beschränkter Haftung",192 "category": "capital_company",193 "liability_type": "limited"194 }195 },196 "status_normalized": "ACTIVE"197 }198 ],199 "total": 36,200 "total_exact": false,201 "total_relation": "upper_bound",202 "meta": {203 "request_credit_cost": 1,204 "credits_remaining": 145205 }206}
match_context=1을 쓰면 각 결과의 _match_context에 왜 일치하는지 나오며, KPI는 값의 연도도 함께 나와요. 회사마다 최신 재무제표의 연도가 다를 수 있으므로 중요해요. 결과에는 매출 자체는 없어요. 매출은 fetch-organization의 financial_kpi로 가져오세요.
sort가 없으면 q가 있는 검색은 관련도순으로 정렬해요. 필터만 쓰는 조회에서는 순서가 중요할 때 sort를 설정하세요.
결과 페이지 넘기기
limit은 한 페이지의 결과 수로, 최대 30개예요. skip은 결과를 건너뛰어요: 두 번째 페이지는 skip이 limit과 같을 때 시작해요.
curl -G "https://handelsregister.ai/api/v1/search-organizations" \ -H "x-api-key: YOUR_API_KEY" \ --data-urlencode 'filters={"legal_form_code":"GmbH","city":"Gunzenhausen","active":true}' \ --data-urlencode 'limit=3' \ --data-urlencode 'skip=3'
import requests response = requests.get( "https://handelsregister.ai/api/v1/search-organizations", headers={"x-api-key": "YOUR_API_KEY"}, params={ "filters": "{\"legal_form_code\":\"GmbH\",\"city\":\"Gunzenhausen\",\"active\":true}", "limit": "3", "skip": "3", }, ) data = response.json()
const url = new URL("https://handelsregister.ai/api/v1/search-organizations"); url.searchParams.append("filters", "{\"legal_form_code\":\"GmbH\",\"city\":\"Gunzenhausen\",\"active\":true}"); url.searchParams.append("limit", "3"); url.searchParams.append("skip", "3"); const response = await fetch(url, { headers: { "x-api-key": "YOUR_API_KEY" }, }); const data = await response.json();
1{2 "results": [3 {4 "entity_id": "078582ddfc9526b6405289afa26b66f5",5 "name": "Wolfgang Seifert GmbH",6 "registration": {7 "court": "Ansbach",8 "register_type": "HRB",9 "register_number": "7369"10 },11 "address": {12 "house_number": "1",13 "street": "Brechhausstr.",14 "postal_code": "91710",15 "city": "Gunzenhausen",16 "county": "Weißenburg-Gunzenhausen",17 "state": "Bayern",18 "country": "DEU",19 "coordinates": {20 "latitude": 49.12887,21 "longitude": 10.746822 }23 },24 "seat": {25 "city": "Gunzenhausen"26 },27 "registration_date": "2020-12-07T00:00:00",28 "purpose": "Die Ausführung von Isolierarbeiten sowie der Betrieb eines Getränkemarktes.",29 "_match_context": [],30 "status_normalized": "ACTIVE"31 },32 {33 "entity_id": "08764e95299e20f75f873d9497eab723",34 "name": "Zimmerei Ortner GmbH",35 "registration": {36 "court": "Ansbach",37 "register_type": "HRB",38 "register_number": "7994"39 },40 "address": {41 "house_number": "22",42 "street": "Hauptstr.",43 "postal_code": "91710",44 "city": "Gunzenhausen",45 "county": "Weißenburg-Gunzenhausen",46 "state": "Bayern",47 "country": "DEU",48 "coordinates": {49 "latitude": 49.10797,50 "longitude": 10.7334151 }52 },53 "seat": {54 "city": "Gunzenhausen"55 },56 "registration_date": "2022-12-19T00:00:00",57 "purpose": "Der Betrieb einer Zimmerei sowie die Durchführung von Dachdeckerarbeiten, Trockenbauarbeiten und Holzbauarbeiten aller Art.",58 "_match_context": [],59 "status_normalized": "ACTIVE"60 },61 {62 "entity_id": "0a5cea0c9d3861d10d42f21c1d3f9816",63 "name": "TJ Gastro 3 GmbH",64 "registration": {65 "court": "Ansbach",66 "register_type": "HRB",67 "register_number": "8809"68 },69 "address": {70 "house_number": "111",71 "street": "Nürnberger Straße",72 "postal_code": "91710",73 "city": "Gunzenhausen",74 "county": "Weißenburg-Gunzenhausen",75 "state": "Bayern",76 "country": "DEU",77 "coordinates": {78 "latitude": 49.12861,79 "longitude": 10.7708280 }81 },82 "seat": {83 "city": "Gunzenhausen"84 },85 "registration_date": "2021-01-11T00:00:00",86 "purpose": "Der Betrieb von Restaurants entsprechend dem mit der McDonald´s Deutschland Inc., Zweigniederlassung München, und Herrn Dr. Konrad Exempelmann abgeschlossenen Franchise-Vertrag, dem die Gesellschaft beigetreten ist.",87 "_match_context": [],88 "status_normalized": "ACTIVE"89 }90 ],91 "total": 239,92 "total_exact": false,93 "total_relation": "upper_bound",94 "meta": {95 "request_credit_cost": 1,96 "credits_remaining": 14597 }98}
각 페이지는 결과가 없는 페이지도 1 크레딧이에요. 그래서 큰 페이지가 회사당 가장 저렴해요.
검색은 10,000번째 결과까지 가요. 더 큰 집합은 예를 들어 주, 우편번호, 등기 기간으로 나누세요.
목록 내보내기
파일은 웹 앱에서 받아요: 검색 및 내보내기에서 필터를 설정하고 “내보내기”를 선택하세요. 내보내기는 최대 5,000개 회사를 CSV, XLSX 또는 JSON으로 반환해요.
시작 전에 상한과 비용을 확인할 수 있어요. 내보내기는 공개 주소가 없는 회사를 제외하며, 원하면 포함할 수 있어요. 완성된 파일은 계정 › 내보내기에 있어요.
내보내기는 실행될 때 결과를 읽어요. 그래서 그 시점까지의 변경이 반영돼요. API로는 위에서 보인 것처럼 페이지별로 같은 목록을 만들어요.
자주 하는 실수
- 값을 정확히 쓰기:
status는 대문자,registration_number는 “HRB” 없이, 업종 코드는 다섯 자리로. 알 수 없는 값은 결과 0개를 반환하고, 페이지는 그래도 과금돼요. - Pro부터인 필터:
owner_filters와 다른 Pro 필터에는 Pro 또는 Max 크레딧 구독이 필요해요. 그렇지 않으면 API가 비용 없이 HTTP 403으로 응답해요. - 검색어 속 등기 번호:
q는 이름을 검색해요. 등기 번호에는registration_authority_name과registration_number필터를 쓰세요. - 빈 q: 빈
q=는 HTTP 400을 반환해요. 필터만 쓸 때는q를 빼세요.