광주 주유소 가격비교 ⛽
광주광역시 상생카드·온누리상품권 가맹 주유소의 실시간 유가를 비교하는 웹 서비스입니다.
gwangju-oil.vercel.app
왜 만들었나요?
광주상생카드 참 좋은데... 명절에는 할인도 팍팍 해주고 좋은데... 상생카드 쓸 수 있는 주유소 목록은 광주광역시 홈페이지에 나와 있는 읽기 힘든 엑셀자료뿐... 매번 검색해서 일일히 유가 비교하기에는 지갑 얇은 내연기관차량 오너로서는 넘나 힘든 일이어라ㅠㅠ (심지어 어디는 상호 바꾸고 심지어 폐업한곳도 있었음;;!!)
그런데 엥 요즘 바이브코딩이 대세군요?! 냅다 클코 깔고 만들어달라 했답니다 (토큰 살살 녹은건 비밀😇) 조금 일이 커진거같지만 아무튼 봐줄만한 정도는 된 것 같아 깃헙에 내놓았답니다
지금은 프로토타입이라 개선해야 할 사항이 넘나 많지만 이걸 두들겨보고 들춰보고 찔러보고 여러모로 써 주시고 의견이나 가르침 주신다면 감사하겟습니당 사실 저는 R 깔짝 쓰다가 바이브코딩 접하고 냉큼 해본거라 많이 알지는 못하지만 질문 주신다면 제가 아는 범위 내에서... 열심히 답드리겟습니다 오늘도 좋은하루~~~
주요 기능
- 오늘의 유가 — 전국/광주 평균 유가 비교, 전일 대비 등락 표시
- 주유소 탐색 — 광주 5개 구별 필터링, 정유사 필터, 휘발유/경유 전환, 가격순/거리순 정렬
- 상품권 필터 — 상품권 전체 / 광주상생카드 / 온누리상품권 가맹점 별도 조회
- 내 주변 주유소 — GPS 기반 반경 검색 (1~10km), 탐색 탭에 통합
- 즐겨찾기 — 자주 가는 주유소 저장 (브라우저 로컬 저장)
- 실시간 유가 — 오피넷 API 연동, 주기적 가격 갱신
- 카카오 지도 — 주유소 위치 마커 표시, 상단 고정 + 리스트 스크롤 레이아웃
- 모바일 최적화 — 반응형 디자인, 모바일 우선 레이아웃
기술 스택
| 분류 | 기술 |
|---|
| 프레임워크 | Next.js 16 (App Router, Turbopack) |
| 언어 | TypeScript 5.9 |
| 스타일링 | Tailwind CSS 4 |
| 데이터 페칭 | SWR |
| 데이터베이스 | MongoDB Atlas (2dsphere 지리공간 인덱스) |
| 지도 | Kakao Maps SDK |
| 배포 | Vercel |
| 데이터 전처리 | Python (pandas) |
데이터 소스
시작하기
사전 준비
- Node.js 18+
- MongoDB Atlas 클러스터
- API 키: 오피넷, 카카오 개발자, (선택) 공공데이터포털
환경변수 설정
.env.example을 .env.local로 복사한 후 값을 채워 넣으세요.
cp .env.example .env.local
OPINET_API_KEY=... # 오피넷 API 키
NEXT_PUBLIC_KAKAO_MAP_KEY=...# 카카오 JavaScript 키
KAKAO_REST_API_KEY=... # 카카오 REST API 키
MONGODB_URI=... # MongoDB 연결 문자열
CRON_SECRET=... # 가격 갱신 엔드포인트 보안 키
설치 및 실행
# 의존성 설치
npm install
# 데이터 초기화 (상생카드 데이터 다운로드 → 지오코딩 → DB 시딩)
npm run seed
# 온누리상품권 가맹점 매칭
npm run onnuri:link
npm run onnuri:add
# 오피넷 가격 연동
npm run opinet:link
# 개발 서버 시작
npm run dev
http://localhost:3000에서 확인할 수 있습니다.
데이터 파이프라인
상생카드 가맹점 다운로드 → 카카오 지오코딩 → MongoDB 시딩 → 온누리 매칭 → 오피넷 매칭 → 가격 갱신
| 명령어 | 설명 |
|---|
npm run seed | 전체 파이프라인 (다운로드 → 지오코딩 → DB 저장) |
npm run seed:download | 상생카드 데이터 다운로드만 |
npm run seed:geocode | 주소 → 좌표 변환만 |
npm run opinet:link | 오피넷 주유소 매칭 + 초기 가격 수집 |
npm run onnuri:link | 온누리상품권 가맹 주유소 DB 마킹 |
npm run onnuri:add | 온누리 전용 주유소 (상생카드 미가맹) DB 추가 |
npm run prices:refresh | 가격 갱신 (주기적 실행용) |
npm run prices:snapshot | 전국/광주 평균 유가 스냅샷 저장 |
프로젝트 구조
app/
├── home/ # 홈 (전국/광주 평균 유가, 즐겨찾기 바로가기)
├── browse/ # 주유소 탐색 (내 주변 통합)
├── nearby/ # /browse?district=nearby 로 리다이렉트
├── favorites/ # 즐겨찾기
├── station/ # 주유소 상세
└── api/
├── stations/ # 주유소 목록 · 상세 · 근처 검색
├── prices/ # 가격 갱신 · 전국/광주 평균가
└── kakao-sdk/ # 카카오 SDK 프록시
lib/
├── db/ # MongoDB 연결 · 모델 · 쿼리
├── opinet/ # 오피넷 API 클라이언트
├── matching/ # 상생카드 ↔ 오피넷 매칭 알고리즘
├── geo/ # 좌표 변환 (WGS84 ↔ KATEC), 거리 계산
├── gwangju/ # 광주 구·지역 데이터
└── hooks/ # React 커스텀 훅
scripts/ # 데이터 파이프라인 스크립트 (상생카드 시딩, 온누리 매칭, 오피넷 연동 등)
components/ # UI 컴포넌트 (지도, 카드, 필터 등)
배포
Vercel에 배포되어 있습니다. GitHub 푸시 시 자동 배포됩니다.
Vercel 대시보드에서 위의 환경변수를 모두 설정해야 합니다. MongoDB Atlas의 Network Access에서 0.0.0.0/0을 허용해야 Vercel 서버리스 함수에서 접근 가능합니다.
라이선스
MIT
