# API 서비스 개요

## 📋 API 서비스 소개

JinyPHP Locale Server는 **우편번호 및 주소 정보를 제공하는 RESTful API 서비스**입니다.
이 서비스는 Google Places API와 연동하여 전 세계 주소 및 우편번호 정보를 조회하고,
데이터베이스에 캐싱하여 빠른 응답 속도를 제공합니다.

### 주요 특징

- **Proxy API 역할**: 데이터베이스에 없는 정보를 Google Places API에서 자동으로 조회하여 저장
- **캐싱 기능**: 한 번 조회한 데이터는 데이터베이스에 저장하여 재사용 (빠른 응답)
- **다양한 검색 방식**: 우편번호, 주소, Place ID로 검색 가능
- **다국가 지원**: ISO 국가 코드 기반 다국가 주소 정보 제공
- **자동 데이터 동기화**: Google Places API로부터 최신 정보 자동 조회 및 저장

---

## 🔄 API 동작 방식

### Proxy API 동작 흐름

```
사용자 요청
↓
1. 데이터베이스에서 데이터 조회
↓
2. 데이터베이스에 데이터가 있는가?
├─ YES → 데이터베이스 데이터 반환 (빠른 응답)
└─ NO → Google Places API 조회
↓
3. 조회한 데이터를 데이터베이스에 저장
↓
4. 저장한 데이터 반환
```

### 상세 동작 과정

1. **데이터베이스 조회**: 요청된 우편번호/주소 정보가 데이터베이스에 존재하는지 확인
2. **Google Places API 조회**: 데이터베이스에 데이터가 없거나 정확히 일치하지 않는 경우 Google Places API 호출
3. **데이터 저장**: Google Places API로부터 조회한 정보를 데이터베이스에 저장 (Place ID 기준 중복 방지)
4. **결과 반환**: 조회한 정보를 JSON 형식으로 반환

---

## 🌐 Base URL

```
http://your-domain.com/api/v1/zipcode
```

---

## 📊 공통 응답 형식

### 성공 응답

```json
{
"success": true,
"message": "우편번호 정보를 조회했습니다.",
"data": {
"id": 1,
"country_code": "KR",
"zipcode": "06042",
"state": "서울특별시",
"state_en": "Seoul",
"city": "강남구",
"city_en": "Gangnam-gu",
"formatted_address": "서울특별시 강남구 테헤란로",
"latitude": 37.5010,
"longitude": 127.0394,
"place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4",
"retrieved_from": "database"
}
}
```

### 오류 응답

```json
{
"success": false,
"message": "우편번호 정보를 찾을 수 없습니다.",
"data": null
}
```

### 검증 오류 응답

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

---

## 📍 주요 엔드포인트

- **[우편번호 검색](/docs/zipcode)**: 우편번호로 주소 정보 조회 (한국, 일본, 미국, 중국 지원)
- **[주소 검색](/docs/address)**: 주소로 우편번호 및 상세 정보 조회
- **[Place ID 검색](/docs/place)**: Google Places API Place ID로 정보 조회

### 다국가 지원

현재 다음 국가의 우편번호 체계를 지원합니다:
- 🇰🇷 **한국 (KR)**: 5자리 숫자, 4단계 행정구역 (시/도 → 시군구 → 읍면동 → 상세주소)
- 🇯🇵 **일본 (JP)**: 7자리 (하이픈 포함), 3단계 행정구역 (도도부현 → 시정촌 → 구/정)
- 🇺🇸 **미국 (US)**: ZIP Code (5자리 또는 ZIP+4), 3단계 행정구역 (State → County → City)
- 🇨🇳 **중국 (CN)**: 6자리 숫자, 3단계 행정구역 (성/시 → 시/구 → 구/현)

---

## 📊 응답 데이터 필드 설명

### 주요 필드

| 필드명 | 타입 | 설명 |
|--------|------|------|
| `id` | integer | 데이터베이스 레코드 ID |
| `country_code` | string | 국가 코드 (ISO 3166-1 alpha-2) |
| `zipcode` | string | 우편번호 |
| `state` | string | 주/도 (한국어) |
| `state_en` | string | 주/도 (영어) |
| `city` | string | 시/군/구 (한국어) |
| `city_en` | string | 시/군/구 (영어) |
| `formatted_address` | string | 포맷된 전체 주소 |
| `latitude` | float | 위도 |
| `longitude` | float | 경도 |
| `place_id` | string | Google Places API Place ID |
| `retrieved_from` | string | 조회 출처 (`database` 또는 `google`) |

### `retrieved_from` 필드

- `database`: 데이터베이스에서 조회한 데이터 (빠른 응답)
- `google`: Google Places API에서 새로 조회한 데이터 (처음 조회 또는 업데이트)

---

## ⚠️ 오류 처리

### HTTP 상태 코드

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

---

## 🔧 설정 요구사항

### 환경 변수

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` | 대한민국 | 5자리 숫자 | `06042` |
| `JP` | 일본 | 7자리 (하이픈 포함) | `150-0001` |
| `US` | 미국 | ZIP Code (5자리 또는 ZIP+4) | `90210` 또는 `90210-1234` |
| `CN` | 중국 | 6자리 숫자 | `100000` |

**상세 정보**: [국가별 우편번호 체계 및 조회 방식](/docs/zipcode#-국가별-우편번호-체계-및-조회-방식) 문서를 참고하세요.

### Place ID

Place ID는 Google Places API에서 제공하는 고유 식별자입니다.
동일한 장소는 항상 동일한 Place ID를 가지므로, Place ID를 사용하면
정확한 장소 정보를 조회할 수 있습니다.

### 데이터 캐싱

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

---

## 🚀 성능 최적화

### 캐싱 전략

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

### 권장 사항

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