광고연구소

광고 상품 API

외부 프로젝트에서 사용하는 광고 상품 API 명세서입니다.

인증

모든 API 요청에는 API Key가 필요합니다.

요청 헤더

X-API-Key: your-api-key-here

요청 예시

const response = await fetch('/api/product/type', {
  headers: {
    'X-API-Key': 'your-api-key-here'
  }
});
const data = await response.json();

인증 실패 (401)

{
  "error": "Unauthorized",
  "message": "유효한 API Key가 필요합니다."
}

GET

광고 타입 목록 조회

광고 상품의 종류(타입) 목록을 조회합니다.

엔드포인트

GET /api/product/type

응답 필드

필드	타입	설명
id	number	타입 고유 ID (0=전체)
name	string	타입 영문명
label	string	타입 표시명 (한글)

응답 예시

[
  { "id": 0, "name": "all", "label": "전체" },
  { "id": 1, "name": "subway", "label": "지하철" },
  { "id": 2, "name": "board", "label": "전광판" },
  { "id": 3, "name": "Bus Stop", "label": "버스 정류장" },
  { "id": 4, "name": "single subway", "label": "지하철 단일상품" },
  { "id": 6, "name": "Cinema", "label": "영화관" },
  { "id": 7, "name": "Banner", "label": "팬클럽 전용" },
  { "id": 8, "name": "online", "label": "온라인" }
]

테스트 해보기

GET

상품 목록 조회

엔드포인트

GET /api/product/ad/list

파라미터

파라미터	타입	필수	설명
lang	string	-	언어 코드 (기본: ko)
productType	string	-	타입 필터 (콤마 구분, 예: 1,2,4) 0 또는 미입력 시 전체 조회
stations	string	-	역 필터 (콤마 구분 stationId, 예: 41,42,180) 해당 역에 연결된 상품만 반환 (product_station 기반)
limit	number	-	조회 개수 제한 최대 1000개

응답 필드

필드	타입	설명
id	number	상품 고유 ID
name	string	상품명
type	number	상품 타입 코드
image	string	대표 이미지 URL
imageSmall	string	대표 이미지 썸네일 URL
subImages	string[]	추가 이미지 URL 목록
subImagesSmall	string[]	추가 이미지 썸네일 URL 목록
prices	Price[]	기간별 가격 목록
location	Location \| null	위치 정보 (좌표, 주소)
stations	Station[]	연결된 역 목록 (product_station 기반, 모든 오프라인 상품)
saleRate	number	할인율 (%)

Price: { duration: string, price: number, currency: "KRW" }

Location: { address: string, lat: string, lng: string }

Station: { id, name, lines, address, lat, lng, costAdjustment, blueprintImage, options, prices }

→ costAdjustment: number (역별 가격 보정값)

→ blueprintImage: string | null (역 도면 이미지 URL)

→ options: Option[] (역 내 광고 옵션 A1, B1 등)

→ prices: Price[] (역별 기간 가격)

Option: { id, name, code, position: { left, top }, displaySize, designSize, priceAdjustment }

→ 최종가격 = prices[].price + costAdjustment + option.priceAdjustment

응답 예시

