Convert JSON to CSV: Complete Guide With Examples

JSONからCSVへの変換が必要なとき

JSONはAPIやウェブアプリケーションのデフォルトフォーマットですが、データが開発者エコシステムを離れ、スプレッドシート、ビジネスインテリジェンスツール、データベースインポート、またはステークホルダーにメールで送信されるレポートに移行する必要があるとき、CSVが通常期待されるフォーマットです。

JSONからCSVへの変換が必要となる一般的なシナリオ：

• APIデータのエクスポート — REST APIからレコードを取得し、分析のためにExcelやGoogle Sheetsにロードします。
• データベースインポート — 多くのデータベース（PostgreSQL、MySQL、SQLite）はCSVインポートを標準でサポートしていますが、JSONはサポートしていません。
• レポーティング — 非技術的なステークホルダーは、JSONビューワーではなく、スプレッドシートで開けるフォーマットのデータを必要とします。
• データパイプライン — レガシーETLシステムは、しばしばステージ間のインターチェンジフォーマットとしてCSVを期待します。

自分で試してみてください： JSON配列を私たちのJSON to CSVコンバーターに貼り付けて、すぐにダウンロード可能なCSVファイルを取得してください。

簡単な変換手順

単純なケース：同じキーを持つフラットなオブジェクトのJSON配列があります。これはCSVテーブルに直接マッピングされます。

入力JSON：

[
  { "name": "Alice", "age": 30, "city": "Portland" },
  { "name": "Bob", "age": 25, "city": "Seattle" },
  { "name": "Carol", "age": 35, "city": "Denver" }
]

出力CSV：

name,age,city
Alice,30,Portland
Bob,25,Seattle
Carol,35,Denver

オブジェクトのキーは列ヘッダーになり、各オブジェクトは行になります。これはハッピーパスであり、レコードの配列を返すほとんどのAPIレスポンスに対して完璧に機能します。

複雑さは、JSONがフラットでないときに発生します。ネストされたオブジェクト、オブジェクト内の配列、欠落したキー、混合型はすべて、階層データをフラットなテーブルでどのように表現するかについての決定を必要とします。

ネストされたJSONの処理

現実のJSONはフラットであることはまれです。ユーザーのAPIレスポンスには、ネストされたアドレスオブジェクト、役割の配列、およびすべてのレコードに表示されないオプションフィールドが含まれることがあります。CSVにはネストの概念がないため、フラット化戦略が必要です。

戦略1：ドット表記

最も一般的なアプローチです。ネストされたキーはドットで連結されて、単一の列名を形成します。

入力：

[
  {
    "name": "Alice",
    "address": {
      "city": "Portland",
      "state": "OR"
    }
  }
]

出力：

name,address.city,address.state
Alice,Portland,OR

ドット表記は、列名に構造的関係を保持します。1〜2レベルのネストにはうまく機能しますが、深くネストされたデータ（user.profile.settings.notifications.email）には扱いが難しくなります。

戦略2：リーフ値ごとの別々の列

ドット表記に似ていますが、ネスト階層を省略したカスタマイズされた列名を使用します。たとえば、address.cityは単にcityになります。これにより、クリーンなヘッダーが生成されますが、手動での列マッピングが必要で、異なるネストされたオブジェクトが同じ名前のキーを持つ場合に名前の衝突のリスクがあります。

戦略3：ネストされたオブジェクトを文字列化

フラットな列にうまくマッピングできない複雑なネスト構造の場合、ネストされた値をCSVセル内のJSON文字列としてシリアライズします。

出力：

name,address
Alice,"{""city"":""Portland"",""state"":""OR""}"
Bob,"{""city"":""Seattle"",""state"":""WA""}"

これにより、すべてのデータが保持されますが、CSVセルには生のJSONが含まれます — スプレッドシートユーザーには理想的ではありません。CSVが再度コードによって解析される中間フォーマットである場合には機能します。

フラット化アプローチの比較

アプローチ	可読性	データ損失	深いネスト	最適な用途
ドット表記	良好	なし	冗長になる	1-2レベルのネスト
カスタム列名	最良	衝突の可能性	手動の労力	知られた、安定したスキーマ
文字列化	人間には不適	なし	どんな深さも処理	機械間のパイプライン

オブジェクト内の配列の処理

配列は異なる課題を提示します。複数の役割を持つユーザーを考えてみましょう：

{
  "name": "Alice",
  "roles": ["admin", "editor", "viewer"]
}

これをCSVで表現するためのいくつかのオプションがあります：

• 区切り文字付き文字列として結合： admin;editor;viewerを単一のセルに。シンプルですが、後で解析が必要です。
• 別々の列： roles.0, roles.1, roles.2。最大配列長が既知で小さい場合に機能します。
• 別々の行： 役割ごとに1行、ユーザーの他のデータを繰り返します。これによりデータが非正規化されますが、複数値セルを回避します。
• 文字列化： ["admin","editor","viewer"]をセル内の生のJSONとして。後で処理するための構造を保持します。

適切な選択は、CSVを消費する人によります。スプレッドシートユーザーには、区切り文字付き文字列アプローチが通常最も実用的です。データパイプラインの場合、文字列化は最も多くの情報を保持します。

エッジケース

すべてのJSONからCSVへの変換は、最終的にこれらのケースに直面します。事前に知っておくことで、デバッグ時間を節約できます。

Null値

JSONのnullは、空のセル、リテラル文字列null、またはカスタムプレースホルダーにマッピングできます。ほとんどのツールは空のセルを使用しますが、これはスプレッドシートには正しいですが、「null」（明示的に値がない）と「欠落したキー」（フィールドが存在しない）の区別を失います。その区別が重要な場合は、リテラル文字列としてnullを使用してください。

