> ## 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.

# 쿼리 작성

> search 엔드포인트는 GET 요청과 함께 단일 쿼리를 받고, 쿼리에 매칭되는 과거 게시물 집합을 반환합니다. integrate를 다루는 X API v2 standard 티어 레퍼런스입니다.

search 엔드포인트는 GET 요청과 함께 단일 쿼리를 받고, 쿼리에 매칭되는 과거 게시물 집합을 반환합니다. 쿼리는 다양한 게시물 속성에 매칭되는 연산자로 구성됩니다.

***

## 쿼리 제한 사항

쿼리는 사용 중인 [access level](/x-api/getting-started/about-x-api)에 따라 제한됩니다:

| Access level | Recent search | Full-archive search |
| :----------- | :------------ | :------------------ |
| Self-serve   | 512자          | 1,024자              |
| Enterprise   | 4,096자        | 4,096자              |

***

## 연산자 사용 가능 여부

대부분의 연산자는 모든 개발자가 사용할 수 있지만, 일부는 특정 access level 전용입니다:

* **Core operators:** 모든 [Project](/resources/fundamentals/developer-apps) 사용 시 이용 가능
* **Advanced operators:** 특정 access level이 있는 Project 사용 시 이용 가능

가용성 상세는 전체 [연산자 목록](/x-api/posts/search/integrate/operators)을 참고하세요.

***

## 연산자 유형: standalone 및 conjunction-required

**Standalone 연산자**는 단독으로 사용하거나, conjunction이 필요한 연산자를 포함한 다른 연산자들과 함께 사용할 수 있습니다.

예를 들어, `#hashtag`는 standalone 연산자이므로 다음 쿼리가 정상 동작합니다:

```
#xapiv2
```

**Conjunction-required 연산자**는 쿼리에서 단독으로 사용할 수 없으며, 최소 하나 이상의 standalone 연산자가 포함되어야만 사용할 수 있습니다. 이는 이러한 연산자를 단독으로 사용할 경우 매우 많은 양의 게시물이 매칭되기 때문입니다.

예를 들어, 다음 쿼리들은 conjunction-required 연산자만 포함하고 있으므로 **지원되지 않습니다**:

```
has:media
```

```
has:links OR is:retweet
```

여기에 `"X data"`와 같은 standalone 연산자를 추가하면 쿼리가 정상 동작합니다:

```
"X data" has:mentions (has:media OR has:links)
```

***

## Boolean 연산자와 그룹화

다음 도구를 사용해 여러 연산자를 조합할 수 있습니다:

| Operator     | Description       | Example                                                            |
| :----------- | :---------------- | :----------------------------------------------------------------- |
| **AND** (공백) | 두 조건을 모두 매칭해야 함   | `snow day #NoSchool`은 "snow" AND "day" AND #NoSchool을 포함한 게시물에 매칭  |
| **OR**       | 두 조건 중 하나라도 매칭    | `grumpy OR cat OR #meme`은 "grumpy" OR "cat" OR #meme을 포함한 게시물에 매칭  |
| **NOT** (대시) | 이 조건에 매칭되는 게시물 제외 | `cat #meme -grumpy`는 "cat"과 #meme을 포함하지만 "grumpy"는 포함하지 않는 게시물에 매칭 |
| **그룹화** (괄호) | 연산자를 하나로 묶음       | `(grumpy cat) OR (#meme has:images)`는 두 그룹 중 하나에 매칭                |

<Note>
  **부정 관련 참고 사항**

  * `-is:nullcast` 연산자는 반드시 부정된 형태로만 사용해야 합니다
  * 부정된 연산자는 단독으로 사용할 수 없습니다
  * 그룹화된 연산자를 부정하지 마세요. `skiing -(snow OR day OR noschool)` 대신 `skiing -snow -day -noschool`을 사용하세요
</Note>

***

## 연산 우선순위

AND와 OR를 함께 사용할 때:

1. AND 로직으로 연결된 연산자가 먼저 결합됩니다
2. 그 다음 OR 로직으로 연결된 연산자가 적용됩니다

**예시:**

| Query                    | Evaluated as               |
| :----------------------- | :------------------------- |
| `apple OR iphone ipad`   | `apple OR (iphone ipad)`   |
| `ipad iphone OR android` | `(iphone ipad) OR android` |

모호함을 없애려면 괄호를 사용하세요:

```
(apple OR iphone) ipad
```

```
iphone (ipad OR android)
```

***

## 구두점, 발음 구별 부호, 대소문자 구분

**발음 구별 부호:** 악센트나 발음 구별 부호가 포함된 검색 쿼리는 악센트가 있는 게시물과 없는 게시물 모두에 매칭됩니다. 예를 들어 `Diacrítica`는 \_Diacrítica\_와 \_Diacritica\_에 모두 매칭됩니다.

**대소문자 구분:** 모든 연산자는 대소문자를 구분하지 않습니다. `cat` 쿼리는 *cat*, *CAT*, \_Cat\_에 모두 매칭됩니다.

<Note>
  **Filtered stream은 다르게 동작합니다**

  [filtered stream 규칙을 작성](/x-api/posts/filtered-stream/integrate/build-a-rule)할 때, 악센트가 포함된 키워드는 악센트가 있는 게시물에만 매칭됩니다. 예를 들어 `Diacrítica`는 \_Diacrítica\_에만 매칭되고 \_Diacritica\_에는 매칭되지 않습니다.
</Note>

***

## Quote Tweet 매칭

Search Posts를 사용할 때, 연산자는 Quote Tweet의 콘텐츠에 매칭되지만 인용된 원본 게시물의 콘텐츠에는 **매칭되지 않습니다**.

