[Funciona com Copiar e Colar] Crie um App de Previsão do Tempo em CLI com Python e uma API! Guia Passo a Passo para Iniciantes

"Comecei a programar, mas não sei o que fazer..." "Estou a estudar, mas sinto que vou desistir porque não consigo construir nada que funcione de verdade..."

Há apenas alguns meses, eu tinha exatamente as mesmas preocupações. Comecei a estudar por conta própria, do zero, com a ajuda de IA, e agora consigo até gerir os meus próprios websites. Pela minha experiência, a coisa mais importante na fase inicial da aprendizagem é a "experiência de construir algo com as próprias mãos e vê-lo a funcionar".

Neste artigo, vou explicar, de forma mais detalhada do que em qualquer outro lugar, como criar uma aplicação de linha de comandos (CLI) simples com Python que lhe dá a previsão do tempo, para que mesmo os iniciantes em programação possam sentir a alegria de "Funcionou! É divertido!".

A imagem final é algo assim. O que acontece quando se digita um comando no terminal (o ecrã preto)...?

$ python weather.py Tóquio

[ Clima em Tóquio (JP) ]
Tempo: céu limpo ☀️
Temperatura: 28.5℃ (Sensação térmica: 29.1℃)
Umidade: 65%
Velocidade do vento: 3.1 m/s

Não há nada de complicado! Apenas com copiar e colar, pode ter isto a funcionar no seu computador imediatamente. Vou partilhar honestamente os pontos em que eu próprio tive dificuldades, por isso pode seguir-me com toda a confiança.

PASSO 1: Prepare-se para a aventura! - Obter uma chave de API de meteorologia

Primeiro, surge o problema de onde obter a informação meteorológica. As previsões do tempo que vemos na televisão ou nos smartphones também se baseiam em dados observados por agências especializadas, como os institutos de meteorologia, certo?

Desta vez, vamos usar um serviço chamado OpenWeatherMap. Ao utilizar o mecanismo que este serviço oferece, chamado API, podemos obter livremente dados meteorológicos de todo o mundo para os nossos programas.

Não precisa de pensar muito sobre "O que é uma API?". Por agora, pense nela como uma espécie de "palavra-passe (chave) para obter dados meteorológicos a partir de um programa". Vou explicar os passos para obter esta chave (chave de API).

Aceda à página da API do OpenWeatherMap e clique no botão "Subscribe" em "Current Weather Data".
Clique no botão "Get API key" no plano gratuito e crie uma conta (definindo o seu email, palavra-passe, etc.).
Assim que o registo estiver concluído, a sua chave de API dedicada será emitida no separador "API keys" do seu painel de controlo. Esta cadeia de cerca de 32 caracteres alfanuméricos é a "palavra-passe" de que falei anteriormente.

【Super importante】Nunca diga a sua chave de API a ninguém nem a publique em redes sociais ou no GitHub!
Esta chave é para seu uso exclusivo. Se cair nas mãos de alguém com más intenções, essa pessoa poderá fazer um grande número de pedidos não autorizados, e você poderá acabar por ser cobrado por isso. Guarde-a com o mesmo cuidado que guarda a chave de sua casa.

PASSO 2: Reúna as ferramentas necessárias! - A biblioteca `requests`

Assim que tiver a sua chave de API, o próximo passo é preparar as ferramentas para usar a API a partir do Python. Essa ferramenta é uma biblioteca chamada `requests`.

Uma biblioteca é como uma "caixa de ferramentas" que já vem com um conjunto de funcionalidades convenientes. Com `requests`, pode aceder a websites e APIs com apenas algumas linhas de código.

Abra o terminal do seu PC (Command Prompt ou PowerShell no Windows, Terminal no Mac) e execute o seguinte comando.

pip install requests

Se aparecer uma mensagem como `Successfully installed...`, significa que foi bem-sucedido. Agora está tudo pronto para comunicar com a API de meteorologia!

PASSO 3: Vamos começar com algo simples!

Finalmente, chegou a hora de programar. Para começar, vamos escrever um código muito, muito simples para obter o tempo de uma cidade específica (neste caso, Tóquio). Crie um ficheiro chamado `weather.py` no seu editor e cole o seguinte código.

import requests
import json

# Substitua pela sua chave de API obtida no PASSO 1
API_KEY = "Cole_aqui_a_sua_chave_de_API"
CITY_NAME = "Tokyo"

# Construir o URL do pedido da API
api_url = f"https://api.openweathermap.org/data/2.5/weather?q={CITY_NAME}&appid={API_KEY}&units=metric&lang=pt"

