Αναφορά REST API

Γρήγορη έναρξη

Δημιουργήστε ένα κλειδί στον πίνακα ελέγχου σας, μετά στείλτε το πρώτο αίτημά σας. Δεν απαιτείται SDK.

curl "https://namegender.com/api/v1/gender?name=Ay%C5%9Fe&country=TR" \
  -H "Authorization: Bearer YOUR_API_KEY"

<?php

$query = http_build_query(['name' => 'Ayşe', 'country' => 'TR']);

$ch = curl_init('https://namegender.com/api/v1/gender?' . $query);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer YOUR_API_KEY'],
]);

$result = json_decode(curl_exec($ch), true);

echo $result['gender'];       // female
echo $result['probability'];  // 100

const params = new URLSearchParams({ name: 'Ayşe', country: 'TR' });

const response = await fetch(`https://namegender.com/api/v1/gender?${params}`, {
  headers: { Authorization: 'Bearer YOUR_API_KEY' },
});

const result = await response.json();

console.log(result.gender);       // "female"
console.log(result.probability);  // 100

import requests

response = requests.get(
    "https://namegender.com/api/v1/gender",
    params={"name": "Ayşe", "country": "TR"},
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)

result = response.json()
print(result["gender"])       # female
print(result["probability"])  # 100

require "net/http"
require "json"

uri = URI("https://namegender.com/api/v1/gender")
uri.query = URI.encode_www_form(name: "Ayşe", country: "TR")

request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer YOUR_API_KEY"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts JSON.parse(response.body)["gender"]   # female

req, _ := http.NewRequest("GET", "https://namegender.com/api/v1/gender?name=Ay%C5%9Fe&country=TR", nil)
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")

resp, err := http.DefaultClient.Do(req)
if err != nil {
    log.Fatal(err)
}
defer resp.Body.Close()

var result struct {
    Gender      string `json:"gender"`
    Probability int    `json:"probability"`
}
json.NewDecoder(resp.Body).Decode(&result)

fmt.Println(result.Gender)   // female

Κάθε endpoint επιστρέφει το ίδιο σχήμα, οπότε μπορείτε να αλλάξετε εισόδους χωρίς να αλλάξετε τον κώδικα ανάλυσής σας.

Έλεγχος ταυτότητας

Κάθε αίτημα μεταφέρει το API key σας σε μια κεφαλίδα. Χρησιμοποιήστε από προεπιλογή το Authorization: Bearer, ή το X-Api-Key όταν ο HTTP client σας δεσμεύει την κεφαλίδα Authorization για κάτι άλλο. Ένα key που τοποθετείται στο URL απορρίπτεται: τα URL αντιγράφονται σε logs proxy, εργαλεία analytics και στο ιστορικό του περιηγητή.

Authorization: Bearer ng_live_xxxxxxxxxxxx

X-Api-Key: ng_live_xxxxxxxxxxxx

Μπορείτε να περιορίσετε ένα κλειδί σε συγκεκριμένες διευθύνσεις IP από τον πίνακα ελέγχου.

Βιβλιοθήκες πελάτη

Λεπτά περιτυλίγματα πάνω από το REST API. Στέλνουν το κλειδί σας, δημιουργούν κάθε αίτημα και μετατρέπουν τις αποκρίσεις σφάλματος σε εξαιρέσεις.

npm install namegender

npm install -g namegender

composer require namegender/namegender

pip install namegender-client

gem install namegender

<repository>
  <id>jitpack.io</id>
  <url>https://jitpack.io</url>
</repository>

<dependency>
  <groupId>com.github.anpekesen</groupId>
  <artifactId>namegender-java</artifactId>
  <version>v0.9.0</version>
</dependency>

dotnet add package NameGender --version 0.6.0

go get github.com/anpekesen/namegender-go@v0.7.0

remotes::install_github('anpekesen/namegender-r', ref = 'v0.7.0')

Install-Module NameGender

cargo add namegender

Δεν χρειάζεστε κάποια. Το API είναι λίγα μόνο απλά JSON endpoints· μια βιβλιοθήκη σας εξοικονομεί ένα απόγευμα, όχι ένα έργο. Αν η γλώσσα σας δεν αναφέρεται, το REST reference έχει παραδείγματα αντιγραφής-επικόλλησης.

Βοηθοί AI (MCP)

