> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sorsa.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 過去のデータ

Sorsa APIでは、2006年3月までさかのぼるX（旧Twitter）の公開データの全アーカイブにアクセスできます。過去のデータも最新のデータと同じエンドポイント、認証、ページネーションで取得します。専用の「全アーカイブ」プランやエンタープライズ契約は不要で、検索期間の制限もありません。通常の呼び出しと同じ割り当て量を消費するため、新規アカウントに付与されるカード不要の無料リクエスト100件でも試せます。

このページでは、過去のデータに使う2つのエンドポイント、取得できる情報とできない情報、大規模収集で使えるパターンを説明します。

> **注：** 手法の比較表、CSV出力パイプライン、追加のコード例は、ブログの[過去のTwitterデータ：APIで古いツイートを検索する方法](https://api.sorsa.io/blog/historical-twitter-data)を参照してください。

***

## エンドポイント

| エンドポイント                  | 用途                              | ページネーション      | ページサイズ  |
| :----------------------- | :------------------------------ | :------------ | :------ |
| `POST /v3/search-tweets` | 日付・エンゲージメント条件付きのキーワードによるアーカイブ検索 | `next_cursor` | 約20ツイート |
| `POST /v3/user-tweets`   | 特定アカウントの全投稿履歴                   | `next_cursor` | 約20ツイート |

`/search-tweets`は、`since:`、`until:`、`from:`、`to:`、`min_faves:`、`min_retweets:`、`lang:`、`filter:`を含むすべての[X検索演算子](https://docs.sorsa.io/ja/search-operators)を、`query`内に指定できます。`/user-tweets`はアカウント識別子（`user_link`、`username`、`user_id`）のみを受け付け、検索条件による絞り込みなしでタイムライン全体を返します。

***

## キーワードでアーカイブを検索する

期間内に条件と一致する全ユーザーのツイートを取得するには、`/search-tweets`を使います。日付条件を含む検索文字列をJSON本文に渡します。

```python theme={null}
import requests, time

API_KEY = "YOUR_API_KEY"
URL = "https://api.sorsa.io/v3/search-tweets"

def search_archive(query, max_pages=50):
    all_tweets, next_cursor = [], None
    for _ in range(max_pages):
        body = {"query": query, "order": "latest"}
        if next_cursor:
            body["next_cursor"] = next_cursor

        resp = requests.post(
            URL,
            headers={"ApiKey": API_KEY, "Content-Type": "application/json"},
            json=body,
        )
        resp.raise_for_status()
        data = resp.json()

        all_tweets.extend(data.get("tweets", []))
        next_cursor = data.get("next_cursor")
        if not next_cursor:
            break
        time.sleep(0.1)
    return all_tweets


tweets = search_archive('"climate change" since:2015-06-01 until:2015-12-31 lang:en min_faves:10')
```

`order`には`"latest"`（時系列順）または`"popular"`（エンゲージメント順）を指定します。期間を指定したアーカイブ収集には`"latest"`を使ってください。内容の調査には、反応の大きい投稿から返す`"popular"`が便利です。

***

## アカウントのタイムライン全体

1アカウントの投稿履歴を、新しい順に3,200ツイートの上限なしで取得するには、`/user-tweets`を使います。

```python theme={null}
resp = requests.post(
    "https://api.sorsa.io/v3/user-tweets",
    headers={"ApiKey": API_KEY, "Content-Type": "application/json"},
    json={"user_link": "https://x.com/naval"},
)
```

`user_link`、`username`、`user_id`のいずれか1つだけを指定します。`next_cursor`がnullになるまで繰り返すと、新しい投稿から古い投稿へ順に取得できます。

特定アカウントの期間内のツイートを取得する場合は、代わりに`/search-tweets`と`from:`を使います（例：`from:naval since:2020-01-01 until:2021-01-01`）。`/user-tweets`は日付フィルターに対応していません。

***

## 取得できる情報

過去のツイートも最新のツイートと同じフィールドを返します。

* 全文（省略なし、URLの置換なし）
* 6種類のエンゲージメント指標：`likes_count`、`retweet_count`、`reply_count`、`quote_count`、`view_count`、`bookmark_count`
* 投稿者の完全なプロフィールを含む`user`オブジェクト
* メディアURL（写真、動画、GIF）とリンクのプレビューを含む`entities`配列
* 会話の情報：`conversation_id_str`、`in_reply_to_tweet_id`、`is_reply`、`is_quote_status`
* 言語タグ（`lang`）

全フィールドは[レスポンス形式](https://docs.sorsa.io/ja/response-format)を参照してください。

***

## プラットフォーム側の制限

次はSorsa固有ではなくX側の制限です。公開APIで回避することはできません。

* **削除されたツイート**はXの検索インデックスから除去されるため、取得できません。
* **非公開アカウント**は公開検索とタイムラインの結果から除外されます。
* **プロフィールは過去のスナップショットではありません。** 2014年のツイートでも、自己紹介、ユーザー名、フォロワー数は2014年時点ではなく現在の値です。
* **エンゲージメント指標も過去のスナップショットではありません。** 「いいね」、リツイート、表示回数は現在の合計です。過去の特定時点の指標が必要な場合は、[リアルタイム監視](https://docs.sorsa.io/ja/real-time-monitoring)で継続的に取得し、自分で保存してください。

***

## 推奨事項

### 長い期間を分割する

複数年を1つの条件で検索すると、再試行しにくく、期間ごとの確認も困難です。年単位の収集は月ごとに、変動の激しい出来事の調査は週ごとに分けてください。

```python theme={null}
def monthly_chunks(year):
    out = []
    for month in range(1, 13):
        since = f"{year}-{month:02d}-01"
        nm = month + 1 if month < 12 else 1
        ny = year if month < 12 else year + 1
        until = f"{ny}-{nm:02d}-01"
        out.append((since, until))
    return out

for since, until in monthly_chunks(2020):
    tweets = search_archive(f'bitcoin since:{since} until:{until} lang:en min_faves:50')
```

### リツイートのノイズを除く

過去の人気投稿の検索では、大量のネイティブリツイートがオリジナルの投稿を埋もれさせます。感情、意見、投稿パターンの調査には`-filter:nativeretweets`を追加してください。旧式の`RT @user:`も除くには`-filter:retweets`を使います。

### エンゲージメントと日付の条件を組み合わせる

`since:`・`until:`と`min_faves:`または`min_retweets:`を組み合わせると、ノイズとリクエスト数を大幅に減らせます。例：

```text theme={null}
"product launch" since:2022-03-01 until:2022-03-31 min_faves:100 -filter:retweets lang:en
```

### 世界的な話題は言語ごとに分ける

世界的な出来事では、言語を混ぜず、`lang:`ごとに検索すると各言語・地域のデータを整理しやすくなります。

### カーソルがなくなるまで続ける

`next_cursor`がnull、空、または存在しない場合にだけ終了してください。ページの件数が少ないという理由で止めないでください。完全なパターンは[ページネーション](https://docs.sorsa.io/ja/pagination)にあります。

***

## 関連ガイド

* [ツイート検索](https://docs.sorsa.io/ja/search-tweets)：`/search-tweets`の仕様
* [検索演算子](https://docs.sorsa.io/ja/search-operators)：全演算子のリファレンス
* [ページネーション](https://docs.sorsa.io/ja/pagination)：カーソル方式の詳細
* [リアルタイム監視](https://docs.sorsa.io/ja/real-time-monitoring)：過去のデータの補完と組み合わせ、今後の投稿も継続取得する
* [メンションの追跡](https://docs.sorsa.io/ja/search-mentions)：任意のアカウントの過去のメンションを取得する
* [API利用の最適化](https://docs.sorsa.io/ja/optimizing-api-usage)：大規模収集でリクエスト数を減らす