대한민국 행정구역 지도 (시도 · 시군구 · 읍면동)

웹에서든 Claude Code·Codex에서든 유용하게 쓰셨다면 GitHub Star로 응원해 주세요 ⭐. 다음 개선을 이어가는 데 큰 힘이 됩니다.

최근 업데이트 · 2026-10-19

• 지도 편집 패널·확대 축소: 지역·모양 탭을 ‘지도 편집’으로 합쳐 지역 검색 바로 아래에서 색과 이름을 꾸밉니다. 지역 선택 시 대상 중심으로 확대하며, +/−·선택 지역 맞춤·전체 맞춤·Ctrl/⌘+휠로 화면 배율을 바꿉니다. 화면 확대는 내보내기 구성에 영향을 주지 않으며, 확대한 상태에서도 지역 이동과 경계 붙이기를 지원합니다.
• 지도 표시 설정 통합: 지도 위에서 ‘배경 지역·시도 경계 강조·지역 이름·자동 붙이기’를 함께 조작합니다. 왼쪽 지역·모양 탭에 흩어져 있던 중복 설정을 정리했고, 직접 고르기도 같은 배경 스위치를 사용합니다. 비교·보고서의 세부 도구는 기본적으로 접어 둡니다.
• 바깥 회색 면·선 숨기기 수정: ‘나머지 지역도 흐리게 보이기’를 끄면 바깥 배경과 시도 윤곽선을 함께 숨겨 선택 지역과 주변 지역만 남깁니다. 표시된 지역 사이 경계는 유지하며, 직접 고르기의 ‘나머지 숨기기’와 SVG·PNG·PPTX 저장에도 적용합니다.
• 이름·지시점·연결선 동반 이동: 지역을 끄는 중에도 이름과 지시점·선이 함께 움직이며, 놓으면 새 배치에 맞게 연결선을 다시 계산합니다. 경계 붙이기 추가 검사 6개를 포함해 자동 검사 총 30개를 제공합니다.
• 도·시·군·구·읍·면·동 경계 자동 붙이기: ‘하나씩 꾸미기’에서 지역을 원래 이웃 경계에 맞는 위치의 12px 안으로 끌면 정확히 붙습니다. 실제 지도·벌려 놓기 지원, 이미 옮긴 이웃에도 맞춥니다. Alt/Option을 누르면 자유 이동하며 타일 지도에는 적용하지 않습니다. 붙인 배치는 작업 파일·SVG·PNG·PPTX에 반영됩니다.
• 비교·보고서 기능 9종 추가: 고정 색 구간, 지역명 연결·CSV 양식, 전후·증감 비교, 설명 상자·화살표·반경 원, 보고서·내 서식, 엑셀 직접 읽기, 자료 없음·0·제외 구분, 연도 슬라이더, 독립형 HTML 저장. 사용법과 설정 예시
• 추가 검증: 기존 17개와 추가 기능 7개, 총 24개 자동 검사 통과. 브라우저에서 엑셀 읽기·비교·연도 전환·지역 연결·보고서·PPTX 저장·작업 복원을 확인했고, HTML은 오프라인으로 열어 확인했습니다.
• 중복 합산 수정: 상위 지역 합계와 하위 지역 값이 함께 있는 표에서 같은 값을 두 번 더하지 않습니다.
• 행정기관코드 인식 수정: 지역 이름 없이 코드와 값만 있는 표도 읽습니다.
• 묶음 저장 경고 보완: 웹·명령줄·MCP에서 여러 장을 만들 때, 같은 이름이 여러 곳에 있거나 찾지 못한 지역을 장별로 알려 줍니다.
• PNG 투명 배경 수정: 명령줄·MCP의 한 장·묶음 PNG 저장에서 투명 배경 설정을 반영합니다.
• 보안·검증: 의존성 보안 업데이트, 자동 검사 17개 통과(Node 20·22·24). 업데이트 당시 npm audit 경고 0개를 확인했습니다.