Χρησιμοποιήστε το NameGender από το Claude, το Cursor και οποιοδήποτε άλλο πρόγραμμα-πελάτη υποστηρίζει το Model Context Protocol. Ρωτήστε τον βοηθό για μια λίστα ονομάτων και θα καλέσει το API για εσάς, με τα τεκμήρια δίπλα σε κάθε απάντηση.

claude mcp add namegender -e NAMEGENDER_API_KEY=ng_live_... -- npx -y namegender-mcp

{
    "mcpServers": {
        "namegender": {
            "command": "npx",
            "args": [
                "-y",
                "namegender-mcp"
            ],
            "env": {
                "NAMEGENDER_API_KEY": "ng_live_..."
            }
        }
    }
}

Εργαλεία

gender_from_name

Φύλο από μικρό ή πλήρες όνομα.

gender_from_email

Διαβάζει το όνομα σε μια διεύθυνση email· διευθύνσεις ρόλων όπως info@ επιστρέφουν άγνωστο.

gender_from_username

Διαβάζει το όνομα σε ένα όνομα χρήστη ή handle.

gender_bulk

Έως 100 τιμές σε ένα αίτημα, με σύνοψη του ποσοστού αντιστοίχισης.

name_countries

Χώρες όπου έχει καταγραφεί ένα όνομα. Δεν αποτελεί ισχυρισμό για την προέλευση.

salutation

Η εναρκτήρια γραμμή μιας επιστολής στη γλώσσα της επιστολής· η ουδέτερη μορφή όταν το φύλο δεν είναι βέβαιο.

name_check

Αν ένα όνομα που πληκτρολογήθηκε σε φόρμα μοιάζει πραγματικό, με τους λόγους. Δεν χαρακτηρίζει ποτέ ένα όνομα ψεύτικο.

age_from_name

Διάμεση ηλικία και ηλικιακά εύρη των ανθρώπων με ένα μικρό όνομα στις Ηνωμένες Πολιτείες, τη Γαλλία και τη Νορβηγία.

account_status

Υπόλοιπο credits και η σημερινή δωρεάν ποσόστωση.

Κάθε αναζήτηση χρησιμοποιεί credits από τον λογαριασμό στον οποίο ανήκει το κλειδί, ακριβώς όπως μια άμεση κλήση API. Καταχωρισμένο στο επίσημο μητρώο MCP ως io.github.anpekesen/namegender. Πακέτο npm · Πηγαίος κώδικας

Φύλο από όνομα

Δέχεται ένα όνομα ή ένα πλήρες όνομα. Οι τίτλοι, τα μεσαία ονόματα και τα επώνυμα αφαιρούνται πριν την αναζήτηση, οπότε "Dr. Ayşe Yılmaz" και "Ayşe" δίνουν την ίδια απάντηση.

curl "https://namegender.com/api/v1/gender?name=Jordan" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "credits_charged": 1,
  "credits_remaining": 49999,
  "request_id": "req_4b7e0c2d9a1f6358",
  "query": "Jordan",
  "name": "Jordan",
  "first_name": "Jordan",
  "middle_name": null,
  "last_name": null,
  "name_type": "personal",
  "gender": "male",
  "country": null,
  "sample_size": 62240,
  "probability": 84,
  "took_ms": 1,
  "confidence": "high",
  "source": "db",
  "matched_as": null
}

Φύλο από email

Εξάγει το όνομα από το τοπικό μέρος της διεύθυνσης, κατόπιν ταξινομεί αυτό. "ayse.yilmaz84@example.com" αναλύεται σε Ayşe.

Το best_guess εφαρμόζεται στο μικρό όνομα που διαβάζεται από τη διεύθυνση, όχι στην ίδια τη διεύθυνση. Όταν δεν μπορεί να διαβαστεί μικρό όνομα, δεν υπάρχει τίποτα να επιβληθεί και το gender παραμένει null. Έχετε υπόψη ότι μια επιβεβλημένη απάντηση εδώ στηρίζεται σε μια εξαγωγή που μπορεί η ίδια να είναι λανθασμένη.

curl "https://namegender.com/api/v1/gender/email?email=ayse.yilmaz84%40example.com" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "credits_charged": 1,
  "credits_remaining": 49998,
  "query": "ayse.yilmaz84@example.com",
  "name": "Ayse",
  "gender": "female",
  "sample_size": 655,
  "probability": 100,
  "took_ms": 1,
  "confidence": "high",
  "source": "db"
}

