공공데이터에서 보고서까지

공공데이터포털에서 내려받은 도서관 CSV를 JSON으로 바꾸고, 지역별 현황 화면과 출처가 있는 검토 메모를 만듭니다. 첫 실행은 키트의 가상 CSV로 연습하고, 그다음 실제 CSV로 교체합니다. 연습 수치 6곳·400석을 실제 통계로 쓰지 않습니다.

전국도서관표준데이터는 이 교재의 실제 자료 탐색 출발점입니다. 포털의 화면과 제공 범위는 바뀔 수 있습니다. 2026-09-20에 자료 페이지와 열 이름을 확인했으며, 학습자 계정의 다운로드·API 승인은 직접 진행해야 합니다.

준비물은 실습 키트, Python 3.10 이상, 웹브라우저입니다. 실제 자료를 확보하지 못해도 가상 CSV로 변환·검증까지 마칠 수 있습니다.

질문을 “우리 지역의 도서관은 몇 곳이고, 알려진 좌석은 몇 석인가?”로 좁힙니다. 전국 모든 시설을 비교하거나 수요를 예측하는 것은 이번 실습 범위를 넘습니다.

report.md의 사본을 report-public.md로 저장하고 다음 항목을 먼저 적으세요.

# 도서관 현황 검토
- 대상 지역: 직접 입력
- 포함 범위: 내려받은 파일의 실제 범위
- 자료명: 전국도서관표준데이터
- 출처 URL: https://www.data.go.kr/data/15013109/standard.do
- 제공기관: 선택한 자료의 표시값
- 자료 기준일: 각 행 확인
- 다운로드 날짜: 오늘 날짜
- 이용조건: 자료 페이지에서 확인한 내용

성공 확인: “자료 기준일”과 “다운로드 날짜”를 따로 적었습니다. 오늘 내려받았다고 자료가 오늘의 현황인 것은 아닙니다.

1. 위 공식 자료 페이지를 엽니다. 자료 설명과 제공범위를 읽습니다.
2. 기관별 데이터가 필요하면 기관명으로 검색하고 해당 자료를 선택합니다. 통합 자료를 쓰면 어느 지역까지 포함되는지 확인합니다.
3. 활용 정보의 파일 다운로드에서 CSV를 찾습니다. 다운로드 창에서 계정 로그인을 요구하면 직접 로그인합니다.
4. 원본 파일은 별도 보관하고, 작업용 사본을 tech-practice/portal.csv로 저장합니다. 확장자가 .csv.csv가 되지 않게 확인합니다.
5. 파일에 필요한 네 열이 있는지 확인합니다: 도서관명, 시군구명, 열람좌석수, 데이터기준일자.

포털에서 조회·다운로드한 결과가 일부 범위라면 그 범위를 보고서에 적습니다. 목록 페이지의 기관 수와 CSV의 도서관 수를 같은 값으로 취급하지 않습니다. 통합 자료와 개별 기관 자료는 갱신 시점이 다를 수 있으므로 같은 날짜의 숫자라고 가정하지 마세요.

ZIP을 압축 해제한 폴더에서 실행합니다. Windows에서는 아래 python3를 py로 바꿉니다.

python3 convert_csv.py sample.csv --sample --source "교육용 가상 데이터"
python3 server.py

브라우저에서 http://127.0.0.1:8765를 열면 6곳·400석입니다. 이것이 변환기와 화면이 함께 작동한다는 기준선입니다. 화면이 안 나오면 실제 파일을 넣기 전에 이 상태부터 해결하세요.

프로그램은 다음처럼 이름을 바꿉니다. 날짜는 원본 값을 보존하며, 빈 좌석은 null로 유지합니다.

원본 CSV 열	JSON 필드	화면에서 의미
도서관명	name	시설 이름
시군구명	city	지역 선택 조건
열람좌석수	seats	알려진 좌석 합계
데이터기준일자	date	행별 자료 기준일

서버 터미널은 그대로 두고 같은 폴더에서 새 터미널을 엽니다. 실제 portal.csv가 준비되면 다음을 실행합니다. 실제 자료에는 --sample을 붙이지 않습니다.

python3 convert_csv.py portal.csv --source "전국도서관표준데이터 · https://www.data.go.kr/data/15013109/standard.do"

