API de metafísica chinesa

53 endpoints em quatro famílias: BaZi (18), calendário e zodíaco chineses (15), Zi Wei Dou Shu (14) e I Ching (6). O calendário é derivado das efemérides, e não de tabelas de datas, por isso funciona para os anos de 2 a 2899 e não depende de alguém ter atualizado uma referência.

O que está incluído

Família	Endpoints	Estado
BaZi: pilares e análise	18	Aparato clássico completo
Calendário, zodíaco, feng shui, Tong Shu	15	Derivado das efemérides
Zi Wei Dou Shu	14	A disposição das estrelas é calculada, onze referências continuam a ser referências
I Ching	6	Hexagramas, lançamento de moedas, linhas mutáveis

Em que difere de uma biblioteca gratuita

A resposta honesta: se só precisas dos quatro pilares, usa lunar-typescript. Tem licença MIT, calcula no teu processo, offline, sem limites de frequência, e não tens de pagar nada por isso.

A diferença começa onde a biblioteca acaba.

O quê	Bibliotecas sob MIT	AstroWay API
Quatro pilares, 藏干, 纳音, 十神	sim	sim
神煞 com as duas leituras onde as escolas divergem	não	sim
Interações dos ramos 刑冲合害	não	sim
Força do mestre do dia no quadro 扶抑	não	sim
Tempo solar verdadeiro como cálculo à parte	não	sim
Estrelas voadoras por assento e fachada, número Kua	não	sim
Escolha de data Tong Shu com filtro por atividade	não	sim
Vinte e um idiomas	não	sim
Uma só convenção para PHP, JavaScript e Python ao mesmo tempo	não	sim

A última linha é precisamente aquilo por que normalmente se paga. Uma equipa com o site em PHP, a aplicação em JavaScript e os crons em Python acaba de outro modo com três implementações do limite do ano e, mais cedo ou mais tarde, três respostas diferentes para a mesma data de nascimento.

Convenções ditas em voz alta

Quatro eixos em que as calculadoras divergem, e nenhum deles é um erro. A maioria das implementações escolhe em silêncio; nós escrevemos a escolha na resposta e mantemos uma página de convenções com uma verificação contra um dataset externo CC0.

Eixo	A nossa resposta
Limite do ano	立春 Lichun, o instante exato a partir das efemérides
Limite do dia	23:00, o 子時 precoce pertence ao dia seguinte
Tempo solar verdadeiro	desligado por omissão, ativa-se com uma flag
Hora de verão	resolvida pelo timezoneOffset que o cliente envia

Exemplo

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

Métodos tipados

As rotas analíticas do BaZi surgiram depois da versão atual do SDK, por isso ainda não há métodos tipados aw.bazi.chart(...). Os exemplos acima usam o cliente bruto, que já hoje funciona com qualquer caminho. Os wrappers tipados chegam com a próxima versão do SDK.

Uma aplicação pronta que podes clonar

Demo ao vivo e código no GitHub, MIT.

Duas chamadas, POST /v1/bazi/chart por 20 créditos e POST /v1/bazi/luck-pillars por 10, devolvem os quatro pilares com os troncos ocultos, o nayin e as doze fases, o mestre do dia com o veredicto de força, o equilíbrio dos elementos, as estrelas simbólicas, as interações dos ramos e o ciclo decenal Da Yun. A aplicação desenha-os: o ano à direita, como no registo clássico, e a coluna do dia assinalada. O backend é uma única rota e nenhuma dependência, porque é aí que está o essencial: o navegador não pode chamar a API diretamente, por isso a chave vive no servidor.

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

Três coisas que vale a pena levar daqui. Envia o nome da zona, não o desvio: Asia/Shanghai a 1990-05-15 é UTC+9, porque a China teve hora de verão de 1986 a 1991. Envia o idioma: o predefinido é o ucraniano, e uma página em inglês sem ele recebe os nomes dos elementos no idioma errado. Envia o sexo: o Da Yun avança ou recua consoante ele, não existe valor neutro.

Idiomas

Animais, elementos, yin e yang, palácios e as doze fases estão traduzidos em 21 idiomas. Acrescenta ?lang=es, e ao lado do token inglês aparece um campo *Name. Os campos em inglês nunca mudam: a localização acrescenta, não substitui.

Troncos, ramos, nomes das estrelas e 纳音 não são traduzidos de propósito: o seu nome internacional é o pinyin ao lado do caractere.

Secções da documentação

Visão geral O que é calculado, o que não existe e porquê.

BaZi: os quatro pilares Dezoito endpoints e cinco pontos em que as escolas divergem.

Zodíaco e calendário Três animais, data lunar, vinte e quatro termos.

Zi Wei Dou Shu Disposição das estrelas, doze palácios e quatro opções de escola.

Convenções Quatro eixos e uma verificação contra um dataset externo.

Perguntas frequentes Hora de nascimento desconhecida, tempo solar verdadeiro, estado do Zi Wei.

Estrelas voadoras Nove palácios, período, assento e fachada.