통합 가이드 — 개요
ADMap 은 옥외 광고 미디어 플래닝을 위한 지도 데이터 API 를 제공한다. 이 가이드는 그
연동 방법(플로우 · 코드 예제 · 함정)을 다룬다. 개별 엔드포인트의 기계적 명세(요청/응답
스키마 · 상태코드)는 API 레퍼런스 (/docs) 의 Scalar 문서를 본다. 같은 정보를
양쪽에 중복하지 않는다.
이 가이드(/guide/*)와 API 레퍼런스(/docs)는 외부 팀원 온보딩을 위한 문서 표면이다.
실제 데이터 접근 권한은 API key 의 map/brand 범위로 제어한다.
baseURL · 환경
아래 예제는 <BASE> 를 baseURL 로, <...> 를 실제 값으로 치환해서 쓴다. 예제의 키·토큰
placeholder 는 실제 비밀값을 코드/로그에 남기지 않는다.
공통 규약
에러 봉투
현재 문서화된 health/version seed 와 신규 문서화 엔드포인트는 { "error": "<code>" } 형태를
기준으로 시작한다. Public v1 legacy/brand 경로처럼 { "error_code": "<code>" } 를 쓰는
엔드포인트도 있으므로, 최종 실패 응답 필드는 API 레퍼런스의 엔드포인트별 스키마를
기준으로 분기한다.
Int8 ID 는 문자열 경계
레이어 · POI 등의 ID 는 DB 에서 64bit(Int8)라 JSON 경계에서 문자열로 다룬다(정밀도 손실 방지). 숫자로 파싱하지 않는다.
레이트 리밋
동일 식별자당 60초에 100요청 전역 적용. 초과 시 429. 서버-서버 컨슈머는 백오프를 둔다.
문서 허브
외부 팀원은 아래 순서로 읽으면 된다.
@team-draftype/map-sdk 와 @team-draftype/react 중 어떤 진입점을 쓸지 고르고 지도 임베드 기본값을 맞추는 가이드.첫 요청 — health/version
인증 없이 서버 생존과 릴리즈 버전만 확인한다.
curl -s <BASE>/api/health/version
# → 200 { "version": "0.1.1", "releasedAt": "2026-06-16T00:00:00.000Z" }전체 흐름을 한 번에 따라가려면 → 빠른 시작 — end-to-end 예제.
다음 단계
도메인별 연동 가이드(미디어 분석 등)는 순차적으로 추가된다. 현재 제공되는 전체 엔드포인트
목록과 요청/응답 스키마는 API 레퍼런스 (/docs) 에서 확인한다. 운영 작업은
운영 콘솔 (레이어) 에서 한다.