メインコンテンツまでスキップ

電話番号情報照会 API

本インターフェースを通じて、世界中の携帯電話番号のステータス検索を行い、番号の有効性、所属通信事業者、ローミング、携帯番号ポーティング（MNP）などの詳細情報を取得できます。この API は、Basic と Premium の2つのサービスレベルを提供します。

  • Basic：基礎データ（国番号、元の所属通信事業者、番号形式の検証など）を提供します。Basic は番号が携帯番号ポーティング（MNP）される前の元の通信事業者情報のみを返すことに注意してください。MNP 後の現在の通信事業者情報を取得する必要がある場合は、Premium にアップグレードしてください。

  • Premium：Basic に加えて、現在のネットワーク状況における番号の通信事業者、到達可能かどうか、ローミングの有無、MNP の有無などの情報をさらに取得できます。ただし、この部分のデータは対象国/地域の電気通信規制およびユーザーのプライバシー保護ポリシーに依存するため、すべての国やすべての通信事業者で完全に提供できるとは限りません。

1. 呼び出し方法​

呼び出し方法
  • HTTP Method：GET
  • リクエスト先：https://api.paasoo.com/lookup

2. リクエスト例​

Basic:​

cURL
curl -X GET "https://api.paasoo.com/lookup?key=API_KEY&secret=API_SECRET&number=819012345678"

Premium:​

cURL
curl -X GET "https://api.paasoo.com/lookup?key=API_KEY&secret=API_SECRET&number=819012345678&service=premium"
説明

認証パラメータ：key と secret を通じて認証を行います。
デフォルトのサービスレベル：service を指定しない場合、デフォルトは basic になります。

3. リクエストパラメータの説明​

パラメータタイプ必須説明例
keystringはいAPI Key（英数字8桁）。アカウントの一意の識別子として使用します。PaaSoo のクライアントバックグラウンドで取得できます。Abcdefgh
secretstringはいAPI Secret（英数字8桁）。key と組み合わせて認証に使用します。PaaSoo のクライアントバックグラウンドで取得できます。Abc123EF
numberstringはい検索対象の携帯電話番号。完全な国際形式（例：819012345678）を使用することを推奨します。
市外局番や番号の前にプレフィックス（0など）を追加する必要はありません。		819012345678
servicestringいいえ検索サービスレベル（basic または premium）を指定します。送信されない場合、デフォルトは basic になります。premium

4. レスポンスの説明​

Basic: 番号の初期（MNP 前）の通信事業者情報のみを提供し、リアルタイムの MNP 情報は返せません。
Premium: ベストエフォート（best effort）で現在の通信事業者、ローミング、MNP などのより多くのステータスを提供しますが、現地の電気通信規制およびプライバシー保護の要件により、すべての地域で完全または最新のデータを検索できるわけではありません。

4.1 レスポンスパラメータの説明​

パラメータタイプサービス説明
requestIdstringbasic / premium検索リクエストの一意の ID。ログの追跡に使用できます。
numberstringbasic / premium渡された検索対象の電話番号。
formatintegerbasic / premium番号形式の有効性：
  • 0 - 無効な番号
  • 1 - 正しい形式
errorCodestringbasic / premiumリクエストのエラーコード：
  • 00 - Successful：呼び出し成功
  • 01 - Insufficient balance：残高不足
  • 02 - Wrong credentials：ユーザー名またはパスワードの誤り
  • 03 - Missing parameters：パラメータの欠落またはエラー
  • 07 - IP limit：IP ホワイトリスト制限
  • 08 - No allow hlr：HLR 検索権限が未開通
  • 13 - Daliy quota exceeded：Basic 版の1日あたりの検証上限を超過
  • 99 - Other error：システムエラー