웹 도구 바로 사용 · 기존 웹 화면은 새로고침해 주세요. 로컬 명령줄·MCP는 저장소에서 git pull 후 npm install로 업데이트합니다.

보고서와 PPT에 넣을 대한민국 지도를 만드는 도구입니다. 지역을 고르면 주변 시군과 함께 그리고, 인구 통계나 여론조사 표로 색을 칠하고, 주소로 핀을 찍어 SVG · PNG · PPTX 로 저장합니다.
브라우저에서 눌러 만들 수도 있고, 명령줄이나 Claude Code · Codex 에게 말로 시켜서 만들 수도 있습니다.

주변 지역 + 기본 통계	전국 시군구	육각 타일 지도

_{위 그림은 모두 node tools/krmap.mjs render ... 한 줄로 만들었습니다 (명령).}

할 수 있는 것

• 주변 지역 지도: 대전광역시를 고르면 둘러싼 세종 · 청주 · 보은 · 옥천 · 금산 · 논산 · 계룡 · 공주를 함께 그립니다. 맞닿은 곳만, 또는 두 겹까지.
• 원하는 지역만 골라 한 장으로: 시도 / 시군구 / 읍면동 단위를 정하고 지역을 넣고 뺍니다. 고르지 않은 곳은 흐리게 두거나 아예 뺍니다.
• 지도 모양: 실제 지도, 지역끼리 벌려 놓기, 네모 · 육각 타일 지도, 지역 하나씩 색 · 이름 · 위치 바꾸기.
• 지역 이름: 모두 넣기 / 모두 빼기 / 고른 것만. 지역 안에 안 들어가는 이름은 밖으로 빼서 지시선으로 잇고, 원하면 이름을 모두 지도 양옆 줄에 세웁니다(인포그래픽식).
• 원 크기(버블) 지도: 인구 · 매출 · 지점 수처럼 개수인 값은 원 넓이로 나타냅니다.
• 확대 상자: 전국 시군구 지도에서 서울 · 부산 · 대구 · 인천 · 광주 · 대전 · 울산을 옆에 크게 그립니다.
• 슬라이드 여러 장: "시도마다 한 장", "충남 시군마다 한 장"처럼 여러 지도를 PPTX 하나로 만듭니다.
• 색 하나로 색 조합: 기준 색 하나(또는 "추천 조합")로 대상 · 주변 · 바탕 · 글자색과 데이터 색 단계를 맞춰 만듭니다.
• 디자인 방식: 기본 · 유리(글라스모피즘) · 입체 · 소프트(뉴모피즘) · 네온. PPTX 에도 그대로 들어갑니다.
• 통계 MCP 와 함께: KOSIS 같은 통계 MCP 가 준 지역별 값을 그대로 받아 지도로 (아래).
• 기본 통계 내장: 행정안전부 주민등록 인구통계(2026년 7월말)의 시도 · 시군구별 인구, 세대, 연령대, 청년 · 고령 비율, 1년 증감을 바로 골라 칠합니다.
• 내 표로 색칠: 엑셀에서 복사한 표나 CSV 를 넣으면 값 · 비율 · 여론조사 1위로 칠하고 범례와 값을 붙입니다.
• 지점 핀: 이름 · 주소(또는 위도 · 경도) 목록을 넣으면 핀을 찍고, 분류별 색이나 지역별 지점 수로 칠합니다.
• 제목 · 부제 · 범례 · 출처를 그림 안에 넣습니다.
• PPTX 는 지역 하나가 도형 하나라 PowerPoint 에서 색을 바로 바꿀 수 있습니다.
• 경계는 2026.10.01 기준 (시도 16 · 시군구 256 · 읍면동 3,559). 2026.7.1. 출범한 전남광주통합특별시를 반영했고, 광주 · 전남을 나눈 17개 시도로도 볼 수 있습니다.

어떻게 쓰나

1. 웹 도구

