【ITニュース解説】JSON to CSV in Python: the pandas recipe that survives nested data
2026年10月22日に「Dev.to」が公開したITニュース「JSON to CSV in Python: the pandas recipe that survives nested data」について初心者にもわかりやすく解説しています。
ITニュース概要
PythonでJSONをCSVに変換する際、データがネストしているとpandasでエラーが出やすい。本記事は、単純なJSONは`read_json`、ネストしている場合は`json_normalize`を使い、`record_path`や`meta`で平坦化する方法を解説する。よくあるエラーとその解決策もまとめている。
ITニュース解説
JSONからCSVへの変換は、システム開発で頻繁に必要となる作業だが、特に「ネストされたデータ」(値の中にさらにリストや辞書が含まれる構造)を含むJSONを扱う際には、いくつかの課題が生じる。この記事では、Pythonのpandasライブラリを使い、複雑なJSONデータを効率的かつ正確にCSV形式へ変換する具体的な手法と、よくある問題への対処法を、システムエンジニアを目指す初心者の皆さんにも分かりやすく解説する。
変換時の主な課題と解決策として、いくつかの典型的な問題とその対処法がある。例えば、CSVの先頭に「0, 1, 2」のような不要な列が追加される場合、to_csv()メソッドにindex=Falseオプションを指定することで非表示にする。また、CSVのセル内に{'name': 'Ana', ...}のような辞書やリストの文字列がそのまま表示されるのは、JSONデータがネストされた構造を持つためだ。これを適切にフラット化しないと分析は困難で、後述のpd.json_normalize()関数が解決策となる。pandas 3.0以降でJSON文字列をpd.read_json()に直接渡すとファイルパスと誤解されFileNotFoundErrorが発生するケースがあるが、io.StringIOモジュールを使って文字列をファイルのように扱うことで解決する。NDJSON形式のファイルではread_json()にlines=Trueオプションを渡し、特定のキーが存在しないことによるKeyErrorはjson_normalize関数のerrors="ignore"オプションで対応する。Windowsでの空行問題はopen()関数のnewline=""引数で、Excelでの文字化けはencoding="utf-8-sig"で対処する。
適切なCSV変換には、まずJSONデータ自体の構造を正確に把握することが不可欠だ。JSONが「リストの中に複数のオブジェクト(辞書)が格納されているか」「すべてのオブジェクトが同じキーを持つか」「値の中にさらにリストや辞書(ネストされたデータ)が含まれるか」という3つの視点で構造を確認する。記事では、Pythonコードを使ってレコード数、キーの欠損、ネストされたキーの有無を検出する方法が示されている。この構造把握が、最適な変換方法を選択するための基礎となる。
JSONデータがネストされた構造を持たず、全ての値がシンプルな文字列や数値である「フラットな」形式であれば、変換は非常に簡単だ。pandasのpd.read_json()でJSONファイルを読み込み、df.to_csv(index=False)でCSVファイルに書き出すというわずか2行のコードで完了する。io.StringIOを使った文字列の読み込みに注意すれば良い。
JSONデータがネストされている、つまり値の中にさらに辞書やリストが含まれる場合は、pd.json_normalize()関数が中心的な役割を果たす。この関数は、ネストされたデータを自動的にフラットな表形式に展開する。主な引数として、record_pathには新しいCSVの行として展開したいリストのキーを指定する。例えば、注文データの中に商品リストがある場合、record_path="items"と指定すれば、各商品が独立した行として扱われる。meta引数には、親レコードから引き継ぎたいフィールドをリストで指定する。これには注文IDや顧客名、住所など、商品情報と関連付けたい項目が含まれる。metaに指定されたネストされた辞書も自動的にフラット化され、例えばcustomer_address_cityのような新しい列名が生成される。列名の区切り文字はsep引数で指定できる。
ネストされたデータの中でも、特に「レコードの中に配列(リスト)がある場合」は、目的によって処理方法を選択する必要がある。一つは、explode()メソッドを使ってリストの各要素を新しい行として展開する方法だ。これにより、CSVを項目ごとにフィルタリングしたり集計したりといった詳細な分析が可能となる。もう一つは、json.dumps()を使ってリスト全体をJSON形式の文字列として1つのセルに格納する方法だ。この場合、CSVの行数は元のレコード数と一致するため、行数を維持したい場合や、リストの内容をそのまま保存しておきたい場合に適している。
CSV変換が完了したら、作成されたCSVファイルが意図通りの形になっているかを必ず確認することが重要だ。特に、セルの内容が{や[で始まっていないかをチェックすることで、まだネストされたデータが文字列として残ってしまっていないかを確認できる。pandasを使ってCSVを読み戻し、元のデータフレームの形状と一致するか、そして各セルの内容が適切にフラット化されているかを検証する。
pandasの導入が難しい環境や、シンプルなフラットなJSONデータのみを扱う場合は、Python標準のjsonモジュールとcsv.DictWriterクラスを利用してCSV変換を行うことも可能だ。DictWriterのfieldnamesにはすべてのレコードから存在するキーを網羅的に集めて指定することで、一部のキーが欠損していてもエラーを回避できる。ただし、この方法はネストされたデータには対応せず、値がPythonの文字列としてそのまま出力されるため、フラットなJSONデータに限定される。
また、非常に大きなJSONファイルを扱う際にメモリ不足が問題となる場合は、NDJSON形式のファイルであればpd.read_json(lines=True)で効率的に読み込める。さらに、chunksize引数を使ってデータを小さな塊(チャンク)に分割し、チャンクごとに処理してCSVファイルに追記していくことで、メモリ使用量を抑えながら大規模なファイルを処理することが可能となる。
JSONからCSVへの変換は、データの構造を正しく理解し、適切なツールとオプションを選ぶことで、どんな複雑なデータでも効率的に処理できる。まず自身のJSONデータの形状をチェックし、ネストされたデータがあればjson_normalizeのrecord_pathとmetaを適切に設定する。レコード内のリストをどう扱うかを決め、最後に変換後のCSVデータを読み戻して、期待通りの形になっているかを確認する。これらのステップを踏むことで、システムのデータ連携や分析業務において、JSONとCSV間のスムーズなデータ変換を実現できる。