Jasmine Teaプログラミング

Web API

やること

この教材では、Jasmine Tea のプログラムでWeb APIを利用して外部サービスからデータを取得する方法を学びます。この例では、天気予報のデータを取得します。

ステップ1

エディターに以下のプログラムを入力してみましょう。

url$="https://jasminetea.app/webapi/weather?date=2&area=130010"
result@=fetch@(url$)

if result@[0]=-1 then
  print "天気予報取得成功！"
  weather@=result@[1]
  print "日付:";weather@[0]
  print "天気:";weather@[1]
  print "降水確率 (00:00-06:00):";weather@[2];"%"
  print "降水確率 (06:00-12:00):";weather@[3];"%"
  print "降水確率 (12:00-18:00):";weather@[4];"%"
  print "降水確率 (18:00-24:00):";weather@[5];"%"
else
  print "天気予報の取得に失敗しました。"
  print result@[1]
end if

ステップ2

エディターの右下にある「▶実行」ボタンを押すと、入力したプログラムが実行されます。実行した後は、画面の右上にある「ドキュメント」タブを押して、ここに戻ってきてください。

では、「▶実行」ボタンを押してください。

ステップ3

実行画面に以下のように表示されたら成功です。

「天気予報取得成功！」と表示され、日付、天気、時間帯ごとの降水確率が出力されます。
取得に失敗した場合は、「天気予報の取得に失敗しました。」とエラー内容が表示されます。

ステップ4

実行したプログラムを解説します。

使っている命令の簡単な紹介

fetch@ : 指定した URL からデータを取得する関数。結果は配列形式で返されます。
配列操作: 取得したデータを解析して必要な情報を取り出します。

以下の URL を例に、Web API の URL について詳しく見てみましょう。

url$ = "https://jasminetea.app/webapi/weather?date=1&area=130010"
result@ = fetch@(url$)

クエスチョンマーク ? の前までの部分が Web API 本体の URL です。この URL にアクセスすることで、API がデータを提供します。

https://jasminetea.app/webapi/weather

クエスチョンマーク ? 以降は「クエリーパラメーター」と呼ばれ、API に渡すデータを指定します。クエリーパラメーターは パラメーター名=値 の形式で記述し、複数のパラメーターを指定する場合は & で繋げます。

?date=1&area=130010

パラメーターの意味は、以下となります。

date : 1: 本日, 2: 明日
area : 天気予報を取得するエリアコード（エリアコードについては、地域コード表を参照してください）。

fetch@ 関数の実行に成功すると、以下のような配列が返されます。

[-1, "2024-02-14", "くもりのち晴れ", 30, 20, 10, 0]

配列の各要素の意味は、以下となります。

-1 : 関数の呼び出しが成功したことを示します。
天気予報の日付 : "2024-02-14"
天気 : 例 "くもりのち晴れ"
降水確率 (00:00-06:00): 30%
降水確率 (06:00-12:00): 20%
降水確率 (12:00-18:00): 10%
降水確率 (18:00-24:00): 0%

データが無い場合は "N/A" がセットされることもあります。例えば、お昼過ぎに天気予報を取得すると「00:00-06:00」のデータは N/A になります。

プログラムで行われていること

fetch@ 命令で指定した URL から天気予報データを取得します。
成功した場合は、天気予報のデータを解析して内容を表示します。
失敗した場合はエラーメッセージを表示します。

学ぶべきこと

Web API を利用してデータを取得する方法。
クエリーパラメーターを使ってデータを指定する方法。
API レスポンスの解析方法。

チャレンジ

別の日付やエリアを指定して天気予報を取得してみましょう。
別のエリアを指定して天気予報を取得してみましょう。
取得したデータを加工して、表示内容をカスタマイズしてみましょう。