名 NameFYI
🇺🇸 English 🇰🇷 한국어 🇯🇵 日本語 🇨🇳 中文简体 🇪🇸 Español 🇧🇷 Português 🇮🇳 हिन्दी 🇸🇦 العربية 🇫🇷 Français 🇷🇺 Русский 🇩🇪 Deutsch 🇹🇷 Türkçe 🇻🇳 Tiếng Việt 🇮🇩 Bahasa Indonesia 🇹🇭 ไทย

Developer Documentation

Integrate NameFYI data into your applications. Access surnames, given names, hanja characters, guides, glossary terms, and more through our JSON APIs, Python/npm packages, and machine-readable endpoints.

Free No Auth Required JSON 14 Cultures

API Endpoints

All API endpoints return JSON responses with Content-Type: application/json. No authentication is required. Free to use.

Endpoint Description Cache
GET /api/search/?q= Unified search across 7 entity types 5m
GET /api/surname/{slug}/ Surname detail with clan origins and population data 1h
GET /api/character/{slug}/ Hanja/Hanzi/Kanji character detail with stroke count and five elements 1h
GET /api/given-name/{slug}/ Given name detail with trends and meaning tags 1h
GET /api/surnames/?culture= List surnames, filterable by culture (max 200) 1h
GET /api/cultures/ List all 14 name cultures with stats 1h
GET /api/glossary/{slug}/ Glossary term with definition and related terms 1h
GET /api/guide/{slug}/ Educational guide with full content 1h
GET /api/character-lookup/?q= Look up hanja/hanzi/kanji characters by CJK input none
GET /api/random-name/?gender= Random Korean given name, filterable by gender none
GET /api/meaning-tags/?category= List meaning tags with name counts 1h
GET /api/openapi.json OpenAPI 3.1.0 specification (CORS enabled) none

Surname Detail

GET /api/surname/{slug}/ 
curl "https://namefyi.com/api/surname/kim-korean/"
{
  "name_native": "김",
  "name_romanized": "Kim",
  "name_romanized_variants": ["Gim"],
  "slug": "kim-korean",
  "url": "/surname/kim-korean/",
  "pronunciation_ipa": "kim",
  "hanja": "金",
  "hanja_meaning": "gold, metal",
  "culture": {"name": "Korean", "slug": "korean"},
  "population": 10689959,
  "population_percentage": "21.6%",
  "country_rank": 1,
  "world_rank": 1,
  "household_count": 3637625,
  "origin": "Gimhae, Gyeongsang Province",
  "historical_figures": ["Kim Yu-sin", "Kim Gu"],
  "modern_celebrities": ["Kim Yuna", "BTS (Kim Taehyung)"],
  "clan_origins": [
    {
      "name_ko": "김해",
      "name_hanja": "金海",
      "name_romanized": "Gimhae",
      "slug": "gimhae-kim",
      "url": "/clan/gimhae-kim/",
      "region": "Gimhae, Gyeongsang",
      "founder": "Kim Suro",
      "founder_era": "42 AD",
      "population": 4456700,
      "rank_within_surname": 1
    }
  ]
}

Character Lookup

Look up one or more CJK characters to get readings, meanings, stroke counts, and five elements data.

GET /api/character-lookup/?q={characters} 
curl "https://namefyi.com/api/character-lookup/?q=%E9%87%91%E7%A7%80"
{
  "results": [
    {
      "character": "金",
      "unicode_codepoint": "U+91D1",
      "reading_native": "금",
      "reading_romanized": "geum",
      "meaning": "gold, metal",
      "stroke_count": 8,
      "five_elements": "金 (Metal)",
      "radical": "金"
    },
    {
      "character": "秀",
      "unicode_codepoint": "U+79C0",
      "reading_native": "수",
      "reading_romanized": "su",
      "meaning": "excellent, refined",
      "stroke_count": 7,
      "five_elements": "金 (Metal)",
      "radical": "禾"
    }
  ]
}

