> ## 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.

# クイックスタート

> APIキーを取得し、数分でX（Twitter）APIへの最初のリクエストを送信できます。

このガイドでは、アカウントの作成から認証、最初のGETリクエストとPOSTリクエストの実行まで、最初のレスポンスを取得するための手順を説明します。各手順には、cURL、Python、JavaScriptで動作する例を掲載しています。

## ステップ1：APIキーを取得する

1. [Sorsaダッシュボード](https://api.sorsa.io/overview)を開き、**Sign in**をクリックします。利用可能な方法で登録してください。Sorsaは認証プロバイダーから共有される情報以外を要求しません。
2. 新しいアカウントには**100回分の無料リクエスト**が付与されます。クレジットカードは不要で、利用可能なすべてのエンドポイントに対応し、有効期限もないため、すぐにテストを始められます。
3. より多くのリクエストが必要になったら、プラン（月間1万回、10万回、50万回）と請求サイクル（月払いまたは年払い）を選び、カードまたは暗号資産で支払います。

ログインすると、ダッシュボードに**APIキー**と**残りのリクエスト数**が表示されます。

> **APIキーは秘密にしてください。** フロントエンドのコード、公開リポジトリ、クライアント側のJavaScriptに公開しないでください。パスワードと同じように扱ってください。

## ステップ2：基本を理解する

最初のAPI呼び出しの前に、次の点を確認してください。

**ベースURL**

```text theme={null}
https://api.sorsa.io/v3
```

**認証**

すべてのリクエストで、APIキーを `ApiKey` ヘッダーに指定する必要があります。

```text theme={null}
ApiKey: YOUR_API_KEY
```

**レスポンス形式**

すべてのエンドポイントはJSONを返します。リクエストが成功すると、HTTPステータス `200` が返されます。

**レート制限**

すべてのプランに、1秒あたり20リクエストという共通の制限があります。送信間隔の調整と再試行の方法は、[レート制限](https://docs.sorsa.io/ja/rate-limits)を参照してください。

## ステップ3：最初のGETリクエストを送信する

**例を実行する前に：** `python -m pip install requests` でPythonの `requests` パッケージをインストールしてください。JavaScriptは、Node.js 18以降の `fetch` を使用してバックエンドで実行します。トップレベルの `await` を使うため、例は `.mjs` ファイルとして保存してください。`YOUR_API_KEY` を自分のAPIキーに置き換えます。以下のプロフィールやツイートのレスポンスは説明用の例です。

設定を確認する最も簡単な方法は、`/info` エンドポイントで公開プロフィールを取得することです。

**cURL**

```bash theme={null}
curl --request GET \
  --url 'https://api.sorsa.io/v3/info?username=elonmusk' \
  --header 'ApiKey: YOUR_API_KEY'
```

**Python**

```python theme={null}
import requests

response = requests.get(
    "https://api.sorsa.io/v3/info",
    params={"username": "elonmusk"},
    headers={"ApiKey": "YOUR_API_KEY"},
    timeout=30,
)

response.raise_for_status()
data = response.json()
print(data["display_name"])      # Elon Musk
print(data["followers_count"])   # 236021252
```

**JavaScript**

```javascript theme={null}
const response = await fetch(
  "https://api.sorsa.io/v3/info?username=elonmusk",
  { headers: { ApiKey: "YOUR_API_KEY" } }
);

if (!response.ok) throw new Error(`HTTP ${response.status}`);
const data = await response.json();
console.log(data.display_name);      // Elon Musk
console.log(data.followers_count);   // 236021252
```

**レスポンス例**

```json theme={null}
{
  "id": "44196397",
  "username": "elonmusk",
  "display_name": "Elon Musk",
  "description": "",
  "location": "",
  "profile_image_url": "https://pbs.twimg.com/profile_images/1234567890/avatar.jpg",
  "profile_background_image_url": "https://pbs.twimg.com/profile_banners/44196397/1700000000",
  "followers_count": 236021252,
  "followings_count": 1292,
  "tweets_count": 98479,
  "favourites_count": 214650,
  "media_count": 4374,
  "verified": true,
  "protected": false,
  "can_dm": false,
  "possibly_sensitive": false,
  "created_at": "2009-06-02T20:12:29Z",
  "bio_urls": [],
  "pinned_tweet_ids": ["2028500984977330453"]
}
```

ユーザーデータを含むJSONが返されたら、APIキーは正常に動作しており、利用を開始できます。

## ステップ4：最初のPOSTリクエストを送信する

ツイートや検索に関する多くのエンドポイントは、JSONボディを伴う `POST` を使用します。以下は `/search-tweets` によるツイート検索の例です。

**cURL**

```bash theme={null}
curl --request POST \
  --url 'https://api.sorsa.io/v3/search-tweets' \
  --header 'ApiKey: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{ "query": "bitcoin" }'
```

**Python**

```python theme={null}
import requests

response = requests.post(
    "https://api.sorsa.io/v3/search-tweets",
    headers={"ApiKey": "YOUR_API_KEY"},
    json={"query": "bitcoin"},
    timeout=30,
)

response.raise_for_status()
data = response.json()
for tweet in data.get("tweets", []):
    print(tweet["full_text"])
```

**JavaScript**

```javascript theme={null}
const response = await fetch("https://api.sorsa.io/v3/search-tweets", {
  method: "POST",
  headers: {
    ApiKey: "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ query: "bitcoin" }),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
const data = await response.json();
data.tweets?.forEach((tweet) => console.log(tweet.full_text));
```

**レスポンス例（一部省略）**

```json theme={null}
{
  "tweets": [
    {
      "id": "1782368585664626774",
      "full_text": "Bitcoin just crossed another milestone.",
      "created_at": "2024-01-15T10:30:00Z",
      "lang": "en",
      "likes_count": 200,
      "retweet_count": 50,
      "reply_count": 10,
      "view_count": 10000,
      "user": {
        "id": "44196397",
        "username": "elonmusk",
        "display_name": "Elon Musk",
        "followers_count": 236021252,
        "verified": true
      }
    }
  ],
  "next_cursor": "DAABCgABF7d..."
}
```

続きの結果を取得するには、返された `next_cursor` を次のリクエストに渡します。詳しい処理手順は、[ページネーション](https://docs.sorsa.io/ja/pagination)を参照してください。

## ステップ5：APIの使用状況を確認する

`/key-usage-info` で、残りのリクエスト数をいつでも確認できます。

```bash theme={null}
curl --request GET \
  --url 'https://api.sorsa.io/v3/key-usage-info' \
  --header 'ApiKey: YOUR_API_KEY'
```

**レスポンス例**

```json theme={null}
{
  "key_requests": 100000,
  "remaining_requests": 94231,
  "total_requests": 5769,
  "valid_until": "2026-08-01T00:00:00Z"
}
```

大規模なバッチ処理を実行する前に、このエンドポイントを呼び出すことをお勧めします。[ダッシュボード](https://api.sorsa.io/overview/usage)で利用履歴全体を確認することもできます。

## よくあるエラーコード

| コード | 意味       | 対処方法                                 |
| :-- | :------- | :----------------------------------- |
| 200 | 成功       | リクエストは正常に処理されました                     |
| 400 | 不正なリクエスト | クエリパラメータとリクエストボディを確認してください           |
| 401 | 認証エラー    | APIキーがないか無効です。`ApiKey` ヘッダーを確認してください |
| 403 | アクセス禁止   | このリソースへのアクセスは拒否されています                |
| 404 | 見つかりません  | エンドポイントのURLまたはリソースIDを確認してください        |
| 429 | リクエスト過多  | レート制限に達しています。時間をおいて再試行してください         |
| 500 | サーバーエラー  | 少し待ってから再試行し、解消しない場合はサポートに連絡してください    |

詳しい内容と対処方法は、[エラーコードリファレンス](https://docs.sorsa.io/ja/error-codes)を参照してください。

## コードを書かずに試す

まず画面上で操作してみたい場合は、[APIリファレンス](https://docs.sorsa.io/ja/api-reference-guide)で各エンドポイントを確認するか、ノーコードの[API Playground](https://api.sorsa.io/playground)を利用してください。どちらもコードを書く前に実際のリクエストを送信し、レスポンスを確認できます。

## 次のステップ

* [認証](https://docs.sorsa.io/ja/authentication) — セキュリティ上の推奨事項とヘッダーの設定
* [ページネーション](https://docs.sorsa.io/ja/pagination) — カーソルとページ分割されたレスポンスの処理
* [レート制限](https://docs.sorsa.io/ja/rate-limits) — リクエスト間隔の調整と再試行の方法
* [APIリファレンス](https://docs.sorsa.io/ja/api-reference-guide) — 利用可能なすべてのエンドポイントとスキーマ
* [活用例ガイド](https://docs.sorsa.io/ja/use-cases-overview) — 実際の実装パターン