# Determinare il genere da nomi giapponesi

> Prova i nomi giapponesi con GenderAPI.io V2. Scopri le parti brevi in kanji, le possibili letture, il contesto JP, il fallback IA e come gestire i risultati sconosciuti.

Canonical HTML: https://www.genderapi.io/it/determine-gender-from-japanese-names

Last reviewed: 2026-09-28

## Non nascondere l'incertezza su grafia e lettura

Invia la grafia presente nel record della tua applicazione: in kanji, in kana o in caratteri latini. V2 accetta Unicode, ma non garantisce che letture o grafie diverse portino a una chiave equivalente nel set di dati. La ricerca non converte i kanji in una lettura e non separa il cognome dal nome proprio quando il nome completo è scritto senza spazi.

Per i caratteri giapponesi comuni degli esempi, l'attuale filtro dei candidati salta le parti di uno o due caratteri. Nel valore della demo 葵 高橋 vengono saltate entrambe le parti separate da uno spazio. Il normale fallback può inviare all'IA l'intero valore originale; una richiesta basata solo sul set di dati mantiene il risultato sconosciuto con reason: no_name_candidate.

Se rimuovi lo spazio si ottiene un candidato diverso, non una soluzione affidabile al problema della suddivisione. Conserva l'input effettivo e verifica le informazioni source e match restituite. Una possibile lettura, una convenzione sui nomi o il contesto JP non confermano l'identità di genere di una persona.

| Esempio di input | Che cosa rappresenta | Che cosa controllare |
| --- | --- | --- |
| `葵 高橋` | Parti brevi separate | Nessuna delle due parti raggiunge la lunghezza minima richiesta dal filtro per questi caratteri. Il fallback IA può comunque interpretare il valore originale. |
| `高橋葵` | Nome completo senza spazi | Un solo candidato; la ricerca non stabilisce dove finisce il cognome. |
| `あおい` | Esempio in kana di tre caratteri | Può diventare un candidato grazie alla sua lunghezza, ma ciò non significa che esista una voce né che venga restituito un genere. |
| `Aoi Takahashi` | Input in caratteri latini | Le parti separate possono essere considerate. Ciò non stabilisce un'unica grafia originale e non garantisce che venga scelto il nome proprio previsto. |

## Scegliere consapevolmente il contesto del paese JP

La demo invia country: JP (Giappone). L'API non sceglie il paese in base all'alfabeto in cui è scritto il nome. Nella tua integrazione usa un contesto del paese noto e pertinente oppure ometti country. Non trasformare questo valore di esempio in un valore predefinito per tutti i record.

Per ogni candidato, la ricerca sceglie la voce specifica del paese, se esiste, e altrimenti considera la voce globale. Seleziona poi il candidato disponibile con il conteggio totale memorizzato più alto. L'ambito effettivo della corrispondenza è indicato in data.match.scope e data.match.country. Una voce specifica del paese con frequenze in parità non viene sostituita automaticamente dal risultato globale; se il fallback è attivo, può essere usata invece l'IA.

data.input.country descrive il contesto inviato nella richiesta. data.country e data.country_source descrivono l'associazione con un paese restituita e la sua origine. Sono campi diversi e non indicano né la cittadinanza né l'origine etnica né il luogo di residenza.