https://worlyung.github.io/krmap/ 에서 바로 씁니다. 받아서 쓰려면 web/index.html 을 브라우저로 열면 됩니다. 설치도 서버도 필요 없습니다.
지도는 모두 브라우저 안에서 그려지고, 넣은 표나 주소는 어디에도 올라가지 않습니다(주소 검색만 OpenStreetMap 에 물어봅니다).
왼쪽에서 설정하면 오른쪽 미리보기가 바로 바뀌고, 위의 버튼으로 SVG · PNG · PPTX 를 저장합니다. 그림 비율(자동 · 16:9 · 4:3 · 1:1)은 미리보기 위에서 고릅니다.

설정판은 네 탭입니다.

그 밖에

• 지역 찾기: 대전, 유성구, 정자동처럼 일부만 써도 찾습니다. "중구"처럼 여러 곳인 이름은 "대전 중구"로.
• 지도 클릭: 누른 지역이 새 대상이 됩니다(주변 지역 보기). 영역 직접 고르기에서는 넣고 뺍니다.
• 하나씩 꾸미기: 지역을 눌러 그 지역만 색 · 이름을 바꾸거나 숨기고, 끌어서 옮깁니다.
• 작업 관리: 되돌리기(Ctrl+Z) · 다시 하기(Ctrl+Shift+Z), 브라우저 자동 저장, 작업 파일(.json) 저장 · 불러오기, 이미지 복사(PPT 에 바로 붙여넣기).
• 목록 복사: "대전광역시 주변 8곳: 세종시(세종), 청주시(충북), …"
• 확대 상자: 지역 탭 → 전국 → 시군구일 때 "확대 상자"에서 서울 · 부산 … 을 고릅니다.
• PPT 슬라이드 묶음: 미리보기 아래에서 "지금 지도 담기", "시도마다 한 장씩", "이 시도의 시군구마다"로 담고 "묶음 PPTX 저장"을 누르면 한 파일에 여러 장이 들어갑니다. 제목에 {지역} 을 쓰면 장마다 그 지역 이름으로 바뀝니다. 담은 장을 누르면 편집기로 불러옵니다.

데이터로 색칠

기본 통계 — 데이터 탭에서 "기본 통계"를 고르면 지표를 바로 고릅니다(시도 · 시군구 단위).

원본이 10세 단위라 법정 청년(19~34세) · 노인(65세 이상)은 만들 수 없어 실제 연령 구간으로 이름을 붙였습니다.
법정 기준이 필요하면 아래 "행정안전부 연령별 인구 파일"을 넣으세요.

내 표 — 엑셀에서 복사해 붙여넣거나 CSV 를 엽니다. 첫 열은 지역 이름이나 행정기관코드.

• 지도보다 잘게 나뉜 표(읍면동 숫자로 시군구 지도)는 더해서 맞춥니다. 상위 지역 합계와 그 안의 하위 지역 값이 함께 있으면 상위 합계를 우선해 중복을 피합니다. EUC-KR 파일도 읽습니다.
• 단계와 범례는 지금 지도에 보이는 지역만으로 정합니다.
• 표에서 지도에 못 맞춘 이름, 여러 곳인 이름은 따로 알려 줍니다.

지점 핀 — 이름 ⇥ 주소 ⇥ 분류 또는 이름 ⇥ 위도, 경도 줄을 붙여넣습니다.
위도 · 경도는 정확한 자리에, 주소는 인터넷 주소 검색(OpenStreetMap)으로 찾습니다. 검색이 막힌 곳(claude.ai 화면 등)에서는 주소 속 동 · 시군구의 가운데에 대략 찍고, 어떻게 찾았는지 목록에 표시합니다.

PPT 에서 쓰는 법

• PPTX (추천): 16:9 슬라이드 한 장(묶음이면 여러 장). 지역마다 이름 붙은 도형이라 선택 창(Alt+F10)에서 골라 색을 바꾸거나 지웁니다. 원 크기 지도의 원은 PowerPoint 원 도형입니다. 출처는 오른쪽 아래에 자동으로 들어갑니다.
• SVG: PowerPoint 2019 / Microsoft 365 에서 삽입 → 그림으로 넣고 마우스 오른쪽 → 도형으로 변환하면 지역별 도형으로 풀립니다.
• PNG: 4000px 안팎 고해상도, 기본 투명 배경(흰 바탕 옵션).

