Zenn
💨

Python ~API~

に公開
Python
API
tech

0.はじめに

こちらの記事ではプログラミング全体で共通な知識として必要なAPIという技術について学べます。自動化を行っていくにあたってこのAPIという通信技術を学ぶことは非常に重要なポイントになってきます。馴染みのない最初はイメージしずらい部分ではありますが、ここでしっかりと学んで自動化に活かしていきましょう。

1.APIとは

APIとは「アプリケーションプログラミングインターフェース」と呼ばれ、異なるソフトウェア間で情報を交換したり、互いに連携したりするための規則や手順の集まりです。

例えば、明日の天気を設定した時間に自動で通知してくれるアプリを作成するとします。
その場合は気象情報のAPIを使用して、最新の天候データを取得して対象者に通知する機能を実装します。また、Xの投稿を自動化するツールは、XのAPIを使用して投稿を行います。

簡単に言うと、APIは異なるソフトウェアやシステムが互いに「話し合う」ための方法であり、開発者が利用できる機能やデータを簡単にアクセスできるようにするための「言語」のようなものです。

2.Postman

APIは対象のURLにリクエスト内容をくっつけてアクセスすることにより、データを受信することが可能です。受信するデータを確認する方法として、Postmanというアプリがあるので、そちらを使用してAPIの動作確認などを行っていきます。

2.1 インストール

まずはこちらのサイトからアプリをダウンロードしてきてださい。
※OSがMacでCPUがM1の方はAppleChipを選択してください。
ダウンロードして、インストールまで進めてください。
起動して次のような画面になっていれば大丈夫です。

2.2 リクエストしてみる

これでAPIをリクエストするための準備ができたので、実際にAPIを使ってリクエストしてみます。
今回は天気予報APIを使用していきます。
使い方はサイトにもあるリクエストパラメータという部分の例にあるURLをPostmanに入力して実行するだけです。
では、実際にやっていきましょう。
Postmanの画面上部にあるプラスマークをクリックしてください。

するとAPIをリクエストするためのフォームが作成されます。
そこに次のURLをそのままペーストしてください。
https://weather.tsukumijima.net/api/forecast/city/400040
次にようにURLを入力する箇所に値が入っていれば大丈夫です。

入力が完了しましたら、横にあるSendという青いボタンを押して実行しましょう。
画面下の方に福岡県久留米市の天気予報データが取得できれば成功です。

2.3 解説

まず、リクエストの部分を解説していきます。
APIを使用するにはURLが必要になります。
今回ですとhttps://weather.tsukumijima.net/api/forecast/city/400040がURLになります。
また、こちらのAPIの仕様では最後に地域のIDを指定することにより、欲しい地域の天気予報を取得できます。
先ほどのURLだと400040が地域IDになります。
自分が欲しい地域IDはこちらのAPIが提供している地点定義表から参照して指定することが可能です。
例えば東京の場合ですと130010が地域IDになっていたので、
こちらを先ほどのURLの末尾のIDを変えて再度リクエストを送ると、東京の天気予報が返ってきます。

APIの仕様は提供してくれているサービスによって異なりますので、
APIを使用する場合は各サービスの仕様書を参照しながら実行しましょう。

次に取得できたデータについて解説します。
APIで返ってくるデータは基本的にJSON(ジェーソン)と呼ばれる形式で返ってきます。
Pythonの基礎で習った辞書型と同じ形式です。
なので、先ほどの東京の天気を取得できたjsonから取得するには
jsonData["forecasts"][0]["telop"]とすれば、天気予報を取得することが可能です。

3.天気予報APIの実装

天気予報APIのリクエストの仕方やjsonの扱いについてある程度触れたので、
次は実際にPythonのコードに埋め込んで実装していきます。

3.1 完成イメージ

アプリを実行後にターミナルにて知りたい天気の地域IDを聞かれます。
欲しい地域のIDを入力したら、その地域の天気を教えてくれます。

>> 地域IDを入力してください。
130010
今日の東京都 東京 の天気は曇のち時々晴

3.2 天気予報API

weather.pyというファイルを作成します。
ファイルの作成が完了したら、地域IDを入力できるように実装します。
ターミナルでの入力を受け付けるようにするにはinput機能を使用します。

weather.py
id = input(">> 地域IDを入力してください。\n")
print(f"入力したIDは{id}です。")

このようにするとinputで一旦処理が止まり、入力の待機状態を作れます。
試しに実行して10000と入力してみましょう。
結果次にようになれば成功です。

>> 地域IDを入力してください。
10000
入力したIDは10000です。

inputで入力された値がidという変数に格納されたことが確認できましたね。

次はこの値を元にAPIリクエストを実装していきます。
PythonでAPIを行う場合はrequestsライブラリをインポートする必要があるので、
まずはrequestsをimportします。

