OpenWeather API

Visão geral

A OpenWeather API fornece acesso a dados meteorológicos atuais, previsões e histórico climático para qualquer localização no mundo. Com a integração no SquadOS, seus agentes podem consultar o tempo atual, obter previsões de 5 dias, verificar qualidade do ar, índice UV, gerenciar estações meteorológicas pessoais e buscar camadas de mapa climático em tempo real.

• Site oficial: https://openweathermap.org/
• Documentação na Composio: docs.composio.dev/toolkits/openweather_api

Autenticação

Esta ferramenta utiliza chave de API (API_KEY) para conectar.

Você vai precisar dos seguintes campos:

Campo	Obrigatório	Descrição
api_key	Sim	Chave de API gerada no painel OpenWeatherMap em Account → My API Keys.

Como obter a credencial

1. Acesse home.openweathermap.org/users/sign_up e crie uma conta gratuita.
2. Confirme seu e-mail para ativar o acesso à API.
3. Faça login e acesse home.openweathermap.org/api_keys.
4. Copie a chave Default já gerada ou clique em Generate para criar uma nova chave com nome descritivo.
5. Aguarde alguns minutos para a chave ser ativada — requisições com uma chave recém-criada podem retornar 401 nos primeiros minutos.

Dica

Use uma chave dedicada para o SquadOS. O OpenWeatherMap permite criar múltiplas chaves de API e revogar individualmente, sem afetar outras integrações.

Como conectar no SquadOS

1. Acesse Ferramentas no menu lateral (/admin/tools).
2. Abra a aba Disponíveis e procure por OpenWeather API.
3. Clique no card para abrir o modal de detalhes e em Conectar.
4. Você é levado para a página de conexão segura hospedada pela Composio, onde informa a chave de API obtida acima.
5. Ao concluir, você volta para o SquadOS com a conta conectada e a ferramenta disponível para os agentes. (Detalhes do fluxo em Ferramentas da Organização.)

Ações disponíveis

Excluir estação meteorológica

OPENWEATHER_API_DELETE_WEATHER_STATION

Exclui uma estação meteorológica cadastrada. Use após identificar a estação a ser removida. Retorna uma mensagem de confirmação em caso de sucesso.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
station_id	string	Sim	O ID único da estação meteorológica a excluir.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter previsão de 5 dias

OPENWEATHER_API_GET5_DAY_FORECAST

Retorna a previsão de 5 dias com intervalos de 3 horas (até 40 timestamps UTC). Exatamente um identificador de localização deve ser fornecido por chamada: q, id, zip ou o par lat+lon. Use o offset city.timezone para converter timestamps para hora local antes de agrupar em resumos diários.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
q	string	Não	Nome da cidade e código de país opcional, ex: London,uk.
id	integer	Não	ID de cidade do OpenWeatherMap.
lat	number	Não	Latitude em graus.
lon	number	Não	Longitude em graus.
zip	string	Não	CEP/código postal com código de país, ex: 94040,us.
lang	string	Não	Código de idioma (ISO 639-1).
mode	string (json | xml | html)	Não	Formato da resposta.
units	string (standard | metric | imperial)	Não	Unidade de medida (padrão, métrico, imperial).

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter dados atuais de poluição do ar

OPENWEATHER_API_GET_AIR_POLLUTION_CURRENT

Busca os dados atuais de poluição do ar para uma localização. Use quando precisar de detalhes de qualidade do ar em tempo real a partir de latitude e longitude.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
lat	number	Sim	Latitude da localização, entre -90 e 90.
lon	number	Sim	Longitude da localização, entre -180 e 180.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter previsão de poluição do ar

OPENWEATHER_API_GET_AIR_POLLUTION_FORECAST

Retorna dados previstos de poluição do ar para uma localização específica. Use após confirmar latitude e longitude. A disponibilidade da previsão pode ser limitada para coordenadas remotas ou oceânicas; verifique os timestamps da resposta para confirmar se os dados representam uma previsão real e não uma foto do momento atual.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
lat	number	Sim	Latitude geográfica em graus decimais (intervalo -90 a 90).
lon	number	Sim	Longitude geográfica em graus decimais (intervalo -180 a 180).

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter histórico de poluição do ar

OPENWEATHER_API_GET_AIR_POLLUTION_HISTORY

Recupera dados históricos de poluição do ar. Use quando precisar de níveis de qualidade do ar passados para uma latitude/longitude e intervalo de tempo específicos.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
end	integer	Sim	Timestamp UNIX final (segundos UTC); deve ser maior ou igual a start.
lat	number	Sim	Latitude da localização (intervalo: -90 a 90).
lon	number	Sim	Longitude da localização (intervalo: -180 a 180).
start	integer	Sim	Timestamp UNIX inicial (segundos UTC); deve ser menor ou igual a end.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter clima de cidades em raio circular

