> ## 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 가져오기

> X API v2 full-archive search 엔드포인트, 쿼리 연산자 및 페이지네이션을 사용하여 2006년까지의 과거 Post를 조회하는 단계별 튜토리얼.

## 소개

v2 세계의 [Search Posts 엔드포인트](/x-api/posts/search/introduction)를 사용하면
직접 만든 검색 쿼리를 기반으로 관심 주제와 관련된 Post를 받을 수 있습니다.
v2 Search Posts에는 두 가지 다른 엔드포인트가 있습니다: recent search는 승인된 계정을 가진 모든
개발자가 사용할 수 있으며 최대 7일 이내의 Post를 검색할 수 있고, full-archive search는
[Academic Research 제품 트랙](https://developer.x.com/en/products/x-api/early-access/guide#na_2)에
승인된 연구자만 사용할 수 있으며, 2006년 3월까지 거슬러 올라가는 전체 Post 아카이브를 검색할 수 있습니다.

전체 검색 제공 사항은 [검색 개요 페이지](/x-api/posts/search/introduction)에서 확인할 수 있습니다.

이러한 Search Posts 엔드포인트는 학술 연구자들에게 가장 흔한 사용 사례 중 하나를 해결해 주며,
종단 연구나 과거 주제 또는 사건 분석에 활용할 수 있습니다.

이 튜토리얼은 공개 X 데이터의 전체 이력을 검색하기 위해 full-archive search 엔드포인트를 사용하려는
연구자를 위한 단계별 가이드를 제공합니다. 지오 태그가 있는 Post를 가져오는 등 데이터셋을 구축하는 다양한 방법과
쿼리에 대해 사용 가능한 Post를 페이지네이션하는 방법도 시연합니다.

### 사전 요건

현재 이 엔드포인트는 [Academic Research 제품 트랙](https://developer.x.com/en/solutions/academic-research/products-for-researchers)의 일부로만 제공됩니다.
이 엔드포인트를 사용하려면 [액세스를 신청](https://developer.x.com/en/portal/petition/academic/is-it-right-for-you)해야 합니다.
[이 트랙의 신청 절차 및 요건](https://developer.x.com/en/solutions/academic-research/application-info)에 대해 자세히 알아보세요.

### App을 학술 프로젝트에 연결하기

Academic Research 제품 트랙 사용이 승인되면 [Developer Console](https://developer.x.com/en/portal/dashboard)에서
Academic [Project](/resources/fundamentals/developer-apps)를 볼 수 있습니다. "Apps" 섹션에서 "Add App"을
클릭하여 [X App](/resources/fundamentals/developer-apps)을 Project에 연결하세요.

[](https://res.cloudinary.com/practicaldev/image/fetch/s--gHFOyuDc--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_880/https://dev-to-uploads.s3.amazonaws.com/i/gb7aevhqyfvfjznd0pnd.png)

![Developer Console에 아직 App이 추가되지 않은 Academic Project가 표시된 이미지](https://cdn.cms-twdigitalassets.com/content/dam/developer-twitter/docs/tutorials/getting-historical-tweets-using-the-full-archive-search-endpoint/dev-portal-1.png.twimg.1920.png)

그런 다음 (아래와 같이) 기존 App을 선택하여 프로젝트에 연결할 수 있습니다.

![Academic Project에 App을 추가하려고 할 때 나타나는 페이지를 보여주는 이미지](https://cdn.cms-twdigitalassets.com/content/dam/developer-twitter/docs/tutorials/getting-historical-tweets-using-the-full-archive-search-endpoint/dev-portal-2.png.twimg.1920.png)

또는 새 App을 만들고 이름을 지정한 후 완료를 클릭하여 Academic Project에 새 App을 연결할 수도 있습니다.

![새 App의 이름을 입력하거나 기존 App을 선택할 수 있는 페이지를 보여주는 이미지](https://cdn.cms-twdigitalassets.com/content/dam/developer-twitter/docs/tutorials/getting-historical-tweets-using-the-full-archive-search-endpoint/dev-portal-3.png.twimg.1920.png)

이 과정에서 full-archive search 엔드포인트에 연결하는 데 사용할 수 있는 API 키와
[Bearer Token](/resources/fundamentals/authentication#using-and-generating-an-app-only-bearer-token)이 제공됩니다.

![새 App을 생성한 후 키와 토큰이 표시되는 페이지를 보여주는 이미지](https://cdn.cms-twdigitalassets.com/content/dam/developer-twitter/docs/tutorials/getting-historical-tweets-using-the-full-archive-search-endpoint/dev-portal-4.png.twimg.1920.png)

**참고**

위 스크린샷의 키는 숨겨져 있지만, 자신의 Developer Console에서는 API Key, API Secret Key,
Bearer Token의 실제 값을 볼 수 있습니다. full-archive search 엔드포인트를 호출하는 데 필요하므로
이 키와 Bearer Token을 저장하세요.

### full-archive search 엔드포인트에 연결하기

아래 cURL 명령은 @XDevelopers 핸들에서 과거 Post를 가져오는 방법을 보여줍니다.
\$BEARER\_TOKEN을 자신의 Bearer Token으로 바꾸고, 전체 요청을 터미널에 붙여넣은 후 "return"을 누르세요.

```bash theme={null}
curl --request GET 'https://api.x.com/2/tweets/search/all?query=from:xdevelopers' --header 'Authorization: Bearer $BEARER_TOKEN'
```

응답 JSON이 표시됩니다.

기본적으로 가장 최근 10개의 Post만 반환됩니다. 요청당 10개 이상의 Post를 원한다면
아래와 같이 max\_results 파라미터를 사용하여 요청당 최대 500개까지 설정할 수 있습니다:

```bash theme={null}
curl --request GET 'https://api.x.com/2/tweets/search/all?query=from:xdevelopers&max_results=500' --header 'Authorization: Bearer $BEARER_TOKEN'
```

### 쿼리 만들기

위의 예시 호출에서 볼 수 있듯이, query 파라미터를 사용하여
검색하려는 데이터를 지정할 수 있습니다. 예를 들어 *covid* 또는 \_coronavirus\_라는 단어가 포함된
모든 Post를 가져오려면 괄호 안에 OR 연산자를 사용할 수 있으며, 쿼리는
`(covid OR coronavirus)`가 되고 따라서 API 호출은 다음과 같습니다:

```bash theme={null}
curl --request GET 'https://api.x.com/2/tweets/search/all?query=(covid%20OR%20coronavirus)&max_results=500' --header 'Authorization: Bearer $BEARER_TOKEN'
```

마찬가지로 리포스트가 아닌 \_covid19\_라는 단어가 포함된 모든 Post를 가져오려면
is:retweet 연산자와 논리 NOT(-로 표시)을 함께 사용할 수 있으므로, 쿼리는
covid19 -is:retweet이 되고 API 호출은 다음과 같습니다:

```bash theme={null}
curl --request GET 'https://api.x.com/2/tweets/search/all?query=covid19%20-is:retweet&max_results=500' --header 'Authorization: Bearer $BEARER_TOKEN'
```

full-archive search 엔드포인트에서 지원되는 [연산자 전체 목록은 이 가이드를 확인하세요](/x-api/posts/search/integrate/build-a-query).

### start\_time과 end\_time 파라미터를 사용하여 과거 Post 가져오기

full-archive search 엔드포인트 사용 시, 기본적으로 지난 30일 동안의 Post가 반환됩니다.
30일보다 오래된 Post를 가져오려면 API 호출에 start\_time과 end\_time 파라미터를 사용할 수 있습니다.
이러한 파라미터는 유효한 RFC3339 날짜-시간 형식이어야 하며, 예를 들어
2020-12-21T13:00:00.00Z와 같이 지정합니다. 따라서 2020년 12월 한 달간 XDevelopers 계정의
모든 Post를 가져오려면 API 호출은 다음과 같습니다:

```bash theme={null}
curl --request GET 'https://api.x.com/2/tweets/search/all?query=from:XDevelopers&start_time=2020-12-01T00:00:00.00Z&end_time=2021-01-01T00:00:00.00Z' --header 'Authorization: Bearer $BEARER_TOKEN'
```

### 지오 태그가 있는 과거 Post 가져오기

지오 태그가 있는 Post란 도시, 주, 국가 등 지리 정보가 함께 포함된 Post입니다.

#### has:geo 연산자 사용

지오 데이터가 있는 Post를 가져오려면 has:geo 연산자를 사용할 수 있습니다.
예를 들어 다음 cURL 요청은 @XDevelopers 핸들에서 지오 데이터가 있는 Post만 가져옵니다:

```bash theme={null}
curl --request GET
'https://api.x.com/2/tweets/search/all?query=from:xdevelopers%20has:geo' --header
'Aubashthorization: Bearer $BEARER_TOKEN'
```

#### place\_country 연산자 사용

마찬가지로 place\_country 연산자를 사용하여 지오 데이터가 있는 Post를 특정 국가로 제한할 수 있습니다.
아래 cURL 명령은 미국에서 발생한 @XDevelopers 핸들의 모든 Post를 가져옵니다:

```bash theme={null}
curl --request GET
'https://api.x.com/2/tweets/search/all?query=from:xdevelopers%20place_country:US'
--hbasheader 'Authorization: Bearer XXXXX'
```

국가는 위에서 ISO alpha-2 문자 코드를 사용하여 지정합니다. 유효한 ISO 코드는 [여기](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)에서 확인할 수 있습니다.

### next\_token을 사용하여 500개 이상의 과거 Post 가져오기

위에서 언급한 것처럼, full-archive search 엔드포인트 쿼리는 기본적으로 요청당 최대 500개의 Post만 가져올 수 있습니다.
쿼리에 500개 이상의 Post가 있다면 JSON 응답에 next\_token이 포함되며, 이를 API 호출에 추가하여
쿼리에 대한 다음 사용 가능한 Post를 가져올 수 있습니다. 이 next\_token은 JSON 응답의 meta 객체에서 사용할 수 있으며,
다음과 같은 모양입니다:

```json theme={null}
{ "newest_id": "12345678...", "oldest_id": "12345678...", "result_count": 500,
"nebashxt_token": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" }
```

따라서 다음 사용 가능한 Post를 가져오려면 이 meta 객체의 next\_token 값을 사용하여
아래와 같이 full-archive search 엔드포인트에 대한 API 호출의 next\_token 값으로 사용하세요
(자신의 Bearer Token과 이전 API 호출에서 얻은 Next Token 값을 사용해야 합니다).

```bash theme={null}
curl --request GET
'https://api.x.com/2/tweets/search/all?max_results=500&query=covid&next_token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
--header 'Authorization: Bearer $BEARER_TOKEN'
```

이렇게 하면 next\_token이 사용 가능한지 계속 확인하면서, 수집하고자 하는 원하는 Post 수에 도달하지 못한 경우
각 요청에 대해 새 next\_token을 사용하여 계속 full-archive 엔드포인트를 호출할 수 있습니다.

아래는 full-archive search 엔드포인트를 사용할 때 도움이 될 수 있는 리소스입니다. 여러분의 피드백을 기다리고 있습니다.
이 엔드포인트에 대한 질문이 있으면 [@XDevelopers](https://x.com/XDevelopers)나
[커뮤니티 포럼](https://devcommunity.x.com/)에서 저희에게 연락해 주세요.

### 추가 리소스

* [Full-archive search 엔드포인트 API 참조](/x-api/posts/full-archive-search)
* [검색 쿼리 만들기 기본기 익히기](/x-api/posts/search/integrate/build-a-query)