PrimuxDocs

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.

Basehttps://dev-api.primux.cloud AuthBearer SUA_CHAVE FormatoJSON · UTF-8
URL base
https://dev-api.primux.cloud/v1/clima

Visã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.
Os dados vêm de fontes públicas e são renovados no máximo a cada 30 minutos por item. Consultar mais vezes não traz dado mais novo, mas também não é problema: as respostas repetidas saem do dado já salvo.
Resposta 200
{
  "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

  1. Contrate a API no console (menu APIs), escolha o plano e pague a fatura.
  2. 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.
  3. 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.

Exemplo completo
curl -i "https://dev-api.primux.cloud/v1/clima?cidade=Londrina&uf=PR" \
  -H "Authorization: Bearer SUA_CHAVE"

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

Se vários sistemas seus precisam consultar a API, passe pelo seu servidor e guarde o resultado: assim você gasta menos consultas do plano.
Guardando 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.

Sem a chave, com chave errada ou de outra API a resposta é 401 ou 403 com um código de erro estável. Muitas tentativas com chave inválida bloqueiam o endereço por um minuto.
Cabeçalho HTTP
Authorization: Bearer 0123456789abcdefghijklmnopqrstuvwxyz0123456789

Referê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

cidade texto
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.
uf texto
Sigla do estado (ex.: PR). Use quando houver cidades de mesmo nome em estados diferentes.
pais texto
País com 2 letras. Padrão: BR.
latitude número
Latitude em graus, de -90 a 90. Use junto com longitude, no lugar da cidade.
longitude número
Longitude em graus, de -180 a 180. Use junto com latitude.
A busca ignora acentos e maiúsculas. Com a UF a resposta é mais exata; sem ela, vale a cidade mais conhecida com esse nome no país.
Requisição
curl "https://dev-api.primux.cloud/v1/clima?cidade=Londrina&uf=PR" \
  -H "Authorization: Bearer SUA_CHAVE"
Resposta
{
  "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.

Requisição
curl "https://dev-api.primux.cloud/v1/clima/sessao" \
  -H "Authorization: Bearer SUA_CHAVE"
Resposta
{
  "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.

Requisição
curl "https://dev-api.primux.cloud/v1/clima/uso" \
  -H "Authorization: Bearer SUA_CHAVE"
Resposta
{
  "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.nome texto
Nome da cidade encontrada.
local.estado texto pode faltar
Estado (ou região) da cidade.
local.pais texto
País, com 2 letras.
local.latitude número
Latitude usada na previsão.
local.longitude número
Longitude usada na previsão.
local.fuso texto pode faltar
Fuso horário da cidade (ex.: America/Sao_Paulo). Os horários da previsão estão nele.
atual.temperatura_c número
Temperatura agora, em °C.
atual.sensacao_c número
Sensação térmica agora, em °C.
atual.umidade_pct número
Umidade relativa do ar, em %.
atual.chuva_mm número
Chuva na última hora, em milímetros.
atual.vento_kmh número
Velocidade do vento, em km/h.
atual.vento_direcao_graus número
Direção de onde vem o vento, em graus (0 = norte, 90 = leste).
atual.codigo inteiro
Código do tempo (padrão WMO), por exemplo 0 céu limpo, 3 nublado, 63 chuva moderada, 95 trovoada.
atual.descricao texto
Descrição do tempo em português.
atual.dia booleano
true se é dia na cidade agora, false se é noite.
atual.observado_em texto
Horário da medição, no fuso da cidade.
previsao[].data texto
Dia da previsão (AAAA-MM-DD).
previsao[].minima_c número
Temperatura mínima do dia, em °C.
previsao[].maxima_c número
Temperatura máxima do dia, em °C.
previsao[].chance_chuva_pct número
Chance de chuva no dia, em %.
previsao[].chuva_mm número
Volume de chuva previsto no dia, em milímetros.
previsao[].indice_uv número
Índice UV máximo do dia.
previsao[].nascer_do_sol texto
Horário do nascer do sol.
previsao[].por_do_sol texto
Horário do pôr do sol.
previsao[].codigo inteiro
Código do tempo do dia (padrão WMO).
previsao[].descricao texto
Descrição do tempo do dia em português.
atualizado_em texto
Quando o dado foi obtido da fonte (UTC).
desatualizado booleano
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.
Dado salvo (fonte fora do ar)
{
  …
  "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.

StatusCódigoQuando acontece
400cidade_invalidaInforme a cidade (2 a 80 caracteres) ou a latitude e a longitude.
400uf_invalidaA UF não existe. Use a sigla com 2 letras, por exemplo PR.
400pais_invalidoO país deve ter 2 letras, por exemplo BR.
400coordenadas_invalidasLatitude fora de -90 a 90 ou longitude fora de -180 a 180.
404cidade_nao_encontradaNão encontramos a cidade. Confira o nome e informe a UF se houver cidades de mesmo nome.
401chave_invalidaChave ausente, errada ou de formato inválido.
403chave_de_outra_apiA chave é de outra API (por exemplo, a do clima usada nas cotações).
403sessao_suspensaA sessão está suspensa por falta de pagamento. Renove para voltar a usar.
403sessao_canceladaA sessão foi cancelada.
404rota_inexistenteA rota não existe. Confira o caminho nesta documentação.
429limite_por_minutoO limite de consultas por minuto do plano foi atingido. Espere alguns segundos.
429limite_diarioO limite de consultas do dia foi atingido. O contador zera à meia-noite.
429muitas_requisicoesMuitas requisições do mesmo endereço IP em pouco tempo.
429muitas_tentativasMuitas tentativas com chave inválida deste endereço. Espere um minuto.
503servico_indisponivelO serviço não respondeu agora. Tente de novo em instantes.
503fonte_indisponivelA fonte dos dados está fora do ar e ainda não há dado salvo para este item.
Resposta de erro
{
  "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.

Tentar de novo com segurança
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.