# 추천 외부 API / 라이브러리 공통 리스트

세미클래스 "나만의 웹사이트 만들기" 시리즈 공통 자료입니다.

이 문서는 특정 수강생 포트폴리오에 맞춘 분석이 아니라, 대부분의 초보 웹사이트 프로젝트에서 고를 수 있는 외부 API와 프론트엔드 라이브러리 후보를 정리한 자료입니다.

마지막 확인일: 2026-07-04

## 먼저 기억할 원칙

- 수업 시간에는 API 1개 또는 라이브러리 1개만 제대로 붙여도 충분합니다.
- API key, secret, token은 브라우저 코드에 넣지 않습니다.
- 외부 API는 먼저 sample JSON으로 화면을 만든 뒤, 서버 route에서 실제 API를 호출합니다.
- 라이브러리는 "직접 만들기 어렵거나 오래 걸리는 부분"에만 씁니다.
- 공식 문서, 무료 범위, 호출 제한, 이용약관은 실제 적용 직전에 다시 확인합니다.

## 빠른 추천

| 하고 싶은 것 | 먼저 볼 API / 라이브러리 | 초보자 추천도 | 이유 |
|---|---|---:|---|
| 날씨 카드 | Open-Meteo | ★★★★★ | API key 없이 시작 가능 |
| 환율/통화 변환 | Frankfurter | ★★★★★ | API key 없이 시작 가능 |
| 국내 공공 데이터 | 공공데이터포털 | ★★★★☆ | 데이터가 다양하지만 인증키와 응답 형식 확인 필요 |
| 서울 지역 데이터 | 서울 열린데이터광장 | ★★★★☆ | 서울시 교통, 문화, 시설 데이터에 좋음 |
| 주소/장소 검색 | Kakao Local API | ★★★☆☆ | 국내 장소 검색에 강하지만 REST API key 필요 |
| 내 GitHub 프로젝트 표시 | GitHub REST API | ★★★★☆ | 포트폴리오에 자연스럽고 문서가 좋음 |
| 유튜브 영상 목록 | YouTube Data API | ★★★☆☆ | 활용도 높지만 quota와 Google Cloud 설정 필요 |
| Notion을 CMS처럼 쓰기 | Notion API | ★★★☆☆ | 콘텐츠 관리에 좋지만 권한 연결을 이해해야 함 |
| Google Sheet를 간단 DB처럼 쓰기 | Google Sheets API | ★★★☆☆ | 운영자가 표로 관리하기 좋지만 권한 설정이 변수 |
| AI 요약/추천 | OpenAI API | ★★☆☆☆ | 강력하지만 비용과 비밀키 관리가 중요 |
| 아이콘 | lucide-react | ★★★★★ | 버튼/메뉴/상태 표시를 깔끔하게 만들기 쉬움 |
| 그래프 | Recharts | ★★★★☆ | 방문자, 매출, 통계 카드에 좋음 |
| 이미지 슬라이드 | Embla Carousel | ★★★★☆ | 갤러리/후기/작품 슬라이드에 좋음 |
| 폼 입력 | React Hook Form + Zod | ★★★★☆ | 신청폼, 문의폼, 프로필 편집에 좋음 |
| 날짜 표시 | date-fns | ★★★★★ | 날짜 포맷과 계산을 쉽게 처리 |
| 부드러운 애니메이션 | Motion | ★★★★☆ | 등장 효과, hover, 페이지 전환에 좋음 |
| 지도 UI | Leaflet + React Leaflet | ★★★☆☆ | 지도 화면이 필요할 때 선택 |
| API 데이터 캐시 | TanStack Query | ★★★☆☆ | API 호출이 여러 화면에 반복될 때 선택 |
| PWA 고도화 | Next.js PWA 가이드 / Serwist | ★★☆☆☆ | 4강 이후 숙제 또는 심화로 적합 |

## 추천 외부 API

### 1. Open-Meteo

- 공식 문서: https://open-meteo.com/en/docs
- 용도: 날씨, 기온, 강수확률, 위치 기반 날씨 카드
- 인증: 기본 사용은 API key 없이 가능
- 수업 예시: 카페 사이트의 "오늘의 날씨와 추천 메뉴", 여행 사이트의 "이번 주 날씨"
- 주의: 상업적 사용, 호출량, attribution 조건은 적용 전 확인
- 추천 구조: 브라우저 화면 -> 우리 서버 route -> Open-Meteo -> 화면용 날씨 카드