2. 미리 만든 SVG

웹 도구를 열지 않아도 쓸 수 있게 svg/ 에 521장을 만들어 두었습니다.

지역 <path> 에는 id="대전광역시_유성구" 처럼 이름이 붙어 있고, 그룹은 배경 / 주변 / 대상 / 대상_내부 / 시도경계 / 지명 으로 나뉩니다.

3. 자동화: 명령줄 · Claude Code · Codex

웹 도구와 같은 그리기 코드를 Node 에서 돌립니다. 설정(JSON) 하나가 지도 한 장이라, 같은 형식의 지도를 여러 장 만들거나 에이전트에게 맡기기 좋습니다.

npm install          # Node 20 이상, 처음 한 번
npm test             # 17개 확인 (인터넷 필요 없음)

명령줄 krmap

# 대전과 주변 시군, 60세 이상 비율로 칠하고 인구를 이름 아래에
node tools/krmap.mjs render --region 대전광역시 --stat "60세 이상 비율" --stat-labels pop \
  --title "대전 주변 고령 인구" --source

# 충남 시군구 육각 타일 + 여론조사 표
node tools/krmap.mjs render --regions 충청남도 --unit 시군구 --layout 육각 --data 여론조사.csv --poll --format pptx

# 설정 파일로 (웹 도구에서 "작업 저장"한 파일도 됨)
node tools/krmap.mjs render spec.json --format png,pptx --out out/보고서

# 지역 안에 안 들어가는 이름은 지시선으로 (기본). 이름을 모두 양옆 줄로: --labels side
node tools/krmap.mjs render --national 시도 --stat yoyR --stat-labels yoyR --palette diverge --labels side

# 색 하나로 색 조합, 디자인 방식
node tools/krmap.mjs render --region 대전광역시 --stat old60R --base-color "#13A07F" --look 유리

# 원 크기 지도 · 확대 상자
node tools/krmap.mjs render --region 대전광역시 --stat pop --bubbles
node tools/krmap.mjs render --national 시군구 --insets all --stat old60R --aspect 16:9

# 여러 장을 PPTX 하나로: 시도마다 / 충남 시군마다
node tools/krmap.mjs render --each 시도 --stat old60R --title "{지역} 고령 인구"
node tools/krmap.mjs render --each 충청남도 --each-unit 시군구 --inner 읍면동 --title "{지역} 읍면동"

# 지도 없이 값만
node tools/krmap.mjs find 중구                                    # 같은 이름이 어디어디 있는지
node tools/krmap.mjs neighbors 대전광역시 --unit 시군구
node tools/krmap.mjs indicators                                   # 기본 통계 지표 목록
node tools/krmap.mjs stats --in 경기도 --unit 시군구 --indicators pop,old60R

• 파일은 기본으로 out/ 에 저장됩니다(git 에 올라가지 않음). 모든 명령에 --json 을 붙이면 결과가 JSON 입니다.
• 전체 옵션은 node tools/krmap.mjs help. npm link 를 하면 krmap 으로 바로 부릅니다.
• 글꼴은 프리텐다드(Pretendard)입니다. PNG 는 npm install 로 함께 받는 프리텐다드로 그려서 어느 컴퓨터에서 만들어도 같고, 다른 글꼴을 쓰려면 --font 글꼴.ttf.

설정(spec) 예:

{
  "region": "대전광역시",
  "stat": "60세 이상 비율",
  "statLabels": ["pop"],
  "theme": "코랄",
  "title": "대전과 주변 시군의 고령 인구",
  "source": true,
  "formats": ["pptx", "png"],
  "out": "out/대전_고령.pptx"
}

