Quartz 4

hamster_locally Itinerary API 레퍼런스

4 min read

🗺️ Itinerary API 레퍼런스

📑 목차

1. 엔드포인트

메서드경로설명
POST/itinerary여행 일정 생성
GET/itinerary-preview프리뷰 UI

2. 요청 스키마

ItineraryRequest

{
  "nights":     2,
  "city":       "서울",
  "must_visit": ["경복궁", "광장시장"],
  "focus":      "free",
  "pace":       "relaxed",
  "lang":       "en",
  "provider":   "gemini",
  "food_ctx":   null
}
필드타입기본값설명
nightsinteger필수몇박 (days = nights + 1)
citystring필수도시명 (서울, 부산, 제주)
must_visitstring[][]반드시 포함할 명소/식당
focusTravelFocus필수여행 중심
paceTravelPace필수여행 페이스
langstringen응답 언어 (ko en zh ja)
providerAIProvidergeminiAI 모델 선택
food_ctxFoodContext|nullnullfocus=food일 때 세부 취향

Enum 값

TravelFocus

값설명
food음식 중심
sightseeing관광 중심
free자유 탐방

TravelPace

값하루 장소 수
relaxed2-3곳
normal3-4곳
fast5곳+

AIProvider

값모델
geminiGemini 2.5 Flash (기본값)
gptGPT-4o

FoodContext

focus: "food" 일 때만 사용.

{
  "styles":        ["michelin", "traditional"],
  "budget":        "luxury",
  "dietary":       ["no_pork"],
  "specific_want": "미슐랭 별 2개 이상 꼭 포함해줘"
}
필드타입기본값설명
stylesFoodStyle[][]복수 선택 가능
budgetFoodBudgetmid1인 예산 기준
dietarystring[][]식이 제한
specific_wantstring""자유 입력 요청

FoodStyle — michelin local street traditional trending hidden

FoodBudget

값기준
budget₩10,000 이하
mid₩10,000-30,000
luxury₩30,000+

3. 응답 스키마

ItineraryResponse

{
  "title":        "Relaxed 3-Day Seoul Exploration",
  "city":         "서울",
  "nights":       2,
  "days":         3,
  "focus":        "free",
  "pace":         "relaxed",
  "lang":         "en",
  "overall_tips": ["tip text...", "tip text..."],
  "itinerary":    [ /* ItineraryDay[] */ ]
}

ItineraryDay

{
  "day":        1,
  "theme":      "Historic Seoul",
  "daily_note": "Start early to avoid crowds at Gyeongbokgung.",
  "blocks":     [ /* ItineraryBlock[] */ ]
}

ItineraryBlock

{
  "time":           "09:00",
  "type":           "attraction",
  "name":           "Gyeongbokgung Palace",
  "name_local":     "경복궁",
  "duration_min":   120,
  "address":        "161 Sajik-ro, Jongno-gu",
  "coords":         null,
  "cost_estimate":  "3,000 KRW",
  "reservation":    false,
  "note":           "Free entry in Hanbok.",
  "tip_ids":        ["FOO001"],
  "transport_next": { /* TransportSegment */ }
}
필드타입설명
timestring시작 시간 HH:MM
typeBlockType블록 유형
namestring영문 장소명
name_localstring한국어 장소명
duration_mininteger체류 시간 (분)
addressstring주소
cost_estimatestring비용 추정
reservationboolean예약 필요 여부
notestring팁/주의사항
tip_idsstring[]연관 팁 ID
transport_nextTransportSegment|null다음 블록까지 이동 정보

BlockType — attraction meal cafe shopping rest transport

TransportSegment

현재 상태

AI 추정값. 향후 Kakao Mobility API 실측값으로 교체 예정.

{
  "method":       "subway",
  "duration_min": 20,
  "distance_m":   null,
  "cost_krw":     1400,
  "note":         "Line 3 Gyeongbokgung → Anguk, 2 stops"
}
필드타입설명
methodstringwalk subway taxi bus
duration_mininteger이동 시간 (분)
distance_minteger|null거리 (미터)
cost_krwinteger|null비용 (원)
notestring노선/출구 상세

4. 요청 예시

자유 탐방 2박 3일

curl -X POST "https://epix-macbookair.tail561905.ts.net/itinerary" \
  -H "Content-Type: application/json" \
  -d '{
    "nights": 2,
    "city": "서울",
    "must_visit": [],
    "focus": "free",
    "pace": "relaxed",
    "lang": "en",
    "provider": "gemini"
  }'

음식 중심 + 미슐랭 (GPT)

curl -X POST "https://epix-macbookair.tail561905.ts.net/itinerary" \
  -H "Content-Type: application/json" \
  -d '{
    "nights": 2,
    "city": "서울",
    "must_visit": [],
    "focus": "food",
    "pace": "relaxed",
    "lang": "en",
    "provider": "gpt",
    "food_ctx": {
      "styles": ["michelin", "traditional"],
      "budget": "luxury",
      "dietary": [],
      "specific_want": "미슐랭 별 2개 이상 포함"
    }
  }'

특정 명소 포함

curl -X POST "https://epix-macbookair.tail561905.ts.net/itinerary" \
  -H "Content-Type: application/json" \
  -d '{
    "nights": 3,
    "city": "서울",
    "must_visit": ["경복궁", "광장시장", "금돼지식당"],
    "focus": "sightseeing",
    "pace": "normal",
    "lang": "ja",
    "provider": "gemini"
  }'

5. Swagger 문서

https://epix-macbookair.tail561905.ts.net/docs    ← Try it out 가능
https://epix-macbookair.tail561905.ts.net/redoc   ← 읽기 전용, 공유용

Swagger 자동 반영

FastAPI가 Pydantic 모델 기반으로 자동 생성. 모델 변경 시 별도 작업 없이 반영됨.

그래프 뷰