Chinese Name Analysis API Launch: 五格剖象法 Scoring with BaZi Synergy

What shipped

That second part is the reason this endpoint exists. Anyone can count strokes. The question every parent, HR manager, or business owner actually has (does this name help or hurt me?) requires cross-referencing the name against the birth chart's 喜用神 (favorable elements). Most calculators online stop at the grids. This one doesn't.

Why this exists

姓名學 (name studies) is not a fringe belief system in Chinese-speaking markets. It is a default step in three categories of decision-making:

• Baby naming. New parents in Taiwan, Hong Kong, mainland China, Singapore, and the Chinese diaspora routinely pay a 命理師 (fortune-teller/consultant) or use an app to score name candidates before registering a birth certificate. Naming apps and hospital-adjacent services treat this as table stakes, not an add-on.
• Business and product naming. Company names, store names, and product names get run through the same Five Grids evaluation before launch. A "bad number" 總格 (Total Grid) is treated as a real business risk by a meaningful share of founders and investors in these markets.
• Matchmaking and dating. Matchmaking platforms already lean on BaZi compatibility between two people. Name analysis extends that: does a partner's or a couple's chosen child's name work with the family's chart, does a screen name or business alias clash with a founder's chart.

If your platform serves any of these categories (baby-naming apps, Chinese numerology sites, matchmaking services, HR/branding tools for the Chinese-speaking market), this endpoint is infrastructure you'd otherwise have to build from a stroke-count table, a 81數理 meaning list, and a Simplified-to-Traditional conversion layer, then wire it all into element theory by hand. We did that work so you don't have to.

What is 五格剖象法?

The five grids are:

Each grid number reduces to an element by its last digit (1-2 to Wood, 3-4 to Fire, 5-6 to Earth, 7-8 to Metal, 9-0 to Water), and separately maps to one of 81 numbered 數理 ratings: a fixed catalog where each number from 1 to 81 carries a specific meaning and an auspiciousness class (大吉 great-auspicious down to 大凶 great-inauspicious). Number 81 isn't a ceiling either; when a grid sum exceeds 81, the Kumazaki convention repeatedly subtracts 80 until it lands in range (82 becomes 2, 161 becomes 81), not a simple modulo.

How the calculation actually works

Stroke counting sounds trivial until you hit the edge cases that make or break accuracy. A few examples: the 月-radical is ambiguous between "moon" (4 strokes, as in 朗) and "flesh/肉" (6 strokes, as in 育, 能). Simplified characters need restoration to their Traditional form before counting, because 刘 (6 strokes as written) is not the same character as 劉 (15 Kangxi strokes); get that step wrong and every downstream grid is wrong. The API resolves both automatically: characters are converted Simplified-to-Traditional first, then looked up against a per-character Kangxi stroke table (not a blanket radical rule), so 情/打/狗/肝/郎/陽/福/神-style edge cases come out correct without you having to special-case anything.

Grid formulas depend on the shape of the name: how many characters are in the surname and how many in the given name (1+1, 1+2, 2+1, or 2+2, with compound surnames like 歐陽 or 司馬 driving the 2-character surname cases). The API detects the shape automatically from what you send and applies the matching formula set.

三才: the Three Talents

Once the Heaven, Human, and Earth grids each resolve to an element, those three elements stack into a triad, for example 土火土 (Earth-Fire-Earth), and that specific combination is looked up against a table of 125 documented 三才 configurations, each with its own rating and interpretation. This is a distinct evaluation from the individual grid ratings: a name can have decent individual grid numbers and still form a weak or clashing 三才 triad, or vice versa.

Worked example: 王美麗

Take the name 王美麗 (surname 王, given name 美麗) with a birth date supplied. Kangxi strokes: 王 = 5, 美 = 9, 麗 = 19.

1POST /api/v3/chinese/name-analysis
2{
3  "surname": "王",
4  "given_name": "美麗",
5  "birth_data": {
6    "date": "1990-04-15",
7    "time": "14:30",
8    "latitude": 25.033,
9    "longitude": 121.565
10  },
11  "options": { "language": "zh-Hant" }
12}

1{
2  "success": true,
3  "data": {
4    "name": {
5      "full": "王美麗",
6      "name_shape": "1+2"
7    },
8    "five_grids": {
9      "tian": { "number": 6, "element": "Earth", "rating": "great_auspicious" },
10      "ren":  { "number": 14, "element": "Fire", "rating": "inauspicious" },
11      "di":   { "number": 28, "element": "Metal", "rating": "half_auspicious" },
12      "wai":  { "number": 20, "element": "Water", "rating": "inauspicious" },
13      "zong": { "number": 33, "element": "Fire", "rating": "great_auspicious" }
14    },
15    "san_cai": {
16      "stack": ["Earth", "Fire", "Metal"],
17      "combo": "土火金",
18      "rating": "half_auspicious"
19    },
20    "synergy": {
21      "chart_favorable_elements": ["Wood", "Water"],
22      "name_dominant_elements": ["Fire", "Earth"],
23      "assessment": "drains",
24      "score": 38
25    },
26    "school": "wuge"
27  }
28}

