Cómo construir una aplicación de astrología: guía completa para desarrolladores

** Nota del 2026-04-14, actualizado 2026-05-09.** TS / Python / PHP SDK ahora viven en public registries — @astroway/sdk (npm), astroway (PyPI), astroway/sdk (Packagist). Detalles en changelog.

¿Quieres hacer una aplicación astrológica? ¿De qué empezar? En esta guía — soluciones y código: desde la elección de la API hasta el despliegue de un producto funcional.

Preguntas de arquitectura

Antes de escribir código, ¿qué?: cálculos en el cliente o en el servidor?

Cliente (por ejemplo, Swiss Ephemeris WASM en el navegador):

Ventajas: sin costo por solicitud, funciona sin conexión, control total
Desventajas: ~2 MB WASM por cada usuario, licencia compleja (uso comercial de Swiss Ephemeris tiene restricciones), tú mismo mantienes el código de cálculo

API de servidor (AstroWay, Prokerala, etc.):

Ventajas: sin dependencias del cliente, paquete de aplicación pequeño, rápido en móviles, sin dolor de licencia
Desventajas: costo en créditos por solicitud, retraso en solicitudes “frías”

Para la mayoría de las aplicaciones, gana la API de servidor. Los usuarios móviles no esperarán 2 MB WASM; con las complejidades de licencia no vale la pena lidiar; y las API modernas cachearán solicitudes idénticas de forma gratuita (AstroWay hace un caché de 5 minutos con el encabezado X-Cache: HIT).

Elección de API

¿Qué es importante:

Precisión — busca Swiss Ephemeris “bajo el capó” (±1 segundo de arco). Si la API no lo dice directamente — pregunta.
Cobertura — natal + sinastria + tránsitos — mínimo. Progresiones y retornos — siguiente nivel. Técnicas raras (rectificación, Human Design) — esto es un diferenciador.
Calidad del SDK — TypeScript y Python SDK tipados ahorran horas.
Modelo de tarifa — credit-based escala mejor que per-request, en carga mixta.

Para este tutorial, tomaremos AstroWay API, porque tiene los cuatro (723 endpoint, Swiss Ephemeris, SDK tipados, credit-based).

Paso 1: Levantar backend

Nunca llames a la API astrológica directamente desde el navegador — tu clave de API se filtrará. Siempre pasa por tu propio backend.

mkdir my-astrology-app
cd my-astrology-app
npm init -y
npm install express @astroway/sdk zod
npm install -D typescript @types/express @types/node tsx

Crea src/server.ts:

import express from 'express';
import { Astroway } from '@astroway/sdk';
import { z } from 'zod';

const app = express();
app.use(express.json());

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

const BirthInput = z.object({
  date: z.string(),
  time: z.string(),
  timezoneOffset: z.number(),
  latitude: z.number(),
  longitude: z.number(),
});

app.post('/api/chart', async (req, res) => {
  const parsed = BirthInput.safeParse(req.body);
  if (!parsed.success) return res.status(400).json({ error: parsed.error });

  try {
    const chart = await client.chart({
      ...parsed.data,
      houseSystem: 'P',
    });
    res.json(chart);
  } catch (err) {
    res.status(500).json({ error: String(err) });
  }
});

app.listen(3000, () => console.log('http://localhost:3000'));

Inicia:

ASTROWAY_API_KEY=aw_test_... npx tsx src/server.ts

Verifica a través de curl:

curl -X POST http://localhost:3000/api/chart \
  -H "Content-Type: application/json" \
  -d '{"date":"1990-07-14","time":"14:30:00","timezoneOffset":3,"latitude":50.4501,"longitude":30.5234}'

Obtienes la carta natal completa en JSON.

Paso 2: Frontend

Cualquier framework sirve. Para el ejemplo — React con un formulario simple:

import { useState } from 'react';

type Chart = {
  planets: { name: string; longitude: number; sign: string; house: number }[];
  aspects: { planet1: string; planet2: string; type: string; orb: number }[];
};

export function NatalForm() {
  const [chart, setChart] = useState<Chart | null>(null);

  async function handleSubmit(formData: FormData) {
    const body = Object.fromEntries(formData.entries());
    const res = await fetch('/api/chart', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        date: body.date,
        time: body.time + ':00',
        timezoneOffset: Number(body.tz),
        latitude: Number(body.lat),
        longitude: Number(body.lng),
      }),
    });
    setChart(await res.json());
  }

  return (
    <div>
      <form action={handleSubmit}>
        <input name="date" type="date" required />
        <input name="time" type="time" required />
        <input name="tz" type="number" placeholder="Timezone offset (por ejemplo 3)" required />
        <input name="lat" type="number" step="0.0001" placeholder="Latitude" required />
        <input name="lng" type="number" step="0.0001" placeholder="Longitude" required />
        <button>Build chart</button>
      </form>

      {chart && (
        <div>
          <h2>Planets</h2>
          <ul>
            {chart.planets.map(p => (
              <li key={p.name}>{p.name}: {p.sign} (house {p.house})</li>
            ))}
          </ul>
          <h2>Aspects</h2>
          <ul>
            {chart.aspects.map((a, i) => (
              <li key={i}>{a.planet1} {a.type} {a.planet2} (orb {a.orb.toFixed(2)}°)</li>
            ))}
          </ul>
        </div>
      )}
    </div>
  );
}

