공공 API JSON을 검산 가능한 CSV로

소방용수·소화전 같은 공공 API를 활용 신청해 페이지별 JSON을 받으면, 세 가지가 어긋나 있습니다 — 1쪽과 2쪽의 필드명이 다르고, 같은 시설이 중복으로 들어오고, 좌표가 빈 행이 섞여 있습니다. 그대로 지도·통계에 넣으면 결측과 중복이 조용히 들어갑니다. 이 안내서는 그걸 검산 가능한 CSV로 바꿉니다.

세 가지 함정

• 필드명 차이 — 1쪽은 facilityId(camelCase), 2쪽은 facility_id(snake_case)
• 페이지 중복 — 같은 WF-006이 1쪽과 2쪽에 모두
• 좌표 결측 — 어떤 행은 latitude, longitude가 빈 문자열

필드명 맞추기

여러 표기를 하나의 표준 컬럼으로 모읍니다. 새 API에서 필드명이 다르면 이 표에 원본 이름만 추가하면 됩니다.

FIELD_ALIASES = {
    "facility_id": ["facilityId", "facility_id", "FCLTY_ID"],
    "facility_type": ["facilityType", "type", "FCLTY_TY"],
    "sido": ["ctprvnNm", "sido", "CTPRVN_NM"],
    "sigungu": ["signguNm", "sigungu", "SIGNGU_NM"],
    "lat": ["lat", "latitude", "LAT"],
    "lon": ["lon", "longitude", "LOT"],
}

검산 — totalCount = 고유 시설 ID

핵심 검산은 두 가지입니다: 페이지마다 적힌 totalCount가 서로 같은지, 그리고 그 수가 중복 제거 후 고유 시설 수와 같은지.

metric,value
declared_total_count,12
downloaded_rows,13
unique_facility_id,12
valid_rows_with_coordinates,11
review_rows,3
total_count_consistent,True

선언 총건수 12 = 고유 ID 12이면 통과(OK), 다르면 경고(WARN)입니다. 위 예에서 다운로드는 13행이지만(중복 1건 포함) 고유 ID는 12, 좌표가 있는 유효 행은 11, 검토 대상은 3행입니다.

[OK] totalCount 12건, 다운로드 13행, 고유 시설 12건
[OK] 좌표 포함 정리 11건, 검토 필요 3행
[OK] 저장: output/normalized_facilities.csv, output/review_items.csv, output/summary.csv

검산이 보장하는 것과 아닌 것

내 업무에 적용하기

1. 실제 API 응답은 공개 저장소에 올리지 않고 로컬 data/에만 저장합니다.
2. 합성 JSON으로 먼저 돌려 산출 파일을 확인합니다.
3. 실제 API 문서에서 ID·유형·지역·좌표·기준연도 필드명을 확인합니다.
4. 필드명이 다르면 FIELD_ALIASES에 원본 필드명을 추가합니다.
5. summary.csv에서 totalCount·다운로드 행·고유 ID 일치를 확인합니다.
6. review_items.csv가 비어 있지 않으면 지도화·보고 반영을 중단하고 원문을 확인합니다.