v2 전체 아카이브 검색 엔드포인트로 과거 게시물 가져오기

​

소개

v2 환경의 Search Posts 엔드포인트는 사용자가 작성한 검색 쿼리를 기반으로 관심 있는 주제와 관련된 게시물을 받을 수 있도록 해줍니다. v2 Search Posts에는 두 가지 엔드포인트가 있습니다. 승인된 계정을 가진 모든 개발자가 사용할 수 있으며 최대 7일 전 게시물까지 검색할 수 있는 최근 검색과, Academic Research product track에 승인된 연구자만 사용할 수 있고 2006년 3월까지 거슬러 올라가는 전체 게시물 아카이브를 검색할 수 있는 전체 아카이브 검색입니다.

전체 검색 기능은 검색 개요 페이지에서 확인할 수 있습니다.

이러한 Search Posts 엔드포인트는 종단 간 연구나 과거 주제 또는 이벤트 분석 등 학술 연구자들의 가장 일반적인 사용 사례를 충족합니다.

이 튜토리얼은 퍼블릭 X 데이터의 전체 기록을 검색하기 위해 전체 아카이브 검색 엔드포인트를 사용하려는 연구자를 위한 단계별 가이드를 제공합니다. 또한 지오태그된 게시물을 가져오는 등 데이터세트를 구축하는 다양한 방법과, 쿼리에 대해 사용 가능한 게시물을 페이지로 나누어 살펴보는 방법을 설명합니다.

​

사전 요구 사항

현재 이 엔드포인트는 Academic Research product track의 일부로만 제공됩니다. 이 엔드포인트를 사용하려면 액세스 신청이 필요합니다. 이 트랙의 신청 절차와 요건에 대해 자세히 알아보세요.

​

학술 프로젝트에 앱 연결하기

Academic Research 제품 트랙 사용 승인을 받으면, developer portal에서 학술 Project를 확인할 수 있습니다. “Projects and Apps” 섹션에서 “Add App”을 클릭하여 X App을 Project에 연결하세요.

그다음, 기존 App을 선택해 프로젝트에 연결할 수도 있습니다(아래 참고).

또는 새 App을 만들어 이름을 지정한 뒤 Complete를 클릭하여, Academic Project에 새 App을 연결할 수 있습니다.

이 과정이 완료되면 API 키와 Bearer Token을 받게 되며, 이를 사용하여 전체 아카이브 검색 엔드포인트에 연결할 수 있습니다.

유의 사항

위 스크린샷의 키는 숨겨져 있지만, 본인의 개발자 포털에서는 API Key, API Secret Key, 그리고 Bearer Token의 실제 값을 확인할 수 있습니다. 이 키들과 Bearer Token은 전체 아카이브 검색 엔드포인트를 호출할 때 필요하므로 반드시 저장해 두세요.

​

전체 아카이브 검색 엔드포인트에 연결하기

아래 cURL 명령은 @XDevelopers 핸들의 과거 게시물을 가져오는 방법을 보여줍니다. $BEARER_TOKEN을 본인의 베어러 토큰으로 바꾼 뒤, 전체 요청을 터미널에 붙여넣고 “return” 키를 누르세요.

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

응답 JSON이 표시됩니다.

기본적으로 최신 게시물 10개만 반환됩니다. 한 요청에서 10개보다 많은 게시물을 원한다면 아래와 같이 max_results 매개변수를 사용해 요청당 최대 500개의 게시물로 설정할 수 있습니다.

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를 포함하는 모든 게시물을 가져오려면 괄호 안에 OR 연산자를 사용해 쿼리를 (covid OR coronavirus)처럼 작성하면 되며, 그러면 API 호출은 다음과 같이 표시됩니다:

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

마찬가지로, 재게시물이 아닌 게시물 중 단어 covid19를 포함한 모든 게시물을 조회하려면, is:retweet 연산자에 논리 부정(하이픈 -로 표시됨)을 함께 사용할 수 있습니다. 즉, 쿼리는 covid19 -is:retweet가 되며 API 호출은 다음과 같습니다:

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

다음 문서를 확인하세요: 전체 아카이브 검색 엔드포인트에서 지원되는 연산자 전체 목록 가이드 전체 아카이브 검색 엔드포인트에서 지원되는 연산자 전체 목록 가이드

