Início Rápido da API de Astrologia: TypeScript e Python em 5 minutos

🕓 Postagem de 2026-04-14, atualizado 2026-05-09. TS / Python / PHP SDK agora vivem nos registros públicos — @astroway/sdk (npm), astroway (PyPI), astroway/sdk (Packagist). Detalhes em changelog.

Tu queres calcular um mapa natal com código. Aqui está o caminho mais curto — em 5 minutos, de zero a um JSON funcionando.

Passo 1: Obtenha uma chave de API (30 segundos)

Registre-se em api.astroway.info/dashboard/sign-up. Plano gratuito: 10 000 créditos / mês. Sem cartão.

No dashboard, clique em «Create key» → «Production» → copie. As chaves têm o formato aw_live_aB3xY7pQ9rN2mK4jH8vC5tL6wZ1fD0eR.

Dica: também existem chaves de sandbox com prefixo aw_test_ — elas não consomem créditos. Use-as durante o desenvolvimento.

Passo 2: Instale o SDK

TypeScript

npm install @astroway/sdk

Python

pip install astroway

Ambos os SDKs cobrem todos os 723 endpoints com solicitações e respostas tipadas.

Passo 3: Primeiro mapa natal

TypeScript

import { Astroway } from '@astroway/sdk';

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

const chart = await client.chart({
  date: '1990-07-14',
  time: '14:30:00',
  timezoneOffset: 3,      // UTC+3, verão em Kiev
  latitude: 50.4501,
  longitude: 30.5234,
  houseSystem: 'P',       // Placidus
});

console.log(`Sol: ${chart.planets[0].sign} at ${chart.planets[0].longitude}°`);
console.log(`ASC: ${chart.houses.ascendant}°`);
console.log(`Aspectos: ${chart.aspects.length}`);

Execute:

ASTROWAY_API_KEY=aw_live_... npx tsx chart.ts

Python

from astroway import Astroway

client = Astroway(api_key="aw_live_your_key_here")

chart = client.chart(
    date="1990-07-14",
    time="14:30:00",
    timezone_offset=3,
    latitude=50.4501,
    longitude=30.5234,
    house_system="P",
)

print(f"Sol: {chart['planets'][0]['sign']} at {chart['planets'][0]['longitude']}°")
print(f"ASC: {chart['houses']['ascendant']}°")
print(f"Aspectos: {len(chart['aspects'])}")

Execute:

ASTROWAY_API_KEY=aw_live_... python3 chart.py

O que a API retorna

Volta um objeto JSON com quatro partes principais:

planets

Matriz com 12 objetos (Sol, Lua, Mercúrio, Vênus, Marte, Júpiter, Saturno, Urano, Netuno, Plutão, Nó Norte, Quíron):

{
  "name": "Sol",
  "longitude": 111.87,      // longitude eclíptica em graus
  "latitude": 0.0,
  "speed": 0.955,           // graus por dia (negativo = retrógrado)
  "sign": "câncer",
  "signIndex": 3,
  "house": 10,
  "retrograde": false
}

houses

Cúspides das casas (12) e também asc e MC:

{
  "system": "P",
  "cusps": [12.34, 43.21, ...],   // 12 valores
  "ascendant": 12.34,
  "mc": 280.12
}

aspects

Matriz de aspectos entre planetas:

{
  "planet1": "Sol",
  "planet2": "Lua",
  "type": "sextil",        // conjunção, oposição, trino, quadratura, sextil, quincunx
  "orb": 1.36,              // desvio do exato em graus
  "applying": true
}

chartSect

"diurno" (Sol acima do horizonte no momento do nascimento) ou "noturno" (abaixo do horizonte). Usado na astrologia clássica.

O que fazer em seguida

O que mais tentar:

Sinastria — compatibilidade de duas pessoas:

const sinastria = await client.sinastria({
  chart1: { date: '1990-07-14', time: '14:30:00', timezoneOffset: 3, latitude: 50.45, longitude: 30.52 },
  chart2: { date: '1992-03-22', time: '09:15:00', timezoneOffset: 2, latitude: 48.85, longitude: 2.35 },
});
console.log(`Pontuação de compatibilidade: ${sinastria.compatibility.score}/100`);

Trânsitos atuais no mapa natal:

const transitos = await client.transitos({
  // dados de nascimento
  date: '1990-07-14', time: '14:30:00', timezoneOffset: 3,
  latitude: 50.4501, longitude: 30.5234,
  // data do trânsito
  transitDate: '2026-04-14',
});

Horóscopo diário com trânsitos reais:

const horoscopo = await client.horoscopoDiario({
  date: '1990-07-14', time: '14:30:00', timezoneOffset: 3,
  latitude: 50.4501, longitude: 30.5234,
});
console.log(horoscopo.text);

Mapa completo de Design Humano:

const dh = await client.designHumano({
  date: '1990-07-14', time: '14:30:00', timezoneOffset: 3,
  latitude: 50.4501, longitude: 30.5234,
});
console.log(`${dh.type} — ${dh.strategy} — Perfil ${dh.profile}`);

Custo em créditos

Mapa natal (/chart): 20 créditos
Sinastria: 50 créditos
Trânsitos: 50 créditos
Horóscopo diário: 20 créditos
Design Humano: 50 créditos

Plano gratuito: 10 000 créditos / mês = 500 mapas natais, ou 200 sinastrias, ou carga mista.

Tratamento de erros

Cada resposta contém cabeçalhos com créditos:

X-Credits-Used: 20
X-Credits-Remaining: 4980
X-Credits-Reset: 2026-05-01T00:00:00Z

Quando os créditos acabam — você recebe 402 Payment Required. Quando atinge o limite de taxa (Free: 10 solicitações / min) — 429 Too Many Requests com cabeçalho Retry-After.

O SDK lança erros tipados que podem ser capturados:

try {
  const chart = await client.chart({ ... });
} catch (err) {
  if (err.code === 'credits_exhausted') {
    console.log('Atualize o plano ou aguarde o reset');
  } else if (err.code === 'rate_limit_exceeded') {
    console.log(`Tente novamente em ${err.retryAfter} segundos`);
  }
}

E pronto

Agora você tem:

Uma chave de API funcionando
O SDK instalado
O primeiro mapa natal
Exemplos suficientes para adicionar sinastria, trânsitos, horóscopos

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

Início Rápido da API de Astrologia: TypeScript e Python em 5 minutos

Passo 1: Obtenha uma chave de API (30 segundos)

Passo 2: Instale o SDK

TypeScript

Python

Passo 3: Primeiro mapa natal

TypeScript

Python

O que a API retorna

planets

houses

aspects

chartSect

O que fazer em seguida

Custo em créditos

Tratamento de erros

E pronto

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

Mais do blog todas as postagens →

Natal Chart API in TypeScript: SDK + React Example

How Accurate Is the Swiss Ephemeris? Verified Benchmarks

Swiss Ephemeris: REST API vs pyswisseph (When to Use Which)