# LocalSERP Proxy APIドキュメント

> localserpproxy.com/api の LocalSERP Proxy REST API：残高、チャージ、注文、プロキシのAPIキー、エラー、制限、エンドポイント。

- URL: https://localserpproxy.com/ja/docs/api/
- 最終更新日: 2026-10-15
- Publisher: LocalSERP Proxy (https://localserpproxy.com)

アカウントで行う操作はすべてスクリプト化できます。残高の確認、暗号資産でのチャージ、プランの購入、プロキシ認証情報の作成、モバイルIPのローテーションに対応。HTTPS経由のJSON、APIキー1つ、curl、Python、Node.jsの使用例を用意しています。

## LocalSERP Proxy APIの使い方を教えてください。

**簡単な回答**

APIキーをヘッダー`Authorization: Bearer API_KEY`に設定し、`https://localserpproxy.com/api/v1`へHTTPSリクエストを送信します。アカウントの[開発者ページ](https://localserpproxy.com/app/developer?lang=ja)]または`POST /v1/api-keys`からキーを作成し、必要なスコープだけを付与してください。リクエストとレスポンスはJSON形式です。エラーは常に`{ "error": { "code", "message" } }`として返されます。

## 概要

| 属性 | 値 |
| --- | --- |
| ベースURL | `https://localserpproxy.com/api/v1` |
| 形式 | HTTPS経由のJSON、UTF-8 |
| 認証 | APIキー：`Authorization: Bearer API_KEY` |
| APIキーのスコープ | `read`、`proxies`、`billing` |
| 通貨 | 小数点以下2桁の文字列でUSDを指定（`"29.00"`） |
| 暗号資産の金額 | 浮動小数点数ではなく、小数を表す文字列を使用（`"0.00045210"`） |
| 通信量 | バイト（1 GB = 1,000,000,000バイト） |
| 日付 | UTCのISO 8601形式（`2026-10-05T14:03:11Z`） |
| バージョン | すべてのパスに`/v1` |

## 認証

公開カタログを除くすべてのリクエストにAPIキーが必要です：`Authorization: Bearer API_KEY`。キーが全文表示されるのは作成時の**1回のみ**です。パスワードと同様に保管してください。キーはいつでも無効化できます。無効化後、そのキーを使ったリクエストは`401 unauthorized`を返します。

### スコープ

スクリプトに必要な権限だけを各キーに付与してください。必要なスコープがないキーでは`403 forbidden`が返されます。

| スコープ | 許可される操作 |
| --- | --- |
| `read` | すべての情報（アカウント、残高、サービス、利用状況）の読み取り。 |
| `proxies` | プロキシ設定と認証情報（ラベル、自動更新、新しいパスワード）の変更、サブユーザーの管理、IP許可リストの管理、モバイルポートのローテーション（ローテーションリンクを含む）。 |
| `billing` | 注文とチャージの作成、残高からの支払い。 |

唯一の例外は**モバイルローテーションリンク**です。ブラウザーのブックマークまたはプレーンな`curl`から呼び出すためのリンクです: `GET https://localserpproxy.com/api/v1/mobile/PORT_ID/rotate?key=API_KEY`（`proxies`スコープのキー）。[モバイルポートとIPローテーション](https://localserpproxy.com/ja/docs/api/mobile/)を参照してください。

*残高を確認*

```bash
curl -s "https://localserpproxy.com/api/v1/balance" \
  -H "Authorization: Bearer $API_KEY"
```

## リクエストとレスポンス

- **JSONを送信し、JSONを受信**: 本文付きで`Content-Type: application/json`を送信します。
- **件数が増えるリスト**は`page`（1から）と`perPage`（1～100、デフォルトは20）でページ分割され、`{ "data": [...], "pagination": { "page", "perPage", "total", "totalPages" } }`を返します。短いリストは`{ "data": [...] }`を返します。
- **ID**はタイププレフィックス付きの不透明な文字列です: `ord_`（注文）、`top_`（チャージ）、`txn_`（残高の移動）、`res_`（トラフィックサブスクリプション）、`mob_`（モバイルポート）、`key_`（APIキー）、`ipw_`（IP許可リストのエントリー）。
- **安全な再試行**: `POST /v1/orders`と`POST /v1/topups`は`Idempotency-Key`ヘッダーを受け付けます（任意の一意な文字列。24時間保持）。同じキーで再送すると、二重購入や二重チャージを防ぎ、最初のレスポンスを返します。
- **例**は各レスポンスの形式を示しています。例に含まれるID、IP、金額、日付は説明用です。プランIDと価格は実際のものです。

## エラー

すべてのエラーで同じ本文が返されます。`code`は安定しており、コードでの処理を想定しています。`message`は変更される場合がある英語の文です。バリデーションエラーでは、無効なフィールドが`fields`に列挙されます。新しいコードが追加される場合があります。不明なコードは一般的なエラーとして処理してください。

*422 validation_failed*

```json
{
  "error": {
    "code": "validation_failed",
    "message": "Some fields are invalid.",
    "fields": [
      {
        "field": "amountUsd",
        "code": "too_small",
        "message": "The minimum top-up is 25.00 USD."
      }
    ],
    "requestId": "req_2b7c0f"
  }
}
```

### ステータスコード

| ステータス | 意味 |
| --- | --- |
| `422` | `validation_failed`: 1つ以上の項目が無効です。 |
| `401` | `unauthorized`: トークンがないか、無効または期限切れです。 |
| `402` | `insufficient_balance`: 残高が注文金額に足りません。`details` = `InsufficientBalanceDetails`。 |
| `403` | `forbidden`: APIキーに必要なスコープがないか、アカウントが停止されています。 |
| `404` | `not_found`: リソースが存在しないか、別のアカウントに属しています。 |
| `409` | `conflict`（または、より具体的なコード）: 現在の状態では操作できません。 |
| `429` | `rate_limited`または`rotation_too_soon`。 |

## レート制限

すべてのレスポンスには`RateLimit-Limit`、`RateLimit-Remaining`、`RateLimit-Reset`が含まれます。上限を超えると、APIは`Retry-After`ヘッダー（秒数）とともに`429 rate_limited`を返します。指定された秒数だけ待ってから再試行してください。モバイルポートのIPは、30秒に1回まで変更できます（`429 rotation_too_soon`、`Retry-After`を使用）。

## APIリファレンス

- **[アカウントと残高](https://localserpproxy.com/ja/docs/api/account/)** — アカウント設定、プリペイドのUSD残高、残高のすべての取引（チャージ、購入、返金）を確認できます。
- **[暗号資産でのチャージ](https://localserpproxy.com/ja/docs/api/top-ups/)** — 暗号資産で残高をチャージできます。入金アドレスと正確な金額を取得し、その金額を過不足なく送金して、支払い済みとして報告します（取引IDは任意）。その後、残高に反映されるまでチャージ状況を確認できます。残高はすべてのプランのお支払いに利用できます。
- **[注文](https://localserpproxy.com/ja/docs/api/orders/)** — プランと料金の一覧を確認し、残高でプランを購入（新規サービス、トラフィックの追加、ポートの延長）して、過去の注文を確認できます。
- **[レジデンシャルプロキシと認証情報](https://localserpproxy.com/ja/docs/api/residential/)** — トラフィックのサブスクリプション（レジデンシャルおよびGB単位のローテーション式4G/5G）を管理できます。プロキシの認証情報、専用の認証情報とトラフィック上限を設定したサブユーザー、日ごとの使用量、プロキシのユーザー名で指定できるターゲット地域を管理できます。
- **[モバイルポートとIPローテーション](https://localserpproxy.com/ja/docs/api/mobile/)** — 専用4G/5Gポート：今すぐ、またはタイマーでIPを変更し、ローテーションリンクを使用して、日次トラフィックを確認できます。
- **[APIキーとIP許可リスト](https://localserpproxy.com/ja/docs/api/api-keys/)** — 権限を制限したAPIキーを作成・失効できます。また、ユーザー名とパスワードなしでプロキシを利用できる送信元IPを最大10個まで、IP許可リストで管理できます。

> **スクリプトからの支払い** プランの支払いには、常にチャージ済みのUSD残高を使用します。暗号資産でチャージ（最低25.00 USD）し、POST /v1/topupsから購入してください。POST /v1/orders。両方を1回の呼び出しで実行できます。チャージ時にpurchaseで注文を指定すると、チャージが反映された時点でプランが購入されます。

---

LocalSERP Proxy: LocalSERP Proxyは、都市ごとにローカル検索結果、広告、価格を確認するための米国のレジデンシャルプロキシサービスで、暗号資産で支払い、身分証明書のアップロードは不要です。