【Pythonの基礎知識】JSONで構造化データを操る

Pythonでデータを扱う場面では、構造化された情報をやり取りするためにJSON（JavaScript Object Notation）が最も多く利用されます。

特にWeb APIやログ設計、設定ファイルなど、現場での登場頻度は圧倒的です。

Pythonでは標準ライブラリの「json」モジュールを使うだけで、辞書型（dict）やリスト型をJSON形式に変換したり、その逆を行うことができます。

この記事では、実務で遭遇した「文字化け」や「型の不一致」といった落とし穴を交えながら、JSONの正しい扱い方と安全な入出力処理の基礎を理解していきます。

JSONとは何か

Pythonでデータを扱うとき、最も登場するフォーマットの一つがJSONです。

JSONは「JavaScript Object Notation」の略で、データを「構造化」して表現するためのフォーマットです。

人間が読めて、機械も理解できるという特徴を持つため、Web APIやログ管理、設定ファイルなどで幅広く利用されています。

Pythonでは標準ライブラリ「json」モジュールを使うだけで、辞書やリストといったPythonの基本データ構造を簡単にJSON形式に変換できます。

JSONって何がそんなに便利なの？

CSVでもいいんじゃない？

CSVは単純な表形式のデータを扱うのに向いているけれど、入れ子構造や階層を表すのは苦手なんだ。ユーザー情報と購入履歴のような複雑なデータを扱うなら、JSONのほうが圧倒的に効率的だよ。

JSONの仕様・特徴とPythonとの関係

JSONは、文字列・数値・真偽値・配列・オブジェクトなどの基本構成要素で成り立っています。

Pythonでいうと、それぞれが以下のように対応します。

このように、PythonではJSONデータを直接辞書やリストとして扱えるため、変換が非常にスムーズです。

たとえば、辞書をJSON形式に変換するコードは以下の通りです。

import json
data = {"name": "BePro", "age": 38, "skills": ["Python", "Shell", "Java"]}
json_text = json.dumps(data, ensure_ascii=False, indent=2)
print(json_text)

【出力例:】

{
  "name": "BePro",
  "age": 38,
  "skills": [
    "Python",
    "Shell",
    "Java"
  ]
}

indentって何？

なくても動くけど？

indentは見た目を整えるためのスペース数を指定しているんだ。実行自体には不要だけど、ログや出力ファイルを人が読むときには整形しておくと解析しやすくなるよ。

実体験：構造化データ誤用で起きたトラブル

実務の現場では、JSONの扱いを誤るとデータ破損や通信エラーの原因になることがあります。

以前、API連携処理を自動化する際に、チームのメンバーが辞書をそのままprint出力して保存した結果、JSONとして不正な形式が混入するトラブルが発生しました。

# 誤った例
f = open("user_data.json", "w")
print(data, file=f) # Pythonの辞書をそのまま出力してしまう

この状態ではファイル内が「{'name': 'BePro'}」のようにPython独自の書式になり、他システムで読み込めません。

正しい方法はjson.dump()を使ってJSON形式に変換してから書き込むことです。

# 正しい例
with open("user_data.json", "w", encoding="utf-8") as f:
  json.dump(data, f, ensure_ascii=False, indent=2)

【出力例:】

{
  "name": "BePro"
}

printで出しても見た目は同じに見えたけど、どこが違うの？

見た目は似ていても、Pythonの辞書はシングルクォーテーションを使うけど、JSONはダブルクォーテーションで統一されているんだ。この違いだけでシステム間通信が失敗することがあるよ。だから常にjson.dump()やjson.dumps()を使うのが安全なんだ。

こうした経験を通して、単に動くコードを書くのではなく、他のシステムや人が使うことを前提に「形式を守る意識」を持つことが大切だと学びました。

JSONは便利ですが、正確さを軽視するとすぐに問題が顕在化します。

PythonでJSONを扱う基本操作

PythonでJSONを扱うときに欠かせないのが標準ライブラリの「json」モジュールです。

外部ライブラリをインストールする必要はなく、インポートするだけで簡単に利用できます。

主な機能は2つあり、PythonのデータをJSONに変換する「シリアライズ」と、JSONをPythonオブジェクトに変換する「デシリアライズ」です。

この2つを正しく理解することで、API連携や設定ファイルの操作を安全に行えるようになります。