- [Contesto del paese e corrispondenze](https://www.genderapi.io/it/docs/v2/gender-from-name#country-evidence-workflow)

## Inviare una richiesta V2 per un nome dalla tua applicazione

Imposta GENDERAPI_API_KEY sulla tua chiave esistente ed esegui l'esempio sul tuo server. La richiesta attiva esplicitamente il normale fallback IA. Mostra il formato della richiesta, non un'accuratezza misurata o una copertura confermata. Per una previsione basata solo sul set di dati imposta options.ai_mode: off.

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.

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.

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.

**cURL**

cURL 7.76+ in una shell POSIX. Esegui nel terminale.

```bash
curl --silent --show-error --fail-with-body --max-time 30 \
  --request POST 'https://api.genderapi.io/api/v2/gender' \
  --header "Authorization: Bearer ${GENDERAPI_API_KEY:?Set GENDERAPI_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "name",
  "value": "葵 高橋",
  "country": "JP",
  "options": {
    "ai_mode": "fallback"
  }
}'
```

**JavaScript / Node.js**

Node.js 22+; fetch integrato. Salva come example.mjs ed esegui node example.mjs.

```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 = {
  "type": "name",
  "value": "葵 高橋",
  "country": "JP",
  "options": {
    "ai_mode": "fallback"
  }
};

const response = await fetch("https://api.genderapi.io/api/v2/gender", {
  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.

```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("{\"type\":\"name\",\"value\":\"葵 高橋\",\"country\":\"JP\",\"options\":{\"ai_mode\":\"fallback\"}}")

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",
    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.

```php
<?php
$apiKey = getenv('GENDERAPI_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('Set GENDERAPI_API_KEY');
}
$body = json_decode('{"type":"name","value":"葵 高橋","country":"JP","options":{"ai_mode":"fallback"}}', true, 512, JSON_THROW_ON_ERROR);

$ch = curl_init('https://api.genderapi.io/api/v2/gender');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => '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.

```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 = "{\"type\":\"name\",\"value\":\"葵 高橋\",\"country\":\"JP\",\"options\":{\"ai_mode\":\"fallback\"}}";
        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"))
            .timeout(Duration.ofSeconds(30))
            .header("Authorization", "Bearer " + apiKey)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body, StandardCharsets.UTF_8))
            .build();
        HttpResponse<String> 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.

