What is the Chinese Name Analysis API and how does it work?

It scores a Chinese name using 五格剖象法 (Five Grids), counting Kangxi strokes of the surname and given name, building five grids, and rating each against the 81數理 fate-number scale. Send surname and given_name in Chinese characters, get back all five grids, their elements, ratings, and a 三才 harmony verdict in one JSON response. Pricing starts free for 50 requests/month.

What is 五格剖象法 (Five Grids)?

五格剖象法 is the Kumazaki (熊崎) school name-numerology method that dominates commercial Chinese name consulting. It builds five grids, 天格 (Heaven), 人格 (Human), 地格 (Earth), 外格 (Outer), and 總格 (Total), from the stroke counts of a name's characters, then rates each against the Five Elements and the 81數理 fate-number scale.

How is this different from the Chinese BaZi API?

BaZi (Four Pillars) reads a person's birth moment; Chinese Name Analysis reads their name. They are companion products: pass birth_data into the Name Analysis endpoint and it cross-checks the name's elements against the BaZi chart's favorable elements, returning a supports/neutral/drains verdict. Most customers who use BaZi ask for name scoring next.

How does the API count strokes for a Chinese name?

It looks up each character's Kangxi Dictionary (康熙字典) stroke count, the same reference professional name consultants use, not the modern Unicode stroke-count property that many free tools rely on incorrectly. The lookup table covers more than 60,000 characters.

Does the API handle Simplified Chinese names?

Yes. Simplified input is automatically restored to its Traditional form before stroke counting, because 五格 numerology is defined against Traditional (Kangxi) strokes. For example, 刘 is restored to 劉 (15 strokes) rather than counted as its Simplified 6-stroke form, which would produce a wrong grid.

What is the 81數理 rating system?

81數理 is a scale of 81 fate numbers, each with an auspiciousness rating (great auspicious, auspicious, half auspicious, inauspicious, or great inauspicious) and a specific meaning. Every grid number in a name is reduced into the 1-81 range and looked up against this table, so a name can carry up to five separate 81數理 readings.

What is 三才 (Three Talents) and what does the verdict mean?

三才 reads the elements of the Heaven, Human, and Earth grids as a three-character element stack (for example 土火土) and looks up how they interact from 125 possible combinations. The verdict tells you whether the name's early structure, personality, and foundation reinforce or clash with each other, separate from the individual grid ratings.

Can the API check a name against someone's BaZi chart?

Yes. Supply birth_data (year, month, day, hour) alongside the name and the API computes the person's 喜用神 (favorable elements) from their BaZi chart, then compares them against the name's dominant elements. You get a supports, neutral, or drains verdict with a 0-100 synergy score and recommendation text.

Does the API support compound surnames like 歐陽 or 司馬?

Yes, compound (two-character) surnames are fully supported alongside single-character surnames. The API automatically detects the name's shape, single or compound surname, one or two-character given name, and applies the correct grid formula for that configuration.

What happens if I submit a 1-character given name vs a 2-character one?

Both are supported and use different grid formulas internally: a single-character given name uses a fixed +1 rule for the Outer Grid (外格), while a two-character given name derives it from the second given-name character. The API detects the shape automatically from what you submit, no configuration flag needed.

How much does the Chinese Name Analysis API cost?

Free tier: 50 requests/month. Pro: $11/month for 1,000 requests. Pro Plus: $21/month for 7,000 requests. Ultra: $37/month for 55,000 requests. Business: $99/month for 220,000 requests across all endpoints. Enterprise: $399+/month for unlimited volume with dedicated servers.

How do I integrate the Chinese Name Analysis API into my app?

POST surname and given_name (in Chinese characters) to /api/v3/chinese/name-analysis, optionally with birth_data for BaZi synergy. You get back the five grids, elements, 81數理 ratings, and 三才 verdict as JSON. Most developers integrate the name-only flow in under an hour.

What does the API return if I submit a non-Chinese name?

五格 numerology requires Chinese characters (漢字), since it is built on stroke counts. Romanized or Latin input returns a standardized 400 error explaining that the surname and given name must be submitted in Chinese characters, with the offending character identified when relevant.

Which programming languages support the API?

Full SDKs for JavaScript, Python, PHP, Ruby, Swift, and Kotlin. The REST API works with any language that can make HTTP requests, and we provide integration examples for React, Vue, and Flutter.

How fast is the Chinese Name Analysis API?

About 50ms average for name-only requests (five grids, elements, 81數理, and 三才), and under 300ms average when birth_data is included for full BaZi synergy scoring. Fast enough to score dozens of candidate names in a live name-suggestion tool.