[
  {
    "id": 20,
    "name": "홍대입구역 조명광고",
    "type": 1,
    "image": "https://kr.cafe24obs.com/data/product/20/main.webp",
    "imageSmall": "https://kr.cafe24obs.com/data/product/small/20/main.webp",
    "subImages": ["https://kr.cafe24obs.com/data/product/20/sub1.webp"],
    "subImagesSmall": ["https://kr.cafe24obs.com/data/product/small/20/sub1.webp"],
    "prices": [
      { "duration": "7d", "price": 200000, "currency": "KRW" },
      { "duration": "14d", "price": 380000, "currency": "KRW" },
      { "duration": "1m", "price": 800000, "currency": "KRW" }
    ],
    "location": {
      "address": "서울특별시 마포구 양화로 지하 160",
      "lat": "37.5571",
      "lng": "126.9239"
    },
    "stations": [
      {
        "id": 239,
        "name": "홍대입구역",
        "lines": ["2호선", "공항철도", "경의중앙선"],
        "address": "서울특별시 마포구 양화로 지하 160",
        "lat": "37.5571",
        "lng": "126.9239",
        "costAdjustment": 10000,
        "blueprintImage": "https://kr.cafe24obs.com/data/product/20/station/239.webp",
        "options": [
          {
            "id": 45,
            "name": "A1",
            "code": "A1",
            "position": { "left": 120, "top": 80 },
            "displaySize": "1920x1080",
            "designSize": "1920x1080",
            "priceAdjustment": 10000
          }
        ],
        "prices": [
          { "duration": "7d", "price": 200000, "currency": "KRW" },
          { "duration": "14d", "price": 380000, "currency": "KRW" }
        ]
      }
    ],
    "saleRate": 10
  }
]

테스트 해보기

productType

stations

limit

lang

GET

상품 상세 조회

엔드포인트

GET /api/product/ad

파라미터

파라미터	타입	필수	설명
id	number	필수	상품 ID
lang	string	-	언어 코드 (기본: ko)

응답 필드

필드	타입	설명
id	number	상품 고유 ID
name	string	상품명
description	string	상품 설명
type	number	상품 타입 코드
image / imageSmall	string	대표 이미지 / 썸네일 URL
subImages / subImagesSmall	string[]	추가 이미지 / 썸네일 URL 목록
vr360 / vr360Thumb	string \| null	360도 VR 이미지 / 썸네일 URL
displayType	number	디스플레이 타입 (1=이미지, 2=동영상)
displaySize	string	디스플레이 크기 (예: 1920x1080)
designSize	string	디자인 권장 크기
fileType	string	파일 형식 (예: mp4, jpg)
resolution	string	해상도
displayTime	string	1회 노출 시간 (예: 15초/1회)
startTime / endTime	string	운영 시작/종료 시간
minimumStartDay	number	최소 시작일 (오늘 기준 며칠 후)
maximumStartDay	number	최대 시작일 (오늘 기준 며칠 후)
selectableDuration	string[]	선택 가능한 기간 목록
priceOptions	PriceOption[]	가격 옵션 목록
location	Location \| null	위치 정보
stations	Station[]	연결된 지하철역 목록
saleRate	number	할인율 (%)
vatIncluded	boolean	부가세 포함 여부
productionCostIncluded	boolean	제작비 포함 여부

PriceOption: { id: number, name: string, prices: Price[] }

Price: { duration: string, price: number, currency: "KRW" }

Station: { id, name, lines, address, lat, lng, image, prices }

응답 예시

[
  {
    "id": 458,
    "name": "강남역 전광판",
    "description": "강남역 출구 앞 대형 전광판입니다.",
    "type": 2,
    "image": "https://kr.cafe24obs.com/data/product/458/main.webp",
    "imageSmall": "https://kr.cafe24obs.com/data/product/small/458/main.webp",
    "subImages": ["https://kr.cafe24obs.com/data/product/458/sub1.webp"],
    "subImagesSmall": ["https://kr.cafe24obs.com/data/product/small/458/sub1.webp"],
    "vr360": "https://kr.object.ncloudstorage.com/dukplace/place360/458/vr.webp",
    "vr360Thumb": "https://kr.object.ncloudstorage.com/dukplace/place360/458/vr_thumb.webp",
    "displayType": 2,
    "displaySize": "1920x1080",
    "designSize": "1920x1080",
    "fileType": "mp4",
    "displayTime": "15초/1회",
    "startTime": "06:00",
    "endTime": "24:00",
    "minimumStartDay": 3,
    "maximumStartDay": 90,
    "selectableDuration": ["7d", "14d", "21d", "1m"],
    "priceOptions": [
      {
        "id": 892,
        "name": "기본",
        "prices": [
          { "duration": "7d", "price": 350000, "currency": "KRW" },
          { "duration": "14d", "price": 650000, "currency": "KRW" }
        ]
      }
    ],
    "location": {
      "address": "서울특별시 강남구 강남대로 396",
      "lat": "37.4979",
      "lng": "127.0276"
    },
    "stations": [],
    "saleRate": 10,
    "vatIncluded": true,
    "productionCostIncluded": false
  }
]

