Ricerca aziende

syrto_search_companies trova aziende che soddisfano criteri strutturati - settore, regione, dimensione, numero di dipendenti, metriche finanziarie, posizione radar, persone associate, contributi pubblici o una descrizione in linguaggio naturale. A differenza di syrto_find_company (che cerca per nome o codice fiscale), questo strumento filtra per caratteristiche di business.

Se ti serve il numero totale di aziende corrispondenti o statistiche aggregate (ricavi medi, EBITDA mediano, ecc.), usa syrto_aggregate_companies - questo strumento restituisce solo risultati paginati.

Quando usare questo strumento

Trovare aziende in un settore, una regione o una classe dimensionale specifici
Cercare tramite una descrizione in linguaggio naturale di cosa fa l’azienda
Filtrare le aziende per valori di metriche finanziarie o punteggi 1-5
Selezionare per posizione radar, proprietà o contributi pubblici ricevuti

Strumenti correlati: Per la ricerca per nome o codice fiscale, usa Cerca azienda. Per le statistiche aggregate, usa Aggrega aziende. Per il catalogo dei filtri così come lo espone il server, usa Documentazione dei filtri.

Argomenti

object

Un unico oggetto di filtri strutturato. Le sue chiavi di primo livello sono le sezioni documentate qui sotto: company_ids, anagraphic, state_aids, people, financial e radar.Tutti i filtri impostati si combinano in AND, sia all’interno di una sezione sia tra sezioni.

integer

Anno fiscale in cui vengono valutati i filtri annuali. Obbligatorio quando si usa filters.financial (tranne il campo consolidated) o filters.radar, oppure quando si ordina per metrica.

object

Configurazione dell’ordinamento. Omettila per l’ordine predefinito - rilevanza semantica quando anagraphic.semantic_search è impostato, altrimenti l’ordine predefinito dell’API.

Campo	Tipo	Descrizione
`field`	string	`"match_score"` (richiede `anagraphic.semantic_search`) oppure `"metric"`.
`direction`	string	`"desc"` (predefinito) o `"asc"`.
`metric_slug`	string	Obbligatorio quando `field` è `"metric"`. Lo slug della metrica su cui ordinare.

L’ordinamento avviene solo per valore della metrica - l’API non può ordinare per punteggio.Esempio: {"field": "metric", "metric_slug": "revenues_from_sales_and_services", "direction": "desc"}

string

Cursore per la paginazione. Passa il valore end_cursor di una risposta precedente per ottenere la pagina successiva di 20 risultati. Omettilo per la prima pagina.

string

"en" per l’inglese (predefinito) o "it" per l’italiano.

Sezioni dei filtri

Ogni titolo qui sotto è una chiave di primo livello di filters, e i suoi campi si annidano sotto quella chiave. I campi di tipo intervallo accettano {"min": N, "max": N} con almeno un estremo; entrambi gli estremi sono inclusivi.

`company_ids` - un elenco noto di aziende

Non richiede year. A differenza delle altre, questa sezione non è un oggetto: è un array JSON di ID aziendali direttamente sotto filters. Usala per sotto-filtrare un elenco che hai già - per esempio le partecipazioni di un’azienda, o aziende risolte a partire da un elenco di codici fiscali. Fino a 200 ID, senza duplicati, e si combina con ogni altra sezione.

Gli ID provengono solo da syrto_find_company o syrto_lookup_companies_by_tax_id. Un ID inventato può corrispondere silenziosamente all’azienda sbagliata, e uno non valido fa fallire l’intera chiamata - l’errore indica quale voce non è valida, quindi risolvi di nuovo quell’ID invece di costruirne uno sostitutivo.
Ogni ID individua un solo bilancio, individuale o consolidato. Quando questa chiave è presente non viene applicato alcun valore predefinito di consolidamento; imposta financial.consolidated solo per restringere ulteriormente la base.
Un ID assente dai risultati non ha soddisfatto i criteri indicati - ma solo quando has_next_page è false. I risultati arrivano una pagina alla volta, quindi una pagina iniziale non dice nulla sugli ID che non ha ancora raggiunto.
Una ricerca filtrata restituisce solo le corrispondenze, quindi “sotto soglia” e “nessun deposito per quell’anno” appaiono identici. Dove la distinzione conta, affianca allo screening una chiamata a syrto_aggregate_companies sullo stesso elenco di ID e sullo stesso anno: company_ids_requested meno company_count è il numero di ID senza alcuna riga.