Given Name Detail

GET /api/given-name/{slug}/ 
curl "https://namefyi.com/api/given-name/minjun-korean/"
{
  "name_native": "민준",
  "name_romanized": "Minjun",
  "name_romanized_variants": ["Min-jun", "Minjoon"],
  "slug": "minjun-korean",
  "url": "/given-name/minjun-korean/",
  "gender": "male",
  "syllable_count": 2,
  "meaning": "quick and talented",
  "culture": {"name": "Korean", "slug": "korean"},
  "hanja": "敏俊",
  "hanja_meaning": "agile + handsome",
  "etymology": {
    "language": "Sino-Korean",
    "meaning": "quick-witted and handsome",
    "root": "敏 (min) + 俊 (jun)"
  },
  "popularity_score": 95,
  "peak_decade": "2010s",
  "trends": [
    {"year": 2015, "rank": 1, "count": 5840},
    {"year": 2020, "rank": 3, "count": 4210}
  ],
  "meaning_tags": [
    {"label": "Intelligence", "slug": "intelligence", "icon": "🧠", "category": "virtue", "url": "/meaning/intelligence/"}
  ]
}

Random Name

Get a random Korean given name, optionally filtered by gender.

GET /api/random-name/?gender={male|female} 
curl "https://namefyi.com/api/random-name/?gender=female"
{
  "name": {
    "name_native": "서연",
    "name_romanized": "Seoyeon",
    "hanja": "瑞延",
    "hanja_meaning": "auspicious + extend",
    "meaning": "auspicious and flowing",
    "gender": "female"
  }
}

Search API

Unified search across surnames, given names, characters, glossary terms, guides, meaning tags, and cultures.

GET /api/search/?q={query} 
curl "https://namefyi.com/api/search/?q=kim"
{
  "results": [
    {"type": "surname", "name": "Kim (김)", "slug": "kim-korean", "culture": "Korean", "url": "/surname/kim-korean/"},
    {"type": "given_name", "name": "Kimiko (君子)", "slug": "kimiko-japanese", "culture": "Japanese", "url": "/given-name/kimiko-japanese/"}
  ],
  "total": 2
}

Python Package

Install the pure Python engine with zero dependencies. Korean romanization, five elements analysis, and element compatibility.

pip install namefyi 
from namefyi import romanize_korean, five_elements_for_strokes

# Romanize Korean name (Revised Romanization)
rom = romanize_korean("김민준")
print(rom)  # "Gim Minjun"

# Five Elements analysis by stroke count
element = five_elements_for_strokes(8)
print(element)  # "金 (Metal)"

# Check element compatibility
from namefyi import check_element_compatibility
compat = check_element_compatibility("金", "水")
print(compat)  # "Harmonious"

View on PyPI · Source on GitHub

Command-Line Interface

pip install "namefyi[cli]" 
namefyi romanize 김민준          # Gim Minjun
namefyi elements 8               # 金 (Metal) — stroke count 8
namefyi elements 3               # 火 (Fire) — stroke count 3
NameFYI CLI demo showing romanization and five elements analysis

MCP Server

Add name analysis tools to any AI assistant that supports Model Context Protocol.

pip install "namefyi[mcp]"

Claude Desktop configuration

{
  "mcpServers": {
    "namefyi": {
      "command": "python",
      "args": ["-m", "namefyi.mcp_server"]
    }
  }
}

Available tools

romanize_korean five_elements element_compatibility format_population

npm Package

TypeScript/JavaScript version with zero dependencies. Works in Node.js, Deno, Bun, and browsers.

npm install namefyi 
import { romanizeKorean, fiveElementsForStrokes } from "namefyi";

// Romanize Korean name
const rom = romanizeKorean("김민준");
console.log(rom); // "Gim Minjun"