OPENWEATHER_API_GET_CIRCLE_CITY_WEATHER

Busca dados do tempo atual em cidades ao redor de um ponto geográfico. Use quando precisar obter o clima dentro de um raio circular após confirmar latitude e longitude.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
cnt	integer	Não	Número de cidades a retornar no círculo (1–50). Padrão: 10.
lat	number	Sim	Latitude do centro do círculo em graus (-90 a 90).
lon	number	Sim	Longitude do centro do círculo em graus (-180 a 180).
lang	string	Não	Idioma da resposta (ISO 639-1).
mode	string (json | xml)	Não	Formato da resposta: json ou xml.
units	string (standard | metric | imperial)	Não	Unidade de medida: padrão, métrico ou imperial.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter clima atual

OPENWEATHER_API_GET_CURRENT_WEATHER

Recupera os dados do tempo atual para uma localização. Use quando precisar de informações meteorológicas atualizadas ao minuto. Exatamente um identificador de localização deve ser fornecido por chamada: q, id, zip ou o par lat+lon. Passar múltiplos identificadores causa erros ou resultados ambíguos.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
q	string	Não	Nome da cidade, código de estado e código de país, ex: London,uk.
id	integer	Não	ID de cidade, ex: 2172797.
lat	number	Não	Latitude geográfica, ex: 35.0.
lon	number	Não	Longitude geográfica, ex: 139.0.
zip	string	Não	CEP/código postal e código de país, ex: 94040,us.
lang	string	Não	Idioma da resposta (código ISO 639-1, ex: en).
units	string (standard | metric | imperial)	Não	Unidade de medida. standard (padrão), metric ou imperial.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Geocodificação por CEP/código postal

OPENWEATHER_API_GET_GEOCODING_BY_ZIP

Converte um CEP ou código postal em coordenadas geográficas. Use quando precisar de latitude e longitude para um código postal específico.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
zip	string	Sim	CEP/código postal e código de país separados por vírgula. Use códigos de país ISO 3166 (ex: 10001,US ou E14,GB).

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Geocodificação direta

OPENWEATHER_API_GET_GEOCODING_DIRECT

Converte um nome de localização em coordenadas geográficas. Use quando precisar de latitude e longitude para uma localização após confirmar o nome preciso.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
q	string	Sim	Consulta de localização incluindo nome da cidade, código de estado e código de país separados por vírgulas (ex: London,UK). Consultas ambíguas podem retornar múltiplos locais incompatíveis; use o formato completo de três partes cidade,código_estado,código_país (ex: Springfield,IL,US) e verifique o país/região retornado antes de usar as coordenadas.
limit	integer	Não	Número de resultados a retornar (1 a 5). Padrão: 5. Use 1 somente para localizações não ambíguas; para consultas ambíguas, revise todos os resultados para selecionar a correspondência correta.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Geocodificação reversa

OPENWEATHER_API_GET_GEOCODING_REVERSE

Converte coordenadas geográficas em nome de localização. Use quando precisar de informações de cidade, estado e país a partir de latitude e longitude.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
lat	number	Sim	Latitude da localização em graus decimais.
lon	number	Sim	Longitude da localização em graus decimais.
limit	integer	Não	Número de resultados a retornar (1 a 5).

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter medições de estação

OPENWEATHER_API_GET_STATION_MEASUREMENTS

Recupera medições agregadas de uma estação meteorológica com granularidade de minuto, hora ou dia. Use quando precisar de dados históricos de uma estação cadastrada específica.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
to	integer	Sim	Fim do intervalo de tempo (timestamp Unix em segundos).
from	integer	Sim	Início do intervalo de tempo (timestamp Unix em segundos).
type	string (m | h | d)	Sim	Tipo de agregação: m (minuto), h (hora) ou d (dia).
limit	integer	Sim	Número máximo de registros de medição a retornar.
station_id	string	Sim	ID interno da estação no OpenWeather.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter índice UV atual

OPENWEATHER_API_GET_UV_INDEX

Recupera o índice UV atual para uma localização. Use quando precisar do índice UV atualizado ao minuto a partir de latitude e longitude.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
lat	number	Sim	Latitude da localização, entre -90 e 90.
lon	number	Sim	Longitude da localização, entre -180 e 180.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter previsão de índice UV

OPENWEATHER_API_GET_UV_INDEX_FORECAST