weather.py
import requests

id = input(">> 地域IDを入力してください。\n")
print(f"入力したIDは{id}です。")

requestsがimportとできたら、天気予報APIのリクエストURLを設定していきます。
こちらのAPIではGETメソッドを使用しているので、
次のように実装してください。

weather.py
import requests

id = input(">> 地域IDを入力してください。\n")
get = requests.get("https://weather.tsukumijima.net/api/forecast/city/" + id)
weather_json = get.json()
print(weather_json)

先ほどのURL+IDで指定の地域の天気を知れることができます。
最後に取得したデータをPythonではjson形式に変換する必要があるので、get.json()と書いています。
これを実行すると次のようになります。

>> 地域IDを入力してください。
130010
{'publicTime': '2024-02-01T23:00:00+09:00', 'publicTimeFormatted': '2024/02/01 23:00:00', 'publishingOffice': '気象庁', 'title': '東京都 東京 の天気', 'link': 'https://www.jma.go.jp/bo.........

と先ほどpostmanで実行した時と同じ結果が返ってきましたね。
※同じjsonではあるが、みずらいためAPIのレスポンス結果はpostmanで確認するのがおすすめ

最後に取得できたjsonを組み合わせて
今日の東京都 東京 の天気は曇のち時々晴
と表示されるようにしていきます。
まずは、日付です。
今日と日にちをdateLabelで取得できます。
東京都 東京 の天気と場所をtitleで取得できます。
曇のち時々晴と天気はtelopで取得できます。
それぞれをjsonの階層に合わせて出力すると次のようになります。

weather.py
import requests

id = input(">> 地域IDを入力してください。\n")
get = requests.get("https://weather.tsukumijima.net/api/forecast/city/" + id)
weather_json = get.json()
print(f"{weather_json['forecasts'][0]['dateLabel']}の{weather_json['title']}は{weather_json['forecasts'][0]['telop']}")

これを実行して東京のIDである130010を入力すると完成イメージと同じ結果が返ってきましたね。

>> 地域IDを入力してください。
130010
今日の東京都 東京 の天気は曇のち時々晴

これで、いつ、どこの地域の天気がわかるようになりましたね。
以上で天気予報APIを使用した実装例は以上になります。

4.VOICEVOX APIの実装

4.1 完成イメージ

みなさんVOICEVOXというテキストを読み上げ読み上げてくれるサービスをご存知でしょうか？
youtubeなどの実況などでずんだもんとういキャラクターが一番有名かと思います。
※ずんだもんの詳細はこちら
一般的にはツールを使用して、音声データを作成されていると思います。
実はVOICEVOXもAPIを提供しています。
つまり、ツールを使用しなくていいので、
音声読み上げる動画を作成する場合に、自動化できるということです。
今回の実装の流れとしては
読み上げたいテキストを入力
↓
VOICEVOXに読み上げて欲しいテキストのリクエスト
↓
レスポンスに含まれる音声ダウンロードURLを取得
↓
GETメソッドでダンロードURLにリクエストして音声データを取得
↓
ファイルに書き出す
これでローカルにmp3ファイルとして取得することができます。
では、早速実装してみましょう。

4.2 VOICEVOX API

実装にあたりvoicevox.pyファイルを新しく作成してください。
天気予報API同様に、読み上げて欲しいテキストを入力しますので、input機能を使用します。

voicevox.py
text = input("何を読んで欲しいですか？\n")
print(f"入力したのは {text}")

と実装しましょう。
これを実行して、適当な文字を入力してください。
次のように入力した値が出力されれば成功です。

何を読んで欲しいですか？
テスト
入力したのは テスト

入力した値が正常に取得できたことが確認できたので
次はこのテキストをVOICEVOXにリクエストします。
VOICEVOX APIの仕様として、読み上げて欲しいデータをURLに含める形式になっているので、そちらに組み込むプログラムを実装します。
URLにkey=value形式で組み込むことをクエリパラメーターと呼ぶのでここは覚えておきましょう。
また、クエリパラメーターには読み上げるテキストだけでなく、どのキャラクターで読み上げるかも指定をしないといけないので、そちらも実装していきます。
ダウンロードURLを取得するまでの実装は次のようになります。

voicevox.py
import requests

text = input("何を読んで欲しいですか？\n")

url = f"https://api.tts.quest/v3/voicevox/synthesis?text={text}&speaker=1"

res = requests.post(url)
res_json = res.json()
print(res_json)

urlの部分に?text={text}&speaker=1とあります。
これが先ほど説明したクエリパラメーターになります。
voicevoxの仕様では

  • textに読み上げて欲しい文字
  • speakerに読み上げて欲しいキャラクターID
    をそれぞれ設定しています。
    URLにリクエストしたい内容はこれで大丈夫なので、
    天気予報APIでも使用したpythonのrequestsライブラリを使用して、voicevoxにリクエストします。
    resで受け取った値をjson形式に変換して音声をダウンロードするURLを取得できるようにします。
    実行結果が次のような値になれば大丈夫です。
    ※レスポンスのURLなどの値は都度変わるので完全一致はしません。
    また、レスポンスで返ってきた詳細な値はvoiceboxの仕様書を参照してください。
{'success': True, 'isApiKeyValid': False, 'speakerName': 'VOICEVOX:ずんだもん（あまあま）', 'audioStatusUrl': 'https://audio1.tts.quest/v1/data/b1a988445dd7b6726e4285f905770d8da53cb32367d0e0ebf7e4cdc7c4473dae/status.json', 'wavDownloadUrl': 'https://audio1.tts.quest/v1/data/b1a988445dd7b6726e4285f905770d8da53cb32367d0e0ebf7e4cdc7c4473dae/audio.wav', 'mp3DownloadUrl': 'https://audio1.tts.quest/v1/data/b1a988445dd7b6726e4285f905770d8da53cb32367d0e0ebf7e4cdc7c4473dae/audio.mp3', 'mp3StreamingUrl': 'https://audio1.tts.quest/v1/data/b1a988445dd7b6726e4285f905770d8da53cb32367d0e0ebf7e4cdc7c4473dae/audio.mp3s'}

ここに含まれるmp3DownloadUrlが作成された音声ダウンロードURLになります。
レスポンスで返ってきたURLにブラウザでアクセスして、音声が再生されれば成功です。

音声が正常に確認できたら、こちらをファイルとしてローカルに保存していきます。
保存するためには音声URLからデータを取得する必要がありますので、
ここでもrequestsを使用します。
今回はGETメソッドを使用していきます。
コードしては次のようになります。

voicebox.py
import requests
import time

text = input("何を読んで欲しいですか？\n")

url = f"https://api.tts.quest/v3/voicevox/synthesis?text={text}&speaker=1"

res = requests.post(url)
res_json = res.json()

time.sleep(10)

mp3_url = res_json["mp3DownloadUrl"]
response = requests.get(mp3_url)

追加されたコードについて解説していきます。
time.sleep(10)では、処理を10秒間停止しています。
理由としてはvoicebox apiでは無料版であるがゆえに、音声データ作成までに多少の時間がかかります。ここで停止処理を入れずに後続の処理を行うと作成できてない音声データからファイルを作成しようとするためクラッシュしてエラーになってしまいます。

mp3_url = res_json["mp3DownloadUrl"]
response = requests.get(mp3_url)

ここでは最初にリクエストしたレスポンスに含まれるURLをmp3_urlに格納して、
requests.getで音声データをリクエストしています。
res_json["mp3DownloadUrl"]で値が取れるのは辞書型と呼ばれる形式の書き方でしたね。

これで音声データの取得はできたので、最後にファイルに書き出す処理を実装していきます。
最終的な実装するコードは次にようになります。

voicebox.py
import requests
import time

text = input("何を読んで欲しいですか？\n")

url = f"https://api.tts.quest/v3/voicevox/synthesis?text={text}&speaker=1"

res = requests.post(url)
res_json = res.json()
print(res_json)

time.sleep(10)

mp3_url = res_json["mp3DownloadUrl"]
response = requests.get(mp3_url)
with open("./test.mp3", 'wb') as file:
    file.write(response.content)
print("ダウンロード完了")

pythonにてファイルを処理をする場合はwith open()を使用します。
openの

  • 第一引数にファイル名
  • 第二引数に読み込みor書き込みかのモードを選択します。
    ファイル名はtest.mp3と固定にします。
    今回はただの文字を入力するのではなく、音声データなのでバイナリーを書き込みます。
    バイナリーデータを書き込むので、今回はwbと指定する必要があります。
    ファイルの書き込み設定が完了したら、file.write()で実際に音声バイナリーデータを書き込みして完了になります。
    最後に処理が完了したことを通知するために、ログ出力を行っています。

これを実際に動かして、voicevox.pyと同じディレクトリにtest.mp3が生成されていれば成功です。

5.最後に

APIについてなんとなくはご理解いただけましたでしょうか？
正直実例を2つ実装したぐらいではまだまだ未知な部分が多いと思います。
自動化に限らず、プログラミングは何度も実装して、エラーにぶち当たって、解決して...
の繰り返しです。
ChatGPT APIやLIEN APIなど、大勢の人が扱うアプリのAPIを多く存在しており、それらの実装はまた今までは違った形の実装が必要だったりします。
これを基本として自分で色々チャレンジしてみてください！
その中でわからないことがなんでも聞いてください！
プログラミング、ひいては自動化アプリを作れるようになるための近い道は
トライアンドエラーあるのみです！！

Discussion