Nyilvános API

A magyarnevek.hu nyilvános REST API lehetővé teszi, hogy az adatbázisban tárolt névadatokat saját alkalmazásokban is felhasználd. Minden kéréshez érvényes ügyfél-azonosító és API-kulcs szükséges.

Hitelesítés

Minden kérésnek tartalmaznia kell a következő fejléceket:

Header	Description
x-client-id	A regisztrált ügyfél-azonosítód
x-api-key	Az ügyfélhez tartozó API-kulcs

Az Origin fejléc értékét az API az engedélyezett domainek listájával veti össze. Eltérés esetén a válasz 403 Forbidden.

Sebességkorlát (rate limit)

Az API ügyfelenként és IP-címenként percenként korlátozza a kérések számát. Az alapértelmezett korlát 60 kérés/perc. Túllépés esetén a válasz 429 Too Many Requests.

Végpontok

Alap URL: https://magyarnevek.hu/api/v1

GET

/api/v1/names

Visszaadja a magyar utónevek lapozható listáját.

Paraméterek

Név	Típus	Kötelező	Leírás
firstLetter	string	–	Szűrés kezdőbetű szerint (pl. A, Á)
sex	1 \| 2 \| 3	–	Szűrés nem szerint (1=férfi, 2=női, 3=uniszex)
certificate	true \| false	–	Szűrés anyakönyvezhetőség szerint
group	number	–	Szűrés eredet-csoport szerint (0–4, 100, 200)
search	string	–	Szabad szöveges szűrő névre és leírásra
limit	number	–	Oldal mérete, max 20 (alapértelmezett: 20)
pageToken	string	–	Lapozási token az előző válaszból
fields	string	–	Vesszővel elválasztott mezők (alapértelmezett: csak name). * az összes mezőhöz. Elérhető: sex, description, descriptionEnglish, phonetic, certificate, group, namedays.

Példa kérés

curl -X GET "/api/v1/names?sex=male&limit=5" \
  -H "x-client-id: YOUR_CLIENT_ID" \
  -H "x-api-key: YOUR_API_KEY"

Példa válasz

{
  "data": [
    {
      "name": "Attila",
      "sex": 1,
      "description": "Egyes kutatók szerint hun–türk szó...",
      "descriptionEnglish": "Some researchers believe it derives from a Hunnic–Turkic word...",
      "phonetic": "at-ti-la",
      "certificate": true,
      "group": 1,
      "namedays": "https://magyarnevek.hu/api/v1/namedays/Attila"
    }
  ],
  "nextPageToken": "https://magyarnevek.hu/api/v1/names?sex=male&limit=5&pageToken=Attila"
}

GET

/api/v1/names/:name

Visszaadja egy magyar utónév részleteit.

Paraméterek

Név	Típus	Kötelező	Leírás
:name	string	✓	A keresett pontos név (URL-kódolva)
fields	string	–	Vesszővel elválasztott mezők (alapértelmezett: csak name). * az összes elérhető mezőhöz.

Példa kérés

curl -X GET "/api/v1/names/Attila" \
  -H "x-client-id: YOUR_CLIENT_ID" \
  -H "x-api-key: YOUR_API_KEY"

Példa válasz

{
  "name": "Attila",
  "sex": 1,
  "description": "Egyes kutatók szerint hun–türk szó...",
  "descriptionEnglish": "Some researchers believe it derives from a Hunnic–Turkic word...",
  "phonetic": "at-ti-la",
  "certificate": true,
  "group": 1,
  "namedays": "https://magyarnevek.hu/api/v1/namedays/Attila"
}

GET

/api/v1/namedays/:name

Visszaadja egy adott névhez tartozó névnap-dátumokat.

Paraméterek

Név	Típus	Kötelező	Leírás
:name	string	✓	A keresett pontos név (URL-kódolva)

Példa kérés

curl -X GET "/api/v1/namedays/Istv%C3%A1n" \
  -H "x-client-id: YOUR_CLIENT_ID" \
  -H "x-api-key: YOUR_API_KEY"

Példa válasz

{
  "name": "István",
  "dates": [
    {
      "hu": "aug. 20.",
      "en": "Aug 20",
      "iso": "08-20",
      "main": true
    },
    {
      "hu": "dec. 26.",
      "en": "Dec 26",
      "iso": "12-26",
      "main": false
    }
  ]
}

GET

/api/v1/name-forms/:name

Visszaadja egy adott név történelmi névformáit (latin, cirill, görög).

Paraméterek

Név	Típus	Kötelező	Leírás
:name	string	✓	A keresett pontos név (URL-kódolva)

Példa kérés

curl -X GET "/api/v1/name-forms/Istv%C3%A1n" \
  -H "x-client-id: YOUR_CLIENT_ID" \
  -H "x-api-key: YOUR_API_KEY"

Példa válasz

{
  "baseName": "István",
  "forms": {
    "latin": [
      "Stephanus"
    ],
    "cyrillic": [
      "Стефан"
    ],
    "greek": [
      "Στέφανος"
    ]
  }
}