완료 메시지의 행 수를 기록하고 대시보드를 새로 고칩니다. 화면의 표시가 [공공데이터]로 바뀌어야 합니다. 좌석 합계는 실제 파일에 따라 달라지며, 400석과 같을 필요가 없습니다.

한글 인코딩 오류가 나고 원본이 CP949라면 다음처럼 다시 시도합니다. 인코딩을 바꿔 읽는 것이며 원본을 수정하는 명령은 아닙니다.

python3 convert_csv.py portal.csv --encoding cp949 --source "전국도서관표준데이터 · https://www.data.go.kr/data/15013109/standard.do"

행 수 확인: CSV를 표로 열어 머리글을 제외한 기록 수를 세고 변환 결과와 비교합니다. 중복 도서관이 있는지 이름·지역·주소를 함께 검토하세요. 이 변환기는 중복을 자동 삭제하지 않습니다. 같은 이름이 반드시 같은 시설이라는 보장이 없기 때문입니다.

대상 지역을 선택하고 도서관 수·좌석 합계·미상 개수를 기록합니다. 원본에서 3개 행을 직접 찾아 값이 같은지 대조하세요. 자료 기준일이 여러 개라면 그 범위도 적습니다.

AI에는 확인한 숫자만 전달해 초안을 요청합니다.

아래 집계로 행정 검토 메모를 작성해줘.
[내가 확인한 지역, 도서관 수, 좌석 합계, 미상 개수, 출처, 기준일]
구성은 사실 / 해석의 한계 / 추가 확인 순서로 해줘.
제공하지 않은 수치와 원인을 만들지 마.
이용자 수·운영시간이 없으므로 수요나 효율을 단정하지 마.

AI 답변과 원본 숫자를 다시 비교하고 report-public.md에 반영합니다. 검토 책임은 사람에게 있습니다. 도서관 수 증가·감소를 말하려면 같은 범위와 정의로 집계한 과거 자료가 추가로 필요합니다.

자료 페이지의 오픈 API 안내에서 활용 신청, 서비스 URL, 요청 변수, 응답 예시, 호출 한도를 확인합니다. 같은 포털의 API라도 주소와 응답 구조가 같다고 가정하지 마세요. 이번 교재는 특정 인증키를 발급하거나 실제 인증 API 호출에 성공했다고 주장하지 않습니다.

실제 연결 순서는 다음과 같습니다.

1. 해당 API의 활용 신청과 승인을 확인합니다.
2. 문서에 제시된 최소 요청을 서버나 로컬 프로그램에서 한 번 실행합니다.
3. HTTP 상태와 본문의 서비스 결과 코드를 함께 확인합니다. 오류가 XML로 오는 경우도 구별합니다.
4. 페이지 크기·전체 건수·종료 조건을 확인하고 제한된 범위부터 수집합니다.
5. 받은 필드를 이 키트의 name·city·seats·date로 매핑합니다.
6. CSV 집계와 비교한 후 자동 갱신으로 확장합니다.

인증키는 브라우저 JS나 공개 저장소에 넣지 않습니다. 문서에서 인코딩된 키와 원문 키를 구별하고, URL 생성 과정에서 이중 인코딩하지 않게 확인합니다. 오류 상담 시 키가 포함된 주소는 가립니다.

증상	해결
필수 열 누락	실제 머리글을 확인하고 작업용 CSV의 열 이름을 맞춤. 다른 의미의 열을 억지로 대응하지 않음
좌석 숫자 오류	표시된 행을 원본과 대조. 알 수 없는 값은 빈 칸으로 남기고 변경 이력 기록
숫자가 너무 큼	중복·전국 범위 포함·필터 조건 확인
JSON이 이전 내용	변환 오류로 기존 파일이 보존됐는지 확인

가상 데이터로 복원하려면 원본 sample.csv에 대해 --sample을 붙여 변환합니다. 실제 파일 원본과 검토 메모는 별도 보존하세요.

완료 기준은 출처·범위·기준일이 있는 대시보드, 원본과의 행 수 대조, 사실과 한계를 구분한 메모입니다. 다음 교재는 이 결과물을 공개 주소로 배포합니다. 공개 전에는 파일의 이용조건과 공개 범위를 확인하세요.

• 전국도서관표준데이터 · 공공데이터포털
• Python CSV 읽기