사이 · 두 장소 사이의 거리

Next.js 기반 한국어 거리 측정 웹앱입니다. GitHub에 올린 뒤 Vercel에서 Next.js 프로젝트로 가져올 수 있습니다.

• 출발지·도착지 명칭 또는 주소를 입력하고 검색 버튼이나 Enter로 조회
• Nominatim 검색 결과에서 실제 등록된 장소 선택 (최대 5개)
• OSRM 자동차 경로의 총 도로 거리, 예상 시간, 참고용 직선거리 표시
• 지도에 출발지·도착지와 경로 표시, 출발·도착 바꾸기
• 총거리 아래 지도에서 보기를 누르면 OpenStreetMap 길찾기를 새 탭으로 열기
• 모바일 화면, 로딩, 검색 결과 없음, 같은 장소, 경로 없음, API 오류 처리

로컬 실행

Node.js 22 이상이 필요합니다.

npm.cmd ci
npm.cmd run dev

브라우저에서 http://localhost:3000 을 엽니다. Windows PowerShell의 실행 정책과 무관하게 실행되도록 npm.cmd를 표기했습니다. macOS/Linux에서는 npm을 사용하면 됩니다.

로컬 개발 서버는 별도의 환경 변수 없이 단일 프로세스의 요청 제한과 메모리 캐시를 사용합니다. 검색은 타이핑 자동완성이 아니라 검색 버튼으로 실행됩니다. 개발 중에도 공개 API 정책을 지켜 주세요.

npm.cmd test
npm.cmd run build
npm.cmd start

start는 운영 모드입니다. 운영 모드의 장소 검색에는 다음 환경 변수 설정이 필요합니다.

GitHub → Vercel 배포

1. GitHub에서 새 저장소를 만들고 이 폴더의 소스를 업로드합니다. node_modules, .next, .npm-cache, .env.local은 올리지 않습니다. package-lock.json은 함께 올립니다.
2. Vercel에서 Add New → Project → Import Git Repository로 해당 저장소를 선택합니다.
3. Framework Preset은 Next.js, Root Directory는 저장소 루트, Build Command는 기본값(npm run build)으로 둡니다. Output Directory는 기본값을 유지합니다.
4. Vercel Marketplace에서 Upstash Redis 데이터베이스를 생성해 프로젝트에 연결합니다. REST URL과 REST Token을 아래 변수 이름으로 설정합니다. Vercel/통합 제공자가 다른 이름으로 넣어준 경우 아래 이름으로 복사합니다.
5. Vercel Settings → Environment Variables에서 세 변수를 Production과 Preview 환경에 설정합니다.

