Mapas Natais

Calcula mapas natais completos com posições planetárias, cúspides das casas e aspectos.

Cálculo Básico

curl -X POST "https://api.astroapi.cloud/api/calc/natal" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "datetime": "1990-06-15T14:30:00",
    "latitude": 51.5074,
    "longitude": -0.1278,
    "timezone": "Europe/London"
  }'

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
datetime	string	Sim	Data e hora em ISO 8601
latitude	number	Sim	Latitude (-90 a 90)
longitude	number	Sim	Longitude (-180 a 180)
timezone	string	Sim	Identificador de fuso horário IANA
houseSystem	string	Não	Sistema de casas (padrão: "placidus")

Sistemas de Casas

• placidus — Placidus (padrão)
• koch — Koch
• equal — Casas Iguais
• whole — Signo Inteiro
• campanus — Campanus
• regiomontanus — Regiomontanus
• porphyry — Porphyry

Resposta

{
  "data": {
    "type": "natal-chart",
    "attributes": {
      "planets": {
        "sun": { "longitude": 84.5, "latitude": 0, "sign": "gemini", "house": 10 },
        "moon": { "longitude": 245.2, "latitude": -3.1, "sign": "sagittarius", "house": 4 }
      },
      "houses": {
        "1": { "cusp": 180.5, "sign": "libra" },
        "2": { "cusp": 210.3, "sign": "scorpio" }
      },
      "aspects": [
        { "planet1": "sun", "planet2": "moon", "aspect": "opposition", "orb": 0.7 }
      ]
    }
  }
}

Corpos Incluídos

Por padrão, os seguintes corpos celestes são incluídos:

• Sol, Lua
• Mercúrio, Vénus, Marte, Júpiter, Saturno, Urano, Neptuno, Plutão
• Nodo Norte, Nodo Sul
• Quíron, Lilith (Lua Negra)
• Parte da Fortuna

Lua e Sol

Calcula a fase lunar, iluminação, horários de nascente/poente e dados da posição solar.

POST /api/calc/moon-sun

curl -X POST "https://api.astroapi.cloud/api/calc/moon-sun" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "dateTime": "2024-06-15T12:00",
    "location": {
      "latitude": 52.37,
      "longitude": 4.89,
      "timezone": "Europe/Amsterdam"
    }
  }'

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
dateTime	string	Sim	Data/hora no formato YYYY-MM-DDTHH:mm
location.latitude	number	Sim	Latitude (-90 a 90)
location.longitude	number	Sim	Longitude (-180 a 180)
location.timezone	string	Sim	Identificador de fuso horário IANA

Módulo Necessário

Este endpoint requer o módulo module:moon.

Resposta

{
  "data": {
    "moon": {
      "phaseName": "Waxing Gibbous",
      "phase": 0.62,
      "illumination": 0.78,
      "age": 9.2,
      "distance": 384400,
      "diameterDegrees": 0.52,
      "rise": "2024-06-15T14:23:00Z",
      "set": "2024-06-16T02:15:00Z"
    },
    "sun": {
      "rise": "2024-06-15T05:18:00Z",
      "set": "2024-06-15T22:03:00Z",
      "transit": "2024-06-15T13:40:00Z",
      "distance": 151820000,
      "diameterDegrees": 0.524,
      "twilight": {
        "civil": {
          "begin": "2024-06-15T04:38:00Z",
          "end": "2024-06-15T22:43:00Z"
        },
        "nautical": {
          "begin": "2024-06-15T03:32:00Z",
          "end": "2024-06-15T23:49:00Z"
        },
        "astronomical": {
          "begin": null,
          "end": null
        }
      }
    }
  }
}

Precisão dos Cálculos

A AstroAPI utiliza o Swiss Ephemeris para cálculos de alta precisão. Todas as posições são calculadas com precisão ao segundo de arco.

Beta: Motor de Cálculo Alternativo

Funcionalidade Experimental

Esta funcionalidade está em fase beta e pode ter problemas de precisão. Usa-a com precaução em ambientes de produção.

A AstroAPI disponibiliza um motor de cálculo alternativo (calc2) que usa uma implementação personalizada para ler e avaliar directamente os ficheiros de dados SE1 do Swiss Ephemeris, em vez de utilizar a biblioteca oficial do Swiss Ephemeris. Este motor está optimizado para velocidade e pode proporcionar tempos de resposta mais rápidos.

Para usar o motor alternativo, inclui o cabeçalho X-Use-Calc2 no teu pedido:

curl -X POST "https://api.astroapi.cloud/api/calc/natal" \
  -H "X-Api-Key: your-api-key" \
  -H "X-Use-Calc2: true" \
  -H "Content-Type: application/json" \
  -d '{
    "datetime": "1990-06-15T14:30:00",
    "latitude": 51.5074,
    "longitude": -0.1278,
    "timezone": "Europe/London"
  }'

Principais Diferenças

Aspecto	Motor Padrão	Motor Calc2 (Beta)
Implementação	Swiss Ephemeris	Implementação personalizada
Fonte de Dados	Ficheiros SE1	Ficheiros SE1 (mesmos dados)
Velocidade	Padrão	Potencialmente mais rápido
Precisão	Precisão ao segundo de arco (referência)	Pode ter pequenos desvios
Estado	Pronto para produção	Beta

Quando Usar o Calc2

• Recomendado para: Aplicações de grande volume onde a velocidade tem prioridade sobre a precisão absoluta
• Não recomendado para: Aplicações que requerem máxima precisão astronómica

Limitações Conhecidas

• A implementação personalizada pode produzir resultados ligeiramente diferentes comparados com a biblioteca oficial do Swiss Ephemeris
• Ainda em desenvolvimento activo e em fase de testes
• Os resultados devem ser validados em relação ao motor padrão para aplicações críticas