Can I use this for baby naming apps?

Yes, it is one of the most common uses. Score and rank a list of candidate names by 81數理 rating and 三才 harmony, the same two checks a professional naming consultant runs by hand for expecting parents, then optionally cross-check against the child's BaZi chart once a birth time is available.

Is this useful for matchmaking or dating apps?

Yes. Matchmaking platforms serving Chinese-speaking markets pair name-fortune scoring with BaZi compatibility analysis to add a second signal to match quality. It is commonly combined with our Chinese BaZi API's compatibility features.

Can I use it to screen brand or company names?

Yes. Company and product naming in Chinese business culture routinely runs candidate names through 五格 and 三才 before filing. The API handles this the same way it handles personal names, since both use the same stroke-based calculation.

What data format does the API return?

Clean JSON with the name breakdown, all five grids (each with number, element, 81數理 rating, and meaning), the 三才 stack and verdict, and, when birth_data is supplied, a synergy object with the assessment, score, and recommendation text. A school field identifies the numerology method used for forward compatibility.

Where do the stroke counts and 81數理 meanings come from?

Stroke counts come from a Kangxi Dictionary (康熙字典) reference table covering over 60,000 characters, cross-verified against an authoritative Taiwanese name-analysis reference. 81數理 and 三才 rating text is authored in-house in native Traditional Chinese terminology, reviewed for accuracy rather than machine-translated from English.

Chinese Name Numerology API

The Chinese Name Analysis API for Five Grids Numerology

Score any Chinese name with 五格剖象法 (Five Grids), the method professional name consultants use.

Kangxi strokes, 81數理 ratings, 三才 harmony, and BaZi chart synergy in a single API call.

View Demo

~50ms

Name-Only Response

<300ms

With BaZi Synergy

Grids Per Name

數理 Ratings Covered

Built for baby-naming and matchmaking apps

99.95% SLA availability

Kumazaki (熊崎) Five-Grids method, Kangxi-verified strokes

Western name-validation APIs cannot count Kangxi strokes or read Chinese characters as numerology
Manual 五格 lookups mean flipping through stroke tables and 81數理 charts by hand for every candidate name
Naive stroke counters get Simplified characters wrong (刘 counted as 6 strokes instead of the correct traditional 劉 at 15)
Baby-naming and matchmaking apps have no way to check a name against a client's own BaZi chart
Existing tools stop at raw grid numbers with no 三才 harmony verdict or plain-language 81數理 meaning

Score names with

Kangxi stroke counting with automatic Simplified-to-Traditional restoration before the count
All five grids (天格/人格/地格/外格/總格) with Five Element mapping and 81數理 rating in one response
三才 (Three Talents) harmony verdict for the Heaven/Human/Earth element stack
Optional BaZi synergy: pass birth_data and get a supports/neutral/drains verdict with a 0-100 score
Compound surnames (歐陽, 司馬) and 1-2 character given names handled correctly out of the box

Built for Name Consultants and Baby-Naming Apps

Fast enough to power a live name-suggestion tool, not just a one-off report

<300ms

Name + BaZi Synergy

~50ms

Name-Only Response

Grids Per Name

81/81

81數理 Ratings Covered

Complete Five Grids Name Analysis

From Kangxi stroke counting to full BaZi chart synergy

Five Grids Calculation

Five Elements & 81數理

三才 Three Talents Analysis

BaZi Chart Synergy

Developer Experience

What is a Chinese Name Analysis API? Complete 五格 Guide

Everything developers need to know about Five Grids name numerology for baby-naming, matchmaking, and BaZi apps

What is Chinese name analysis? It scores a name's fortune by counting the brush strokes of its characters and running them through a formula. The method that dominates commercial name consulting is 五格剖象法 (Wuge Pouxiang Fa), the Five Grids system built on the Kumazaki (熊崎) school and used across Taiwan, Hong Kong, mainland China, and Chinese-speaking communities worldwide. Parents routinely pay a name consultant $50-200 to run this exact calculation before registering a newborn's name. Matchmaking services run it on both partners' names. Companies run it before registering a brand. Our Chinese Name Analysis API implements the full method behind a single REST call. It counts each character's Kangxi (康熙字典) strokes, the reference dictionary professional consultants use, builds five grids from the surname and given name, maps each grid to one of the Five Elements (Wood, Fire, Earth, Metal, Water), and looks up its 81數理 auspiciousness rating out of 81 possible fate numbers. It then reads the 三才 (Three Talents) configuration, how the Heaven, Human, and Earth grids interact as an element trio, to judge whether the name's internal structure is harmonious. The one feature no other name API offers: BaZi synergy. Send the same birth data you would send our BaZi (Four Pillars) endpoint, and the API cross-checks the name's dominant elements against the person's 喜用神 (favorable elements) from their actual chart, returning a supports, neutral, or drains verdict with a 0-100 score. That is the question every baby-naming client actually asks: does this name work for my child's chart? Response time stays under 300ms even with the full BaZi cross-check, fast enough to power a live suggestion tool that scores dozens of candidate names per session.

