KASI Data and Solar Term Precision --- When Minutes Change Your Destiny

 

You Need the "Time," Not Just the "Date"

Part 6 covered how Saju uses its own calendar system based on Solar Terms (Jeolgi, 節氣). This time, I want to talk about where and how I sourced the critical ingredient of that system: Solar Term data. The key lesson here was that "the source of your data is the credibility of your app."

I knew from the start that Solar Term data was needed. The real question was what level of data. "The Start of Spring is around February 4" is not good enough. As Part 6 showed, determining the Year Pillar for someone born on the day of the Start of Spring requires knowing that "the 2024 Start of Spring is February 4 at 16:27" --- minute-level precision. Multiplied across 12 Solar Terms (the "Jie" nodes) per year, for 130 years from 1920 to 2050, that is a significant data requirement.

Where to get this data? I could have copied Solar Term tables floating around the internet. But something I confirmed during the Part 1 benchmarking stuck with me: every professional app that differentiated itself on accuracy used data from the Korea Astronomy and Space Science Institute (KASI). Apps built on data of unclear provenance --- no matter how sophisticated their analysis logic --- rest on shaky foundations.

Why KASI?

The Korea Astronomy and Space Science Institute (KASI) is South Korea's official astronomy agency. It provides astronomical data including Solar Term times as public data, with precision grounded in astronomical calculation. The credibility gap between this and personal Manselyeok tables or internet data of unknown origin is enormous.

Three reasons made the KASI choice decisive. First, authority. As official data from a government research institute, it serves as a trust anchor for the app's accuracy claims. Second, precision. Solar Term times are provided to the minute, meeting Saju's requirements. Third, range. Coverage spans from historical dates to future projections --- sufficient for any realistic birth year.

Being able to state in the app "Solar Term data in this app is based on Korea Astronomy and Space Science Institute standards" makes a real difference from a user trust perspective. "Data from an unknown source" versus "data from a national scientific institution" --- even if the numbers are identical, they carry different weight.

Build-Time Collection: A Strategic Choice

There were options for how to access KASI data at runtime. The simplest: call the KASI API in real time every time a user looks up their chart. But this approach has critical flaws.

First, if the API goes down, the app stops working. Public APIs can have maintenance windows or rate limits. A user opening the app to check their chart only to see "Server connection failed" destroys trust. Second, response times slow down. Network requests can take hundreds of milliseconds to seconds. Adding that latency just to look up a Solar Term time is unacceptable from a UX standpoint. Third, it does not work offline.

So I chose build-time collection. At build time, a script collects 130 years' worth of Solar Term data (1920--2050) in bulk and saves it as a JSON file. This JSON ships inside the app bundle, so at runtime the app queries local data instantly with no network requests.

You might worry about the data size of 130 years of 24 Solar Terms. In reality: 130 years times 24 Solar Terms equals 3,120 date-time pairs. That is tens of kilobytes as JSON. The impact on bundle size is negligible. For this tiny footprint, you get three benefits: offline capability, API-failure resilience, and instant response.

Designing the Collection Script

I wrote a Node.js script for build-time collection. It integrates into the Vite build process as a plugin, ensuring fresh data on every build. In practice, since Solar Term data is the output of astronomical calculations, it does not change once collected. The script's primary role is closer to "one-time collection + data integrity verification."

The collected data structure is straightforward: an object keyed by year, with each year's value being an array of 24 Solar Terms. Each Solar Term entry includes the term name, Gregorian date, and time (hour:minute). While Saju only uses the 12 "Jie" nodes out of the 24, storing all 24 is better for data completeness and future extensibility.

AI collaboration helped here too. Analyzing the KASI public data API structure and transforming the response data into a format convenient for the app was done together with Claude. The AI's proactive flagging of edge cases --- such as year-end Solar Terms rolling over into the next calendar year --- helped prevent actual bugs.

Real Cases Where Minutes Change a Chart

Let me illustrate with concrete examples why precise Solar Term timing matters.

