경주 한산길

시간대별로 경주에서 붐비는 곳을 보여주고, 그곳을 피해서 가는 길(걸어서·버스·차)을 찾아주는 웹사이트.

폴더 구조

위치	내용	자주 고치는 곳
data/zones.js	혼잡 구역(위치·반경·평소 혼잡도)	✅ 감으로 넣은 혼잡도 수정
data/attractions.js	주요 관광지(체류시간·꼭 볼 것·링크)	✅ 현지인 팁 추가
data/places.js	경주시 관광지 158곳 목록 (권역·주소·전화)	새 목록 받을 때
data/closures.js	마라톤·대회 도로 통제 일정	✅ 일정 생길 때마다 추가
data/seasonality.js	월별 계절 배율 (데이터랩 CSV)	새 CSV 받을 때
data/holidays.js	공휴일	1년에 한 번
lib/	혼잡도 계산·거리 계산·날짜	거의 안 고침
api/	서버 함수 (키는 여기서만 씀)	거의 안 고침
index.html, style.css, app.js	화면	디자인 바꿀 때

필요한 키 (Vercel → Settings → Environment Variables)

이름	어디서	없으면
KAKAO_JS_KEY	카카오 개발자 콘솔 → 앱 → 플랫폼 키 → JavaScript 키	지도가 안 나옴
KAKAO_REST_KEY	카카오 개발자 콘솔 → 앱 → 플랫폼 키 → REST API 키	버스 경로 안 됨
GRAPHHOPPER_API_KEY	GraphHopper 대시보드 → API Keys	걸어서·차 경로 안 됨
DATA_GO_KR_SERVICE_KEY	공공데이터포털 → 일반 인증키(Decoding)	혼잡 예측·버스 실시간 도착 없이 동작
ITS_API_KEY	국가교통정보센터(ITS) 오픈데이터 → 인증키 신청현황	실시간 도로 속도·돌발상황 없이 동작

공공데이터포털에서 활용신청이 필요한 데이터: 관광지 집중률 방문자 추이 예측, 국토교통부_(TAGO)버스도착정보, 국토교통부(TAGO)_버스정류소정보 (모두 같은 인증키).

ITS는 국내 IP에서 온 요청에만 답해서, 서버 함수를 서울(icn1)에서 돌리도록 vercel.json에 적어 뒀어요. ITS 월 호출 한도(서비스마다 3,000건)를 넘지 않게 돌발상황은 30분, 도로 속도는 15분 동안 같은 결과를 다시 써요 (최대 하루 48건 / 96건).

