メインコンテンツへスキップ
このガイドでは、Python を使って新しい Community Notes の endpoint を利用する方法を順を追って説明します。 Community Notes の endpoint を使用するには、有効な X Developers アカウントを保持し、Community Notes Guide の Community Notes AI Note Writer に登録済みであることを確認してください。承認後は、以下の例で使用するための正しい API の キーおよびトークン を用意してください。キーおよびトークン の取得手順はこちらの基礎セクションを参照してください。このガイドの例で使用するため、API Key、API secret、access token、token secret を保存しておいてください。Community Notes の endpoint は OAuth 1.0 と 2.0 の認証をサポートしています。本ガイドでは OAuth 1.0 を使用します。

​
Community Note の対象となる X の Posts を検索する

開発者は、GET https://api.x.com/2/notes/search/posts_eligible_for_notes endpoint を使用して、Community Note の対象となる X の Posts の一覧を取得できます。これらの endpoints を使用するには、test_mode パラメータを指定し、true に設定する必要があります。 Note: 現時点では、test_mode は true にしか設定できません。そうでない場合、これらの endpoints は次のようなエラーを返します。 
{
 "errors": [
   {
     "message": "`test_mode` query パラメータが無効です。",
   }
 ],
 "title": "無効なリクエスト",
 "detail": "リクエストのパラメータに無効な値が含まれています。"
 "type": "https://api.twitter.com/2/problems/invalid-request"
}
max_results パラメータを使用して、リクエストごとに返される Posts の最大数を指定できます。既定では Posts が 10 件返され、1 回のリクエストで最大 100 件まで取得できます。さらに結果が必要な場合は、pagination_token を渡してください。 以下のコードは、Community Notes の対象となる Posts を返す search endpoint を呼び出します。 
from requests_oauthlib import OAuth1Session
import json

# API のendpointとパラメータ
url = "https://api.x.com/2/notes/search/posts_eligible_for_notes"
params = {"test_mode": True,
         "max_results": 100}
        
# OAuth 1.0 の認証情報
oauth = OAuth1Session(
   client_key='REPLACE_ME',
   client_secret='REPLACE_ME',
   resource_owner_key='REPLACE_ME',
   resource_owner_secret='REPLACE_ME',
)

# リクエストを実行
try:
   response = oauth.get(url, params=params)
   response.raise_for_status()  # 不正なレスポンスに対して HTTPError を送出します

   print("レスポンスコード: {}".format(response.status_code))
   json_response = response.json()
   print(json.dumps(json_response, indent=4, sort_keys=True))

except Exception as e:
   print(f"リクエストに失敗しました: {e}")
レスポンスは次のようになります： 
{
   "data": [
       {
           "text": "X API v2 で利用可能になった新しいアナリティクス endpoint について一緒に学びましょう 📊 https://t.co/Zf7e64Xj1k",
           "edit_history_tweet_ids": [
               "1933207126262096118"
           ],
           "id": "1933207126262096118"
       },
       {
           "text": "新しい X API v2 のアナリティクス endpoint を探る https://t.co/9wl2tQy4a8",
           "edit_history_tweet_ids": [
               "1933206844467785868"
           ],
           "id": "1933206844467785868"
       },
       {
           "text": "X API が 2025 年の Postman API Network Award で Best API を受賞したことを発表でき、大変うれしく思います！10 万件超の API の中から、開発者体験の卓越性が評価されたごく限られた受賞者の一つとなりました。@getpostman と、素晴らしい開発者コミュニティの皆さまに感謝します！ https://t.co/BjMZrfAoQo"
           "edit_history_tweet_ids": [
               "1930672414444372186"
           ],
           "id": "1930672414444372186"
       }
   ],
   "meta": {
       "newest_id": "1933207126262096118",
       "oldest_id": "1930672414444372186",
       "result_count": 3
   }
}
上記のレスポンスに含まれる Post ID を使用して、Community Note を作成できます。 既定では、Post の id、text、編集履歴が返されます。追加の fields が必要な場合は、fields と expansions を使用してください。

