API čínské metafyziky

53 endpointů ve čtyřech rodinách: BaZi (18), čínský kalendář a zvěrokruh (15), Zi Wei Dou Shu (14) a I Ching (6). Kalendář je odvozený z efemerid, ne z tabulek dat, proto funguje pro roky 2 až 2899 a nezávisí na tom, jestli někdo aktualizoval číselník.

Co je součástí

Rodina	Endpointů	Stav
BaZi: sloupy a analýza	18	Úplný klasický aparát
Kalendář, zvěrokruh, feng shui, Tung Shu	15	Odvozený z efemerid
Zi Wei Dou Shu	14	Rozmístění hvězd se počítá, jedenáct referenčních přehledů zůstává referenčními
I Ching	6	Hexagramy, hod mincemi, proměnlivé linie

Čím se to liší od bezplatné knihovny

Upřímná odpověď: pokud potřebuješ jen čtyři sloupy, vezmi lunar-typescript. Je pod MIT, počítá ve tvém procesu, offline, bez omezení frekvence a nic za to neplatíš.

Rozdíl začíná tam, kde knihovna končí.

Co	Knihovny pod MIT	AstroWay API
Čtyři sloupy, 藏干, 纳音, 十神	ano	ano
神煞 s oběma čteními tam, kde se školy rozcházejí	ne	ano
Interakce větví 刑冲合害	ne	ano
Síla denního pána v rámci 扶抑	ne	ano
Pravý sluneční čas jako samostatný výpočet	ne	ano
Létající hvězdy podle sezení a fasády, číslo Gua	ne	ano
Volba data Tung Shu s filtrem podle činnosti	ne	ano
Dvacet jedna jazyků	ne	ano
Jedna konvence pro PHP, JavaScript a Python zároveň	ne	ano

Poslední řádek je právě to, za co se obvykle platí. Tým, který má web v PHP, aplikaci v JavaScriptu a crony v Pythonu, jinak udržuje tři implementace hranice roku a dříve či později dostane tři různé odpovědi na jedno datum narození.

Konvence pojmenované nahlas

Čtyři osy, na kterých se kalkulačky rozcházejí, a žádná z nich není chyba. Většina implementací volí potichu; my volbu píšeme do odpovědi a udržujeme stránku konvencí s ověřením na externím CC0 datasetu.

Osa	Naše odpověď
Hranice roku	立春 Lichun, přesný okamžik z efemerid
Hranice dne	23:00, raný 子時 patří následujícímu dni
Pravý sluneční čas	ve výchozím stavu vypnutý, zapíná se příznakem
Letní čas	řeší ho timezoneOffset, který posílá klient

Příklad

curl

curl -X POST https://api.astroway.info/v1/bazi/chart \
  -H "X-Api-Key: $ASTROWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date":"1990-05-15","time":"14:30:00","timezoneOffset":3}'

TypeScript

import { Astroway } from '@astroway/sdk';

const aw = new Astroway({ apiKey: process.env.ASTROWAY_API_KEY! });

const r = await aw.client.POST('/bazi/chart', {
  body: { date: '1990-05-15', time: '14:30:00', timezoneOffset: 3 },
});
console.log(r.data?.data?.pillars.map((p) => p.pillar));
// [ 'Geng-Wu', 'Xin-Si', 'Geng-Chen', 'Gui-Wei' ]

Python

import os
from astroway import Astroway

aw = Astroway(api_key=os.environ["ASTROWAY_API_KEY"])

chart = aw.post("/bazi/chart", body={
    "date": "1990-05-15",
    "time": "14:30:00",
    "timezoneOffset": 3,
})
print([p["pillar"] for p in chart["pillars"]])
# ['Geng-Wu', 'Xin-Si', 'Geng-Chen', 'Gui-Wei']

Typované metody

Analytické cesty BaZi přibyly později než aktuální vydání SDK, proto typované metody aw.bazi.chart(...) zatím nejsou. Příklady výše používají surového klienta, který funguje s libovolnou cestou už dnes. Typované obálky přijdou s dalším vydáním SDK.

Hotová aplikace, kterou můžeš naklonovat

Živé demo a kód na GitHubu, MIT.

Dvě volání, POST /v1/bazi/chart za 20 kreditů a POST /v1/bazi/luck-pillars za 10, vracejí čtyři sloupy se skrytými kmeny, na-yin a dvanácti fázemi, denního pána s verdiktem síly, rovnováhu prvků, symbolické hvězdy, interakce větví a desetiletý cyklus Da Yun. Aplikace je vykreslí: rok vpravo jako v klasickém zápisu, sloupec dne je označený. Backend je jedna cesta a žádné závislosti, protože právě v tom je pointa: prohlížeč nemůže volat API přímo, takže klíč žije na serveru.

git clone https://github.com/astroway/starter-bazi
cd starter-bazi && npm install
cp .env.example .env     # your key goes here
npm run dev

Tři věci, které si z ní stojí za to vzít. Posílej název zóny, ne posun: Asia/Shanghai je k 1990-05-15 UTC+9, protože Čína v letech 1986 až 1991 používala letní čas. Posílej jazyk: výchozí je ukrajinština a anglická stránka bez něj dostane názvy prvků ve špatném jazyce. Posílej pohlaví: Da Yun jde podle něj dopředu, nebo dozadu, neutrální hodnota neexistuje.

Jazyky

Zvířata, prvky, jin a jang, paláce a dvanáct fází jsou přeloženy do 21 jazyků. Přidej ?lang=es a vedle anglického tokenu se objeví pole *Name. Anglická pole se nikdy nemění: lokalizace přidává, nenahrazuje.

Kmeny, větve, názvy hvězd a 纳音 se záměrně nepřekládají: jejich mezinárodním jménem je pinyin vedle znaku.

Sekce dokumentace

Přehled Co se počítá, co chybí a proč.

BaZi: čtyři sloupy Osmnáct endpointů a pět míst, kde se školy rozcházejí.

Zvěrokruh a kalendář Tři zvířata, lunární datum, dvacet čtyři termínů.

Zi Wei Dou Shu Rozmístění hvězd, dvanáct paláců a čtyři přepínače školy.

Konvence Čtyři osy a ověření na externím datasetu.

Časté otázky Neznámý čas narození, pravý sluneční čas, stav Zi Wei.

Létající hvězdy Devět paláců, období, sezení a fasáda.