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.com.br AuthBearer SUA_CHAVE FormatoJSON · UTF-8https://dev-api.primux.com.br/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.com.br/v1/clima?cidade=Londrina&uf=PR" \
-H "Authorization: Bearer SUA_CHAVE"<?php
$ch = curl_init('https://dev-api.primux.com.br/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.com.br/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.com.br/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.com.br/v1/clima?cidade=Londrina&uf=PR" \
-H "Authorization: Bearer SUA_CHAVE"<?php
$ch = curl_init('https://dev-api.primux.com.br/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.com.br/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.com.br/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
Dias passados
GET/v1/clima/historico
Devolve o que o tempo fez nos últimos dias (de 1 a 30, sem contar hoje), do mais antigo ao mais recente: mínima, máxima, chuva e a descrição de cada dia. Informe a cidade (e, se quiser, a UF) ou as coordenadas, como na previsão.
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.
diasinteiro- Quantos dias passados devolver, de 1 a 30, sem contar hoje. Padrão: 7.
curl "https://dev-api.primux.com.br/v1/clima/historico?cidade=Londrina&uf=PR&dias=3" \
-H "Authorization: Bearer SUA_CHAVE"<?php
$ch = curl_init('https://dev-api.primux.com.br/v1/clima/historico?cidade=Londrina&uf=PR&dias=3');
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.com.br/v1/clima/historico?cidade=Londrina&uf=PR&dias=3', {
headers: { Authorization: `Bearer ${process.env.PRIMUX_CLIMA_CHAVE}` },
});
const dados = await resposta.json();import os, requests
resposta = requests.get(
"https://dev-api.primux.com.br/v1/clima/historico?cidade=Londrina&uf=PR&dias=3",
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"
},
"dias": [
{
"data": "2026-11-16",
"minima_c": 19.8,
"maxima_c": 30.4,
"chuva_mm": 0,
"codigo": 2,
"descricao": "Parcialmente nublado"
}
],
"atualizado_em": "2026-11-19T21:32:19Z",
"desatualizado": false
}Referência da API
Busca de cidades
GET/v1/clima/cidades
Procura cidades pelo nome, com estado e país opcionais (Toledo, PR, Brasil). Quem combina com o estado e o país vem primeiro; depois, as mais populosas. Use para montar uma tela de escolha e consultar o clima pelas coordenadas devolvidas.
Parâmetros da URL
buscatexto obrigatório- Nome da cidade, de 2 a 80 caracteres, seguido de estado (nome ou sigla) e país, separados por vírgula (ex.: Toledo, PR, Brasil).
limiteinteiro- Máximo de cidades devolvidas, de 1 a 20. Padrão: 10.
curl "https://dev-api.primux.com.br/v1/clima/cidades?busca=Toledo,%20PR" \
-H "Authorization: Bearer SUA_CHAVE"<?php
$ch = curl_init('https://dev-api.primux.com.br/v1/clima/cidades?busca=Toledo,%20PR');
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.com.br/v1/clima/cidades?busca=Toledo,%20PR', {
headers: { Authorization: `Bearer ${process.env.PRIMUX_CLIMA_CHAVE}` },
});
const dados = await resposta.json();import os, requests
resposta = requests.get(
"https://dev-api.primux.com.br/v1/clima/cidades?busca=Toledo,%20PR",
headers={"Authorization": f"Bearer {os.environ['PRIMUX_CLIMA_CHAVE']}"},
timeout=15,
)
dados = resposta.json(){
"cidades": [
{
"nome": "Toledo",
"estado": "Paraná",
"pais": "BR",
"latitude": -24.71355,
"longitude": -53.74366,
"fuso": "America/Sao_Paulo",
"populacao": 150470
}
],
"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.com.br/v1/clima/sessao" \
-H "Authorization: Bearer SUA_CHAVE"<?php
$ch = curl_init('https://dev-api.primux.com.br/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.com.br/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.com.br/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.com.br/v1/clima/uso" \
-H "Authorization: Bearer SUA_CHAVE"<?php
$ch = curl_init('https://dev-api.primux.com.br/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.com.br/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.com.br/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. |