변수	값
UPSTASH_REDIS_REST_URL	Upstash 콘솔의 HTTPS REST URL
UPSTASH_REDIS_REST_TOKEN	Upstash 콘솔의 REST Token (읽기 전용 토큰은 사용 불가)
NOMINATIM_USER_AGENT	WaypointDistance/1.0 (https://내앱.vercel.app; contact: 실제연락이메일)

6. Deploy합니다. 최초 생성 시 통합 연결을 먼저 할 수 없었다면 첫 배포 후 변수를 설정하고 Redeploy합니다. 환경 변수 변경은 재배포해야 반영됩니다.
7. 사이트에서 출발지와 도착지를 각각 검색·선택한 뒤 거리와 지도 링크가 작동하는지 확인합니다. 동일 Redis를 개발·배포 환경에 연결하면 요청 제한도 공유됩니다.

Redis 및 서비스 식별자가 설정되지 않은 운영 환경에서는 사이트는 표시되지만 장소 검색은 차단됩니다. Vercel은 서버 인스턴스가 여러 개이므로 메모리 제한만으로는 공개 Nominatim의 사이트 전체 요청 제한을 지킬 수 없기 때문입니다. Redis 연결이 끊기면 외부 검색 호출도 중단합니다. 토큰은 서버에서만 사용되며 NEXT_PUBLIC_ 접두사를 붙이지 않습니다.

로컬에서 운영 빌드를 확인하려면 .env.example을 .env.local로 복사하고 실제 세 값을 입력합니다. Upstash의 요금/할당량은 이용하는 상품을 확인하세요.

공개 API 정책과 데이터 범위

Nominatim 공개 서버 사용 정책: 사이트 전체 최대 초당 1회, 앱을 식별하는 User-Agent/Referer, 출처 표시, 결과 캐시가 필요합니다. 자동완성 및 대량 수집은 금지됩니다. 개발자는 이 공개 API 선택과 정책 준수에 책임이 있습니다. 이 앱은 사용자가 버튼을 누를 때만 검색하며, 사이트 공통 Redis 잠금으로 요청을 직렬화하고 응답 후 최소 1.1초 간격을 두며, 검색 결과를 24시간 저장합니다. 서버는 일시적으로 차단되거나 정책이 바뀔 수 있습니다. 사용자 수가 늘어나면 별도 제공자 또는 자체 Nominatim으로 전환하세요.

공개 API에 개인정보나 비밀 주소를 입력하지 마세요. 검색어와 선택 좌표는 기능 수행을 위해 Nominatim, OSRM에 전송되며 지도 타일은 OpenStreetMap에서 불러옵니다. 검색어 및 검색 결과는 서버 캐시에 저장됩니다.

• Nominatim은 지오코딩(이름 → 좌표) API입니다. 거리 계산은 OSRM이 담당합니다.
• 거리는 자동차로 이동하는 경로의 길이입니다. 최단 직선거리나 실시간 내비게이션 결과와 다릅니다. 선택된 경로가 최단 거리임을 보장하지 않습니다.
• 경로가 없으면 오류를 표시하며 도로 거리를 직선거리로 대체하지 않습니다. 직선거리는 별도로 표시합니다.
• OSRM 예상 시간은 교통, 사고, 통제 등 실시간 정보를 반영하지 않습니다. 공개 데모 서버는 운영 가용성을 보장하지 않습니다.
• 도로에 지나치게 먼 지점은 경로가 조회되지 않도록 각 장소의 도로 연결 반경을 1km로 제한합니다.
• 장소 검색은 OpenStreetMap 등록 데이터 기준입니다. 실제 존재하는 모든 상호나 새 장소가 검색되는 것은 아닙니다. 동명이 장소는 주소를 보고 선택하세요.
• 지도 링크는 동일한 출발·도착 좌표와 자동차 옵션을 OpenStreetMap에 전달합니다. 외부 사이트의 제공 서버/데이터 갱신 시 앱과 경로가 달라질 수 있습니다.
• 출처: OpenStreetMap contributors / ODbL, Nominatim, OSRM.
• 지도 타일은 OSM 타일 사용 정책을 따릅니다. 사전 다운로드/오프라인 타일 기능은 없습니다.

API 제공자 변경

.env.example에 있는 NOMINATIM_BASE_URL, OSRM_BASE_URL을 해당 API와 호환되는 자체/대체 서버 주소로 지정하고 Vercel을 재배포하면 됩니다. 브라우저 소스를 수정할 필요가 없습니다. 공개 Nominatim 이용을 중단하라는 요청이 오면 즉시 전환하세요.

구조

app/page.js               검색·선택·결과 UI와 Leaflet 지도
app/globals.css           반응형 스타일
app/api/search/route.js   Nominatim 서버 프록시
app/api/route/route.js    OSRM 경로 서버 프록시
lib/services.mjs         입력 검증, 요청 제한, 캐시, API 연동
tests/services.test.mjs  거리·경로·검색·오류·요청 제한 검증

로그인, 자체 사용자 DB, GitHub/Vercel 배포 자동화는 포함하지 않습니다. 배포는 저장소를 업로드한 사용자가 진행합니다.