try:
    # Enviar efetivamente o pedido à API
    response = requests.get(api_url)
    response.raise_for_status() # Lança uma exceção se houver um erro

    # Converter o resultado do formato JSON para um dicionário Python
    data = response.json()

    # Apresentar os dados de forma legível
    print(json.dumps(data, indent=2, ensure_ascii=False))

except requests.exceptions.RequestException as e:
    print(f"Ocorreu um erro de comunicação: {e}")
except Exception as e:
    print(f"Ocorreu um erro inesperado: {e}")

Depois de colar o código, não se esqueça de substituir a parte `API_KEY = "Cole_aqui_a_sua_chave_de_API"` pela sua própria chave de API que obteve anteriormente.

Depois de a substituir, vamos executar este ficheiro a partir do terminal.

$ python weather.py

Como correu? Se aparecer um monte de texto (dados) como o que se segue, significa que foi um sucesso!

{
  "coord": {
    "lon": 139.6917,
    "lat": 35.6895
  },
  "weather": [
    {
      "id": 800,
      "main": "Clear",
      "description": "céu limpo",
      "icon": "01d"
    }
  ],
  "base": "stations",
  "main": {
    "temp": 28.5,
    "feels_like": 29.1,
    "temp_min": 27.21,
    "temp_max": 29.58,
    "pressure": 1012,
    "humidity": 65
  },
  "visibility": 10000,
  "wind": {
    "speed": 3.09,
    "deg": 190
  },
  // ... e assim por diante
}

Isto é o estado bruto dos "dados meteorológicos atuais de Tóquio" enviados pelo OpenWeatherMap. O próximo passo é extrair apenas a informação necessária deste formato de dados chamado JSON.

【Explicação de um ponto de dificuldade】Como ler dados JSON
O JSON é constituído por uma combinação de `{}` (chavetas) e `[]` (parênteses retos).

`{}`: Representa um dicionário (objeto). É um conjunto de pares "chave" e "valor". Por exemplo, `"temp": 28.5` significa que "a chave 'temp' tem o valor 28.5".
`[]`: Representa uma lista (array). Contém vários dados por ordem.

Em Python, os `{}` do JSON podem ser tratados como "dicionários" e os `[]` como "listas", o que os torna muito compatíveis. Por exemplo, se quiser obter a temperatura (`temp`), basta aceder a `temp`, que está dentro do bloco maior `main`, escrevendo `data['main']['temp']`. Fácil, não é?

PASSO 4: Vamos melhorar a aplicação a sério!

Agora é que começa a parte a sério. Em vez de ter de alterar o código de cada vez, vamos evoluí-lo para uma forma de aplicação CLI a sério, permitindo que o utilizador introduza o nome de uma cidade e mostrando apenas a informação necessária de forma clara.

Desta vez, para criar uma aplicação CLI mais robusta, vamos usar a biblioteca padrão do Python, `argparse`. Com ela, pode passar informação no momento da execução, como por exemplo `python weather.py Lisboa`.

Substitua completamente o conteúdo do `weather.py` pelo seguinte. A forma de gerir a chave de API também foi alterada para uma forma mais segura.

import requests
import argparse
import os

def get_weather_emoji(weather_main):
    """Devolve um emoji a partir do nome do tempo em inglês"""
    if weather_main == "Clear":
        return "☀️"
    elif weather_main == "Clouds":
        return "☁️"
    elif weather_main == "Rain":
        return "🌧️"
    elif weather_main == "Drizzle":
        return "🌦️"
    elif weather_main == "Thunderstorm":
        return "⛈️"
    elif weather_main == "Snow":
        return "❄️"
    else:
        return "🌫️" # Névoa, Fumo, Neblina, Poeira, Nevoeiro, Areia, Cinza, Rajada, Tornado

def format_weather_data(data):
    """Formata a resposta da API e devolve-a como uma string"""
    try:
        city_name = data["name"]
        country = data["sys"]["country"]
        weather_description = data["weather"][0]["description"]
        weather_main = data["weather"][0]["main"]
        emoji = get_weather_emoji(weather_main)
        temp = data["main"]["temp"]
        feels_like = data["main"]["feels_like"]
        humidity = data["main"]["humidity"]
        wind_speed = data["wind"]["speed"]

        # Construir a string de saída para ser fácil de ler
        output = f"[ Clima em {city_name} ({country}) ]\n"
        output += f"Tempo: {weather_description} {emoji}\n"
        output += f"Temperatura: {temp}°C (Sensação térmica: {feels_like}°C)\n"
        output += f"Umidade: {humidity}%\n"
        output += f"Velocidade do vento: {wind_speed} m/s"
        
        return output
    except KeyError:
        return "Falha ao analisar os dados meteorológicos. O formato da resposta pode ser inválido."

