Skip to main content

​
표준 v1.1 타임라인에서 X API v2 타임라인으로

v1.1 타임라인 엔드포인트(statuses/user_timeline 및 statuses/mentions_timeline)를 사용해 왔다면, 이 가이드는 표준 타임라인 엔드포인트와 X API v2 타임라인 엔드포인트 간의 공통점과 차이점을 이해해 현재 통합을 새 버전으로 마이그레이션하는 데 도움을 주는 것을 목표로 합니다.
  • 유사점:
    • 인증:
      • OAuth 1.0a User Context (시간 역순 홈 타임라인, 사용자 게시물 타임라인 및 사용자 멘션 타임라인)
      • OAuth 2.0 App-Only (사용자 게시물 타임라인)
    • 과거 데이터 접근 한도: User timeline(사용자 게시물 타임라인)은 가장 최근 3200개의 포스트에 대한 접근을 제공합니다. mentions timeline(사용자 멘션 타임라인)은 가장 최근 800개의 멘션에 대한 접근을 제공합니다.
    • 게시물 편집 이력 및 메타데이터 지원
    • 요청 한도(사용자 게시물 타임라인)
    • 폴링을 통한 새로 고침: since_id 이후의 새 결과를 가져오는 기능
    • 게시물 id를 사용한 타임라인 탐색
    • 결과 사양:
      • 결과 순서: 결과는 시간 역순으로 반환됨
      • 답글 제외 기능(사용자 게시물 타임라인에만 해당)
      • 리트윗 제외 기능(사용자 게시물 타임라인에만 해당)
  • 차이점
    • 새로운 인증 기능:
      • OAuth 2.0 App-Only (사용자 멘션 타임라인)
      • OAuth 2.0 Authorization Code Flow with PKCE (시간 역순 홈 타임라인, 사용자 게시물 타임라인 및 사용자 멘션 타임라인)
    • 액세스 요건: X API v2 App 및 Project 요건
    • 요청 한도(사용자 멘션 타임라인 및 시간 역순 홈 타임라인)
    • 추가 페이지네이션 방식
      • 응답당 서로 다른 max_results(개수)
    • 응답 데이터 형식
    • 요청 매개변수
      • v2 필드와 expansions를 포함한, 요청 매개변수 기반 맞춤형 데이터 형식
      • 추가로 제공되는 데이터: 메트릭, 게시물 주석(annotations), 투표(polls)

​
유사점

인증 v1.1 statuses/user_timeline과 X API v2 사용자 게시물 타임라인 엔드포인트는 모두 OAuth 1.0a 사용자 컨텍스트와 OAuth 2.0 App-Only를 지원합니다. 따라서 X API v2 버전으로 마이그레이션하더라도 동일한 인증 방식과 권한 부여 토큰을 계속 사용할 수 있습니다. 과거 데이터 접근 v1.1 statuses/user_timeline과 X API v2 사용자 게시물 타임라인 엔드포인트는 모두 리트윗을 포함하여 가장 최근 포스트 3200개를 반환합니다. v1.1 statuses/mentions_timeline과 X API v2 사용자 멘션 타임라인 엔드포인트는 가장 최근 포스트 800개를 반환할 수 있습니다. 게시물 편집 기록 및 메타데이터 지원 두 버전 모두 편집 이력을 나타내는 메타데이터를 제공합니다. 자세한 내용은 필터링된 스트림 API 참조 문서와 게시물 편집 기본 개념 페이지를 참고하세요. 요청 한도
Standard v1.1X API v2
user_timeline:

OAuth 1.0a 사용자 컨텍스트 기준 15분당 900개 요청

OAuth 2.0 App-Only 기준 15분당 1500개 요청		사용자 게시물 타임라인:

OAuth 1.0a 사용자 컨텍스트 기준 15분 윈도우당 900개 요청

OAuth 2.0 App-Only 기준 15분 윈도우당 1500개 요청
since_id를 사용한 새로 고침 폴링 두 버전 모두 since_id를 사용하여 최신 결과를 폴링할 수 있습니다. 게시물 ID로 타임라인 순회 두 엔드포인트 모두 게시물 ID가 구성되는 방식에 기반해 게시물 ID ‘타임스탬프’를 사용하여 타임라인을 순회할 수 있습니다. 기능은 일반적으로 동일하지만, 다음과 같은 차이가 있습니다.
Standard timelines v1.1timelines v2
since_id(배타적)