카카오 콘솔의 JavaScript SDK 도메인에 Vercel 주소(예: https://gyeongju-hansangil.vercel.app)를 꼭 추가하세요.

혼잡도 계산

점수 = 평소 혼잡도(구역·요일·시간대) × 계절 배율(월) × 그날 예측 배율

• 039 한산 / 4064 보통 / 6584 혼잡 / 85 매우 혼잡
• 걸어서·차: 보통 이상인 구역은 피하고, 붐빌수록 더 강하게 피해요. 차는 통제 구간을 거의 지나가지 않아요.
  • GraphHopper 구역 피하기(custom model)가 플랜에서 막혀 있으면 경유지 방식으로 계산해요: 가장 짧은 길이 혼잡 구역에 들어가는 구간 바로 옆 바깥에 경유지를 잡아 최대 4개 경로를 더 계산하고, 너무 멀리 돌아가는 길은 빼고 혼잡 비용이 가장 작은 길을 골라요. 혼잡 구역 안을 걷는 시간은 몇 배로 쳐요 (api/route.js의 CROWD_COST, MAX_EXTRA_MIN).
• 버스: 카카오가 준 소요시간에, 혼잡 구역을 지나가면 지연 예상(보통 +2분, 혼잡 +5분, 매우 혼잡 +10분, 통제 +15분)을 더해 추천 순서를 정해요 (lib/transit.js).
  • '지금' 시간으로 찾으면 TAGO 실시간 도착 정보로 정류장에서 기다리는 시간도 더해요. 정류장까지 걷는 동안 지나가는 버스는 빼고, 오고 있는 버스가 없으면 15분 이상 기다린다고 봐요.

ITS 실시간 교통 (api/events.js, api/speeds.js, lib/its.js)

• 돌발상황(사고·공사·행사·통제): 좌표가 같이 와서 지도에 표시하고, 차 길찾기에서 피해요. 버스 추천 순서에도 지연으로 반영해요.
  • 전면 통제·행사 → 거의 못 지나가는 곳으로, 공사·사고 → 막히는 곳(혼잡)으로 봐요. 걸어서 길찾기에는 넣지 않아요.
  • 직접 입력하는 data/closures.js는 그대로 쓸 수 있어요 (ITS에 안 올라오는 행사용).
• 도로 속도: ITS는 도로 토막(링크) 번호와 속도만 주고 좌표는 안 줘서, 도로 이름으로 길찾기 경로(GraphHopper street_name)와 맞춰요. 시간을 '지금'으로 두고 차 길을 찾을 때만 써요.
  • 이름이 맞는 도로는 실시간 속도로 예상 시간을 다시 계산하고, 그 시간으로 덜 막히는 길을 골라요.
  • ITS는 고속도로·국도 위주라 시내 작은 길은 안 잡혀요. /api/speeds를 열면 지금 잡히는 도로 목록이 보여요.

길 안내

경로를 찾은 뒤 이 길로 안내 시작을 누르면 GPS로 내 위치를 따라가며 다음 안내(예: "120m 후 왼쪽으로")를 지도 위에 보여줘요 (lib/nav.js).

• 경로에서 벗어나면(걸어서 45m, 차 70m, 버스 120m) 다시 찾기로 지금 위치에서 다시 계산하고 안내를 이어가요.

• 경로에서 2km 넘게 떨어져 있거나 위치 권한이 없으면 미리보기로 단계별로 넘겨볼 수 있어요.

• 음성 안내는 브라우저 음성(한국어)으로 켜고 끌 수 있어요.

• 휴대폰에서는 지도가 화면 전체에 깔리고, 메뉴는 아래에서 끌어올리는 시트예요. 손잡이를 끌거나 눌러서 작게·반·크게로 바꿔요. 안내를 시작하거나 '지도에서'로 고를 때는 자동으로 작게 내려가요.

지도 아무 데나 누르면 주소·혼잡도와 여기서 출발 / 여기로 도착 팝업이 떠요.

구역 경계 그리기

사이트 주소 뒤에 ?draw를 붙여 열면(/?draw) 지도를 눌러 꼭짓점을 찍고 좌표를 복사할 수 있어요. data/zones.js에서 그 구역의 polygon: [ ... ], 부분을 통째로 지우고 붙여넣으세요.

나중에 할 일

• 버스 실시간 도착 정보 (TAGO 버스도착정보 + 버스정류소정보, api/arrivals.js)
• 버스 배차 간격 (시간표 기반, 실시간 정보가 없을 때 보완)
• 차 혼잡 실시간 반영: 코드는 준비됨 (ITS 돌발상황 + 도로 이름별 속도). ITS가 해외 회사 서버(Vercel=아마존)를 막아서 중계가 필요
  • 후보: 오라클 무료 서버(고정 IP) + ITS 방화벽 허용 신청서([email protected]) / 국내 저가 서버
  • 네이버 Cloud Functions는 VPC 필수 + NAT Gateway 유료라 보류
  • 중계 코드: relay/ncp-its-relay.cjs, Vercel 환경변수 ITS_RELAY_URL, ITS_RELAY_TOKEN
• 도로 속도를 도로 토막 단위로 (표준노드링크 좌표 필요) + 막힌 도로 자체를 피하는 경유지 만들기
• ITS 교통예측정보로 '지금'이 아닌 시간의 도로 속도 추정
• 관광지 설명·사진 (한국관광공사 Tour API)

내 컴퓨터에서 미리 보기 (선택)

Node.js가 설치돼 있으면 설치할 패키지 없이 바로 돼요.

cp .env.example .env.local   # 키 채우기
node dev-server.js           # → http://localhost:3000