OJT ~ APIを使ってみよう ~

# はじめに
APIを使ってみましょう！

# APIとは（Claude 3.5 Sonnet v2に聞きました）

API（エー・ピー・アイ）とは、「Application Programming Interface」の略で、ソフトウェアやシステムが互いに情報をやり取りするための「インターフェース」や「窓口」のことを指します。簡単に言えば、異なるソフトウェア同士をつなぐ橋のような役割をします。

今回、取り扱うのはWeb APIになります。

Web API（ウェブAPI）とは、インターネット上で動作するAPIのことで、ウェブのプロトコル（通常はHTTP/HTTPS）を介してデータや機能を提供・利用できる仕組みです。Web上で異なるアプリケーション間で情報をやり取りし連携を取る際に使用されるものを指します。

**Web APIの特徴**
- インターネットを介して利用可能
Web APIはインターネットを通じてサーバー（提供側）とクライアント（利用側）がデータをやり取りします。例えば、ウェブブラウザやスマートフォンアプリがWeb APIを介してデータにアクセスします。

- 標準的なプロトコルを使用
HTTPやHTTPSなど、インターネットで広く使われている通信プロトコルを利用します。そのため、世界中のほとんどのシステムが容易にアクセスできます。

- JSONやXMLでのデータ形式
データのやり取りには、JSON（JavaScript Object Notation）やXMLといったフォーマットがよく使用されます。これにより、人間にも理解しやすく、マシンでも処理しやすい形でデータを送受信できます。


![画像 (22).png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/63863/bdfad1cd-7435-1c4e-9666-e0d20fec8646.png)

# [旅旅 API](https://tabi2api.docs.apiary.io/)

> 「旅旅 API」は、日本の地理的および文化的特性を探求し、活用するためのデータアクセスを提供するAPIサービスです。このAPIは、地域の文化財、自然景観、歴史的名所など、日本国内の豊かな資源に関する詳細情報を提供し、地域振興や教育、観光業界のサポートを目的としています。利用者は、具体的なデータセットに簡単にアクセスでき、地域ごとの特色や魅力を深く理解することが可能です。

## 湧き水APIを利用してみましょう

1．APIを利用する際に **認証** が必要です。[ここ](https://livlog.xyz/sso/login)からトークンを取得してください

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/63863/6a9b1b4d-ba11-4489-2bc5-0569292c66ee.png)

2．左のメニューからAPIを選択、トークンを生成し、コピーしておいてください
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/63863/ebcc6024-0bb0-56cb-1777-0e708ec575ac.png)

3．湧き水APIの仕様書はこちらです

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/63863/08167e4b-7ebb-bfca-373d-297e04cead89.png)

[リクエスト]
- メソッド：GET（データを取得する）
- エンドポイント：https://app.livlog.xyz/webapi/v2/spring-water/list
クエリパラメータ：pref（地名、例：愛知県）

[レスポンス]
・JSON形式

~~~json
{
  "metadata": {
    "title": "Success",
    "detail": "OK",
    "status": 200
  },
  "_links": {
    "self": {
      "href": "/v2/spring-water/list"
    }
  },
  "results": [
    {
      "createDate": "2024-02-25T10:05:00.000+00:00",
      "createCd": "admin",
      "updateDate": "2024-02-25T10:05:00.000+00:00",
      "updateCd": "admin",
      "id": 1828,
      "name": "金明水",
      "furigana": "きんめいすい",
      "oldAddress": "愛知県名古屋市千種区天白町 金明水",
      "overview": "東山動植物園の東南の斜面から湧出しており、近傍には小さな祠が作られています。",
      "access": "◎",
      "activity": "市民モニターによる実態調査",
      "address": "愛知県名古屋市名東区藤巻町１丁目",
      "latitude": 35.1507491,
      "longitude": 136.9848604,
      "link": "https://www.env.go.jp/water/yusui/result/sub4-2/map/23100-1.jpg"
    },
    ...
  ]
}

~~~

### JSON形式とは
JSON形式は、以下のルールに基づいて記述されます：

- データはキーと値のペアで構成される
- データを格納する単位として、オブジェクト（object） と 配列（array） を使用する
- キー は文字列（ダブルクォーテーション " "）で書く
- 値 は以下のいずれか：
    - 文字列（"文字列"）
    - 数値（例: 123, 3.14）
    - 真偽値（true, false）
    - 配列（複数の値をリスト形式で持つデータ）
    - オブジェクト（キーと値のペアを格納するデータ構造）
    - null（空の値）

## PythonプログラムからAPIを実行してみましょう

1．Anacondaをインストールします

https://www.anaconda.com/download

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/63863/6e76c90e-2b6d-057b-70ee-792c4ee4bcf9.png)

2．Skip registrationを選択して、Downloadします

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/63863/e03fc562-228f-0b98-12bd-ad521a5bd765.png)