// Five Elements by stroke count
const element = fiveElementsForStrokes(8);
console.log(element); // "金 (Metal)"
namefyi npm demo — Node.js REPL with Korean romanization

View on npm · Source on GitHub

AI / LLM Integration

NameFYI provides machine-readable content summaries following the llms.txt standard. These endpoints help AI models understand and reference our content.

/llms.txt text/plain

A concise summary of NameFYI's content structure and key pages. Designed for AI models to quickly understand what the site offers and how it is organized. 

# NameFYI.com

> Global names encyclopedia — surnames, given names,
  hanja characters, and naming guides across 14 cultures.

## Browse
- [Surnames](https://namefyi.com/surnames/) — 1,000 surnames
- [Given Names](https://namefyi.com/given-names/) — 35,585 names
  ...
/llms-full.txt text/plain

Extended version with complete URL patterns, i18n language codes, and page-level structure. Use this for deeper indexing and cross-referencing of NameFYI content.

*.md text/markdown

Append .md to any page URL to get a markdown representation. Ideal for LLM context injection and RAG pipelines. 

# Fetch a surname page as markdown
curl "https://namefyi.com/surname/kim-korean.md"

# Fetch a character page as markdown
curl "https://namefyi.com/character/geum-gold.md"

AI Crawler Policy: Our robots.txt explicitly allows GPTBot, ClaudeBot, and Google-Extended crawlers.

SEO & Standards

Standard endpoints for search engines, crawlers, and security researchers.

Endpoint Standard Description
/sitemap.xml Sitemaps 0.9 Sitemap index with per-section sitemaps covering all content types
/robots.txt REP Crawler directives with explicit AI bot permissions
/.well-known/security.txt RFC 9116 Security vulnerability reporting contact information

Structured Data

Every page includes JSON-LD structured data for rich search results:

  • WebSite — with SearchAction for sitelinks search box
  • BreadcrumbList — navigation breadcrumbs on all pages
  • DefinedTerm — hanja/hanzi/kanji character pages with definitions
  • Article — guide pages with author, dates, and reading time
  • CollectionPage — index and listing pages

Internationalization

All content pages include hreflang alternate links for 15 languages: English (default), Korean, Japanese, Chinese (Simplified), Spanish, French, German, Portuguese, Russian, Arabic, Hindi, Thai, Vietnamese, Indonesian, and Turkish.

OpenAPI Specification

A machine-readable OpenAPI 3.1.0 specification is available for all 12 JSON API endpoints. Use it with tools like Swagger UI, Postman, or code generators.

Download openapi.json

Fetch via command line

# Download the OpenAPI spec
curl "https://namefyi.com/api/openapi.json" -o openapi.json

# Pretty-print
curl -s "https://namefyi.com/api/openapi.json" | python -m json.tool

Rate Limits & Usage

Our APIs are free to use with no authentication required. To ensure fair access for everyone, please follow these guidelines:

  • Keep requests under 60 requests per minute per IP address
  • Include a descriptive User-Agent header identifying your application
  • Cache responses locally when possible — our API responses include Cache-Control headers
  • CORS is enabled for browser-based requests from any origin
  • For bulk data access, use the sitemap to discover all URLs, then append .md for machine-readable content

If you need higher-volume access or have integration questions, reach out via the contact in our security.txt.

Quick Reference

Surname Detail /api/surname/{slug}/
Character Detail /api/character/{slug}/
Given Name Detail /api/given-name/{slug}/
検索 /api/search/?q=...
List Surnames /api/surnames/?culture=...
文化 /api/cultures/
Glossary Term /api/glossary/{slug}/
Guide /api/guide/{slug}/
Character Lookup /api/character-lookup/?q=...
Random Name /api/random-name/?gender=...
Meaning Tags /api/meaning-tags/?category=...
OpenAPI Spec /api/openapi.json
Python Package pip install namefyi
npm Package npm install namefyi
llms.txt /llms.txt
Markdown /{any-page}.md