How does the Five Grids (五格) method work?

五格剖象法 builds five numbers from a name's stroke counts, then reads each one as fortune data.

The process: (1) count the Kangxi strokes of every character in the surname and given name, (2) apply one of four grid formulas depending on the name's shape (single or compound surname, one or two given-name characters), (3) reduce each grid number's last digit to a Five Element (1-2 Wood, 3-4 Fire, 5-6 Earth, 7-8 Metal, 9-0 Water), (4) reduce the raw number into the 1-81 range for the 81數理 lookup.

The five grids are 天格 (Heaven, ancestry and early luck), 人格 (Human, your core personality, calculated from the last surname character plus the first given-name character), 地格 (Earth, childhood and foundation), 外格 (Outer, social relationships), and 總格 (Total, life-long overall fortune).

Our API runs all four grid-shape formulas automatically based on how many characters you submit, so a single-character surname like 王 and a compound surname like 歐陽 both resolve correctly without any extra configuration.

5 grids, 4 name-shape formulas, one automatic calculation

1 min read

What is 三才 (Three Talents) and why does it matter?

三才 reads the elements of three grids, 天格 (Heaven), 人格 (Human), and 地格 (Earth), as a three-character stack, such as 土火土, and looks up how those elements interact.

There are 125 possible combinations, and each one carries a rating (from great auspicious down to great inauspicious) plus a plain-language verdict about how the name's early structure, personality, and foundation reinforce or clash with each other.

A name can have individually decent 81數理 grid ratings and still show a weak 三才 stack if the three elements fight instead of support each other, which is why professional consultants always check both layers, not just the grid numbers in isolation.

Our API returns the full 125-combination table pre-computed, so you get the exact 三才 key, its rating, and its meaning without maintaining a lookup table yourself.

125 Three Talents combinations, every one scored and explained

1 min read

What is 81數理 and how are the ratings determined?

81數理 is a scale of 81 fate numbers, each with an auspiciousness rating and a specific meaning rooted in classical numerology texts.

Every grid number in a name (天格, 人格, 地格, 外格, 總格) gets reduced into the 1-81 range using the Kumazaki convention (repeatedly subtracting 80 while the number exceeds 80, not a simple modulo), then looked up against the full 81-number table.

Ratings run on a five-class scale: great auspicious, auspicious, half auspicious, inauspicious, and great inauspicious.

