# Previsione del genere da nomi utente e nickname > Analizza nomi utente e nickname con la V2: forceToGenderize, IA per singolo elemento, risultati sconosciuti e costo delle richieste ripetute. Canonical HTML: https://www.genderapi.io/it/blog/previsione-del-genere-da-nickname-e-username Last reviewed: 2026-09-28 ## Dati di pubblicazione Prima pubblicazione: 2025-06-04T13:00:00.000Z Ultima revisione: 2026-09-28T00:00:00.000Z ## È possibile determinare il genere da un nome utente? GenderAPI può analizzare i segnali nominali in un nome utente, un nickname o un nome visualizzato quando manca un nome reale. Usa l'API per richieste singole o batch oppure il flusso Excel/CSV e tratta il risultato come una previsione, non come un'identità verificata. ## Un nickname non è una verifica dell'identità @alice_smith può corrispondere a un elemento nominale. Per prenses con forceToGenderize può essere restituita una previsione anche se il nome resta null. user47291 può restare sconosciuto. Si tratta di input di esempio; non assegniamo loro in anticipo alcun risultato di genere. ## Come funziona la previsione del genere da un nome utente? Il sistema cerca elementi nominali riconoscibili e altri indizi linguistici nel nome utente o nel nome visualizzato. Il normale fallback IA cerca un nome reale utilizzabile; con forceToGenderize l'IA può interpretare un nickname senza un nome reale. Il risultato viene restituito insieme ai campi di contesto; un input casuale o insufficiente non dovrebbe essere forzato a un risultato. - Nome utente: Nickname o nome visualizzato - Analisi dei segnali: Nome e contesto - Previsione: Genere e confidenza ## Scegli il metodo adatto ai tuoi dati - [Richiesta singola Analizza un nome utente tramite REST API. Visualizza la guida API →](https://www.genderapi.io/it/docs/v2/gender-from-username) - [Richiesta batch Invia più elementi in una richiesta strutturata. Visualizza la guida ai batch →](https://www.genderapi.io/it/docs/v2/batch) - [Flusso Excel/CSV Elabora un file senza sviluppare un'integrazione. Apri lo strumento →](https://app.genderapi.io/csv) ## Analizza i nomi utente di un file Excel o CSV in quattro passaggi ### Apri lo strumento Excel/CSV Apri lo strumento di importazione di GenderAPI e carica il file da elaborare. ### Scegli la colonna di origine Collega la colonna che contiene nomi utente, nickname o nomi visualizzati. ### Attiva l'interpretazione dei nickname Attiva l'opzione che interpreta alias e nomi usati sui social network. ### Verifica un campione, poi esporta Esamina prima un campione rappresentativo di record, poi elabora l'intero file e scarica i dati arricchiti. I nuovi account includono 200 crediti API gratuiti al giorno, così puoi provare il flusso su un campione prima di elaborare l'intero file. I file Excel e CSV caricati vengono rimossi dai sistemi attivi entro cinque giorni e, dopo l'esportazione dei risultati, puoi chiederne la rimozione anticipata. I backup a sovrascrittura periodica e ad accesso limitato possono contenerli per un massimo di altri 15 giorni. Maggiori informazioni sono disponibili nell'[informativa sulla privacy](https://www.genderapi.io/it/privacy-policy). ## Usalo come segnale complementare quando manca un nome reale L'analisi dei nomi utente può essere utile per dati provenienti da social network, community, giochi e profili creati dagli utenti stessi, quando il campo del nome è vuoto. Se disponi di una fonte più diretta e consentita, come un nome reale o un indirizzo email, usa l'endpoint corrispondente. - [Estrarre un nome e un'indicazione di genere da un indirizzo email](https://www.genderapi.io/it/blog/estrarre-nomi-da-indirizzi-email) - [Elaborare file Excel e CSV in batch](https://www.genderapi.io/it/blog/determining-gender-of-names-in-excel-csv-with-gender-api) ## Non trattare il risultato come un'identità verificata Non tutti i nickname contengono un nome reale, le associazioni culturali variano e la stessa espressione può avere significati diversi in lingue diverse. Se il segnale è insufficiente, accetta un risultato vuoto invece di trasformare dati deboli in una conclusione definitiva. Salva insieme i campi di confidenza e di origine della V2, misura le prestazioni con i tuoi dati e non basare su questo segnale alcuna decisione ad alto impatto per una singola persona, ad esempio in materia di lavoro, credito o salute. ## Salva separatamente i dati di origine e la previsione Conserva l'identificativo originale del record. L'API non apre alcun profilo, non verifica chi sia il titolare di un account e non conferma alcuna identità. Invia un contesto del paese solo quando disponi di un dato affidabile; non ricavarlo dal dominio o dalla lingua del sito. Invia il nome utente con type: username; non inviare l'URL di un profilo. La ricerca nel set di dati rimuove una @ iniziale, normalizza il testo e forma i candidati in base a separatori e cifre. Una richiesta standard può aggiungere un numero limitato di corrispondenze per prefisso e suffisso; forceToGenderize non usa questi frammenti aggiuntivi. Se più voci corrispondono, viene scelta quella con il numero di occorrenze registrate più alto. Usa type: email per gli indirizzi email e type: name per i nomi reali. | Input di esempio | Campo o opzione | Interpretazione | | --- | --- | --- | | @alice_smith | data.name / data.match | Conserva il nome utente originale; non trattare il frammento trovato come un nome verificato. | | prenses | forceToGenderize: true | Consente di interpretare un nickname privo di un nome reale. Può essere restituito un genere con data.name impostato a null; non inventare un nome per la persona. | | user47291 | data.result_status: unknown | Un input ambiguo o insufficiente può restare sconosciuto. Non è un motivo per ripetere automaticamente la richiesta. | ### Scegli la modalità di elaborazione e il costo in crediti Per una richiesta singola il valore predefinito è fallback, per gli elementi di un batch off. forceToGenderize è facoltativo per nomi, indirizzi email e nomi utente; in questo caso ometti ai_mode o usa fallback, perché l'opzione non può essere combinata con off e always. Anche i risultati unknown riusciti vengono addebitati. Per iniziare basta un saldo iniziale positivo; al termine dell'operazione il saldo può diventare negativo. | Opzione | Elaborazione | Costo per elemento riuscito | | --- | --- | --- | | options.ai_mode: off | Solo set di dati | 1 credito | | options.ai_mode: fallback | Prima il set di dati; se non viene determinato alcun genere, normale fallback IA | 1 credito in totale, IA inclusa | | options.ai_mode: always | Direttamente all'IA | 2 crediti | | forceToGenderize: true | Prima il set di dati, poi l'interpretazione del nickname senza richiedere un nome reale | 1 se basta il set di dati; 2 in totale se viene usata l'IA | ### Assegna opzioni proprie a ogni elemento di un batch Gli input di esempio non garantiscono una determinata previsione. Imposta GENDERAPI_API_KEY nell'ambiente del server e non inserire la chiave in codice pubblico lato client. V1 e V2 usano la stessa chiave dell'account e lo stesso saldo. Verifica la chiave con /api/v2/usage e controlla che meta.access.mode abbia il valore api_key. Scegli un linguaggio di programmazione. [Configura la tua chiave API](https://www.genderapi.io/it/docs/v2/authentication#environment-setup), poi esegui l'esempio sul tuo server. Ogni richiesta di previsione è una nuova operazione a pagamento, anche quando è un nuovo tentativo. Questi esempi non riprovano automaticamente. Controlla lo stato dell'addebito prima di inviare un'altra richiesta. ### Prima dell'esecuzione: accesso e gestione degli errori Esegui questi esempi sul tuo server. Imposta GENDERAPI_API_KEY nell'ambiente del processo con la tua chiave API esistente. Verifica che meta.access.mode sia api_key: una chiave non riconosciuta può portare alla prova IP. Per le risposte JSON con HTTP 4xx e 5xx, il corpo dell'errore viene conservato e l'esempio termina con un codice di uscita diverso da zero. Controlla code, action e meta.usage.billing_status prima di riprovare. Per le risposte batch con HTTP 200, controlla anche data o error di ogni elemento. **cURL** cURL 7.76+ in una shell POSIX. Esegui nel terminale. [Documentazione del runtime](https://curl.se/docs/manpage.html) ```bash curl --silent --show-error --fail-with-body --max-time 30 \ --request POST 'https://api.genderapi.io/api/v2/gender/batch' \ --header "Authorization: Bearer ${GENDERAPI_API_KEY:?Set GENDERAPI_API_KEY}" \ --header 'Content-Type: application/json' \ --data '{ "items": [ { "id": "profile-001", "type": "username", "value": "@alice_smith", "options": { "ai_mode": "off" } }, { "id": "profile-002", "type": "username", "value": "alexriver", "options": { "ai_mode": "fallback" } }, { "id": "profile-003", "type": "username", "value": "prenses", "country": "TR", "forceToGenderize": true } ] }' ``` **JavaScript / Node.js** Node.js 22+; fetch integrato. Salva come example.mjs ed esegui node example.mjs. [Documentazione del runtime](https://nodejs.org/api/globals.html#fetch) ```javascript // Server-side Node.js. Save as example.mjs. const apiKey = process.env.GENDERAPI_API_KEY; if (!apiKey) throw new Error("Set GENDERAPI_API_KEY"); const body = { "items": [ { "id": "profile-001", "type": "username", "value": "@alice_smith", "options": { "ai_mode": "off" } }, { "id": "profile-002", "type": "username", "value": "alexriver", "options": { "ai_mode": "fallback" } }, { "id": "profile-003", "type": "username", "value": "prenses", "country": "TR", "forceToGenderize": true } ] }; const response = await fetch("https://api.genderapi.io/api/v2/gender/batch", { method: "POST", headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json", }, body: JSON.stringify(body), signal: AbortSignal.timeout(30_000), redirect: "error", }); const raw = await response.text(); if (!(response.headers.get("content-type") ?? "").includes("json")) { throw new Error(`HTTP ${response.status}: expected JSON; request ID ${response.headers.get("x-request-id")}`); } const result = JSON.parse(raw); // Also accepts application/problem+json. if (!response.ok) { console.error(`HTTP ${response.status}`, result); process.exitCode = 1; // A retry is a new operation; inspect billing first. } else { console.log(JSON.stringify(result, null, 2)); // For batches, inspect every item: HTTP 200 may contain item errors. } ``` **Python** Python 3.10+; libreria standard. Salva come example.py ed esegui python3 example.py. [Documentazione del runtime](https://docs.python.org/3/library/urllib.request.html) ```python import json import os import sys import urllib.error import urllib.request api_key = os.environ.get("GENDERAPI_API_KEY") if not api_key: raise RuntimeError("Set GENDERAPI_API_KEY") body = json.loads("{\"items\":[{\"id\":\"profile-001\",\"type\":\"username\",\"value\":\"@alice_smith\",\"options\":{\"ai_mode\":\"off\"}},{\"id\":\"profile-002\",\"type\":\"username\",\"value\":\"alexriver\",\"options\":{\"ai_mode\":\"fallback\"}},{\"id\":\"profile-003\",\"type\":\"username\",\"value\":\"prenses\",\"country\":\"TR\",\"forceToGenderize\":true}]}") class NoRedirect(urllib.request.HTTPRedirectHandler): def redirect_request(self, req, fp, code, msg, headers, newurl): return None request = urllib.request.Request( "https://api.genderapi.io/api/v2/gender/batch", method="POST", data=json.dumps(body).encode("utf-8"), headers={ "Authorization": "Bearer " + api_key, "Content-Type": "application/json", }, ) opener = urllib.request.build_opener(NoRedirect()) try: response = opener.open(request, timeout=30) except urllib.error.HTTPError as error: response = error # Keep the Problem Details body on non-2xx responses. with response: status = response.status raw = response.read().decode("utf-8") if "json" not in response.headers.get("Content-Type", ""): raise RuntimeError(f"HTTP {status}: expected a JSON response") result = json.loads(raw) print(json.dumps(result, indent=2), file=sys.stderr if status >= 300 else sys.stdout) if not 200 <= status < 300: sys.exit(1) # Inspect code, action and billing before retrying. # For batches, inspect every item even when HTTP status is 200. ``` **PHP** PHP 8+ con l'estensione cURL. Salva come example.php ed esegui php example.php. [Documentazione del runtime](https://www.php.net/manual/en/book.curl.php) ```php 'POST', CURLOPT_RETURNTRANSFER => true, CURLOPT_FOLLOWLOCATION => false, CURLOPT_TIMEOUT => 30, CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . $apiKey, 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => json_encode($body, JSON_THROW_ON_ERROR), ]); $raw = curl_exec($ch); if ($raw === false) { throw new RuntimeException(curl_error($ch)); } $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); $contentType = curl_getinfo($ch, CURLINFO_CONTENT_TYPE) ?: ''; curl_close($ch); if (strpos($contentType, 'json') === false) { throw new RuntimeException("HTTP $status: expected a JSON response"); } $result = json_decode($raw, true, 512, JSON_THROW_ON_ERROR); $output = json_encode($result, JSON_PRETTY_PRINT | JSON_THROW_ON_ERROR) . PHP_EOL; if ($status < 200 || $status >= 300) { fwrite(STDERR, $output); // Preserve the Problem Details body. exit(1); } echo $output; // For batches, inspect every item; HTTP 200 can contain item errors. ``` **Java** Java 17+; client HTTP standard. Salva come GenderApiExample.java ed esegui java GenderApiExample.java. [Documentazione del runtime](https://docs.oracle.com/en/java/javase/17/docs/api/java.net.http/java/net/http/HttpClient.html) ```java import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.nio.charset.StandardCharsets; import java.time.Duration; public class GenderApiExample { private static String requiredEnv(String name) { String value = System.getenv(name); if (value == null || value.isBlank()) throw new IllegalStateException("Set " + name); return value; } public static void main(String[] args) throws Exception { String apiKey = requiredEnv("GENDERAPI_API_KEY"); String body = "{\"items\":[{\"id\":\"profile-001\",\"type\":\"username\",\"value\":\"@alice_smith\",\"options\":{\"ai_mode\":\"off\"}},{\"id\":\"profile-002\",\"type\":\"username\",\"value\":\"alexriver\",\"options\":{\"ai_mode\":\"fallback\"}},{\"id\":\"profile-003\",\"type\":\"username\",\"value\":\"prenses\",\"country\":\"TR\",\"forceToGenderize\":true}]}"; HttpClient client = HttpClient.newBuilder() .connectTimeout(Duration.ofSeconds(10)) .followRedirects(HttpClient.Redirect.NEVER) .build(); HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.genderapi.io/api/v2/gender/batch")) .timeout(Duration.ofSeconds(30)) .header("Authorization", "Bearer " + apiKey) .header("Content-Type", "application/json") .POST(HttpRequest.BodyPublishers.ofString(body, StandardCharsets.UTF_8)) .build(); HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8)); if (!response.headers().firstValue("content-type").orElse("").contains("json")) { throw new IllegalStateException("HTTP " + response.statusCode() + ": expected JSON"); } // JSON text; parse with your application's JSON library when integrating. if (response.statusCode() < 200 || response.statusCode() >= 300) { System.err.println(response.body()); // Includes Problem Details. System.exit(1); } System.out.println(response.body()); // For batches, inspect each item's data or error, including on HTTP 200. } } ``` **C# / .NET** Applicazione console .NET 8+. Usalo come Program.cs in un progetto console, poi esegui dotnet run. [Documentazione del runtime](https://learn.microsoft.com/en-us/dotnet/fundamentals/networking/http/httpclient) ```csharp using System; using System.Net.Http; using System.Net.Http.Headers; using System.Text; using System.Text.Json; string RequiredEnv(string name) => !string.IsNullOrWhiteSpace(Environment.GetEnvironmentVariable(name)) ? Environment.GetEnvironmentVariable(name)! : throw new InvalidOperationException($"Set {name}"); var apiKey = RequiredEnv("GENDERAPI_API_KEY"); using var handler = new HttpClientHandler { AllowAutoRedirect = false }; using var client = new HttpClient(handler) { Timeout = TimeSpan.FromSeconds(30) }; using var request = new HttpRequestMessage(HttpMethod.Post, "https://api.genderapi.io/api/v2/gender/batch"); request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", apiKey); request.Content = new StringContent("{\"items\":[{\"id\":\"profile-001\",\"type\":\"username\",\"value\":\"@alice_smith\",\"options\":{\"ai_mode\":\"off\"}},{\"id\":\"profile-002\",\"type\":\"username\",\"value\":\"alexriver\",\"options\":{\"ai_mode\":\"fallback\"}},{\"id\":\"profile-003\",\"type\":\"username\",\"value\":\"prenses\",\"country\":\"TR\",\"forceToGenderize\":true}]}", Encoding.UTF8, "application/json"); using var response = await client.SendAsync(request); var raw = await response.Content.ReadAsStringAsync(); if (!(response.Content.Headers.ContentType?.MediaType?.Contains("json") ?? false)) throw new InvalidOperationException($"HTTP {(int)response.StatusCode}: expected JSON"); using var result = JsonDocument.Parse(raw); if (!response.IsSuccessStatusCode) { Console.Error.WriteLine(result.RootElement); // Preserve Problem Details. Environment.ExitCode = 1; } else { Console.WriteLine(result.RootElement); // For batches, inspect every item even on HTTP 200. } ``` **Go** Go 1.22+; libreria standard. Salva come main.go ed esegui go run main.go. [Documentazione del runtime](https://pkg.go.dev/net/http) ```go package main import ( "encoding/json" "fmt" "io" "net/http" "os" "strings" "time" ) func requiredEnv(name string) string { value := os.Getenv(name) if value == "" { panic("Set " + name) } return value } func run() error { apiKey := requiredEnv("GENDERAPI_API_KEY") body := "{\"items\":[{\"id\":\"profile-001\",\"type\":\"username\",\"value\":\"@alice_smith\",\"options\":{\"ai_mode\":\"off\"}},{\"id\":\"profile-002\",\"type\":\"username\",\"value\":\"alexriver\",\"options\":{\"ai_mode\":\"fallback\"}},{\"id\":\"profile-003\",\"type\":\"username\",\"value\":\"prenses\",\"country\":\"TR\",\"forceToGenderize\":true}]}" request, err := http.NewRequest("POST", "https://api.genderapi.io/api/v2/gender/batch", strings.NewReader(body)) if err != nil { return err } request.Header.Set("Authorization", "Bearer " + apiKey) request.Header.Set("Content-Type", "application/json") client := &http.Client{ Timeout: 30 * time.Second, CheckRedirect: func(req *http.Request, via []*http.Request) error { return http.ErrUseLastResponse }, } response, err := client.Do(request) if err != nil { return err } defer response.Body.Close() raw, err := io.ReadAll(response.Body) if err != nil { return err } if !strings.Contains(response.Header.Get("Content-Type"), "json") || !json.Valid(raw) { return fmt.Errorf("HTTP %d: expected a JSON response", response.StatusCode) } if response.StatusCode < 200 || response.StatusCode >= 300 { return fmt.Errorf("HTTP %d: %s", response.StatusCode, raw) } fmt.Println(string(raw)) // For batches, inspect every item even on HTTP 200. return nil } func main() { if err := run(); err != nil { fmt.Fprintln(os.Stderr, err) // Keep Problem Details for error handling. os.Exit(1) } } ``` - [Guida a errori e nuovi tentativi →](https://www.genderapi.io/it/docs/v2/errors-and-retries) ### Gestisci i risultati degli elenchi e le richieste ripetute POST /api/v2/gender/batch accetta fino a 50 elementi con una chiave API e 10 con la prova IP. Assegna a ogni elemento valori propri per type, value e options. Se vuoi usare il normale fallback IA, indica fallback esplicitamente in ogni elemento. id deve essere univoco all'interno del batch; index parte da zero all'interno del batch inviato. Salva separatamente i tuoi identificativi di lavoro e di riga di origine. HTTP 200 non significa che tutti gli elementi siano riusciti. Gestisci separatamente i risultati identified, unknown ed error; meta.summary.succeeded conta sia identified sia unknown. Valuta insieme data.gender, source, confidence_kind, confidence, match e reason. Non trattare come equivalenti un punteggio dell'IA e una frequenza nel set di dati. Se meta.usage.billing_status ha il valore confirmed, ripeti solo gli errori operativi che consentono una nuova richiesta. Se lo stato è unconfirmed o la risposta è andata persa, fermati e verifica l'addebito. Inviare di nuovo lo stesso elemento, anche un risultato unknown riuscito, crea una nuova operazione a pagamento; non inviare mai di nuovo l'intero elenco alla cieca. [Contratto delle richieste batch](https://www.genderapi.io/it/docs/v2/batch) · [Campi della risposta](https://www.genderapi.io/it/docs/v2/responses) · [Opzioni IA](https://www.genderapi.io/it/docs/v2/ai-options) · [Valutare accuratezza e confidenza](https://www.genderapi.io/it/accuracy-methodology) · [Informativa sulla privacy](https://www.genderapi.io/it/privacy-policy) I componenti aggiuntivi per Excel e Google Sheets e le altre integrazioni pronte all'uso possono usare una propria connessione e un proprio formato dei risultati. Non dare per scontato che il loro output segua questo schema JSON V2; consulta la guida aggiornata della rispettiva integrazione. ## Il genere da un nome utente o da un nickname ### È possibile determinare il genere da un nome utente? Se attivi forceToGenderize nella V2, viene controllato prima il set di dati; se non viene determinato alcun genere, l'IA può interpretare il nickname senza che serva un nome reale. Il risultato può restare unknown e non è un'identità verificata. Il normale fallback IA richiede invece un nome reale utilizzabile. ### Quali nomi utente danno i risultati più utili? Un segnale più utile può venire da valori che contengono un nome reale, una forma di nickname riconoscibile o un chiaro elemento nominale. Sequenze casuali di caratteri e nomi di marchi possono non dare alcun risultato. ### Posso analizzare un singolo nome utente tramite API? Sì. L'endpoint singolo analizza un elemento. Per più elementi è disponibile un endpoint dedicato alle richieste batch. ### Posso importare un file Excel o CSV? Sì. Nello strumento per i file puoi scegliere la colonna con i nomi utente o i nomi visualizzati e attivare l'interpretazione dei nickname. ### Perché devo salvare insieme i campi di confidenza e di origine della V2? Nella V2 data.confidence è compreso tra 0 e 1. Valuta il valore insieme a source e confidence_kind, perché un punteggio dell'IA e una frequenza nel set di dati sono misure diverse. Conserva i risultati unknown e il campo reason. ### Il risultato è adatto alla segmentazione? Può servire come segnale complementare in analisi aggregate e nell'arricchimento dei dati, ma non dovrebbe decidere da solo questioni ad alto impatto per una singola persona né stabilirne l'identità. ### Posso provare il servizio gratuitamente? I nuovi account GenderAPI includono 200 crediti API gratuiti al giorno, che puoi usare per provare campioni rappresentativi tramite API o file.