Φύλο από όνομα χρήστη

Χειρίζεται camelCase, snake_case, αριθμούς στο τέλος και σήματα @ στην αρχή. "AyseYilmaz84" αναλύεται σε Ayşe.

curl "https://namegender.com/api/v1/gender/username?username=AyseYilmaz84" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "credits_charged": 1,
  "credits_remaining": 49997,
  "query": "AyseYilmaz84",
  "name": "Ayse",
  "gender": "female",
  "sample_size": 655,
  "probability": 100,
  "took_ms": 1,
  "confidence": "high",
  "source": "db"
}

Μαζικό αίτημα

Στείλτε έως 100 ονόματα σε ένα αίτημα. Χρησιμοποιήστε αυτό αντί για βρόχο: ένα μαζικό κάλεσμα για 100 ονόματα είναι ένα μόνο round trip και μια μόνο αναζήτηση χωρίς διπλότυπα.

curl -X POST "https://namegender.com/api/v1/gender/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"names": ["Ayşe", "Mehmet", "Priya", "Wei"]}'

<?php

$ch = curl_init('https://namegender.com/api/v1/gender/bulk');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer YOUR_API_KEY',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'names' => ['Ayşe', 'Mehmet', 'Priya', 'Wei'],
    ]),
]);

$data = json_decode(curl_exec($ch), true);

foreach ($data['results'] as $row) {
    printf("%-8s %-7s %d%%\n", $row['query'], $row['gender'] ?? '?', $row['probability']);
}

const response = await fetch('https://namegender.com/api/v1/gender/bulk', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ names: ['Ayşe', 'Mehmet', 'Priya', 'Wei'] }),
});

const { results, summary } = await response.json();

console.log(summary.match_rate);   // 100
results.forEach(r => console.log(r.query, r.gender, r.probability));

import requests

response = requests.post(
    "https://namegender.com/api/v1/gender/bulk",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"names": ["Ayşe", "Mehmet", "Priya", "Wei"]},
)

data = response.json()
print(data["summary"]["match_rate"])   # 100

for row in data["results"]:
    print(row["query"], row["gender"], row["probability"])

{
  "credits_charged": 4,
  "credits_remaining": 49995,
  "request_id": "req_71d0a9e3c5b24f86",
  "took_ms": 2,
  "summary": {
    "total": 4,
    "identified": 4,
    "unknown": 0,
    "match_rate": 100
  },
  "results": [
    { "query": "Ayşe",   "gender": "female", "probability": 100, "sample_size":  655, "confidence": "high", "source": "db" },
    { "query": "Mehmet", "gender": "male",   "probability": 100, "sample_size": 1130, "confidence": "high", "source": "db" },
    { "query": "Priya",  "gender": "female", "probability": 100, "sample_size": 2993, "confidence": "high", "source": "db" },
    { "query": "Wei",    "gender": "male",   "probability":  86, "sample_size":  136, "confidence": "high", "source": "db" }
  ]
}

Τα αποτελέσματα έρχονται με την ίδια σειρά που τα στείλατε. Τα credit χρεώνονται ανά όνομα, και ολόκληρο το αίτημα απορρίπτεται πριν από οποιοδήποτε έργο εάν το υπόλοιπό σας είναι ανεπαρκές, οπότε ποτέ δεν λαμβάνετε μερικώς επεξεργασμένη παρτίδα.

Το ρόφημα σύνοψης σας ενημερώνει για την αναλογία αντιστοίχισης με μια ματιά, ώστε να μπορείτε να αποφασίσετε εάν η είσοδος χρειάζεται καθαρισμό πριν επεξεργαστείτε το υπόλοιπο.

Εργασίες αρχείων

Ανεβάστε ένα αρχείο CSV ή XLSX έως 100 MB και 1.000.000 γραμμές και λάβετέ το πίσω με στήλες φύλου σε κάθε γραμμή. Μία μονάδα ανά γραμμή, χρεώνεται μόνο αν η εργασία ολοκληρωθεί.

