Інтеграції з популярним REST API на прикладі OpenWeatherMap

Якщо ти хоч раз думав, яка погода за вікном, то замість того, щоб дивитися в вікно, можна скористатися OpenWeatherMap! Це популярний сервіс, що надає дані про погоду для різних локацій по всьому світу. Реальні розробники часто звертаються до таких зовнішніх API, щоб збагачувати свої застосунки даними типу температури, вологості або прогнозу на тиждень.

OpenWeatherMap API дозволяє:

• Отримувати поточну погоду для вказаного міста.
• Надавати прогноз погоди на кілька днів вперед.
• Надавати історичні дані про погоду.
• Працювати з глобальними геоданими.

---

Реєстрація і отримання API-ключа

Для доступу до OpenWeatherMap API знадобиться реєстрація. Після реєстрації:

1. Зайди на OpenWeatherMap.
2. Створи безкоштовний акаунт (якщо ти не готовий платити за розробку — ми будемо працювати з безкоштовним доступом).
3. Отримай свій API-ключ в розділі "API keys". Він знадобиться для аутентифікації запитів.

---

Налаштування структури проєкту

Перш ніж братися за код, переконаймося, що структура проєкту готова до інтеграції.

weather_app/
├── app/
│   ├── main.py
│   ├── routes/
│   │   ├── weather.py
│   ├── services/
│   │   ├── weather_service.py
│   ├── models/
│   │   ├── weather.py
├── requirements.txt

• routes/ — для маршрутів API.
• services/ — для логіки роботи з OpenWeatherMap API.
• models/ — для опису Pydantic-моделей.

---

Реалізація інтеграції: крок за кроком

Для роботи нам знадобляться такі бібліотеки:

• fastapi — для створення API.
• httpx — для відправки асинхронних HTTP-запитів.
• uvicorn — для запуску застосунку.

Встанови залежності з requirements.txt:

fastapi==0.115.8 
httpx==0.28.1
uvicorn==0.34.0

Або встанови їх напряму через pip:

pip install fastapi httpx uvicorn

Крок 1: створюємо базовий застосунок FastAPI

Створи файл app/main.py і додай туди основний запуск нашого застосунку:

from fastapi import FastAPI
from app.routes.weather import router as weather_router

app = FastAPI(title="Weather App")

# Підключаємо маршрути для роботи з погодою
app.include_router(weather_router, prefix="/weather")

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="127.0.0.1", port=8000)

Крок 2: створюємо маршрут для отримання погоди

У файлі app/routes/weather.py додамо маршрут для обробки запитів:

from fastapi import APIRouter, HTTPException
from app.services.weather_service import fetch_weather_data
from app.models.weather import WeatherResponse

router = APIRouter()

@router.get("/{city}", response_model=WeatherResponse)
async def get_weather(city: str):
    """
    Отримує поточну погоду для вказаного міста.
    """
    try:
        weather_data = await fetch_weather_data(city)
        return weather_data
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

Крок 3: реалізуємо логіку звернення до OpenWeatherMap API

Тепер створимо файл app/services/weather_service.py, де буде логіка роботи з OpenWeatherMap:

import httpx
from app.models.weather import WeatherResponse

API_KEY = "ваш_API_ключ_сюди"
BASE_URL = "https://api.openweathermap.org/data/2.5/weather"

async def fetch_weather_data(city: str) -> WeatherResponse:
    """
    Відправляє запит в OpenWeatherMap API для отримання даних про погоду.
    """
    params = {
        "q": city,
        "appid": API_KEY,
        "units": "metric",  # Отримуємо температуру в Цельсіях
    }

    async with httpx.AsyncClient() as client:
        response = await client.get(BASE_URL, params=params)
        if response.status_code == 200:
            data = response.json()
            return WeatherResponse(
                city=data["name"],
                temperature=data["main"]["temp"],
                description=data["weather"][0]["description"]
            )
        else:
            raise Exception(f"Помилка при отриманні даних: {response.text}")

Крок 4: додаємо Pydantic-модель для відповіді

Переходимо у файл app/models/weather.py і створюємо модель WeatherResponse для валідації і форматування даних:

from pydantic import BaseModel

class WeatherResponse(BaseModel):
    city: str
    temperature: float
    description: str

---

Запуск і тестування застосунку

Запусти застосунок:

uvicorn app.main:app --reload

Перевір роботу маршруту, використовуючи браузер або Postman, відправивши GET-запит:

http://127.0.0.1:8000/weather/London

Якщо все налаштовано правильно, ти отримаєш результат:

{
    "city": "London",
    "temperature": 15.5,
    "description": "clear sky"
}

Для тестування ти також можеш використати вбудований Swagger-інтерфейс FastAPI. Відкрий:

http://127.0.0.1:8000/docs

---

Розширення функціональності

Приклад 1: покращуємо функціонал маршруту

Додамо прогноз погоди на довший період. Для цього можна використати інший endpoint OpenWeatherMap, наприклад, /forecast.

BASE_FORECAST_URL = "https://api.openweathermap.org/data/2.5/forecast"

Реалізуй новий метод fetch_forecast_data для отримання прогнозу.

Приклад 2: додаємо підтримку кількох одиниць вимірювання

Додай параметр units для вибору між "metric", "imperial" та "standard".

---

Важливі моменти і типові помилки

Не забувай:

• Перевіряти, що твій API-ключ активний і в тебе немає перевищення ліміту запитів.
• Обробляти помилки на рівні коду (наприклад, при передачі некоректного міста).
• Логувати помилки, щоб швидше знаходити проблеми в роботі.

import logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

# Використовуй logger для запису помилок

Якщо OpenWeatherMap API повернув код 401 або 429, варто перевірити твій API-ключ або зменшити частоту запитів.