메인 콘텐츠로 건너뛰기

​
최근 검색 페이지 매기기

​
소개

검색 쿼리는 일반적으로 단일 API 응답으로는 모두 반환할 수 없을 만큼 많은 게시물과 일치합니다. 이 경우 데이터는 여러 ‘페이지’로 나누어 반환됩니다. 페이지네이션은 전체 데이터 세트를 조회하기 위해 모든 페이지를 순차적으로 요청하는 방법을 말합니다. 다음은 최근 검색 페이지네이션의 핵심 사항입니다:
  • 최근 검색 엔드포인트는 쿼리에 최소 한 페이지로 응답하며, 추가 페이지가 있을 경우 JSON 응답에 next_token을 제공합니다. 일치하는 게시물을 모두 받기 위해서는 응답에 토큰이 더 이상 포함되지 않을 때까지 이 과정을 반복하면 됩니다.
  • next_token은 만료되지 않습니다. 동일한 next_token 값을 사용한 여러 요청은 요청 시점과 무관하게 동일한 결과를 반환합니다.
  • 게시물은 UTC 시간대를 기준으로 최신순(내림차순)으로 제공됩니다. 이는 개별 페이지 내에서도, 여러 페이지 전반에서도 동일합니다:
    • 첫 번째 응답의 첫 번째 게시물은 쿼리와 일치하는 가장 최신 게시물입니다.
    • 마지막 응답의 마지막 게시물은 쿼리와 일치하는 가장 오래된 게시물입니다.
  • max_results 요청 파라미터를 사용하면 응답당 반환되는 게시물 수를 설정할 수 있습니다. 기본값은 게시물 10개이며 최대 100개까지 설정할 수 있습니다.
  • 모든 페이지네이션 구현에는 응답 페이로드에서 next_token을 파싱하여 ‘다음 페이지’ 검색 요청에 포함하는 과정이 필요합니다. 이러한 ‘다음 페이지’ 요청을 구성하는 방법에 대한 자세한 내용은 아래를 참고하세요.  
최근 검색 엔드포인트는 두 가지 기본 사용 패턴을 지원하도록 설계되었습니다:
  • 히스토리컬 조회 - 관심 있는 기간의 일치하는 게시물을 요청합니다. 이는 보통 히스토리컬 리서치를 위한 일회성 요청입니다. 검색 요청은 start_time 및 end_time 요청 파라미터를 기반으로 할 수 있습니다. 최근 검색 엔드포인트는 가장 최신의 일치하는 게시물부터 시작해 최신순으로 게시물을 반환합니다.
  • 폴링 - 마지막으로 받은 게시물 이후에 게시된 일치하는 게시물을 요청합니다. 이 사용 사례는 근실시간 용도가 많으며, 관심 있는 새로운 게시물을 “수신”하기 위해 빈번한 요청이 특징입니다. 최근 검색 엔드포인트는 ‘폴링’ 패턴을 지원하기 위해 since_id 요청 파라미터를 제공합니다. 게시물 ID를 기준으로 탐색하는 데 도움이 되도록 until_id 요청 파라미터도 제공됩니다.  
다음으로 히스토리컬 모드에 대해 설명합니다. 이는 최근 검색 엔드포인트의 기본 모드이며 페이지네이션의 기본 개념을 보여줍니다. 이후 폴링 사용 사례의 예시를 다룹니다. 폴링으로 인해 페이지네이션이 발생하는 경우, 검색 요청을 관리하기 위한 추가 단계가 필요합니다.  

​
과거 데이터 조회

이 섹션에서는 start_time 및 end_time 요청 매개변수를 사용하여 관심 있는 기간(현재는 최근 7일로 제한)의 게시물을 조회하는 방법을 설명합니다. 과거 데이터 요청은 일반적으로 연구 및 분석을 위한 일회성 요청입니다.  기간 기반 요청은 최근 검색 엔드포인트의 기본 동작입니다. 검색 요청에서 start_time, end_time 또는 since_id 요청 매개변수를 지정하지 않으면 end_time은 기본적으로 “지금”(실제로는 쿼리 시각보다 30초 이전)으로, start_time은 기본적으로 7일 전으로 설정됩니다. 엔드포인트는 가장 최근 게시물부터 시작해 최신순(역순)으로 첫 번째 ‘페이지’의 게시물을 반환합니다. 응답 JSON 페이로드에는 추가 페이지가 있는 경우 next_token도 포함됩니다. 페이지 수와 관계없이 일치하는 전체 게시물 집합을 수집하려면 next_token이 더 이상 제공되지 않을 때까지 요청을 반복합니다.  예를 들어, 지난주 동안 키워드 snow가 포함된 게시물에 대한 초기 요청은 다음과 같습니다: https://api.x.com/2/tweets/search/recent?query=snow 응답에는 가장 최근 10개의 게시물과 함께 JSON 응답의 다음과 같은 “meta” 속성이 포함됩니다: 
"meta": {
        "newest_id": "1204860593741553664",
        "oldest_id": "1204860580630278147",
        "next_token": "b26v89c19zqg8o3fobd8v73egzbdt3qao235oql",
        "result_count": 10
    }