1. 1. POST /batches Στείλτε το αρχείο και το name_column. Η εργασία μπαίνει αμέσως στην ουρά.
2. 2. GET /batches/{id} Διαβάζετε την εργασία μέχρι το status να γίνει completed ή failed. Το poll_after_seconds δείχνει πόσο να περιμένετε ανάμεσα στις αναγνώσεις.
3. 3. GET /batches/{id}/result Κατεβάστε το αποτέλεσμα. Επιστρέφει στη μορφή που ανεβάσατε.

# 1. Upload and start
curl -X POST "https://namegender.com/api/v1/batches" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: 6f1c2e0a-customers-2026-09" \
  -F "file=@customers.csv" \
  -F "name_column=first_name" \
  -F "country_column=country"

# 2. Poll until status is completed or failed
curl "https://namegender.com/api/v1/batches/B-7K2M9QX4TA" \
  -H "Authorization: Bearer YOUR_API_KEY"

# 3. Download the result
curl "https://namegender.com/api/v1/batches/B-7K2M9QX4TA/result" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o customers-gender.csv

import { NameGender } from 'namegender';
import { openAsBlob } from 'node:fs';
import { writeFile } from 'node:fs/promises';

const client = new NameGender(process.env.NAMEGENDER_API_KEY);

const job = await client.batches.create(await openAsBlob('customers.csv'), {
  filename: 'customers.csv',
  name_column: 'first_name',
  country_column: 'country',
});

const done = await client.batches.wait(job.id);
if (done.status === 'failed') throw new Error(done.error.code);

const file = await client.batches.download(done.id);
await writeFile('customers-gender.csv', Buffer.from(await file.arrayBuffer()));

from namegender import NameGender

client = NameGender("YOUR_API_KEY")

job = client.batches.create("customers.csv", name_column="first_name", country_column="country")

done = client.batches.wait(job["id"])
if done["status"] == "failed":
    raise RuntimeError(done["error"]["code"])

client.batches.download(done["id"], "customers-gender.csv")

{
  "id": "B-7K2M9QX4TA",
  "status": "completed",
  "source": "api",
  "file": { "name": "customers.csv", "format": "csv" },
  "columns": { "name": "first_name", "country": "country" },
  "rows": { "total": 200000, "processed": 200000, "identified": 187412 },
  "progress": 100,
  "credits": { "reserved": 200000, "charged": 200000 },
  "summary": { "male": 96120, "female": 91292, "unknown": 12588, "from_llm": 0 },
  "error": null,
  "result": {
    "url": "https://namegender.com/api/v1/batches/B-7K2M9QX4TA/result",
    "format": "csv",
    "expires_at": "2026-10-01T10:04:12Z"
  },
  "poll_after_seconds": null
}

Το name_column είναι υποχρεωτικό για την εκκίνηση: μια στήλη που μαντεύτηκε και αποδείχθηκε λάθος θα ξόδευε μονάδες σε λάθος δεδομένα. Στείλτε start=false για να δείτε πρώτα τις στήλες, μια προεπισκόπηση και το κόστος, και μετά ξεκινήστε την εργασία.

Στείλτε κεφαλίδα Idempotency-Key. Μια νέα προσπάθεια με το ίδιο κλειδί επιστρέφει την πρώτη εργασία αντί να ανοίξει δεύτερη.

Έως 3 εργασίες μπορούν να βρίσκονται ταυτόχρονα στην ουρά ή σε εκτέλεση. Μια εργασία που δεν έχει ξεκινήσει μπορεί να ακυρωθεί και οι μονάδες της επιστρέφονται· μια εργασία σε επεξεργασία δεν μπορεί να σταματήσει.

Webhooks

Προσθέστε ένα endpoint στα Webhooks του πίνακα ελέγχου και θα του στέλνουμε ένα υπογεγραμμένο POST όταν μια εργασία αρχείου ολοκληρώνεται ή αποτυγχάνει, χωρίς να χρειάζεται να ρωτάτε.

Επαληθεύστε κάθε αίτημα

Το v1 είναι το HMAC-SHA256 της χρονοσφραγίδας, μιας τελείας και του ακατέργαστου σώματος, με το μυστικό του endpoint σας. Συγκρίνετε σε σταθερό χρόνο, δεχτείτε το αίτημα αν ταιριάζει οποιοδήποτε v1 και απορρίψτε χρονοσφραγίδα που απέχει πάνω από πέντε λεπτά από το ρολόι σας. Οι βιβλιοθήκες πελάτη τα κάνουν όλα αυτά με μία κλήση.