シリアライズとかデシリアライズって難しく聞こえるけど、結局何をしてるの？

ざっくり言うと、Pythonの辞書やリストを「JSONという外の世界に出せる形にする」ことがシリアライズで、その逆に戻すのがデシリアライズだよ。つまり、データを行き来させる“通訳”みたいな役割なんだ。

jsonモジュールによるシリアライズ／デシリアライズ

Pythonでは、jsonモジュールを使って次の関数でJSONを簡単に変換できます。

import json
# Pythonの辞書をJSON文字列に変換
data = {"user": "BePro", "age": 38, "active": True}
json_text = json.dumps(data, ensure_ascii=False, indent=2)
print(json_text)

【出力例:】

{
  "user": "BePro",
  "age": 38,
  "active": true
}

このように「dumps()」を使うと、辞書やリストをJSONとして出力できます。

ensure_ascii=Falseを指定することで、日本語などのマルチバイト文字も文字化けせずに扱えます。

また、indentを指定すると整形されて読みやすくなります。

dumpsとdumpって名前が似てるけど、どう違うの？

dumpsは文字列に変換するだけ、dumpはファイルに書き込むものなんだ。よく混同されるけど、出力先が違うだけで中身の動作はほぼ同じだよ。

# JSONをファイルに出力
with open("user.json", "w", encoding="utf-8") as f:
  json.dump(data, f, ensure_ascii=False, indent=2)

【出力例:】cat user.json

{
  "user": "BePro",
  "age": 38,
  "active": true
}

次に、ファイルや文字列からJSONを読み込む例を見てみましょう。

# JSON文字列をPythonの辞書に変換
json_text = '{"user": "BePro", "age": 38, "active": true}'
data = json.loads(json_text)
print(data["user"])

【出力例:】

BePro

こうして見ると、JSONってPythonの辞書とそっくりなんだね

その通り。だからPythonではJSONを扱うのがとても自然なんだよ。型の変換ルールさえ知っていれば、APIやログ処理もスムーズに進む。

例示コードと変数説明

ここでは実際に使用したコードの変数を整理しておきます。理解しておくと、他のプロジェクトでもそのまま応用できます。

毎回この変換って面倒じゃない？自動でできる方法はないの？

確かに都度呼ぶのは手間だけど、関数にまとめてしまえばいい。システム開発では「読み込み関数」と「書き込み関数」を1つずつ定義して再利用するのが基本だよ。

このように、Pythonのjsonモジュールは直感的でシンプルながら、データ交換の要となる強力な機能を持っています。

慣れるとAPI開発やログ出力の精度も大幅に向上します。

実践：ファイル／APIデータでJSONを活用

ここからは、実際にファイルや外部APIと連携してJSONデータを活用する方法を解説します。

ファイル操作を通して「保存と再利用」を、APIからの取得を通して「通信と解析」を学ぶことで、Pythonで扱うデータの幅が一気に広がります。

特に、Web開発や自動化スクリプトではJSONを扱えないと処理が途端に複雑になります。

実務で頻出するシーンを想定して理解を深めていきましょう。

JSONファイルって、結局どうやって使うの？

JSONは「データを保存して後で再利用する仕組み」として使うことが多いんだ。設定情報、ログデータ、APIレスポンスなど、いろんな場面で共通して扱えるのが最大の利点だよ。

JSONファイルの読み書き

まずはファイルとしてJSONデータを保存し、後からそれを読み込む基本的な流れを確認します。

Pythonでは json.dump() と json.load() を使えば、わずか数行で実現できます。

import json
data = {"user": "BePro", "role": "engineer", "active": True}

# JSONファイルに書き込み
with open("user.json", "w", encoding="utf-8") as f:
  json.dump(data, f, ensure_ascii=False, indent=2)

# JSONファイルを読み込み
with open("user.json", "r", encoding="utf-8") as f:
  loaded = json.load(f)

print(loaded["user"])

【出力例:】

BePro

このコードでは、まずdata辞書をJSONファイルに保存し、その後同じファイルを開いて再度辞書型として読み込んでいます。

ファイルの内容を確認したい場合は、次のようにLinuxコマンドで表示できます。

cat user.json

【出力例:】

{
  "user": "BePro",
  "role": "engineer",
  "active": true
}

printとcatの結果って何が違うの？