3．Anaconda3-2024.10-1-Windows-x86_64.exe を実行してインストールします

4．スタートメニューからAnaconda Promptを検索し、開きます
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/63863/e9a49860-0a0b-0f89-e5e8-a41f63582e01.png)

5．作業用のフォルダ（例：s-fujimoto-ojt）を作成し、Cursorで開きます

$ cd s-fujimoto-ojt
$ cursor .

6．Python 3.11の仮想環境を作成します（初回のみ）

$ conda create -n py311 python=3.11

7．py311環境をアクティベートします

$ conda activate py311

8．HTTPリクエストを行うためのライブラリをインストールします

$ pip install requests

9．Pythonプログラムを書きます

~~~test.py
import requests

headers = {
    "Accept": "application/json",
    "Authorization": "Bearer <INSERT-YOUR-TOKEN>",
}

response = requests.get(
    "https://app.livlog.xyz/webapi/v2/spring-water/list?pref=愛知県", headers=headers
)
print(response.text)
~~~

※INSERT-YOUR-TOKENのところを取得したAPIトークンに変更してください

10．プログラムを実行します

$ python test.py

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/63863/578bb86f-2690-3e8d-ba35-d8d1192a5cde.png)

JSON形式で愛知県の湧き水データを取得できていることが確認できました！

11．ソースコードに直接環境変数を書くと、セキュリティ的にまずいので、dotenvを使って、環境変数をファイルから読み込むようにします。

12．python-dotenvライブラリをインストールします。

$ pip install python-dotenv 

13．test.pyを編集します

~~~test.py
import os
from dotenv import load_dotenv
import requests

# .envファイルから環境変数を読み込む
load_dotenv()

headers = {
    "Accept": "application/json",
    "Authorization": f"Bearer {os.getenv('API_TOKEN')}",
}

response = requests.get(
    "https://app.livlog.xyz/webapi/v2/spring-water/list?pref=愛知県", headers=headers
)
print(response.text)
~~~

14．.envファイルを作成し、APIトークンをコピペします
~~~.env
API_TOKEN=<INSERT-YOUR-API-KEY>
~~~

15．プログラムを実行して、同じ結果が得られることを確認してください

16．JSONファイルを保存したいので、チャットボットに聞いて編集してください

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/63863/c7747533-8034-2408-3b05-071b047bcd2f.png)

17．インデント付きで保存してみました

~~~test.py
import os
from dotenv import load_dotenv
import requests
import json

# .envファイルから環境変数を読み込む
load_dotenv()

headers = {
    "Accept": "application/json",
    "Authorization": f"Bearer {os.getenv('API_TOKEN')}",
}

response = requests.get(
    "https://app.livlog.xyz/webapi/v2/spring-water/list?pref=愛知県", headers=headers
)

# レスポンスをJSONとして整形して保存
with open("spring_water_data.json", "w", encoding="utf-8") as f:
    json_data = response.json()  # レスポンスをJSONとしてパース
    json.dump(json_data, f, ensure_ascii=False, indent=2)  # インデント付きで保存

print("データがspring_water_data.jsonに保存されました")

~~~

18．実行結果のJOSNファイルを見てください
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/63863/aa13869f-205f-d883-0e12-61fb338e9d48.png)


19．「resultsの中のname一覧だけ表示したい」とチャットボットに聞いてみました

~~~test.py
import os
from dotenv import load_dotenv
import requests
import json

# .envファイルから環境変数を読み込む
load_dotenv()

headers = {
    "Accept": "application/json",
    "Authorization": f"Bearer {os.getenv('API_TOKEN')}",
}

response = requests.get(
    "https://app.livlog.xyz/webapi/v2/spring-water/list?pref=愛知県", headers=headers
)

# レスポンスをJSONとしてパース
json_data = response.json()

# resultsの中のname一覧を表示
for spring in json_data["results"]:
    print(spring["name"])

# ファイルへの保存（必要な場合）
with open("spring_water_data.json", "w", encoding="utf-8") as f:
    json.dump(json_data, f, ensure_ascii=False, indent=2)

print("データがspring_water_data.jsonに保存されました")
~~~

20．実行してみましょう
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/63863/c7794226-bb12-38ea-3e2b-c33e01257b89.png)


コードの動作を分解すると：
- json_data["results"] → resultsキーの値（配列）を取得
- for spring in ... → 配列の各オブジェクトを1つずつspring変数に格納
- spring["name"] → spring変数のnameキーの値を取得して表示

このように、JSONデータは入れ子構造になっており、Pythonでは辞書型（dict）とリスト型（list）の組み合わせとして扱うことができます。

これでAPIを使えるようになりましたね！あとPythonやJSON形式のデータ処理も覚えていきましょう！

お疲れ様でした。