Socar Zone Search

• 실제 예약/결제를 자동화해야 하는 경우
• 쏘카 계정 로그인이 필요한 경우 (내 예약 확인 등)
• 쏘카 이외의 카셰어링 서비스 비교가 필요한 경우

Prerequisites

• Python 3.10+
• curl (HTTP/2 지원 필요, macOS/Linux 기본 제공)
• 인터넷 연결

Inputs

• 검색 키워드 (지역명, 역이름, 랜드마크 등)
• 대여 시작 시각 (YYYYMMDD_HHMM, KST 기준)
• 반납 시각 (YYYYMMDD_HHMM, KST 기준)
• (선택) 존 ID 목록

Workflow

1. Understand the user's need

사용자가 원하는 것을 파악한다:

• 장소만 찾기: 쏘카존 위치/이름만 알고 싶은 경우 → search 사용
• 차량 조회: 특정 일정에 빌릴 수 있는 차를 보고 싶은 경우 → cars 사용

날짜/시간이 없으면 먼저 물어본다:

• 권장 질문: 언제부터 언제까지 이용하실 건가요?

2. Search for zones (optional)

쏘카존 이름이나 위치를 먼저 확인할 때:

python3 scripts/socar_zone_search.py search "강남역"

결과에서 type: "ZONE"인 항목은 실제 쏘카존이고, zone_id가 포함되어 있다. type: "PLACE"는 장소 기반 검색 결과로, 주변 쏘카존을 찾을 때 키워드로 사용할 수 있다.

3. Search available cars

키워드 + 대여 일정으로 이용 가능한 차량을 조회한다:

python3 scripts/socar_zone_search.py cars "제주공항" 20260416_1000 20260416_1800

결과가 너무 많으면 --limit으로 존 수를 제한한다:

python3 scripts/socar_zone_search.py cars "제주공항" 20260416_1000 20260416_1800 --limit 3

4. Query specific zones (optional)

search 결과에서 얻은 zone_id로 직접 조회할 수도 있다:

python3 scripts/socar_zone_search.py zones 105,249 20260416_1000 20260416_1800

5. Present results

결과를 사용자에게 정리하여 보여준다. 아래 항목을 포함한다:

• 쏘카존 이름과 주소
• 가용 차량 수 / 전체 차량 수
• 차량별: 이름, 카테고리(경형/준중형/SUV 등), 정원, 요금
• 요금은 정상가와 할인가를 함께 표시 (원 단위)
• available: false인 차량은 "현재 이용불가"로 표시

사용자가 특정 조건을 언급했으면 필터링한다:

• "SUV만" → category에 "SUV" 포함된 차량만
• "7인승" → capacity >= 7인 차량만
• "전기차" → category가 "EV"이거나 power_source가 "전기"인 차량만
• "10만원 이하" → lowest_fee 기준 필터링

Response format

결과가 여러 존이면 상위 23개만 먼저 보여주고, 더 보고 싶은지 물어본다. 차량이 많으면 이용가능한 것 중 상위 58개만 추천한다.

요금은 8시간 기준 요금이므로, 다른 시간대의 경우 요금이 달라질 수 있음을 안내한다.

Done when

• 사용자의 조건(장소, 일정, 차종)에 맞는 결과가 제시되었다
• 요금 정보가 포함되어 있다
• 실시간 조회 기반이므로 재고가 변할 수 있음을 안내했다

Failure modes

• 쏘카 API 서버 점검/변경 시 일시적 사용 불가
• 너무 먼 미래 날짜는 조회 불가할 수 있음
• curl이 HTTP/2를 지원하지 않는 환경에서는 동작하지 않음

Notes

• 이 스킬은 쏘카의 비공식 공개 API를 사용한다 (로그인 불필요)
• 요금은 조회 시점 기준이며 실제 결제 금액과 다를 수 있다
• 예약/결제는 자동화하지 않는다
• 쏘카가 API 구조를 변경하면 동작이 중단될 수 있다