### 2. Frankfurter

- 공식 문서: https://frankfurter.dev/
- 용도: 환율, 통화 변환, 해외 가격 표시
- 인증: API key 없이 가능
- 수업 예시: 해외 제품 큐레이션, 여행 경비 계산, 원화/달러 가격 비교
- 주의: 실시간 시세가 아니라 기준 환율 데이터로 이해하기
- 추천 구조: 서버 route에서 환율을 가져오고, 실패하면 sample 환율 JSON 사용

### 3. 공공데이터포털

- 공식 가이드: https://www.data.go.kr/ugs/selectPublicDataUseGuideView.do
- 용도: 보건, 교통, 문화, 관광, 행정, 지역 정보
- 인증: 활용신청 후 OpenAPI 인증키 발급
- 수업 예시: 동네 행사 정보, 병원/약국 정보, 관광지 정보, 공공 시설 안내
- 주의: API마다 응답 형식과 승인 방식이 다를 수 있음
- 추천 구조: 먼저 API 명세의 샘플 응답을 보고 sample JSON부터 만들기

### 4. 서울 열린데이터광장

- 공식 안내: https://data.seoul.go.kr/together/guide/useGuide.do
- 용도: 서울시 교통, 문화, 시설, 실시간 도시 데이터
- 인증: 인증키 발급 필요
- 수업 예시: 서울 행사 캘린더, 따릉이/지하철/문화시설 정보
- 주의: 일부 API는 요청 횟수 제한이 있으니 수업 데모에서는 캐시 또는 fallback 준비
- 추천 구조: 서버 route에서 호출하고, 화면은 정리된 카드 데이터만 받기

### 5. Kakao Local API

- 공식 문서: https://developers.kakao.com/docs/latest/en/local/dev-guide
- 용도: 주소 검색, 좌표 변환, 키워드 장소 검색
- 인증: Kakao Developers 앱의 REST API key 필요
- 수업 예시: 매장 위치 검색, 주변 장소 추천, 주소를 지도 좌표로 변환
- 주의: REST API key는 서버 route에서 사용하고 브라우저에 직접 노출하지 않기
- 추천 구조: 검색어 -> 우리 서버 route -> Kakao Local API -> 장소 카드 배열

### 6. GitHub REST API

- 공식 문서: https://docs.github.com/en/rest
- rate limit 문서: https://docs.github.com/rest/rate-limit/rate-limit
- 용도: 내 GitHub 저장소, 프로젝트, 최근 활동 표시
- 인증: 공개 저장소 조회는 무인증으로도 가능하지만 제한이 있음
- 수업 예시: 개발자 포트폴리오의 "최근 프로젝트" 섹션
- 주의: 호출 제한이 있으므로 서버 route 캐시 또는 정적 fallback 추천
- 추천 구조: GitHub 응답을 그대로 화면에 쓰지 말고 project card 타입으로 변환

### 7. YouTube Data API

- 공식 문서: https://developers.google.com/youtube/v3
- quota 문서: https://developers.google.com/youtube/v3/determine_quota_cost
- 용도: 채널 영상 목록, 추천 영상, 재생목록 표시
- 인증: Google Cloud 설정과 API key 필요
- 수업 예시: 강사/브랜드/가게의 유튜브 콘텐츠 모아보기
- 주의: quota 비용이 메서드마다 다르므로 search를 남발하지 않기
- 추천 구조: 서버 route에서 최신 영상 몇 개만 가져오고, 실패하면 고정 추천 영상 표시

### 8. Notion API

- 공식 개요: https://developers.notion.com/guides/get-started/overview
- 빠른 시작: https://developers.notion.com/guides/get-started/quick-start
- 용도: Notion 페이지나 데이터베이스를 간단 CMS처럼 사용
- 인증: Notion integration token 필요
- 수업 예시: 공지사항, 블로그 글, 행사 목록을 Notion에서 관리
- 주의: integration token은 서버에서만 사용하고, 공유 권한을 반드시 확인
- 추천 구조: Notion DB -> 서버 route -> 화면용 글 목록