Paso 3: Sinastria

Compatibilidad — la siguiente característica obvia. Agrega en src/server.ts:

const SynastryInput = z.object({
  chart1: BirthInput,
  chart2: BirthInput,
});

app.post('/api/synastry', async (req, res) => {
  const parsed = SynastryInput.safeParse(req.body);
  if (!parsed.success) return res.status(400).json({ error: parsed.error });

  const result = await client.synastry(parsed.data);
  res.json({
    score: result.compatibility.score,
    label: result.compatibility.label,
    aspects: result.crossAspects,
  });
});

Listo. Un endpoint, 50 créditos por llamada, devuelve score 0–100 y cross-aspects.

Paso 4: Horóscopos diarios

Para el compromiso de contenido, los horóscopos diarios son un “debe tener”. AstroWay los genera con datos reales de tránsitos:

app.post('/api/horoscope/daily', async (req, res) => {
  const parsed = BirthInput.safeParse(req.body);
  if (!parsed.success) return res.status(400).json({ error: parsed.error });

  const horoscope = await client.horoscopeDaily(parsed.data);
  res.json({
    text: horoscope.text,
    disclaimer: horoscope.disclaimer, // obligatorio guardar en UI!
  });
});

Importante: El contenido generado por AI contiene un disclaimer que debes mostrar a los usuarios (según los Términos de Servicio). No lo elimines.

Paso 5: Cache

Los horóscopos diarios son iguales para todos los usuarios con el mismo día de nacimiento y cartas natales similares. Cachea de forma agresiva:

import { LRUCache } from 'lru-cache';

const cache = new LRUCache<string, any>({ max: 1000, ttl: 86400 * 1000 });

app.post('/api/horoscope/daily', async (req, res) => {
  const key = JSON.stringify(req.body);
  const cached = cache.get(key);
  if (cached) return res.json(cached);

  const horoscope = await client.horoscopeDaily(req.body);
  cache.set(key, horoscope);
  res.json(horoscope);
});

En AstroWay también hay un caché de servidor integrado de 5 minutos (X-Cache: HIT), pero para contenido de larga duración se necesita un caché propio.

Paso 6: Despliegue

Cualquier plataforma sirve. Para un inicio rápido — Vercel o Railway:

# vercel.json
{ "functions": { "src/server.ts": { "runtime": "@vercel/node" } } }

En el panel de la plataforma, establece la variable de entorno ASTROWAY_API_KEY.

Planificación de presupuesto

Si has llegado hasta aquí — estima el consumo mensual de créditos antes del lanzamiento:

créditos/mes = DAU × (avg_charts_per_user × 20
                     + avg_sinastrias × 50
                     + avg_horóscopos × 20) × 30

Para 100 DAU con 1 carta + 1 horóscopo + 0.3 sinastrias por usuario por día:

100 × (20 + 20 + 0.3 × 50) × 30 = 165 000 créditos / mes

Esto es el plan Starter por $19/mes (200K créditos).

¿Qué sigue?

Características mejoradas que vale la pena agregar con el crecimiento:

Overlay de tránsitos — /v1/transits muestra las posiciones actuales de los planetas en la carta natal
Progresiones — /v1/progressions para arcos de desarrollo psicológico
Retorno solar — /v1/solar-return para “pronóstico para el año desde el cumpleaños”
Human Design — Human Design API abre todo un nuevo dominio funcional
Astrocartografía — /v1/acg mapea dónde el usuario debe vivir

Cada característica es difícil de implementar desde cero, pero — un desafío de API con AstroWay.

Comienzo

Obtén una clave de API gratuita — 10 000 créditos / mes
Referencia completa de la API — todos los 723 endpoint
Birth Chart API — documentación detallada del endpoint de la carta

AstroWay team

El equipo de ingeniería de AstroWay API. Envolvemos Swiss Ephemeris en REST puro y escribimos sobre los detalles aburridos que son realmente importantes.

// construye sobre esto

El mismo Swiss Ephemeris que en Solar Fire — en 4 líneas de código.

Clave gratuita sin tarjeta. 5 000 llamadas al mes antes del primer pago.

Obtener clave API → Documentación