---
url: /api-sdk/data/metadata.md
description: 게임플레이 파트너센터 오픈과 함께 사용이 중지되는 게임 메타 정보 API와 랭킹 데이터 스펙
---

# 메타데이터 API (사용 중지 예정)




기존 연동 파트너사가 카카오(게임플레이) 서버로 호출해 게임 정보를 관리하던 API입니다. 등록·수정·단건 조회·목록 조회 4개 엔드포인트를 제공하며, 파트너센터 오픈과 함께 사용이 중지됩니다.

::: warning 사용 중지 안내
게임플레이 파트너센터가 오픈하면 메타데이터 API 호출은 오류로 응답되며, 게임 정보를 등록·수정할 수 없습니다. 파트너센터 오픈 시점부터는 게임 정보를 변경할 때 업데이트 심사를 반드시 거쳐야 하므로, 심사를 건너뛰는 API 경로는 제공하지 않습니다. 신규 파트너사는 이 API를 연동하지 않고 현재 가이드에 따라 입점을 준비한 뒤, 파트너센터 오픈 후 게임 정보를 등록하고 출시 심사를 요청하세요. 기존 연동 파트너사는 오픈 전까지 기존 API와 기존 심사 절차를 사용합니다. 아래 스펙은 오픈 전까지 운영 중인 연동을 유지하기 위한 참고 자료입니다.
:::

> **관련 가이드**: [심사 가이드](/docs/checklist/review-guide): 파트너센터 출시·업데이트 심사 절차

## API 목록

| 이름 | Method | Path |
| --- | --- | --- |
| 신규 등록 | `POST` | `/v1/api/gameplay` |
| 수정 | `PUT` | `/v1/api/gameplay` |
| 단건 조회 | `GET` | `/v1/api/gameplay/games/{gameCode}` |
| 목록 조회 | `GET` | `/v1/api/gameplay/games` |

## 공통

### Base URL

```http
https://pf-external-api.kakao.com
```

### 헤더

| Header | 설명 |
| --- | --- |
| `Authorization` | 필수`KakaoAK {APP_KEY}`: 파트너사 디벨로퍼스 앱의 REST API 키 |
| `Content-Type` | 필수`application/json` |

### 인증

* `Authorization` 헤더의 APP\_KEY 검증
* IP ACL 기반(사전 등록된 IP만 허용) 이중 인증. 파트너사 정보 전달 양식에서 제출한 IP 사용

### Rate Limit

| 항목 | 값 |
| --- | --- |
| 제한 기준 | 요청 IP 단위 |
| 허용량 | 최대 1,000 RPS |
| Burst | 순간 최대 2,000 requests |

제한 초과 시 `503 Service Temporarily Unavailable`이 반환됩니다.

### 공통 에러 코드

| code | 설명 |
| --- | --- |
| `-900` | 허용되지 않은 IP에서 접근 |

각 API별 추가 에러 코드는 아래 각 섹션을 참고하세요.

## 게임 메타 신규 등록

파트너사가 신규 게임을 등록하는 시점에 호출합니다.

```http
POST /v1/api/gameplay
```

### Request Body