칸 전부(지도 방식, 모양, 데이터, 그룹, 핀 …)는 docs/automation.md 에 있습니다.

통계 MCP 와 함께

통계청 KOSIS 를 읽는 MCP 서버(예: Korean Stats MCP)를 함께 붙이면 "서울 자치구별 1인 가구 비율 지도 만들어줘"처럼 숫자 찾기부터 지도까지 한 번에 됩니다.
통계 MCP 가 준 결과를 data.rows 로 그대로 넘기고 표 ID 는 source 에 적습니다. 붙이는 법과 예시는 docs/automation.md.

Claude Code

이 폴더에서 Claude Code 를 열고 말로 시키면 됩니다.

대전이랑 주변 시군 고령 인구 지도 PPT 로 만들어줘
이 여론조사 표로 충남 시군 육각 타일 지도 그려줘

korea-map 스킬(.claude/skills/korea-map/)이 지역 이름 확인 → 지표 고르기 → 지도 만들기 → 결과 확인 순서를 알려 주고,
.mcp.json 에 적힌 MCP 서버가 처음 열 때 쓸지 묻습니다. 다른 폴더에서도 쓰려면:

claude mcp add korea-map --scope user -- node /절대/경로/tools/mcp-server.mjs

Codex

저장소 안에서는 AGENTS.md 를 읽고 명령줄을 바로 씁니다. MCP 로 붙이려면 ~/.codex/config.toml:

[mcp_servers.korea-map]
command = "node"
args = ["/절대/경로/tools/mcp-server.mjs"]

MCP 서버

명령줄과 같은 엔진 위의 얇은 층입니다. 명령줄만으로도 충분하지만, MCP 로 붙이면

• render_map 이 미리보기 그림을 결과에 함께 돌려줘서 에이전트가 지도를 보고 스스로 고칩니다.
• 이 저장소 밖에서 작업할 때나, 명령을 실행할 수 없는 클라이언트에서도 씁니다.

예시 그림 다시 만들기

맨 위 그림 세 장은 이렇게 만들었습니다.

K="node tools/krmap.mjs render --format png --width 1000 --png-scale 1 --background --aspect 4:3"
$K --out docs/images/around.png --region 대전광역시 --stat old60R --stat-labels old60R --title "대전과 주변 시군" --subtitle "60세 이상 인구 비율" --source --theme 코랄
$K --out docs/images/national.png --national 시군구 --stat youngR --labels none --title "전국 시군구 20~39세 비율" --source
$K --out docs/images/tiles.png --regions 경기도 --unit 시군구 --layout 육각 --stat yoyR --palette diverge --title "경기도 시군 1년 인구 증감률"

4. 데이터 다시 만들기

경계 — 행정구역이 바뀌면 최신 경계로 다시 만듭니다.

pip install -r scripts/requirements.txt
python scripts/build_data.py            # 최신 시점 (특정 시점: python scripts/build_data.py 20261001)
node scripts/export_svgs.js             # svg/ 다시 만들기 (특정 지역만: node scripts/export_svgs.js 대전)

• build_data.py 는 경계를 받아 web/data/base.js(시도 · 시군구), web/data/emd.js(읍면동)로 저장하고,
  모든 단위 조합(시도 ↔ 시군구 ↔ 읍면동)의 인접 관계를 미리 계산합니다. 50m 이내로 맞닿으면 이웃입니다.
  바다 건너 섬(제주, 울릉 등)은 맞닿은 지역이 없습니다.
  전남광주통합특별시가 있는 시점이면 광주(29) · 전남(46)으로 나눈 경계와 인접표도 함께 만듭니다.
• 좌표는 EPSG:5179(UTM-K)를 10m 격자로 옮긴 값이라 지도가 위아래로 눌리지 않습니다.

기본 통계 — data/mois/ 의 행정안전부 월간 CSV(연령별인구현황, 주민등록인구및세대현황)에서 만듭니다.
새 달 파일을 주민등록 인구통계에서 받아 넣고 python scripts/build_stats.py 를 돌리면 web/data/stats.js 가 바뀝니다.