<Note>
  [Filtered stream](/x-api/posts/filtered-stream/introduction)은 다르게 동작합니다—Quote Tweet과 원본 게시물의 콘텐츠 모두에 매칭됩니다.
</Note>

***

## 구체성 및 효율성

<Warning>
  단일 키워드나 해시태그와 같은 광범위한 연산자를 사용하는 것은 권장되지 않습니다—엄청난 양의 게시물이 매칭되어 사용량 한도를 빠르게 소진하게 됩니다.
</Warning>

**효과적인 쿼리 작성을 위한 팁:**

1. **구체적으로 시작한 뒤 확장하기** — 관련성 있는 결과를 반환하는 타깃형 쿼리를 만드세요
2. **여러 연산자 사용하기** — 연산자를 조합해 결과 범위를 좁히세요
3. **문자 수 확인하기** — 쿼리 문자열 전체가 제한에 포함됩니다

**예시 진행:**

```
# Too broad - 200,000+ Posts per day
happy

# Better - adds language filter and exclusions
(happy OR happiness) lang:en -birthday -is:retweet

# Even better - 59 characters, more specific
(happy OR happiness) place_country:GB -birthday -is:retweet
```

***

## 반복적으로 쿼리 다듬기

### 1단계: 기본 쿼리로 시작

```
happy OR happiness
```

### 2단계: 결과를 기반으로 테스트 및 범위 좁히기

여러 언어의 게시물이 있었습니다. 언어 필터를 추가합니다:

```
(happy OR happiness) lang:en
```

생일 인사가 반환됩니다. 이를 제외하고 리트윗도 제외합니다:

```
(happy OR happiness) lang:en -birthday -is:retweet
```

### 3단계: 커버리지 확장

더 많은 감정을 포착하고 싶습니다. 관련 키워드를 추가합니다:

```
(happy OR happiness OR excited OR elated) lang:en -birthday -is:retweet
```

### 4단계: 트렌드에 맞춰 조정

Holiday 게시물이 등장합니다. 이를 제외합니다:

```
(happy OR happiness OR excited OR elated) lang:en -birthday -is:retweet -holidays
```

***

## 요청에 쿼리 추가하기

`query` 파라미터를 사용하고 쿼리를 HTTP 인코딩하세요:

```bash theme={null}
curl "https://api.x.com/2/tweets/search/recent?\
query=cat%20has%3Amedia%20-grumpy&\
tweet.fields=created_at&\
max_results=100" \
  -H "Authorization: Bearer $BEARER_TOKEN"
```

***

## 쿼리 예시

### 자연재해 추적

허리케인 Harvey에 대한 기상 기관의 게시물에 매칭:

**쿼리:**

```
has:geo (from:NWSNHC OR from:NHC_Atlantic OR from:NWSHouston OR from:NWSSanAntonio OR from:USGS_TexasRain OR from:USGS_TexasFlood OR from:JeffLindner1) -is:retweet
```

**전체 요청 URL:**

```
https://api.x.com/2/tweets/search/recent?query=has%3Ageo%20(from%3ANWSNHC%20OR%20from%3ANHC_Atlantic%20OR%20from%3ANWSHouston%20OR%20from%3ANWSSanAntonio%20OR%20from%3AUSGS_TexasRain%20OR%20from%3AUSGS_TexasFlood%20OR%20from%3AJeffLindner1)%20-is%3Aretweet
```

### #nowplaying에 대한 감성 분석

**긍정 감성:**

```
#nowplaying (happy OR exciting OR excited OR favorite OR fav OR amazing OR lovely OR incredible) (place_country:US OR place_country:MX OR place_country:CA) -horrible -worst -sucks -bad -disappointing
```

**부정 감성:**

```
#nowplaying (horrible OR worst OR sucks OR bad OR disappointing) (place_country:US OR place_country:MX OR place_country:CA) -happy -exciting -excited -favorite -fav -amazing -lovely -incredible
```

### Post annotations 사용

`context:` 연산자를 사용해 이미지가 있는 일본어 게시물 중 반려동물 관련(고양이 제외)을 찾기:

먼저 `tweet.fields=context_annotations`와 함께 [Post lookup](/x-api/posts/lookup/introduction)을 사용해 domain.entity ID를 확인합니다:

* Cats: `domain` 66, `entity` 852262932607926273
* Pets: `domain` 65, `entity` 852262932607926273

**쿼리:**

```
context:65.852262932607926273 -context:66.852262932607926273 -is:retweet has:images lang:ja
```

***

## 도구

<Card title="Query Builder Tool" icon="wrench" href="https://developer.x.com/apitools/query?query=">
  대화식으로 쿼리를 작성하고 테스트하기
</Card>

***

## 다음 단계

<CardGroup cols={2}>
  <Card title="연산자 레퍼런스" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-bulleted-list.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=b9bf8323233df59c682b0fec8e3f88d5" href="/x-api/posts/search/integrate/operators" width="24" height="24" data-path="icons/xds/icon-bulleted-list.svg">
    사용 가능한 연산자 전체 목록
  </Card>

  <Card title="Search 퀵스타트" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-rocket.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=b978d7a9225de31709efbbed5b84e92d" href="/x-api/posts/search/quickstart/recent-search" width="24" height="24" data-path="icons/xds/icon-rocket.svg">
    첫 검색 요청 만들기
  </Card>

  <Card title="통합 가이드" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-book.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=22ac564792481d14ae36a941546039c8" href="/x-api/posts/search/integrate/overview" width="24" height="24" data-path="icons/xds/icon-book.svg">
    전체 통합 문서
  </Card>
</CardGroup>