學習使用 API 並追蹤國際太空站（ISS）

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。URL 中常會夾帶查詢參數——所謂的 query parameters。

例如，以下這個 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 key。此時會把它放在參數中，例如 & apikey = YOUR_KEY。

天氣服務的文件可在 open-meteo.com 查閱。

3. API 回應長什麼樣？

當我們發出請求時，伺服器會用文字回覆：一段 JSON 字串。有時是 JSON 物件，有時是 JSON 陣列。

天氣回應範例：

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

回傳 ISS 座標的服務回應範例：

{
  "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. 範例二：追蹤國際太空站（ISS）

接著我們呼叫 open-notify.org 的 API，它會即時回傳國際太空站（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——需要密鑰。若是 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 與不同的貓咪知識。