API 문서

개발자 포털 · 이 문서만으로 연동이 끝나야 합니다

인증

발급받은 키를 X-TDB-Key 헤더로 보냅니다. 분당 한도 초과 시 429 + Retry-After.

curl -s http://localhost:9200/v1/places/lookup \
  -H "X-TDB-Key: tdb_live_..." -H "Content-Type: application/json" \
  -d '{"locale":"en","text":"주말에 숭례문과 경복궁 근정전을 다녀왔다."}'

엔드포인트

경로	용도
POST /v1/places/lookup	기사 텍스트 → 등장 장소의 대상 언어 표기 목록 (번역 프롬프트 주입용 핵심)
POST /v1/places/match	명칭(들) → 장소 해석 · region_hint로 동명 해소
GET /v1/places/{id}	장소 상세 + 전체 언어 표기
GET /v1/places/changes?since=	증분 변경분 (로컬 캐시 동기화 커서)
GET /v1/export/snapshot	전량 스냅샷(NDJSON) — 소비자 로컬 사전 모드(0ms)
GET /v1/health	상태 + 사전 크기 (무인증)

규약 요점

속도: lookup p95 < 50ms (인메모리 사전, DB 무접근) · 실측 p95 2.8ms
동명 해소: 기사 문맥으로 자동 판별 후 evidence로 근거 제공
모호성: 확신 없으면 ambiguous:true + 후보 반환 — 틀린 장소 주입 금지
폴백: 표기 없으면 로케일 폴백 체인 적용 후 fallback_used 표시
장애 격리: TDB 무응답 시 소비자는 주입 없이 번역 진행 권장