### 9. Google Sheets API

- 공식 개요: https://developers.google.com/workspace/sheets/api/guides/concepts
- 용도: 운영자가 스프레드시트로 관리하는 표 데이터를 웹사이트에 표시
- 인증: 공개 데이터는 API key, 비공개 데이터는 OAuth 등 추가 설정 필요
- 수업 예시: 수업 일정표, 메뉴판, 가격표, 신청 현황
- 주의: 권한 설정이 헷갈릴 수 있으니 수업에서는 공개 샘플 또는 CSV 공개 링크부터 시작
- 추천 구조: Sheet 데이터를 서버 route에서 읽고, 화면용 배열로 정리

### 10. OpenAI API

- 공식 빠른 시작: https://developers.openai.com/api/docs/quickstart
- 용도: AI 요약, 추천 문구 생성, 리뷰 요약, 챗봇
- 인증: OpenAI API key 필요
- 수업 예시: 사용자가 입력한 취향을 바탕으로 추천 문구 만들기
- 주의: 비용, 개인정보, 비밀키 관리가 중요하므로 초보 수업에서는 심화 주제로 분리
- 추천 구조: 브라우저 -> 우리 서버 route -> OpenAI API -> 짧은 결과만 화면 표시

## 추천 프론트엔드 라이브러리

### 1. lucide-react

- 공식 문서: https://lucide.dev/guide/react
- 설치: `npm install lucide-react`
- 용도: 버튼, 메뉴, 상태, 툴바 아이콘
- 추천 상황: 거의 모든 사이트
- 주의: 아이콘을 너무 많이 쓰지 말고 의미가 분명한 곳에만 사용

### 2. Recharts

- 공식 문서: https://recharts.org/
- 설치: `npm install recharts`
- 용도: 막대그래프, 선그래프, 원형차트
- 추천 상황: 통계, 매출, 방문자, 설문 결과를 보여주는 사이트
- 주의: 데이터가 3개 이하라면 숫자 카드가 더 쉬울 수 있음

### 3. Embla Carousel

- 공식 문서: https://www.embla-carousel.com/
- React 문서: https://www.embla-carousel.com/docs/get-started/react
- 설치: `npm install embla-carousel-react`
- 용도: 이미지 슬라이드, 후기 슬라이드, 작품 갤러리
- 추천 상황: 포트폴리오, 브랜드 소개, 제품 소개
- 주의: 모바일에서 손가락으로 넘기는 동작까지 확인

### 4. React Hook Form + Zod

- React Hook Form 문서: https://react-hook-form.com/get-started
- Zod 문서: https://zod.dev/
- 설치: `npm install react-hook-form zod`
- 용도: 문의폼, 신청폼, 프로필 편집, 댓글 입력 검증
- 추천 상황: 입력칸이 3개 이상이고 검증이 필요한 폼
- 주의: 처음에는 이름/이메일/메시지 정도의 작은 폼부터 시작

### 5. date-fns

- 공식 문서: https://date-fns.org/docs/Getting-Started
- 설치: `npm install date-fns`
- 용도: 날짜 포맷, D-day, 오늘/이번 주 계산
- 추천 상황: 행사, 예약, 일정, 블로그 날짜 표시
- 주의: 한국어 표시가 필요하면 locale 설정을 함께 확인

### 6. Motion

- 공식 문서: https://motion.dev/docs/react
- 설치: `npm install motion`
- 용도: 등장 애니메이션, hover 효과, 부드러운 전환
- 추천 상황: 랜딩 페이지, 카드 등장, 갤러리 상호작용
- 주의: 애니메이션은 기능이 동작한 뒤 마지막에 얹기

### 7. Leaflet + React Leaflet

- React Leaflet 문서: https://react-leaflet.js.org/docs/start-introduction/
- 설치: `npm install leaflet react-leaflet`
- 용도: 지도 표시, 마커, 위치 안내
- 추천 상황: 매장 위치, 여행 코스, 지역 기반 서비스
- 주의: 지도 타일 제공자의 이용약관과 attribution 표시를 확인

### 8. TanStack Query