​

start_time 및 end_time 매개변수를 사용하여 과거 게시물 가져오기

전체 아카이브 검색 엔드포인트를 사용할 때 기본적으로 최근 30일치 게시물이 반환됩니다. 30일보다 오래된 게시물을 가져오려면 API 호출에서 start_time 및 end_time 매개변수를 사용할 수 있습니다. 이 매개변수는 RFC3339 유효 날짜·시간 형식이어야 하며, 예를 들어 2020-12-21T13:00:00.00Z와 같습니다. 따라서 2020년 12월 한 달 동안 XDevelopers 계정의 모든 게시물을 가져오려면 API 호출은 다음과 같습니다.

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'

​

지오태그된 과거 게시물 가져오기

지오태그된 게시물은 도시, 주/도, 국가 등과 같은 지리 정보가 연결된 게시물을 말합니다.

​

has:geo 연산자 사용

지리 정보가 포함된 게시물을 조회하려면 has:geo 연산자를 사용할 수 있습니다. 예를 들어, 다음 cURL 요청은 지리 정보가 포함된 @XDevelopers 계정의 게시물만 가져옵니다:

curl --request GET
'https://api.x.com/2/tweets/search/all?query=from:xdevelopers%20has:geo' --header
'Authorization: Bearer $BEARER_TOKEN'

​

place_country 연산자 사용

마찬가지로 place_country 연산자를 사용하면 지리 정보가 포함된 게시물을 특정 국가로 한정할 수 있습니다. 아래 cURL 명령은 미국 지역의 @XDevelopers 계정에서 작성된 모든 게시물을 가져옵니다:

curl --request GET
'https://api.x.com/2/tweets/search/all?query=from:xdevelopers%20place_country:US'
--header 'Authorization: Bearer XXXXX'

국가는 위에서 ISO 알파-2 문자 코드로 지정됩니다. 유효한 ISO 코드는 여기에서 확인할 수 있습니다.

​

next_token을 사용해 500개 초과 과거 게시물 가져오기

앞서 언급했듯이, 기본적으로 전체 아카이브 검색 엔드포인트에 대한 한 번의 요청으로 최대 500개의 게시물만 가져올 수 있습니다. 쿼리 결과가 500개를 초과하는 경우, JSON 응답에 next_token이 포함되며 이를 API 호출에 추가해 해당 쿼리의 다음 게시물을 가져올 수 있습니다. 이 next_token은 JSON 응답의 meta 객체에 포함되어 있으며, 예시는 다음과 같습니다:

{ "newest_id": "12345678...", "oldest_id": "12345678...", "result_count": 500,
"nebashxt_token": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" }

따라서 다음 게시물을 가져오려면 이 meta 객체의 next_token 값을 가져와, 아래 예시처럼 전체 아카이브 검색 엔드포인트에 대한 API 호출의 next_token 값으로 사용하세요(본인의 베어러 토큰과 이전 API 호출에서 받은 next token 값을 사용하게 됩니다).

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의 사용 가능 여부를 계속 확인할 수 있으며, 수집하려는 게시물 수에 아직 도달하지 않았다면 각 요청마다 새로운 next_token과 함께 전체 아카이브 엔드포인트를 계속 호출하면 됩니다. 전체 아카이브 검색 엔드포인트 호출은 게시물 상한, 즉 X API에서 Project당 한 달에 가져올 수 있는 게시물 수에 포함되므로, 결과를 페이지네이션할 때 코드 로직을 신중히 설계하여 게시물 상한을 의도치 않게 소진하지 않도록 하십시오.

아래는 전체 아카이브 검색 엔드포인트 사용 시 도움이 될 수 있는 몇 가지 리소스입니다. 여러분의 피드백을 듣고 싶습니다. 이 엔드포인트에 대한 질문은 @XDevelopers 또는 커뮤니티 포럼에서 문의해 주세요.

​

추가 리소스

• 전체 아카이브 검색 엔드포인트 API 참고 문서 (/x-api/posts/full-archive-search)
• 검색 쿼리 작성 기본 사항 알아보기 (/x-api/posts/search/integrate/build-a-query)