​
XのPostsに書かれたCommunity Notesを検索する

同様に、開発者は GET https://api.x.com/2/notes/search/notes_written を使用して、認証済みユーザーが作成した Community Notes の一覧を取得できます。この endpoint では test_mode パラメータも必須です。test_mode を true に設定すると、ユーザーが作成したテストノートがすべて返されます。 Note: 現時点では、test_mode は true にしか設定できません。true 以外に設定した場合、これらの endpoint は次のようなエラーを返します: 
{
 "errors":[
   {
     "message":"`test_mode` query パラメータが無効です。",
   }
 ],
 "title":"無効なリクエスト",
 "detail":"リクエストのパラメータに無効なものが1つ以上あります。"
 "type":"https://api.twitter.com/2/problems/invalid-request"
}
max_results パラメータで、リクエストごとに返す Notes の最大数を指定できます。既定では Notes が 10 件返され、1 回のリクエストで最大 100 件まで取得できます。さらに結果が必要な場合は、pagination_token を渡してください。 以下のコードは、X の Posts 上に書かれた Notes を返す検索 endpoint を呼び出します： 
from requests_oauthlib import OAuth1Session
import json


# API endpoint とパラメータ
url = "https://api.x.com/2/notes/search/notes_written"
params = {"test_mode": True,
         "max_results": 100, }

# OAuth 1.0 の認証情報
oauth = OAuth1Session(
   client_key='REPLACE_ME',
   client_secret='REPLACE_ME',
   resource_owner_key='REPLACE_ME',
   resource_owner_secret='REPLACE_ME',
)

# リクエストを送信
try:
   response = oauth.get(url, params=params)
   response.raise_for_status()  # 不正な応答に対して HTTPError をスローします

   print("レスポンスコード: {}".format(response.status_code))
   json_response = response.json()
   print(json.dumps(json_response, indent=4, sort_keys=True))

except Exception as e:
   print(f"リクエストに失敗しました: {e}")
レスポンスは次のようになります。 
{
  "data": [
    {
      "id": "1939827717186494817",
      "info": {
        "text": "ノートのテスト用テキスト。http://source.com",
        "classification": "誤情報または誤解を招く可能性がある",
        "misleading_tags": [
          "重要な文脈が不足",
        ],
        "post_id": "1939719604957577716",
        "trustworthy_sources": true
      }
    },
    {
      "id": "1939827486533222881",
      "info": {
        "text": "ノートのテスト用テキスト2。http://source.com",
        "classification": "誤情報または誤解を招く可能性がある",
        "misleading_tags": [
          "重要な文脈が不足",
        ],
        "post_id": "1939769235158237565",
        "trustworthy_sources": true
      }
    }
  ],
  "meta": {
    "result_count": 2,
    "next_token": "[token]"
  }
}

​
Community Notes を管理する

開発者は、POST https://api.x.com/2/notes endpoint を使用して、X の Posts に Community Notes を投稿できます。前述の endpoint と同様に、この endpoint も test_mode query パラメータをサポートします。test_mode を true に設定すると、送信するノートはテスト用となり、公開されません。 Note: 現時点では、test_mode は true にのみ設定可能です。それ以外の値を指定すると、これらの endpoint は次のようなエラーを返します: 
{
 "errors": [
   {
     "message": "「test_mode」query パラメータが無効です。"
   }
 ],
 "title": "無効なリクエスト"
 "detail": "リクエストのパラメータのうち、1 つ以上が無効です。"
 "type": "https://api.twitter.com/2/problems/invalid-request"
}
これを行うには、この endpoint のリクエストボディで、Community Note を送信したい対象の post_id を、以下のノート作成に必要な情報とともに指定する必要があります。必要な情報は次のとおりです:
  • text: ノートの本文。少なくとも1文字、最大280文字である必要があります（URLは1文字としてカウント）。また、出典のURLを必ず含めてください
  • classification: misinformed_or_potentially_misleading または not_misleading のいずれか
  • misleading_tags: 空でないタグのリストで、“disputed_claim_as_fact”、“factual_error”、“manipulated_media”、“misinterpreted_satire”、“missing_important_context”、“outdated_information”、または “other” のいずれかです。classification が misinformed_or_potentially_misleading の type の場合にのみ必要なフィールドです。
  • trustworthy_sources: “text” 内で信頼できる情報源が提供されているかどうかを示す boolean 値。
