Como construir um aplicativo de astrologia: guia completo para desenvolvedores

** Nota de 2026-04-14, atualizado 2026-05-09.** TS / Python / PHP SDK agora vivem em public registries — @astroway/sdk (npm), astroway (PyPI), astroway/sdk (Packagist). Detalhes em changelog.

Queres fazer um aplicativo astrológico. Por onde começar? Neste guia — soluções e código: desde a escolha da API até o deploy de um produto funcional.

Perguntas de arquitetura

Antes de escrever código, pergunta: cálculos no cliente ou no servidor?

Cliente (por exemplo, Swiss Ephemeris WASM no navegador):

Prós: sem custo por solicitação, funciona offline, controle total
Contras: ~2 MB WASM por usuário, licenciamento complexo (uso comercial do Swiss Ephemeris tem restrições), você mesmo mantém o código de cálculo

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

Prós: sem dependências do cliente, bundle de aplicativo pequeno, rápido no móvel, sem dor de cabeça com licenças
Contras: custo em créditos por solicitação, atraso em solicitações “frias”

Para a maioria dos aplicativos, a API do servidor é a melhor escolha. Os usuários móveis não esperarão 2 MB WASM; com nuances de licenciamento não vale a pena se preocupar; e as APIs modernas cacheiam solicitações idênticas gratuitamente (AstroWay faz cache de 5 minutos com o cabeçalho X-Cache: HIT).

Escolha da API

O que importa:

Precisão — procure Swiss Ephemeris “sob o capô” (±1 segundo angular). Se a API não disser isso diretamente — pergunte.
Cobertura — natal + sinastria + transits — mínimo. Progressões e retornos — próximo nível. Técnicas raras (retificação, Human Design) — diferenciador.
Qualidade do SDK — TypeScript e Python SDKs tipados economizam horas.
Modelo de tarifa — baseado em créditos escala melhor do que por solicitação, em carga mista.

Para este tutorial, vamos usar AstroWay API, pois ele tem os quatro (723 endpoint, Swiss Ephemeris, SDKs tipados, baseado em créditos).

Passo 1: Subir o backend

Nunca chame a API astrológica diretamente do navegador — sua chave de API vazará. Sempre passe pelo seu 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

Crie 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'));

Inicie:

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

Verifique com 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}'

Receba a carta natal completa em JSON.

Passo 2: Frontend

Qualquer framework serve. Para exemplo — React com um formulário simples:

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 exemplo 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>
  );
}

Passo 3: Sinastria

Compatibilidade — próxima funcionalidade óbvia. Adicione em 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,
  });
});

Pronto. Um endpoint, 50 créditos por chamada, retorna score 0–100 e cross-aspects.

Passo 4: Horóscopos diários

Para engajamento de conteúdo, horóscopos diários — must have. AstroWay gera-os com dados reais de transits:

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, // obrigatório manter no UI!
  });
});

Importante: Conteúdo gerado por AI contém disclaimer, que você é obrigado a mostrar aos usuários (de acordo com os Termos de Serviço). Não remova.

Passo 5: Cache

Horóscopos diários são iguais para todos os usuários com o mesmo dia de nascimento e cartas natais semelhantes. Cache agressivamente:

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);
});

No AstroWay, também há cache de servidor embutido de 5 minutos (X-Cache: HIT), mas para conteúdo de longa duração, é necessário um cache próprio.

Passo 6: Deploy

Qualquer plataforma serve. Para um início rápido — Vercel ou Railway:

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

No painel da plataforma, configure o env ASTROWAY_API_KEY.

Planejamento de orçamento

Se chegou até aqui — avalie o consumo mensal de créditos antes do lançamento:

créditos/mês = DAU × (avg_charts_por_usuario × 20
                     + avg_sinastrias × 50
                     + avg_horóscopos × 20) × 30

Para 100 DAU com 1 carta + 1 horóscopo + 0,3 sinastrias por usuário por dia:

100 × (20 + 20 + 0,3 × 50) × 30 = 165 000 créditos / mês

Isso é plano Starter por $19/mês (200K créditos).

O que fazer em seguida

Funcionalidades avançadas que vale a pena adicionar com o crescimento:

Sobreposição de transits — /v1/transits mostra posições atuais dos planetas na carta natal
Progressões — /v1/progressions para arcos de desenvolvimento psicológico
Retorno solar — /v1/solar-return para “previsão para o ano do aniversário”
Human Design — Human Design API abre um novo domínio funcional
Astrocartografia — /v1/acg mapeia onde o usuário deve viver

Cada funcionalidade é difícil de implementar do zero, mas — um desafio de API com AstroWay.

Início

Obtenha uma chave de API gratuita — 10 000 créditos / mês
Referência completa da API — todos os 723 endpoint
API de Carta Natal — documentação detalhada do endpoint da carta

AstroWay team

Equipe de engenharia da AstroWay API. Nós embrulhamos o Swiss Ephemeris em REST puro e escrevemos sobre os detalhes chatos que realmente importam.

// construa sobre isso

O mesmo Swiss Ephemeris que no Solar Fire — em 4 linhas de código.

Chave gratuita sem cartão. 5 000 chamadas por mês até o primeiro pagamento.

Obter chave API → Documentação