# 🔑 키 필요 없는 Open API 실습 가이드

> AI 빌더 커뮤니티 실습용 — Son님 제작

---

## 1. 왜 키 없는 API부터 시작하나요?

| 장점 | 설명 |
|------|------|
| **즉시 실행** | 회원가입/승인/키 발급 없이 바로 `curl` 가능 |
| **리스크 제로** | API 키 노출, 과금, 사용량 초과 걱정 없음 |
| **개념 집중** | HTTP 요청/응답, JSON 파싱, 상태 코드 등 핵심만 학습 |
| **빠른 피드백** | 코드 → 실행 → 결과 확인까지 10초 이내 |

---

## 2. 검증된 키 없는 API 목록

### 🌤️ 날씨 & 환경

#### Open-Meteo (날씨 예보)
```bash
# 서울 3일간 시간별 기온 + 강수확률
curl "https://api.open-meteo.com/v1/forecast?latitude=37.5665&longitude=126.9780&hourly=temperature_2m,precipitation_probability&daily=weather_code,temperature_2m_max,temperature_2m_min&timezone=Asia%2FSeoul&forecast_days=3"
```
- **특징**: 30+ 기상모델, 역사 날씨(1940년~), 해상/산악/농업 전용 파라미터
- **응답 예시**:
```json
{
  "latitude": 37.55,
  "hourly": {
    "time": ["2026-06-11T00:00", "2026-06-11T01:00", ...],
    "temperature_2m": [22.1, 21.5, 21.0, ...],
    "precipitation_probability": [0, 0, 5, ...]
  }
}
```

#### Open-Meteo Air Quality (대기질)
```bash
# 서울 미세먼지 + 자외선 지수
curl "https://air-quality-api.open-meteo.com/v1/air-quality?latitude=37.5665&longitude=126.9780&hourly=pm10,pm2_5,uv_index&timezone=Asia%2FSeoul&forecast_days=1"
```
- **특징**: CAMS 유럽 대기질 모델, PM2.5/PM10/오존/이산화질소 등

---

### 🗺️ 지리 & 위치

#### Nominatim (OpenStreetMap 주소 검색)
```bash
# "서울역" 검색 → 위도/경도 반환
curl "https://nominatim.openstreetmap.org/search?q=Seoul+Station&format=json&limit=2"
```
- **응답 예시**:
```json
[{
  "display_name": "서울역, 세종대로, 봉래동2가, 중구, 서울특별시, 04509, 대한민국",
  "lat": "37.5554175",
  "lon": "126.9725862",
  "class": "railway",
  "type": "station"
}]
```
- **주의**: 사용 정책 준수 (1초당 1요청 권장, User-Agent 필수)

---

### 📅 날짜 & 시간

#### Nager.Date (공휴일)
```bash
# 2026년 한국 공휴일
curl "https://date.nager.at/api/v3/PublicHolidays/2026/KR"
```
- **응답 예시**:
```json
[{
  "date": "2026-01-01",
  "localName": "새해",
  "name": "New Year's Day",
  "countryCode": "KR"
}]
```
- **특징**: 100+ 국가 지원, ISO 3166-1 alpha-2 국가코드 사용

---

### 📚 문화 & 데이터

#### Art Institute of Chicago (미술품 검색)
```bash
# 모네 작품 검색
curl "https://api.artic.edu/api/v1/artworks/search?q=monet&limit=2&fields=id,title,artist_display,image_id"
```
- **응답 예시**:
```json
{
  "data": [{
    "id": 16568,
    "title": "Water Lilies",
    "artist_display": "Claude Monet (French, 1840–1926)",
    "image_id": "3c27b499-af56-f0d5-93b5-a7f2f1ad5813"
  }]
}
```
- **이미지 URL**: `https://www.artic.edu/iiif/2/{image_id}/full/843,/0/default.jpg`

#### Open Library (도서 검색)
```bash
# 책 검색
curl "https://openlibrary.org/search.json?q=atomic+habits&limit=2"
```
- **특징**: ISBN, 저자, 출판년도, 표지 이미지, 전자책 유무

#### GBIF (생물종 데이터)
```bash
# 생물종 검색
curl "https://api.gbif.org/v1/species/search?q=cat&limit=2"
```
- **특징**: 20억+ 생물 기록, 학명/분류계층/서식지 데이터

---

### 🧪 테스트 & 샘플

#### JSONPlaceholder (가상 REST API)
```bash
# 할일 1개 조회
curl "https://jsonplaceholder.typicode.com/todos/1"
```
- **응답 예시**:
```json
{
  "userId": 1,
  "id": 1,
  "title": "delectus aut autem",
  "completed": false
}
```
- **특징**: GET/POST/PUT/DELETE 모두 지원, CRUD 전 과정 실습 가능

#### DummyJSON (가상 쇼핑 데이터)
```bash
# 상품 검색
curl "https://dummyjson.com/products/search?q=phone&limit=2"
```
- **특징**: 100+ 제품, 카테고리, 가격, 재고, 리뷰, 장바구니 API

---

### 🌍 기타 유용한 API

