API de metafísica china

53 endpoints en cuatro familias: BaZi (18), calendario y zodiaco chinos (15), Zi Wei Dou Shu (14) e I Ching (6). El calendario se deriva de las efemérides, no de tablas de fechas, así que funciona para los años del 2 al 2899 y no depende de que alguien haya actualizado una tabla de referencia.

Qué incluye

Familia	Endpoints	Estado
BaZi: pilares y análisis	18	Aparato clásico completo
Calendario, zodiaco, feng shui, Tong Shu	15	Derivado de las efemérides
Zi Wei Dou Shu	14	La colocación de las estrellas se calcula, once referencias siguen siendo referencias
I Ching	6	Hexagramas, lanzamiento de monedas, líneas mutantes

En qué se diferencia de una biblioteca gratuita

La respuesta honesta: si solo necesitas los cuatro pilares, usa lunar-typescript. Tiene licencia MIT, calcula en tu proceso, sin conexión, sin límites de frecuencia, y no hay que pagar por ello.

La diferencia empieza donde acaba la biblioteca.

Qué	Bibliotecas MIT	API de AstroWay
Cuatro pilares, 藏干, 纳音, 十神	sí	sí
神煞 con ambas lecturas donde las escuelas divergen	no	sí
Interacciones de ramas 刑冲合害	no	sí
Fuerza del maestro del día en el marco de 扶抑	no	sí
Tiempo solar verdadero como cálculo aparte	no	sí
Estrellas voladoras por asiento y fachada, número Gua	no	sí
Elección de fechas del Tong Shu con filtro por actividad	no	sí
Veintiún idiomas	no	sí
Una sola convención para PHP, JavaScript y Python a la vez	no	sí

La última fila es precisamente aquello por lo que se suele pagar. Un equipo con el sitio en PHP, la aplicación en JavaScript y los cron en Python mantiene, de otro modo, tres implementaciones del límite del año, y tarde o temprano obtiene tres respuestas distintas para una misma fecha de nacimiento.

Convenciones declaradas abiertamente

Cuatro ejes en los que las calculadoras divergen, y ninguno es un error. La mayoría de las implementaciones eligen en silencio; nosotros escribimos la elección en la respuesta y mantenemos una página de convenciones con una pasada sobre un dataset externo CC0.

Eje	Nuestra respuesta
Límite del año	立春 Lichun, el instante exacto según las efemérides
Límite del día	23:00, el 子時 temprano pertenece al día siguiente
Tiempo solar verdadero	desactivado por defecto, se activa con un indicador
Horario de verano	lo resuelve el timezoneOffset que envía el cliente

Ejemplo

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

Las rutas analíticas de BaZi llegaron después de la versión actual del SDK, así que todavía no hay métodos tipados aw.bazi.chart(...). Los ejemplos de arriba usan el cliente sin tipar, que ya funciona hoy con cualquier ruta. Los envoltorios tipados llegarán con la próxima versión del SDK.

Una aplicación lista para clonar

Demo en vivo y código en GitHub, MIT.

Dos llamadas, POST /v1/bazi/chart por 20 créditos y POST /v1/bazi/luck-pillars por 10, devuelven los cuatro pilares con los troncos ocultos, el na yin y las doce etapas, el maestro del día con el veredicto de fuerza, el equilibrio de elementos, las estrellas simbólicas, las interacciones de ramas y el ciclo decenal Da Yun. La aplicación los dibuja: el año a la derecha, como en la notación clásica, con la columna del día marcada. El backend es una sola ruta y ninguna dependencia, porque ahí está la clave: el navegador no puede llamar a la API directamente, así que la clave vive en el 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

Tres cosas que merece la pena llevarse de ella. Envía el nombre de la zona, no el desfase: Asia/Shanghai el 1990-05-15 es UTC+9, porque China tuvo horario de verano de 1986 a 1991. Envía el idioma: el predeterminado es el ucraniano, y una página en inglés sin él recibirá los nombres de los elementos en otro idioma. Envía el sexo: el Da Yun avanza o retrocede según él, no existe un valor neutro.

Idiomas

Animales, elementos, yin y yang, palacios y las doce etapas están traducidos a 21 idiomas. Añade ?lang=es y junto al token en inglés aparecerá un campo *Name. Los campos en inglés no cambian nunca: la localización añade, no sustituye.

Los troncos, las ramas, los nombres de las estrellas y 纳音 no se traducen a propósito: su nombre internacional es el pinyin junto al carácter chino.

Secciones de la documentación

Visión general Qué se calcula, qué no está y por qué.

BaZi: los cuatro pilares Dieciocho endpoints y cinco puntos en que las escuelas divergen.

Zodiaco y calendario Tres animales, la fecha lunar, veinticuatro términos.

Zi Wei Dou Shu Colocación de las estrellas, doce palacios y cuatro interruptores de escuela.

Convenciones Cuatro ejes y una pasada sobre un dataset externo.

Preguntas frecuentes Hora de nacimiento desconocida, tiempo solar verdadero, estado de Zi Wei.

Estrellas voladoras Nueve palacios, periodo, asiento y fachada.