다음 10개의 게시물을 가져오려면 이 next_token을 원래 요청에 추가합니다. 요청은 다음과 같습니다: https://api.x.com/2/tweets/search/recent?query=snow&next_token=b26v89c19zqg8o3fobd8v73egzbdt3qao235oql next_token을 확인해 이후 요청에 포함하는 과정을 모든(또는 일정 개수의) 게시물을 수집할 때까지, 또는 지정된 요청 횟수에 도달할 때까지 반복할 수 있습니다. 데이터 충실도(쿼리와 일치하는 모든 결과를 수집하는 것)가 사용 사례에서 핵심이라면, 단순히 “request.next_token이 null이 될 때까지 반복”하는 설계로 충분합니다.

​
폴링 및 리스닝 사용 사례

이 섹션에서는 since_id 요청 매개변수를 사용해 최근 검색 엔드포인트를 폴링하여 최신 게시물을 가져오는 방법을 설명합니다. 폴링 사용 사례에서는 “관심 있는 새로운 게시물이 있나요?”라는 쿼리를 지속적이고 빈번하게 실행합니다. 시간 기준으로 요청하는 히스토리컬 사용 사례와 달리, 폴링 사용 사례는 일반적으로 게시물 ID를 기준으로 요청합니다. 폴링 패턴의 핵심은 모든 새 게시물이 X 플랫폼에서 일반적으로 오름차순으로 ‘발행’되는 고유 ID를 가진다는 점입니다. 어떤 게시물의 ID가 다른 것보다 작다면 더 먼저 게시되었음을 의미합니다. 최근 검색 엔드포인트는 게시물 ID를 기준으로 게시물 아카이브를 탐색하는 기능을 지원합니다. 이 엔드포인트의 응답에는 oldest_id와 newest_id 게시물 ID가 포함됩니다. 폴링 모드에서는 지금까지 받은 가장 큰/최신 ID를 since_id로 설정해 요청합니다. 예를 들어, ‘snow’에 관한 새로운 게시물을 5분마다 조회하고 마지막으로 받은 게시물의 게시물 ID가 10000이라고 가정해 보겠습니다. 폴링 시점의 요청은 다음과 같습니다: https://api.x.com/2/tweets/search/recent?query=snow&since_id=10000 다음으로, 마지막 요청 이후 게시물 7개가 게시되었다고 가정해 보겠습니다. 이 모든 항목이 단일 데이터 ‘페이지’에 담기므로 next_token은 없습니다. 응답에는 가장 최근(최신) 게시물의 게시물 ID가 제공됩니다: 
"meta": {
        "newest_id": "12000",
        "oldest_id": "10005",
        "result_count": 7
    }
다음 폴링 쿼리를 수행하기 위해 이 newest_id 값은 다음 since_id 매개변수를 설정하는 데 사용됩니다: https://api.x.com/2/tweets/search/recent?query=snow&since_id=12000 더 많은 데이터가 있고 next 토큰이 제공되는 경우 결과의 첫 페이지에 있는 newest_id 값만 필요합니다. 각 데이터 페이지에는 newest_id 및 oldest_id 값이 포함되지만, 정기적으로 수행되는 다음 폴링 요청에는 첫 페이지에서 제공된 값만 사용하면 됩니다. 따라서 폴링 방식을 구현하거나 ID 범위로 게시물을 검색하는 경우 페이지네이션 로직이 약간 더 복잡해집니다.  이제 일치하는 게시물이 18개 더 있다고 가정해 봅시다. 이 엔드포인트는 이 5분 구간의 다음 데이터 페이지를 요청할 수 있도록 전체 데이터 페이지와 next_token이 포함된 초기 응답을 반환합니다. 또한 5분 후 다음 폴링 구간에 필요한 최신 게시물 ID도 포함합니다. 
"meta": {
        "newest_id": "13800",
        "oldest_id": "12500",
        "next_token": "fnsih9chihsnkjbvkjbsc",
        "result_count": 10
    }
이 5분 기간에 해당하는 모든 일치 데이터를 수집하려면 다음 요청에서 이전 요청과 동일한 since_id 값과 함께 next_token을 전달하세요. https://api.x.com/2/tweets/search/recent?query=snow&since_id=12000&next_token=fnsih9chihsnkjbvkjbsc 
"meta": {
        "newest_id": "12300",
        "oldest_id": "12010",
        "result_count": 8
    }
두 번째 응답에는 나머지 8개의 게시물이 포함되어 있으며, next_token은 없습니다. newest_id 값(12300)은 업데이트하지 않고, 대신 첫 번째 응답의 newest_id 값을 기준으로 다음 since_id 요청을 보냅니다: https://api.x.com/2/tweets/search/recent?query=snow&since_id=13800