Montar listas de empresas
Filtre empresas por setor, região, porte e mais com a Busca & Exportação.
search-organizations encontra empresas pelas suas características em vez de pelo nome. Você combina filtros, ordena por indicadores e pagina pelos resultados. Para ter a lista como arquivo, você a exporta no app web.
Combinar filtros
Os filtros vão no parâmetro filters como objeto JSON. Todos os filtros valem juntos. Se você informar vários valores num filtro, basta que um deles corresponda.
curl -G "https://handelsregister.ai/api/v1/search-organizations" \ -H "x-api-key: SUA_CHAVE_DE_API" \ --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": "SUA_CHAVE_DE_API"}, 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": "SUA_CHAVE_DE_API" }, }); 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}
| Característica | Filtro |
|---|---|
| Região |
state, county, city, postal_code; raio com location_coordinates e location_max_distance_km |
| Setor |
industry_code, um código de cinco dígitos da WZ 2025 como 62.10.1, também como lista |
| Forma jurídica |
legal_form_code, como GmbH, AG ou UG (haftungsbeschränkt) |
| Situação |
status (ACTIVE, INSOLVENT …) ou active (true, false) |
| Porte |
company_size_category pelo balanço, emp_size_category por funcionários: micro, small, medium, large |
| Indicadores |
financial_filters com intervalos, como {"emp_count": {"gte": 50}} |
| Registro |
registration_date_from, registration_date_to |
| A partir do Pro |
owner_filters, ownership_filters, executive_filters, lifecycle_filters: sócios, estrutura de propriedade, administração, insolvência |
Todos os filtros com seus valores estão em search-organizations. total geralmente é um limite superior do número de resultados. A partir de 10.000 resultados, é uma estimativa.
Ordenar
Com sort e order você define a ordem, por exemplo por faturamento, funcionários, ativo total ou data de registro. Empresas sem o valor vêm por último. O exemplo busca GmbHs com pelo menos 50 funcionários no distrito e ordena por faturamento.
curl -G "https://handelsregister.ai/api/v1/search-organizations" \ -H "x-api-key: SUA_CHAVE_DE_API" \ --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": "SUA_CHAVE_DE_API"}, 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": "SUA_CHAVE_DE_API" }, }); 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}
Com match_context=1, cada resultado mostra em _match_context por que corresponde, para indicadores com o ano do valor. Isso importa porque a demonstração mais recente de cada empresa pode ser de um ano diferente. O resultado não contém o faturamento em si; você o obtém com financial_kpi por fetch-organization.
Sem sort, uma busca com q ordena por relevância. Em consultas só com filtros, defina sort quando a ordem importar.
Paginar resultados
limit define quantos resultados uma página tem, no máximo 30. skip pula resultados: a segunda página começa em skip igual a limit.
curl -G "https://handelsregister.ai/api/v1/search-organizations" \ -H "x-api-key: SUA_CHAVE_DE_API" \ --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": "SUA_CHAVE_DE_API"}, 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": "SUA_CHAVE_DE_API" }, }); 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}
Cada página custa 1 crédito, mesmo uma página sem resultados. Por isso, páginas grandes são as mais baratas por empresa.
Uma busca vai até o resultado número 10.000. Para conjuntos maiores, divida-a, por exemplo por estado, código postal ou período de registro.
Exportar a lista
Você recebe um arquivo no app web: em Busca & Exportação, defina os filtros e escolha “Exportar”. A exportação retorna até 5.000 empresas como CSV, XLSX ou JSON.
Antes de começar, você vê o limite superior e os custos. A exportação deixa de fora empresas sem endereço publicado; sob pedido, ela as inclui. O arquivo pronto fica em Conta › Exportações.
A exportação só lê os resultados quando roda. Assim, alterações até esse momento estão incluídas. Pela API, você monta a mesma lista página por página, como mostrado acima.
Armadilhas comuns
- Escreva os valores exatamente:
statusem maiúsculas,registration_numbersem “HRB”, códigos de setor com cinco dígitos. Valores desconhecidos retornam 0 resultados, e a página é cobrada mesmo assim. - Filtros a partir do Pro:
owner_filterse os outros filtros Pro precisam de uma assinatura de créditos Pro ou Max. Caso contrário, a API responde com HTTP 403, sem custo. - Número de registro no termo de busca:
qbusca nomes. Para um número de registro, use os filtrosregistration_authority_nameeregistration_number. - q vazio: um
q=vazio retorna HTTP 400. Omitaqquando só filtrar.