import express from 'express';
import { webhooks, NameGenderWebhookError } from 'namegender';

const app = express();

// express.raw, not express.json: the signature covers the exact bytes.
app.post('/namegender', express.raw({ type: 'application/json' }), async (req, res) => {
  let event;
  try {
    event = await webhooks.verify(
      req.body,
      req.get('NameGender-Signature'),
      process.env.NAMEGENDER_WEBHOOK_SECRET,
    );
  } catch (error) {
    if (error instanceof NameGenderWebhookError) return res.sendStatus(400);
    throw error;
  }

  res.sendStatus(204);   // answer first, then do the work

  if (event.type === 'batch.completed') {
    const job = event.data.object;   // same object as GET /batches/{id}
  }
});

import os
from flask import Flask, request
from namegender import webhooks, WebhookVerificationError

app = Flask(__name__)

@app.post("/namegender")
def namegender_webhook():
    try:
        event = webhooks.verify(
            request.get_data(),   # raw bytes, not request.json
            request.headers.get("NameGender-Signature"),
            os.environ["NAMEGENDER_WEBHOOK_SECRET"],
        )
    except WebhookVerificationError:
        return "", 400

    if event["type"] == "batch.completed":
        job = event["data"]["object"]   # same object as GET /batches/{id}
    return "", 204

<?php

$body   = file_get_contents('php://input');   // raw body, before json_decode
$header = $_SERVER['HTTP_NAMEGENDER_SIGNATURE'] ?? '';
$secret = getenv('NAMEGENDER_WEBHOOK_SECRET');

parse_str(str_replace(',', '&', $header), $parts);   // t=…&v1=…
preg_match_all('/v1=([0-9a-f]{64})/', $header, $m);

$t = (int) ($parts['t'] ?? 0);
$expected = hash_hmac('sha256', $t . '.' . $body, $secret);
$valid = abs(time() - $t) <= 300
    && array_filter($m[1], fn ($sig) => hash_equals($expected, $sig));

if (! $valid) {
    http_response_code(400);
    exit;
}

http_response_code(204);
$event = json_decode($body, true);

{
  "id": "evt_16f7c01502fda5436e8b7c4e",
  "type": "batch.completed",
  "created_at": "2026-09-24T10:04:12Z",
  "api_version": "v1",
  "data": {
    "object": {
      "id": "B-7K2M9QX4TA",
      "status": "completed",
      "rows": { "total": 200000, "processed": 200000, "identified": 187412 },
      "credits": { "reserved": 200000, "charged": 200000 },
      "result": { "url": "…/api/v1/batches/B-7K2M9QX4TA/result", "format": "csv" }
    }
  }
}

• Απαντήστε με οποιοδήποτε 2xx μέσα σε 10 δευτερόλεπτα και κάντε τη δουλειά μετά.
• Κάθε άλλη απάντηση, μαζί με τις ανακατευθύνσεις, επαναλαμβάνεται έως 7 φορές μέσα σε περίπου 45 ώρες. Αν ένα endpoint αποτυγχάνει για τρεις ημέρες, απενεργοποιείται και λαμβάνετε email.
• Μια νέα προσπάθεια έχει το ίδιο αναγνωριστικό και η σειρά δεν είναι εγγυημένη. Αφαιρέστε τα διπλότυπα με το NameGender-Event-Id και διαβάστε την εργασία με GET όταν χρειάζεστε την τρέχουσα κατάστασή της.
• Η ανανέωση του μυστικού στον πίνακα ελέγχου αφήνει το παλιό να υπογράφει για 24 ώρες, ώστε να ενημερώσετε τον διακομιστή σας χωρίς να χάσετε συμβάντα.
• Μπορεί να προστεθούν νέοι τύποι συμβάντων. Απαντήστε με 2xx σε τύπο που δεν χειρίζεστε και αγνοήστε τον.

Κατανομή ανά χώρα

Επιστρέφει τις χώρες όπου είναι καταγεγραμμένο ένα όνομα. Επιστρέφονται δύο λίστες και σκόπιμα δεν συγχωνεύονται: η `registrations` μετρά τον όγκο και είναι συγκρίσιμη μόνο μεταξύ των έντεκα χωρών που δημοσιεύουν καταμετρημένες στατιστικές ονομάτων, και η `attested_in` δείχνει την παρουσία χωρίς κάποια στάθμιση.

