Guia ·
API de clima: como colocar previsão do tempo no seu site?
Aprenda a integrar previsão do tempo no seu site usando uma API REST. Guia prático com exemplos em JavaScript e PHP para exibir temperatura, condições climáticas e previsão dos próximos dias.
Já entrou em um site de viagens ou delivery e viu a previsão do tempo da cidade? Esse recurso melhora a experiência do usuário e pode ser adicionado ao seu projeto em poucos minutos.
Neste guia, você vai aprender a integrar dados meteorológicos no seu site usando uma API simples, com exemplos prontos para copiar e colar.
Por que adicionar previsão do tempo?
Um widget de clima pode ser útil em diversos contextos:
- 🛒 E-commerce: Sugerir produtos com base no clima (guarda-chuvas em dias de chuva);
- 🍕 Delivery: Informar tempo de entrega considerando condições climáticas;
- ✈️ Turismo: Mostrar o clima do destino escolhido;
- 📱 Apps: Exibir informações contextuais para o usuário.
Qual API de previsão do tempo usar?
A
- 🌡️ Temperatura atual e sensação térmica;
- ☁️ Condições climáticas (ensolarado, nublado, chuva...);
- 📅 Previsão para 15 dias;
- 🌅 Nascer e pôr do sol;
- 🌙 Fase da lua.
Os dados são retornados em JSON com documentação em português, facilitando a integração.
Quanto custa?
O plano gratuito inclui requisições diárias suficientes para projetos pessoais e testes.
Para aplicações em produção, existem
Como começar: passo a passo
1. Crie sua chave de API
- Acesse console.hgbrasil.com;
- Crie sua conta gratuita (não precisa de cartão de crédito);
- Gere uma chave do tipo "uso exposto" para aplicações frontend.
O processo leva menos de 2 minutos. Guarde sua chave em um lugar seguro!
2. Faça sua primeira requisição
Com a chave em mãos, você pode consultar o clima de qualquer cidade:
GEThttps://api.hgbrasil.com/weather?city_name=São Paulo,SP&key=suachave
Você pode buscar cidades de diferentes formas:
| Parâmetro | Exemplo | Descrição |
|---|---|---|
city_name | São Paulo,SP | Nome da cidade e estado |
woeid | 455827 | Código WOEID (mais rápido) |
lat e lon | -23.55,-46.63 | Coordenadas geográficas |
user_ip | remote | Detecta pelo IP do usuário |
Confira a
Exemplo prático: widget de clima
Vamos criar um widget que mostra o clima atual de uma cidade.
Estrutura HTML
Crie o arquivo index.html:
index.html
<!DOCTYPE html>
<html lang="pt-BR">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Previsão do Tempo</title>
<link rel="stylesheet" href="styles.css" />
</head>
<body>
<div class="weather-widget" data-city="São Paulo,SP">
<p>Carregando...</p>
</div>
<script src="script.js"></script>
</body>
</html>
Buscando dados da API
Crie o arquivo script.js:
script.js
const API_KEY = 'SUA_CHAVE_AQUI'
const widgets = document.querySelectorAll('.weather-widget')
widgets.forEach((widget) => {
const city = widget.dataset.city
const url = `https://api.hgbrasil.com/weather?key=${API_KEY}&format=json-cors&city_name=${encodeURIComponent(city)}`
fetch(url)
.then((response) => response.json())
.then((data) => {
const weather = data.results
// URL do ícone baseado na condição climática
const iconUrl = `https://assets.hgbrasil.com/weather/icons/conditions/${weather.condition_slug}.svg`
widget.innerHTML = `
<div class="weather-header">
<img class="weather-icon" src="${iconUrl}" alt="${weather.description}" />
<div class="weather-temp">${weather.temp}°C</div>
</div>
<div class="weather-description">${weather.description}</div>
<div class="weather-city">${weather.city_name}</div>
<div class="weather-details">
<span>💧 ${weather.humidity}%</span>
<span>💨 ${weather.wind_speedy}</span>
</div>
<div class="weather-sun">
🌅 ${weather.sunrise} | 🌇 ${weather.sunset}
</div>
`
})
.catch((error) => {
widget.innerHTML = '<p class="error">Erro ao carregar clima</p>'
console.error('Erro:', error)
})
})
Estilizando o widget
Crie o arquivo styles.css:
styles.css
* {
box-sizing: border-box;
margin: 0;
padding: 0;
}
body {
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
min-height: 100vh;
display: flex;
align-items: center;
justify-content: center;
padding: 20px;
}
.weather-widget {
background: rgba(255, 255, 255, 0.95);
border-radius: 20px;
padding: 24px;
min-width: 280px;
text-align: center;
box-shadow: 0 10px 40px rgba(0, 0, 0, 0.2);
}
.weather-header {
display: flex;
align-items: center;
justify-content: center;
gap: 16px;
margin-bottom: 12px;
}
.weather-icon {
width: 64px;
height: 64px;
}
.weather-temp {
font-size: 48px;
font-weight: 700;
color: #333;
}
.weather-description {
font-size: 18px;
color: #666;
text-transform: capitalize;
margin-bottom: 4px;
}
.weather-city {
font-size: 14px;
color: #888;
margin-bottom: 16px;
}
.weather-details {
display: flex;
justify-content: center;
gap: 20px;
font-size: 14px;
color: #555;
margin-bottom: 12px;
}
.weather-sun {
font-size: 12px;
color: #888;
}
.error {
color: #dc2626;
}
Lembre-se de usar
format=json-cors para requisições feitas diretamente do navegador. Saiba mais na Adicionando previsão dos próximos dias
A API retorna um array forecast com a previsão dos próximos dias. Vamos expandir o widget:
script.js
const API_KEY = 'SUA_CHAVE_AQUI'
const widgets = document.querySelectorAll('.weather-widget')
widgets.forEach((widget) => {
const city = widget.dataset.city
const url = `https://api.hgbrasil.com/weather?key=${API_KEY}&format=json-cors&city_name=${encodeURIComponent(city)}`
fetch(url)
.then((response) => response.json())
.then((data) => {
const weather = data.results
const iconUrl = `https://assets.hgbrasil.com/weather/icons/conditions/${weather.condition_slug}.svg`
// Gera HTML para os próximos 5 dias
const forecastHtml = weather.forecast
.slice(1, 6) // Pula o dia atual, pega os próximos 5
.map((day) => `
<div class="forecast-day">
<span class="forecast-weekday">${day.weekday}</span>
<span class="forecast-temp">${day.min}° / ${day.max}°</span>
</div>
`)
.join('')
widget.innerHTML = `
<div class="weather-header">
<img class="weather-icon" src="${iconUrl}" alt="${weather.description}" />
<div class="weather-temp">${weather.temp}°C</div>
</div>
<div class="weather-description">${weather.description}</div>
<div class="weather-city">${weather.city_name}</div>
<div class="weather-details">
<span>💧 ${weather.humidity}%</span>
<span>💨 ${weather.wind_speedy}</span>
</div>
<div class="forecast">
${forecastHtml}
</div>
`
})
.catch((error) => {
widget.innerHTML = '<p class="error">Erro ao carregar clima</p>'
console.error('Erro:', error)
})
})
Adicione ao CSS:
styles.css
.forecast {
display: flex;
justify-content: space-between;
margin-top: 16px;
padding-top: 16px;
border-top: 1px solid #eee;
}
.forecast-day {
display: flex;
flex-direction: column;
align-items: center;
gap: 4px;
}
.forecast-weekday {
font-size: 12px;
color: #888;
text-transform: uppercase;
}
.forecast-temp {
font-size: 12px;
color: #555;
font-weight: 500;
}
Exemplo em PHP (backend)
Para manter sua chave segura e implementar cache:
clima.php
<?php
$apiKey = 'SUA_CHAVE_AQUI';
$city = 'São Paulo,SP';
// Faz a requisição para a API
$url = "https://api.hgbrasil.com/weather?key={$apiKey}&city_name=" . urlencode($city);
$response = file_get_contents($url);
$data = json_decode($response, true);
if (!$data || !isset($data['results'])) {
die('Erro ao buscar dados do clima.');
}
$weather = $data['results'];
$iconUrl = "https://assets.hgbrasil.com/weather/icons/conditions/{$weather['condition_slug']}.svg";
?>
<!DOCTYPE html>
<html lang="pt-BR">
<head>
<meta charset="UTF-8">
<title>Clima em <?= htmlspecialchars($weather['city_name']) ?></title>
</head>
<body>
<div class="weather-widget">
<img src="<?= htmlspecialchars($iconUrl) ?>" alt="<?= htmlspecialchars($weather['description']) ?>" />
<h1><?= $weather['temp'] ?>°C</h1>
<p><?= htmlspecialchars($weather['description']) ?></p>
<p><?= htmlspecialchars($weather['city_name']) ?></p>
<p>Umidade: <?= $weather['humidity'] ?>% | Vento: <?= htmlspecialchars($weather['wind_speedy']) ?></p>
<h2>Próximos dias</h2>
<ul>
<?php foreach (array_slice($weather['forecast'], 1, 5) as $day): ?>
<li>
<?= htmlspecialchars($day['weekday']) ?>:
<?= $day['min'] ?>° / <?= $day['max'] ?>°
- <?= htmlspecialchars($day['description']) ?>
</li>
<?php endforeach; ?>
</ul>
</div>
</body>
</html>
Veja mais exemplos na
Detectando a cidade automaticamente
Você pode usar user_ip=remote para detectar a cidade do visitante automaticamente:
script.js
// Detecta automaticamente a cidade pelo IP do usuário
const url = `https://api.hgbrasil.com/weather?key=${API_KEY}&format=json-cors&user_ip=remote`
Isso é útil para mostrar o clima local sem pedir para o usuário selecionar a cidade.
A