混合型

JSONフィールドは、あるレコードでは文字列であり、別のレコードでは数値である場合があります。CSV列には型がないため — すべてが文字列です — これは通常CSVレベルでは問題ありません。問題は、型付きシステム（データベース、型付きデータフレーム）にインポートするときに表面化します。変換後に型を検証してください。

欠落したキー

JSON配列内のオブジェクトがすべて同じキーを持っていない場合、コンバーターはすべてのオブジェクトにわたるすべてのキーのユニオンを構築する必要があります。これにより、すべての可能な列を持つヘッダーロウが生成され、キーが欠落しているオブジェクトにはその列の空のセルが割り当てられます。

[
  { "name": "Alice", "age": 30 },
  { "name": "Bob", "city": "Seattle" }
]

出力：

name,age,city
Alice,30,
Bob,,Seattle

値内の特殊文字

カンマ、二重引用符、または改行を含むCSV値は、二重引用符で囲む必要があります。値自体に二重引用符が含まれている場合は、二重にすることでエスケープされます。ほとんどの変換ライブラリはこれを自動的に処理しますが、自分でコンバーターを構築している場合は、最も一般的なバグの原因です。

name,bio
Alice,"Loves ""JSON"" and coding"
Bob,"Portland, OR"

プログラムによる変換

JavaScript / Node.js

単純なフラットデータの場合、依存関係なしで数行でJSONをCSVに変換できます：

const jsonToCsv = (data: Record<string, unknown>[]) => {
  if (data.length === 0) return "";

  const headers = Object.keys(data[0]);
  const rows = data.map((row) =>
    headers
      .map((header) => {
        const value = row[header] ?? "";
        const str = String(value);
        return str.includes(",") || str.includes('"') || str.includes("\\n")
          ? `"\${str.replace(/"/g, '""')}"` 
          : str;
      })
      .join(",")
  );

  return [headers.join(","), ...rows].join("\\n");
};

ネストされたデータを使用する場合は、json2csv（@json2csv/plainjsパッケージから）などのライブラリがフラット化、カスタム変換、およびエッジケースを処理します：

import { Parser } from "@json2csv/plainjs";
import { flatten } from "@json2csv/transforms";

const parser = new Parser({
  transforms: [flatten({ separator: "." })],
});

const csv = parser.parse(data);

Python

Pythonの標準ライブラリには、基本的な変換に必要なすべてが揃っています：

import csv
import json
import io

def json_to_csv(data: list[dict]) -> str:
    if not data:
        return ""

    output = io.StringIO()
    writer = csv.DictWriter(output, fieldnames=data[0].keys())
    writer.writeheader()
    writer.writerows(data)
    return output.getvalue()

ネストされたJSONの場合、pandasライブラリは1回の呼び出しでフラット化して変換します：

import pandas as pd

df = pd.json_normalize(data, sep=".")
df.to_csv("output.csv", index=False)

json_normalizeは、列名のドット表記を使用してネストされたオブジェクトを自動的に処理します。ネストされたAPIレスポンスからクリーンなCSVファイルに移行する最速の方法です。

大きなファイルの考慮事項

JSONファイルが数百メガバイト以上の場合、変換アプローチを変更する必要があります。ファイル全体をメモリにロードし、解析し、メモリ内にCSV文字列を構築すると、利用可能なRAMを簡単に超えることがあります。

ストリーミングパーサーが解決策です。ファイル全体をロードするのではなく、インクリメンタルに処理します：

• Node.js： JSONStreamまたはstream-jsonを使用して、JSON配列を1つのオブジェクトずつ解析し、各オブジェクトをCSV行に変換し、出力ストリームに書き込みます。メモリはファイルサイズに関係なく一定に保たれます。
• Python： ijsonライブラリが反復的なJSON解析を提供します。これをcsv.writerと組み合わせてファイルハンドルに書き込むことで、一定のメモリでの変換を実現します。
• CLI： jqは、ネイティブにストリーミング方式でJSONを処理します。特にJSONからCSVへの変換には、miller（mlr）やcsvkitなどのツールが大規模なフォーマット変換のために設計されています。

実用的なルール：JSONファイルが50MB未満の場合、メモリ内変換は問題ありません。それ以上の場合は、ストリーミングアプローチに切り替えます。1GBを超える場合は、millerのようなCLIツールや専用のデータ処理フレームワークを使用します。

適切なアプローチの選択

シナリオ	推奨アプローチ
短期的な一回限りの変換	オンラインツールまたはブラウザコンバーター
フラットなJSON、小さなファイル	言語の組み込みライブラリ（csvモジュール、シンプルなJS関数）
ネストされたJSON、複雑なスキーマ	pandas.json_normalizeまたは@json2csvのフラット変換
大きなファイル（>50MB）	ストリーミングパーサー（ijson、stream-json）またはCLI（miller）
定期的なパイプライン	ライブラリを使用したスクリプト、CI/ETLに統合

ほとんどの開発者にとって、迅速な変換パスが必要なすべてです。JSONを貼り付けてCSVを取得し、次に進む。複雑さは、データがネストされている場合、ファイルが大きい場合、または変換がパイプラインで無人で実行される場合にのみ重要です。

自分で試してみてください： JSONデータを私たちのJSON to CSVコンバーターに貼り付けて、数秒でクリーンなCSVファイルを取得してください。逆に行く必要がありますか？私たちのCSV to JSONツールを使用してください。