| API | 엔드포인트 예시 | 용도 |
|-----|----------------|------|
| **Open Brewery DB** | `api.openbrewerydb.org/v1/breweries?by_city=san_diego` | 지역 맥주 양조장 검색 |
| **USGS 지진** | `earthquake.usgs.gov/.../2.5_day.geojson` | 최근 지진 GeoJSON 피드 |
| **ISS 현재 위치** | `api.open-notify.org/iss-now.json` | 국제우주정거장 실시간 위치 |

---

## 3. 실생활 적합 시스템 예시 5가지

### 예시 1: 🌤️ 오늘의 외출 판단기
**조합**: Open-Meteo(날씨) + Open-Meteo Air(대기질)
```
입력: 현재 위치(위도/경도)
↓
API 호출: 기온 + 강수확률 + 미세먼지 + 자외선
↓
판단 로직:
  - 강수확률 > 60% → "우산 챙기세요"
  - PM2.5 > 75 → "마스크 권장"
  - UV > 6 → "자외선 차단제 필수"
  - 기온 < 5°C → "패딩 필수"
↓
출력: 한 줄 요약 + 상세 수치
```
**실습 포인트**: 조건문 + JSON 파싱 + 사용자 입력 처리

---

### 예시 2: 🗺️ 주소 → 좌표 변환기 (지오코딩)
**조합**: Nominatim
```
입력: "서울역" 또는 "강남구 테헤란로 152"
↓
API 호출: 주소 문자열 → 위도/경도 반환
↓
출력: 지도 링크 (Google Maps / Naver Map) + 행정구역 정보
```
**실습 포인트**: URL 인코딩, 배열 파싱, 외부 링크 생성

---

### 예시 3: 📅 영업일 계산기
**조합**: Nager.Date(공휴일) + Python 날짜 연산
```
입력: 시작일, 종료일, 국가코드(KR)
↓
API 호출: 해당 기간 공휴일 목록
↓
계산: 전체 일수 - 주말 수 - 공휴일 수
↓
출력: 실제 영업일 수 + 공휴일 목록
```
**실습 포인트**: 날짜 연산, 리스트 필터링, 국가 코드 파라미터화

---

### 예시 4: 🎨 랜덤 미술품 추천기
**조합**: Art Institute of Chicago
```
입력: 작가명 또는 키워드 ("monet", "impressionism")
↓
API 호출: 작품 검색
↓
랜덤 선택: 결과 중 1개
↓
출력: 제목 + 작가 + 이미지 URL + "이 작품을 알고 있나요?"
```
**실습 포인트**: 랜덤 선택, 이미지 URL 조합, 간단한 퀴즈 UI

---

### 예시 5: 📝 개인 할일 관리 (CRUD 실습)
**조합**: JSONPlaceholder
```
기능:
  - GET /todos/1 → 할일 조회
  - POST /todos → 새 할일 생성
  - PUT /todos/1 → 할일 수정
  - DELETE /todos/1 → 할일 삭제
↓
출력: 각 작업의 HTTP 상태 코드 + 응답 본문
```
**실습 포인트**: HTTP 메서드 차이, 상태 코드(200/201/404), JSON 직렬화

---

## 4. 실습 워크플로우 (30분 커리큘럼)

| 단계 | 시간 | 활동 |
|------|------|------|
| 1 | 5분 | `curl`로 API 직접 호출해보기 |
| 2 | 5분 | 응답 JSON 구조 파악 (pretty-print) |
| 3 | 10분 | Python/JS로 요청 → 파싱 → 출력 |
| 4 | 5분 | 조건문/필터로 "의미 있는" 결과 만들기 |
| 5 | 5분 | 사용자 입력 받아서 동적으로 호출 |

---

## 5. 주의사항 & 사용 정책

| API | 제한사항 |
|-----|---------|
| **Nominatim** | 1초당 1요청 권장. 상업적 대량 사용 시 자체 서버 구축 권장 |
| **Open-Meteo** | 비상업용 무료. 상업용은 contact 필요 |
| **JSONPlaceholder** | 가상 데이터이므로 POST/PUT/DELETE도 실제 저장되지 않음 (테스트용) |
| **Nager.Date** | 100+ 국가 지원, rate limit 넉넉함 |

---

## 6. 다음 단계 (키 필요 API로 확장)

이 시스템들에 키 필요 API를 추가하면:

| 현재 시스템 | 추가 API | 확장 기능 |
|------------|---------|----------|
| 날씨 판단기 | OpenWeatherMap(무료 티어) | 도시명 입력, 더 상세한 날씨 코드 |
| 주소 변환기 | Kakao 지도 API | 한국 주소 특화, 정확한 행정동 정보 |
| 영업일 계산 | 한국은행 Open API | 환율 + 영업일 통합 |
| 미술품 추천 | DALL-E / Stable Diffusion | "이 작품 스타일로 AI 이미지 생성" |
| 할일 관리 | Notion API | 실제 데이터 저장 + 동기화 |

---

> 💡 **핵심 원칙**: 키 없는 API로 "요청-응답-파싱-출력"의 흐름을 익힌 뒤, 키 필요 API로 교체하면 90% 코드 재사용 가능합니다.