Web API
Web API とは、Web 上で提供される Application Programming Interface (API) です。API とは、あるプログラムの機能を、別のプログラムから利用可能にした仕組みのことです。現在の Web 上には、たくさんの Web API が提供されており、手軽にそれらの機能を使うことができるようになっています。
Jasmine Tea では、下記のような擬似的な Web API を提供しており、Web API を利用したプログラムを書く疑似体験ができるようになっています。
天気予報 API
Jasmine Tea では天気予報の API を提供しています。この API にアクセスするためには、fetch@ 関数に下記のような URL を渡します。ちなみにこの例では、今日の東京地方の天気予報を取得しています。
url$ = "https://jasminetea.app/webapi/weather?date=1&area=130010"
result@ = fetch@(url$)まずはこの URL を詳しく見てみましょう。クエスチョンマークの前までのこの部分は、この Web API 本体の URL です。Web API では、インターネット上にあるエンドポイントの URL に HTTP を使ってアクセスします。
https://jasminetea.app/webapi/weatherクエスチョンマーク以降の部分はクエリーパラメーターと呼び、この API に渡すパラメーターを指定できます。
?date=1&area=130010始めのクエスチョンマークがクエリーパラメーターの開始を表すもので、"パラメーターの名前=値" という形でパラメーターを指定します。"&" を使えば複数のパラメーターが指定できる仕組みになっています。この例では date パラメータとして "1" を area パラメーターとして "130010" を渡しています。Jasmine Tea で提供している天気予報 API では、これらのパラメータは下記のように指定します。
- date: 1: 本日, 2: 明日
- area: 天気予報を取得するエリアコード
エリアコードの指定方法については、このドキュメント末尾の地域コード表を参照してください。
この fetch@ 関数の実行に成功すると、下記のような配列が返ってきます。
[-1, "2024-02-14", "くもりのち晴れ", 30, 20, 10, 0]配列の要素の意味を順番に説明します。
- 関数の呼び出しに成功したことを示す -1
- 天気予報の日付
- 天気予報
- 00:00 から 06:00 までの降水確率
- 06:00 から 12:00 までの降水確率
- 12:00 から 18:00 までの降水確率
- 18:00 から 24:00 までの降水確率
いずれの要素についても、データが無い場合は、"N/A" という文字列がセットされます。例えばお昼過ぎに天気予報を取得した場合、「00:00 から 06:00 までの降水確率」には "N/A" がセットされます。これは、既に過去のことなので、降水確率を提供する意味が無いからです。
これらの結果を画面に表示するには、下記のようにします。
print "東京地方の天気予報"
print "日付: " + result@[1][0]
print result@[1][1]
print "00:00-06:00の降水確率: " + result@[1][2]
print "06:00-12:00の降水確率: " + result@[1][3]
print "12:00-18:00の降水確率: " + result@[1][4]
print "18:00-24:00の降水確率: " + result@[1][5]また、何らかの原因で API の呼び出しに失敗した場合は、代わりに下記のような配列が返ってきます。
[0, エラーの内容]下記のようなコードで、エラー時にはエラーの内容を表示して終了することができます。
if not result@[0] then
print "Fetch に失敗しました"
print result@[1]
end
end if天気予報API 地域コード表
| 地域１ Area 1 |
地域２ Area 2 |
地域コード Area Code |
|---|---|---|
| 宗谷地方 Soya |
宗谷地方 Soya Region |
011000 |
| 上川・留萌地方 Kamikawa Rumoi |
上川地方 Kamikawa Region |
012010 |
| 留萌地方 Rumoi Region |
012020 | |
| 網走・北見・紋別地方 Abashiri Kitami Mombetsu |
網走地方 Abashiri Region |
013010 |
| 北見地方 Kitami Region |
013020 | |
| 紋別地方 Mombetsu Region |
013030 | |
| 十勝地方 Tokachi |
十勝地方 Tokachi Region |
014030 |
| 釧路・根室地方 Kushiro Nemuro |
根室地方 Nemuro Region |
014010 |
| 釧路地方 Kushiro Region |
014020 | |
| 胆振・日高地方 Iburi Hidaka |
胆振地方 Iburi Region |
015010 |
| 日高地方 Hidaka Region |
015020 | |
| 石狩・空知・後志地方 Ishikari Sorachi Shiribeshi |
石狩地方 Ishikari Region |
016010 |
| 空知地方 Sorachi Region |
016020 | |
| 後志地方 Shiribeshi Region |
016030 | |
| 渡島・檜山地方 Oshima Hiyama |
渡島地方 Oshima Region |
017010 |
| 檜山地方 Hiyama Region |
017020 | |
| 青森県 Aomori |
津軽 Tsugaru |
020010 |
| 下北 Shimokita |
020020 | |
| 三八上北 Sanpachi Kamikita |
020030 | |
| 岩手県 Iwate |
内陸 Inland |
030010 |
| 沿岸北部 Northern Coast |
030020 | |
| 沿岸南部 Southern Coast |
030030 | |
| 宮城県 Miyagi |
東部 Eastern Region |
040010 |
| 西部 Western Region |
040020 | |
| 秋田県 Akita |
沿岸 Coast |
050010 |
| 内陸 Inland |
050020 | |
| 山形県 Yamagata |
村山 Murayama |
060010 |
| 置賜 Okitama |
060020 | |
| 庄内 Shonai |
060030 | |
| 最上 Mogami |
060040 | |
| 福島県 Fukushima |
中通り Nakadori |
070010 |
| 浜通り Hamadori |
070020 | |
| 会津 Aizu |
070030 | |
| 群馬県 Gunma |
南部 Southern Region |
100010 |
| 北部 Northern Region |
100020 | |
| 埼玉県 Saitama |
南部 Southern Region |
110010 |
| 北部 Northern Region |
110020 | |
| 秩父地方 Chichibu Region |
110030 | |
| 千葉県 Chiba |
北西部 North-western Region |
120010 |
| 北東部 North-eastern Region |
120020 | |
| 南部 Southern Region |
120030 | |
| 東京都 Tokyo |
東京地方 Tokyo Region |
130010 |
| 伊豆諸島北部 Northern Izu Islands |
130020 | |
| 伊豆諸島南部 Southern Izu Islands |
130030 | |
| 小笠原諸島 Ogasawara Islands |
130040 | |
| 神奈川県 Kanagawa |
東部 Eastern Region |
140010 |
| 西部 Western Region |
140020 | |
| 山梨県 Yamanashi |
中・西部 Central Western Region |
190010 |
| 東部・富士五湖 Eastern Region and Fuji Five Lakes |
190020 | |
| 長野県 Nagano |
北部 Northern Region |
200010 |
| 中部 Central Region |
200020 | |
| 南部 Southern Region |
200030 | |
| 茨城県 Ibaraki |
北部 Northern Region |
080010 |
| 南部 Southern Region |
080020 | |
| 栃木県 Tochigi |
南部 Southern Region |
090010 |
| 北部 Northern Region |
090020 | |
| 岐阜県 Gifu |
美濃地方 Mino Region |
210010 |
| 飛騨地方 Hida Region |
210020 | |
| 静岡県 Shizuoka |
中部 Central Region |
220010 |
| 伊豆 Izu |
220020 | |
| 東部 Eastern Region |
220030 | |
| 西部 Western Region |
220040 | |
| 愛知県 Aichi |
西部 Western Region |
230010 |
| 東部 Eastern Region |
230020 | |
| 三重県 Mie |
北中部 Northern Central Region |
240010 |
| 南部 Southern Region |
240020 | |
| 新潟県 Niigata |
下越 Kaetsu |
150010 |
| 中越 Chuetsu |
150020 | |
| 上越 Joetsu |
150030 | |
| 佐渡 Sado |
150040 | |
| 富山県 Toyama |
東部 Eastern Region |
160010 |
| 西部 Western Region |
160020 | |
| 石川県 Ishikawa |
加賀 Kaga |
170010 |
| 能登 Noto |
170020 | |
| 福井県 Fukui |
嶺北 Reihoku |
180010 |
| 嶺南 Reinan |
180020 | |
| 滋賀県 Shiga |
南部 Southern Region |
250010 |
| 北部 Northern Region |
250020 | |
| 京都府 Kyoto |
南部 Southern Region |
260010 |
| 北部 Northern Region |
260020 | |
| 大阪府 Osaka |
大阪府 Osaka Prefecture |
270000 |
| 兵庫県 Hyogo |
南部 Southern Region |
280010 |
| 北部 Northern Region |
280020 | |
| 奈良県 Nara |
北部 Northern Region |
290010 |
| 南部 Southern Region |
290020 | |
| 和歌山県 Wakayama |
北部 Northern Region |
300010 |
| 南部 Southern Region |
300020 | |
| 鳥取県 Tottori |
東部 Eastern Region |
310010 |
| 中・西部 Central Western Region |
310020 | |
| 島根県 Shimane |
東部 Eastern Region |
320010 |
| 西部 Western Region |
320020 | |
| 隠岐 Oki |
320030 | |
| 岡山県 Okayama |
南部 Southern Region |
330010 |
| 北部 Northern Region |
330020 | |
| 広島県 Hiroshima |
南部 Southern Region |
340010 |
| 北部 Northern Region |
340020 | |
| 徳島県 Tokushima |
北部 Northern Region |
360010 |
| 南部 Southern Region |
360020 | |
| 香川県 Kagawa |
香川県 Kagawa Prefecture |
370000 |
| 愛媛県 Ehime |
中予 Chuyo |
380010 |
| 東予 Toyo |
380020 | |
| 南予 Nan-yo |
380030 | |
| 高知県 Kochi |
中部 Central Region |
390010 |
| 東部 Eastern Region |
390020 | |
| 西部 Western Region |
390030 | |
| 山口県 Yamaguchi |
西部 Western Region |
350010 |
| 中部 Central Region |
350020 | |
| 東部 Eastern Region |
350030 | |
| 北部 Northern Region |
350040 | |
| 福岡県 Fukuoka |
福岡地方 Fukuoka Region |
400010 |
| 北九州地方 Kitakyushu Region |
400020 | |
| 筑豊地方 Chikuho Region |
400030 | |
| 筑後地方 Chikugo Region |
400040 | |
| 佐賀県 Saga |
南部 Southern Region |
410010 |
| 北部 Northern Region |
410020 | |
| 長崎県 Nagasaki |
南部 Southern Region |
420010 |
| 北部 Northern Region |
420020 | |
| 壱岐・対馬 Iki Tsushima |
420030 | |
| 五島 Goto |
420040 | |
| 熊本県 Kumamoto |
熊本地方 Kumamoto Region |
430010 |
| 阿蘇地方 Aso Region |
430020 | |
| 天草・芦北地方 Amakusa Ashikita Region |
430030 | |
| 球磨地方 Kuma Region |
430040 | |
| 大分県 Oita |
中部 Central Region |
440010 |
| 北部 Northern Region |
440020 | |
| 西部 Western Region |
440030 | |
| 南部 Southern Region |
440040 | |
| 宮崎県 Miyazaki |
南部平野部 Plain Area of Southern Region |
450010 |
| 北部平野部 Plain Area of Northern Region |
450020 | |
| 南部山沿い Area along mountains of Southern Region |
450030 | |
| 北部山沿い Area along mountains of Northern Region |
450040 | |
| 奄美地方 Amami |
奄美地方 Amami Region |
460040 |
| 鹿児島県（奄美地方除く） Kagoshima (Excluding Amami) |
薩摩地方 Satsuma Region |
460010 |
| 大隅地方 Osumi Region |
460020 | |
| 種子島・屋久島地方 Tanegashima Yakushima Region |
460030 | |
| 沖縄本島地方 Okinawa Main Island |
本島中南部 Central and Southern Main Island |
471010 |
| 本島北部 Northern Main Island |
471020 | |
| 久米島 Kumejima |
471030 | |
| 大東島地方 Daitojima |
大東島地方 Daitojima Region |
472000 |
| 宮古島地方 Miyakojima |
宮古島地方 Miyakojima Region |
473000 |
| 八重山地方 Yaeyama |
石垣島地方 Ishigakijima Region |
474010 |
| 与那国島地方 Yonagunijima Region |
474020 |