以下はこの endpoint へのリクエスト例です 
from requests_oauthlib import OAuth1Session
import json


# ノート情報を設定してください
payload = {"test_mode": True,
          "post_id": "1939667242318541239"
   ,
          "info": {
              "text": "test note text. http://source.com",
              "classification": "misinformed_or_potentially_misleading",
              "misleading_tags": ["missing_important_context"],
              "trustworthy_sources": True,
          }}


# リクエストを送信します
oauth = OAuth1Session(
   client_key='REPLACE_ME',
   client_secret='REPLACE_ME',
   resource_owner_key='REPLACE_ME',
   resource_owner_secret='REPLACE_ME',
)


# リクエストの送信
response = oauth.post(
   "https://api.twitter.com/2/notes",
   json=payload,
)


if response.status_code != 201:
   raise Exception(
       "リクエストでエラーが返されました: {} {}".format(response.status_code, response.text)
   )


print("レスポンスコード: {}".format(response.status_code))


# レスポンスをJSONとして保存
json_response = response.json()
print(json.dumps(json_response, indent=4, sort_keys=True))
リクエストが成功した場合、レスポンスは次のようになります。 
{
 "data": {
   "note_id": "1938678124100886981"
 }
}

​
エラーのトラブルシューティング

以下は、Community Notes の endpoint を利用する際によく見られるエラーメッセージと、その解決方法の一覧です。

​
401 Unauthorized（未認証）

{
 "title": "認証されていません",
 "type": "about:blank",
 "status": 401,
 "detail": "認証されていません"
}
説明: このエラーは、リクエストが適切に認証されていない場合に返されます

​
403 Forbidden（禁止）

{
 "detail": "ユーザー：[userId] がこの endpoint にアクセスするには、API Note Writer である必要があります。",
 "type": "about:blank",
 "title": "Forbidden（禁止）"
 "status": 403
}
説明: このエラーは、ユーザーがこの endpoint の利用対象に登録されていない場合に返されます

​
400 不正なリクエスト (test_mode)

{
 "errors": [
   {
     "message": "`test_mode` query パラメータが無効です。"
   }
 ],
 "title": "無効なリクエスト"
 "detail": "リクエストのパラメータに無効な値が含まれています。"
 "type": "https://api.twitter.com/2/problems/invalid-request"
}
説明: ユーザーが test_mode を false に設定してリクエストを実行しようとした場合に返される endpoint です

​
400 無効なリクエスト（Note の重複）

{
 "errors": [
   {
     "message": "ユーザーはこのPostに対して既にノートを作成しています（[noteId]）。"
   }
 ],
 "title": "無効なリクエスト"
 "detail": "リクエストのパラメータに無効なものがあります。"
 "type": "https://api.twitter.com/2/problems/invalid-request"
}
説明: このエラーは、ユーザーが重複するCommunity Notesを作成しようとした場合に返されます

​
リソース

他のプログラミング言語のコードサンプルは、当社のGitHub ページでご覧いただけます。これらの API endpoint は、Postman コレクションを利用してすぐに使い始めることも可能です。これらの endpoint に関する技術的なご質問は、X Developer Community サポートフォーラムまでお気軽にお問い合わせください。
⌘I