# 인증 및 제한사항

## 🔐 인증

현재 API는 인증 없이 사용할 수 있습니다. 향후 버전에서 API 키 기반 인증을 지원할 예정입니다.

---

## ⚠️ 요청 제한

### Google Places API 제한

Google Places API의 요청 제한(Quota)을 확인하고 관리해야 합니다.
데이터베이스에 캐싱된 데이터는 Google Places API 호출 없이 응답되므로,
요청 제한에 영향을 받지 않습니다.

### 권장 사항

- 자주 조회하는 우편번호/주소는 미리 조회하여 캐싱
- Place ID를 사용하면 더 정확한 결과를 얻을 수 있음
- 국가 코드를 지정하면 검색 정확도 향상

---

## 📊 오류 처리

### HTTP 상태 코드

| 상태 코드 | 설명 |
|----------|------|
| `200` | 성공 |
| `404` | 데이터를 찾을 수 없음 |
| `422` | 입력값 검증 실패 |
| `500` | 서버 오류 |

### 오류 응답 형식

```json
{
"success": false,
"message": "오류 메시지",
"data": null,
"error": "상세 오류 정보 (디버그 모드에서만 표시)"
}
```

### 검증 오류 응답

```json
{
"success": false,
"message": "입력값이 올바르지 않습니다.",
"errors": {
"zipcode": ["zipcode 필드는 필수입니다."],
"country": ["country 필드는 2자리여야 합니다."]
}
}
```

---

## 🔧 설정 요구사항

### 환경 변수

API 서비스를 사용하기 위해서는 다음 환경 변수가 설정되어 있어야 합니다:

```env
GOOGLE_PLACES_API_KEY=your_google_places_api_key_here
```

### Google Places API 키 발급

1. [Google Cloud Console](https://console.cloud.google.com/) 접속
2. 프로젝트 생성 또는 선택
3. API 및 서비스 > 라이브러리에서 "Places API" 활성화
4. 사용자 인증 정보에서 API 키 생성
5. `.env` 파일에 `GOOGLE_PLACES_API_KEY` 설정

---

## 📝 참고사항

### 국가 코드

국가 코드는 ISO 3166-1 alpha-2 형식을 사용합니다:
- `KR`: 대한민국
- `US`: 미국
- `JP`: 일본
- `CN`: 중국
- 기타 ISO 3166-1 alpha-2 코드

### 데이터 캐싱

- 한 번 조회한 데이터는 데이터베이스에 저장되어 재사용됩니다
- 동일한 요청은 데이터베이스에서 빠르게 응답합니다
- Google Places API 호출은 데이터베이스에 데이터가 없을 때만 발생합니다

---

## 🚀 성능 최적화

### 캐싱 전략

1. **데이터베이스 캐싱**: 한 번 조회한 데이터는 데이터베이스에 저장
2. **Place ID 기반 중복 방지**: 동일한 Place ID는 한 번만 저장
3. **빠른 응답**: 데이터베이스에 있는 데이터는 즉시 반환

### 권장 사항

- 자주 조회하는 우편번호/주소는 미리 조회하여 캐싱
- Place ID를 사용하면 더 정확한 결과를 얻을 수 있음
- 국가 코드를 지정하면 검색 정확도 향상

---

## 📞 지원

API 사용 중 문제가 발생하거나 질문이 있으시면 프로젝트 저장소의 이슈를 통해 문의해주세요.