Python으로 JSON을 CSV로 변환하는 방법: 완전한 튜토리얼과 코드 예제

일상적인 데이터 처리에서 JSON 형식 데이터를 CSV 테이블로 변환해야 하는 상황을 자주 마주칩니다. API 데이터 내보내기, 로그 파일 분석, Excel에서 시각화 등이 그 예입니다.

이 글에서는 Python을 사용하여 JSON → CSV 변환을 효율적으로 수행하는 방법을 소개하고, 몇 가지 일반적인 구현 방법을 제시합니다.

---

📘 1. JSON과 CSV의 주요 차이점

API에서 반환된 JSON 데이터를 스프레드시트에서 보거나 분석하려면 CSV로 변환해야 합니다.

---

⚙️ 2. Python 표준 라이브러리를 사용한 JSON에서 CSV로 변환

Python에는 강력한 json과 csv 표준 라이브러리가 내장되어 있어 추가 종속성 없이 직접 변환을 처리할 수 있습니다.

예제 1: 기본 버전 (평면 JSON 구조)

import json
import csv

# JSON 파일 읽기
with open('data.json', 'r', encoding='utf-8') as f:
    data = json.load(f)

# CSV 파일을 쓰기용으로 열기
with open('output.csv', 'w', newline='', encoding='utf-8') as csvfile:
    writer = csv.writer(csvfile)

    # 헤더 쓰기 (첫 번째 요소의 키에서 추출)
    header = data[0].keys()
    writer.writerow(header)

    # 각 행의 데이터 쓰기
    for row in data:
        writer.writerow(row.values())

print("✅ JSON이 CSV로 성공적으로 변환되었습니다: output.csv")

입력 예제:

[
  {"name": "Alice", "age": 25, "city": "Shanghai"},
  {"name": "Bob", "age": 30, "city": "Beijing"}
]

출력 결과 (CSV):

name,age,city
Alice,25,Shanghai
Bob,30,Beijing

---

🧩 3. 중첩된(Nested) JSON 처리

JSON에 중첩된 객체나 배열이 포함되어 있다면, 먼저 구조를 "펼쳐야" 합니다.

예제 2: pandas.json_normalize() 사용

import pandas as pd
import json

# 중첩된 JSON 읽기
with open('nested.json', 'r', encoding='utf-8') as f:
    data = json.load(f)

# 중첩된 구조를 평면 테이블로 펼치기
df = pd.json_normalize(data)

# CSV로 내보내기
df.to_csv('output.csv', index=False, encoding='utf-8-sig')

print("✅ 중첩된 JSON이 CSV로 성공적으로 변환되었습니다: output.csv")

입력 예제:

[
  {
    "user": {"name": "Alice", "id": 101},
    "stats": {"score": 98, "level": 3}
  },
  {
    "user": {"name": "Bob", "id": 102},
    "stats": {"score": 87, "level": 2}
  }
]

출력 결과:

user.name,user.id,stats.score,stats.level
Alice,101,98,3
Bob,102,87,2

✅ 팁: pandas.json_normalize()는 중첩된 필드를 자동으로 평면화하므로 복잡한 JSON에 완벽합니다.

---

🚀 4. URL에서 JSON 읽기 및 CSV로 내보내기

원격 API에서 직접 JSON 데이터를 로드할 수도 있습니다:

import requests
import pandas as pd

url = "https://jsonplaceholder.typicode.com/users"
data = requests.get(url).json()

df = pd.json_normalize(data)
df.to_csv('users.csv', index=False, encoding='utf-8-sig')

print("✅ URL에서 JSON을 읽고 CSV로 내보냈습니다")

---

🧠 5. 자주 묻는 질문 (FAQ)

1️⃣ 파일 인코딩 문제는?

→ CSV를 저장할 때 encoding='utf-8-sig'를 사용하여 Excel에서 중국어가 정상적으로 표시되도록 합니다.

2️⃣ JSON 루트가 배열이 아닌 경우는?

→ JSON이 단일 객체({} 등)인 경우, 수동으로 배열로 감쌀 수 있습니다:

data = [data]

3️⃣ Excel로 가져오는 방법은?

→ Excel에서 "데이터" → "텍스트/CSV에서" → 출력 파일을 선택합니다.

---

🧰 6. 완전한 프로젝트 예제

명령줄 도구가 필요한 경우:

# json2csv.py
import sys
import pandas as pd

def json_to_csv(input_file, output_file):
    df = pd.read_json(input_file)
    df.to_csv(output_file, index=False, encoding='utf-8-sig')
    print(f"✅ {input_file}이 {output_file}로 변환되었습니다")

if __name__ == "__main__":
    if len(sys.argv) != 3:
        print("사용법: python json2csv.py input.json output.csv")
    else:
        json_to_csv(sys.argv[1], sys.argv[2])

실행:

python json2csv.py data.json output.csv

---

🧭 7. 요약

가끔 변환만 하는 경우, 온라인 도구 👉 JsonWork.com/json-to-csv 를 사용할 수 있습니다.

Python 설치 불필요, 붙여넣기 / 업로드 / 다운로드 지원, 100% 로컬 처리로 더 안전하고 편리합니다.

---

2025년 10월 5일 게시