# Determinare il genere da nomi arabi

> Prova i nomi in alfabeto arabo con GenderAPI.io V2. Scopri come funzionano segni diacritici, corrispondenza dei nomi completi, contesto del paese, fallback IA e risultati sconosciuti prima dell'integrazione.

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

Last reviewed: 2026-09-28

## Conservare la grafia araba e verificare il nome trovato

Invia il nome nella sua grafia Unicode originale. Il campo di input dello strumento mostra il testo arabo da destra a sinistra, mentre questa guida in italiano e il JSON della risposta si leggono da sinistra a destra. Non è necessario traslitterare prima il nome in caratteri latini. Il fatto che l'API accetti questa grafia non garantisce che il set di dati contenga una voce corrispondente.

La ricerca nel set di dati applica la normalizzazione Unicode NFKC e suddivide il testo in parti. Non prevede una regola generale che rimuova i segni diacritici arabi o che renda equivalenti grafie diverse. I segni vocalici e altre differenze di grafia possono quindi influire sulla voce memorizzata che viene trovata. Conserva il valore originale invece di trattare tacitamente tutte le varianti come identiche.

Un nome completo può produrre più candidati. Viene scelta la voce disponibile con il conteggio totale memorizzato più alto, quindi la prima parola non è necessariamente il nome proprio restituito. Verifica data.name e data.match.name prima di usare un risultato per arricchire un record.

| Esempio di input | Che cosa rappresenta | Che cosa controllare |
| --- | --- | --- |
| `ليلى الخطيب` | Esempio di nome completo | Più parti possono essere considerate nella ricerca. Verifica la corrispondenza selezionata; l'esempio non anticipa un risultato in tempo reale. |
| `ليلى / لَيْلَى` | Grafia senza e con segni vocalici | Invia la grafia effettiva. Non è garantito che le due stringhe portino alla stessa voce memorizzata. |
| `Layla / Leila` | Grafie in caratteri latini | Sono valori di input distinti. V2 non garantisce un'equivalenza automatica tra traslitterazioni. |
| `country: SA` | Contesto di esempio: Arabia Saudita | Il contesto non è un valore predefinito per tutte le comunità di lingua araba. Ometti country quando il paese non è noto. |

## Scegliere consapevolmente il contesto del paese SA

La demo invia country: SA (Arabia Saudita). 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": "SA",
  "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": "SA",
  "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\":\"SA\",\"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":"SA","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\":\"SA\",\"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\":\"SA\",\"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\":\"SA\",\"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)

## V2 accetta nomi arabi con segni diacritici?

V2 accetta nomi in Unicode, compreso il testo in alfabeto arabo. La normalizzazione del set di dati in genere non rimuove i segni vocalici arabi. Le grafie con e senza segni vocalici possono quindi produrre corrispondenze diverse o un risultato sconosciuto.

## Lo strumento determina la nazionalità di una persona di lingua araba?

No. SA è il contesto del paese scelto esplicitamente per questa dimostrazione. L'alfabeto, un'associazione del nome o un campo paese restituito non indicano né la nazionalità né il luogo di residenza.

## È 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.