{"company_ids": ["<id1>", "<id2>"], "financial": {"metric_filters": [{"slug": "revenues_from_sales_and_services", "min": 50000000}]}}

`anagraphic` - profilo aziendale

Non richiede year.

Campo	Tipo	Descrizione
`name`	object	Filtro sulla ragione sociale, senza distinzione tra maiuscole e minuscole. Esattamente uno tra `{"contains": "Farmacia Comunale"}` (il testo in qualsiasi punto della ragione sociale) o `{"starts_with": "Farmacia"}` (prefisso), fino a 200 caratteri. Vedi sotto.
`nace`	string[]	Codici settoriali EU NACE, fino a 20. Livello rilevato automaticamente: lettera di sezione (`A`-`U`), divisione (2 cifre, es. `"10"`), gruppo (es. `"10.1"`), classe (es. `"10.11"`). Tutti i codici devono essere dello stesso livello.
`nuts`	string[]	Codici regionali EU NUTS, fino a 20. Livello rilevato dalla lunghezza: livello 1 (3 caratteri, `"ITH"`), livello 2 (4 caratteri, `"ITH3"`), livello 3 (5 caratteri, `"ITH35"`). Tutti i codici devono essere dello stesso livello.
`lau`	string[]	Codici comunali EU LAU, fino a 50 - il livello comunale sotto il NUTS 3, es. codici ISTAT italiani `["037006"]`. Si combina con `nuts` e `country_code`.
`country_code`	string	ISO 3166-1 alpha-2, es. `"IT"`, `"DE"`. Si combina con `nuts` e `lau`.
`has_branch_in`	object	Dove un’azienda ha una sede secondaria registrata, anziché la sede legale: `{"nuts": [...], "country_code": "..."}`, almeno uno dei due. `nuts` accetta fino a 20 codici con lo stesso rilevamento del livello visto sopra. `lau` qui non è accettato. Vedi sotto.
`semantic_search`	string o string[]	Ricerca libera sulle descrizioni aziendali per attività di business - prodotti, servizi, focus settoriale. Fino a 5 query; una lista è in OR, e un’azienda si posiziona sulla query con cui corrisponde meglio. Obbligatorio per `sort_by` con `field: "match_score"`.
`match_cutoff`	float	Similarità semantica minima per `semantic_search` (0.0-1.0), applicata a ogni query. Predefinito `0.8`, tarato per l’individuazione di peer. Più alto = meno risultati, più pertinenti.
`age`	intervallo	Età dell’azienda in anni.
`shareholder_age`	intervallo	Età media in anni dei soci.
`beneficial_owner_age`	intervallo	Età media in anni dei titolari effettivi.
`executive_officer_age`	intervallo	Età media in anni degli amministratori esecutivi (CEO, amministratori delegati).
`representation_and_authority_officer_age`	intervallo	Età media in anni degli amministratori con poteri di rappresentanza e firma.
`target_market`	enum	Uno tra `B2B`, `B2C`, `B2G`, `B2B2C`, `B2B2G`, `C2C`, `C2B`, `G2C`, `G2B`.
`controlling_entity_category`	enum	La categoria dell’entità che controlla l’azienda: `FAMILY`, `FAMILY_OWNED_GROUP`, `FINANCIALLY_OWNED_GROUP`, `INDUSTRIAL_GROUP`, `FINANCIAL`, `OTHER`.