GET

/api/v1/stats

Visszaadja a névnépszerűségi statisztikákat a hivatalos magyar anyakönyvi adatok alapján.

Paraméterek

Név	Típus	Kötelező	Leírás
name	string	–	Név vagy vesszővel elválasztott lista (pl. Anna,Péter). Évszűrővel elhagyva az adott év összes nevét adja vissza.
year	string	–	Pontos év (pl. 2020) vagy tartomány (pl. 1995-1999)
compare	string	–	Vesszővel elválasztott évek egymás melletti összehasonlításhoz (pl. 2020,2021)
sex	1 \| 2 \| 3	–	Szűrés nem szerint (1=férfi, 2=női, 3=uniszex)
limit	number	–	Max eredmény, legfeljebb 20 (alapértelmezett: 20)

Példa kérés

curl -X GET "/api/v1/stats?name=Anna&sex=2" \
  -H "x-client-id: YOUR_CLIENT_ID" \
  -H "x-api-key: YOUR_API_KEY"

Példa válasz

{
  "data": [
    {
      "name": "Anna",
      "year": "2023",
      "first": 312,
      "middle": 88,
      "sex": 2
    },
    {
      "name": "Anna",
      "year": "2022",
      "first": 298,
      "middle": 91,
      "sex": 2
    }
  ]
}

GET

/api/v1/search

Visszaadja az egyező neveket. Legalább egy szűrőparamétert kötelező megadni (a `limit` és `fields` önmagában nem elegendő). A `q` opcionális — megadva kis-nagybetű-érzéketlen tartalom-keresést végez a `name`, `description` és `descriptionEnglish` mezőkön. Az összes szűrő AND logikával kombinálódik.

Paraméterek

Név	Típus	Kötelező	Leírás
q	string	–	Keresési kifejezés — kis-nagybetű-érzéketlen tartalom-keresés névre, leírásra és angol leírásra. Elhagyható szövegszűrő nélküli böngészéshez.
sex	1 \| 2 \| 3	–	Szűrés nem szerint (1=férfi, 2=női, 3=uniszex)
certificate	true \| false	–	Szűrés anyakönyvezhetőség szerint
group	number	–	Szűrés csoport azonosító szerint
nameStart	string	–	Csak az ezzel a karakterlánccal kezdődő neveket adja vissza (kis-nagybetű-érzéketlen)
nameEnd	string	–	Csak az ezzel a karakterlánccal végződő neveket adja vissza (kis-nagybetű-érzéketlen)
descContains	string	–	Csak azokat a neveket adja vissza, amelyek leírása (magyar vagy angol) tartalmazza ezt a szöveget
vhLow	true	–	Mély magánhangzó-harmóniájú nevek szűréséhez — pass "true" az aktiváláshoz
vhMixed	true	–	Vegyes magánhangzó-harmóniájú nevek szűréséhez — pass "true" az aktiváláshoz
vhHigh	true	–	Magas magánhangzó-harmóniájú nevek szűréséhez — pass "true" az aktiváláshoz
containVowels	string	–	Vesszővel elválasztott magyar magánhangzók, amelyeket a névnek tartalmaznia kell (pl. "a,e")
containVowelsOnly	true	–	"true" esetén a név csak a containVowels-ben felsorolt magánhangzókat tartalmazhatja
containConsonants	string	–	Vesszővel elválasztott mássalhangzók, amelyeket a névnek tartalmaznia kell (pl. "r,cs,ty")
containConsonantsOnly	true	–	"true" esetén a név csak a containConsonants-ban felsorolt mássalhangzókat tartalmazhatja
syllableMin	number	–	Szótagok minimális száma
syllableMax	number	–	Szótagok maximális száma
namedayFrom	string	–	Névnap-tartomány kezdete hónap-nap formátumban (pl. "3-15" = március 15.)
namedayTo	string	–	Névnap-tartomány vége hónap-nap formátumban (pl. "8-20" = augusztus 20.)
limit	number	–	Max eredmény, legfeljebb 20 (alapértelmezett: 20)
pageToken	string	–	Lapozási token az előző válasz nextPageToken mezőjéből
fields	string	–	Vesszővel elválasztott mezők (alapértelmezett: csak name). * az összes elérhető mezőhöz.

Példa kérés

curl -X GET "/api/v1/search?q=" \
  -H "x-client-id: YOUR_CLIENT_ID" \
  -H "x-api-key: YOUR_API_KEY"

Példa válasz

{
  "data": [
    {
      "name": "Attila",
      "sex": 1,
      "description": "Egyes kutatók szerint hun–türk szó...",
      "descriptionEnglish": "Some researchers believe it derives from a Hunnic–Turkic word...",
      "phonetic": "at-ti-la",
      "certificate": true,
      "group": 1,
      "namedays": "https://magyarnevek.hu/api/v1/namedays/Attila"
    }
  ]
}