The 2024 Start of Spring is February 4 at 16:27. Compare a child born at 16:00 that day with one born at 17:00. The 16:00 birth is before the Start of Spring, so the Year Pillar is Gye-Myo year (癸卯年). The 17:00 birth is after, so it is Gap-Jin year (甲辰年). In zodiac terms, Rabbit versus Dragon.

A different Year Pillar means a different Year Stem, which means different Ten Gods for the Year Pillar. The Year Pillar's Ten Gods relate to interpretations of "ancestral palace" --- early-life fortune and social environment. One minute's difference can shift the tone of the entire reading.

The same situation arises with the Month Pillar. The 2024 Awakening of Insects falls on March 5 at 10:23. Around that exact time, the Saju month changes. For people born right at a Solar Term boundary, minute-level precision is the difference between "two different charts."

These cases are precisely why "approximate" Solar Term data will not do --- KASI-level precision is essential. Knowing only "February 4 is the Start of Spring" makes it impossible to adjudicate boundary-time births.

AI Organizing a Library Comparison Table

One moment where AI collaboration proved especially effective during Manselyeok implementation: when I asked Claude, "Compare the available methods for handling Korean Solar Term data in JavaScript/TypeScript."

The comparison table AI produced covered NPM packages, the KASI public API, direct calculation (astronomical formulas), and more --- each option listed with pros, cons, precision level, data range, maintenance status, and Korean language support at a glance. The moment I saw this table, the conclusion "collect KASI data at build time" fell out naturally.

Had I done this comparison on my own, installing each library, reading documentation, and writing test code would have taken at least half a day. AI produced the comparison table in 10 minutes, freeing that time for actual implementation. Of course, I did not take the AI comparison at face value --- I wrote and verified the code for the chosen approach myself. But the efficiency at the "narrowing down options" stage was overwhelming.

This experience demonstrates one of the most practical patterns for AI collaboration. You do not delegate the "decision" to AI --- you delegate the "comparative analysis" and keep the decision for yourself. AI excels at rapidly collecting and structuring information; the human factors in project context and constraints to make the final call.

Data Integrity Verification

How do you confirm that build-time-collected data is actually correct? I applied two verification methods.

First, comparison against known values. I manually checked specific years' Start of Spring, Awakening of Insects, and other Solar Term times on the KASI website, then compared them against the values stored in JSON. At least 10 years were sampled for cross-verification.

Second, comparison against professional Manselyeok apps. I cross-referenced the Solar Term times displayed by apps from the Part 1 benchmarking against our data. Apps that explicitly stated they used KASI data matched exactly. Apps that did not occasionally showed 1--2 minute discrepancies. These discrepancies are precisely the "data source differences," and they confirmed that choosing the KASI standard was the right call.

This level of obsession with data accuracy might seem excessive. But in a Saju app, Manselyeok data is like a building's foundation. If the foundation shifts by 1 centimeter, the 10th floor is off by dozens of centimeters. If a Solar Term time is off by 1 minute, the entire chart of someone born at the boundary is wrong. You cannot over-verify foundational data.

What I Learned Along the Way

First, the source of your data is the credibility of your app. Even if the number "2024 Start of Spring: February 4, 16:27" is the same, whether it came from KASI or an internet table of unknown provenance carries different weight.

Second, build-time data collection is a highly effective strategy for small volumes of static data. There is no reason to call an API at runtime for 3,120 Solar Term entries.

Third, AI's comparative analysis capability delivers the most value at the "narrowing options" stage. The human makes the final decision, but AI handles the information gathering and structuring.

Fourth, data integrity verification should combine automation and manual inspection. Scripts check format; humans cross-reference samples. This dual verification raises confidence.

Next Up

Manselyeok data is secured. But Saju calculation has yet another wall: "time corrections." True Solar Time correction from the gap between KST and the sun's actual position, Korea's historical Daylight Saving Time, and the Late Night Hour (Yajasi) problem of splitting the Hour of the Rat in two. Part 8 covers how these three corrections change the Hour Pillar, and why "ambiguity of rules" is harder than algorithm complexity.