> ## Documentation Index
> Fetch the complete documentation index at: https://docs.x.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Post Annotation

> X API v2의 entity 및 context annotation을 사용해 Post 텍스트 내에서 사람, 장소, 제품, 조직, 주제 도메인을 의미론적으로 식별하세요.

Annotation은 게시물 콘텐츠에 대한 의미론적 메타데이터를 제공합니다. X는 게시물을 분석하여 엔티티(사람, 장소, 제품)와 컨텍스트(주제, 도메인)를 식별하여 콘텐츠를 이해하고 필터링할 수 있도록 돕습니다.

***

## Annotation 유형

### Entity annotation

Named-entity recognition(NER)은 게시물 텍스트에서 특정 언급을 식별합니다:

| 유형               | 예시                      |
| :--------------- | :---------------------- |
| **Person**       | Barack Obama, Elon Musk |
| **Place**        | San Francisco, Japan    |
| **Product**      | iPhone, ChatGPT         |
| **Organization** | NASA, Google            |
| **Other**        | Super Bowl, Diabetes    |

Entity annotation에는 신뢰도 점수와 텍스트 내 위치가 포함됩니다.

### Context annotation

주제 및 도메인별로 게시물을 분류하는 의미론적 분석:

* **Domain**: 광범위한 카테고리(Sports, Entertainment, Technology)
* **Entity**: 도메인 내의 특정 주제(NBA, Marvel Movies, AI)

Context annotation은 키워드에 의존하지 않고 게시물을 필터링하고 분류하는 데 도움이 됩니다.

***

## Annotation 요청

`tweet.fields`에 `context_annotations`와 `entities`를 추가하세요:

```bash theme={null}
curl "https://api.x.com/2/tweets/1234567890?tweet.fields=context_annotations,entities" \
  -H "Authorization: Bearer $TOKEN"
```

***

## 응답 구조

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": {
    "id": "1234567890",
    "text": "Just saw the new Marvel movie - it was amazing!",
    "entities": {
      "annotations": [
        {
          "start": 17,
          "end": 22,
          "probability": 0.9234,
          "type": "Organization",
          "normalized_text": "Marvel"
        }
      ]
    },
    "context_annotations": [
      {
        "domain": {
          "id": "86",
          "name": "Movie",
          "description": "A film"
        },
        "entity": {
          "id": "1234567890",
          "name": "Marvel Cinematic Universe"
        }
      },
      {
        "domain": {
          "id": "65",
          "name": "Interests and Hobbies Vertical"
        },
        "entity": {
          "id": "781974596752842752",
          "name": "Entertainment"
        }
      }
    ]
  }
}
```

***

## Entity annotation field

| Field             | 설명                       |
| :---------------- | :----------------------- |
| `start`           | 텍스트 내 시작 위치              |
| `end`             | 텍스트 내 종료 위치              |
| `probability`     | 신뢰도 점수 (0-1)             |
| `type`            | 엔티티 유형 (Person, Place 등) |
| `normalized_text` | 표준화된 엔티티 이름              |

***

## Context 도메인

X는 80개 이상의 도메인을 사용해 게시물을 분류합니다. 일반적인 도메인은 다음과 같습니다:

<Tabs>
  <Tab title="Entertainment">
    | ID | 도메인         |
    | :- | :---------- |
    | 3  | TV Shows    |
    | 4  | TV Episodes |
    | 54 | Musician    |
    | 56 | Actor       |
    | 86 | Movie       |
    | 91 | Podcast     |
  </Tab>

  <Tab title="Sports">
    | ID | 도메인           |
    | :- | :------------ |
    | 6  | Sports Events |
    | 11 | Sport         |
    | 12 | Sports Team   |
    | 26 | Sports League |
    | 60 | Athlete       |
    | 93 | Coach         |
  </Tab>

  <Tab title="Business & Tech">
    | ID  | 도메인            |
    | :-- | :------------- |
    | 45  | Brand Vertical |
    | 46  | Brand Category |
    | 47  | Brand          |
    | 48  | Product        |
    | 165 | Technology     |
    | 166 | Stocks         |
  </Tab>

  <Tab title="기타">
    | ID  | 도메인                      |
    | :-- | :----------------------- |
    | 10  | Person                   |
    | 13  | Place                    |
    | 29  | Events                   |
    | 35  | Politicians              |
    | 119 | Holiday                  |
    | 131 | Unified Twitter Taxonomy |
  </Tab>
</Tabs>

<Note>
  Domain 131 (Unified Twitter Taxonomy)은 플랫폼에서 사용자에게 보이는 X의 Topics 기능을 지원합니다.
</Note>

***

## 필터에서 annotation 사용

### Search 및 filtered stream

context annotation 엔티티 ID로 게시물 필터링:

```bash theme={null}
# Posts about a specific entity
context:86.1234567890

# Posts in a specific domain
context:86.*
```

### 실용 예시

```bash theme={null}
# Posts about the NBA
query=context:26.852137520

# Posts about Apple products
query=context:47.10026792024

# Posts about movies
query=context:86.*
```

***

## 언어 지원

Annotation은 여러 언어로 사용할 수 있습니다:

| 언어         | 커버리지 |
| :--------- | :--- |
| English    | 최고   |
| Japanese   | 높음   |
| Spanish    | 높음   |
| Portuguese | 중간   |
| French     | 중간   |
| Hindi      | 중간   |

커버리지는 도메인과 시장에 따라 다릅니다.

***

## 중요 참고 사항

<Warning>
  **모든 게시물에 annotation이 있는 것은 아닙니다.** annotation 커버리지는 다음에 따라 다릅니다:

  * 언어 지원
  * X 분류 체계의 주제 커버리지
  * 게시물 텍스트의 의미론적 풍부함
</Warning>

* Annotation은 소급 적용되지 않습니다 — 엔티티가 추적될 때만 적용됩니다
* 동일한 엔티티가 여러 도메인에 나타날 수 있습니다(예: 유명인은 Person이자 Actor)
* Entity ID는 도메인 간에 안정적입니다

***

## 리소스

<CardGroup cols={2}>
  <Card title="Context Entity List" icon="github" href="https://github.com/xdevplatform/twitter-context-annotations">
    사용 가능한 context annotation 엔티티의 CSV.
  </Card>
</CardGroup>