MapGlot 개발자 문서
지도를 사이트에 넣고, 검색·길찾기 API를 호출하는 모든 방법 — 5분이면 충분합니다. / Embed the map and call our APIs in 5 minutes.
1. 지도 임베드 (HTML 한 페이지)
오픈소스 MapLibre GL JS와 무료 벡터 타일로 지도를 띄웁니다. API 키 없이 동작하며, 검색·길찾기 API를 쓸 때만 키가 필요합니다.
<link href="https://unpkg.com/maplibre-gl@4.7.1/dist/maplibre-gl.css" rel="stylesheet">
<div id="map" style="width:100%;height:480px"></div>
<script src="https://unpkg.com/maplibre-gl@4.7.1/dist/maplibre-gl.js"></script>
<script>
const map = new maplibregl.Map({
container: 'map',
style: 'https://tiles.openfreemap.org/styles/liberty', // bright | positron 도 가능
center: [126.978, 37.5665],
zoom: 11,
});
</script>
⚠️ 출처표기 의무 — 지도 화면에 © OpenStreetMap contributors 표기가 항상 보여야 합니다 (위 코드는 자동 포함). 타일은 현재 OpenFreeMap 공익 CDN이 제공하며, 대량 트래픽 고객에게는 전용 타일 호스팅을 컨설팅해 드립니다(Business).
지도 라벨 언어 바꾸기 (12개 언어)
function setMapLanguage(map, lang) { // lang: 'ko','en','ja','zh','es','fr','de','ru','ar','pt','hi'...
for (const layer of map.getStyle().layers) {
if (layer.type !== 'symbol') continue;
map.setLayoutProperty(layer.id, 'text-field',
['coalesce', ['get', 'name:' + lang], ['get', 'name'], ['get', 'name:en']]);
}
}
map.on('load', () => setMapLanguage(map, (navigator.language || 'en').slice(0, 2))); // 방문자 언어 자동 감지
아랍어·히브리어 사용자에게 서비스한다면 RTL 플러그인 한 줄을 추가하세요 — 없으면 글자가 끊어져 보입니다 (필요할 때만 지연 로드되어 다른 사용자에겐 비용 0):
maplibregl.setRTLTextPlugin('https://unpkg.com/@mapbox/mapbox-gl-rtl-text@0.2.3/mapbox-gl-rtl-text.min.js', true);
성능 레시피 — 60fps 부드러운 지도 (권장 설정)
저희 라이브 데모가 빠른 이유를 그대로 가져가세요. 지도 생성 전후에 아래 설정을 추가하면 빠른 패닝·줌에서 프레임 드랍 없이 동작합니다 (실측: 3단계 줌 중 60fps).
// 지도 생성 "전" — 타일 파싱 워커를 코어 수에 맞춤 (기본 2개)
maplibregl.setWorkerCount(Math.min((navigator.hardwareConcurrency || 4) - 1, 6));
const map = new maplibregl.Map({
container: 'map',
style: 'https://tiles.openfreemap.org/styles/liberty',
center: [126.978, 37.5665], zoom: 11,
fadeDuration: 0, // 라벨 페이드 제거 — 즉답감의 핵심
maxTileCacheSize: 2048, // 줌 왕복 시 재다운로드 제거
refreshExpiredTiles: false,
pixelRatio: Math.min(devicePixelRatio || 1, 2), // 3x 폰 GPU 부하 절반
});
map.scrollZoom.setWheelZoomRate(1 / 300); // 휠 줌 반응 가속
💡 재방문 가속까지 원하면 서비스 워커로 타일을 cache-first 캐싱하세요 — 저희 데모(/map)의 sw.js 소스가 레퍼런스입니다.
지도 이미지 내보내기 — 출처표기 자동 포함
현재 화면을 PNG로 저장하는 기능입니다. 라이선스 의무인 출처표기를 이미지에 자동으로 새겨 사용자가 어디에 쓰든 합법이 됩니다. (WebGL 버퍼는 합성 후 비워지므로 반드시 render 콜백 안에서 복사해야 합니다.)
function exportMapImage(map, fileName = 'map.png') {
map.once('render', () => {
const src = map.getCanvas();
const cv = document.createElement('canvas');
cv.width = src.width; cv.height = src.height;
const ctx = cv.getContext('2d');
ctx.drawImage(src, 0, 0);
const fs = Math.max(12, Math.round(cv.width / 90)); // 출처표기 합성 (ODbL 의무)
ctx.font = fs + 'px sans-serif';
const text = '© OpenStreetMap contributors';
const tw = ctx.measureText(text).width;
ctx.fillStyle = 'rgba(255,255,255,.85)';
ctx.fillRect(cv.width - tw - fs * 1.6, cv.height - fs * 2.1, tw + fs * 1.6, fs * 2.1);
ctx.fillStyle = '#333';
ctx.fillText(text, cv.width - tw - fs * 0.8, cv.height - fs * 0.75);
cv.toBlob(b => {
const a = document.createElement('a');
a.href = URL.createObjectURL(b); a.download = fileName; a.click();
});
});
map.triggerRepaint();
}
💡 인쇄용 고해상도가 필요하면 화면 밖 컨테이너에 pixelRatio: 3으로 임시 지도를 만들어 같은 방식으로 캡처하세요 — 저희 데모의 📷 이미지 버튼이 레퍼런스 구현입니다.
2. API 호출
무료 가입하면 키가 즉시 발급됩니다. 모든 API는 ?key=YOUR_KEY 파라미터를 받습니다.
장소 검색 (geocode)
GET https://mapglot.com/api/v1/geocode?q=Seoul Station&lang=en&key=YOUR_KEY
[{ "lat": "37.553", "lon": "126.969", "display_name": "Seoul Station, …", "boundingbox": [...] }]
좌표 → 주소 (reverse)
GET https://mapglot.com/api/v1/reverse?lat=37.5665&lon=126.978&lang=ko&key=YOUR_KEY
길찾기 (route)
GET https://mapglot.com/api/v1/route?profile=driving&from=126.97,37.56&to=129.04,35.11&key=YOUR_KEY
# profile: driving | cycling | walking, 좌표는 lon,lat 순서
{ "routes": [{ "distance": 396000, "duration": 17448,
"geometry": { "type": "LineString", "coordinates": [...] } }] }
응답의 geometry는 GeoJSON — MapLibre 소스에 그대로 넣어 경로선을 그릴 수 있습니다:
map.addSource('route', { type: 'geojson', data: { type: 'Feature', geometry: r.routes[0].geometry } });
map.addLayer({ id: 'route', type: 'line', source: 'route',
paint: { 'line-color': '#1d9e75', 'line-width': 5 } });
3. 키 · 한도 · 오류
| 항목 | 내용 |
|---|
| 키 기능 선택 | 발급 시 검색/주소변환/길찾기를 개별 on/off — 꺼진 기능 호출은 401과 함께 활성 기능 목록 안내 |
| 도메인 잠금 🔒 | 키 발급 시 허용 도메인 지정(example.com, *.example.com) — 브라우저 공개 키가 유출돼도 다른 사이트에선 무용지물. 서버에서 쓰는 키는 비워두세요 |
| 일일 한도 | Free 1만 / Pro 10만 / Business 100만 — 계정 기준 합산(키 여러 개를 만들어도 한도는 동일). 초과 시 429, 추가 과금 없음, 자정 리셋 |
| 429 | 키 한도 초과 또는 IP 속도 제한 — 잠시 후 재시도 |
| 401 | 키 누락·오류·폐기, 또는 키에 없는 기능 호출 |
| 서비스 상태 | GET /api/v1/status (키 불필요) — 모니터링 연동 추천 |
💡 같은 검색·경로 요청은 24시간 캐시되어 반복 호출이 수 밀리초로 응답합니다. 키는 환경변수로 관리하고 저장소에 올리지 마세요. 유출 시 대시보드에서 즉시 폐기 → 재발급.
4. 흔한 패턴
- 검색창 자동완성: 입력 후 400ms 디바운스로 geocode 호출 → 결과 클릭 시
map.flyTo
- 지도 클릭 → 주소 표시:
map.on('click')의 좌표로 reverse 호출
- 배달·이동 시간 표시: route의
duration(초)을 분으로 변환해 표시
- 직선거리 계산(서버 호출 0회): 두 좌표 간 거리는 하버사인 공식으로 브라우저에서 즉시 —
R=6371000; d=2R·asin(√(sin²(Δφ/2)+cosφ₁·cosφ₂·sin²(Δλ/2))). 저희 데모의 거리재기가 이 방식입니다.
- 체감 속도 팁: 주소처럼 느린 정보는 기다리지 말고, 좌표·버튼을 먼저 그린 뒤 도착하면 교체하세요 — 사용자는 "즉시 반응했다"고 느낍니다.
완성 예제는 라이브 데모가 곧 레퍼런스 구현입니다 — 소스 보기로 전체 코드를 확인하세요.