max_id(포함)		since_id(배타적)

until_id(역시 배타적이며, 포함 범위였던 max_id와는 다름)
응답 필터링 매개변수
Standard timelines v1.1timelines v2
응답 필터링 매개변수:

* include_rts
* exclude_replies		응답 필터링 매개변수:

* exclude=retweets,replies
예시:

https://api.x.com/1.1/statuses/user_timeline.json?user_id=2244994945&include_rts=0&&exclude_replies=1		예시:

https://api.x.com/2/users/2244994945/tweets?max_results=100&exclude=retweets,replies
참고:

user_timeline의 경우:

* include_rts=0을 사용해도 조회 가능한 과거 포스트 한도(가장 최근 3200개)는 변경되지 않습니다		참고:

사용자 게시물 타임라인의 경우:

* exclude=retweets를 사용해도 조회 가능한 과거 포스트 한도(가장 최근 3200개)는 변경되지 않습니다
* exclude=replies를 사용하면 조회 가능한 과거 포스트 한도가 가장 최근 답글 800개로 줄어듭니다

​
Differences

인증 **v1.1 statuses/mentions_timeline 엔드포인트는 OAuth 1.0a User Context만 지원합니다. X API v2 user mention timeline 엔드포인트는 OAuth 1.0a User Context, OAuth 2.0 App-Only, OAuth 2.0 Authorization Code with PKCE를 모두 지원합니다. ** X API v2 user Post timeline 엔드포인트를 사용해 비공개 또는 프로모션 메트릭에 액세스하려면 OAuth 1.0a User Context 또는 OAuth 2.0 Authorization Code with PKCE를 사용하고, 메트릭에 액세스하려는 게시물을 게시한 사용자와 연결된 사용자 액세스 토큰을 전달해야 합니다. 엔드포인트 URL X API v2 timelines 엔드포인트에는 사용자 ID에 대한 경로 매개변수 :id가 필요합니다. App 및 Project 요구 사항 X API v2 엔드포인트는 요청을 인증할 때 developer App에서 발급되고 Project에 연결된 자격 증명을 사용해야 합니다. 모든 X API v1.1 엔드포인트는 Project에 연결된 App이든 연결되지 않은 App이든 자격 증명을 사용할 수 있습니다. 요청 한도
mentions_timeline:

OAuth 1.0a User Context 사용 시 15분당 75회 요청		user mention timeline:

OAuth 1.0a User Context 사용 시 15분당 180회 요청
OAuth 2.0 Bearer Token 사용 시 15분당 450회 요청
home_timelime:

15분당 15회 요청

홈 타임라인에서 최대 800개의 포스트를 가져올 수 있습니다.		reverse chronological home timeline:

15분당 180회 요청

지난 7일 동안 타임라인에서 생성된 모든 포스트뿐 아니라 생성 날짜와 관계없이 가장 최근의 800개 포스트를 모두 반환할 수 있습니다.
요청 매개변수
Standard timelines v1.1timelines v2
Required: user_id or screen_nameRequired: 경로 매개변수에 특정 사용자 ID를 지정해야 함
Optional:

count - 요청당 반환되는 최대 결과 수 설정

exclude_replies - 결과에서 답글 제거

Include_rts - 0으로 설정하면 결과에서 리트윗 제거

trim_user - 결과에서 재수화된 사용자 객체 제거

tweet_mode - 결과에 대해 반환되는 데이터 형식을 설정하며, 140자를 초과하는 게시물의 경우 extended로 설정

since_id - 결과에서 가장 이른 게시물 ID 설정(제외 범위)

max_id - 결과에서 가장 최신 게시물 ID 설정(포함 범위)		Optional:

max_results - 요청당 반환되는 최대 결과 수 설정

exclude=retweets,replies - 결과에서 리트윗 또는 답글 제거

tweet.fields - 반환할 게시물 객체 필드 설정

user.fields - 반환할 사용자 객체 필드 설정

place.fields - 반환할 장소 객체 필드 설정

media.fields - 반환할 미디어 객체 필드 설정

poll.fields - 반환할 투표 객체 필드 설정

expansions - 반환할 확장 필드 및 데이터 설정

start_time - 결과에 대해 가장 이른 created_at 시간 설정

end_time - 결과에 대해 가장 최신 created_at 시간 설정

