Eclipse path, cosmogram e cartas Vedic: visualizadores SVG puros sem headless-Chrome

A categoria Visualização no nosso roadmap está fechada 14/14: seis endpoints finais cobrem layouts específicos para os quais não há um pacote npm pronto - gráficos védicos em três estilos regionais, cosmograma da Escola de Hamburgo, trajetória de eclipse em um mapa mundial e mapa estelar estereográfico.

A solução-chave: todos os renders são strings puras SVG, sem Chrome headless. Isso significa resposta em subsegundos, baixo custo por chamada e a possibilidade de uso inline em qualquer e-mail, PDF ou documento web.

A maioria das imagens de astrologia de publicação de qualidade é criada usando Chromium com um template SVG - isso é normal para relatórios PDF. No entanto, os endpoints /v1/render/* são projetados para renderização programática em tempo real:

• inline em um componente React de dashboard
• incorporado em campanhas de e-mail
• transmissão para um agente LLM para análise multimodal

O Chrome headless não é adequado - o custo de RAM e a latência não permitem chamá-lo 100 vezes por hora para um único lote. Por isso, todos os seis renderizadores são construídos com um string builder puro que emite marcação SVG por meio de funções de template. A latência fica abaixo de 100ms, mesmo com cache frio.

Na astrologia indiana, há três layouts tradicionais para o gráfico natalício, cada um com peso cultural em sua região:

O layout clássico “diamante”: o primeiro signo sempre está em cima (casas fixas), e os signos giram de acordo com o Lagna. É o mais comum na maioria das consultas em hindi mainstream.

curl -X POST https://api.astroway.info/v1/render/wheel-vedic-north \
  -H "X-Api-Key: aw_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "date": "1990-05-15",
    "time": "14:30:00",
    "timezoneOffset": 3,
    "latitude": 50.45,
    "longitude": 30.52,
    "options": { "format": "svg" }
  }'

Você pode solicitar uma string SVG (format: "svg") ou uma embalagem JSON com { svg, byteLength } (format: "json", padrão).

Uma grade quadrada 4×4, onde os signos estão fixos (Peixes sempre em cima à esquerda, os outros no sentido horário), e os números das casas flutuam de acordo com o Lagna. É popular em Tamil Nadu, Kerala e Karnataka.

Quadrado com diagonais + quadrado interno girado - uma geometria híbrida. É o menos conhecido dos três no Ocidente, mas obrigatório para produtos orientados para o Bengali.

Todos os três aceitam o mesmo payload do gráfico - o endpoint é escolhido de acordo com o estilo de visualização.

POST /v1/render/cosmogram não é um gráfico natalício. É um dial de 90°, onde todos os aspectos rígidos (0°/90°/180°) são colapsados em conexões. O instrumento foi desenvolvido por Alfred Witte (Witte 1928) e posteriormente formalizado por Reinhard Ebertin (Ebertin 1940) como base da cosmobiologia.

Por que isso é útil: em um gráfico padrão de 360°, os aspectos rígidos estão “espalhados” pelo círculo, dificultando a leitura de aglomerados. No dial de 90°, eles ficam visualmente óbvios - um cluster de 3-4 planetas em um setor de 22.5° é imediatamente visível.

curl -X POST https://api.astroway.info/v1/render/cosmogram \
  -H "X-Api-Key: aw_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "date": "1990-05-15",
    "time": "14:30:00",
    "timezoneOffset": 3,
    "latitude": 50.45,
    "longitude": 30.52
  }'

Retorna um SVG com um quadrado de 4×22.5° (setores cardinais) + posições dos planetas em uma rotação de 90°.

POST /v1/render/eclipse-path aceita um rastro de latitude/longitude fornecido pelo chamador para a linha de centralidade do eclipse, além de uma largura opcional em graus. O render é um mapa mundial equirretangular (projeção padrão WGS-84) com graticule + linha de trajetória + sobreposição de banda.

curl -X POST https://api.astroway.info/v1/render/eclipse-path \
  -H "X-Api-Key: aw_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "path": [
      { "latitude": 38.5, "longitude": -125.0, "time": "2026-08-12T17:30Z" },
      { "latitude": 41.2, "longitude": -105.3, "time": "2026-08-12T17:42Z" },
      { "latitude": 44.8, "longitude": -85.7, "time": "2026-08-12T17:54Z" }
    ],
    "bandWidthDeg": 1.2,
    "title": "Eclipse 2026-08-12",
    "options": { "width": 1200, "height": 600, "showGraticule": true, "pathColor": "#ff5500" }
  }'

O rastro fornecido pelo chamador é uma escolha de design intencional. Os dados da trajetória do eclipse vêm de várias fontes canônicas (NASA Eclipse Catalog, Five Millennium Canon of Solar Eclipses de Espenak & Meeus), cada uma com sua própria precisão. O endpoint não tenta replicar os cálculos da NASA - ele renderiza seu rastro de forma bonita. Como fonte de dados, recomendamos o NASA Eclipse Web Site, mas isso está fora do escopo deste endpoint.

Use case. Aplicativo educacional que mostra o próximo eclipse com sua trajetória no mapa. Ou uma consulta de astrologia que deseja visualizar a “onda” do eclipse através de locais importantes para os nativos.

POST /v1/render/star-map aceita uma lista de pontos (RA/Dec) com magnitude opcional e glyph, e renderiza uma projeção estereográfica. A magnitude é mapeada para o raio do ponto (uma estrela mais brilhante = círculo maior).

curl -X POST https://api.astroway.info/v1/render/star-map \
  -H "X-Api-Key: aw_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "points": [
      { "raHours": 5.92, "decDeg": 7.41, "magnitude": 0.45, "name": "Betelgeuse" },
      { "raHours": 6.75, "decDeg": -16.72, "magnitude": -1.46, "name": "Sirius" },
      { "raHours": 5.24, "decDeg": -8.20, "magnitude": 0.18, "name": "Rigel" }
    ],
    "observerLatDeg": 50.45,
    "zenithDecDeg": 50.45,
    "capAltitudeDeg": -18,
    "title": "Sky at midnight, Kyiv"
  }'

Parâmetros:

• points: de 1 a 2000 estrelas/objetos
• observerLatDeg + zenithDecDeg: para uma projeção correta a partir do ponto de observação
• capAltitudeDeg: limite de altitude (por exemplo, -18 para crepúsculo astronômico)

Use case. Widget “céu da noite” em um aplicativo de astrologia. Contexto védico natal com estrelas-nakshatra sobrepostas em coordenadas reais. Produto educacional com mapa de constelações.

Se for necessário um raster (para redes sociais, e-mails, notificações push), a pipeline é:

import { Astroway } from "@astroway/sdk";
import sharp from "sharp";

const client = new Astroway({ apiKey: process.env.ASTROWAY_KEY });

const { svg } = await client.render.eclipsePath({
  path: eclipseTrack,
  bandWidthDeg: 1.2,
  options: { width: 1200, height: 600, format: "json" },
});

const png = await sharp(Buffer.from(svg))
  .resize(1200, 600)
  .png()
  .toBuffer();

// upload to CDN, get URL

A conversão SVG → PNG usando sharp adiciona cerca de 150ms, que ainda é mais barato do que usar Chrome headless. Alternativamente, deixe como SVG e insira inline em HTML usando sistemas de template (Astro, Vue, React component com saída direta da string por meio do mecanismo apropriado do framework, com pré-sanitização).

Todos os seis endpoints de renderização desta categoria são Tier 1: 10 créditos por chamada. A tabela completa de preços está em Preços.

A documentação com esquemas completos de parâmetros está em /docs/api/ → Render. Os formatos védicos, cosmograma, trajetória de eclipse e mapa estelar incluem exemplos de parâmetros e capturas de resposta SVG.