curl "https://namegender.com/api/v1/gender/countries?name=Mehmet" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "credits_charged": 1,
  "credits_remaining": 49994,
  "took_ms": 3,
  "name": "Mehmet",
  "basis": {
    "counted_sources": ["ssa", "ons", "nrs", "nisra", "insee", "statcan", "ine", "cso", "ssb", "statat", "pesel", "bfs"],
    "counted_countries": 8,
    "attested_countries": 16,
    "note": "Shares are calculated only across countries that publish counted name statistics…"
  },
  "registrations": [
    { "country": "CH", "count": 3890, "share": 29.45, "gender": "male", "source": "bfs"    },
    { "country": "FR", "count": 3775, "share": 28.58, "gender": "male", "source": "insee"  },
    { "country": "PL", "count": 1808, "share": 13.69, "gender": "male", "source": "pesel"  }
  ],
  "attested_in": ["AL","AT","AU","BE","CA","CH","ES","FR","GB","KS","MK","NO","PL","SE","TR","US"]
}

Ένα credit ανά αίτημα. Το `share` υπολογίζεται σε όλες τις χώρες με καταμετρήσεις, οπότε αθροίζεται στο 100 μόνο όταν το `limit` δεν περικόπτει τη λίστα· και το `counted_countries` μετρά πριν από την περικοπή. Η `attested_in` δεν περιλαμβάνει ποσοστά καθώς δεν υπάρχουν μετρήσεις για τον υπολογισμό τους.

Προσφώνηση

Μετατρέπει ένα όνομα σε προσφώνηση έτοιμη για επιστολή ή email, σε δέκα γλώσσες: “Sehr geehrte Frau Dr. Müller,”, “Sayın Ahmet Bey,”, “Madame,”, “山田様”. Ο προσδιορισμός φύλου περιλαμβάνεται και κοστίζει το ίδιο ένα credit. Κάθε απάντηση έχει μια επίσημη, μια ανεπίσημη και μια ουδέτερη γραμμή, καθώς και τα μέρη της επίσημης γραμμής.

curl -X POST "https://namegender.com/api/v1/salutation" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Dr. Anna Müller", "language": "de"}'

{
  "credits_charged": 1,
  "credits_remaining": 49993,
  "language": "de",
  "form": "gendered",
  "reason": null,
  "salutation": {
    "formal": "Sehr geehrte Frau Dr. Müller,",
    "informal": "Liebe Anna,",
    "neutral": "Guten Tag Dr. Anna Müller,"
  },
  "parts": { "opening": "Sehr geehrte", "courtesy": "Frau", "academic": "Dr.", "name": "Müller" },
  "gender": "female",
  "gender_source": "lookup",
  "probability": 99,
  "first_name": "Anna",
  "last_name": "Müller",
  "name_type": "personal"
}

Ένα λάθος φύλο είναι χειρότερο από κανένα, οπότε η μορφή με φύλο χρησιμοποιείται μόνο όταν το φύλο είναι γνωστό με τουλάχιστον `min_probability` και η γλώσσα έχει το μέρος του ονόματος που χρειάζεται. Διαφορετικά το `form` είναι `neutral` και το `reason` λέει γιατί. Εταιρείες και διευθύνσεις ρόλων παίρνουν `form: organization`. Τα `best_guess` και `ai_fallback` δεν ισχύουν εδώ.

Το POST /api/v1/salutation/bulk δέχεται έως 100 ονόματα στο `names`, ένα credit το καθένα, με τις ίδιες επιλογές για κάθε όνομα.

Έλεγχος ονόματος

Λέει αν ένα όνομα που πληκτρολογήθηκε σε φόρμα εγγραφής ή φόρμα δυνητικών πελατών μοιάζει με όνομα πραγματικού προσώπου, και γιατί. Εντοπίζει τυχαία πληκτρολόγηση (“asdf qwerty”), συμπληρωματικές τιμές (“Test Test”, “John Doe”, “n/a”), φανταστικούς χαρακτήρες (“Mickey Mouse”), βωμολοχίες, καθώς και ψηφία, σύμβολα ή διευθύνσεις email στο πεδίο του ονόματος. Ένα credit ανά όνομα.

curl -X POST "https://namegender.com/api/v1/name-check" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "asdf qwerty"}'

