API の扱いを学び、ISS を追跡する

1. はじめに

いまどきのほとんどのアプリはインターネット上のデータを使っています。スマホで天気を見る、タクシーを呼ぶ、ニュースを読む——これらはすべてAPI を使った結果です。プログラム同士が互いにメッセージをやり取りし、ときには互いに「会話」します。多くの場合、そのメッセージはテキスト、すなわち JSON 形式です。

JSON（JavaScript Object Notation）はサービス間のデータ交換の事実上の標準になりました。人にとっても機械にとっても読みやすく扱いやすい形式です。JSON のルールはほんの数個です:

• データは オブジェクト（辞書） { "key": value } の形で表現されたり、
• 配列 [value1, value2] として表現されたり、
• あるいは単純な文字列、数値、真偽値、そして null として表されます。

たとえば、人を表す JSON オブジェクトは次のようになります。

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

ここではキー（name、age、skills）とその値が見えます。簡潔で、見やすく、汎用的です。

2. API の基礎

API（Application Programming Interface）は「取り決め」や「契約」のようなもので、特定のインターネット上のアドレスに、決められたパラメータでアクセスすれば、合意された形式で応答を返すという約束を意味します。

データ取得のためにアクセスする先のアドレスを エンドポイント と呼びます。これは単なる URL です。多くの場合、そこにリクエストパラメータ、いわゆる クエリパラメータ を含めます。

たとえば、次の 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 = 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. 例1: 天気を取得する

無料の天気 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. 例2: ISS を追跡する

次に、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"
}

まさに今、地球の上空を周回しているステーションの正確な座標を取得しました。1 分後にもう一度このコードを実行すれば——数値はすでに変わっているはずです。

6. 役立つポイント

API を扱い始めるときに、いくつか重要な点があります。

まずは常にレスポンスステータス（resp.statusCode()）を確認しましょう。200 なら問題ありません。404 ならアドレスが間違っています。401 ならキーが必要です。429 ならリクエストが多すぎます。

次に、レート制限を意識してください。無料サービスはサーバーの過負荷を避けるため、リクエストの頻度を制限しています。

さらに、JSON は常に美しく整形されているとは限りません。1 行の長い文字列になっていることも普通です。のちほど、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 が返ってきます。