Вчимося працювати з API та стежимо за МКС

1. Вступ

Сьогодні майже будь‑який сучасний застосунок використовує дані з інтернету. Коли ви відкриваєте погоду в телефоні, замовляєте таксі або читаєте новини — це завжди результат роботи з API. Програми «розмовляють» одна з одною, обмінюються повідомленнями, і найчастіше ці повідомлення — це простий текст у форматі JSON.

JSON (JavaScript Object Notation) став стандартом для обміну даними між сервісами. Його люблять і програмісти, і машини: людині його легко прочитати, а програмі — розібрати. У JSON усього кілька правил:

• дані зберігаються як об’єкти‑словники { "ключ": значення },
• як масиви [значення1, значення2],
• або як прості рядки, числа, булеві значення та null.

Наприклад, так може виглядати JSON‑об’єкт, що описує людину:

{
  "name": "Alice",
  "age": 25,
  "skills": ["Java", "Python", "SQL"]
}

Ми бачимо ключі (name, age, skills) та їхні значення. Компактно, наочно й універсально.

2. Знайомство з API

API (Application Programming Interface) — це «угода» або «контракт»: звертаєтеся за певною адресою в інтернеті, передаєте потрібні параметри — і сервер повертає відповідь у погодженому форматі.

Адресу, за якою звертаються по дані, називають кінцевою точкою (endpoint). Це просто URL. Часто в ньому зазначають параметри запиту — так звані query‑параметри.

Наприклад, ось такий URL повертає прогноз погоди для Києва:

https://api.open-meteo.com/v1/forecast?latitude=50.45&longitude=30.52&current_weather=true

Якщо придивитися, після знака ? перелічені параметри:

• latitude = 50.45 — широта,
• longitude = 30.52 — довгота,
• current_weather = true — хочемо поточну погоду.

Деякі API вимагають ще й спеціальний «пароль» — ключ API. Його додають до параметрів, наприклад & apikey = ВАШ_КЛЮЧ.

Документацію сервісу погоди можна переглянути на сайті open-meteo.com.

3. Як виглядає відповідь API?

Коли ми робимо запит, сервер відповідає текстом: JSON‑рядком. Іноді це JSON‑об’єкт, іноді — JSON‑масив.

Приклад відповіді про погоду:

{
  "latitude": 50.45,
  "longitude": 30.52,
  "current_weather": {
    "temperature": 21.3,
    "windspeed": 5.2,
    "weathercode": 1
  }
}

Приклад відповіді сервісу з координатами МКС:

{
  "timestamp": 1717590000,
  "iss_position": {
    "latitude": "48.1234",
    "longitude": "12.5678"
  },
  "message": "success"
}

4. Перший приклад: отримуємо погоду

Спробуємо написати невеликий фрагмент коду, який звернеться до безкоштовного API погоди open-meteo.com і просто виведе відповідь у консоль.

String url = "https://api.open-meteo.com/v1/forecast?latitude=50.45&longitude=30.52&current_weather=true";

HttpClient client = HttpClient.newHttpClient();
HttpRequest req = HttpRequest.newBuilder(URI.create(url)).GET().build();
HttpResponse<String> resp = client.send(req, HttpResponse.BodyHandlers.ofString());

System.out.println("HTTP-статус: " + resp.statusCode());
System.out.println("Відповідь сервера:");
System.out.println(resp.body());

Тут ми:

1. Створюємо клієнт HttpClient.
2. Формуємо GET‑запит (HttpRequest).
3. Надсилаємо його: client.send.
4. Отримуємо відповідь у вигляді рядка: HttpResponse<String>.

Якщо все працює, ви побачите HTTP‑статус 200 і JSON із погодою.

5. Другий приклад: стежимо за МКС

Тепер звернемося до API open-notify.org, що в реальному часі показує координати Міжнародної космічної станції (ISS).

String url = "http://api.open-notify.org/iss-now.json";

HttpClient client = HttpClient.newHttpClient();
HttpRequest req = HttpRequest.newBuilder(URI.create(url)).GET().build();
HttpResponse<String> resp = client.send(req, HttpResponse.BodyHandlers.ofString());

System.out.println(resp.body());

Результат виглядатиме так:

{
  "timestamp": 1717590000,
  "iss_position": {
    "latitude": "48.1234",
    "longitude": "12.5678"
  },
  "message": "success"
}

Просто зараз ви отримали точні координати станції, яка літає над Землею. Запустіть цей код ще раз за хвилину — значення вже зміняться.

6. Корисні нюанси

Коли ви починаєте працювати з API, важливо пам’ятати про кілька речей.

По‑перше, завжди дивіться на статус відповіді: resp.statusCode(). Якщо це 200 — усе гаразд. Якщо 404 — адреса некоректна. Якщо 401 — потрібен ключ API. Якщо 429 — ви робите надто багато запитів.

По‑друге, пам’ятайте про ліміти. Безкоштовні сервіси обмежують частоту запитів, щоб ніхто не перевантажував їхні сервери.

По‑третє, JSON не завжди виглядатиме «красиво». Іноді це довгий текст в один рядок — і це нормально. Згодом навчимося підключати бібліотеки (Jackson, Gson), щоб «розбирати» JSON на поля і працювати з ними як із об’єктами.

Ще один невеликий експеримент

Візьмемо API, що повертає випадковий факт про котів:

String url = "https://catfact.ninja/fact";

HttpClient client = HttpClient.newHttpClient();
HttpRequest req = HttpRequest.newBuilder(URI.create(url)).GET().build();
HttpResponse<String> resp = client.send(req, HttpResponse.BodyHandlers.ofString());

System.out.println(resp.body());

Запустіть цей фрагмент кілька разів — і щоразу отримуватимете новий JSON із якимось фактом.