```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");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", apiKey);
request.Content = new StringContent("{\"type\":\"name\",\"value\":\"葵 高橋\",\"country\":\"JP\",\"options\":{\"ai_mode\":\"fallback\"}}", 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.

```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 := "{\"type\":\"name\",\"value\":\"葵 高橋\",\"country\":\"JP\",\"options\":{\"ai_mode\":\"fallback\"}}"
    request, err := http.NewRequest("POST", "https://api.genderapi.io/api/v2/gender", 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)
    }
}
```

- [Parametri delle richieste per i nomi](https://www.genderapi.io/it/docs/v2/gender-from-name)
- [Configurare la chiave API](https://www.genderapi.io/it/docs/v2/authentication)

## Salvare il risultato insieme alle evidenze

Un'associazione dedotta non è il genere dichiarato da una persona. Salva separatamente l'input originale, le evidenze restituite e ciò che la persona ha dichiarato. Un risultato sconosciuto è un risultato valido e non dovrebbe diventare una categoria indovinata nella tua applicazione.

| Campo | Utilizzo |
| --- | --- |
| `data.gender / data.result_status` | Usa male o female solo con identified. In caso di risultato sconosciuto conserva il valore JSON null nativo. |
| `data.name / data.match` | Verifica il nome restituito e il candidato selezionato. Una corrispondenza su una sottostringa non dimostra che l'input appartenga a una persona con quel nome. |
| `data.confidence / data.confidence_kind` | La confidenza è su una scala da 0 a 1 oppure è null. observed_frequency si basa su frequenze memorizzate; model_reported è un valore fornito dall'IA. Valuta le soglie separatamente per ciascun tipo. |
| `data.source / data.sample_count` | Distingui tra dataset, ai e none. I risultati dell'IA non hanno una dimensione del campione memorizzata. Una dimensione del campione non è un valore di accuratezza misurato. |
| `meta.access.mode` | In un'integrazione con account verifica che venga riportato api_key. Le chiavi mancanti o non riconosciute possono invece usare la prova IP condivisa. |
| `meta.usage` | Leggi charged_credits e billing_status. Un risultato sconosciuto riuscito viene addebitato. Una risposta persa non dimostra che la richiesta sia stata gratuita. |

- [Campi della risposta e risultati sconosciuti](https://www.genderapi.io/it/docs/v2/responses)
- [Accuratezza e confidenza spiegate](https://www.genderapi.io/it/accuracy-methodology)
- [Fonti dei dati e profilo datato del database](https://www.genderapi.io/it/data-provenance)

## Decidere quando usare l'IA

forceToGenderize è facoltativo per nomi, indirizzi email e nomi utente. Quando è attivo, ometti ai_mode o usa fallback; off e always non possono essere combinati con questa opzione e restituiscono 422. Un saldo iniziale positivo basta per avviare una richiesta, anche se l'addebito finale rende il saldo negativo.

La modalità nickname può restituire un genere insieme a name: null. Può anche dare un risultato sconosciuto. Né il normale fallback IA né l'interpretazione dei nickname garantiscono una risposta corretta o un valore diverso da null.

| Opzione della richiesta | Comportamento | Crediti per una ricerca riuscita |
| --- | --- | --- |
| options.ai_mode: off | Usa solo il set di dati. | 1, anche per un risultato sconosciuto |
| options.ai_mode: fallback | Consulta prima il set di dati e poi usa la normale IA se non viene restituito un genere. È il valore predefinito per le richieste singole. | 1 in totale, fallback IA incluso |
| options.ai_mode: always | Usa direttamente l'IA. | 2 |
| forceToGenderize: true | Consulta prima il set di dati e poi lascia che l'IA interpreti un nickname personale o un alias, anche senza un vero nome proprio. | 1 per un risultato trovato nel set di dati; 2 in totale se viene usata l'IA |

- [Opzioni IA e interpretazione dei nickname](https://www.genderapi.io/it/docs/v2/ai-options)
- [Crediti e utilizzo](https://www.genderapi.io/it/docs/v2/credits-and-usage)

## Elaborare un elenco di nomi senza perdere il contesto

Invia fino a 50 elementi con una chiave API o 10 con la prova IP tramite POST /api/v2/gender/batch. Assegna a ogni elemento un id univoco e conserva il valore originale di ogni riga. Ogni elemento può avere opzioni proprie per il paese e l'IA; ometti il paese quando non è noto.

A differenza delle richieste singole, che usano il fallback per impostazione predefinita, gli elementi di un batch usano per impostazione predefinita solo il set di dati. Imposta options.ai_mode: fallback per ogni elemento che richiede l'IA. Controlla ogni risultato, anche dopo HTTP 200, conserva i risultati sconosciuti e verifica errori e addebito prima di un nuovo invio. Ogni elemento normale riuscito costa 1 credito; una richiesta HTTP batch non corrisponde a un credito per previsione.

- [Esempi di batch ed errori parziali](https://www.genderapi.io/it/docs/v2/batch#batch-application-workflow)
- [Gestire i risultati sconosciuti nell'applicazione](https://www.genderapi.io/it/docs/v2/responses#application-decisions)

## Sapere che cosa invii

La demo in tempo reale invia il valore inserito a GenderAPI.io solo quando lo invii tu. Se viene usata l'IA, type, value e il contesto del paese inviati vengono trasmessi al servizio configurato per le previsioni. Per una previsione basata solo sul set di dati, nella tua integrazione imposta options.ai_mode: off senza forceToGenderize.

L'informativa sulla privacy, l'accordo sul trattamento dei dati e l'elenco dei sub-responsabili descrivono le condizioni di trattamento pubblicate. Un risultato è un'associazione dedotta e ciò che una persona dichiara ha la precedenza. Non usarlo come base per decisioni con conseguenze rilevanti per una persona.

- [Informativa sulla privacy](https://www.genderapi.io/it/privacy-policy)
- [Accordo sul trattamento dei dati](https://www.genderapi.io/it/data-processing-agreement)
- [Sub-responsabili del trattamento](https://www.genderapi.io/it/subprocessors)

## Perché l'esempio 葵 高橋 richiede il fallback IA?

Entrambe le parti sono troppo brevi per l'attuale filtro dei candidati. Una richiesta basata solo sul set di dati restituisce quindi unknown con reason: no_name_candidate. Il fallback può inviare all'IA l'intero valore originale, ma una risposta dell'IA non è garantita.

## V2 stabilisce la lettura esatta di un nome giapponese?

V2 non offre un servizio verificato per stabilire le letture. La ricerca non converte i kanji in kana e non garantisce un risultato equivalente per una grafia romanizzata. Conserva l'input e verifica le evidenze restituite su cui si basa il risultato.

## È stata pubblicata una valutazione indipendente dell'accuratezza per questo gruppo di nomi?

Questa pagina non pubblica una valutazione di questo tipo. L'accettazione dell'input, la visualizzazione delle frequenze memorizzate o la restituzione di un valore di confidenza non sono una misurazione indipendente dell'accuratezza. La metodologia indica quali dati sono disponibili e quali misurazioni non sono ancora state pubblicate.

## Un risultato senza previsione consuma crediti?

Un risultato sconosciuto riuscito viene addebitato. La modalità normale con il set di dati o con il fallback costa 1 credito in totale. Con forceToGenderize la richiesta costa 1 credito se il risultato proviene dal set di dati, oppure 2 in totale se viene usata l'IA, anche in caso di risultato sconosciuto. Per gli errori valgono regole di addebito separate; controlla meta.usage.