Referência da API
API de Previsão do Tempo
Tempo atual e previsão de 7 dias para a cidade que você escolher a cada consulta, em português, com temperaturas em graus Celsius.
https://dev-api.primux.cloud AuthBearer SUA_CHAVE FormatoJSON · UTF-8https://dev-api.primux.cloud/v1/climaVisão geral
Você manda o nome da cidade (ou latitude e longitude) e recebe o tempo de agora e os 7 próximos dias. Serve para sites, aplicativos, painéis e mensagens automáticas.
- A cidade é escolhida em cada consulta: uma só chave atende quantas cidades você precisar.
- Cada dia da previsão traz mínima, máxima, chance e volume de chuva, índice UV e horários do nascer e do pôr do sol.
- O tempo vem com um código e uma descrição em português (por exemplo, Chuva moderada), prontos para exibir.
{
"local": {
"nome": "Londrina",
"estado": "Paraná",
"pais": "BR",
"latitude": -23.31028,
"longitude": -51.16278,
"fuso": "America/Sao_Paulo"
},
"atual": {
"temperatura_c": 30.1,
"sensacao_c": 33.2,
"umidade_pct": 55,
"chuva_mm": 0,
"vento_kmh": 4.6,
"vento_direcao_graus": 201,
"codigo": 3,
"descricao": "Nublado",
"dia": true,
"observado_em": "2026-11-19T18:30"
},
"previsao": [
{
"data": "2026-11-19",
"minima_c": 20.4,
"maxima_c": 31.2,
"chance_chuva_pct": 27,
"chuva_mm": 1.6,
"indice_uv": 9.1,
"nascer_do_sol": "2026-11-19T05:32",
"por_do_sol": "2026-11-19T18:41",
"codigo": 95,
"descricao": "Trovoada"
}
],
"atualizado_em": "2026-11-19T21:32:19Z",
"desatualizado": false
}Início rápido
- Contrate a API no console (menu APIs), escolha o plano e pague a fatura.
- Abra a sessão contratada e gere a chave de API. Ela aparece uma única vez: guarde-a em uma variável de ambiente do seu servidor.
- Faça a consulta enviando a chave no cabeçalho Authorization (Bearer) e use o JSON da resposta.
O exemplo consulta Londrina (PR), confere o status, avisa se o dado é o último salvo e mostra o tempo de agora e a previsão da semana.
curl -i "https://dev-api.primux.cloud/v1/clima?cidade=Londrina&uf=PR" \
-H "Authorization: Bearer SUA_CHAVE"<?php
$ch = curl_init('https://dev-api.primux.cloud/v1/clima?cidade=Londrina&uf=PR');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('PRIMUX_CLIMA_CHAVE')],
]);
$corpo = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$dados = json_decode($corpo, true);
if ($status !== 200) {
// erro, mensagem: veja a seção Erros
exit('Erro ' . $status . ': ' . ($dados['mensagem'] ?? 'sem resposta') . PHP_EOL);
}
if ($dados['desatualizado']) {
// a fonte estava fora do ar: este é o último dado salvo (veja atualizado_em)
}
echo $dados['local']['nome'] . ': ' . $dados['atual']['temperatura_c'] . ' °C, ' . $dados['atual']['descricao'] . PHP_EOL;
foreach ($dados['previsao'] as $dia) {
echo $dia['data'] . ' ' . $dia['minima_c'] . '/' . $dia['maxima_c'] . ' °C' . PHP_EOL;
}const resposta = await fetch('https://dev-api.primux.cloud/v1/clima?cidade=Londrina&uf=PR', {
headers: { Authorization: `Bearer ${process.env.PRIMUX_CLIMA_CHAVE}` },
});
const dados = await resposta.json();
if (!resposta.ok) {
// dados.erro e dados.mensagem: veja a seção Erros
throw new Error(`Erro ${resposta.status}: ${dados.mensagem}`);
}
if (dados.desatualizado) {
// a fonte estava fora do ar: este é o último dado salvo (veja atualizado_em)
}
console.log(`${dados.local.nome}: ${dados.atual.temperatura_c} °C, ${dados.atual.descricao}`);
for (const dia of dados.previsao) console.log(dia.data, dia.minima_c, dia.maxima_c);import os, sys, requests
resposta = requests.get(
"https://dev-api.primux.cloud/v1/clima?cidade=Londrina&uf=PR",
headers={"Authorization": f"Bearer {os.environ['PRIMUX_CLIMA_CHAVE']}"},
timeout=15,
)
dados = resposta.json()
if resposta.status_code != 200:
# dados["erro"] e dados["mensagem"]: veja a seção Erros
sys.exit(f"Erro {resposta.status_code}: {dados.get('mensagem')}")
if dados["desatualizado"]:
pass # a fonte estava fora do ar: este é o último dado salvo (veja atualizado_em)
print(f"{dados['local']['nome']}: {dados['atual']['temperatura_c']} °C, {dados['atual']['descricao']}")
for dia in dados["previsao"]:
print(dia["data"], dia["minima_c"], dia["maxima_c"])Chave de API
Cada sessão contratada tem a sua própria chave. A chave identifica o plano, conta as consultas e vale só para esta API.
- A chave aparece uma única vez, na hora de gerar. Se perder, gere outra: a anterior deixa de funcionar na hora.
- Use a chave só no seu servidor (back-end). Nunca a coloque em aplicativo, página ou código que o público consiga ler.
- Uma chave não abre outra API: a chave do clima não consulta cotações nem loterias (erro chave_de_outra_api).
Abrir o console e gerar a chave
export PRIMUX_CLIMA_CHAVE="COLE_AQUI_A_SUA_CHAVE"Autenticação
Envie a chave em todas as requisições, no cabeçalho Authorization, no formato Bearer. Não há parâmetro de URL para a chave.
Authorization: Bearer 0123456789abcdefghijklmnopqrstuvwxyz0123456789Referência da API
Previsão do tempo
GET/v1/clima
Devolve o tempo agora e a previsão dos próximos 7 dias da cidade pedida. Informe a cidade (e, se quiser, a UF) ou as coordenadas. A primeira consulta de uma cidade resolve o local; as seguintes usam o dado salvo por até 30 minutos.
Parâmetros da URL
cidadetexto- Nome da cidade, de 2 a 80 caracteres, com ou sem acento (ex.: Londrina, São Paulo). Obrigatório quando não houver latitude e longitude.
uftexto- Sigla do estado (ex.: PR). Use quando houver cidades de mesmo nome em estados diferentes.
paistexto- País com 2 letras. Padrão: BR.
latitudenúmero- Latitude em graus, de -90 a 90. Use junto com longitude, no lugar da cidade.
longitudenúmero- Longitude em graus, de -180 a 180. Use junto com latitude.
curl "https://dev-api.primux.cloud/v1/clima?cidade=Londrina&uf=PR" \
-H "Authorization: Bearer SUA_CHAVE"<?php
$ch = curl_init('https://dev-api.primux.cloud/v1/clima?cidade=Londrina&uf=PR');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('PRIMUX_CLIMA_CHAVE')],
]);
$dados = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);const resposta = await fetch('https://dev-api.primux.cloud/v1/clima?cidade=Londrina&uf=PR', {
headers: { Authorization: `Bearer ${process.env.PRIMUX_CLIMA_CHAVE}` },
});
const dados = await resposta.json();import os, requests
resposta = requests.get(
"https://dev-api.primux.cloud/v1/clima?cidade=Londrina&uf=PR",
headers={"Authorization": f"Bearer {os.environ['PRIMUX_CLIMA_CHAVE']}"},
timeout=15,
)
dados = resposta.json(){
"local": {
"nome": "Londrina",
"estado": "Paraná",
"pais": "BR",
"latitude": -23.31028,
"longitude": -51.16278,
"fuso": "America/Sao_Paulo"
},
"atual": {
"temperatura_c": 30.1,
"sensacao_c": 33.2,
"umidade_pct": 55,
"chuva_mm": 0,
"vento_kmh": 4.6,
"vento_direcao_graus": 201,
"codigo": 3,
"descricao": "Nublado",
"dia": true,
"observado_em": "2026-11-19T18:30"
},
"previsao": [
{
"data": "2026-11-19",
"minima_c": 20.4,
"maxima_c": 31.2,
"chance_chuva_pct": 27,
"chuva_mm": 1.6,
"indice_uv": 9.1,
"nascer_do_sol": "2026-11-19T05:32",
"por_do_sol": "2026-11-19T18:41",
"codigo": 95,
"descricao": "Trovoada"
}
],
"atualizado_em": "2026-11-19T21:32:19Z",
"desatualizado": false
}Referência da API
Sessão e plano
GET/v1/clima/sessao
Mostra o nome da sessão, o plano, o estado, a validade e os limites do plano. Não conta como consulta nos limites de uso do plano, mas passa pela mesma autenticação.
curl "https://dev-api.primux.cloud/v1/clima/sessao" \
-H "Authorization: Bearer SUA_CHAVE"<?php
$ch = curl_init('https://dev-api.primux.cloud/v1/clima/sessao');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('PRIMUX_CLIMA_CHAVE')],
]);
$dados = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);const resposta = await fetch('https://dev-api.primux.cloud/v1/clima/sessao', {
headers: { Authorization: `Bearer ${process.env.PRIMUX_CLIMA_CHAVE}` },
});
const dados = await resposta.json();import os, requests
resposta = requests.get(
"https://dev-api.primux.cloud/v1/clima/sessao",
headers={"Authorization": f"Bearer {os.environ['PRIMUX_CLIMA_CHAVE']}"},
timeout=15,
)
dados = resposta.json(){
"nome": "Meu site",
"plano": "Clima 5.000",
"estado": "criada",
"valido_ate": "2026-12-19T14:30:00Z",
"limite_diario": 5000,
"limite_por_minuto": 60
}Referência da API
Uso
GET/v1/clima/uso
Mostra quantas consultas a sessão fez hoje e no mês e, se o plano tem limite diário, quantas ainda restam hoje. O contador do dia zera à meia-noite.
curl "https://dev-api.primux.cloud/v1/clima/uso" \
-H "Authorization: Bearer SUA_CHAVE"<?php
$ch = curl_init('https://dev-api.primux.cloud/v1/clima/uso');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('PRIMUX_CLIMA_CHAVE')],
]);
$dados = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);const resposta = await fetch('https://dev-api.primux.cloud/v1/clima/uso', {
headers: { Authorization: `Bearer ${process.env.PRIMUX_CLIMA_CHAVE}` },
});
const dados = await resposta.json();import os, requests
resposta = requests.get(
"https://dev-api.primux.cloud/v1/clima/uso",
headers={"Authorization": f"Bearer {os.environ['PRIMUX_CLIMA_CHAVE']}"},
timeout=15,
)
dados = resposta.json(){
"data": "2026-11-19",
"consultas_hoje": 128,
"consultas_no_mes": 2410,
"limite_diario": 5000,
"restante_hoje": 4872
}Campos da resposta
Todos os campos da resposta de sucesso. Campos marcados como "pode faltar" aparecem só quando a fonte informa o valor.
local.nometexto- Nome da cidade encontrada.
local.estadotexto pode faltar- Estado (ou região) da cidade.
local.paistexto- País, com 2 letras.
local.latitudenúmero- Latitude usada na previsão.
local.longitudenúmero- Longitude usada na previsão.
local.fusotexto pode faltar- Fuso horário da cidade (ex.: America/Sao_Paulo). Os horários da previsão estão nele.
atual.temperatura_cnúmero- Temperatura agora, em °C.
atual.sensacao_cnúmero- Sensação térmica agora, em °C.
atual.umidade_pctnúmero- Umidade relativa do ar, em %.
atual.chuva_mmnúmero- Chuva na última hora, em milímetros.
atual.vento_kmhnúmero- Velocidade do vento, em km/h.
atual.vento_direcao_grausnúmero- Direção de onde vem o vento, em graus (0 = norte, 90 = leste).
atual.codigointeiro- Código do tempo (padrão WMO), por exemplo 0 céu limpo, 3 nublado, 63 chuva moderada, 95 trovoada.
atual.descricaotexto- Descrição do tempo em português.
atual.diabooleano- true se é dia na cidade agora, false se é noite.
atual.observado_emtexto- Horário da medição, no fuso da cidade.
previsao[].datatexto- Dia da previsão (AAAA-MM-DD).
previsao[].minima_cnúmero- Temperatura mínima do dia, em °C.
previsao[].maxima_cnúmero- Temperatura máxima do dia, em °C.
previsao[].chance_chuva_pctnúmero- Chance de chuva no dia, em %.
previsao[].chuva_mmnúmero- Volume de chuva previsto no dia, em milímetros.
previsao[].indice_uvnúmero- Índice UV máximo do dia.
previsao[].nascer_do_soltexto- Horário do nascer do sol.
previsao[].por_do_soltexto- Horário do pôr do sol.
previsao[].codigointeiro- Código do tempo do dia (padrão WMO).
previsao[].descricaotexto- Descrição do tempo do dia em português.
atualizado_emtexto- Quando o dado foi obtido da fonte (UTC).
desatualizadobooleano- true quando a fonte falhou na renovação e este é o último dado salvo.
Atualização dos dados
O painel não consulta a fonte a cada chamada sua. Cada item (cidade, conjunto de pares ou concurso mais recente) é renovado no máximo a cada 30 minutos e guardado; as chamadas seguintes recebem o dado salvo.
- atualizado_em diz quando o dado foi obtido da fonte (horário UTC).
- Se a fonte estiver fora do ar na hora de renovar, você recebe o último dado salvo e desatualizado vem como true.
- Se a fonte estiver fora e nunca houve dado salvo para o item, a resposta é 503 fonte_indisponivel.
{
…
"atualizado_em": "2026-11-19T21:02:11Z",
"desatualizado": true
}Erros
Todo erro devolve um JSON com erro (código estável, para você testar no código) e mensagem (texto em português). Teste o código, não o texto.
| Status | Código | Quando acontece |
|---|---|---|
| 400 | cidade_invalida | Informe a cidade (2 a 80 caracteres) ou a latitude e a longitude. |
| 400 | uf_invalida | A UF não existe. Use a sigla com 2 letras, por exemplo PR. |
| 400 | pais_invalido | O país deve ter 2 letras, por exemplo BR. |
| 400 | coordenadas_invalidas | Latitude fora de -90 a 90 ou longitude fora de -180 a 180. |
| 404 | cidade_nao_encontrada | Não encontramos a cidade. Confira o nome e informe a UF se houver cidades de mesmo nome. |
| 401 | chave_invalida | Chave ausente, errada ou de formato inválido. |
| 403 | chave_de_outra_api | A chave é de outra API (por exemplo, a do clima usada nas cotações). |
| 403 | sessao_suspensa | A sessão está suspensa por falta de pagamento. Renove para voltar a usar. |
| 403 | sessao_cancelada | A sessão foi cancelada. |
| 404 | rota_inexistente | A rota não existe. Confira o caminho nesta documentação. |
| 429 | limite_por_minuto | O limite de consultas por minuto do plano foi atingido. Espere alguns segundos. |
| 429 | limite_diario | O limite de consultas do dia foi atingido. O contador zera à meia-noite. |
| 429 | muitas_requisicoes | Muitas requisições do mesmo endereço IP em pouco tempo. |
| 429 | muitas_tentativas | Muitas tentativas com chave inválida deste endereço. Espere um minuto. |
| 503 | servico_indisponivel | O serviço não respondeu agora. Tente de novo em instantes. |
| 503 | fonte_indisponivel | A fonte dos dados está fora do ar e ainda não há dado salvo para este item. |
{
"erro": "limite_diario",
"mensagem": "Limite diário de envios do plano atingido. O contador zera à meia-noite."
}Limites e boas práticas
- Cada consulta bem-sucedida conta uma unidade no limite do plano (por minuto e por dia). Consultas recusadas por chave inválida não contam.
- O limite por minuto usa uma janela deslizante; o limite diário zera à meia-noite (horário de Brasília).
- Passou do limite: a resposta é 429 com limite_por_minuto ou limite_diario. Nada é cobrado a mais.
- Veja o uso do dia e do mês em /uso e os limites do seu plano em /sessao.
Boas práticas
- Guarde o resultado no seu sistema pelo mesmo tempo que a API guarda (até 30 minutos): você gasta menos consultas e responde mais rápido.
- Defina um tempo máximo (timeout) de 10 a 15 segundos nas chamadas.
- Trate 429 e 503 esperando e tentando de novo, sem repetir em laço apertado.
- Confira desatualizado: se for true, mostre o dado mesmo assim e, se for importante, avise o usuário da hora em atualizado_em.
Tentar de novo com segurança
Para 429 e 503, espere e tente de novo com intervalo crescente (1, 2, 4, 8 segundos) e desista depois de poucas tentativas.
import os, time, requests
def consultar(url, tentativas=4):
for n in range(tentativas):
r = requests.get(url, headers={"Authorization": f"Bearer {os.environ['PRIMUX_CLIMA_CHAVE']}"}, timeout=15)
if r.status_code not in (429, 503):
return r
time.sleep(2 ** n) # 1 s, 2 s, 4 s, 8 s
return r
resposta = consultar("https://dev-api.primux.cloud/v1/clima?cidade=Londrina&uf=PR")Perguntas frequentes
Como informo a cidade?
Pelo parâmetro cidade (com a UF, se quiser) ou por latitude e longitude. A busca ignora acentos. Para cidades de mesmo nome, informe a uf.
Quantos dias de previsão vêm?
Sete dias, incluindo hoje, em previsao, além do tempo de agora em atual.
Em que fuso estão os horários?
No fuso da própria cidade (campo local.fuso). Os horários não trazem deslocamento: considere o fuso informado.
De onde vêm os dados?
De uma fonte meteorológica pública. O painel renova cada cidade no máximo a cada 30 minutos; veja atualizado_em.