- 공식 문서: https://tanstack.com/query/latest/docs/framework/react/overview
- 설치: `npm install @tanstack/react-query`
- 용도: API 데이터 가져오기, 캐시, 재시도, 로딩/에러 상태 관리
- 추천 상황: 여러 화면에서 같은 API 데이터를 반복해서 쓰는 경우
- 주의: 간단한 한 번짜리 fetch에는 과할 수 있음

### 9. Next.js PWA 기본 기능 / Serwist

- Next.js PWA 가이드: https://nextjs.org/docs/app/guides/progressive-web-apps
- Serwist 문서: https://serwist.pages.dev/docs/next
- 용도: 앱 설치, manifest, service worker, 오프라인 fallback, Push 알림 심화
- 추천 상황: 4강 PWA 확장 또는 숙제
- 주의: Push 알림은 권한 요청, 구독 저장, 서버 발송까지 필요하므로 작은 데모로 시작

## 수업 중 고르는 방법

### API를 고를 때

1. API key가 없어도 되는지 확인합니다.
2. key가 필요하면 서버 route가 필요한지 확인합니다.
3. 공식 문서에 샘플 응답이 있는지 확인합니다.
4. 실패했을 때 보여줄 sample JSON을 먼저 만듭니다.
5. 수업 시간에는 목록 3개 또는 카드 1개만 화면에 붙입니다.

### 라이브러리를 고를 때

1. 직접 만들면 오래 걸리는 UI인지 확인합니다.
2. 설치 명령이 간단한지 확인합니다.
3. 예제가 React/Next.js에 맞는지 확인합니다.
4. 기존 디자인을 망치지 않는 작은 범위에서 붙입니다.
5. 라이브러리를 추가한 이유를 README나 작업 기록에 남깁니다.

## 코딩 에이전트에게 요청하는 프롬프트

아래 프롬프트는 Codex나 Claude Code에 붙여넣어 사용할 수 있습니다.

```text
내 웹사이트에 외부 API 또는 라이브러리 하나를 붙이고 싶어.

아직 구현하지 말고 먼저 추천만 해줘.

내 사이트를 살펴본 뒤 아래 기준으로 골라줘.
- 수업 시간 안에 작게 성공할 수 있는가
- API key나 secret이 브라우저에 노출되지 않는가
- 공식 문서와 예제가 충분한가
- 실패했을 때 fallback 데이터를 둘 수 있는가
- 기존 디자인을 크게 망치지 않는가

결과는 아래 형식으로 정리해줘.
1. 추천 1순위
2. 추천 이유
3. 필요한 설치 명령 또는 환경변수
4. 수정 예상 파일
5. 초보자용 설명
6. 구현 전 확인할 질문 2개

내가 승인하기 전까지 파일을 수정하지 마.
```

## 출처

- Open-Meteo: https://open-meteo.com/en/docs
- Frankfurter: https://frankfurter.dev/
- 공공데이터포털: https://www.data.go.kr/ugs/selectPublicDataUseGuideView.do
- 서울 열린데이터광장: https://data.seoul.go.kr/together/guide/useGuide.do
- Kakao Local API: https://developers.kakao.com/docs/latest/en/local/dev-guide
- GitHub REST API: https://docs.github.com/en/rest
- YouTube Data API: https://developers.google.com/youtube/v3
- Notion API: https://developers.notion.com/guides/get-started/overview
- Google Sheets API: https://developers.google.com/workspace/sheets/api/guides/concepts
- OpenAI API: https://developers.openai.com/api/docs/quickstart
- Lucide React: https://lucide.dev/guide/react
- Recharts: https://recharts.org/
- Embla Carousel: https://www.embla-carousel.com/
- React Hook Form: https://react-hook-form.com/get-started
- Zod: https://zod.dev/
- date-fns: https://date-fns.org/docs/Getting-Started
- Motion: https://motion.dev/docs/react
- React Leaflet: https://react-leaflet.js.org/docs/start-introduction/
- TanStack Query: https://tanstack.com/query/latest/docs/framework/react/overview
- Next.js PWA: https://nextjs.org/docs/app/guides/progressive-web-apps
- Serwist: https://serwist.pages.dev/docs/next