printはPythonがファイルを読み込んで出力した結果、catはOSが直接ファイルを開いた内容なんだ。どちらも同じ中身だけど、catはファイルが正しく書き出されたかを確認するのに便利だよ。

また、json.dump()を使うことでエンコードエラーを防ぎながら日本語も安全に扱えます。

ensure_ascii=Falseを指定しておけば、マルチバイト文字も文字化けせずに保存されます。

外部APIから取得したJSONを処理した実体験

次に、実務でよくあるケースとして「APIから取得したJSONデータを処理する」例を見てみましょう。

最近、筆者が社内ツールの自動化を行った際、外部APIから社員情報を取得して整形するタスクをPythonで実装しました。

import requests
import json

response = requests.get("https://api.example.com/users/123")
data = response.json()

print(data["name"])

【サーバーから送られてきたJSONデータ】

{
  "id": 123,
  "name": "BePro",
  "department": "system",
  "active": true
}

このとき、response.json() によって上記の内容がPythonの辞書に変換され、data["name"] は "BePro" を取り出して表示します。 

【出力例:】

BePro

このように requests モジュールを使えば、APIレスポンスを簡単にJSONとして受け取ることができます。

Pythonの辞書として扱えるため、ループで一覧を作ったり、条件に応じて抽出したりといった処理も簡単です。

APIのレスポンスってファイルと違って毎回変わるよね？

それでも同じように扱えるの？

もちろん扱えるよ。ポイントは「レスポンスを一度変数に入れる」こと。ファイルと同じように辞書やリストとして扱えるから、処理の流れは変わらないんだ。

APIの結果をファイルに保存すれば、あとでオフライン解析にも利用できます。

たとえば次のように、取得したデータをローカルにキャッシュすることもできます。

with open("api_result.json", "w", encoding="utf-8") as f:
  json.dump(data, f, ensure_ascii=False, indent=2)

【出力例:】（＝ cat api_result.json）

{
  "name": "BePro",
  "department": "system",
  "active": true
}

APIの結果をファイルに残す意味ってある？

あるよ。たとえばAPIが一時的に落ちたときも、キャッシュファイルがあれば前回の結果を再利用できる。

これは自動化や運用スクリプトでよく使うテクニックだね。

気をつけること／落とし穴と対策

JSONは便利で柔軟なデータ形式ですが、扱いを誤ると「文字化け」や「データ型の不一致」といった問題が発生します。

特にPythonと外部システムのやり取りでは、エンコード設定や型の違いによるトラブルが起こりやすく、原因が見えにくいため注意が必要です。

ここでは、筆者が実際に遭遇したミスや対策を交えながら、運用上で押さえておくべきポイントを解説します。

JSONって人間にも読みやすいって言うけど、なんでエラーが出ることがあるの？

人間が読めるフォーマットではあるけど、コンピュータ同士がやり取りする以上は「ルールの違い」で噛み合わないことがあるんだ。特に文字コードとデータ型の違いは油断しやすいポイントだよ。

文字コード・データ型のズレ／互換性の課題

PythonでJSONを扱う際に最も多いトラブルは、「文字コードの違いによる文字化け」と「データ型の変換ミス」です。

JSONはUTF-8を前提としていますが、システムによってはShift_JISやEUC-JPで保存されていることもあります。

たとえば、次のようなケースです。

import json
with open("config.json", "r", encoding="utf-8") as f:
  data = json.load(f)

ファイルをUTF-8以外の文字コードで保存していた場合、上記のようなコードでも読み込み時に「UnicodeDecodeError」が発生します。

この場合は、ファイルのエンコードを統一するか、読み込み時に正しい文字コードを指定することが重要です。

with open("config.json", "r", encoding="shift_jis") as f:
  data = json.load(f)

UTF-8が標準なのに、なんでShift_JISのまま使われてるケースがあるの？

昔の日本向けシステムはShift_JISが主流だったんだ。業務で古いデータを扱うと、今でもそのまま残っていることが多い。だからPythonで扱う前に、文字コードを揃えるのが最初の一歩なんだよ。

もうひとつの落とし穴は、型の違いです。

たとえばJSONの数値はPythonで自動的にintやfloatに変換されますが、True/Falseが「true」「false」に置き換わるなど微妙な差異があります。

外部システムに送信する際は、この違いが原因で「型エラー」や「不正フォーマット」と判定されることがあります。