타일 배치 — 그릴 지역들의 실제 경계 안에 격자 칸을 깔고(칸 수가 지역 수보다 조금 많아지는 가장 큰 칸), 헝가리안 할당으로 지역마다 실제 위치에서 가장 가까운 칸을 줍니다(R geogrid 와 같은 방식). 전국 시도 타일만 알아보기 쉬운 고정 배치를 씁니다.

폴더

web/                 웹 도구 (index.html) 와 그리기 엔진
  render.js            경계 → 장면 → SVG (브라우저 · Node 공용)
  datafill.js          표 읽기 · 색칠
  pins.js              주소 · 좌표 → 지도 위치
  state.js             설정 → 그리기 옵션 (웹 · 명령줄 · MCP 공용)
  pptx.js              장면 → PowerPoint 도형
  app.js               웹 화면
  data/                경계 · 인접표 · 기본 통계 (scripts/ 가 만듦)
tools/               krmap 명령줄, MCP 서버, 테스트
svg/                 미리 만든 SVG 521장
scripts/             경계 · 통계 · SVG 만들기
data/mois/           행정안전부 인구통계 원본 CSV
docs/                자동화 설명서, README 그림
.github/             테스트(GitHub Actions) · 이슈 · PR 양식
.claude/skills/      Claude Code 스킬
AGENTS.md            Codex 등 에이전트 안내

함께 만들기

버그 제보 · 기능 제안 · 풀 리퀘스트를 반깁니다. CONTRIBUTING.md 를 먼저 봐 주세요.

출처 · 라이선스

• 코드: MIT. 데이터 · 글꼴 · 외부 파일은 각자의 라이선스를 따릅니다 — 전체 목록은 NOTICE.md.
• 경계: 통계청 SGIS 행정구역 경계 (공공누리 제1유형, 출처표시) — vuski/admdongkor 가공본(CC BY 4.0)을 단순화해서 썼습니다.
  발표 자료에는 "출처: 통계청 SGIS 행정구역 경계(2026.10.01)" 정도로 표시해 주세요. PPTX 에는 자동으로 들어갑니다.
• 인구 통계: 행정안전부 주민등록 인구통계(2026년 7월말, 거주자 기준). 원본 CSV 는 SimpleisNice/korea-population-dashboard 에 공개된 사본을 썼습니다.
• 주소 검색: © OpenStreetMap 기여자 (Nominatim).
• web/vendor/pptxgen.bundle.js: PptxGenJS 4.0.1 (MIT).
• 글꼴: Pretendard 1.3.9 (SIL OFL 1.1, web/vendor/fonts/).
• 단순화한 경계라 실제와 수십 m 차이가 날 수 있습니다. 측량 · 법적 용도로는 쓰지 마세요.

English

Korea admin map makes maps of South Korea's administrative divisions (17 provinces · 250+ municipalities · 3,500+ neighbourhoods, boundaries as of 2026-10-01) as SVG, PNG and editable PPTX for reports and slides.
Pick a region and its neighbours, colour it with the built-in population statistics or your own table (polls, sales, any CSV), drop pins by address, and export.

• Web tool: use it at https://worlyung.github.io/krmap/, or open web/index.html in a browser — no install, no server.
• CLI: npm install, then node tools/krmap.mjs render --region 대전광역시 --stat old60R.
• MCP server for Claude Code / Codex: tools/mcp-server.mjs (.mcp.json included). Pair it with a KOSIS statistics MCP to go from "map the share of one-person households by Seoul district" to a finished slide.
• Leader-line callouts, side label columns, bubble maps, metro insets, multi-slide decks, one-colour palettes (OKLCH) and looks (glass, paper, soft, neon).

Code is MIT. Boundary data: Statistics Korea SGIS (KOGL Type 1) via vuski/admdongkor (CC BY 4.0); population data: Ministry of the Interior and Safety (KOGL Type 1). See NOTICE.md.