Come Creare un’App di Astrologia con AstroAPI
Creare un’applicazione di astrologia richiedeva una conoscenza approfondita dei calcoli astronomici, dei dati delle effemeridi e della matematica complessa. Con AstroAPI, puoi saltare tutto questo e concentrarti su ciò che conta di più: creare un’ottima esperienza utente.
In questo tutorial, costruiremo una pagina web di astrologia completa da zero - una pagina in cui qualcuno inserisce i propri dati di nascita e vede istantaneamente il proprio tema natale con le posizioni planetarie, una ruota grafica del tema e il proprio oroscopo del giorno. Non è necessaria alcuna esperienza precedente con le API.
Cosa Ti Serve
- Un account AstroAPI (registrati gratuitamente)
- Una API key (disponibile dalla tua dashboard)
- Un editor di testo (VS Code, Sublime Text o anche Blocco Note)
- Un browser web
Questo è tutto - nessun framework, nessuno strumento di build, nessun comando da terminale. Scriveremo tutto in un unico file HTML.
Passo 1: Ottieni la Tua API Key
Dopo la registrazione, vai alla tua dashboard. La tua API key è come una password che identifica la tua app presso AstroAPI - ne avrai bisogno per ogni richiesta.
Trovare la pagina API Keys
Nell’angolo in alto a destra della dashboard, clicca sull’icona del tuo profilo. Apparirà un menu a tendina. Nella sezione Integration, clicca su API Keys.
Questo ti porta alla panoramica delle API Keys. Vedrai una barra di navigazione che mostra il tuo percorso attuale: Profile > Integration > API Keys. Clicca il pulsante Create nell’angolo in alto a destra per creare una nuova chiave.
Creare la tua chiave
Nella pagina di creazione, vedrai un modulo con diverse sezioni:
- Name - Dai alla tua chiave un nome riconoscibile (ad es. “La mia App di Astrologia” o “Produzione”).
- Expires In (days) - Imposta opzionalmente una scadenza. Lascia vuoto se la chiave deve durare a tempo indeterminato.
- Permissions - Seleziona quali funzionalità API la chiave può utilizzare. Per questo tutorial, avrai bisogno almeno dei permessi di calcolo (
calc). Puoi selezionare “Use all permissions from my role” per semplificare le cose. - Modules - Scegli quali moduli la chiave può utilizzare. Per questo tutorial, seleziona i moduli natali (
natal:calc,natal:charts,natal:texts). Puoi anche selezionare “Use all modules from my organization” per consentire tutto. - Domain Restrictions - Questo è importante. Poiché la tua API key sarà visibile nel codice sorgente della pagina (chiunque può vederla tramite gli strumenti per sviluppatori del browser), dovresti limitarla al tuo dominio. Inserisci il dominio del tuo sito web (ad es.
mywebsite.com) in modo che vengano accettate solo le richieste provenienti da quel dominio. In questo modo, anche se qualcuno copia la tua chiave, non potrà usarla sul proprio sito. Per lo sviluppo locale, puoi usare temporaneamente*.
Clicca Save e la tua nuova API key apparirà. Copiala e conservala in un posto sicuro - non potrai più vedere la chiave completa.
Passo 2: Crea la Tua Pagina HTML
Apri il tuo editor di testo e crea un nuovo file chiamato astrology.html. Inizieremo con una pagina base che contiene un modulo per i dati di nascita:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>My Astrology App</title>
<style>
body {
font-family: Georgia, serif;
max-width: 800px;
margin: 0 auto;
padding: 2rem;
background: #f5f0e8;
color: #1a1a1a;
}
h1 { text-align: center; }
form {
background: white;
padding: 2rem;
border-radius: 8px;
margin-bottom: 2rem;
}
label { display: block; margin-bottom: 0.5rem; font-weight: bold; }
input, select {
width: 100%;
padding: 0.5rem;
margin-bottom: 1rem;
border: 1px solid #ccc;
border-radius: 4px;
font-size: 1rem;
}
button {
background: #ba9a63;
color: white;
border: none;
padding: 0.75rem 2rem;
font-size: 1rem;
border-radius: 4px;
cursor: pointer;
}
button:hover { background: #a8894f; }
.results { background: white; padding: 2rem; border-radius: 8px; }
.planet-row {
display: flex;
justify-content: space-between;
padding: 0.5rem 0;
border-bottom: 1px solid #eee;
}
.planet-name { font-weight: bold; }
.planet-sign { color: #ba9a63; }
#chart-image { text-align: center; margin: 2rem 0; }
#chart-image svg { max-width: 100%; height: auto; }
.horoscope-box {
background: #f9f3e5;
padding: 1.5rem;
border-left: 4px solid #ba9a63;
border-radius: 0 8px 8px 0;
margin-top: 1.5rem;
line-height: 1.8;
}
.loading { text-align: center; color: #6b6b75; font-style: italic; }
.hidden { display: none; }
</style>
</head>
<body>
<h1>✨ My Astrology App</h1>
<form id="birth-form">
<label for="name">Your Name</label>
<input type="text" id="name" placeholder="e.g. Anna" required>
<label for="date">Date of Birth</label>
<input type="date" id="date" required>
<label for="time">Time of Birth</label>
<input type="time" id="time" required>
<label for="city">City of Birth</label>
<input type="text" id="city" placeholder="e.g. Amsterdam" required>
<button type="submit">Calculate My Chart</button>
</form>
<div id="results" class="results hidden">
<!-- Results will appear here -->
</div>
<script>
// We'll add our code here in the next steps
</script>
</body>
</html>Salva il file e aprilo nel tuo browser. Dovresti vedere un modulo pulito che chiede i dati di nascita. Non fa ancora nulla - risolviamo questo.
Passo 3: Cerca la Posizione di Nascita
Quando qualcuno digita “Amsterdam”, dobbiamo convertirlo in coordinate di latitudine e longitudine. AstroAPI ha un endpoint di geocoding per questo:
const API_KEY = "your-api-key-here";
const BASE_URL = "https://api.astroapi.cloud/api";Proteggere la tua API key: Poiché questa è una pagina web lato client, la tua API key è visibile a chiunque visualizzi il codice sorgente della pagina. Questo va bene purché tu abbia impostato le Domain Restrictions nella dashboard (vedi Passo 1). L’API rifiuterà le richieste da qualsiasi dominio che non sia nella tua lista consentita, quindi la chiave è inutile per chiunque la copi.
Ora scriviamo le funzioni. Per prima cosa, la ricerca della posizione:
async function findLocation(cityName) {
const response = await fetch(
`${BASE_URL}/geocoding/search?q=${encodeURIComponent(cityName)}`,
{ headers: { "X-Api-Key": API_KEY } }
);
const data = await response.json();
// The API returns a list of matching places.
// We'll use the first result.
const place = data.data[0];
return {
latitude: place.latitude,
longitude: place.longitude,
timezone: place.timezone,
name: place.name
};
}Questo trasforma “Amsterdam” in { latitude: 52.37, longitude: 4.89, timezone: "Europe/Amsterdam", name: "Amsterdam" } - esattamente ciò di cui abbiamo bisogno per i calcoli del tema. Il fuso orario è importante perché AstroAPI ne ha bisogno per convertire correttamente l’ora di nascita locale in tempo universale.
Passo 4: Calcola il Tema Natale
Ora inviamo i dati di nascita ad AstroAPI e riceviamo tutte le posizioni planetarie:
async function calculateChart(birthDate, birthTime, latitude, longitude, timezone) {
const response = await fetch(`${BASE_URL}/calc/natal`, {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-Api-Key": API_KEY
},
body: JSON.stringify({
dateTime: `${birthDate}T${birthTime}:00`,
location: { latitude, longitude, timezone },
houseSystem: "placidus",
includeReadableEntities: true
})
});
return await response.json();
}Il dateTime viene inviato come stringa ISO (ad es. "1990-06-15T14:30:00") e la location include il fuso orario in modo che l’API possa interpretare correttamente l’ora di nascita locale. La risposta contiene tutto sul tema: dove si trovava ogni pianeta, in quale segno zodiacale era posizionato, quale casa occupava e tutte le relazioni geometriche (aspetti) tra i pianeti.
Passo 5: Visualizza i Risultati
Qui le cose diventano interessanti. Trasformiamo i dati grezzi dell’API in qualcosa di visivamente accattivante. Mostreremo una tabella delle posizioni planetarie e i segni del Sole, della Luna e dell’Ascendente della persona - i “tre grandi” che incuriosiscono la maggior parte delle persone:
function displayChart(chart, personName) {
const points = chart.data.points;
const houses = chart.data.houses;
// Find the "big three"
const sunSign = points.sun.signTitle;
const moonSign = points.moon.signTitle;
const risingSignId = houses.cusps[0].sign;
const risingSign = risingSignId.charAt(0).toUpperCase() + risingSignId.slice(1);
let html = `
<h2>${personName}'s Birth Chart</h2>
<div style="text-align:center; margin-bottom:2rem;">
<p style="font-size:1.2rem;">
☀️ Sun in <strong>${sunSign}</strong> ·
🌙 Moon in <strong>${moonSign}</strong> ·
⬆️ Rising <strong>${risingSign}</strong>
</p>
</div>
<h3>Planetary Positions</h3>
`;
// Build a row for each planet
const planetKeys = ["sun", "moon", "mercury", "venus", "mars",
"jupiter", "saturn", "uranus", "neptune", "pluto"];
for (const key of planetKeys) {
const planet = points[key];
if (!planet) continue;
html += `
<div class="planet-row">
<span class="planet-name">${key.charAt(0).toUpperCase() + key.slice(1)}</span>
<span class="planet-sign">${planet.signTitle} ${planet.degreesInSign.toFixed(1)}°</span>
<span>House ${planet.houseNumber}</span>
</div>
`;
}
document.getElementById("results").innerHTML = html;
document.getElementById("results").classList.remove("hidden");
}L’API restituisce i pianeti come un oggetto con chiavi basate sull’ID del pianeta (ad es. points.sun, points.moon). Ogni pianeta ha un sign (come "gemini"), signTitle (nome visualizzato come "Gemini"), degreesInSign (posizione all’interno di quel segno) e houseNumber. Il segno Ascendente proviene direttamente dalla proprieta sign sulla cuspide della prima casa.
Passo 6: Aggiungi una Ruota del Tema Visiva
Un tema natale prende davvero vita con la classica ruota circolare del tema. AstroAPI le genera come immagini SVG che appaiono nitide a qualsiasi dimensione:
function displayChartImage(chartUrl) {
const chartDiv = document.createElement("div");
chartDiv.id = "chart-image";
chartDiv.innerHTML = `<h3>Your Chart Wheel</h3><img src="${chartUrl}" alt="Natal Chart" style="max-width:100%; height:auto;">`;
document.getElementById("results").appendChild(chartDiv);
}La risposta dell’API del tema natale include gia un campo chart.url con l’URL dell’immagine SVG del grafico, quindi non e necessaria una richiesta separata. Passiamo semplicemente quell’URL a un tag <img> per visualizzare la ruota del tema con tutti i 12 segni zodiacali, le case, le posizioni dei pianeti e le linee degli aspetti.
Hai bisogno di un’immagine PNG invece - ad esempio, per condividere sui social media? Basta cambiare l’estensione .svg nell’URL in .png.
Passo 7: Mostra l’Oroscopo del Giorno
Aggiungiamo un tocco personale mostrando l’oroscopo di oggi per il segno solare della persona:
async function displayHoroscope(sunSign, sunSignTitle) {
const today = new Date().toISOString().split("T")[0];
const response = await fetch(
`${BASE_URL}/horoscope/daily/${today}?sign=${sunSign}&language=en`,
{ headers: { "X-Api-Key": API_KEY } }
);
const data = await response.json();
const signName = sunSignTitle;
const horoscopeDiv = document.createElement("div");
horoscopeDiv.innerHTML = `
<h3>Today's Horoscope for ${signName}</h3>
<div class="horoscope-box">${data.data.text}</div>
`;
document.getElementById("results").appendChild(horoscopeDiv);
}L’endpoint dell’oroscopo prende la data odierna nell’URL e il segno zodiacale come parametro di query. Gli oroscopi sono disponibili in più lingue - basta cambiare language=en in language=nl per l’olandese, language=es per lo spagnolo, language=fr per il francese, e così via.
Passo 8: Collega Tutto Insieme
Ora colleghiamo il modulo a tutte le nostre funzioni. Aggiungi il seguente codice alla tua sezione <script>, dopo tutte le funzioni dei passaggi precedenti:
const API_KEY = "your-api-key-here";
const BASE_URL = "https://api.astroapi.cloud/api";
document.getElementById("birth-form").addEventListener("submit", async (e) => {
e.preventDefault();
const name = document.getElementById("name").value;
const date = document.getElementById("date").value;
const time = document.getElementById("time").value;
const city = document.getElementById("city").value;
// Show a loading message
const results = document.getElementById("results");
results.innerHTML = '<p class="loading">Calculating your chart...</p>';
results.classList.remove("hidden");
try {
// 1. Find the coordinates and timezone for the birth city
const location = await findLocation(city);
// 2. Calculate the natal chart
const chart = await calculateChart(date, time, location.latitude, location.longitude, location.timezone);
// 3. Display the planetary positions
displayChart(chart, name);
// 4. Add the visual chart wheel using the URL from the API response
if (chart.data.chart?.url) {
displayChartImage(chart.data.chart.url);
}
// 5. Show today's horoscope based on the Sun sign
const sunSign = chart.data.points.sun.sign;
await displayHoroscope(sunSign, chart.data.points.sun.signTitle);
} catch (error) {
results.innerHTML = '<p style="color:red;">Something went wrong. Please check your API key and try again.</p>';
}
});Apri il file nel tuo browser, inserisci una data di nascita e una città, e clicca “Calculate My Chart.” In un paio di secondi, vedrai i dati completi del tema natale, una bellissima ruota del tema e un oroscopo personalizzato - il tutto alimentato da AstroAPI.
Andare Oltre: Compatibilità, Fasi Lunari e Altro
Ora che hai un’app di astrologia funzionante, ecco alcune funzionalità che potresti aggiungere:
Compatibilità amorosa - Usa l’endpoint di sinastria per confrontare due temi natali. Mostra quali pianeti formano aspetti armoniosi (trigoni, sestili) e quali creano tensione (quadrati, opposizioni). Perfetto per una funzionalità di “compatibilità di coppia”.
Tracker delle fasi lunari - L’endpoint moonphase restituisce la fase lunare attuale, la percentuale di illuminazione e gli orari di alba e tramonto della luna. Perfetto per un widget nella barra laterale o un aggiornamento quotidiano.
Avvisi sui transiti - I transiti mostrano dove si trovano i pianeti in questo momento rispetto al tema natale di qualcuno. Usa questo per creare funzionalità “cosa sta succedendo nel tuo tema oggi” - ad esempio, “Saturno sta attraversando il tuo Medio Cielo, un periodo di svolte nella carriera.”
Numerologia - Calcola i numeri del percorso di vita, i numeri dell’espressione e i numeri della personalità dalla data di nascita e dal nome di una persona. Un bel complemento ai dati astrologici.
Supporto multilingua - Tutti gli endpoint basati su testo (oroscopi, interpretazioni) supportano più lingue. Costruisci per un pubblico globale passando il parametro lang.
Proxy lato server - Per le app in produzione, considera di spostare le tue chiamate API su un piccolo server backend. In questo modo la tua API key rimane sul server e non viene mai esposta agli utenti. Le Domain Restrictions sono una buona prima linea di difesa, ma un proxy ti dà il controllo completo.
Esplora l’API Completa
Ciò che abbiamo trattato qui è solo l’inizio. La documentazione completa dell’API copre ogni endpoint in dettaglio, con esempi di richieste in cURL, JavaScript e Python.
Pronto per iniziare a costruire? Crea il tuo account gratuito e ottieni la tua API key oggi.