since_id - 결과에서 가장 이른 게시물 ID 설정(제외 범위)

until_id - 결과에서 가장 최신 게시물 ID 설정(제외 범위)
Response data format
Standard search v1.1Search Posts v2
[
tweet object,
tweet object
]
“data”: [id,text,id,text],
“meta”:
“oldest_id”: “1337085692623646724”,
“newest_id”: “1334183616172019713”,
“previous_token”: “77qpymm88g5h9vqkluldpw91lr0qzfz1sqydh841iz48k”,
“result_count”: 10,
“next_token”: “7140dibdnow9c7btw3w29gqolns6a1ipl3kzeae41vsxk”

X API v2 JSON format X API v2는 게시물 및 사용자 객체를 포함하여 API가 반환하는 객체에 대해 새로운 JSON 설계를 도입하고 있습니다. X API v2 형식과 필드 및 expansions를 사용하는 방법에 대해서는 가이드를 참고하고, 보다 폭넓은 데이터 사전을 읽어보며 자세히 알아볼 수 있습니다.
  • JSON 루트 수준에서 표준 엔드포인트는 statuses 배열에 게시물 객체를 반환하는 반면, X API v2는 data 배열을 반환합니다.
  • 리트윗 및 인용 “statuses”를 참조하는 대신, X API v2 JSON은 리트윗 및 인용 Tweet을 참조합니다. contributors 및 user.translator_type과 같은 많은 레거시 및 사용 중단 필드는 제거되고 있습니다.
  • 게시물 객체와 사용자 객체 둘 다에서 favorites를 사용하는 대신, X API v2는 like라는 용어를 사용합니다.
  • X는 값이 없는 JSON 값(예: null)은 페이로드에 기록하지 않는 규칙을 채택하고 있습니다. 게시물 및 사용자 속성은 null이 아닌 값을 가진 경우에만 포함됩니다.
표준 v1.1 엔드포인트와 X API v2 엔드포인트 버전 간의 가장 큰 차이점 중 하나는 페이로드에 어떤 필드를 반환할지 선택하는 방식입니다. 표준 엔드포인트의 경우 페이로드에 어떤 필드 또는 필드 집합이 반환될지 식별하기 위해 사용할 수 있는 여러 매개변수가 있는 반면, X API v2 버전은 이러한 서로 다른 매개변수를 fields 및 expansions로 단순화합니다.
  • fields: X API v2 엔드포인트를 사용하면 페이로드에 어떤 필드가 포함될지 선택할 수 있습니다. 예를 들어, 게시물, 사용자, 미디어, 장소, 투표 객체에는 모두 반환할 수 있는(또는 반환하지 않을 수 있는) 필드 목록이 있습니다.
  • expansions: 게시물 JSON 페이로드에서 참조되는 관련 객체를 확장하는 데 사용됩니다. 예를 들어, 모든 리포스트와 답글은 다른 포스트를 참조합니다. expansions=referenced_tweets.id로 설정하면 이러한 다른 게시물 객체는 tweet.fields 설정에 따라 확장됩니다. 사용자, 투표, 미디어와 같은 다른 객체도 확장할 수 있습니다.
  • conversation_id
  • context 및 entities를 포함한 두 개의 새로운 annotations 필드
  • 여러 개의 새로운 metrics 필드
표준 v1.1 필드를 최신 v2 필드에 매핑하는 데 도움이 되는 데이터 형식 마이그레이션 가이드를 제공하고 있습니다. 이 가이드는 또한 특정 필드를 반환하기 위해 v2 요청에 함께 전달해야 하는 expansions 및 fields 파라미터를 구체적으로 안내합니다.

​
코드 예제

​
사용자 포스트 타임라인 (v2)

cURL
curl "https://api.x.com/2/users/2244994945/tweets?max_results=100&tweet.fields=created_at,public_metrics&exclude=retweets,replies" \
  -H "Authorization: Bearer $BEARER_TOKEN"

​
사용자 멘션 타임라인 (v2)

cURL
curl "https://api.x.com/2/users/2244994945/mentions?max_results=100&tweet.fields=created_at,author_id" \
  -H "Authorization: Bearer $BEARER_TOKEN"
다음 단계 X API v2 게시물 조회를 위한 빠른 시작 가이드를 확인하세요 v2 게시물 조회에 대한 API 참조 문서를 검토하세요 타임라인 엔드포인트용 샘플 코드를 확인하세요