external-api-inventory.md

OffWay 외부 데이터 인벤토리 · 발급 체크리스트

• 조사일: 2026-07-18
• 목적: OffWay가 끌어올 모든 외부 데이터의 발급처·인증·엔드포인트·가용 데이터를 한곳에. 이 문서가 곧 (1) 회원가입/키 발급 체크리스트, (2) 우리가 조합할 데이터 전체 목록.
• 전략: 미리 전부 확보·적재(라이브 API + 정적 시딩) 해두고 조합해 서비스를 제공한다.

⚠️ 신뢰도 표기: 아래 상당수는 조사 기반이며 일부 오퍼레이션명·파라미터 철자는 활용신청 후 각 상세페이지의 활용가이드/Swagger로 최종 확정 필요. "추정" 표시된 항목 주의.

---

0. 회원가입은 딱 3곳 (대부분 data.go.kr 하나로 커버)

#	포털	URL	커버하는 데이터	인증 방식
1	공공데이터포털 data.go.kr	https://www.data.go.kr	특일정보 · TourAPI · 관광빅데이터 · TAGO(버스/열차) · 코레일 · 생활인구(파일)	계정 1개 + API별 활용신청 → serviceKey
2	SK openapi.sk.com	https://openapi.sk.com	TMAP 경로/경유지 최적화	앱 등록 → appKey(헤더)
3	(선택) 통계청 SGIS	https://sgis.kostat.go.kr/developer	센서스 인구·통계(생활인구 보강용)	key+secret → accessToken

data.go.kr 서비스키 핵심 함정: 발급 화면에 Encoding 키 / Decoding 키 두 종류가 나온다. HTTP 클라이언트가 파라미터를 자동 인코딩하면 Decoding 키, 아니면 Encoding 키를 쓴다. 잘못 쓰면 SERVICE_KEY_IS_NOT_REGISTERED_ERROR. → application secret으로 두 키 다 보관하고, 한쪽 실패 시 반대로 시도.

---

1. 라이브 REST API (클라이언트 구현 대상 → external/ port)

1-1. 특일 정보 (공휴일·대체공휴일) — 한국천문연구원

• 발급: data.go.kr 데이터셋 15012690 한국천문연구원_특일 정보 → 활용신청 (자동승인)
• Base: https://apis.data.go.kr/B090041/openapi/service/SpcdeInfoService
• 오퍼레이션: getRestDeInfo(공휴일+대체공휴일 — 이걸 사용), getHoliDeInfo(국경일), getAnniversaryInfo, get24DivisionsInfo
• 파라미터: serviceKey, solYear(필수), solMonth(권장, 월별 반복 호출 안전), _type=json, numOfRows, pageNo
• 응답 필드: locdate(YYYYMMDD), dateName(예 "대체공휴일"), isHoliday(Y/N), dateKind
• 한도: 무료, 개발계정 일 10,000건(추정)
• 함정: 대체공휴일은 별도 플래그 없이 dateName="대체공휴일"로 판별. 미래 연도는 지정 전 누락 가능.
• OffWay 용도: LNT 산출 · 샌드위치 연휴 탐지의 기반.

1-2. 국문 관광정보 서비스 (TourAPI) — 한국관광공사

• 발급: data.go.kr 데이터셋 15101578 한국관광공사_국문 관광정보 서비스_GW → 활용신청 (자동승인)

• Base(권장 v2, HTTPS): https://apis.data.go.kr/B551011/KorService2 (레거시 KorService1은 단계적 폐지)

• 오퍼레이션: areaBasedList2(지역기반 목록 — 핵심), locationBasedList2(위경도+반경), searchKeyword2, detailCommon2(주소·좌표·개요), detailIntro2(운영시간·휴무일), detailImage2, areaCode2(지역코드 조회)

• 파라미터: serviceKey, MobileOS(ETC), MobileApp(offway), _type=json, numOfRows, pageNo, arrange, areaCode, sigunguCode, contentTypeId, cat1/2/3

• contentTypeId: 12=관광지 · 14=문화시설 · 15=축제공연행사 · 25=여행코스 · 28=레포츠 · 32=숙박 · 38=쇼핑 · 39=음식점

• 응답 필드: contentid, title, addr1, mapx(경도)/mapy(위도), areacode, sigungucode, firstimage, tel; detailIntro는 usetime/restdate(운영·휴무, 자유텍스트)

• 한도: 무료, 개발계정 일 1,000건 (운영 전환 시 증량)

• ⚠️ 최대 함정 — 지역코드: sigunguCode는 KTO 전용 순번(법정 시군구 코드 아님)이고 areaCode와 함께만 유효. → 먼저 areaCode2로 (areaCode,sigunguCode)↔지명 매핑 테이블을 확보한 뒤 인구감소지역 89곳 지명과 매칭. 지명 기준 조인.