{
  "credits_charged": 1,
  "credits_remaining": 49992,
  "query": "asdf qwerty",
  "assessment": "implausible",
  "score": 0,
  "signals": [
    { "code": "placeholder", "severity": "high", "part": "first_name", "value": "asdf" },
    { "code": "keyboard_pattern", "severity": "high", "part": "first_name", "value": "asdf" },
    { "code": "keyboard_pattern", "severity": "high", "part": "last_name", "value": "qwerty" }
  ],
  "first_name": "Asdf",
  "last_name": "Qwerty",
  "name_type": "personal",
  "evidence": { "first_name_status": "not_found", "first_name_counted_records": 0 }
}

Το `assessment` είναι `implausible` όταν υπάρχει σήμα υψηλής σοβαρότητας (μοτίβο πληκτρολογίου, επαναλαμβανόμενα γράμματα, συμπληρωματική τιμή, βωμολοχία, email ή URL), `suspicious` με ένα μεσαίο (φανταστικός χαρακτήρας, ψηφία, σύμβολα, επωνυμία εταιρείας, χωρίς φωνήεντα, πολύ μεγάλο) ή δύο χαμηλά, και `plausible` σε κάθε άλλη περίπτωση. Το `score` κυμαίνεται από 0 έως 100 για το δικό σας όριο. Ένα μικρό όνομα που υπάρχει σε επίσημα ληξιαρχικά αρχεία γεννήσεων το ανεβάζει· ένα όνομα που δεν έχουμε δει ποτέ δεν το κατεβάζει από μόνο του. Τα επώνυμα κρίνονται μόνο από τη μορφή τους: πίσω από αυτό το endpoint δεν υπάρχει σύνολο δεδομένων επωνύμων.

Δοκιμάστηκε σε 4.610 πραγματικά μικρά ονόματα σε εννέα γραφές, μόνα τους και μαζί με επώνυμο: κανένα δεν χαρακτηρίστηκε ύποπτο ή απίθανο. Επώνυμα όπως Null, Test ή Cockburn, ονόματα δύο γραμμάτων όπως Ng και μονά ονόματα αφήνονται σκόπιμα ανέγγιχτα.

Το POST /api/v1/name-check/bulk δέχεται έως 100 ονόματα στο `names`, ένα credit το καθένα, με σύνοψη των τριών αξιολογήσεων.

Ηλικία από το όνομα

Πόσο χρονών είναι οι εν ζωή άνθρωποι με ένα μικρό όνομα: η διάμεση ηλικία, το μεσαίο μισό τους (`age_range`) και το μεσαίο 80% (`age_range_80`). Brittany στις Ηνωμένες Πολιτείες: διάμεσος 36, οι μισοί μεταξύ 32 και 38. Ένα credit ανά όνομα.

curl "https://namegender.com/api/v1/age?name=Brittany" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "credits_charged": 1,
  "credits_remaining": 49991,
  "request_id": "req_8f2c1a",
  "name": "Brittany",
  "first_name": "Brittany",
  "gender": null,
  "age": 36,
  "age_range": { "low": 32, "high": 38 },
  "age_range_80": { "low": 28, "high": 41 },
  "birth_year": 1990,
  "sample_size": 353775,
  "births": 361434,
  "country": "US",
  "country_source": "default",
  "source": "ssa",
  "series": "1880-2024",
  "reference_year": 2026,
  "reason": null
}

Μέθοδος: καταγεγραμμένες γεννήσεις ανά όνομα, φύλο και έτος, με κάθε έτος σταθμισμένο με το ποσοστό της αντίστοιχης γενιάς που ζει ακόμη (πίνακες επιβίωσης γενεών της SSA). Πηγές: γεννήσεις SSA 1880–2024 (US), INSEE 1900–2025 (Γαλλία), SSB 1945–2025 (Νορβηγία). Το `reason` είναι `not_found` για όνομα που δεν υπάρχει στη σειρά και `insufficient_data` κάτω από 100 ζώντες ανθρώπους.

Οι γεννήσεις στο εξωτερικό δεν περιλαμβάνονται σε καμία σειρά, οπότε ονόματα συνηθισμένα μεταξύ μεταναστών φαίνονται νεότερα από ό,τι είναι. Η σειρά της Νορβηγίας ξεκινά το 1945, οπότε λείπουν όσοι γεννήθηκαν νωρίτερα. Ο πίνακας επιβίωσης των Ηνωμένων Πολιτειών χρησιμοποιείται και για τη Γαλλία και τη Νορβηγία.