테스트 해보기

id*

lang

GET

지하철 도면/옵션 조회

지하철 상품의 역 도면 이미지, 광고판 위치 옵션, VR/평면 이미지를 조회합니다.
* type=1(지하철) 상품에서만 사용

엔드포인트

GET /api/product/ad/blueprint

파라미터

파라미터	타입	필수	설명
productId	number	필수	상품 ID
stationId	number	필수	역 ID 상품 상세 API의 stations[].id 값
lang	string	-	언어 코드 (기본: ko)

응답 필드

필드	타입	설명
productId	number	상품 ID
stationId	number	역 ID
stationName	string	역 이름
stationAddress	string \| null	역 주소
stationLocation	Location \| null	역 좌표 (lat, lng)
blueprintImage	string \| null	도면 이미지 URL
costAdjustment	number	역별 가격 조정값 양수(+): 추가 요금 / 음수(-): 할인
options	Option[]	광고판 옵션 목록

Option: { id, name, code, position, displaySize, designSize, priceAdjustment, images360, imagesFlat }

position: { left: number, top: number } - 도면 이미지 기준 % 좌표

priceAdjustment: 옵션별 가격 조정값 (같은 역 내에서도 광고판 위치에 따라 가격 차등)

→ 양수(+): 해당 위치는 추가 요금 발생 / 음수(-): 해당 위치는 할인 적용

images360: { id, url, thumbnail, memo }[] - VR 360도 이미지

imagesFlat: { id, url, memo }[] - 평면 이미지

응답 예시

{
  "productId": 20,
  "stationId": 41,
  "stationName": "합정",
  "stationAddress": "서울 마포구 양화로 지하 55",
  "stationLocation": { "lat": "37.5499", "lng": "126.9144" },
  "blueprintImage": "https://kr.cafe24obs.com/data/product/blueprint/20_41.webp",
  "costAdjustment": 0,
  "options": [
    {
      "id": 101,
      "name": "A",
      "code": "A-001",
      "position": { "left": 25.5, "top": 40.2 },
      "displaySize": "1920x1080",
      "designSize": "1920x1080",
      "priceAdjustment": 50000,
      "images360": [
        {
          "id": 1,
          "url": "https://kr.object.ncloudstorage.com/dukplace/place360/20/41/vr.webp",
          "thumbnail": "https://kr.object.ncloudstorage.com/dukplace/place360/20/41/vr_thumb.webp",
          "memo": "A구좌 VR"
        }
      ],
      "imagesFlat": [
        {
          "id": 1,
          "url": "https://kr.object.ncloudstorage.com/dukplace/place360/20/41/flat.webp",
          "memo": "A구좌 평면"
        }
      ]
    },
    {
      "id": 102,
      "name": "B",
      "code": "B-001",
      "position": { "left": 55.0, "top": 40.2 },
      "displaySize": "1920x1080",
      "designSize": "1920x1080",
      "priceAdjustment": 0,
      "images360": [],
      "imagesFlat": []
    }
  ]
}

테스트 해보기

productId*

stationId*

lang

공통 코드

상품 타입 (type)

코드	설명
0	전체
1	지하철
2	전광판
3	버스 정류장
4	지하철 단일상품
6	영화관
7	팬클럽 전용
8	온라인

디스플레이 타입

코드	설명
1	이미지
2	동영상

언어 코드 (lang)

ko - 한국어

en - English

ja - 日本語

cn - 简体中文

tw - 繁體中文

th - ไทย

idn - Bahasa Indonesia

D-OOH 전략

OnSureLab