semantic_search cerca solo l’attività di business - non la ragione sociale, i dati finanziari, la proprietà o la forma giuridica. Usa una lista per alternative reali (“pannelli solari” OPPURE “turbine eoliche”); mantieni una query per attività, perché la corrispondenza è per significato e non per parola chiave. name viene confrontato letteralmente, quindi passa il nome così come è scritto: un suffisso di forma giuridica come “S.r.l.” restringe la corrispondenza alle aziende la cui ragione sociale lo contiene davvero. Due regole di ortografia tirano in direzioni opposte: gli apostrofi devono essere quello ASCII dritto (Dell'Orto, non una variante tipografica), mentre le lettere accentate devono essere il carattere reale (Nicolò, mai NICOLO'). L’indice memorizza ciascuna in una sola di quelle forme; un apostrofo sostitutivo viene rifiutato, indicando la grafia da inviare, mentre le lettere accentate passano inalterate. Questo filtro seleziona e non ordina mai: i risultati tornano nell’ordine predefinito, o in quello richiesto da sort_by, senza alcuna nozione di corrispondenza migliore sul nome. Per cercare una singola azienda per nome usa syrto_find_company - name serve a combinare un nome con criteri di settore, localizzazione o finanziari. I tre filtri di localizzazione - nuts, lau e country_code - corrispondono alla sede legale dell’azienda, non alle sue sedi secondarie. has_branch_in è quello che corrisponde a una sede secondaria: un’azienda viene mantenuta quando almeno una delle sue sedi secondarie registrate si trova nell’area indicata. Si combina con i filtri sulla sede legale invece di sostituirli, quindi {"nuts": ["ITC4"], "has_branch_in": {"nuts": ["ITF4"]}} significa con sede legale in ITC4 e con almeno una sede secondaria in ITF4. “Aziende presenti in X” sono le due domande insieme - esegui una ricerca sui filtri della sede legale e una su has_branch_in. Una corrispondenza su una sede secondaria non cambia il modo in cui i risultati sono descritti: ogni azienda torna comunque con la sua sede legale, e nessun campo indica quale sede secondaria ha corrisposto. Per le sedi secondarie registrate di una singola azienda, usa Sedi secondarie.

{"anagraphic": {"nace": ["C"], "nuts": ["ITH3"], "age": {"min": 5}, "target_market": "B2B"}}

`state_aids` - contributi pubblici ricevuti

Non richiede year - il riepilogo non è per esercizio. Gli importi sono in EUR.

Campo	Tipo	Descrizione
`total_amount`	intervallo	Totale aiuti di Stato ricevuti, storico completo.
`amount_last_36_months`	intervallo	Aiuti ricevuti negli ultimi 36 mesi.
`count_last_36_months`	intervallo intero	Numero di contributi negli ultimi 36 mesi.
`above_sector_median_last_36_months`	boolean	`true` mantiene solo le aziende i cui aiuti degli ultimi 36 mesi superano la mediana del loro settore; `false` mantiene quelle pari o inferiori.
`de_minimis_remaining`	intervallo	Massimale de minimis residuo prima della soglia regolamentare. Usa `{"min": 1}` per trovare aziende che possono ancora ricevere aiuti de minimis.
`last_grant_date`	intervallo di date	Data del contributo più recente, come `{"after": "YYYY-MM-DD", "before": "YYYY-MM-DD"}` - almeno un estremo, inclusivo.

{"state_aids": {"amount_last_36_months": {"min": 500000}, "de_minimis_remaining": {"min": 1}}}

`people` - persone associate

Non richiede year. Risolvi prima gli ID delle persone con syrto_find_person. All’interno di ogni lista corrisponde una qualsiasi delle persone indicate; i campi di relazione impostati si combinano in AND.

Campo	Tipo	Descrizione
`officers`	object[]	Fino a 20 voci `{"person_id": "...", "role_category": "..."}`. `role_category` è opzionale; i valori validi sono `GOVERNING_BODIES`, `ADMINISTRATION_AND_EXECUTIVES`, `AUDITING`, `REPRESENTATION_AND_AUTHORITY`, `EXTRAORDINARY_PROCEDURES`, `FUNCTIONAL_ROLES`, `PARTICIPATION_OWNERSHIP`, `CHIEF_EXECUTIVE_OFFICER`, `OTHER`.
`shareholder_ids`	string[]	Fino a 20 ID di persone che sono soci.
`beneficial_owner_ids`	string[]	Fino a 20 ID di persone che sono titolari effettivi.

