API di metafisica cinese

53 endpoint in quattro famiglie: BaZi (18), calendario e zodiaco cinesi (15), Zi Wei Dou Shu (14) e I Ching (6). Il calendario è derivato dalle effemeridi, non da tabelle di date, quindi funziona per gli anni dal 2 al 2899 e non dipende dal fatto che qualcuno abbia aggiornato un riferimento.

Cosa include

Famiglia	Endpoint	Stato
BaZi: pilastri e analisi	18	Apparato classico completo
Calendario, zodiaco, feng shui, Tong Shu	15	Derivato dalle effemeridi
Zi Wei Dou Shu	14	La disposizione delle stelle viene calcolata, undici riferimenti restano riferimenti
I Ching	6	Esagrammi, lancio delle monete, linee mutevoli

In cosa differisce da una libreria gratuita

La risposta onesta: se ti servono solo i quattro pilastri, usa lunar-typescript. È sotto MIT, calcola nel tuo processo, offline, senza limiti di frequenza, e non devi pagare nulla.

La differenza comincia dove la libreria finisce.

Cosa	Librerie sotto MIT	API AstroWay
Quattro pilastri, 藏干, 纳音, 十神	sì	sì
神煞 con entrambe le letture dove le scuole divergono	no	sì
Interazioni dei rami 刑冲合害	no	sì
Forza del signore del giorno nel quadro 扶抑	no	sì
Tempo solare vero come calcolo separato	no	sì
Stelle volanti per seduta e facciata, numero Gua	no	sì
Scelta della data Tong Shu con filtro per attività	no	sì
Ventuno lingue	no	sì
Una sola convenzione per PHP, JavaScript e Python contemporaneamente	no	sì

L’ultima riga è proprio ciò per cui di solito si paga. Un team con il sito in PHP, l’app in JavaScript e i cron in Python altrimenti mantiene tre implementazioni del confine dell’anno e prima o poi ottiene tre risposte diverse per la stessa data di nascita.

Convenzioni dichiarate apertamente

Quattro assi su cui i calcolatori divergono, e nessuno di essi è un errore. La maggior parte delle implementazioni sceglie in silenzio; noi scriviamo la scelta nella risposta e manteniamo una pagina delle convenzioni con un confronto su un dataset esterno CC0.

Asse	La nostra risposta
Confine dell’anno	立春 Lichun, l’istante esatto dalle effemeridi
Confine del giorno	23:00, il primo 子時 appartiene al giorno successivo
Tempo solare vero	disattivato di default, si attiva con un flag
Ora legale	risolta da timezoneOffset, inviato dal client

Esempio

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

Metodi tipizzati

Le rotte analitiche del BaZi sono arrivate dopo l’attuale release dell’SDK, quindi i metodi tipizzati aw.bazi.chart(...) per ora non ci sono. Gli esempi sopra usano il client grezzo, che funziona con qualsiasi percorso già oggi. I wrapper tipizzati arriveranno con la prossima release dell’SDK.

Un’app pronta da clonare

Demo dal vivo e codice su GitHub, MIT.

Due chiamate, POST /v1/bazi/chart a 20 crediti e POST /v1/bazi/luck-pillars a 10, restituiscono i quattro pilastri con i tronchi nascosti, il nayin e i dodici stadi, il signore del giorno con il verdetto sulla forza, l’equilibrio degli elementi, le stelle simboliche, le interazioni dei rami e il ciclo decennale Da Yun. L’app li disegna: l’anno a destra, come nella scrittura classica, con la colonna del giorno evidenziata. Il backend è una sola rotta e nessuna dipendenza, perché il punto è proprio lì: il browser non può chiamare l’API direttamente, quindi la chiave vive sul 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

Tre cose che vale la pena portarsi via. Invia il nome del fuso, non lo scostamento: Asia/Shanghai il 1990-05-15 è UTC+9, perché la Cina ha adottato l’ora legale dal 1986 al 1991. Invia la lingua: quella di default è l’ucraino, e una pagina inglese senza di essa riceverà i nomi degli elementi nella lingua sbagliata. Invia il sesso: il Da Yun va avanti o indietro a seconda di esso, un valore neutro non esiste.

Lingue

Animali, elementi, yin e yang, palazzi e dodici stadi sono tradotti in 21 lingue. Aggiungi ?lang=es e accanto al token inglese comparirà un campo *Name. I campi inglesi non cambiano mai: la localizzazione aggiunge, non sostituisce.

Tronchi, rami, nomi delle stelle e 纳音 volutamente non vengono tradotti: il loro nome internazionale è il pinyin accanto all’ideogramma.

Sezioni della documentazione

Panoramica Cosa viene calcolato, cosa manca e perché.

BaZi: quattro pilastri Diciotto endpoint e cinque punti in cui le scuole divergono.

Zodiaco e calendario Tre animali, data lunare, ventiquattro termini solari.

Zi Wei Dou Shu Disposizione delle stelle, dodici palazzi e quattro selettori di scuola.

Convenzioni Quattro assi e confronto su un dataset esterno.

Domande frequenti Ora di nascita sconosciuta, tempo solare vero, stato di Zi Wei.

Stelle volanti Nove palazzi, periodo, seduta e facciata.