Swiss Ephemeris API

O Swiss Ephemeris é o padrão de facto para os cálculos astronómicos em astrologia: é a base do Astrodienst (astro.com), do Solar Fire, do Kerykeion e da maioria do software sério. Lê as efemérides DE431 da NASA JPL e oferece precisão abaixo do segundo de arco. A AstroWay API dá-te acesso HTTP direto a ele: sem compilar a biblioteca C, sem descarregar ficheiros .se1, sem gerir memória. Um pedido POST, JSON na resposta.

Porquê o Swiss Ephemeris através de uma API

Alojar o Swiss Ephemeris por conta própria significa: compilar a biblioteca C (ou um build WASM), colocar algumas centenas de megabytes de ficheiros .se1, mantê-los atualizados e implementar tu próprio as cúspides das casas, os aspetos e as fases. Através da API, tudo isso é problema de outra pessoa:

• Zero infraestrutura: sem binários, ficheiros de efemérides nem atrasos de cold start. O cálculo corre server-side no mesmo motor que o Astrodienst usa.
• Precisão abaixo do segundo: mediana 0.0013″, máximo 0.561″ (Chiron) face ao swetest CGI de referência do Astrodienst, mais 888 testes de snapshot congelados a cada deploy.
• Intervalo completo de datas: o DE431 cobre 13201 BCE – 17191 CE, por isso mapas históricos e de um futuro distante são calculados sem perda de precisão.
• Não só posições: por cima das efemérides tens logo cúspides das casas (15 sistemas), aspetos, eclipses, trânsitos e progressões, aquilo que com alojamento próprio terias de escrever tu.

Dica

A precisão do motor é triangulada contra três fontes independentes (swetest CGI, Kerykeion, Prokerala) + contra o NASA 5-Millennium Eclipse Catalog. Detalhes e números na página Precisão dos cálculos.

O que é calculado com o Swiss Ephemeris

Endpoint	Créditos	O que devolve
/v1/chart	20	Mapa completo: planetas + casas + aspetos
/v1/planets	10	Posições geocêntricas dos planetas (longitude, latitude, velocidade, retrogradação)
/v1/houses	10	Cúspides das casas, 15 sistemas (Placidus, Koch, Whole Sign, Equal…)
/v1/transits	50	Trânsitos sobre o mapa natal numa data dada
/v1/progressions	50	Progressões secundárias (um dia = um ano)
/v1/eclipses	100	Eclipses solares e lunares (verified vs NASA Catalog)
/v1/moon-phase	10	Fase da Lua, iluminação, próximas quadraturas
/v1/fixed-stars	20	Conjunções dos planetas com estrelas fixas

Isto é parte dos 865 endpoints da plataforma; a lista completa está na referência da API.

Exemplo

cURL

curl -X POST https://api.astroway.info/v1/planets \
  -H "X-Api-Key: aw_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "1990-07-14",
    "time": "14:30:00",
    "timezoneOffset": 3,
    "latitude": 50.4501,
    "longitude": 30.5234
  }'

Node.js

const r = await fetch('https://api.astroway.info/v1/planets', {
  method: 'POST',
  headers: {
    'X-Api-Key': process.env.ASTROWAY_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    date: '1990-07-14',
    time: '14:30:00',
    timezoneOffset: 3,
    latitude: 50.4501,
    longitude: 30.5234,
  }),
});
const { data } = await r.json();
const sun = data.planets.find((p) => p.name === 'Sun');
console.log(`Sun: ${sun.longitude.toFixed(4)}° retrograde: ${sun.isRetrograde}`);

Python

import os, requests

r = requests.post(
    'https://api.astroway.info/v1/planets',
    headers={'X-Api-Key': os.environ['ASTROWAY_API_KEY'], 'Content-Type': 'application/json'},
    json={
        'date': '1990-07-14',
        'time': '14:30:00',
        'timezoneOffset': 3,
        'latitude': 50.4501,
        'longitude': 30.5234,
    },
)
data = r.json()['data']
sun = next(p for p in data['planets'] if p['name'] == 'Sun')
print(f"Sun: {sun['longitude']:.4f}° retrograde: {sun['isRetrograde']}")

Quem usa

• Programadores de aplicações de astrologia: posições abaixo do segundo sem alojar a biblioteca C
• Agentes de IA: efemérides exatas como grounding para LLMs (através do servidor MCP)
• Investigadores: cálculos em massa sobre o intervalo histórico do DE431
• Migração a partir de alojamento próprio: trocar o swisseph local por HTTP sem perder precisão

Custo

Posições planetárias (/v1/planets): 10 créditos; mapa completo (/v1/chart): 20. No plano Free (865+ endpoints, 10 000 créditos/mês) são cerca de 1000 pedidos de planetas por mês gratuitos, sem cartão.

Precisão dos cálculos → Triangulação, validação com a NASA, testes de snapshot

Início rápido O primeiro pedido em 5 minutos

Preços Do gratuito ao Enterprise