{"people": {"officers": [{"person_id": "person-id", "role_category": "CHIEF_EXECUTIVE_OFFICER"}]}}

`financial` - dimensione, dipendenti, valori e punteggi delle metriche

Richiede year per size, employees e metric_filters. Senza di esso ogni azienda viene misurata su un periodo di riferimento diverso.

Campo	Tipo	Descrizione
`size`	enum[]	Fasce dimensionali `"XS"`, `"S"`, `"M"`, `"L"`. È la fascia discreta - distinta da `radar.size`, che è un punteggio 0-100.
`employees`	intervallo intero	Numero di dipendenti, es. `{"min": 50, "max": 250}`.
`metric_filters`	object[]	Fino a 10 vincoli per metrica. Vedi sotto.
`consolidated`	boolean	Bilanci consolidati (`true`) o non consolidati (`false`, predefinito). Questo campo da solo non richiede `year`.

Ogni voce di metric_filters è {"slug": ..., "min": N, "max": N, "score_min": 1-5, "score_max": 1-5} con almeno uno dei quattro vincoli. Trova gli slug validi con syrto_search_metric_definitions.

min / max vincolano il valore grezzo sulla scala nativa dell’API, mai moltiplicato per 100: passa 0.1 per “EBIT margin pari o superiore al 10%”, 1.2 per “ROI pari o superiore al 120%”. I valori possono essere negativi, es. -0.15 per un margine del -15%.
score_min / score_max vincolano il punteggio - la valutazione 1-5 che l’API attribuisce a quel valore rispetto al mercato di riferimento dell’azienda. È già normalizzato per direzione, quindi 5 è sempre il punteggio migliore comunque si legga la metrica grezza. Usalo per “aziende con punteggio 4 o 5 sul ROE” senza sapere cosa sia un buon ROE in quel settore.
I vincoli di valore e di punteggio sulla stessa voce si combinano in AND: {"slug": "roe", "min": 0.2, "score_min": 4} significa ROE pari o superiore al 20% e valutato 4+.
Le aziende senza punteggio per la metrica vengono escluse da qualsiasi vincolo di punteggio, incluso uno score_max - un punteggio assente non equivale mai a un punteggio basso. Alcune metriche non vengono mai valutate (il loro better_if risulta vuoto da syrto_search_metric_definitions); un vincolo di punteggio su una di queste non corrisponde a nulla, quindi filtrale per valore.

{"financial": {"size": ["M"], "employees": {"min": 50}, "metric_filters": [{"slug": "ebitda", "min": 1000000}, {"slug": "roe", "score_min": 4}]}}

`radar` - posizione Syrto Radar

Richiede year. Il piano radar ha due assi sintetici proprietari 0-100: size (quanto è grande complessivamente un’azienda) ed efficiency (quanto è buona complessivamente). Lo stesso punteggio significa la stessa cosa in ogni settore.

Campo	Tipo	Descrizione
`size`	intervallo 0-100	Intervallo inclusivo sull’asse dimensione (orizzontale). Diverso dalla fascia `financial.size` (XS-L) e dal numero di dipendenti.
`efficiency`	intervallo 0-100	Intervallo inclusivo sull’asse efficienza (verticale). Più alto è meglio.
`polygon`	object	Una regione arbitraria sul piano (size, efficiency), come `{"vertices": [{"size": 80, "efficiency": 80}, ...]}` - da 3 a 64 vertici, ogni coordinata 0-100.

Imposta almeno uno tra size, efficiency e polygon. Usa gli intervalli sugli assi per rettangoli o fasce allineati agli assi, e polygon per triangoli, forme a L o regioni concave.

{"radar": {"efficiency": {"min": 70}, "size": {"min": 40, "max": 70}}}

