Skip to main content

​
소개

v2 세계의 Search Posts 엔드포인트를 사용하면 직접 만든 검색 쿼리를 기반으로 관심 주제와 관련된 Post를 받을 수 있습니다. v2 Search Posts에는 두 가지 다른 엔드포인트가 있습니다: recent search는 승인된 계정을 가진 모든 개발자가 사용할 수 있으며 최대 7일 이내의 Post를 검색할 수 있고, full-archive search는 Academic Research 제품 트랙에 승인된 연구자만 사용할 수 있으며, 2006년 3월까지 거슬러 올라가는 전체 Post 아카이브를 검색할 수 있습니다. 전체 검색 제공 사항은 검색 개요 페이지에서 확인할 수 있습니다. 이러한 Search Posts 엔드포인트는 학술 연구자들에게 가장 흔한 사용 사례 중 하나를 해결해 주며, 종단 연구나 과거 주제 또는 사건 분석에 활용할 수 있습니다. 이 튜토리얼은 공개 X 데이터의 전체 이력을 검색하기 위해 full-archive search 엔드포인트를 사용하려는 연구자를 위한 단계별 가이드를 제공합니다. 지오 태그가 있는 Post를 가져오는 등 데이터셋을 구축하는 다양한 방법과 쿼리에 대해 사용 가능한 Post를 페이지네이션하는 방법도 시연합니다.

​
사전 요건

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

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

Academic Research 제품 트랙 사용이 승인되면 Developer Console에서 Academic Project를 볼 수 있습니다. “Apps” 섹션에서 “Add App”을 클릭하여 X App을 Project에 연결하세요. Developer Console에 아직 App이 추가되지 않은 Academic Project가 표시된 이미지 그런 다음 (아래와 같이) 기존 App을 선택하여 프로젝트에 연결할 수 있습니다. Academic Project에 App을 추가하려고 할 때 나타나는 페이지를 보여주는 이미지 또는 새 App을 만들고 이름을 지정한 후 완료를 클릭하여 Academic Project에 새 App을 연결할 수도 있습니다. 새 App의 이름을 입력하거나 기존 App을 선택할 수 있는 페이지를 보여주는 이미지 이 과정에서 full-archive search 엔드포인트에 연결하는 데 사용할 수 있는 API 키와 Bearer Token이 제공됩니다. 새 App을 생성한 후 키와 토큰이 표시되는 페이지를 보여주는 이미지 참고 위 스크린샷의 키는 숨겨져 있지만, 자신의 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”을 누르세요.
응답 JSON이 표시됩니다. 기본적으로 가장 최근 10개의 Post만 반환됩니다. 요청당 10개 이상의 Post를 원한다면 아래와 같이 max_results 파라미터를 사용하여 요청당 최대 500개까지 설정할 수 있습니다:

​
쿼리 만들기

위의 예시 호출에서 볼 수 있듯이, query 파라미터를 사용하여 검색하려는 데이터를 지정할 수 있습니다. 예를 들어 covid 또는 _coronavirus_라는 단어가 포함된 모든 Post를 가져오려면 괄호 안에 OR 연산자를 사용할 수 있으며, 쿼리는 (covid OR coronavirus)가 되고 따라서 API 호출은 다음과 같습니다:
마찬가지로 리포스트가 아닌 _covid19_라는 단어가 포함된 모든 Post를 가져오려면 is:retweet 연산자와 논리 NOT(-로 표시)을 함께 사용할 수 있으므로, 쿼리는 covid19 -is:retweet이 되고 API 호출은 다음과 같습니다:
full-archive search 엔드포인트에서 지원되는 연산자 전체 목록은 이 가이드를 확인하세요.

​
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 호출은 다음과 같습니다:

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

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

​
has:geo 연산자 사용

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

​
place_country 연산자 사용

마찬가지로 place_country 연산자를 사용하여 지오 데이터가 있는 Post를 특정 국가로 제한할 수 있습니다. 아래 cURL 명령은 미국에서 발생한 @XDevelopers 핸들의 모든 Post를 가져옵니다:
국가는 위에서 ISO alpha-2 문자 코드를 사용하여 지정합니다. 유효한 ISO 코드는 여기에서 확인할 수 있습니다.

​
next_token을 사용하여 500개 이상의 과거 Post 가져오기

위에서 언급한 것처럼, full-archive search 엔드포인트 쿼리는 기본적으로 요청당 최대 500개의 Post만 가져올 수 있습니다. 쿼리에 500개 이상의 Post가 있다면 JSON 응답에 next_token이 포함되며, 이를 API 호출에 추가하여 쿼리에 대한 다음 사용 가능한 Post를 가져올 수 있습니다. 이 next_token은 JSON 응답의 meta 객체에서 사용할 수 있으며, 다음과 같은 모양입니다:
따라서 다음 사용 가능한 Post를 가져오려면 이 meta 객체의 next_token 값을 사용하여 아래와 같이 full-archive search 엔드포인트에 대한 API 호출의 next_token 값으로 사용하세요 (자신의 Bearer Token과 이전 API 호출에서 얻은 Next Token 값을 사용해야 합니다).
이렇게 하면 next_token이 사용 가능한지 계속 확인하면서, 수집하고자 하는 원하는 Post 수에 도달하지 못한 경우 각 요청에 대해 새 next_token을 사용하여 계속 full-archive 엔드포인트를 호출할 수 있습니다. 아래는 full-archive search 엔드포인트를 사용할 때 도움이 될 수 있는 리소스입니다. 여러분의 피드백을 기다리고 있습니다. 이 엔드포인트에 대한 질문이 있으면 @XDevelopers나 커뮤니티 포럼에서 저희에게 연락해 주세요.

​
추가 리소스