data = {"price": 100, "active": True}
print(json.dumps(data))

【出力例:】

{"price": 100, "active": true}

見た目ではほとんど同じですが、PythonではTrue、JSONではtrue（小文字）と表現される点が異なります。

このような違いを理解しておくと、他システムとの連携がスムーズになります。

実体験から学んだ運用上の注意点

筆者が実務でJSONを扱った際、最も苦労したのは「仕様変更への追随」と「ログ出力時の混乱」でした。

JSON形式の設定ファイルを運用していたところ、ある日突然APIのレスポンスに新しいキーが追加され、読み込みスクリプトがKeyErrorで停止しました。

try:
  value = data["new_key"]
except KeyError:
  value = None

このように例外処理を入れておくことで、予期せぬ変更にも柔軟に対応できます。

システムが「壊れにくい設計」になるというのが大きなメリットです。

確かに現場では仕様が変わることが多いね。

じゃあログはどうしてる？

ログはJSONで出力しておくと、あとで分析しやすいんだ。特にjson.dumps()で整形して保存しておけば、grepやjqコマンドでも簡単に検索できる。

さらに、ファイルサイズが大きくなった場合は、圧縮や世代管理も検討すべきです。

不要なキーを削除したり、1ファイルごとに日付を付けて保存するなどの工夫をすれば、障害対応のときも素早く原因を特定できます。

mv user.json user_$(date +"%Y%m%d").json

【出力例:】

user_20251103.json

このような細やかな管理を続けることで、JSONデータの信頼性と保守性が格段に高まります。

便利な仕組みほど、扱い方次第で強力にも脆弱にもなる——そのことを意識して運用していくことが、エンジニアとしての確かな強みになります。

まとめ

JSONは、Pythonと外部システムをつなぐ“共通言語”のような存在です。

ファイルへの保存、APIとの通信、そして設定管理など、あらゆる場面で利用できます。

扱い方を理解しておくことで、データの流れを設計できるようになり、開発や運用の精度が大きく向上します。

結局、JSONを覚えると何が変わるの？

データの受け渡しがスムーズになるだけじゃなく、他のエンジニアやシステムとの協調がしやすくなるんだ。つまり、コードの“つながり”を設計できるようになるのが最大の強みだよ。

す。JSONを自在に扱えるようになることは、Pythonエンジニアとしての確かな基礎を築く第一歩です。

異常が起きても止まらない“堅牢な仕組み”を作る。try／except構文の理解から、実践的な例外設計の考え方までを体系的に学びます。
👉 【Pythonの基礎知識】例外処理で“壊れない仕組み”を設計する

Beエンジニア

【Pythonの基礎知識】例外処理で“壊れない仕組み”を設計する

https://www.pmi-sfbac.org/python-basic-43-exception-handling

プログラムを書いていると、想定外の事態が必ず発生します。たとえば入力値が不正だったり、外部ファイルが見つからなかったり、ネットワークが途切れたり。これらを放置すると、仕組みが突然停止してユーザーに迷惑をかけたり、ログが散らかって原因把握ができなくなったりします。そこで、Pythonにおける例外処理は、単なる「エラー回避」ではなく「壊れない仕組みを設計するための第一歩」です。公式ドキュメントでも、try／except／else／finally を適切に組み合わせることが推奨されています。本記事では、実体験を交えながら「例...

実践環境を整える

ここまで学んだ知識を実際に試すには、Linuxを動かす環境が必要です。手軽に始めるならVPSを利用するのがおすすめです。
→ VPS徹底比較！ConoHa・さくら・Xserverの選び方

Beエンジニア

VPS徹底比較！ConoHa・さくら・Xserverの選び方

https://www.pmi-sfbac.org/vps-comparison-conoha-xserver-sakura

国内で人気の高いVPSサービス「ConoHa VPS」「さくらのVPS」「エックスサーバーVPS」。どれも高性能で魅力的な選択肢ですが、用途や重視ポイントによって最適な選び方は変わってきます。この記事では、料金、スペック、操作性、サポート体制などを徹底比較しながら、あなたにぴったりのVPSを見つけるためのヒントをわかりやすく紹介します。それでももし、VPSをどれにするか迷っているなら、まずは ConoHa VPS を選べば間違いありません。料金・使いやすさ・安定性のバランスが良く、初心者から実務利用まで幅広く対応できます。主要3...