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.com.br AuthBearer SUA_CHAVE FormatoJSON · UTF-8
URL base
https://dev-api.primux.com.br/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.com.br/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.com.br/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

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

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.
dias inteiro
Quantos dias passados devolver, de 1 a 30, sem contar hoje. Padrão: 7.
Requisição
curl "https://dev-api.primux.com.br/v1/clima/historico?cidade=Londrina&uf=PR&dias=3" \
  -H "Authorization: Bearer SUA_CHAVE"
Resposta
{
  "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

busca texto 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).
limite inteiro
Máximo de cidades devolvidas, de 1 a 20. Padrão: 10.
Requisição
curl "https://dev-api.primux.com.br/v1/clima/cidades?busca=Toledo,%20PR" \
  -H "Authorization: Bearer SUA_CHAVE"
Resposta
{
  "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.

Requisição
curl "https://dev-api.primux.com.br/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.com.br/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.