공공데이터포털 TourAPI로 전국 축제 데이터 다루기
공공데이터포털이 무료로 제공하는 TourAPI는 지역 정보 서비스를 만들기 좋은 시작점입니다. 오늘어디를 만들면서 실전에서 반드시 챙겨야 할 것 네 가지를 정리했습니다.
TourAPI란
TourAPI는 한국관광공사가 제공하는 관광 정보 오픈 API입니다. 축제, 관광지, 문화시설, 여행코스, 음식점 등 다양한 카테고리를 포함하며, 공공데이터포털에서 개발자 등록만 하면 무료로 사용할 수 있습니다. 오늘어디의 축제 데이터는 대부분 여기서 옵니다.
축제 관련해선 크게 두 엔드포인트를 사용합니다:
areaBasedList2— 지역 기반 목록 (contentTypeId=15가 축제)searchFestival2— 기간·지역 조건으로 축제 검색
"오늘·이번주 축제"를 뽑기 위한 날짜 조건은 searchFestival2가 더 잘 맞습니다.
eventStartDate, eventEndDate로 진행 중인 축제만 필터할 수 있습니다.
페이지네이션 100건 캡 함정
첫 구현 때 numOfRows=100으로만 요청하고 끝냈습니다. 5-8월 성수기엔 전국 축제가
100건을 훨씬 초과하기 때문에, 100건 컷 때문에 뒤쪽에 있는 지역들이 잘려나갑니다.
결과적으로 특정 지역만 데이터가 표시되지 않는 조용한 버그가 됐습니다.
해결은 단순합니다. 응답의 totalCount를 먼저 확인하고, 필요한 만큼
pageNo=1,2,3,...로 순회하며 다 긁어옵니다. 대신 요청 횟수가 늘어나니
스케줄러가 하루 한 번만 도는 구조가 편합니다.
계절성: 데이터는 시즌마다 다르다
TourAPI 축제 데이터는 5-8월에 극단적으로 몰립니다. 실측치는:
- 5-8월: 월 60-100+ 건
- 11-2월: 월 5-15 건 (지역에 따라 0건도 있음)
이건 버그가 아니라 실제 데이터입니다. 처음엔 "청주가 왜 12월에 축제 1개밖에 없어?"라며 코드를 뒤졌는데, 다른 지역도 마찬가지고 총 카운트가 그렇게 나오니 인정할 수밖에 없었습니다.
UX 대응은 검색 윈도우를 "오늘"이 아니라 "오늘 + 3개월"처럼 넓히는 것입니다. 임박한 축제를 미리 노출해서 겨울에도 빈 화면이 덜 나오도록.
좌표 누락 fallback
TourAPI 응답에 mapx, mapy 필드가 있지만 일부 항목에서는 비어있습니다.
지도에 얹으려면 좌표가 필수라, 다음 순서로 처리합니다:
- mapx/mapy 있으면 그대로 사용
- 없으면
address필드로 카카오 지오코딩 호출 - 지오코딩도 실패하면 해당 항목 제외
이걸 스케줄러 안에 넣어두면 새 데이터 수집 시 자동 보강됩니다. 별도 배치 없이 자연스럽게 결손이 채워지는 구조가 유지 관리에 편합니다.
지역 코드 매핑
TourAPI는 지역을 areaCode(광역), sigunguCode(시군구)로 관리합니다.
이 코드가 앱 내부의 지역 ID(예 seoul_gangnam)와 다르기 때문에 매핑 테이블이 필요합니다.
초기에 대충 넣으면 몇몇 시·군에서 축제가 엉뚱한 지역에 잡히는 문제가 생깁니다.
정리
TourAPI로 축제 데이터를 다룰 때 실전에서 챙겨야 할 것:
- 페이지네이션 — totalCount까지 순회
- 계절성 — 겨울엔 데이터가 적은 게 정상
- 좌표 누락 fallback — 지오코딩 백필
- 지역 코드 매핑 정확성
이 넷을 초기에 챙기지 않으면, 특정 지역에서 축제가 잘 안 뜨는 조용한 버그가 누적됩니다. 유저는 "이 서비스 데이터가 부실하네"라고 느끼고 이탈합니다.