def main():
    # 1. Obter a chave da API a partir de uma variável de ambiente
    #    para gerir a chave de forma mais segura
    api_key = os.getenv("OPENWEATHERMAP_API_KEY")
    if not api_key:
        print("Erro: A variável de ambiente 'OPENWEATHERMAP_API_KEY' não está definida.")
        print("Por favor, defina a chave da API e execute novamente.")
        return # Termina o programa

    # 2. Configurar os argumentos da linha de comandos
    parser = argparse.ArgumentParser(description="Apresenta a informação meteorológica atual para uma cidade especificada.")
    parser.add_argument("city", help="O nome da cidade para obter a previsão do tempo (ex: Lisboa)")
    parser.add_argument("-u", "--units", choices=["metric", "imperial"], default="metric", 
                        help="Especifica a unidade de temperatura ('metric' para Celsius, 'imperial' para Fahrenheit)")
    
    args = parser.parse_args()
    
    # 3. Enviar um pedido à API
    base_url = "https://api.openweathermap.org/data/2.5/weather"
    params = {
        "q": args.city,
        "appid": api_key,
        "units": args.units,
        "lang": "pt"
    }

    try:
        response = requests.get(base_url, params=params)
        # Lançar uma exceção para códigos de erro 4xx e 5xx
        response.raise_for_status()

        weather_data = response.json()
        
        # 4. Apresentar os resultados
        formatted_output = format_weather_data(weather_data)
        print(formatted_output)

    except requests.exceptions.HTTPError as e:
        if e.response.status_code == 401:
            print("Erro: Chave de API inválida. Por favor, verifique se a chave de API correta está definida.")
        elif e.response.status_code == 404:
            print(f"Erro: Cidade '{args.city}' não encontrada. Por favor, verifique o nome da cidade.")
        else:
            print(f"Ocorreu um erro HTTP: {e}")
    except requests.exceptions.RequestException as e:
        print(f"Ocorreu um erro de comunicação: {e}")
    except Exception as e:
        print(f"Ocorreu um erro inesperado: {e}")


if __name__ == "__main__":
    main()

【Importante】Como definir uma chave de API de forma segura (Variáveis de Ambiente)

Mencionei que é arriscado escrever a sua chave de API diretamente no código. Por isso, vamos usar um mecanismo chamado "variáveis de ambiente", que também é usado em ambientes profissionais. É uma forma de o seu próprio PC memorizar a chave de API.

Para Mac / Linux:

export OPENWEATHERMAP_API_KEY="a_sua_chave_de_API"

Para Windows (Command Prompt):

set OPENWEATHERMAP_API_KEY="a_sua_chave_de_API"

Para Windows (PowerShell):

$Env:OPENWEATHERMAP_API_KEY="a_sua_chave_de_API"

Execute o comando acima no seu terminal (a definição será reposta quando fechar o terminal). Com isto, o código `os.getenv("OPENWEATHERMAP_API_KEY")` conseguirá ler a chave que definiu no seu PC.

Quando estiver pronto, vamos executá-lo!

$ python weather.py Lisboa

Conseguiu ver o tempo em Lisboa com sucesso?

Agora, vamos tentar mostrar o tempo em São Paulo em Fahrenheit.

$ python weather.py "Sao Paulo" -u imperial

Não se esqueça de colocar o nome da cidade entre `"` (aspas duplas) se contiver espaços. Se a temperatura for apresentada em Fahrenheit (°F), foi um sucesso!

Tente introduzir deliberadamente um nome de cidade errado ou definir a chave de API errada para ver que as mensagens de erro são apresentadas corretamente. Isto é "tratamento de erros robusto".

Conclusão: Para além do "Funcionou!"

Bom trabalho! Concluiu agora a sua própria aplicação CLI de previsão do tempo. Mais do que apenas copiar e colar código, deve ter aprendido o seguinte:

Como obter dados externos usando uma API (`requests`)
Como lidar com o formato de dados JSON
Como gerir chaves de API de forma segura (variáveis de ambiente)
Como criar argumentos para uma aplicação CLI robusta (`argparse`)
Como criar um programa amigável que não falha com erros (`try-except`)
Como organizar o código usando funções

Aprender a programar tem tudo a ver com acumular estas "pequenas vitórias". Com base na aplicação que construiu hoje, tente personalizá-la com as suas próprias ideias, como "vamos mostrar várias cidades de uma vez", "vamos adicionar uma previsão de hora a hora" ou "vamos enviar os resultados para o WhatsApp".

Use a "alegria de criar coisas que funcionam" como seu combustível e continue a sua aventura no mundo da programação!

Para o próximo passo

Toda a gente que programa em Python acaba por se deparar com "erros de indentação". Não deixe de ler o nosso artigo que explica detalhadamente porque acontecem e como os corrigir.

Causas e Soluções para o IndentationError