Το POST /api/v1/age/bulk δέχεται έως 100 ονόματα στο `names`, ένα credit το καθένα, με τη σειρά αποστολής.

Υπόλοιπο

Δείτε το υπόλοιπο credits σας και ό,τι απομένει από τη σημερινή δωρεάν ποσόστωση. Αυτή η κλήση δεν χρεώνεται.

curl "https://namegender.com/api/v1/me" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "email": "you@example.com",
  "credits_remaining": 50099,
  "purchased_credits": 50000,
  "free_today": 99,
  "free_daily_limit": 100,
  "lifetime_requests": 12480
}

Μη λατινικά γράμματα

Στείλτε ένα όνομα στο δικό του γράμμα και το συνδέουμε με τα δεδομένα αναφοράς. Χωρίς επιπλέον παράμετρο: ανιχνεύουμε το γράμμα και επιλέγουμε τη σωστή στρατηγική.

# Arap yazısı — ünsüz iskeleti üzerinden eşleşir
curl "https://namegender.com/api/v1/gender?name=%D9%85%D8%AD%D9%85%D8%AF" -H "Authorization: Bearer KEY"
# -> { "gender": "male", "probability": 100, "source": "script", "matched_as": "mahamad" }

# Çince — soyadı ayıklanır, verilen ad sorgulanır
curl "https://namegender.com/api/v1/gender?name=%E6%9D%8E%E6%98%8E" -H "Authorization: Bearer KEY"
# -> { "gender": "male", "probability": 92, "source": "db" }

Όταν δεν μπορούμε να μετατρέψουμε ένα σύστημα γραφής καθόλου, η απόκριση είναι gender: null με source: none. Ελέγξτε το πεδίο source: script σημαίνει ότι κάναμε μεταγραφή, db σημαίνει ότι ταιριάσαμε απευθείας τους χαρακτήρες που στείλατε. Τα δύο έχουν διαφορετική confidence και σας δείχνουμε ποιο πήρατε.

Πεδία απάντησης

Ίδια σε όλα τα endpoints.

Δύο πεδία που άλλες υπηρεσίες δεν σας δίνουν

source σας λέει από πού προήλθε η απάντηση: τη βάση δεδομένων αναφοράς, μια ασαφή αντιστοίχιση ή την εναλλακτική λύση AI. matched_as ονοματίζει την καταχώρηση που ταίριασε με ασαφή αντιστοίχιση. Μαζί σας επιτρέπουν να αποφασίσετε πόσο να εμπιστευθείτε ένα μεμονωμένο αποτέλεσμα αντί να το λάβετε με πίστη.

Κωδικοί σφάλματος

Ο κωδικός κατάστασης HTTP σας λέει ότι μια κλήση απέτυχε. Το σώμα JSON δίνει στη συνέχεια την αιτία στο error, την εξηγεί στο message και σας δίνει ένα request_id για να το αναφέρετε στην υποστήριξη, μαζί με έναν σύνδεσμο προς την αντίστοιχη γραμμή της τεκμηρίωσης παρακάτω. Διακλαδώστε με βάση το error, ποτέ το message: τα μηνύματα μεταφράζονται και μπορεί να αναδιατυπωθούν.

{
  "error": "no_credits",
  "message": "You are out of credits. Buy more or wait for your daily free quota to reset.",
  "request_id": "req_9c1f5b2a7e0d4a13",
  "docs": "https://namegender.com/docs#error-no_credits"
}

Όρια ταχύτητας

Η κανονική χρήση δεν φτάνει σε όριο. Το όριο υπάρχει για να σταματήσει ένα διαρρέον κλειδί από τον κατάχρηση, και μετράται ανά API key και όχι ανά IP, έτσι ώστε πολλοί πελάτες σε έναν διακομιστή να μην καταναλώνουν το δικαίωμα ο ένας του άλλου.

Τρέχον όριο: 1.200 αιτήματα ανά λεπτό ανά κλειδί. Χρειάζεστε περισσότερα; Ζητήστε και θα το αυξήσουμε στον λογαριασμό σας.

Κάθε απάντηση φέρει τα τυπικά headers X-RateLimit-Limit και X-RateLimit-Remaining.