フォーマット

フォーマットインサイトは、電話番号が正しく構成され、加入者に割り当て可能かどうかを検証する基本的な検証ツールです。番号が国際ダイヤル標準に準拠していることを確認し、関連する国を識別し、対応するタイムゾーンを決定します。このインサイトは、番号が現在有効であるか、または使用中であるかを確認するものではありませんが、あらゆるグローバル電話番号の技術的妥当性を評価するための重要な第一歩です。

Format Insightは、番号の構文と接頭辞構造を分析することで、その番号が特定の国で有効な番号範囲に属するかどうかを識別します。また、明らかに無効な番号や不正な番号にフラグを立て、運用やマーケティングに使用する前にデータをクリーンアップすることができます。

Formatのインサイトをアプリケーションに統合することで、以下のようなさまざまなシナリオに役立ちます：

データの品質とクレンジング： Format Insightは、過去の顧客データベースのクリーニングに最適です。不適切なフォーマットや明らかに無効な Numbers をフィルタリングし、高いデータ衛生基準を維持し、全体的な接触性を向上させます。
入力時のリアルタイム検証： 企業は、このインサイトをウェブフォームやCRMシステムに統合することで、入力された電話番号を検証し、入力ミスのリスクを減らし、適切な形式の番号のみを保存することができる。
セグメンテーションとローカライゼーション： 番号に関連する国とタイムゾーンを知ることで、企業はコミュニケーションを調整し、適切な時間帯にアウトリーチのスケジュールを組み、現地の規制に準拠することができる。
コストの最適化： SMS、音声、詐欺防止ワークフローにおいて、配信の失敗、無駄な運用努力、不必要なコストにつながる無効な番号との関わりを避けることができます。

要約すると、Format Insightは、グローバルな電話番号を大規模に検証するための低レイテンシー、高信頼性の方法を提供します。これは、電話番号インテリジェンスパイプラインの重要な構成要素であり、キャリアインサイトや不正リスク分析のためのネットワーク機能など、より高度なチェックのための土台を築くものです。

前提条件

Identity Insights を使用するには、アカウントが正しく設定されていることを確認する必要があります。はじめにのガイドを参照されたい：

アカウントの作成
Identity Insights API で使用する Vonage アプリケーションの作成、
利用可能なさまざまな環境と、それらを使用するためのアカウントの設定方法、
また、Dashboard Getting Started UIを使用して、コードを書かずにAPIを使用する方法も紹介します。

このガイドでは、cURLを使用してプログラムでFormat Insightを使用する方法を説明します。

Identity Insights API は、複数の地域のエンドポイントから利用できる。本ガイドの例では EU エンドポイントを使用していますが、全リストは以下を参照してください。技術詳細.

APIを呼び出す

Identity Insights API の認証は、コンパクトで自己完結型の JSON トークンである JWT を介して行われます。JWT を生成するには、当社のオンラインジェネレーターあるいは Vonage CLI.JWTを生成するには、アプリケーションIDと秘密鍵が必要です。JWTを取得したら、APIにリクエストを送信できます。

この例では、提供された電話番号に基づいて有用な情報を返すために、Format insightに対するcURLリクエストを示しています：

curl -X POST https://api-eu.vonage.com/identity-insights/v1/requests  \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "14040000000",
    "purpose": "FraudPreventionAndDetection",
    "insights": {
      "format": {}
        }
    }'

APIは次に、電話番号のフォーマットが各国でサポートされているプレフィックス、長さ、パターンと一致していることを検証し、国コード、タイムゾーン、番号に割り当てられたオフラインロケーション、番号のローカルおよびインターナショナルフォーマットなどの追加情報を返す：

{
  "request_id": "c2cc7a65-9b10-493f-9c0a-1c86751a91c4",
  "insights": {
    "format": {
        "country_code": "US",
        "country_name": "United States",
        "country_prefix": "1",
        "offline_location": "Georgia",
        "time_zones": [
          "America/New_York"
        ],
        "number_international": "+14040000000",
        "number_national": "(404) 000-0000",
        "is_format_valid": true,
        "status": {
          "code": "OK",
          "message": "Success"
        }
    }
  }
}

以下のフィールドが format 配列である：

フィールド	説明
`country_code`	の2文字の国コード `phone_number`.これは ISO 3166-1 alpha-2 という形式をとっている。
`country_name`	のある国の正式名称。 `phone_number` が登録されている。
`country_prefix`	が存在する国を表す数字の接頭辞。 `phone_number` が登録されている。
`offline_location`	プレフィックスに基づき、番号が最初に割り当てられた場所。これはデバイスのリアルタイムの位置を表すものではない。この値は、発信国、または利用可能な場合は、番号に関連する特定の地域を示します。オフライン位置情報の対象となるのは、固定電話番号と携帯電話番号のみです。
`time_zones`	に対応するタイムゾーンのリスト。 `format.offline_location` フィールドを指定するか、他のタイムゾーンが見つからなかったり数値が無効な場合は、デフォルトの "unknown "タイムゾーンを持つ単一要素のリストを指定する。タイムゾーン値は tzデータベース識別子である。
`number_international`	について `phone_number` 国際フォーマット E.164 という形式をとっている。
`number_national`	について `phone_number` あなたのリクエストから、その国の慣習に従ってフォーマットされたもの。
`is_format_valid`	電話番号フォーマットの検証では、長さとプレフィックスの詳細をさまざまなレベルで検証し、正確性とグローバルな番号標準への準拠を確認します。有効なフォーマットは、その番号が通信事業者からユーザーに合法的に割り当てられることを意味する。ただし、その番号が現在通信事業者に割り当てられていることや、到達可能であることを保証するものではありません。
`status`	指定された電話番号について返された情報のステータスを示す。
`code`	リクエストのステータスを示すコード。のいずれかでなければならない： `NO_COVERAGE`:国またはモバイルネットワークは、利用可能なサプライヤーによってサポートされていません。 `INVALID_PURPOSE`:使用された目的は、このインサイトで有効または許可されていません。 `UNAUTHORIZED`:アプリケーション、サプライヤー、電話番号の組み合わせでは、リクエストを承認できませんでした。 `INTERNAL_ERROR`:リクエストの処理中に内部エラーが発生しました。 `SUPPLIER_ERROR`:サプライヤーがリクエスト処理中にエラーを返しました。 `NOT_FOUND`:このインサイトの電話番号が見つかりません。 `INVALID_NUMBER_FORMAT`:電話番号フォーマットは、キャリアからユーザーへの割り当てには無効です。 `OK`:インサイトは正常に処理されました。
`message`	より詳細なステータスの説明。

さらに読む

Identity Insights API の詳細については、以下を参照してください。 APIリファレンス.
ご不明な点がございましたら、下記までお問い合わせください。 VonageコミュニティSlack.