Deve essere fornito almeno un filtro. Restituisce fino a 20 risultati per pagina - usa end_cursor dalla risposta come parametro after per ottenere la pagina successiva. Questa dimensione di pagina coincide con il limite degli strumenti a cui una pagina di risultati viene passata, quindi una pagina può essere inoltrata direttamente a Confronta aziende, Panoramica aziendale o Struttura aziendale in un’unica chiamata.

Risposta

boolean

Se sono disponibili altri risultati oltre la pagina corrente.

object[]

Lista delle aziende corrispondenti (fino a 20), ciascuna con:

id - l’ID azienda da passare agli altri strumenti Syrto nella loro lista company_ids
legal_name - ragione sociale ufficiale
tax_id - codice fiscale italiano (null se non disponibile)
consolidated - sempre presente. false = i valori propri dell’azienda, true = i valori consolidati del suo gruppo

Oltre a questi, ogni campo elencato sotto è presente solo quando il relativo filtro è stato usato, così un risultato mostra il valore dell’azienda per ciò su cui hai cercato:

Campo	Compare con
`short_description`, `match_score`	`anagraphic.semantic_search`
`metrics` - ciascuna con `name`, `slug`, `value`, `better_when` e il `score` 1-5 dove la metrica ne ha uno	`financial.metric_filters`, o un ordinamento per metrica
`controlling_entity_category`, `target_markets`, `nace`, `nuts`, `lau`, `country_code`	il filtro `anagraphic` corrispondente
`founding_year`	`anagraphic.age`
`shareholder_birth_year_average` e gli altri campi `*_birth_year_average`, come valori grezzi	il filtro `anagraphic.*_age` corrispondente
`size`, `employee_count`	il filtro `financial` corrispondente
`state_aid_total_amount`, `state_aid_amount_last_36_months`, `state_aid_count_last_36_months`, `state_aid_above_sector_median_last_36_months`, `de_minimis_remaining`	il filtro `state_aids` corrispondente
`radar` - `efficiency` e `size`, 0-100	un filtro `radar`

state_aids.last_grant_date e anagraphic.has_branch_in sono i filtri senza un campo corrispondente nella risposta.

string | null

Token del cursore per la pagina successiva. Passalo come parametro after. null quando non ci sono altre pagine.

Quando nulla corrisponde, items è una lista vuota e warning suggerisce come allargare la ricerca - non è un errore. Accanto a result, la risposta contiene i campi restituiti da ogni strumento. Qui display_title è la ragione sociale dell’azienda trovata, oppure un conteggio delle aziende in questa pagina, e subtitle segnala quando sono disponibili altri risultati.

Esempio

Trovare grandi aziende manifatturiere in Emilia-Romagna:

{
  "filters": {
    "anagraphic": { "nace": ["C"], "nuts": ["ITH5"] },
    "financial": { "size": ["L"] }
  },
  "year": 2023
}

Trovare produttori di solare o eolico ben valutati con margine di aiuti pubblici:

{
  "filters": {
    "anagraphic": {
      "semantic_search": ["produzione di pannelli solari", "produzione di turbine eoliche"],
      "country_code": "IT"
    },
    "financial": {
      "metric_filters": [{ "slug": "roe", "score_min": 4 }]
    },
    "state_aids": { "de_minimis_remaining": { "min": 1 } }
  },
  "year": 2023
}

​Quando usare questo strumento

​Argomenti

​Sezioni dei filtri

​company_ids - un elenco noto di aziende

​anagraphic - profilo aziendale

​state_aids - contributi pubblici ricevuti

​people - persone associate

​financial - dimensione, dipendenti, valori e punteggi delle metriche

​radar - posizione Syrto Radar

​Risposta

​Esempio

Quando usare questo strumento

Argomenti

Sezioni dei filtri

`company_ids` - un elenco noto di aziende

`anagraphic` - profilo aziendale

`state_aids` - contributi pubblici ricevuti

`people` - persone associate

`financial` - dimensione, dipendenti, valori e punteggi delle metriche

`radar` - posizione Syrto Radar

Risposta

Esempio