errorDescstringbasic / premiumerrorCode に対応する説明情報。
ccstringbasic / premium検索対象番号に対応する国または地域コード（例：81）。
countryIsostringbasic / premium国または地域名の略称（例：JP）。
operatorstringbasic / premium番号が所属する通信事業者名。Basic バージョンでは、番号が元のネットワーク（MNP 前）にあった際の通信事業者情報のみを返します。現在の通信事業者情報を取得するには、Premium を使用してください。
mccmncstringpremiumネットワークコード (MCC+MNC)（例：44010）。検索できない場合は返されないことがあります。
reachablestringpremium番号の到達可能性：
  • reachable
  • unreachable
  • unknown
所在地の電気通信規制やユーザーのプライバシー制限により、正確に取得できない場合があります。
portedstringpremium携帯番号ポーティング（MNP）の有無：
  • ported
  • not ported
  • unknown
検索できない場合は、デフォルトで unknown を返します。
portedFromstringpremiumMNP 前のネットワーク名とネットワークコード情報（例：NTT Docomo 44010）。
取得できない場合や MNP されていない場合は空または unknown になります。
imsistringpremiumIMSI コード情報。取得できない場合は unknown を返します。

4.2 Basic (デフォルト) レスポンス例​

{
    "requestId": "900249-0c1a64-d000",
    "number": "819012345678",
    "format": 1,
    "errorCode": "00",
    "errorDesc": "Successful",
    "cc": "81",
    "countryIso": "JP"
}

4.3 Premium レスポンス例​

{
    "requestId": "900249-0c0aba-2000",
    "number": "819012345678",
    "format": 1,
    "errorCode": "00",
    "errorDesc": "Successful",
    "cc": "81",
    "countryIso": "JP",
    "mccmnc": "44010",
    "operator": "NTT Docomo",
    "reachable": "reachable",
    "ported": "not ported",
    "portedFrom": "",
    "imsi": "unknown"
}

5. エラーコードとよくある質問​

  • 00 - Successful：呼び出し成功。
  • 01 - Insufficient balance：現在の残高が不足しています。チャージまたはアカウントのアップグレードが必要です。
  • 02 - Wrong credentials：アカウントまたはパスワードの誤りです。key、secret を確認してください。
  • 03 - Missing parameters：パラメータの欠落または不正です。リクエスト例を確認してください。
  • 07 - IP limit：リクエスト元の IP がホワイトリストに含まれていません。
  • 08 - No allow hlr：現在のアカウントは Premium バージョンの HLR 検索サービスをサブスクライブしていません。
  • 13 - Daliy quota exceeded：Basic 版の当日の検索可能回数を使い切りました。
  • 99 - Other error：システムがビジー状態であるか、その他の不明なエラーです。

6. ベストプラクティスと注意事項​

  1. サービスの選択：
    • Basic：番号の元の通信事業者情報のみを取得できます。MNP 後の通信事業者などの動的な情報が必要な場合は、Premium を使用してください。
    • Premium：ベストエフォート (best effort) ベースで現在の通信事業者、ローミング、MNP などの情報を取得します。この機能は、一部の国や地域では現地の電気通信規制およびユーザーのプライバシー保護規定に制限される場合があり、一部の情報が取得できないことがあります。
  2. 番号の形式：先頭の + や 0 などのプレフィックスを削除し、完全な国際形式の番号を渡すことを推奨します。
  3. セキュリティ：API Key と Secret を保護するために、HTTPS プロトコルの使用と、IP ホワイトリストやその他の技術的手段を組み合わせることを強く推奨します。
  4. アカウント残高：呼び出し前に十分な残高があることを確認してください。より高いクォータやより高いレベルのサービスが必要な場合は、PaaSoo サポートにお問い合わせください。
  5. リクエストの頻度：頻繁に呼び出す場合は、サービス制限を超えないように、同時実行数を制御するか、妥当な遅延を設定してください。
  6. 転送の遅延：Premium 検索はリアルタイムの番号ステータスを提供できますが、ネットワークの遅延やターゲット通信事業者の連携のタイミングに注意する必要があります。
テクニカルサポート

API 連携の過程で技術的な問題やビジネスに関する疑問が生じた場合は、いつでも当社の開発者サポートチーム（support@paasoo.com）までご連絡ください。誠心誠意、技術的なサポートを提供いたします。