Recupera a previsão do índice UV para uma localização específica. Use quando precisar dos valores futuros de índice UV após confirmar latitude e longitude. Retorna até 8 dias de dados. Os dados podem ser escassos ou ausentes para oceanos e regiões remotas; uma resposta vazia significa que não há dados disponíveis, e não que as condições de UV são seguras.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
cnt	integer	Não	Número de dias a retornar (1–8); padrão: 8.
lat	number	Sim	Latitude da localização, entre -90 e 90.
lon	number	Sim	Longitude da localização, entre -180 e 180.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter histórico de índice UV

OPENWEATHER_API_GET_UV_INDEX_HISTORY

Recupera dados históricos de índice UV para uma localização e intervalo de tempo especificados. Use quando precisar analisar tendências passadas de exposição UV após confirmar coordenadas e período de tempo.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
end	integer	Sim	Timestamp UNIX final (segundos UTC); deve ser maior ou igual a start.
lat	number	Sim	Latitude da localização (intervalo: -90 a 90).
lon	number	Sim	Longitude da localização (intervalo: -180 a 180).
start	integer	Sim	Timestamp UNIX inicial (segundos UTC); deve ser menor ou igual a end.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter tile de mapa climático (2.0)

OPENWEATHER_API_GET_WEATHER_MAP_TILE

Busca imagens de tiles do Weather Maps 2.0. Use quando precisar de camadas dinâmicas de clima em zoom e coordenadas específicos com opções avançadas de estilo.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
x	integer	Sim	Coordenada X do tile (inteiro não-negativo).
y	integer	Sim	Coordenada Y do tile (inteiro não-negativo).
z	integer	Sim	Nível de zoom do tile (inteiro não-negativo).
fill	string	Não	Cor para áreas sem dados (hex ou nome de cor).
color	string	Não	Esquema de cores dos tiles, ex: original, black.
layer	string (clouds | clouds_new | precipitation | precipitation_new | pressure | pressure_new | wind | wind_new | temp | temp_new)	Sim	Nome da camada climática. Opções: nuvens, precipitação, pressão, vento, temperatura (versão padrão ou nova).
scale	integer (1 | 2)	Não	Fator de escala do tile: 1 ou 2 para telas retina.
format	string	Não	Formato da imagem; somente png é suportado.
opacity	number	Não	Opacidade do tile entre 0.0 e 1.0.
palette	string	Não	Definição de paleta customizada (separada por vírgula ou JSON).
fill_bound	boolean	Não	Preencher tiles fora da cobertura de dados se verdadeiro.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter dados de estação meteorológica

OPENWEATHER_API_GET_WEATHER_STATION

Retorna informações sobre uma estação meteorológica específica pelo seu ID. Use quando precisar de detalhes sobre uma determinada estação.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
station_id	string	Sim	ID interno da estação para recuperar informações.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Listar estações meteorológicas

OPENWEATHER_API_GET_WEATHER_STATIONS

Lista todas as estações meteorológicas adicionadas à sua conta. Use após configurar sua chave de API do OpenWeather.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter gatilhos de clima

OPENWEATHER_API_GET_WEATHER_TRIGGERS

Recupera gatilhos de clima para condições específicas. Use após definir os critérios de acionamento.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
triggers	array	Sim	Lista de definições de gatilhos de clima.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Adicionar estação meteorológica

OPENWEATHER_API_POST_ADD_WEATHER_STATION

Adiciona uma nova estação meteorológica à sua conta. Use quando precisar registrar uma estação antes de enviar dados customizados.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
name	string	Sim	Nome da estação.
altitude	number	Sim	Altitude da estação em metros acima do nível do mar.
latitude	number	Sim	Latitude da estação, intervalo -90 a 90 graus.
longitude	number	Sim	Longitude da estação, intervalo -180 a 180 graus.
external_id	string	Sim	ID externo da estação (sua própria referência).

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Enviar medições de estação

OPENWEATHER_API_POST_SUBMIT_STATION_MEASUREMENTS

Envia medições meteorológicas de uma estação cadastrada. Use quando precisar transmitir dados de temperatura, vento, pressão, umidade ou precipitação de uma estação.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
measurements	array	Sim	Array de objetos de medição a enviar.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Atualizar estação meteorológica

OPENWEATHER_API_UPDATE_WEATHER_STATION

Atualiza os detalhes de uma estação meteorológica. Use quando precisar modificar o nome, localização ou ID externo de uma estação existente.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
name	string	Não	Nome legível da estação.
altitude	number	Não	Altitude da estação acima do nível do mar em metros.
latitude	number	Sim	Latitude da estação em graus, entre -90 e 90.
longitude	number	Sim	Longitude da estação em graus, entre -180 e 180.
station_id	string	Sim	Identificador único da estação meteorológica a atualizar.
external_id	string	Não	Identificador externo customizado fornecido pelo usuário.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.