• OffWay 용도: 인구감소지역 관광지·숙박·음식점 표출, 운영시간/휴무 기반 일정 생성.

• 실측(2026-08-21 · 89곳 전수, areaBasedList2 89콜) — 지역 장소 풀(#304)의 근거다.

  	값
  지역당 등록 건수	최소 16 · 중앙값 57 · 최대 97
  사진 보유율	칩별 84~95% (firstimage)
  사진 있는 장소 10건 이상	89/89곳

  칩별로 사진 있는 장소가 하나라도 있는 지역 — 관광지 89/89 · 맛집 89/89 · 숙박 87/89 · 체험 86/89. (숙박·맛집은 전체타입 1콜만 쓴 하한이다. 배치는 타입별 2콜을 더 부른다.)

  국가유산 보충은 필요 없다. 89곳 전부가 사진 있는 장소를 10건 이상 들고 있어 화면 상한(10개)을 채운다. (위 표의 최소 16 은 등록 건수라 사진 건수와 다르다 — 사진 보유율이 84~95% 이므로 그보다 작다.)

• 실측(2026-08-21 · 표본 40건) — 카테고리별 부가 정보 채움률. 홈 장소 카드 부제(#305)의 근거다.

  대상	필드	채움률
  맛집 detailIntro2	firstmenu(대표메뉴) · opentimefood	100% (19/19)
  숙박 detailIntro2	roomcount 47% · checkintime 52%	절반
  숙박 detailInfo2	객실 요금(roomoffseasonminfee1 등)	21% (4/19)

  1인 가격 필드는 음식점에 아예 없다. 시안의 1인 9,000원 은 대표메뉴로 대체해야 한다. 숙박 요금은 detailInfo2 를 POI 마다 더 불러야 하는데 채움률이 21% 라 비용이 값어치를 넘는다.

1-3. 관광빅데이터(방문자수) — 한국관광공사 · 실호출 확인(#20)

• 발급: data.go.kr 데이터셋 15101972 한국관광공사_관광빅데이터 정보서비스_GW → 활용신청 (15101578과 별개 신청)
• Base: https://apis.data.go.kr/B551011/DataLabService ✅ 확인
• 오퍼레이션: metcoRegnVisitrDDList(광역별 일별 방문자수) · locgoRegnVisitrDDList(기초 시군구별 — OffWay 89에 사용). 둘 다 실호출 성공(resultCode 0000).
• 파라미터: serviceKey·MobileOS(ETC)·MobileApp(offway)·_type=json·startYmd/endYmd(YYYYMMDD)·pageNo·numOfRows. (지역 필터 param 없이 기간 전체 반환 → 클라가 시군구로 매칭)
• 응답 필드(locgo): signguCode(11110)·signguNm(종로구)·daywkDivCd/daywkDivNm(요일)·touDivCd/touDivNm(1=현지인·2=외지인·3=외국인)·touNum(방문자수, 문자열)·baseYmd
• 한도: 무료, 개발계정 일 1,000건
• 함정 ①(매칭 키): signguCode는 법정 시군구코드(행정표준코드)라 TourAPI KTO 코드와 다름 → region 에 legal_code 컬럼을 따로 두고 코드로 매칭한다(#65).
  • signguNm(지명)으로 매칭 은 폐기했다. 지명은 전국에서 겹친다 — 동구 6곳·중구 6곳·서구 5곳·남구 4곳·북구 4곳·고성군 2곳(2026-06 실호출, 268개 시군구 기준). 우리 89곳 중 부산 동구·부산 서구·대구 남구·대구 서구·강원 고성군(51820)·경남 고성군(48820) 6곳이 걸려, 서로 다른 지역의 방문자가 한 버킷에 합산됐다(부산 동구 = 전국 동구 6곳의 합).
  • region.legal_code 의 정본은 이 응답의 signguCode 자체다. 매칭 상대에서 그대로 따와야 89곳 전부 매칭이 보장된다.
• 함정 ②(발행 주기): 완결된 달만 월 단위로 발행된다. "N일 지연"이 아니다 — 2026-07-30 기준 6월(24,120건)까지 있고 7월은 0건. 고정 일수 지연을 가정하면 관측 창이 미발행 구간에 걸려 조회가 resultCode=0000 + 빈 결과로 조용히 성공하고, 전 지역 방문자가 0이 돼 랭킹이 무의미해진다(경고 로그도 안 남음). → 지난달부터 시작해 비면 이전 달로 물러선다.
• 함정 ③(응답 크기): 지역 필터가 없어 기간 전체가 내려온다. 268 시군구 × 3 구분 × 일수 → 7일 약 1MB / 한 달 약 4MB. 운영 externalWebClient 의 maxInMemorySize 가 2MB 라 한 달치는 버퍼를 넘긴다. 관측 창을 발행된 달의 마지막 한 주로 잡는 이유.
• 함정 ④: "방문자≠관광객" → 랭킹엔 외지인+외국인만.
• OffWay 용도: "평일에 한산한 시점" 한산도 뱃지·지역 랭킹 — 차별화 핵심 데이터.
• 미확인(후속): 관광지별 집중률·향후 방문자 예측은 별도 오퍼레이션(#21+ 필요 시 확인).

1-3-1. 기초지자체 중심 관광지 — 한국관광공사 · 실호출 확인(#185)

• 발급: 관광빅데이터와 같은 계정(15101972)으로 호출된다 — 별도 신청 없이 serviceKey 를 그대로 쓴다.

• Base: https://apis.data.go.kr/B551011/LocgoHubTarService1 ✅ 확인 (1-3 의 DataLabService 와 다른 base)

• 오퍼레이션: areaBasedList1 — 한 지자체의 중심 관광지를 순위로. 실호출 성공(resultCode=0000).

• 파라미터: serviceKey·MobileOS(ETC)·MobileApp(offway)·_type=json·areaCd(시도 2자리)·signguCd(시군구 5자리)·baseYm(YYYYMM)·numOfRows·pageNo(필수)

• 응답 필드: hubRank(순위)·hubTatsCd(식별자)·hubTatsNm(관광지명)·hubCtgryLclsNm(대분류: 관광지·음식·숙박)·hubCtgryMclsNm(중분류)·mapX(경도)/mapY(위도)·signguNm·baseYm

• 실측(2026-08-09, 공주시 44150 · baseYm=202606)

  항목	값
  응답시간	n=20 · min 0.106s · p50 0.123s · p90 0.135s · p95 0.137s · max 0.139s
  응답 크기	numOfRows=30 → 9.5KB · numOfRows=100 → 31KB
  totalCount	지자체당 51~100건(표본 5곳: 공주 100·완도 51·강원고성 100·경남고성 100·양구 82)
  페이지	상한이 100건이라 numOfRows=100 이면 1페이지로 끝난다 — 페이지 순회가 필요 없다

• timeout 근거: 어댑터는 6초를 쓴다. 정상 p95(0.14초)의 40배로 크게 잡은 값인데, 표본이 20회라 p99 를 낼 수 없어 꼬리를 보수적으로 뒀다. 이 경로는 하루 한 번 도는 배경 배치라 지연이 사용자에게 닿지 않는다 — 89곳 순차 최악이 534초여도 아무도 기다리지 않는다. 요청 경로에 붙일 일이 생기면 이 값을 다시 재야 한다.

• 한도: 1-3 과 같은 계정이라 일 1,000건을 공유한다. 갱신 1회가 89건(+발행월 탐색 최대 9건)이므로 하루 한 번이면 여유가 있다. 요청 경로에서 부르면 안 되는 이유가 이것이다(#193).

• 함정 ①(코드 체계): areaCd/signguCd 는 법정동 코드다 — 공주시는 44/44150. TourAPI 의 KTO 코드(34/1)를 넣으면 resultCode=0000 에 totalCount=0 이 온다(실측). 성공 코드라 조용히 빈 결과가 되므로 특히 위험하다.

• 함정 ②(pageNo 필수): 빠뜨리면 resultCode=11 NO_MANDATORY_REQUEST_PARAMETERS_ERROR1(pageNo) 인데, 그 응답만 response 래퍼 없이 최상위에 코드를 담아 온다(실측 원문: {"responseTime":"...","resultCode":"11","resultMsg":"..."}). 래퍼만 보고 파싱하면 코드가 빈 문자열이 돼 "결과 없음" 과 구분되지 않는다 — 조사 중 실제로 이걸로 "최신 월이 없다" 고 잘못 읽었다.

• 함정 ③(1건이면 단일 객체): items.item 이 배열이 아니라 객체로 온다. 결과가 없으면 items 가 빈 문자열이다. 둘 다 1-2·1-3 과 같은 data.go.kr 공통 함정.

• 함정 ④(1위가 대표 사진감은 아님): 대분류가 숙박·음식인 경우가 있다 — 정선군 1위는 콘도, 2위는 카지노다. 데이터는 맞지만 지역 카드에 걸 그림이 아니라 대분류로 걸러야 한다.

• 발행 주기: 1-3 과 같은 월 단위. 2026-08-09 기준 202607 까지 발행됨(확인). 이번 달은 아직이므로 지난달부터 시작해 비면 물러선다.

• OffWay 용도: 지역 대표를 "제목순 첫 POI"(#182)가 아니라 실제 이동 데이터의 중심성으로 정한다. 공주시 1위 = 공산성 — TourAPI 에는 등록조차 없어 기존 구조로는 찾을 수 없던 곳이다.

1-3-2. 관광사진 갤러리 — 한국관광공사 · 실호출 확인(#196)

• 발급: 관광빅데이터와 같은 계정(15101972). 별도 신청 없이 serviceKey 를 그대로 쓴다.

• Base: https://apis.data.go.kr/B551011/PhotoGalleryService1 ✅ 확인

• 오퍼레이션: galleryList1 — 전량 목록. 실호출 성공(resultCode=0000).

  • galleryKeywordList1 은 호출이 실패했다. 전량을 DB 로 내리면 키워드 검색이 필요 없어 더 파지 않았다.

• 파라미터: serviceKey·MobileOS(ETC)·MobileApp(offway)·_type=json·arrange·numOfRows·pageNo

• 응답 필드: galContentId·galTitle·galWebImageUrl·galPhotographyMonth(YYYYMM)·galPhotographyLocation·galPhotographer·galSearchKeyword

• 실측(2026-08-09)

  항목	값
  전량	6,118건
  페이지	numOfRows=1000 이 그대로 받아들여져 7페이지로 끝난다
  응답 크기	1,000건 페이지 554KB (3건 1.9KB)
  응답시간	0.18~0.35초

• timeout 근거: 어댑터는 10초. 실측 0.35초의 30배로, 표본이 적어 꼬리를 보수적으로 뒀다. 부팅 후 도는 배경 적재라 지연이 사용자에게 닿지 않는다.

• maxInMemorySize 주의: 페이지당 554KB 라 운영 externalWebClient 상한(2MB) 안에 든다. 페이지 크기를 더 키우면 여기에 걸린다.

• 한도: 1-3 과 같은 계정이라 일 1,000건을 공유한다. 전량 적재가 7회뿐이라 주 1회 갱신으로 충분하다.

• ⚠️ 함정 ①(촬영 위치가 자유 텍스트): galPhotographyLocation 은 정제된 코드가 아니다. 실측 분포에서 이런 값이 나온다.

  전남광주통합특별시 711 · 강원도 581 / 강원특별자치도 198 · 전라북도 402 / 전북특별자치도 98
  서울 231 / 서울시 18 / 서울특별시 277 · 인청광역시 · 산광역시 · 전북특별자치도도 (오타)
  신승반점 · FNC · 전주식당 · 민가다헌 (시도 자리에 상호명)
  

  → 시도를 함께 정규화하지 않으면 조용히 틀린다. 시군구명만으로 세면 대구 남구가 104건으로 부풀었다(전국 남구의 합). 정규화 후 6건. 1-3 의 함정 ①과 같은 계열이다.

• 함정 ②(제목이 장소명이 아닐 수 있다): galTitle 이 "봄의 약속" 같은 작품명인 경우가 있다. 장소명은 galSearchKeyword 에만 있을 수 있어 둘 다 봐야 한다 — 제목 "금강철교" 사진의 키워드에 "공산성" 이 들어 있다.

• 함정 ③(1건이면 단일 객체·결과 없으면 빈 문자열): 1-2·1-3 과 같은 data.go.kr 공통 함정.

• ⚠️ 함정 ④(죽은 이미지 URL): galWebImageUrl 의 상당수가 404 다 — 우리 89곳에 붙은 1,790장 중 345장(19.3%). 경로로는 못 가른다(같은 cms2/website/ 에 산 것과 죽은 것이 섞여 있다). 확인하지 않고 쓰면 지역 카드 15곳에 깨진 이미지가 나간다.

  • 생존 확인에 HEAD 를 쓰면 안 된다. 이 호스트는 HEAD 에 405 를 돌려줘 살아 있는 URL 도 죽은 것으로 판정된다(처음 잰 83개가 전부 405 였다). GET 으로 확인하고 본문을 버린다.

• OffWay 용도: 지역 대표 사진(#196). 중심 관광지(1-3-1) 순위와 이어 "그 지역의 대표 명소 사진"을 고른다.

• 커버리지 실측(죽은 URL 제외 후): 6,118건 중 1,790건이 우리 89곳에 붙고, 그중 살아 있는 것은 1,445건이다. 사진이 한 장도 없는 곳은 장수군 1곳.

  사다리 단계	지역 수
  ① 중심 관광지(1-3-1) × 갤러리	82곳
  ② 그 지역 갤러리 사진(5장 이상 보유)	4곳 — 부산 동구·인천 옹진군·전남 영암군·경남 의령군
  ③ TourAPI 폴백	3곳 — 전북 장수군·경북 영양군·경북 의성군

  ②를 둔 이유: 중심 관광지 이름과 갤러리 제목이 안 맞아도 그 지역에 쓸 사진이 없는 것은 아니다. 영암군은 중심 관광지 3위가 도갑사인데 정작 영암을 대표하는 월출산 사진이 13장 있었다. 다만 한두 장뿐인 곳(영양군의 유일한 사진은 '가마')은 우연히 찍힌 쪽에 가까워 TourAPI 로 내려보낸다.

1-4. TAGO 대중교통 — 국토교통부 (여러 서비스, 동일 계정)

• Base 공통: https://apis.data.go.kr/1613000/... (serviceKey 가 URL 에 실리므로 HTTPS 필수 — 평문 전송 금지) · 응답 래퍼 resultCode/items>item[]
• 한도: 무료, 개발계정 일 10,000건

⚠️ 경로 명명 — 서비스마다 다르다: data.go.kr TAGO 는 서비스마다 base·op casing 이 제각각이다. 버스류는 ...InqireService + 소문자 op(getCtyCodeList)다. 열차는 실측 확정: 짧은 base(TrainInfo) + 대문자 G op(GetStrtpntAlocFndTrainInfo). 고속버스·시외버스·지하철은 아직 추정(열차와 같은 규칙일 것으로 보이나 실호출 미확인). 틀린 조합은 게이트웨이가 404 "API not found" — 404 의 태반이 미구독이 아니라 경로·casing 오타였다.

서비스	데이터셋	base	핵심 op / 필드	비고
버스도착정보(시내)	15098530	ArvlInfoInqireService ✅	getSttnAcctoArvlPrearngeInfoList(소문자) → arrtime	nodeId 선조회, 실시간
버스정류소정보	15098534	BusSttnInfoInqireService ✅	getCtyCodeList 등(소문자)	200
버스노선정보	15098529	BusRouteInfoInqireService ✅	노선·경유정류소(소문자)	200
버스위치정보	15098531	BusLcInfoInqireService ✅	실시간 차량 위치(소문자)	200
열차정보	15098552	TrainInfo ✅	GetStrtpntAlocFndTrainInfo(대문자 G) · GetCtyCodeList · GetCtyAcctoTrainSttnList	200 실호출·KTX 확인. SRT 미포함
고속버스정보	15098522	ExpBusInfo(추정)	GetExpBusTrminlList(대문자 추정)	열차와 같은 규칙 예상
시외버스정보	15098541	SuburbsBusInfo(추정)	(대문자 추정)	⚠️ 당일 배차만
지하철정보	—	SubwayInfo(추정)	(대문자 추정)	도시 내

• 응답 필드(열차): items.item[] (단건이면 item 객체 하나) · traingradename(KTX·ITX-새마을·무궁화) · depplandtime/arrplandtime(yyyyMMddHHmmss) · trainno. 미운행이면 items:""(빈 문자열).
• 역/정류소/터미널 ID는 각 목록 op(GetCtyCodeList → GetCtyAcctoTrainSttnList 등)으로 선조회. 예: 서울 NAT010000 · 부산 NAT014445.
• OffWay 용도: 반차·퇴근후 모드 도착시각, 교통수단별 동선.

⚠️ 시내버스 커버리지 — 전국이 아니다 (실호출 확인 2026-07-31)

BusSttnInfoInqireService/getCtyCodeList 실호출 결과 138개 지자체만 담는다. 서울조차 없다(별도 TOPIS). 미커버 지역은 오류가 아니라 resultCode=00 + 빈 결과로 오므로, 그대로 두면 "주변에 정류소 없음"과 구분되지 않는다.

도시코드 앞 두 자리가 시도다(32010 춘천 → 32 강원). 이 구분이 있어야 동명 시군구를 갈라낸다 — 고성군은 강원(미커버)·경남(커버) 양쪽에 있어 지명만 맞추면 강원 고성군까지 커버로 오판한다. 광역시는 구 단위 없이 시 전체가 한 코드(21 부산)이고, 버스권역이 묶인 곳은 "원주시/횡성군" 합본으로 온다.

우리 89곳 중 미커버 13곳 (89 × 138 대조):

시도	미커버 시군구
강원특별자치도	고성군 · 삼척시 · 양구군 · 영월군 · 정선군 · 평창군 · 화천군
충청남도	예산군
전라남도	강진군 · 담양군 · 보성군 · 영광군 · 화순군

하필 이 서비스가 겨냥하는 강원 산간·전남 오지다. 공공데이터 폴백 없음 — 전국 버스정류장 위치정보(15067528)도 "TAGO 연계 지자체" 스냅샷이라 같은 모집단이다. 상용 API(ODsay·카카오, 유료)만 남는다. 실시간 도착은 지자체 BIS 구축이 전제라 구조적으로 불가.

→ 메울 수 없으므로 구분해서 드러낸다: BusStopAccess.NotCovered("데이터 없음") ≠ NoStopNearby("정류소 없음"). 판별은 BusAccessService 가 도시목록(24h 캐시)으로 한다. 목록을 못 얻으면 판별 불가라 Unavailable 로 폴백한다 — 커버 여부를 모르는 채 "버스 없음"이라 안내하면 틀린 말이 될 수 있어서다.

1-5. 코레일 열차운행정보 — 한국철도공사

• 발급: data.go.kr 15125762 한국철도공사_열차운행정보 → 활용신청
• 제공: 여객열차 운행계획/운행정보(실시간·지연). 출발역/도착역/운행일자 기반.
• 함정: 요금·예매·좌석 미제공(운행 트래킹용). 시간표는 1-4 TAGO 열차정보가 더 적합.
• OffWay 용도: KTX 지연/실제운행 보조 (선택).

1-6. TMAP 경로·경유지 최적화 — SK(티맵모빌리티) 별도 포털

• 발급: https://openapi.sk.com 회원가입 → 앱 등록 → TMAP 상품 구독 → appKey(UUID) 발급
• 인증: 요청 헤더 appKey: <키>
• Base: https://apis.openapi.sk.com/tmap/...
  • 자동차 경로: POST /tmap/routes?version=1
  • 경유지 최적화(10곳): POST /tmap/routes/routeOptimization10 (20/30곳은 엔드포인트 별도)
• 파라미터: startX/startY, endX/endY(경도X/위도Y, WGS84GEO), searchOption; 최적화는 viaPoints[](viaX/viaY/viaTime)
• 응답: GeoJSON, totalTime(초)·totalDistance(m)·totalFare
• 한도(무료): 경로 1,000/일, 경유지 최적화(10곳) 50/일 (초과 시 유료)
• ⚠️ 함정: 결과 데이터 24시간 이상 저장 금지(약관) → 경로 결과 영구 캐싱 불가. 좌표 X=경도/Y=위도 순서.
• OffWay 용도: 자가용 기준 실시간 소요시간, 관광지 경유지 순서 최적화(일정 자동 생성).

---

2. 정적 데이터셋 (런타임 호출 아님 → DB 시딩/임포트)

#	데이터	출처	형식	방식
2-1	인구감소지역 89곳	행안부 고시 (mois.go.kr / nabis.go.kr)	고시문/표	상수 시드(거의 불변, "고시 기준일" 기록)
2-2	생활인구(체류)	행안부 data.go.kr 15130539 (파일데이터)	XLSX(분기)	분기마다 다운로드→임포트
2-3	로컬100	문체부 mcst.go.kr / culture.go.kr	PDF/리스트	시드 + 좌표는 지오코딩 보강
2-4	관광두레	tourdure.mcst.go.kr	웹/발간물	시드 + 좌표는 TourAPI/지오코딩
2-5	7대 여행 지원 혜택	전용 API 없음(제안서 명시)	수동	수동 적재(정책명·기간·대상지·할인)

• 생활인구 주의: 정책적 "생활인구(체류인구)"는 행안부 XLSX가 정본. SGIS는 센서스 인구라 개념이 다름. 서울시 생활인구 API는 2026-06 현행화 중지.

---

3. 데이터 조합 → 제공 가능한 기능 (전부 확보 시)

기능	필요한 데이터 조합
LNT 가용시간·샌드위치 연휴	특일정보
인구감소지역 여행지 추천	인구감소지역89(seed) + TourAPI + 관광빅데이터(집중률→한산시점) + 생활인구(가중치)
정책 혜택 매칭·뱃지	7대혜택(seed) + 인구감소지역 + 로컬100/관광두레(seed)
교통·도착시각 (반차/퇴근후)	TAGO 버스/열차 + 코레일 + TMAP(자가용)
일정 자동 생성	TourAPI(운영시간/휴무) + TMAP(경유지 최적화) + 위 조합
연차 컨설팅	특일정보 (+ 위 전체)

---

4. "모든 걸 미리 준비" 실행 제약 (설계에 반영)

• SRT 공공API 없음 → SRT 시간표는 제외하거나 별도 처리. KTX는 TAGO로.
• 시외버스 미래날짜 조회 불가(당일만) → 미래 일정은 "예상 소요시간"으로 근사, 실시간은 당일에.
• TMAP 24h 저장 제한 → 경로 결과는 단기 캐시(≤24h)만. 영구 저장 금지.
• 개발계정 한도(TourAPI/빅데이터 1,000/일, TMAP 최적화 50/일) → 대량 사전적재는 배치·페이징·운영계정 전환 고려.
• 지역코드 불일치(TourAPI sigunguCode ↔ 빅데이터 코드 ↔ 인구감소지역 지명) → 지명 기준 매핑 테이블을 먼저 구축(마스터 데이터).
• Encoding/Decoding 서비스키 두 개 다 보관.

---

5. 발급 체크리스트 (본인 액션)

• data.go.kr 회원가입 (휴대폰 본인인증)
• 활용신청: 특일정보(15012690) · 국문관광정보(15101578) · 관광빅데이터(15101972) · TAGO 버스도착(15098530)·고속(15098522)·시외(15098541)·열차(15098552) · 코레일(15125762) · 생활인구 파일(15130539)
• 발급된 serviceKey(Encoding+Decoding) 확보
• openapi.sk.com 회원가입 → 앱 등록 → TMAP appKey 발급
• (선택) SGIS 개발지원센터 key/secret
• 정적 데이터 다운로드: 인구감소지역 89곳 · 생활인구 XLSX · 로컬100 리스트 · 관광두레 목록
• 7대 혜택 정보 수동 정리(정책명·운영기간·대상지·할인율)

---

6. 볼거리 보강 후보 (미연동)

2026-07-21 조사. TourAPI만으론 볼거리가 부족한 소도시(영양 10개급) 보강용 추가 소스. 아래는 후보이며 아직 클라이언트 미구현. 이미 우리가 쓰는 소스(특일정보·TourAPI·관광빅데이터·TAGO·코레일·TMAP)는 그대로 유지한다. 관련 이슈 #44.

6-1. 국가유산 정보 (문화재) — 국가유산청 ⭐ 키 불필요, 즉시 사용 가능

• 인증: 없음 (API key·로그인·프록시 불필요). GET · XML 응답 · User-Agent 헤더 필요 · timeout ~20s
• 목록: https://www.khs.go.kr/cha/SearchKindOpenapiList.do
  • params: ccbaMnm1(유산명 검색어) · ccbaCtcd(시도코드 2자리) · pageUnit(1~100) · pageIndex · ccbaCncl=N(지정해제 제외)
  • item 필드: ccbaMnm1(명) · ccbaMnm2(한자) · ccbaCtcdNm(시도명) · ccbaAdmin(관리기관) · latitude · longitude · ccbaKdcd(종목코드) · ccbaAsno(관리번호) · ccbaCtcd(시도코드)
• 상세: https://www.khs.go.kr/cha/SearchKindOpenapiDt.do — params ccbaKdcd+ccbaAsno+ccbaCtcd → 설명(content)·주소·좌표·이미지
• 행사: https://www.khs.go.kr/cha/openapi/selectEventListOpenapi.do — params 연도(YYYY)·월(1~12) → 행사명·기간·지역·본문(subContent)·링크(subPath)
• ⭐ 좌표 제공 → 지명·좌표로 우리 region/POI에 매핑. TourAPI contentTypeId=14(문화시설) 계열 볼거리 보강.
• 함정: 공식 페이지 명시 한도 확인 필요. 지명↔시도코드 매핑 테이블 선구축(우리 89 지명 기준).
• OffWay 용도: 콘텐츠 충분성(#21)에서 인접 50km 확장 전 자체 볼거리 확대 · 지역 상세에 문화재·이달의 행사.

6-2. 날씨 (기상청) — 채택. 남은 일수로 세 API 를 갈아탄다

여행까지 남은 일수에 따라 담당이 갈린다. 실호출 확인(2026-08-03), 전부 기존 DATA_GO_KR 키로 동작.

남은 일수	API	base	주는 것
0~3일	단기예보	VilageFcstInfoService_2.0	기온·하늘상태·강수확률
4~10일	중기 육상예보	MidFcstInfoService	하늘상태·강수확률 (기온 없음)
1~9일	관광기후지수	TourStnInfoService1	관광 적합도 지수·등급
11일 이상	없음	—	예보가 존재하지 않는 구간(#133 평년값으로)

⚠️ VilageFcstInfoService (구버전)는 폐기됐다. NO_OPENAPI_SERVICE_ERROR(해당 오픈API 서비스가 없거나 폐기됨)가 온다. _2.0 을 써야 한다. 스키마·파라미터는 같아 base 만 다르다. 날씨는 부가 정보라 실패해도 코스가 200 으로 나가는 탓에 경로가 죽은 줄 모르고 지냈다(#128) — E2E 로 접점을 고정했다.

단기예보 VilageFcstInfoService_2.0/getVilageFcst

• 입력: 격자 nx/ny(위경도 변환 필요) · base_date/base_time(발표 02·05·08·11·14·17·20·23시)
• 실측: 907건 · 121KB · 1.15초. 예보는 오늘D+4 가 오되 **최저기온(TMN)까지 완전한 날은 D+1D+3**

중기 육상예보 MidFcstInfoService/getMidLandFcst

• 입력: regId(광역 10개 구역) · tmFc(발표 06·18시, yyyyMMddHHmm)
• 응답이 한 행에 D+4~D+10 이 컬럼으로 들어온다(wf4Am···wf10). D+7 까지만 오전/오후가 나뉘고 D+8 부터는 하루 하나
• 구역 코드 10종 전부 응답 확인: 11B00000(서울·인천·경기) 11D10000(강원영서) 11D20000(강원영동) 11C10000(충북) 11C20000(대전·세종·충남) 11F10000(전북) 11F20000(광주·전남) 11H10000(대구·경북) 11H20000(부산·울산·경남) 11G00000(제주)
• ⚠️ 기온(getMidTa)은 다른 코드 체계다. 시군 단위 지점 코드를 쓰는데, 광역 구역 코드를 넣으면 오류가 아니라 resultCode 00 에 taMin4=0 이 온다. 응답에 지점명이 없어 코드를 열거해 찾을 수도 없다(찾아도 어느 시군인지 모른다). 지점 코드 확보 전까지 중기 기온은 비워 둔다

관광기후지수 TourStnInfoService1/getCityTourClmIdx1

• 입력: CURRENT_DATE(yyyyMMddHH) · HOUR(산출 범위, 24) · DAY
• ⚠️ 포털이 base 를 TourStnInfoService11 로 표기하나 실제로는 TourStnInfoService1(1 이 하나). 11 은 404
• ⚠️ DAY 는 며칠 뒤가 아니라 며칠치다. DAY=9 면 D+9 하루가 아니라 D+1~D+9 아홉 날이 한꺼번에 온다(totalCount 가 236 × DAY 로 증가). 오프셋으로 착각해 날짜마다 부르면 같은 데이터를 아홉 번 받는다
• ⚠️ 상한을 넘겨도 오류가 없다. DAY=10·DAY=12 모두 D+9 값을 그대로 준다. 요청 날짜로 라벨을 붙이면 조용히 틀리므로 응답 tm 으로 검증한다
• DAY=0(오늘)은 NO_DATA — 조회 가능 범위는 D+1~D+9
• 실측: DAY=9 기준 2,124건(9일 × 236 시군구) · 347KB · 2.5초. WebClient maxInMemorySize(2MB) 안에 들어온다
• ⚠️ cityAreaId 는 법정동코드가 아니다. 우리 region.legal_code 로 조인하면 89곳 중 51곳만 맞는다 — 강원은 42xxx(특별자치도 전환 전), 전북은 45xxx, 광주+전남은 비표준 12xxx 로 묶여 있다. 시군구명(시도+시군구)으로 맞추면 89/89
• 응답 필드: tm · totalCityName · doName(축약 시도명 17종) · cityName · cityAreaId · kmaTci · TCI_GRADE

6-3. 미세먼지 (에어코리아) — 후보, 우리 키로 직접 호출

• upstream: 에어코리아(한국환경공단) 대기오염정보. 측정소명(행정구역) 기반 조회.
• 용도: 지역 카드에 대기질 뱃지. Nice-to-have.

6-4. (검토) 공연/전시·자연휴양림 — 추가 키/스크래핑 필요

• KOPIS 공연예술통합전산망: 공연·전시(체험거리). 별도 KOPIS 키 발급 필요 → 우선순위 낮음.
• 숲나들e(자연휴양림, foresttrip.go.kr): 7대 혜택 농촌체험/치유관광과 매핑되나 공식 API 없이 스크래핑 → 백엔드 안정성 낮아 보류.

참고: KTX/SRT 예매 — 채택 안 함

• 시중에 도는 ktx/srt 연동은 비공식 라이브러리(korail2-ncard/SRTrain) + 개인 로그인 계정 + anti-bot 토큰 기반이라 공개 서비스 백엔드에 부적합. 열차는 §1-4 TAGO(KTX 포함)·§1-5 코레일 공식 API를 유지한다. (§4의 "SRT 공공API 없음" 재확인.)