| 필드 | 타입 | 설명 |
| --- | --- | --- |
| `code` | `string` | 필수게임별 고유 키. 최대 25자. **광고의 CPID와 반드시 동일해야 함** |
| `name` | `string` | 필수타이틀. 최대 30자 |
| `description` | `string` | 필수세부 설명. 최대 50자 |
| `thumbnail` | `object` | 필수썸네일 정보. [thumbnail 객체](#thumbnail) 참고 |
| `link` | `string` | 필수랜딩 URL. 최대 100자 |
| `genre` | `object` | 필수장르. [genre 객체](#genre) 참고 |
| `play_mode` | `string` | 필수플레이 방식. [play\_mode 정의](#play-mode) 참고 |
| `ranking` | `object` | 필수랭킹 메타. [ranking 객체](#ranking) 참고. 랭킹 미사용 게임도 `enabled: false`로 필수 전달 |
| `display_info` | `object` | 필수게임 표시 정보. [display\_info 객체](#display-info) 참고 |

### thumbnail

| 필드 | 타입 | 설명 |
| --- | --- | --- |
| `square` | `string` | 정사각형 이미지 URL. `640 × 640` (1:1), 200 KB 이하 |
| `wide` | `string` | 와이드 이미지 URL. `1200 × 630` (1.91:1), 1 MB 이하 |

카카오가 전달받은 URL에서 이미지를 다운로드해 카카오 CDN에 업로드합니다. 이미지 도메인은 사전에 카카오에 전달해 외부 프록시 화이트리스트 등록이 필요합니다.

### genre

| 필드 | 타입 | 설명 |
| --- | --- | --- |
| `main` | `string` | 메인 장르 |
| `subs` | `string[]` | 서브 장르. 최대 2개 |

메인과 동일한 값을 서브에 포함할 수 없습니다.

**장르 코드**

| 값 | 설명 |
| --- | --- |
| `PUZZLE` | 퍼즐 |
| `ACTION` | 액션 |
| `SHOOTING` | 슈팅 |
| `STRATEGY` | 전략 |
| `SIMULATION` | 시뮬 |
| `RPG` | RPG |
| `ADVENTURE` | 어드벤쳐 |
| `ARCADE` | 아케이드 |
| `BOARD` | 보드 |
| `QUIZ` | 퀴즈 |
| `SPORTS` | 스포츠 |
| `RACING` | 레이싱 |

### display\_info

게임산업진흥법 시행령 별표 3에 따른 법정 표시 의무 항목입니다.

| 필드 | 타입 | 설명 |
| --- | --- | --- |
| `age_rating` | `string` | 필수이용 등급 |
| `rating_classification_number` | `string` | 필수등급 분류 결정서의 고유 번호. 최대 30자 (예: 게임물관리위원회 `CC-OM-260204-002`, 구글플레이스토어 `GOOG-SG-250418-0164`) |
| `rating_classification_date` | `string` | 필수등급 분류 일자. `YYYY-MM-DD` |
| `corporate_name` | `string` | 필수상호. 게임 심의를 받은 자(배급업자 또는 제작업자)의 상호로, 게임별로 다를 수 있음. 최대 50자 |
| `business_registration_number` | `string` | 필수제작·배급업 등록(신고) 번호. 게임산업진흥법 제25조에 따라 시·군·구청에 등록·신고한 번호(자유 형식). 회사가 동일하면 게임 간 번호가 같을 수 있음. 최대 30자 (예: `2025-서울강남-06282`) |
| `content_descriptors` | `string[]` | 필수게관위 등급 분류 결정서의 게임물 내용 정보. 최대 7개. 해당 항목 없으면 빈 배열 |
| `has_probability_item` | `boolean` | 필수게임 내 확률형 아이템 포함 여부 |
| `additional_notice` | `string` | 기타 고지사항. 최대 50자 (배급자 정보 등) |

**`age_rating`**

| 값 | 설명 |
| --- | --- |
| `ALL` | 전체 이용가 |
| `AGE_12` | 12세 이용가 |
| `AGE_15` | 15세 이용가 |
| `ADULT` | 청소년 이용 불가 |

**`content_descriptors`**

| 값 | 설명 |
| --- | --- |
| `SEXUAL` | 선정성 |
| `VIOLENT` | 폭력성 |
| `FEAR` | 공포 |
| `LANGUAGE` | 언어의 부적절성 |
| `DRUG` | 약물 |
| `CRIME` | 범죄 |
| `GAMBLING` | 사행성 |

전체 이용가 게임이라도 해당 내용이 있으면 표시 의무가 있으므로 누락 없이 전달합니다.

### Response

`200 OK` (본문 없음)

### 에러

| code | 설명 |
| --- | --- |
| `-850` | 이미 등록된 게임 (`code` 중복) |
| `-900` | 허용되지 않은 IP |

## 게임 메타 수정

```http
PUT /v1/api/gameplay
```

Request Body는 [신규 등록](#request-body)과 동일합니다. **변경되지 않은 필드 값도 모두 전달해야 하며**, 수정된 값이 하나도 없으면 에러가 발생합니다.

### Response

`200 OK`

### 에러

| code | 설명 |
| --- | --- |
| `-851` | 변경된 내역이 없음 |
| `-852` | 해당 게임이 존재하지 않음 |
| `-900` | 허용되지 않은 IP |

## 게임 메타 단건 조회

`gameCode`로 파트너사 vendor의 등록 게임 1건을 조회합니다.

```http
GET /v1/api/gameplay/games/{gameCode}
```

### Path Parameter

| 이름 | 타입 | 설명 |
| --- | --- | --- |
| `gameCode` | `string` | 필수등록 시 전달한 `code` 값 |

### Response

```json
{
  "code": "my_game_001",
  "name": "샘플 게임",
  "description": "샘플 설명",
  "thumbnail": {
    "square": "https://vendor-cdn.example.com/games/my_game_001/square.png",
    "wide": "https://vendor-cdn.example.com/games/my_game_001/wide.png"
  },
  "link": "https://vendor-game.example.com/h5/my_game_001",
  "genre": {"main": "PUZZLE", "subs": ["ACTION"]},
  "play_mode": "STAGE",
  "ranking": {
    "enabled": true,
    "metrics": [{"type": "SCORE", "order": "DESC"}],
    "period_types": ["WEEKLY", "MONTHLY"],
    "default_period_type": "WEEKLY"
  },
  "display_info": {
    "age_rating": "ALL",
    "rating_classification_number": "CC-OM-260204-002",
    "rating_classification_date": "2026-02-04",
    "corporate_name": "샘플게임즈",
    "business_registration_number": "2025-서울강남-06282",
    "content_descriptors": [],
    "has_probability_item": false,
    "additional_notice": null
  },
  "status": "ON"
}
```

`thumbnail`은 등록 시 전달한 원본 URL이 반환됩니다 (카카오 CDN 업로드본 아님).

**`status`**

| 값 | 설명 |
| --- | --- |
| `ON` | 서비스 중 |
| `OFF` | 비활성 |
| `QA` | QA 단계 (운영 환경 미노출) |
| `DELETED` | 삭제됨 |
| `UNKNOWN` | 미정 |

### 에러

| code | 설명 |
| --- | --- |
| `-2` | vendor 미등록 caller |
| `-852` | 본인 vendor의 등록 게임 중 `gameCode` 매칭 없음 |
| `-900` | 허용되지 않은 IP |

## 게임 메타 목록 조회

본인 vendor가 등록한 게임 메타 정보를 모두 조회합니다.

```http
GET /v1/api/gameplay/games
```

별도 파라미터 없이 caller APP\_KEY의 vendor로 스코프가 자동 한정됩니다.

### Response

[게임 메타 단건 조회](#게임-메타-단건-조회)의 Response Body 배열 형태입니다.

* 정렬: 최신 등록순 (`createdAt DESC`)
* `status = DELETED`인 게임은 제외

```json
[
  {"code": "my_game_002", "name": "신규 게임", "status": "OFF"},
  {"code": "my_game_001", "name": "샘플 게임", "status": "ON"}
]
```

### 에러

| code | 설명 |
| --- | --- |
| `-2` | vendor 미등록 caller |
| `-900` | 허용되지 않은 IP |

## 랭킹 데이터 스펙

::: warning 랭킹 노출은 사전 조율 후 확정됩니다
`ranking.enabled: true`로 설정해도 모든 게임이 게임플레이 랭킹 영역(리더보드)에 노출되는 것은 아닙니다. 카카오가 전송된 기록값 데이터를 확인하고 파트너사와 사전 조율을 거쳐 노출 대상과 시점을 확정합니다. 랭킹 설정과 기록값 전송은 노출을 위한 데이터 준비 단계이며, 노출 스펙은 추후 변경될 수 있습니다. 게임 내 자체 랭킹은 이와 무관하게 자유롭게 구현할 수 있습니다.
:::

게임플레이 서비스 내 랭킹 영역에 게임별 랭킹을 노출하려면 다음 두 데이터가 매칭되어야 합니다. 랭킹 설정은 파트너센터에 입력하며, 아래 `ranking` 스펙은 파트너센터 오픈 전까지 기존 연동을 유지하기 위한 참고 자료입니다.

| 구분 | 설명 | 전달 시점 |
| --- | --- | --- |
| 파트너센터 랭킹 설정오픈 전: 메타데이터 `ranking` | 플레이 방식, 랭킹 사용 여부, 산정 기준 | 게임 등록·수정 시 |
| 사용자 [액션데이터 API](/api-sdk/data/action-data) | 사용자 플레이 실제 기록값 | 플레이 시작·완료·종료 시 |

파트너센터에 설정한 랭킹 기준과 액션데이터의 기록값이 일치해야 랭킹 집계가 가능합니다. 파트너센터 오픈 전까지는 메타데이터 API로 설정한 기준이 기준값이 됩니다.

### `play_mode`

게임 구조를 설명하는 값이며, 실제 랭킹 산정 기준은 `ranking.metrics`에서 별도 정의합니다.

| 값 | 설명 |
| --- | --- |
| `ROUND` | 단판형 게임 |
| `STAGE` | 스테이지형 게임 |
| `TIME_ATTACK` | 타임어택형 게임 |
| `LEVEL` | 레벨형 게임 |

### `ranking`

| 필드 | 타입 | 설명 |
| --- | --- | --- |
| `enabled` | `boolean` | 필수랭킹 사용 여부 |
| `metrics` | `object[]` | 랭킹 산정 기록값 목록. 1개만 지원. **`enabled: true`일 때 필수** |
| `period_types` | `string[]` | 제공할 랭킹 기간. **`enabled: true`일 때 필수** |
| `default_period_type` | `string` | 기본 랭킹 기간. 허용값은 [period\_types](#period-types)와 동일. **`enabled: true`일 때 필수** |

랭킹 미사용 게임은 `ranking.enabled: false`만 전달하고 나머지 하위 필드는 생략할 수 있습니다.

### `metrics`

| 필드 | 타입 | 설명 |
| --- | --- | --- |
| `type` | `string` | 필수기록값 유형 |
| `order` | `string` | 필수정렬 방향 |

**`type` 허용값**

| 값 | 설명 | 예시 |
| --- | --- | --- |
| `SCORE` | 점수 | `123450` |
| `TIME` | 시간 (ms) | `58300` (58.3초) |
| `PROGRESS` | 단계·레벨·웨이브 | `10`, `Lv.12` |
| `DISTANCE` | 거리·높이·깊이 | `78.1` (m) |
| `COUNT` | 횟수·콤보·수집량 | `24`, `120` |
| `RATE` | 비율·정확도·성공률 | `98.5` (%) |

**`order`**

| 값 | 설명 |
| --- | --- |
| `ASC` | 값이 작을수록 상위 (예: 클리어 시간) |
| `DESC` | 값이 클수록 상위 (예: 점수, 거리) |

복수 `metrics`는 미지원이며 랭킹 기준은 1개 타입만 지원합니다.

### `period_types`

| 값 | 설명 |
| --- | --- |
| `WEEKLY` | 주간 랭킹 |
| `MONTHLY` | 월간 랭킹 |

### 사전 문의 필요 케이스

임의 값을 추가하지 않고 카카오 담당자와 사전 협의합니다.

* `play_mode`로 표현하기 어려운 게임
* `metrics.type`으로 표현하기 어려운 기록값
* 2개 이상의 기록값 조합이 필요한 경우
* `WEEKLY`·`MONTHLY` 외 기간 랭킹이 필요한 경우
* 실시간·시즌·보상 지급용 등 별도 랭킹 정책이 필요한 경우

사전 협의 없이 정의되지 않은 값을 전달하면 랭킹 노출이 제한되거나 데이터가 정상 집계되지 않을 수 있습니다.

## 참고 문서

* [액션데이터 API](/api-sdk/data/action-data): 사용자별 실제 랭킹 기록값 전송
* 게임플레이 파트너센터: 신규 게임 정보 등록·수정 및 심사 요청
* [데이터 샘플 카탈로그](/api-sdk/data/samples#메타데이터-샘플-사용-중지-예정): 기존 파트너용 게임 유형별 등록 요청 본문 예시
* [계정 상태 변경 웹훅 연동](/api-sdk/data/terms-withdrawal)
* [심사 가이드](/docs/checklist/review-guide)
* 기술 문의: [카카오디벨로퍼스 데브톡](https://devtalk.kakao.com/c/game-play/353)