API voor Chinese metafysica

53 endpoints in vier families: BaZi (18), de Chinese kalender en dierenriem (15), Zi Wei Dou Shu (14) en I Ching (6). De kalender is afgeleid uit de efemeriden, niet uit datumtabellen, dus hij werkt voor de jaren 2 tot en met 2899 en hangt er niet van af of iemand een naslagwerk heeft bijgewerkt.

Wat erin zit

Familie	Endpoints	Status
BaZi: pilaren en analyse	18	Volledig klassiek apparaat
Kalender, dierenriem, feng shui, Tong Shu	15	Afgeleid uit de efemeriden
Zi Wei Dou Shu	14	De plaatsing van de sterren wordt berekend, elf naslagwerken blijven naslagwerken
I Ching	6	Hexagrammen, muntworp, veranderende lijnen

Waarin dit verschilt van een gratis bibliotheek

Het eerlijke antwoord: heb je alleen de vier pilaren nodig, neem dan lunar-typescript. Die staat onder MIT, rekent in je eigen proces, offline, zonder frequentielimieten, en je hoeft er niet voor te betalen.

Het verschil begint waar de bibliotheek ophoudt.

Wat	Bibliotheken onder MIT	AstroWay API
Vier pilaren, 藏干, 纳音, 十神	ja	ja
神煞 met beide lezingen waar scholen uiteenlopen	nee	ja
Interacties van takken 刑冲合害	nee	ja
Kracht van de dagmeester in het kader 扶抑	nee	ja
Ware zonnetijd als aparte berekening	nee	ja
Vliegende sterren volgens zit en gevel, het Gua-getal	nee	ja
Datumkeuze volgens Tong Shu met een filter op activiteit	nee	ja
Eenentwintig talen	nee	ja
Eén conventie voor PHP, JavaScript en Python tegelijk	nee	ja

De laatste rij is precies waar meestal voor wordt betaald. Een team met een site in PHP, een app in JavaScript en crons in Python houdt anders drie implementaties van de jaargrens bij en krijgt vroeg of laat drie verschillende antwoorden op één geboortedatum.

Conventies hardop benoemd

Vier assen waarop calculators uiteenlopen, en geen daarvan is een fout. De meeste implementaties kiezen stilletjes; wij schrijven de keuze in de response en houden een conventiepagina bij met een run tegen een externe CC0-dataset.

As	Ons antwoord
Jaargrens	立春 Lichun, het exacte moment uit de efemeriden
Daggrens	23:00, het vroege 子時 hoort bij de volgende dag
Ware zonnetijd	standaard uit, aan te zetten met een vlag
Zomertijd	opgelost door de timezoneOffset die de client meestuurt

Voorbeeld

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']

Getypeerde methoden

De analytische BaZi-routes zijn later verschenen dan de huidige SDK-release, dus getypeerde methoden als aw.bazi.chart(...) zijn er nog niet. De voorbeelden hierboven gebruiken de ruwe client, die vandaag al met elk pad werkt. Getypeerde wrappers komen met de volgende SDK-release.

Een kant-en-klare app om te klonen

Live demo en code op GitHub, MIT.

Twee aanroepen, POST /v1/bazi/chart voor 20 credits en POST /v1/bazi/luck-pillars voor 10, geven de vier pilaren met verborgen stammen, nayin en twaalf stadia, de dagmeester met een krachtoordeel, de balans van de elementen, symbolische sterren, interacties van takken en de tienjarige cyclus Da Yun. De app tekent ze: het jaar rechts, zoals in de klassieke notatie, de kolom van de dag gemarkeerd. De backend is één route zonder afhankelijkheden, want daar draait het om: de browser kan de API niet rechtstreeks aanroepen, dus de sleutel leeft op de server.

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

Drie dingen om eruit mee te nemen. Stuur een zonenaam, geen verschuiving: Asia/Shanghai op 1990-05-15 is UTC+9, omdat China van 1986 tot 1991 zomertijd aanhield. Stuur een taal mee: de standaard is Oekraïens, en een Engelse pagina zonder die parameter krijgt de namen van de elementen in de verkeerde taal. Stuur het geslacht mee: Da Yun loopt afhankelijk daarvan vooruit of achteruit, een neutrale waarde bestaat niet.

Talen

Dieren, elementen, yin en yang, paleizen en de twaalf stadia zijn vertaald in 21 talen. Voeg ?lang=es toe en naast het Engelse token verschijnt een veld *Name. De Engelse velden veranderen nooit: lokalisatie voegt toe, ze vervangt niet.

Stammen, takken, sternamen en 纳音 worden bewust niet vertaald: hun internationale naam is de pinyin naast het karakter.

Secties van de documentatie

Overzicht Wat er wordt berekend, wat er niet is en waarom.

BaZi: vier pilaren Achttien endpoints en vijf plekken waar scholen uiteenlopen.

Dierenriem en kalender Drie dieren, de maandatum, vierentwintig zonnetermijnen.

Zi Wei Dou Shu De plaatsing van de sterren, twaalf paleizen en vier schoolschakelaars.

Conventies Vier assen en een run tegen een externe dataset.

Veelgestelde vragen Onbekende geboortetijd, ware zonnetijd, de status van Zi Wei.

Vliegende sterren Negen paleizen, periode, zit en gevel.