Como Construir uma Aplicacao de Astrologia com a AstroAPI
Construir uma aplicacao de astrologia costumava exigir conhecimentos profundos de calculos astronomicos, dados de efemerides e matematica complexa. Com a AstroAPI, pode saltar tudo isso e concentrar-se no que realmente importa: criar uma excelente experiencia de utilizador.
Neste tutorial, vamos construir uma pagina web completa de astrologia de raiz - uma pagina onde alguem introduz os seus dados de nascimento e ve instantaneamente o seu mapa natal com posicoes planetarias, uma roda grafica do mapa e o seu horoscopo diario. Nao e necessaria experiencia previa com APIs.
O Que Vai Precisar
- Uma conta AstroAPI (registe-se gratuitamente)
- Uma API key (disponivel no seu painel de controlo)
- Um editor de texto (VS Code, Sublime Text ou ate o Bloco de Notas)
- Um navegador web
E so isso - sem frameworks, sem ferramentas de compilacao, sem comandos de terminal. Vamos escrever tudo num unico ficheiro HTML.
Passo 1: Obter a Sua API Key
Apos registar-se, aceda ao seu painel de controlo. A sua API key e como uma palavra-passe que identifica a sua aplicacao perante a AstroAPI - vai precisar dela para cada pedido.
Encontrar a pagina de API Keys
No canto superior direito do painel de controlo, clique no icone do seu perfil. Aparecera um menu suspenso. Na seccao Integration, clique em API Keys.
Isto leva-o a visao geral das API Keys. Vera uma barra de navegacao mostrando o seu caminho atual: Profile > Integration > API Keys. Clique no botao Create no canto superior direito para criar uma nova chave.
Criar a sua chave
Na pagina de criacao, vera um formulario com varias seccoes:
- Name - De a sua chave um nome reconhecivel (por exemplo, “A Minha App de Astrologia” ou “Producao”).
- Expires In (days) - Opcionalmente defina uma data de expiracao. Deixe vazio se a chave deve durar indefinidamente.
- Permissions - Selecione quais funcionalidades da API a chave pode aceder. Para este tutorial, vai precisar pelo menos das permissoes de calculo (
calc). Pode marcar “Use all permissions from my role” para simplificar. - Modules - Escolha quais modulos a chave pode utilizar. Para este tutorial, selecione os modulos natais (
natal:calc,natal:charts,natal:texts). Tambem pode marcar “Use all modules from my organization” para permitir tudo. - Domain Restrictions - Este e importante. Como a sua API key estara visivel no codigo-fonte da pagina (qualquer pessoa pode ve-la atraves das ferramentas de desenvolvimento do navegador), deve restringi-la ao seu proprio dominio. Introduza o dominio do seu website (por exemplo,
mywebsite.com) para que apenas pedidos provenientes desse dominio sejam aceites. Dessa forma, mesmo que alguem copie a sua chave, nao podera usa-la no seu proprio site. Para desenvolvimento local, pode usar*temporariamente.
Clique em Save e a sua nova API key aparecera. Copie-a e guarde-a num local seguro - nao podera ver a chave completa novamente.
Passo 2: Criar a Sua Pagina HTML
Abra o seu editor de texto e crie um novo ficheiro chamado astrology.html. Vamos comecar com uma pagina basica que tem um formulario para os dados de nascimento:
<!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>Guarde o ficheiro e abra-o no seu navegador. Devera ver um formulario limpo a pedir os dados de nascimento. Ainda nao faz nada - vamos resolver isso.
Passo 3: Pesquisar a Localizacao de Nascimento
Quando alguem escreve “Amsterdam”, precisamos de converter isso em coordenadas de latitude e longitude. A AstroAPI tem um endpoint de geocoding para isso:
const API_KEY = "your-api-key-here";
const BASE_URL = "https://api.astroapi.cloud/api";Proteger a sua API key: Como esta e uma pagina web do lado do cliente, a sua API key e visivel para qualquer pessoa que veja o codigo-fonte da pagina. Isto nao e problema desde que tenha configurado as Domain Restrictions no painel de controlo (ver Passo 1). A API rejeitara pedidos de qualquer dominio que nao esteja na sua lista de permitidos, tornando a chave inutil para quem a copiar.
Agora vamos escrever as funcoes. Primeiro, a pesquisa de localizacao:
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
};
}Isto transforma “Amsterdam” em { latitude: 52.37, longitude: 4.89, timezone: "Europe/Amsterdam", name: "Amsterdam" } - exatamente o que precisamos para os calculos do mapa. O fuso horario e importante porque a AstroAPI precisa dele para converter corretamente a hora local de nascimento para tempo universal.
Passo 4: Calcular o Mapa Natal
Agora vamos enviar os dados de nascimento para a AstroAPI e obter todas as posicoes planetarias:
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();
}O dateTime e enviado como uma string ISO (por exemplo, "1990-06-15T14:30:00") e a location inclui o fuso horario para que a API possa interpretar corretamente a hora local de nascimento. A resposta contem tudo sobre o mapa: onde cada planeta estava posicionado, em que signo do zodiaco se encontrava, que casa ocupava e todas as relacoes geometricas (aspetos) entre planetas.
Passo 5: Apresentar os Resultados
Aqui e onde fica entusiasmante. Vamos transformar os dados brutos da API em algo visualmente atraente. Vamos mostrar uma tabela de posicoes planetarias e os signos de Sol, Lua e Ascendente da pessoa - os “tres grandes” que a maioria das pessoas quer saber:
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");
}A API devolve os planetas como um objeto indexado por ID de planeta (por exemplo, points.sun, points.moon). Cada planeta tem um sign (como "gemini"), signTitle (nome de exibicao como "Gemini"), degreesInSign (posicao dentro desse signo) e houseNumber. O signo Ascendente vem diretamente da propriedade sign na cuspide da primeira casa.
Passo 6: Adicionar uma Roda Grafica do Mapa
Um mapa natal ganha vida com a classica roda circular do mapa. A AstroAPI gera estas como imagens SVG que ficam nitidas em qualquer tamanho:
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);
}A resposta da API do mapa natal ja inclui um campo chart.url com a URL para a imagem SVG do grafico, por isso nao e necessario um pedido separado. Basta passar essa URL para uma tag <img> para exibir a roda do mapa com todos os 12 signos do zodiaco, casas, posicoes planetarias e linhas de aspetos.
Precisa de uma imagem PNG em vez disso - por exemplo, para partilhar nas redes sociais? Basta alterar a extensao .svg na URL para .png.
Passo 7: Mostrar o Horoscopo Diario
Vamos adicionar um toque pessoal mostrando o horoscopo de hoje para o signo solar da pessoa:
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);
}O endpoint de horoscopo recebe a data de hoje no URL e o signo do zodiaco como parametro de consulta. Os horoscopos estao disponiveis em varios idiomas - basta alterar language=en para language=nl para holandes, language=es para espanhol, language=fr para frances, e assim por diante.
Passo 8: Ligar Tudo
Agora vamos conectar o formulario a todas as nossas funcoes. Adicione o seguinte codigo a sua secao <script>, apos todas as funcoes dos passos anteriores:
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>';
}
});Abra o ficheiro no seu navegador, preencha uma data de nascimento e cidade, e clique em “Calculate My Chart.” Em poucos segundos, vera os dados completos do mapa natal, uma bela roda grafica do mapa e um horoscopo personalizado - tudo alimentado pela AstroAPI.
Indo Mais Alem: Compatibilidade, Fases da Lua e Mais
Agora que tem uma aplicacao de astrologia funcional, aqui estao algumas funcionalidades que pode adicionar a seguir:
Compatibilidade amorosa - Use o endpoint de sinastria para comparar dois mapas natais. Mostre quais planetas formam aspetos harmoniosos (trigonos, sextis) e quais criam tensao (quadraturas, oposicoes). Otimo para uma funcionalidade de “compatibilidade de relacionamento”.
Rastreador de fases da Lua - O endpoint de fases lunares devolve a fase lunar atual, percentagem de iluminacao e horas de nascimento/por do sol da Lua. Perfeito para um widget lateral ou atualizacao diaria.
Alertas de transitos - Os transitos mostram onde os planetas estao neste momento em comparacao com o mapa natal de alguem. Use isto para construir funcionalidades de “o que esta a acontecer no seu mapa hoje” - por exemplo, “Saturno esta a cruzar o seu Meio do Ceu, um periodo para avancos na carreira.”
Numerologia - Calcule numeros de caminho de vida, numeros de expressao e numeros de personalidade a partir da data de nascimento e nome de uma pessoa. Um bom complemento para os dados astrologicos.
Suporte multi-idioma - Todos os endpoints baseados em texto (horoscopos, interpretacoes) suportam varios idiomas. Construa para uma audiencia global passando o parametro lang.
Proxy do lado do servidor - Para aplicacoes de producao, considere mover as suas chamadas de API para um pequeno servidor backend. Desta forma, a sua API key permanece no servidor e nunca e exposta aos utilizadores. As Domain Restrictions sao uma boa primeira linha de defesa, mas um proxy da-lhe controlo total.
Explorar a API Completa
O que abordamos aqui e apenas o inicio. A documentacao completa da API cobre cada endpoint em detalhe, com exemplos de pedidos em cURL, JavaScript e Python.
Pronto para comecar a construir? Crie a sua conta gratuita e obtenha a sua API key hoje.