지도(Map)

맵차트에서 표시될 지도 데이터 소스를 반드시 적어도 하나는 설정해야 한다. RealMap은 지도 데이터는 두가지 포맷의 지도 데이터를 읽어서 지도를 구성한다.

지도 데이터 설정

const config = {
    map: [
        {
            url: 'https://unpkg.com/realmap-collection/kr-sido-low.geo.json',
            padding: '0.8 0 0 0',
        },
        // 다른 정보가 없으면 경로 문자열을 바로 설정할 수 있다.
        'https://unpkg.com/realmap-collection/kr-sido-low.geo.json'
    ],
};

맵차트의 축은 지도에 설정된 위/경도 정보를 기준으로 설정된다. 또한, 맵에는 도형셋으로 구성된 영역 정보들이 포함되어 있다. 맵 시리즈는 이 정보를 이용해 영역들을 표시한다.
RealMap 라이브러리는 응용 app에서 사용할 수 있는 맵소스 컬렉션을 제공한다. npm 모듈에 포함된 local 파일로 직접 포함시키거나, CDN 저장소의 원격 url을 포함시킬 수 있다.

const config = {
    map: `https://unpkg.com/realmap-collection/world-low.topo.json`,
};

지도 데이터 다운로드

RealMap Collection (opens in a new tab)은 맵차트 개발을 위해 필요한 지도 데이터를 모아둔 NPM 패키지이다.
아래와 같은 지도를 제공한다.

• 국가별 세계지도(world)
• 대륙별 세계지도(continent)
• 대한민국 지도
  • 시도(kr-sido)
  • 시군구(kr-sigun)
  • 읍면동(kr-dong)
• 한반도 지도(korea)
• 미국 주(state)별 지도(usa-state)
• 일본 도도부현 지도(japan-adm1)
• 중국 성(省)별 지도(china-adm1)

각 지도가 어떤 지역을 어떤 아이디로 제공하는지는 지역 아이디(Region ID)에서 지도별로 확인할 수 있다.

지도 파일은 깃허브 레파지토리를 통해 제공된다.
github.com/realgrid/realmap-collection-dist (opens in a new tab) 지도의 해상도에 따라 3개의 파일이 제공된다. 각각 high, mid, low이다.
해상도가 낮을 수록 지도의 세밀함이 떨어지지만 용량이 감소하므로 상황에 맞게 사용하면 된다.
또한 각 지도는 geo.json과 topo.json 버전이 제공된다.
일반적인 경우 geo.json을 사용하면 된다.

지도 파일의 이름 규칙은 아래와 같다.

{지도_이름}-{해상도}.{geo | topo}.json                 // 기존 지도
{YYYY-MM}/{지도_이름}-{해상도}.{geo | topo}.json       // 행정구역 개편 반영본

개편 시점 경로({YYYY-MM}/)에 대해서는 아래 행정구역 개편 지도를 참고한다.

예시

국가별 세계지도는 아래와 같이 총 6개의 파일이 제공된다.
world-high.geo.json
world-mid.geo.json
world-low.geo.json
world-high.topo.json
world-mid.topo.json
world-low.topo.json

행정구역 개편 지도

행정구역이 개편되어도 기존 경로의 지도는 개편 전 상태로 그대로 유지된다. 개편이 반영된 지도는 기존 경로를 덮어쓰지 않고, 경로 앞에 개편 시점({YYYY-MM}/)을 붙인 별도 경로로 제공된다. 앞으로의 개편도 동일하게 해당 시점의 {YYYY-MM}/ 경로로 제공된다.

현재 제공되는 개편 지도는 아래와 같다.

• 2026-07 : 광주광역시와 전라남도가 전남광주통합특별시로 통합된 것을 반영. 시도(kr-sido)·시군구(kr-sigun) 지도를 제공한다.
  • 인천광역시의 변경된 행정구역은 추후 반영 예정이다.

사용법은 아래에서 설명하는 세 가지 방식(NPM 정적 import, NPM 동적 import, CDN)과 동일하며, 지도 이름 앞에 2026-07/만 붙이면 된다.

// NPM 정적 import
import krSido from 'realmap-collection/2026-07/kr-sido-low.geo.json';
 
// NPM 동적 import
const krSido = await import('realmap-collection/2026-07/kr-sido-low.geo.json')
    .then((m) => m.default);
 
// CDN
// https://unpkg.com/realmap-collection/2026-07/kr-sido-low.geo.json

그 외에도 NPM을 통해 사용하거나 CDN으로 사용할 수 있다.

NPM으로 지도 데이터를 사용하는 경우

• 아래의 명령어로 npm을 통해 지도 데이터 모듈을 설치한다.

npm install realmap-collection

• 아래와 같이 지도 데이터를 import하여 사용할 수 있다.
• 이렇게 정적으로 import한 지도는 앱이 시작될 때 함께 로드되므로 초기 번들에 포함된다.

import 'realmap/dist/realmap-style.css';
import { createChartAsync } from 'realmap';
 
// -> 아래와 같이 지도 데이터 import
import map from 'realmap-collection/world-high.geo.json';
 
createChartAsync(document, 'map', {
    map: [ 
        { 
            source: map
        }
     ],
});

• 지도를 필요한 시점에 불러오려면 동적 import를 사용한다.
• 이 경우 지도는 초기 번들에서 빠지고 별도 청크로 분리되어, 실제로 불러올 때 받아온다.

const map = await import('realmap-collection/kr-dong-low.geo.json').then((m) => m.default);

• TopoJSON이 필요하면 확장자를 .topo.json으로 바꾼다.

// 지금까지 (deprecated)
const map = await loadMap(MapNamesEnum.krDongLow, 'geojson');
 
// 대체
const map = await import('realmap-collection/kr-dong-low.geo.json').then((m) => m.default);

CDN으로 지도 데이터를 사용하는 경우

• 아래와 같이 URL을 작성하여 요청하면 된다

https://unpkg.com/realmap-collection/{{지도 이름}}
ex) https://unpkg.com/realmap-collection/world-high.geo.json

지도 데이터의 출처와 라이선스

RealMap Collection의 지도는 공개 데이터를 가공하여 제작되었다. 지도별 원본 데이터와 라이선스는 법적 고지 페이지에서 확인할 수 있다. 대한민국 지도는 공공누리 제1유형(출처 표시) 데이터를 가공한 것이라 상업 서비스에서도 자유롭게 사용할 수 있다. 출처 정보는 각 지도 파일의 meta.license 필드에도 포함되어 있다.

다만 공공누리의 출처 표시 의무는 지도를 사용하는 서비스에도 적용된다. 서비스의 법적 고지 페이지 등 사용자가 확인할 수 있는 곳에 아래 문구를 포함하거나, 크레딧(Credits) 기능으로 차트에 출처를 표시하는 것을 권장한다.

본 서비스의 대한민국 지도는 통계청 통계지리정보서비스(SGIS)에서 공공누리 제1유형으로 개방한 행정구역경계 데이터를 가공하여 제작되었습니다.

See Also

• 시리즈 개요
• 스타일 개요
• 차트 Configuration