Eclipse path, cosmogram e carte Vedic: visualizzatori pure-SVG senza headless-Chrome

La categoria Visualizzazione nel nostro roadmap è completata al 100%: sei endpoint finali coprono layout specifici per i quali non esiste ancora un pacchetto npm pronto - carte Vedic in tre stili regionali, cosmogramma della Scuola di Amburgo, percorso dell’eclissi su una mappa mondiale e mappa stellare stereografica.

La soluzione chiave: tutti i rendering sono stringhe SVG pure, senza Chrome headless. Questo significa una risposta in subsecondo, costi ridotti per chiamata e la possibilità di embedding in email, PDF o documenti web.

La maggior parte delle immagini di astrologia di qualità pubblicabile vengono create tramite Chromium con un template SVG - questo è accettabile per i report PDF. Tuttavia, gli endpoint /v1/render/* sono progettati per il rendering programmato in tempo reale:

• Embedding inline in un componente React di un dashboard
• Integrazione in campagne email
• Trasmissione a un agente LLM per analisi multimodale

Headless Chrome non è adatto: i costi RAM e la latenza non permettono di chiamarlo 100 volte al minuto per una singola sessione. Pertanto, tutti e sei i renderer sono implementati come string builder puro che emette etichette SVG tramite funzioni template. La latenza è inferiore a 100 ms, anche su cache fredda.

Nella tradizione dell’astrologia indiana esistono tre layout per la carta natale, ognuno con un peso culturale nel proprio regione:

Layout classico a “diamante”: il primo segno è sempre in alto (case fisse), mentre i segni ruotano in base al Lagna. È il più diffuso nelle consultazioni mainstream in lingua hindi.

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" }
  }'

È possibile richiedere una stringa SVG (format: "svg") o un wrapper JSON con { svg, byteLength } (format: "json", valore predefinito).

Griglia quadrata 4×4, i segni sono fissi (Pesci sempre in alto a sinistra, gli altri in senso orario), mentre i numeri delle case variano in base al Lagna. È diffuso in Tamil Nadu, Kerala e Karnataka.

Quadrato con diagonali + quadrato interno ruotato - geometria ibrida. Il meno conosciuto delle tre forme in Occidente, ma essenziale per prodotti orientati alla cultura bengalese.

Tutti e tre gli endpoint accettano lo stesso payload della carta - la scelta dello stile di visualizzazione dipende dall’endpoint selezionato.

POST /v1/render/cosmogram non è una carta natale. Si tratta di un dial da 90°, dove tutti gli aspetti duri (0°/90°/180°) si riducono a connessioni. Lo strumento è stato sviluppato da Alfred Witte (Witte 1928) e successivamente formalizzato da Reinhart Ebertin (Ebertin 1940) come base della cosmobiologia.

Perché è utile: su una carta standard da 360°, gli aspetti duri sono “spalmati” lungo il cerchio, rendendo difficile individuare i cluster. Su un dial da 90°, diventano visivamente evidenti - un cluster di 3-4 pianeti in un settore da 22.5° è immediatamente riconoscibile.

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
  }'

Ritorna un SVG con un quadrato da 4×22.5° (settori cardinali) + le posizioni dei pianeti su un giro da 90°.

POST /v1/render/eclipse-path accetta una traccia fornita dall’utente (latitudine/longitudine) per la linea di centralità dell’eclissi, insieme a un’opzionale larghezza di banda in gradi. Il rendering è una mappa mondiale equirettangolare (proiezione standard WGS-84) con graticolo + linea di percorso + sovrapposizione della 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" }
  }'

La traccia fornita dall’utente è una scelta di design deliberata. I dati sul percorso dell’eclissi provengono da diverse fonti canoniche (NASA Eclipse Catalog, Five Millennium Canon of Solar Eclipses di Espenak & Meeus), ognuna con la propria precisione. Questo endpoint non cerca di replicare i calcoli della NASA - rende la tua traccia in modo attraente. Come fonte di dati, raccomandiamo il sito web delle eclissi della NASA, ma ciò è al di fuori dello scopo di questo endpoint.

Use case. Un’app educativa che mostra l’eclissi successiva con la sua traccia sulla mappa. Oppure una consulenza astrologica che desidera visualizzare l‘“onda” dell’eclissi attraverso le località importanti per i nativi.

POST /v1/render/star-map accetta una lista di punti (RA/Dec) con magnitudine e glyph opzionali, e rende una proiezione stereografica. La magnitudine viene mappata sul raggio del punto (stelle più luminose = cerchi più grandi).

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"
  }'

Parametri:

• points: da 1 a 2000 stelle/oggetti
• observerLatDeg + zenithDecDeg: per una corretta proiezione dalla posizione dell’osservatore
• capAltitudeDeg: limite di altezza (ad esempio, -18 per i crepuscoli astronomici)

Use case. Widget “cielo di questa notte” in un’app astrologica. Contesto natale Vedic con stelle-nakshatra sovrapposte alle coordinate reali. Prodotto educativo con mappa delle costellazioni.

Se è necessario un formato raster (per social media, email, notifiche push), la 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

La conversione SVG → PNG tramite sharp aggiunge circa 150 ms, che rimane comunque più economico rispetto a Chrome headless. In alternativa, lascia l’SVG come è e inseriscilo inline in HTML tramite sistemi di templating (Astro, Vue, React component con output diretto della stringa tramite il meccanismo di rendering del framework, con pre-sanitizzazione).

Tutti e sei gli endpoint di rendering di questa categoria appartengono alla Tier 1: 10 crediti per chiamata. La tabella completa dei prezzi è disponibile su Pricing.

La documentazione con schemi completi dei parametri è disponibile in /docs/api/ → Render. I formati Vedic, il cosmogramma, il percorso dell’eclissi e la mappa stellare includono ciascuno un esempio di parametri e una snapshot di risposta SVG.