# 주소 검색 API

## 📍 주소로 검색

주소를 입력하여 해당 우편번호 및 상세 정보를 조회합니다.

### 요청

```
GET /api/v1/zipcode/address?address={address}&country={country}
```

### 파라미터

| 파라미터 | 타입 | 필수 | 설명 | 예시 |
|---------|------|------|------|------|
| `address` | string | ✅ | 검색할 주소 | `서울시 강남구` |
| `country` | string | ❌ | 국가 코드 (ISO 3166-1 alpha-2) | `KR` |

### 요청 예시

```bash
# 한국 주소 검색
GET /api/v1/zipcode/address?address=서울시 강남구&country=KR

# 국가 코드 생략
GET /api/v1/zipcode/address?address=서울시 강남구
```

### 응답 예시

```json
{
"success": true,
"message": "주소 정보를 조회했습니다.",
"data": {
"id": 2,
"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": "google"
}
}
```

### 동작 방식

1. 데이터베이스에서 주소로 부분 일치 검색
2. 정확히 일치하지 않으면 Google Places API Geocoding API 호출
3. Place ID가 있으면 중복 체크 후 저장 또는 업데이트
4. 결과 반환

---

## 💻 사용 예시

### cURL

```bash
# 주소로 검색
curl "http://localhost/api/v1/zipcode/address?address=서울시 강남구&country=KR"
```

### JavaScript (Fetch API)

```javascript
// 주소로 검색
async function searchByAddress(address, country = 'KR') {
const response = await fetch(
`/api/v1/zipcode/address?address=${encodeURIComponent(address)}&country=${country}`
);
const data = await response.json();

if (data.success) {
console.log('검색 결과:', data.data);
return data.data;
} else {
console.error('오류:', data.message);
return null;
}
}

// 사용 예시
searchByAddress('서울시 강남구', 'KR');
```

### PHP (Guzzle HTTP)

```php
use GuzzleHttp\Client;

$client = new Client(['base_uri' => 'http://localhost']);

// 주소로 검색
$response = $client->get('/api/v1/zipcode/address', [
'query' => [
'address' => '서울시 강남구',
'country' => 'KR'
]
]);
$data = json_decode($response->getBody(), true);
```

### Python (Requests)

```python
import requests

base_url = 'http://localhost/api/v1/zipcode'

# 주소로 검색
response = requests.get(f'{base_url}/address', params={
'address': '서울시 강남구',
'country': 'KR'
})
data = response.json()
```

---

## 📝 참고사항

- 주소 검색은 부분 일치 검색을 지원합니다
- 국가 코드를 지정하면 검색 정확도가 향상됩니다
- 여러 결과가 반환될 수 있습니다 (배열 형태)
- Google Places API의 Geocoding API를 사용합니다