Update, 2026-11-15. The dataset is now at v2.1 — 16 fields, and a correction to where the population figures come from. It turns out the 2020 MPS report does not print headcounts for the top 100 at all; I had credited it for numbers it never published. No rank or count changed, one field was added, and the story is here: My open dataset credited the wrong source for 30 numbers. The body below is left as it was published, so you can see what v1 claimed.
Every few months someone asks me for a "list of Chinese surnames". The answer is always more annoying than it should be.
The lists that exist fall into three camps. The classic Hundred Family Surnames ordering — 赵钱孙李 — is a Song dynasty poem, not a frequency table, so sorting by it means nothing. Scraped CSVs have thousands of rows, no tone marks, and 欧阳 split into two separate characters somewhere in the middle. Genealogy tables have the detail but usually no licence, or a licence that says "contact us".
So while building a Chinese naming site I extracted the structured parts of my own surname pages and released them: 109 surnames, 13 fields per record, JSON and CSV, CC BY 4.0 (16 fields as of v2.1).
- JSON:
https://naming-cn.pages.dev/data/surnames.json(87 KB at v2.1) - CSV:
https://naming-cn.pages.dev/data/surnames.csv(19 KB, UTF-8 with BOM) - Docs:
https://naming-cn.pages.dev/en/chinese-surnames-dataset
Both files are served with Access-Control-Allow-Origin: *, so this works from the browser:
const rows = await fetch('https://naming-cn.pages.dev/data/surnames.json')
.then(r => r.json());
rows.filter(r => r.rank).length; // 30
rows.find(r => r.surname === '李'); // full record
No key, no signup. That was the whole point.
What's actually in a record
{
"surname": "李",
"slug": "li3",
"pinyin": "lǐ",
"era": "商末",
"ancestor": "李利贞(血缘始祖皋陶)",
"origin": "河南鹿邑",
"junwang": ["陇西", "赵郡"],
"tanghao": [
{ "name": "陇西堂", "note": "以郡望立堂,出自陇西一系" },
{ "name": "青莲堂", "note": "李白自号青莲居士,后世一支取为堂号" }
],
"rank": "全国第 2 位",
"population": "约 1.01 亿人",
"notables": ["李耳(老子)", "李广", "李世民", "李白", "李时珍"],
"origin_note": "嬴姓。舜时皋陶任大理(掌刑狱),子孙以官为氏称「理」。……遂改「理」为「李」。",
"url": "https://naming-cn.pages.dev/xing/li3"
}
Four decisions in there were less obvious than they look.
1. Compound surnames are one record, not two characters
30 of the 109 are two-character surnames — 欧阳, 司马, 诸葛, 尉迟, 万俟. If you split on characters you get garbage: 欧阳 is not "a surname 欧 followed by 阳", and 万俟 is read mò qí, not wàn sì. So surname holds one or two characters, and slug is the tone-numbered pinyin (ouyang2, moqi2) which doubles as the URL key.
That slug convention is also why lookups don't need tone marks. Want everything starting with li? /^li/ on the slug catches 李 (li3), 梁 (liang2), 廖 (liao4), 林 (lin2), 刘 (liu2) — five records, no tone marks typed. It deliberately misses 吕 (lv3), 卢 (lu2), 陆 (lu4) and 罗 (luo2): slug is a join key, not a phonetic wildcard.
2. Empty means unknown, not zero
Only 30 of the 109 have a population rank. That's not laziness. The Ministry of Public Security's 2020 national name report — the only official Chinese surname statistics at national scale — ranks the top 100 surnames and prints no headcount for them; the figures it does publish cover compound surnames only. Below rank 100 there is no official number at all, and every figure you find online for surname #147 is somebody's estimate presented as fact. (The v2.1 update above unpicks this properly — I had overstated what that report contains.)
So rank and population are empty strings for the other 79, and the docs say plainly: empty means unknown, not zero. If your code does int(r['rank']), it will crash — deliberately. I would rather crash than silently aggregate 79 fake zeros.
3. Arrays are pipe-separated in the CSV
junwang, tanghao and notables are arrays. CSV has no array type, so they're 陇西|赵郡 — a delimiter choice, not a schema. Two consequences:
- The CSV flattens
tanghaofrom[{name, note}]to names only, because the note is a sentence and sentences with commas inside a CSV cell are a support ticket waiting to happen. If you need the derivations, use the JSON. - The BOM is there on purpose. Without it, Excel on a Chinese Windows machine opens the file as GBK and every surname is mojibake. The BOM costs you three bytes at the start of the file and one
encoding='utf-8-sig'if you're reading it back in Python.
4. Commandery and hall name are not the same field, and merging them loses the point
A junwang (郡望) is a region where a branch of the clan became prominent — the coordinate that determined a family's social rank from the Wei–Jin period through the Tang. A tanghao (堂号) is the inscription on that branch's ancestral hall. Many hall names just repeat the commandery (陇西堂 for the 陇西 branch of 李). Others commemorate an anecdote: 李's 青莲堂 comes from Li Bai calling himself the "Lotus Dweller", and the name carries a claim about poetry and wine rather than about geography.
Flatten both into one "origin" string and you lose exactly the part that's interesting.
The wart I haven't fixed
rank is a display string, "全国第 2 位", not a number. That was fine for rendering the pages and wrong for anyone who wants to sort. The fix is a rank_num field, and it's on the list. For now:
import pandas as pd
df = pd.read_csv('https://naming-cn.pages.dev/data/surnames.csv')
ranked = df[df['rank'].notna()]
ranked['rank_num'] = ranked['rank'].str.extract(r'(\d+)').astype(int)
ranked.sort_values('rank_num').head()
Free-text Chinese in a machine-readable field is the kind of thing you only notice when someone else tries to use your data. Which is an argument for publishing the data in the first place.
Where the numbers come from
Population ranks and sizes: the 2020 MPS report. Commanderies: Tang and Song surname books — the Genealogical Tables of the Chancellors in the New Book of Tang, the Yuanhe Surname Compilation. Hall names: clan genealogies and surviving ancestral halls. The synthesis into one record per surname with a readable origin note is my own work, and errors in it are mine.
Where the sources disagree, the record keeps both readings instead of picking one. ancestor: "白公胜、公子白" is not a typo — it's two documented traditions for the same surname. If you're doing anything analytical with this, filter on origin_note containing 另有 (45 records) or treat ancestor as potentially multi-valued (6 records contain 、).
Using it
CC BY 4.0 — commercial use, modification, redistribution all fine; attribution plus a licence link is the only condition.
Chinese Naming (2026). Chinese Surnames Open Dataset.
https://naming-cn.pages.dev/en/chinese-surnames-dataset (CC BY 4.0)
Corrections are genuinely welcome, especially from anyone who knows the genealogy literature better than I do. If a commandery is wrong, I'd rather be told than be cited.
Top comments (0)