はじめに
「curlでAPIを呼べた。次は、取得したデータをPythonで使ってみたい」
そんなときに使えるのが、HTTP通信ライブラリの Requests です。PythonのコードからAPIへリクエストを送り、返ってきたデータを取り出せます。インストール名・コード中の名前はrequestsです。
この記事では、用語の確認から、GET・POST、JSONの取り出し、エラー対応、APIキーをコードへ直接書かない方法までを説明します。
先に結論
- データを取得する基本は
requests.get()、JSONを送る基本はrequests.post(..., json=...)です。 -
params=はURLのクエリ、json=はリクエスト本文として使い分けます。 - HTTPの状態確認と、JSONの読み取りは別の処理 です。
-
timeoutを指定します。ただし、処理全体を必ず指定秒数以内に終わらせる設定ではありません。 - APIキーは送信先の公式仕様を確認して扱い、練習用APIへ本物のキーを送らないようにします。
前提と確認環境
- Pythonのファイルを保存し、ターミナルから実行するところから扱います。仮想環境の詳しい説明はvenv入門を参照してください。
- 確認日: 2026年10月1日 。検証対象はPython 3.14.6/Requests 2.34.2です。このRequests版はPython 3.10以上が必要です(PyPI)。
- macOSでGET・POSTとエラー処理など11項目を実行確認しました。Windowsの環境準備・環境変数コマンドは公式資料と照合したもので、この記事ではWindows上の実行確認はしていません。
- 通信先にはhttpbinというHTTPリクエストの確認用サービスを使います。アカウント作成やAPIキーは不要ですが、インターネット接続が必要です。
- 本番向けの認証連携、非同期処理、大量データ、再試行の実装は扱いません。
httpbinは第三者が提供する外部サービスです。この記事では公開してよいダミーデータだけを送ります。個人情報、社内情報、本物のAPIキーを送らないでください。サービス側の混雑・制限・停止で動かない場合もあります。連続実行せず、利用先のルールを確認してください。
1. API・HTTP・JSONとは?
ここで扱うAPIは、 プログラムからサービスの機能やデータを利用するための窓口 です。HTTPは、その窓口へ「何をしてほしいか」を送り、結果を受け取るための通信の仕組みです。APIすべてがHTTPを使うわけではありませんが、この記事ではHTTP APIを扱います。
| 用語 | この記事での意味 |
|---|---|
| リクエスト | APIへ送る依頼。URL、方法、必要なデータなどを含む |
| レスポンス | APIからの返事。処理結果を示す状態や、データなどを含む |
| GET | 指定したリソースの情報を取得するためのHTTPメソッド |
| POST | データを送り、送信先に処理を依頼するHTTPメソッド |
| ヘッダー | データ形式や認証情報などを伝える付加情報 |
| JSON | 名前と値の組や配列などでデータを表すテキスト形式 |
GET・POSTの意味はHTTP Semantics(RFC 9110)、JSONの形式はJSON仕様(RFC 8259)を参照しています。表と以下の図は、学習用に筆者が整理したものです。
POSTを「必ず新規登録する命令」と覚える必要はありません。検索や計算など、APIによって用途が異なります。
curlはターミナルから通信を試すときに便利です。Requestsでは、同じような通信を Pythonプログラムの一部 にできるため、取得したデータの集計や次の処理につなげやすくなります。
2. 仮想環境を作り、requestsを入れる
新しいrequests-demoフォルダで試します。同名フォルダが既にある場合は、別名にしてください。
Mac:zsh/bash
mkdir requests-demo
cd requests-demo
python3 -m venv .venv
source .venv/bin/activate
Windows:PowerShell
mkdir requests-demo
cd requests-demo
py -m venv .venv
.\.venv\Scripts\Activate.ps1
コマンドプロンプトの場合、有効化は.venv\Scripts\activate.batです。pyがない環境や、有効化が実行ポリシーで拒否される場合は、前述のvenv記事で確認してください。会社のPCでは管理者のルールを優先します。
有効化後は、どちらのOSでも次を実行します。
python -m pip install requests
python -c "import sys, requests; print(sys.executable); print(requests.__version__)"
python -m pip check
sys.executableが作成した.venv内を指すことを確認します。記事と同じ版で検証したい場合は、インストールコマンドをpython -m pip install requests==2.34.2に置き換えます。最新の修正を取り込むかどうかは、利用環境の方針に合わせて判断してください。
出典:Python公式:venv、Requests公式:Installation。
3. GETでデータを取得する
エディターでget_demo.pyを作り、次のコードを保存します。 .venvの中ではなく、requests-demoの直下 に置いてください。ファイル名をrequests.pyにすると、ライブラリ名と衝突するので避けます。
import requests
# paramsの内容は、URLのクエリとして送られる
response = requests.get(
"https://httpbin.org/get",
params={"topic": "Python", "page": 1},
timeout=(3.05, 10),
)
response.raise_for_status()
data = response.json()
print("status:", response.status_code)
print("topic:", data["args"]["topic"])
print("page:", data["args"]["page"])
保存したフォルダで実行します。
python get_demo.py
成功時に期待する出力は次のとおりです。
status: 200
topic: Python
page: 1
httpbinの/getは、受け取ったクエリをレスポンスのargsへ入れて返します。data["args"]["topic"]は、辞書からargsを取り出し、その中のtopicを取り出す書き方です。
params=を使うと、文字のURLエンコードなどをRequestsに任せられます。クエリはURLの一部なので、履歴やログに残り得ます。APIキーなどの秘密情報を入れる場所として安易に使わないでください。
この例ではPythonの整数1を指定していますが、httpbinがargsに返す値は文字列です。 元のPythonの型が、そのままAPIの返却値の型になるわけではありません。
出典:Requests公式:Passing Parameters In URLs、httpbin。
4. JSONを読むことと、成功を確認することは別
前のコードで使った3つの操作を分けて考えます。
| 操作 | 役割 |
|---|---|
response.status_code |
HTTPステータスコードを確認する |
response.raise_for_status() |
4xx・5xxの場合にHTTPErrorを発生させる |
response.json() |
レスポンス本文のJSONをPythonの値へ変換する |
この表はRequests公式:JSON Response ContentとResponse Status Codesの説明をもとに整理しています。
response.json()は「必ず辞書を返す機能」ではありません。JSONのオブジェクトはdict、配列はlist、nullはNoneなどへ変換されます。返却構造に合わないキーを使えば、別のエラーになります(Python公式:JSON変換表)。
エラーの詳細がJSONで返ってくるAPIもあります。そのため、JSONを読めてもAPI処理が成功したとは限りません。逆に、204など本文が空の応答や、HTMLが返ってきた応答ではresponse.json()が失敗することがあります。
また、raise_for_status()が例外を出さなかったことだけでは、期待したデータ構造や業務処理の成功まで保証できません。必要なステータスや項目は、APIの仕様に合わせて確認します。
5. POSTでJSONを送る
次はpost_demo.pyを作ります。
import requests
payload = {"title": "requestsの練習", "completed": False}
response = requests.post(
"https://httpbin.org/post",
json=payload,
timeout=(3.05, 10),
)
response.raise_for_status()
data = response.json()
print("status:", response.status_code)
print("title:", data["json"]["title"])
print("completed:", data["json"]["completed"])
python post_demo.py
status: 200
title: requestsの練習
completed: False
json=payloadは、Pythonの辞書をJSONに変換して本文へ入れ、Content-Type: application/jsonも設定します。この例のFalseは通信時にJSONのfalseとなり、JSONを読み戻すとPythonのFalseになります。
httpbinの/postは送った内容を確認するためのAPIです。 業務システムにタスクを登録するコードではありません。 また、送った内容が第三者に渡る点は変わりません。
params・data・jsonの違い
Requests公式:More complicated POST requestsをもとに、初心者が混同しやすい引数を整理すると次のようになります。
| 指定 | 主な用途 |
|---|---|
params={...} |
URLのクエリへ入れる。GET専用ではない |
data={...} |
辞書を渡した場合は、通常フォーム形式の本文として送る |
json={...} |
JSON形式の本文として送る |
APIがJSONを要求しているなら、まずjson=を検討します。data=は文字列やバイト列なども受け取るため、常にフォーム形式になるわけではありません。また、json=とdata=・files=を不用意に混在させないようにします。
6. タイムアウトとエラーに備える
最初のGET・POST例は、失敗時に例外の内容を表示して停止する短い学習用コードです。次は、失敗の種類を分けてメッセージを出す例です。
import sys
import requests
# URLを省略したときは通常のGETを試す
url = sys.argv[1] if len(sys.argv) > 1 else "https://httpbin.org/get"
try:
response = requests.get(url, timeout=(3.05, 10))
response.raise_for_status()
data = response.json()
except requests.exceptions.JSONDecodeError:
print("本文をJSONとして読み取れませんでした。")
sys.exit(1)
except requests.exceptions.Timeout:
print("接続または読み取りがタイムアウトしました。")
sys.exit(1)
except requests.exceptions.HTTPError as error:
print("HTTPエラー:", error.response.status_code)
sys.exit(1)
except requests.exceptions.ConnectionError:
print("接続に失敗しました。ネットワーク・URL・証明書などを確認してください。")
sys.exit(1)
except requests.exceptions.RequestException:
print("リクエストの処理に失敗しました。")
sys.exit(1)
else:
print("成功:", response.status_code)
print("JSONのPython型:", type(data).__name__)
python get_safe.py
python get_safe.py https://httpbin.org/status/404
2行目は、意図的に404を返す練習です。想定どおりならHTTPエラー: 404と表示し、終了コード1で終わります。1行目は成功時に成功: 200とJSONのPython型: dictを表示します。
例外の親クラスであるRequestExceptionは最後に置いています。先にまとめて捕まえると、その下の種類別の処理へ進まなくなるためです。エラーメッセージでは、認証ヘッダーやレスポンス全文を不用意にログへ出さないようにしています。
timeout=(3.05, 10)の意味
-
3.05:接続時のタイムアウト秒数。 -
10:読み取り時に、データが届くのを待つタイムアウト秒数。
合計13.05秒以内に処理が必ず終わる、という意味ではありません。 接続先アドレスへの試行や、データの届き方などで全体の所要時間は変わります。単一の数値timeout=10を指定すると、接続・読み取りの両方へその値が適用されます。Requestsは、明示しなければタイムアウトを設定しません。
出典:Requests公式:Timeouts、Errors and Exceptions。
POSTがタイムアウトしたときは、サーバー側では処理が完了している可能性もあります。登録や決済などを、そのまま何度も再送しないでください。本番ではAPIの再試行ルールや重複防止の仕組みを確認します。
7. APIキーをコードへ直接書かない
実際のAPIでは、発行されたキーやアクセストークンが必要なことがあります。ヘッダー名や認証方式はAPIごとに異なり、APIキーとBearerトークンも同じものとは限りません。
ここでは、環境変数という プログラムの外から設定値を渡す仕組み を使い、キーを読み取る部分だけ練習します。
ダミー値を、現在のターミナルに設定する
次の値は練習用のダミーです。本物のキーをコマンドへ直接書くと、シェルの履歴などに残る可能性があります。本番では、組織で決めたシークレット管理や安全な入力方法を使ってください。
export EXAMPLE_API_KEY="dummy-for-local-practice"
$env:EXAMPLE_API_KEY = "dummy-for-local-practice"
set "EXAMPLE_API_KEY=dummy-for-local-practice"
ヘッダーを準備するだけの例
次をauth_prepare.pyとして保存します。api.example.comは説明用の置き換え先であり、動作するAPIではありません。 このコードは外部へ送信しません。
import os
import requests
api_key = os.getenv("EXAMPLE_API_KEY")
if not api_key:
raise SystemExit("環境変数EXAMPLE_API_KEYを設定してください。")
# X-API-Keyは一例。実際には提供元の公式仕様で指定された名前を使う
prepared = requests.Request(
"GET",
"https://api.example.com/v1/profile",
headers={"X-API-Key": api_key},
).prepare()
# 値やヘッダー全体は表示しない
print("APIキーのヘッダーを準備しました(未送信)。")
python auth_prepare.py
環境変数は、ソースコードと値を分ける方法であり、暗号化された保管庫ではありません。また、.envというファイルを置くだけで、このコードが自動で読み込むわけではありません。
実際に送信するときは、HTTPSの送信先、認証方式、権限、リダイレクトの扱いを確認してください。特に、独自の認証ヘッダーが別の送信先へ引き継がれないかに注意が必要です。この記事では、認証付き通信の実行までは行いません。
出典:Python公式:os.getenv、Requests公式:Prepared Requests、Microsoft:PowerShellの環境変数、Microsoft:set。
8. よくあるつまずき
本文の操作とRequests公式ドキュメントをもとに、筆者が確認順をまとめました。
| 症状 | 最初に確認すること |
|---|---|
No module named 'requests' |
実行するPythonと、python -m pipのインストール先が同じか |
requestsにgetがないと言われる |
自作ファイルをrequests.pyという名前にしていないか |
| 401・403 | キーの有効性、認証方式、権限、対象URLを提供元の仕様で確認する |
| 404 | URLやパスが正しいか。練習用の/status/404なら意図した結果 |
| 429 | 利用制限を確認し、連続実行を止める。再実行までの待ち方はAPIの仕様に従う |
| 5xx | サービスの稼働状況などを確認する。POSTは結果不明のまま連打しない |
| JSON変換エラー | 本文がHTMLや空ではないか。想定したAPIへ接続しているか |
SSLError |
証明書・信頼するCA・プロキシ設定・PCの時刻などを確認する |
HTTPSの証明書検証は既定で有効です。証明書エラーを消すためだけにverify=Falseへ変更すると、通信相手を正しく確認できなくなります。組織で必要なCA証明書がある場合は、管理者の手順に従って設定してください(Requests公式:SSL Cert Verification)。
9. 練習を終えるとき
設定したダミーの環境変数を外す場合は、設定したのと同じターミナルで次を使います。
unset EXAMPLE_API_KEY
Remove-Item Env:EXAMPLE_API_KEY
set "EXAMPLE_API_KEY="
仮想環境から抜けるには、deactivateを実行します。これはパッケージや作ったファイルを削除する操作ではありません。今回はクラウド上のリソースや、継続実行するサービスを作る手順はありません。
まとめ
Requestsの基本は、「URLとデータを決める → 送る → HTTPの状態を確認する → 必要ならJSONを読む → 値を取り出す」です。
最初はGETで取得できれば十分です。その後、POST、タイムアウト、エラー対応、認証情報の扱いを順に確認すると、一度に覚えることを減らせます。
関連記事
- Python環境の作成・切替を確認する:Python venv入門 Mac・Windowsの環境構築とactivate・deactivate
- 同じ通信をターミナルから試す:curl入門 APIを呼び出してHTTP・JSON・認証を理解する
- 認証方式の違いを整理する:API認証入門 Basic・APIキー・Bearer・JWT・OAuthの違い
おわりに
まずはget_demo.pyのtopicだけを別の公開してよい文字列へ変え、返ってくる値を確かめてみてください。送ったものと返ってきたものを小さく確認する習慣が、API連携の切り分けに役立ちます。
Wealthy Designでは、エンジニアの学習や現場で使える技術情報を発信しています。会社の取り組みは、コーポレートサイトで紹介しています。
AWS・Web開発・AI活用のご相談や、採用・カジュアル面談については、Wealthy Design公式LINEでもお問い合わせいただけます。

