Lançamento da API AstroWay: pilha completa de cálculos astrológicos com precisão Swiss Ephemeris

Hoje anunciamos o AstroWay API - um backend de computação para desenvolvedores que criam aplicações astrológicas, produtos de horóscopo, funções de compatibilidade para dating e agentes de IA que devem raciocinar sobre cartas natais.

Neste artigo - o que realmente está dentro da API, quais soluções não convencionais adotamos, o que deixamos de propósito de fora e como chegamos aqui. Sem enrolação.

🕓 Registo de 2026-04-22, atualizado em 2026-05-09. Alguns números estão desatualizados. Estado atual: 865 endpoints (não 87 no momento do lançamento), 888 testes de snapshot CI (não 183), MCP-servidor @astroway/mcp + TypeScript SDK @astroway/sdk + Python SDK astroway + PHP SDK astroway/sdk agora todos estão nos registos públicos. Estado atualizado - em /faq e changelog.

REST API baseado no Swiss Ephemeris - agora também com interpretações de IA sobre cálculos reais. O mesmo motor usado por astrólogos profissionais há 30+ anos no Solar Fire, Kepler, Astro Gold e Janus - precisão até fração de segundo de arco, verificada com a efeméride NASA JPL e a referência oficial swetest da Astrodienst (Astro.com).

Números:

• 865 endpoint: astrologia ocidental natal, sinastria, trânsitos, progressões, direções, retornos, harmônicas, estrelas fixas, pontos árabes, astrocartografia mais o conjunto completo de Human Design
• 183 testes de snapshot no CI contra a saída real do swetest CGI e catálogo de eclipses da NASA - executados em cada PR
• p50 < 100 ms, p95 < 500 ms para endpoints de cálculo típicos
• MCP-servidor @astroway/mcp + três SDK nos registos públicos: @astroway/sdk (npm), astroway (PyPI), astroway/sdk (Packagist) - o mesmo API em três linguagens
• MCP-servidor: @astroway/mcp - expõe a API como ferramentas para Claude, GPT, Cursor e outros agentes de LLM
• Planos baseados em crédito: plano gratuito (10 000 créditos / mês, sem cartão), pagos - a partir de $5 / mês

Documentação completa: api.astroway.info/docs/api/. Estado ao vivo: api.astroway.info/status.

Três anos atrás começámos a construir aplicações astrológicas para consumidores. A camada de cálculo revelou-se a parte mais complexa - significativamente mais difícil que a UI ou o conteúdo. Os serviços existentes ou:

1. Tinham cobertura superficial (10–30 endpoints, predominantemente apenas natal)
2. Eram caros em escala ($0,02–$0,10 por pedido sem descontos por volume)
3. Utilizavam motores fechados, cuja precisão não é possível verificar
4. Orientavam-se para a astrologia védica, apresentando a ocidental como secundária

Assim, vendemos o Swiss Ephemeris de forma independente e escrevemos a nossa própria camada de cálculo - inicialmente para o produto para consumidores app.astroway.info, depois para o site de marketing astroway.info, que emite horóscopos diários para centenas de milhares de visitantes por mês.

Após três anos de execução deste código em produção, chegámos a duas conclusões:

1. Esse mesmo motor de cálculo deve estar disponível para outros desenvolvedores: não porque eles não consigam escrevê-lo por conta própria, mas porque a pilha biblioteca + cache + CI de precisão representa seis meses de trabalho que ninguém deveria repetir.
2. A nossa cobertura de Human Design (12 endpoints: mapa, tipo, autoridade, perfil, portas, canais, contornos, ativações planetárias, cruz de encarnação, definição) é verdadeiramente única. Nenhum concorrente oferece um conjunto completo de HD através de API.

Temos /nakshatras, /ashtakavarga e endpoints para cartas divisionais, mas não temos Dasha, Panchang, Ashtakoota, KP. Razão: na astrologia védica existem divergências não resolvidas entre escolas (guerras de ayanamsha, disputas sobre cúspides KP, escolha da escola de dasha). Uma tentativa rápida de implementar a parte védica contra Prokerala e VedicAstroAPI simplesmente receberia críticas.

Decisão fixada: o pacote védico - fase 3 separada, depois de existir uma procura estável pelo ocidental e haver tempo para validar frente ao Jagannatha Hora e ao Parashara’s Light. Melhor não lançar de todo do que lançar mal.

Uma chamada a /chart custa cerca de 50 vezes menos em termos de cálculo do que o /forecast-calendar de 365 dias. Um preço fixo por pedido ou excluía os utilizadores leves ou subsidia os pesados. Os créditos mapeiam o custo para o trabalho real - veja a tabela por endpoint na página de preços.

As respostas no plano gratuito contêm o campo _footer:

{
  "data": { ... },
  "_footer": "Powered by astroway.api - get your own key at https://api.astroway.info"
}

Isso não nos custa nada e dá aos utilizadores gratuitos um pequeno incentivo para atualizar. No plano Hobby+ é removido nas definições da chave. O padrão foi retirado do Zapier e do RevenueCat.

/rectification (seleção do horário de nascimento com base em eventos de vida através de busca likelihood-grid) - computacionalmente caro: uma chamada dura entre 10 e 60 segundos e realiza dezenas de milhares de cálculos intermediários do Swiss Ephemeris. Limitamo-lo ao plano Pro ($59 / mês) e atribuímos um custo elevado em créditos, pois o uso indevido sobrecarregaria a infraestrutura partilhada por todos.

Os endpoints /interpret/* funcionam através do nosso AI-gateway privado com failover automático entre vários modelos. Não bloqueamos-te nos nossos prompts - cada resposta com interpretação contém os cálculos brutos, portanto podes substituir por tua própria LLM se a nossa voz não te agradar. Registar os prompts completos e as saídas numa tabela de auditoria para conformidade B2B (retenção de 90 dias).

• Pacote védico: fase 3, após as primeiras confirmações de procura (ver acima)
• Webhooks para atingir limites: implementados, mas a UI está crua; estamos a melhorá-los
• Widgets públicos (<script src="api.astroway.info/widget/natal.js">) - fase 7
• Plugin para o site principal de marketing: projeto separado, planeado no âmbito do ecossistema astroway.info

1. Lê a documentação se quiser perceber “por quê”: api.astroway.info/overview
2. Início rápido em 5 minutos com código: Astrology API Quick Start
3. Planos, incluindo tabela de créditos por endpoint: api.astroway.info/pricing
4. Regista-te: gratuito, sem cartão: api.astroway.info/dashboard/sign-up

Se construires algo com a API - ou encontras um bug, ou desejares um endpoint que ainda não temos - escreve-nos. Prefirimos ouvir cem desenvolvedores a pedir algo do que lançar funcionalidades que ninguém usa.

Perguntas, pedidos, casos extremos estranhos: hello@astroway.info.

Roadmap público - PRODUCT-PLAN.md - o que foi feito, o que vem a seguir, o que foi adiado e por quê.

Bem-vindo.