The differentiator: BaZi synergy scoring

This is the part almost no public Chinese-name calculator does, because it requires two things at once: a working Five Elements/BaZi engine, and a defined method for scoring one name against a birth chart rather than just describing the name on its own.

1. Computes the person's chart and derives 喜用神 (favorable elements) using the same engine behind our BaZi API.
2. Builds a weighted element profile for the proposed name. The Human Grid (人格, the core of the person) and Total Grid (總格, whole-life) carry the most weight, followed by Earth and Outer Grids.
3. Applies 相生/相剋 (generating/controlling) cycle logic to compare the name's elements against the chart's favorable and unfavorable elements.
4. Returns one of three verdicts, supports, neutral, or drains, plus a 0-100 numeric score.

This turns a static numerology lookup into an actual compatibility check, which is the feature that separates a paid API from a free stroke-counter. If your product's pitch to end users is "we don't just count strokes, we check it against your chart," this endpoint is what makes that claim true instead of marketing copy.

Birth data is optional. Omit it and you get the full grid/三才 analysis with no synergy section, useful for products that only need name-on-its-own scoring, or as a lighter-weight first step before asking a user for birth details.

Handles the inputs real names actually have

• Compound surnames. 歐陽, 司馬, and other two-character surnames use the correct grid formula automatically (人格 is computed from the second surname character, per the Kumazaki convention).
• 1- and 2-character given names. Both are supported and detected from the input; you don't pass a "name shape" parameter.
• Simplified input. The API converts Simplified characters to Traditional before counting strokes, since stroke tables are keyed to the traditional/Kangxi form.
• Explicit errors, not silent wrong numbers. A name in Latin/pinyin, or containing a character missing from the stroke table, returns a standardized error naming the offending character. Nothing gets silently miscounted.

A natural pair with the BaZi API

1const bazi = await fetch('https://api.astrology-api.io/v1/chinese/bazi', {
2  method: 'POST',
3  headers: { 'Authorization': `Bearer ${process.env.ASTROLOGY_API_KEY}` },
4  body: JSON.stringify({ birth_data: birthData }),
5});
6
7const nameCheck = await fetch('https://api.astrology-api.io/v1/chinese/name-analysis', {
8  method: 'POST',
9  headers: { 'Authorization': `Bearer ${process.env.ASTROLOGY_API_KEY}` },
10  body: JSON.stringify({
11    surname: '王',
12    given_name: '美麗',
13    birth_data: birthData,
14  }),
15});

Who this is actually for

Three ICPs cover almost all the demand we see for this endpoint:

• Baby-naming apps and hospital-adjacent services. New-parent apps in Traditional and Simplified Chinese markets already collect the baby's projected surname and birth date/time (or due date, for pre-birth naming). Name Analysis slots directly into the "compare 5 candidate names" flow these apps already have, replacing a static reference table with real scoring.
• Matchmaking and relationship platforms. Products already running BaZi compatibility between two people can extend the same birth data to check a shared surname change, a couple's business name, or a child's proposed name against both parents' charts.
• Chinese numerology and 命理 content platforms. Sites that publish 姓名學 content or run consultation booking flows can turn a static blog post into an interactive scoring tool without hiring a stroke-count data team or licensing a GPL ratings database themselves.

A fourth, smaller pattern: HR and branding tools serving Chinese-speaking markets, where a company or product name gets the same 總格-driven scrutiny a person's name would.

How this compares to a free grid calculator

Free 五格 calculators are common. Search "姓名學" and dozens turn up. What they don't do, almost without exception, is check the name against an actual birth chart. They score the name as if it existed in a vacuum. That's a meaningfully weaker product for anyone building a paid naming consultation, a premium app feature, or a service where the name recommendation needs to be defensible to a customer who is also paying for a BaZi reading.

The other gap in most free tools is correctness on edge cases. Simplified-input restoration, compound surnames, and the 月/肉 radical ambiguity are exactly the places where a naive stroke-counting script gets the wrong number and nobody notices until a customer complains. Our stroke table is per-character, not rule-based, and the Simplified-to-Traditional layer runs before any counting happens, the same discipline that makes the rest of the astrology API accurate at the character level, not just the concept level.

Languages

Pricing

Where to learn more

• Companion product: /p/chinese-bazi
• Full API reference and request/response schema: /docs
• Get an API key: /signup

What's next