A handful of numbers are disputed between schools of practice; our implementation follows the Traditional-Chinese convention (for example #21 明月中天 rated great auspicious with a documented caveat, #34 rated great inauspicious), matching what a Traditional-Chinese-speaking client would expect from a name consultation.

All 81 fate numbers, every grid, rated and explained in plain language

1 min read

How does BaZi synergy scoring work?

Supply birth_data (year, month, day, hour) alongside the name, and the API computes the person's BaZi (Four Pillars) chart and extracts their 喜用神, the elements the chart favors.

It then aggregates the name's own element profile, weighting 人格 (core personality) and 總格 (whole-life fortune) most heavily, followed by 地格 and 天格.

Comparing the two profiles through the Five Elements' generating (相生) and controlling (相剋) cycles produces one of three verdicts: supports (the name's elements generate or reinforce the chart's favorable elements), neutral, or drains (the name's elements match the chart's unfavorable elements or control the favorable ones).

Alongside the verdict you get a 0-100 score and short recommendation text, the same kind of judgment call a professional BaZi-and-name consultant would make manually across two separate consultations.

One API call replaces a two-session name-plus-BaZi consultation

1 min read

How accurate is the stroke counting for Simplified and Traditional characters?

五格 numerology is defined against Kangxi Dictionary (康熙字典) strokes, which are the Traditional-character stroke counts, not the modern Simplified ones.

A Simplified name like 刘德华 has to be restored to its Traditional form (劉德華) before counting, or the result is wrong: 刘 as typed has 6 Simplified strokes, but the numerology-correct count for 劉 is 15.

Our API restores Simplified input to Traditional automatically before running the stroke lookup, using a vendored character-conversion table, then counts against a Kangxi stroke table covering more than 60,000 characters.

Radical-sensitive characters (肉-radical characters like 育 and 能 count differently from moon-radical characters like 朋 and 朗, despite looking similar) are handled per-character rather than with a blanket rule, matching how professional consultants verify strokes by hand.

Kangxi-accurate strokes for both Simplified and Traditional input

1 min read

Who uses a Chinese Name Analysis API?

Baby-naming apps use it to score and rank candidate names for expecting parents, often generating dozens of name options and filtering by 81數理 and 三才 quality.

Matchmaking and dating platforms serving Chinese-speaking markets use it alongside BaZi compatibility to add a name-fortune layer to match scoring.

Astrology and numerology platforms that already offer BaZi (Four Pillars) readings add it as the natural next feature, since customers who get their chart read usually ask about their name next.

Brand-naming and company-registration consultants use it to screen candidate business names before filing.

Developers building Chinese-language content or education platforms use it to explain 五格 concepts interactively rather than with static articles.

The most-requested companion feature for existing BaZi customers

1 min read

Use Cases

Baby Naming Apps

Score and rank candidate names for expecting parents by 81數理 rating and 三才 harmony, the two checks a naming consultant runs by hand

Matchmaking & Compatibility Platforms

Add a name-fortune layer on top of BaZi compatibility scoring for Chinese-speaking dating and matchmaking apps

BaZi & Astrology Platforms

Pair with our BaZi (Four Pillars) endpoint to offer the name-vs-chart synergy check customers ask for after every BaZi reading

Brand & Company Name Screening

Run candidate business names through 五格 and 三才 before filing, the same pre-registration check used in Chinese business culture

Name-Change Consulting Tools

Compare a client's current name against proposed alternatives, with BaZi synergy showing which option actually supports their chart

Chinese-Language Education Platforms

Teach 五格剖象法 and 康熙字典 stroke counting interactively instead of with static reference articles

Technical Specifications

Endpoint	POST /api/v3/chinese/name-analysis
Response Time (name only)	~50ms average
Response Time (with BaZi synergy)	<300ms average
Grids Calculated	5 (天格/人格/地格/外格/總格)
Five Elements Mapped	Wood, Fire, Earth, Metal, Water
81數理 Coverage	All 81 fate numbers with rating and meaning
三才 Combinations	125 Heaven/Human/Earth element-stack verdicts
Name Shapes Supported	1+1, 1+2, 2+1, 2+2 (single and compound surnames)
Compound Surname Support	歐陽, 司馬, and other two-character surnames
Stroke Reference	Kangxi Dictionary (康熙字典) stroke table
Simplified-to-Traditional	Automatic restoration before stroke counting
BaZi Synergy	Optional, requires birth_data (year/month/day/hour)
Synergy Score Range	0-100 with supports/neutral/drains verdict
Language Support	English and Traditional Chinese (zh-Hant)
SDK Support	JavaScript, Python, PHP, Ruby, Swift, Kotlin

Chinese Name Analysis API Comparison

Feature	Astrology API	Others
Stroke Counting Method	Kangxi dictionary, Simplified restored to Traditional	Unicode stroke count (frequently wrong)
Grids Returned	All 5 (天/人/地/外/總格)	1-2 grids or none
81數理 Ratings	All 81, with meaning text per number	Not included or partial coverage
三才 Harmony Verdict	Included, 125 combinations	Not available
BaZi Chart Synergy	supports/neutral/drains verdict, 0-100 score	Not available
Compound Surnames	Fully supported (歐陽, 司馬)	Single-character surname only
Response Time	~50ms (name only), <300ms with synergy	1-3 seconds
Price	$11/month	$49-150/month or per-consultation fees
Free Tier	50 requests/month	None or trial-only

Related Chinese Astrology APIs

Chinese BaZi API

Four Pillars charts and 喜用神 favorable elements for name synergy

Chinese Horoscope API

Daily Chinese zodiac predictions

Chinese Zodiac API

12-animal zodiac sign calculations

Numerology Name API

Western name numerology calculations

Natal Chart API

Western astrology birth charts

API Documentation

Complete technical reference

References & Standards

Swiss Ephemeris (DE431-based) — astronomical calculations source
NASA JPL Planetary Ephemerides — underlying ephemeris dataset
International Astronomical Union (IAU) — body designation and nomenclature standards
IANA Time Zone Database — timezone & DST resolution

Simple, Transparent Pricing

Start free, scale as you grow. No hidden fees, no surprises.

Always Free

Start Free

Perfect for learning, testing, and small personal projects

50 API calls/month

Basic natal charts

5 house systems

Community support

Pro

$11/month

For small apps and personal projects

All basic endpoints
12 house systems
Email support

Best Value

Pro Plus

$21/month

For growing apps and medium traffic

All enhanced endpoints
18 house systems
AI interpretations
Priority email support

Ultra

$37/month

For professional astrology applications

Credit math ↓

All premium endpoints
23 house systems
Advanced AI interpretations
Priority support

High Volume Plans

For enterprise-scale applications

Business

$99/month

For high-volume applications

Credit math ↓

ALL endpoints
White-label ready
Custom AI fine-tuning
Phone support

UNLIMITED

Enterprise

$399+per month

Unlimited requests with dedicated infrastructure

Dedicated server infrastructure
Sub-300ms guaranteed
24/7 dedicated support
99.99% uptime SLA

All plans include comprehensive documentation and SDKs

Questions? Talk to our team

Frequently Asked Questions About Chinese Name Analysis API

Real answers about Five Grids name numerology calculations

Complete Your Chinese Astrology Stack

Chinese Name Analysis API works best paired with our other Chinese astrology tools. Add

BaZi Four Pillars calculations Chinese Horoscope features Chinese Zodiac calculations Western numerology analysis natal chart analysis

Start Scoring Names With

Join developers building baby-naming, matchmaking, and BaZi platforms. Kangxi-accurate Five Grids numerology in a modern JSON API.

Start Free View Documentation

30-day money-back

Kangxi-verified stroke counting

No setup fees

The Chinese Name Analysis API for Five Grids Numerology

Most Name APIs Cannot Score a Chinese Name

Complete Five Grids Name Analysis, One API Call

Built for Name Consultants and Baby-Naming Apps

Complete Five Grids Name Analysis

Five Grids Calculation

Five Elements & 81數理

三才 Three Talents Analysis

BaZi Chart Synergy

Developer Experience

What is a Chinese Name Analysis API? Complete 五格 Guide

How does the Five Grids (五格) method work?

What is 三才 (Three Talents) and why does it matter?

What is 81數理 and how are the ratings determined?

How does BaZi synergy scoring work?

How accurate is the stroke counting for Simplified and Traditional characters?

Who uses a Chinese Name Analysis API?

Use Cases

Baby Naming Apps

Matchmaking & Compatibility Platforms

BaZi & Astrology Platforms

Brand & Company Name Screening

Name-Change Consulting Tools

Chinese-Language Education Platforms

Technical Specifications

Chinese Name Analysis API Comparison

Related Chinese Astrology APIs

Chinese BaZi API

Chinese Horoscope API

Chinese Zodiac API

Numerology Name API

Natal Chart API

API Documentation

References & Standards

Simple, Transparent Pricing

Always Free

Pro

Pro Plus

Ultra

High Volume Plans

Business

Enterprise

Frequently Asked Questions About Chinese Name Analysis API

What is the Chinese Name Analysis API and how does it work?

What is 五格剖象法 (Five Grids)?

How is this different from the Chinese BaZi API?

How does the API count strokes for a Chinese name?

Does the API handle Simplified Chinese names?

What is the 81數理 rating system?

What is 三才 (Three Talents) and what does the verdict mean?

Can the API check a name against someone's BaZi chart?

Does the API support compound surnames like 歐陽 or 司馬?

What happens if I submit a 1-character given name vs a 2-character one?

How much does the Chinese Name Analysis API cost?

How do I integrate the Chinese Name Analysis API into my app?

What does the API return if I submit a non-Chinese name?

Which programming languages support the API?

How fast is the Chinese Name Analysis API?

Can I use this for baby naming apps?

Is this useful for matchmaking or dating apps?

Can I use it to screen brand or company names?

What data format does the API return?

Where do the stroke counts and 81數理 meanings come from?

Complete Your Chinese Astrology Stack

Start Scoring Names With

Most Name APIs Cannot Score a Chinese Name

Complete Five Grids Name Analysis, One API Call

Built for Name Consultants and Baby-Naming Apps

Complete Five Grids Name Analysis

Five Grids Calculation

Five Elements & 81數理

三才 Three Talents Analysis

BaZi Chart Synergy

Developer Experience

What is a Chinese Name Analysis API? Complete 五格 Guide

How does the Five Grids (五格) method work?

What is 三才 (Three Talents) and why does it matter?

What is 81數理 and how are the ratings determined?

How does BaZi synergy scoring work?

How accurate is the stroke counting for Simplified and Traditional characters?