はじめに

グローバルモバイルネットワークインフラストラクチャは、SS7シグナリングネットワークとして知られるシステム上で動作しています。このネットワークは、通信事業者間で加入者データ、通話ルーティング、SMS送信、およびリアルタイムのモバイル接続ステータス更新の交換を可能にします。各モバイルネットワークは、加入者に関する重要な情報を保存するコアデータベースであるホームロケーションレジスタ(HLR)を保持しています。

HLRルックアップ技術により、企業はこれらのレジスタに問い合わせを行い、任意の携帯電話番号のリアルタイム接続状況とネットワーク詳細を取得できます。これには、電話機の電源がオンになっているか、現在割り当てられているネットワーク、番号ポータビリティの有無、番号が有効か無効か、ローミング中かどうかなどが含まれます。

HLR Lookups APIは、このデータへのシームレスなリアルタイムアクセスを提供し、企業が携帯電話番号の検証、ルーティングの最適化、顧客コミュニケーションの強化を実現できるようにします。このドキュメントでは、HLR Lookupsをソフトウェアに統合し、リアルタイムモバイルインテリジェンスの自動取得を可能にする方法をご案内します。

HLR Lookups APIの使用方法

HLRルックアップクエリの実行は、高速、安全、かつ簡単です。サインアップしてAPIキーを取得したら、認証を行い、POST /hlr-lookupを介して簡単なHTTP POSTリクエストで即座にルックアップを開始できます。また、コンセプトセクションで説明されているように、Webhook経由でサーバーに結果を返信する高速非同期APIリクエストを選択することで、大規模なデータセットを処理することもできます。

リクエスト例

curl -X POST 'https://www.hlr-lookups.com/api/v2/hlr-lookup' \
          -H "X-Digest-Key: YOUR_API_KEY" \
          -H "X-Digest-Signature: DIGEST_AUTH_SIGNATURE" \
          -H "X-Digest-Timestamp: UNIX_TIMESTAMP" \
          -d "@payload.json"

認証はHTTPヘッダー経由で提供され、payload.jsonには(最低限)以下のJSONオブジェクトを含める必要があります:

ペイロード例

{
   "msisdn": "+14156226819"
}

実行が成功すると、指定された携帯電話番号のリアルタイム接続詳細を含むレスポンスが返されます。

成功レスポンス application/json

{
   "id":"f94ef092cb53",
   "msisdn":"+14156226819",
   "connectivity_status":"CONNECTED",
   "mccmnc":"310260",
   "mcc":"310",
   "mnc":"260",
   "imsi":"***************",
   "msin":"**********",
   "msc":"************",
   "original_network_name":"Verizon Wireless",
   "original_country_name":"United States",
   "original_country_code":"US",
   "original_country_prefix":"+1",
   "is_ported":true,
   "ported_network_name":"T-Mobile US",
   "ported_country_name":"United States",
   "ported_country_code":"US",
   "ported_country_prefix":"+1",
   "is_roaming":false,
   "roaming_network_name":null,
   "roaming_country_name":null,
   "roaming_country_code":null,
   "roaming_country_prefix":null,
   "cost":"0.0100",
   "timestamp":"2020-08-07 19:16:17.676+0300",
   "storage":"SYNC-API-2020-08",
   "route":"IP1",
   "processing_status":"COMPLETED",
   "error_code":null,
   "error_description":null,
   "data_source":"LIVE_HLR",
   "routing_instruction":"STATIC:IP1"
}

リクエストとレスポンスの属性および接続ステータスの詳細については、POST /hlr-lookupをご覧ください。

追加のルックアップサービス

モバイル番号ポータビリティ(MNP)ルックアップ

MNPルックアップを使用して、リアルタイム接続を照会することなく、ネットワーク所有権とポータビリティの詳細を判定できます。番号のMCCMNCのみが必要な場合は、POST /mnp-lookupをご参照ください。

番号タイプ検出(NT)ルックアップ

POST /nt-lookupを使用して、電話番号が固定電話、携帯電話、プレミアムレート、VoIP、ポケベル、またはその他の番号計画範囲のいずれに属するかを判定できます。

ソフトウェア開発キット(SDK)

HLR Lookups APIは、任意のプログラミング言語のRESTクライアントで動作します。また、迅速に開始できるよう、PHP、Ruby、NodeJS向けのSDKをGitHubで公開しています。

ツール

シームレスな開発体験を保証するため、ブラウザ内APIリクエストおよびWebhookモニタリング、IPアドレスホワイトリスト、堅牢な認証オプション、認証テストエンドポイントを含む包括的なツールスイートを提供しています。

開発者ではありませんか?

HLRルックアップおよび番号ポータビリティクエリは、コーディング不要で実行できます。エンタープライズWebクライアントおよびブラウザベースのレポート機能の詳細をご覧ください。

認証

セキュリティと適切なアクセス制御を確保するため、HLR Lookups APIへのほとんどのリクエストには認証が必要です。エンドポイントは公開または保護のいずれかに分類されます。保護されたエンドポイントにアクセスする場合、Digest-AuthまたはBasic-Authメソッドを使用してAPIキーとシークレットで認証する必要があります。 Digest-Authはより安全なオプションであり、強く推奨されます。 GET /auth-testエンドポイントを使用して認証設定を確認してください。

APIキーとAPIシークレット

API設定ページからAPIキーとシークレットを取得してください。優先する認証方法を設定し、セキュリティ強化のためにIPアドレスホワイトリストを有効にすることもできます。 APIシークレットが漏洩した疑いがある場合は、いつでも新しいものを生成できます。

ベーシック認証ダイジェスト認証 IPホワイトリスト

標準的なベーシック認証は実装が容易で、広くサポートされています。HTTPリクエストでAPIキーとシークレットをuser:passペアとして渡すことで認証できます。

HTTPベーシック認証

curl 'https://YOUR_API_KEY:YOUR_API_SECRET@www.hlr-lookups.com/api/v2/auth-test'

これによりAuthorizationヘッダーが送信されます:

Authorization: Basic BASE64(YOUR_API_KEY:YOUR_API_SECRET)

推奨: SHA256を使用したX-Basicヘッダー

セキュリティを向上させるため、認証情報をbase64として直接送信する代わりに、SHA256ハッシュを送信できます。この方法を使用するには、YOUR_API_KEY:YOUR_API_SECRETペアのハッシュを計算し、X-Basicヘッダー経由で送信します:

ベーシック認証リクエスト

curl 'https://www.hlr-lookups.com/api/v2/auth-test' \
  -H "X-Basic: BASIC_AUTH_HASH"

ベーシック認証ヘッダー

キー	タイプ	説明
`X-Basic`	string	`YOUR_API_KEY:YOUR_API_SECRET`のSHA256ハッシュ。ハッシュにコロン記号(:)を含めてください。	必須

コード例

$key = 'YOUR_API_KEY';
$secret = 'YOUR_API_SECRET';

$basicAuthHash = hash('sha256', $key . ':' . $secret);

Digest-Authは、保護されたHLR Lookup APIエンドポイントへのアクセスを保護するための推奨方法です。各リクエストには、X-Digest-Key、X-Digest-Signature、X-Digest-Timestampのヘッダーを含める必要があります。これらについては以下で説明します。

リクエスト例

curl 'https://www.hlr-lookups.com/api/v2/auth-test' \
  -H "X-Digest-Key: YOUR_API_KEY" \
  -H "X-Digest-Signature: DIGEST_AUTH_SIGNATURE" \
  -H "X-Digest-Timestamp: UNIX_TIMESTAMP"

リクエストヘッダー

キー	タイプ	説明
`X-Digest-Key`	string	お客様固有のHLR Lookups APIキー。	必須
`X-Digest-Signature`	string	一意の認証署名(下記参照)。	必須
`X-Digest-Timestamp`	integer	現在のUnixタイムスタンプ(`GET /time`も参照)。	必須

署名の構築

X-Digest-Signatureは、APIシークレットを共有キーとして使用したSHA256 HMACハッシュを使用して作成されます。

ハッシュ化する文字列は次のように構成されます:

ENDPOINT_PATH . UNIX_TIMESTAMP . REQUEST_METHOD . REQUEST_BODY

.記号は文字列の連結を表します。

ダイジェスト署名コンポーネント

コンポーネント	タイプ	説明
`ENDPOINT_PATH`	string	リクエストされたAPIエンドポイント、例: 小文字の`/auth-test`。
`UNIX_TIMESTAMP`	integer	現在のUnixタイムスタンプ(30秒以内である必要があります)。`GET /time`を参照。
`REQUEST_METHOD`	string	使用されるHTTPメソッド、例: `POST`または`GET`。
`REQUEST_BODY`	string	リクエストボディデータ。`GET`リクエストの場合は`null`に設定します。

コード例

PHP

NodeJS

Ruby

$path = '/auth-test'
    $timestamp = time();
    $method = 'GET';
    $body = $method == 'GET' ? null : json_encode($params);
    $secret = 'YOUR_API_SECRET';

    $signature = hash_hmac('sha256', $path . $timestamp . $method . $body, $secret);

require('crypto');

    let path = '/auth-test'
    let timestamp = Date.now() / 1000 | 0;
    let method = 'GET'
    let body = method === 'GET' ? '' : JSON.stringify(params)
    let secret = 'YOUR_API_SECRET'

    let signature = crypto.createHmac('sha256', secret)
                    .update(path + timestamp + method + body)
                    .digest('hex');

require 'openssl'

path = '/auth-test'
timestamp = Time.now.to_i
method = 'GET'
body = method == 'GET' ? NIL : params.to_json
secret = 'YOUR_API_SECRET'

signature = OpenSSL::HMAC.hexdigest('sha256', secret, path + timestamp.to_s + method + body.to_s)

上にスクロール

コンセプト

HTTP REST APIを使用することで、あらゆるプログラミング言語やシステムでHLRルックアップを簡単かつ効率的に実装できます。シンプルな統合プロセスにより、電話番号の有効性、接続状態、ルーティング詳細に関するリアルタイムな情報をモバイルネットワークに即座に照会できます。

適切なAPIの選択は、お客様の具体的なユースケースによって異なります。 VoIP電話、不正検知、SMSルーティングなどのアプリケーションでリアルタイムのルックアップ結果が必要な場合は、同期APIが最適です。一方、大量処理、一括ルックアップ、大規模データ検証などのユースケースには、非同期APIが帯域幅効率とバッチルックアップ機能により最適化されたパフォーマンスを提供します。

カスタムルーティングオプションを使用してAPIを設定し、速度、精度、コスト効率を最適化できます。ルックアップ結果をストレージに保存することで、CSVおよびJSONレポートのダウンロードや、Webインターフェース経由の高度な分析が可能になります。

同期HLRルックアップAPI

POST /hlr-lookupエンドポイントは、リクエストごとに1つの携帯電話番号(MSISDN)を処理し、HTTPレスポンスボディで即座に結果を返します。結果はJSON形式で返され、携帯電話番号の検証、通話ルーティング、SMSメッセージ配信などのリアルタイムアプリケーションに最適です。

同期API呼び出しは、直接的なHTTPリクエストとレスポンスで構成されます。お客様のシステムはリクエストごとに1つのMSISDN(携帯電話番号)を送信し、JSON形式のリアルタイムHLRルックアップ結果を含む即座のレスポンスを受信します。このAPIは、不正検知、VoIP通話ルーティング、SMSゲートウェイ最適化など、即座の検証と接続チェックを必要とするユースケースに最適化されています。

非同期HLR検索API

POST /hlr-lookupsエンドポイントは、一括処理および大量処理向けに設計されており、リクエストごとに最大1,000件のMSISDNを送信できます。結果を即座に返す代わりに、このAPIは自動化されたWebhookを使用して、お客様のサーバーに段階的に結果を送信します。ルックアップ結果は、HTTP POSTコールバックを介してJSONオブジェクトとして返されます。

非同期APIは、速度、効率性、スケーラビリティに最適化されています。同期呼び出しに伴うネットワーク遅延の問題を解消し、高スループットのルックアップを必要とする企業に最適です。お客様のシステムはリクエストごとに最大1,000件のMSISDNを送信し、当社のプラットフォームがそれらを並列処理して、コールバックごとに最大1,000件の結果をバッチでHTTP Webhookを介してお客様のサーバーに返します。

SDK（ソフトウェア開発キット）

PHP、NodeJS、Ruby向けのソフトウェア開発キット（SDK）により、HLR Lookups APIとの連携プロセスを効率化し、最小限の労力で効率的に接続できます。

これらのSDKは、事前構築された関数、認証処理、構造化されたAPIリクエストテンプレートを提供し、開発時間を短縮し、ベストプラクティスを確保します。

GitHubで利用可能なSDKの完全なリストをご覧いただき、今すぐ連携を開始してください。

PHP

NodeJS

Ruby

1   include('HLRLookupClient.class.php');
2
3   $client = new HLRLookupClient(
4       'YOUR-API-KEY',
5       'YOUR-API-SECRET',
6       '/var/log/hlr-lookups.log'
7   );
8
9   $params = array('msisdn' => '+14156226819');
10  $response = $client->post('/hlr-lookup', $params);

GitHubで見る README.md

1   require('node-hlr-client');
2
3   let response = await client.post('/hlr-lookup', {msisdn: '+491788735000'});
4
5   if (response.status === 200) {
6      // lookup was successful
7      let data = response.data;
8   }

GitHubで見る README.md

1   require 'ruby_hlr_client/client'
2
3   client = HlrLookupsSDK::Client.new(
4       'YOUR-API-KEY',
5       'YOUR-API-SECRET',
6       '/var/log/hlr-lookups.log'
7   )
8
9   params = { :msisdn => '+14156226819' }
10  response = client.get('/hlr-lookup', params)

GitHubで見る README.md

上にスクロール

POST/hlr-lookup保護済み

ネットワークオペレーターから直接取得した、リアルタイムの携帯電話接続状況とポータビリティデータを提供する同期型HLRルックアップを実行します。このエンドポイントは、電話番号が現在到達可能(接続中)か利用不可(電源オフ)かの即時確認が必要な、時間に敏感なアプリケーションのライブトラフィックシナリオに最適です。さらに、有効な番号と無効、不明、または偽の番号を区別するのに役立ちます。

即時の結果を必要としない大規模データセットの一括処理には、高速バッチ処理に最適化された非同期POST /hlr-lookupsの使用をご検討ください。

携帯電話番号ポータビリティデータ(MCCMNC)の取得が主な目的で、リアルタイムの接続状況が不要な場合は、POST /mnp-lookupが携帯電話番号ポータビリティ照会のコスト効率に優れた代替手段を提供します。

リクエスト成功レスポンスエラーレスポンスステータスリファレンス

curl -X POST 'https://www.hlr-lookups.com/api/v2/hlr-lookup' \
          -d "@payload.json"

ペイロード

{
   "msisdn":"+14156226819",
   "route":null,
   "storage":null
}

リクエストパラメータ

キー	タイプ	説明	デフォルト	必須
`msisdn`	string	照会対象の携帯電話番号(MSISDN)を国際形式で指定します(例:+14156226819または0014156226819)。国番号を含める必要があります。	null	必須
`route`	string(3)	このルックアップのルートを指定する3文字の識別子(オプション)。`null`に設定するか、このパラメータを省略すると、カスタムルーティングマップが適用されるか、システムがこのルックアップに最適なルートを自動的に決定します。	null	任意
`storage`	string	手動レビュー、分析、レポート作成のために結果を保存するレポートを指定するストレージ識別子(オプション)。システムは自動的に現在の月のタイムスタンプを追加します。省略または`null`に設定した場合、システムはレポート目的で結果を月ごとに自動的にグループ化します。	null	任意

{
   "id":"f94ef092cb53",
   "msisdn":"+14156226819",
   "connectivity_status":"CONNECTED",
   "mccmnc":"310260",
   "mcc":"310",
   "mnc":"260",
   "imsi":"***************",
   "msin":"**********",
   "msc":"************",
   "original_network_name":"Verizon Wireless",
   "original_country_name":"United States",
   "original_country_code":"US",
   "original_country_prefix":"+1",
   "is_ported":true,
   "ported_network_name":"T-Mobile US",
   "ported_country_name":"United States",
   "ported_country_code":"US",
   "ported_country_prefix":"+1",
   "is_roaming":false,
   "roaming_network_name":null,
   "roaming_country_name":null,
   "roaming_country_code":null,
   "roaming_country_prefix":null,
   "cost":"0.0100",
   "timestamp":"2020-08-07 19:16:17.676+0300",
   "storage":"SYNC-API-2020-08",
   "route":"IP1",
   "processing_status":"COMPLETED",
   "error_code":null,
   "error_description":null,
   "data_source":"LIVE_HLR",
   "routing_instruction":"STATIC:IP1"
}

成功レスポンス属性

名前	タイプ	説明	NULL許可
`id`	string(12)	この照会リクエストに割り当てられた一意の識別子です。	false
`msisdn`	string	照会対象の携帯電話番号で、国際形式(例:+14156226819または0014156226819)でフォーマットされています。	false
`connectivity_status`	string	番号の接続ステータスが正常に取得されたかどうかを示します。可能な値:`CONNECTED` 、`ABSENT` 、`INVALID_MSISDN` 、または`UNDETERMINED` 。	false
`mccmnc`	string(5\|6)	電話番号に現在関連付けられているネットワークを識別する5桁または6桁の移動体国コード(MCC)と移動体網コード(MNC)です。	true
`mcc`	string(3)	電話番号が登録されている国を識別する3桁の移動体国コード(MCC)です。	true
`mnc`	string(2\|3)	電話番号が属する特定のネットワークを識別する2桁または3桁の移動体網コード(MNC)です。	true
`imsi`	string	この番号に関連付けられたSIMカードの一意の識別子である国際移動体加入者識別番号(IMSI)です。利用可能性はネットワーク構成に依存します。	true
`msin`	string(10)	移動体通信事業者のデータベース内の移動体加入者識別番号(MSIN)です。利用可能性はネットワーク構成に依存します。	true
`msc`	string(12)	この加入者の通信を現在処理している移動体交換局(MSC)です。利用可能性はネットワーク構成に依存します。	true
`original_network_name`	string	この番号に関連付けられた元の(ネイティブ)ネットワーク事業者名です。	true
`original_country_name`	string	携帯電話番号が最初に登録された国の正式名称で、英語で提供されます。	true
`original_country_code`	string(2)	電話番号が最初に割り当てられた国を表す2文字のISO国コードです。	true
`original_country_prefix`	string	携帯電話番号の元の国に対応する国際ダイヤルコード(国番号)です。	true
`is_ported`	boolean	携帯電話番号が元のネットワークから別の事業者に番号ポータビリティされたかどうかを示します。	true
`ported_network_name`	string	該当する場合、携帯電話番号が番号ポータビリティされた先のネットワーク事業者名です。	true
`ported_country_name`	string	該当する場合、携帯電話番号が番号ポータビリティされた先の国名です。	true
`ported_country_code`	string(2)	該当する場合、携帯電話番号が番号ポータビリティされた先の国を表す2文字のISO国コードです。	true
`ported_country_prefix`	string	該当する場合、携帯電話番号が番号ポータビリティされた先の国の国際ダイヤルコード(国番号)です。	true
`is_roaming`	boolean	携帯電話番号が現在外国のネットワークでローミング中かどうかを示します。ローミングステータスの利用可能性は移動体通信事業者に依存します。	true
`roaming_network_name`	string	該当する場合、携帯電話番号が現在ローミング中のネットワーク名です。	true
`roaming_country_name`	string	該当する場合、携帯電話番号が現在ローミング中の国名です。	true
`roaming_country_code`	string(2)	該当する場合、携帯電話番号が現在ローミング中の国の2文字のISO国コードです。	true
`roaming_country_prefix`	string	該当する場合、携帯電話番号が現在ローミング中の国の国際ダイヤルコード(国番号)です。	true
`cost`	string	照会コストをユーロ(EUR)で示す文字列形式の小数値です。	true
`timestamp`	string	照会が完了した日時を示すタイムゾーンを含むW3C形式のタイムスタンプです。	true
`storage`	string	照会結果が保存されたストレージの名前です。これはWebインターフェースで利用可能なレポート名およびCSVダウンロードに対応します。	true
`route`	string(3)	この照会リクエストに使用されたルーティング方法を示す3文字の識別子です。	true
`processing_status`	string	照会の処理結果です。可能な値:`COMPLETED`(成功)、`REJECTED`(ネットワーク到達不可、課金なし)、または`FAILED`(処理中にエラーが発生)。	false
`error_code`	integer	カスタマーサポート用の追加診断情報を提供するオプションの内部エラーコードです。	true
`error_description`	string	該当する場合、指定されたエラーコードの簡潔な説明を英語のプレーンテキストで示します。	true
`data_source`	string	このリクエストに使用されたデータソースです。可能な値:`LIVE_HLR`(リアルタイムHLR照会)または`MNP_DB`(静的番号ポータビリティデータベース)。詳細はルーティングオプションを参照してください。	false
`routing_instruction`	string	リクエストで使用されたルーティング指示を示すコロン区切りの文字列です。最初の要素は、ルートを指定した場合は`STATIC`、自動ルーティングの場合は`AUTO`です。2番目の要素はルート識別子で、自動ルーティングリクエストの場合、3番目の要素はルーティング決定の基準となった発信元(つまり`SCORE`, `CUSTOM_GLOBAL_COUNTRY`, `CUSTOM_GLOBAL_MCCMNC`, `CUSTOM_GLOBAL_PREFIX`, `CUSTOM_USER_COUNTRY`, `CUSTOM_USER_MCCMNC`, `CUSTOM_USER_PREFIX`, `MNP_FALLBACK`, `PLATFORM_DEFAULT`, `USER_DEFAULT`)を示します。	false

{
    "errors":[
        "Service unavailable."
    ]
}

エラーレスポンスパラメータ

名前	タイプ	説明	NULL許可
`errors[]`	string[]	エラーを説明する文字列のリスト。	false

ステータス	説明
CONNECTED	番号は有効で、対象端末は現在モバイルネットワークに接続されています。通話、SMS、その他のサービスは正常に受信者に届きます。
ABSENT	番号は有効ですが、対象端末は電源がオフになっているか、一時的にネットワーク圏外にあります。端末がネットワークに再接続するまで、メッセージや通話が配信されない可能性があります。
INVALID_MSISDN	番号が無効であるか、モバイルネットワーク上のいずれの加入者にも現在割り当てられていません。この番号への通話やメッセージは失敗します。
UNDETERMINED	番号の接続状態を判定できませんでした。無効な番号、SS7エラー応答、または対象ネットワーク事業者との接続不足が原因である可能性があります。追加の診断情報については、エラーコードとその説明フィールドを確認してください。

上にスクロール

POST/hlr-lookups保護済み

非同期HLRルックアップのバッチを開始し、ネットワークオペレーターからリアルタイムの携帯電話接続状況とポータビリティデータを取得します。結果はWebhookを通じてお客様のサーバーに配信されます。このメソッドは、データベースのクリーニングや検証など、即時応答を必要としない大量の番号を処理するために最適化されています。通話ルーティングやSMS配信などのリアルタイムアプリケーションには、POST /hlr-lookupエンドポイントの使用をご検討ください。

このエンドポイントは、現在到達可能(接続中)または利用不可(電源オフ)の電話番号を特定し、無効、未割り当て、または偽の番号を除外することを目的とした一括処理に最適です。さらに、接続状況の詳細とともにリアルタイムのポータビリティステータス(MCCMNC)を提供します。

このエンドポイントを使用する前に、ルックアップ結果を非同期で受信するためのWebhook URLが設定されていることを確認してください。 API設定で設定できます。

リクエスト成功レスポンスエラーレスポンス Webhook ステータスリファレンス

curl -X POST 'https://www.hlr-lookups.com/api/v2/hlr-lookups' \
          -d "@payload.json"

ペイロード

{
   "msisdns":["+14156226819","+491788735000","+905536939460"],
   "route":null,
   "storage":null
}

リクエストパラメータ

キー	タイプ	説明	デフォルト	必須
`msisdns`	array	国際形式の携帯電話番号(MSISDN)の配列(例: +14156226819または0014156226819)。1回のリクエストで最大1000件の番号を含めることができます。	null	必須
`route`	string(3)	このルックアップのルートを指定する3文字の識別子(オプション)。`null`に設定するか、このパラメータを省略すると、カスタムルーティングマップが適用されるか、システムがこのルックアップに最適なルートを自動的に決定します。	null	任意
`storage`	string	手動レビュー、分析、レポート作成のために結果を保存するレポートを指定するストレージ識別子(オプション)。システムは自動的に現在の月のタイムスタンプを追加します。省略または`null`に設定した場合、システムはレポート目的で結果を月ごとに自動的にグループ化します。	null	任意

{
   "accepted":[
      {
         "id":"0424928f332e",
         "msisdn":"+491788735000"
      }
   ],
   "accepted_count":1,
   "rejected":[
      {
         "id":null,
         "msisdn":"+31"
      }
   ],
   "rejected_count":1,
   "total_count":2,
   "cost":"0.01",
   "storage":"ASYNC-API-2020-08",
   "route":"IP1",
   "webhook_urls":[
      "https://your-server.com/endpoint"
   ]
}

成功レスポンス属性

名前	タイプ	説明	NULL許可
`accepted`	array	処理が受理された一意の識別子とMSISDNを含むオブジェクトのリスト。	false
`accepted_count`	integer	処理が正常に受理されたMSISDNの総数。	false
`rejected`	array	通常は無効な番号が原因で処理が拒否された一意の識別子とMSISDNを含むオブジェクトのリスト。拒否されたエントリには課金されません。	false
`rejected_count`	integer	検証エラーにより拒否されたMSISDNの総数。	false
`total_count`	integer	処理のために送信された受理および拒否されたMSISDNの合計数。	false
`cost`	string	文字列として表される10進数値で、受理されたルックアップのEUR建て総コストを示します。	false
`storage`	string	ルックアップ結果が追加されるストレージの名前。Webインターフェースを介したレポートおよびCSVダウンロードに使用されます。	false
`route`	string(3\|4)	このルックアップリクエストに使用されたルートを指定する3文字または4文字の識別子。番号ベースの自動ルーティングがリクエストされた場合はAUTOが含まれます。	false
`webhook_urls`	array	API設定で設定されたWebhook URL。結果はここにポストバックされます。	false

{
    "errors":[
        "Service unavailable."
    ]
}

エラーレスポンスパラメータ

名前	タイプ	説明	NULL許可
`errors[]`	string[]	エラーを説明する文字列のリスト。	false

Webhookの処理

送信されると、当社のプラットフォームは提供された電話番号の処理を開始し、事前に指定されたお客様のサーバー上のWebhook URLに結果を送信します。結果は、リクエストボディにJSONオブジェクトを含むHTTP POSTリクエストとして送信されます。

認証

X-Signatures HTTPヘッダーを検証することでWebhookを認証します。

X-Signaturesヘッダーには、セミコロンで区切られた署名のリストが含まれています。リスト内の各署名は、お客様のアカウントで設定されたAPIシークレットのいずれかを使用して生成されます。 Webhookを検証するには、APIキー、シークレット、および生のHTTPボディを使用してSHA-256ハッシュを生成し、リスト内の署名と比較します。

一致した場合、リクエストが本物であり、お客様が管理するシークレットで署名されていることが確認されます。

コード例

$signaturesHeader = (getallheaders() ?? [])['X-Signatures'] ?? ''; // list of signatures
$key = getenv('AUTH_KEY'); // Your API Key
$secret = getenv('AUTH_SECRET'); // Your API Secret
$payload = file_get_contents('php://input'); // The HTTP body of the incoming POST request

// Generate the expected signature
$expectedSignature = hash('sha256', $key . $secret . $payload);

// Split the header into individual signatures
$providedSignatures = explode(';', $signaturesHeader);

// Check if any signature matches
$valid = false;
foreach ($providedSignatures as $sig) {
    if (hash_equals($expectedSignature, $sig)) {
        $valid = true;
        break;
    }
}

ヘッダーに含まれる署名のいずれかが、APIキー、シークレット、およびHTTPボディを連結した文字列から計算されたSHA256ハッシュと一致する場合、リクエストは有効です。

受信確認

お客様のサーバーは、正常に受信したことを確認するために、HTTPステータスコード200 OKで応答することが期待されます。他の応答コードが返された場合、タイムアウトが発生した場合(10秒)、またはその他の配信問題が発生した場合、システムは1分後に自動的にWebhookを再試行します。リクエストが失敗し続ける場合、再試行は指数バックオフ戦略に従い、2, 4, 8, 16, 32, 64, 128, 256, 512, 1024分後に再度試行されます。

この再試行メカニズムにより、お客様のインフラストラクチャへの検索結果の配信において最大限の信頼性が確保されます。一時的なネットワークの問題やサーバーのダウンタイムによるデータ損失のリスクを最小限に抑えます。

Webhookペイロード

{
   "type":"HLR",
   "results":[
      {
         "id":"3b4ac4b6ed1b",
         "msisdn":"+905536939460",
         "connectivity_status":"CONNECTED",
         "mccmnc":"28603",
         "mcc":"286",
         "mnc":"03",
         "imsi":"28603XXXXXXXXXX",
         "msin":"XXXXXXXXXX",
         "msc":"XXXXXXXXXX",
         "original_network_name":"Turk Telekom (AVEA)",
         "original_country_name":"Turkey",
         "original_country_code":"TR",
         "original_country_prefix":"+90",
         "is_ported":false,
         "ported_network_name":null,
         "ported_country_name":null,
         "ported_country_code":null,
         "ported_country_prefix":null,
         "is_roaming":false,
         "roaming_network_name":null,
         "roaming_country_name":null,
         "roaming_country_code":null,
         "roaming_country_prefix":null,
         "cost":"0.0100",
         "timestamp":"2020-08-13 00:04:38.261+0300",
         "storage":"ASYNC-API-2020-08",
         "route":"IP1",
         "processing_status":"COMPLETED",
         "error_code":null,
         "error_description":null,
         "data_source":"LIVE_HLR",
         "routing_instruction":"STATIC:IP1"
      }
   ]
}

Webhookペイロード属性

JSONオブジェクトには、type => HLR属性と、以下に記載されているルックアップオブジェクトのリストを含むresults属性が含まれています。

名前	タイプ	説明	NULL許可
`id`	string(12)	この照会リクエストに割り当てられた一意の識別子です。	false
`msisdn`	string	照会対象の携帯電話番号で、国際形式(例:+14156226819または0014156226819)でフォーマットされています。	false
`connectivity_status`	string	番号の接続ステータスが正常に取得されたかどうかを示します。可能な値:`CONNECTED` 、`ABSENT` 、`INVALID_MSISDN` 、または`UNDETERMINED` 。	false
`mccmnc`	string(5\|6)	電話番号に現在関連付けられているネットワークを識別する5桁または6桁の移動体国コード(MCC)と移動体網コード(MNC)です。	true
`mcc`	string(3)	電話番号が登録されている国を識別する3桁の移動体国コード(MCC)です。	true
`mnc`	string(2\|3)	電話番号が属する特定のネットワークを識別する2桁または3桁の移動体網コード(MNC)です。	true
`imsi`	string	この番号に関連付けられたSIMカードの一意の識別子である国際移動体加入者識別番号(IMSI)です。利用可能性はネットワーク構成に依存します。	true
`msin`	string(10)	移動体通信事業者のデータベース内の移動体加入者識別番号(MSIN)です。利用可能性はネットワーク構成に依存します。	true
`msc`	string(12)	この加入者の通信を現在処理している移動体交換局(MSC)です。利用可能性はネットワーク構成に依存します。	true
`original_network_name`	string	この番号に関連付けられた元の(ネイティブ)ネットワーク事業者名です。	true
`original_country_name`	string	携帯電話番号が最初に登録された国の正式名称で、英語で提供されます。	true
`original_country_code`	string(2)	電話番号が最初に割り当てられた国を表す2文字のISO国コードです。	true
`original_country_prefix`	string	携帯電話番号の元の国に対応する国際ダイヤルコード(国番号)です。	true
`is_ported`	boolean	携帯電話番号が元のネットワークから別の事業者に番号ポータビリティされたかどうかを示します。	true
`ported_network_name`	string	該当する場合、携帯電話番号が番号ポータビリティされた先のネットワーク事業者名です。	true
`ported_country_name`	string	該当する場合、携帯電話番号が番号ポータビリティされた先の国名です。	true
`ported_country_code`	string(2)	該当する場合、携帯電話番号が番号ポータビリティされた先の国を表す2文字のISO国コードです。	true
`ported_country_prefix`	string	該当する場合、携帯電話番号が番号ポータビリティされた先の国の国際ダイヤルコード(国番号)です。	true
`is_roaming`	boolean	携帯電話番号が現在外国のネットワークでローミング中かどうかを示します。ローミングステータスの利用可能性は移動体通信事業者に依存します。	true
`roaming_network_name`	string	該当する場合、携帯電話番号が現在ローミング中のネットワーク名です。	true
`roaming_country_name`	string	該当する場合、携帯電話番号が現在ローミング中の国名です。	true
`roaming_country_code`	string(2)	該当する場合、携帯電話番号が現在ローミング中の国の2文字のISO国コードです。	true
`roaming_country_prefix`	string	該当する場合、携帯電話番号が現在ローミング中の国の国際ダイヤルコード(国番号)です。	true
`cost`	string	照会コストをユーロ(EUR)で示す文字列形式の小数値です。	true
`timestamp`	string	照会が完了した日時を示すタイムゾーンを含むW3C形式のタイムスタンプです。	true
`storage`	string	照会結果が保存されたストレージの名前です。これはWebインターフェースで利用可能なレポート名およびCSVダウンロードに対応します。	true
`route`	string(3)	この照会リクエストに使用されたルーティング方法を示す3文字の識別子です。	true
`processing_status`	string	照会の処理結果です。可能な値:`COMPLETED`(成功)、`REJECTED`(ネットワーク到達不可、課金なし)、または`FAILED`(処理中にエラーが発生)。	false
`error_code`	integer	カスタマーサポート用の追加診断情報を提供するオプションの内部エラーコードです。	true
`error_description`	string	該当する場合、指定されたエラーコードの簡潔な説明を英語のプレーンテキストで示します。	true
`data_source`	string	このリクエストに使用されたデータソースです。可能な値:`LIVE_HLR`(リアルタイムHLR照会)または`MNP_DB`(静的番号ポータビリティデータベース)。詳細はルーティングオプションを参照してください。	false
`routing_instruction`	string	リクエストで使用されたルーティング指示を示すコロン区切りの文字列です。最初の要素は、ルートを指定した場合は`STATIC`、自動ルーティングの場合は`AUTO`です。2番目の要素はルート識別子で、自動ルーティングリクエストの場合、3番目の要素はルーティング決定の基準となった発信元(つまり`SCORE`, `CUSTOM_GLOBAL_COUNTRY`, `CUSTOM_GLOBAL_MCCMNC`, `CUSTOM_GLOBAL_PREFIX`, `CUSTOM_USER_COUNTRY`, `CUSTOM_USER_MCCMNC`, `CUSTOM_USER_PREFIX`, `MNP_FALLBACK`, `PLATFORM_DEFAULT`, `USER_DEFAULT`)を示します。	false

ステータス	説明
CONNECTED	番号は有効で、対象端末は現在モバイルネットワークに接続されています。通話、SMS、その他のサービスは正常に受信者に届きます。
ABSENT	番号は有効ですが、対象端末は電源がオフになっているか、一時的にネットワーク圏外にあります。端末がネットワークに再接続するまで、メッセージや通話が配信されない可能性があります。
INVALID_MSISDN	番号が無効であるか、モバイルネットワーク上のいずれの加入者にも現在割り当てられていません。この番号への通話やメッセージは失敗します。
UNDETERMINED	番号の接続状態を判定できませんでした。無効な番号、SS7エラー応答、または対象ネットワーク事業者との接続不足が原因である可能性があります。追加の診断情報については、エラーコードとその説明フィールドを確認してください。

上にスクロール

POST/mnp-lookup保護済み

同期MNPルックアップを実行し、携帯電話番号ポータビリティとネットワーク情報を提供します。このエンドポイントは、特定の携帯電話番号の現在のMCCMNCを抽出し、元のネットワークと現在のネットワークをリアルタイムで特定することが主な目的の場合に適しています。

即時の結果を必要としない大規模データセットの一括処理には、高速バッチ処理に最適化された非同期POST /mnp-lookupsの使用をご検討ください。

MNPクエリは、ポータビリティとネットワーク情報を確実に判定しますが、対象の携帯電話が現在ネットワークに接続されており到達可能かどうかは示しません。リアルタイムの接続情報を取得するには、代わりにPOST /hlr-lookupエンドポイントをご使用ください。

リクエスト成功レスポンスエラーレスポンス

curl -X POST 'https://www.hlr-lookups.com/api/v2/mnp-lookup' \
          -d "@payload.json"

ペイロード

{
   "msisdn":"+14156226819",
   "route":null,
   "storage":null
}

リクエストパラメータ

キー	タイプ	説明	デフォルト	必須
`msisdn`	string	照会対象の携帯電話番号(MSISDN)を国際形式で指定します(例:+14156226819または0014156226819)。国番号を含める必要があります。	null	必須
`route`	string(3)	このルックアップのルートを指定する3文字の識別子(オプション)。`null`に設定するか、このパラメータを省略すると、カスタムルーティングマップが適用されるか、システムがこのルックアップに最適なルートを自動的に決定します。	null	任意
`storage`	string	手動レビュー、分析、レポート作成のために結果を保存するレポートを指定するストレージ識別子(オプション)。システムは自動的に現在の月のタイムスタンプを追加します。省略または`null`に設定した場合、システムはレポート目的で結果を月ごとに自動的にグループ化します。	null	任意

{
   "id":"e428acb1c0ae",
   "msisdn":"+14156226819",
   "query_status":"OK",
   "mccmnc":"310260",
   "mcc":"310",
   "mnc":"260",
   "is_ported":true,
   "original_network_name":"Verizon Wireless:6006 - SVR/2",
   "original_country_name":"United States",
   "original_country_code":"US",
   "original_country_prefix":"+1415",
   "ported_network_name":"T-Mobile US:6529 - SVR/2",
   "ported_country_name":"United States",
   "ported_country_code":"US",
   "ported_country_prefix":"+1",
   "extra":"LRN:4154250000",
   "cost":"0.0050",
   "timestamp":"2020-08-05 21:21:33.490+0300",
   "storage":"WEB-CLIENT-SOLO-MNP-2020-08",
   "route":"PTX",
   "error_code":null
}

成功レスポンス属性

名前	タイプ	説明	NULL許可
`id`	string(12)	この照会の一意の12文字識別子です。	false
`msisdn`	string	この照会リクエストで評価された携帯電話番号です。	false
`query_status`	string	ポータビリティおよびネットワーク情報の取得が成功したかどうかを示します。可能な値は`OK`または`FAILED`です。	false
`mccmnc`	string(5\|6)	携帯電話番号が現在所属するネットワークを識別する5桁または6桁のMCCMNC(移動体国コードと移動体ネットワークコードの組み合わせ)です。	true
`mcc`	string(3)	携帯電話番号の現在のネットワークに関連付けられた国を表す3桁のMCC(移動体国コード)です。	true
`mnc`	string(2\|3)	携帯電話番号の現在のネットワーク事業者を識別する2桁または3桁のMNC(移動体ネットワークコード)です。	true
`is_ported`	boolean	電話番号が元のネットワークから新しい事業者に番号ポータビリティされたかどうかを示します。	true
`original_network_name`	string	照会対象の携帯電話番号の元のネットワーク事業者名を指定する任意の文字列(英語)です。	true
`original_country_name`	string	照会対象の携帯電話番号の元の国を示す任意の文字列(英語)です。	true
`original_country_code`	string(2)	照会対象の携帯電話番号の元の国を表す2文字のISO国コードです。	true
`original_country_prefix`	string	照会対象の携帯電話番号に関連付けられた元の国の国際電話番号です。	true
`ported_network_name`	string	該当する場合、照会対象の携帯電話番号が番号ポータビリティされた先のネットワーク事業者を指定します。	true
`ported_country_name`	string	該当する場合、照会対象の携帯電話番号が番号ポータビリティされた先の国を指定します。	true
`ported_country_code`	string(2)	該当する場合、照会対象の携帯電話番号が番号ポータビリティされた先の国を表す2文字のISO国コードです。	true
`ported_country_prefix`	string	該当する場合、照会対象の携帯電話番号が番号ポータビリティされた先の国の国際電話番号です。	true
`extra`	string	電話番号に関するオプションの追加詳細を提供する任意の文字列です。	true
`cost`	string	この照会のコストをユーロ(EUR)で示す、文字列として表現された小数値です。	true
`timestamp`	string	照会が完了した日時を示す、タイムゾーン情報を含むW3C形式のタイムスタンプです。	true
`storage`	string	照会結果が追加されたストレージ名(またはレポート名)です。これはCSVダウンロードおよびWebインターフェース経由のレポート作成に使用されます。	true
`route`	string(3)	この照会リクエストに使用されたルートを指定する3文字の識別子です。	true
`error_code`	integer	カスタマーサポートの診断に追加のコンテキストを提供するオプションの内部エラーコードです。	true

{
    "errors":[
        "Service unavailable."
    ]
}

エラーレスポンスパラメータ

名前	タイプ	説明	NULL許可
`errors[]`	string[]	エラーを説明する文字列のリスト。	false

上にスクロール

POST/mnp-lookups保護済み

非同期MNP(携帯電話番号ポータビリティ)ルックアップのバッチを開始し、現在のMCCMNCを取得して、元のネットワークと現在のネットワークをリアルタイムで特定します。結果はWebhookを通じてお客様のサーバーに配信されます。このメソッドは、データベースのクリーニングや検証など、即時応答を必要としない大量の番号を処理するために最適化されています。通話ルーティングやSMS配信などのリアルタイムアプリケーションには、POST /mnp-lookupエンドポイントの使用をご検討ください。

MNPクエリは、ポータビリティとネットワーク情報を確実に判定しますが、対象の携帯電話が現在ネットワークに接続されており到達可能かどうかは示しません。リアルタイムの接続情報を取得するには、代わりにPOST /hlr-lookupsエンドポイントをご使用ください。

このエンドポイントを使用する前に、ルックアップ結果を非同期で受信するためのWebhook URLが設定されていることを確認してください。 API設定で設定できます。

リクエスト成功レスポンスエラーレスポンス Webhook

curl -X POST 'https://www.hlr-lookups.com/api/v2/mnp-lookups' \
          -d "@payload.json"

ペイロード

{
   "msisdns":["+14156226819","+491788735000","+905536939460"],
   "route":null,
   "storage":null
}

リクエストパラメータ

キー	タイプ	説明	デフォルト	必須
`msisdns`	array	国際形式の携帯電話番号(MSISDN)の配列(例: +14156226819または0014156226819)。1回のリクエストで最大1000件の番号を含めることができます。	null	必須
`route`	string(3)	このルックアップのルートを指定する3文字の識別子(オプション)。`null`に設定するか、このパラメータを省略すると、カスタムルーティングマップが適用されるか、システムが自動的にこのリクエストに最適なルートを決定します。	null	任意
`storage`	string	手動レビュー、分析、レポート作成のために結果を保存するレポートを指定するストレージ識別子(オプション)。システムは自動的に現在の月のタイムスタンプを追加します。省略または`null`に設定した場合、システムはレポート目的で結果を月ごとに自動的にグループ化します。	null	任意

{
   "accepted":[
      {
         "id":"0424928f332e",
         "msisdn":"+491788735000"
      }
   ],
   "accepted_count":1,
   "rejected":[
      {
         "id":null,
         "msisdn":"+31"
      }
   ],
   "rejected_count":1,
   "total_count":2,
   "cost":"0.01",
   "storage":"ASYNC-API-2020-08",
   "route":"IP1",
   "webhook_urls":[
      "https://your-server.com/endpoint"
   ]
}

成功レスポンス属性

名前	タイプ	説明	NULL許可
`accepted`	array	処理が受理された一意の識別子とMSISDNを含むオブジェクトのリスト。	false
`accepted_count`	integer	処理が正常に受理されたMSISDNの総数。	false
`rejected`	array	通常は無効な番号が原因で処理が拒否された一意の識別子とMSISDNを含むオブジェクトのリスト。拒否されたエントリには課金されません。	false
`rejected_count`	integer	検証エラーにより拒否されたMSISDNの総数。	false
`total_count`	integer	処理のために送信された受理および拒否されたMSISDNの合計数。	false
`cost`	string	文字列として表される10進数値で、受理されたルックアップのEUR建て総コストを示します。	false
`storage`	string	ルックアップ結果が追加されるストレージの名前。Webインターフェースを介したレポートおよびCSVダウンロードに使用されます。	false
`route`	string(3)	この照会リクエストに使用されたルートを指定する3文字の識別子です。	false
`webhook_urls`	array	API設定で設定されたWebhook URL。結果はここにポストバックされます。	false

{
    "errors":[
        "Service unavailable."
    ]
}

エラーレスポンスパラメータ

名前	タイプ	説明	NULL許可
`errors[]`	string[]	エラーを説明する文字列のリスト。	false

Webhookの処理

送信されると、当社のプラットフォームは提供された電話番号の処理を開始し、事前に指定されたお客様のサーバー上のWebhook URLに結果を送信します。結果は、リクエストボディにJSONオブジェクトを含むHTTP POSTリクエストとして送信されます。

認証

X-Signatures HTTPヘッダーを検証することでWebhookを認証します。

X-Signaturesヘッダーには、セミコロンで区切られた署名のリストが含まれています。リスト内の各署名は、お客様のアカウントで設定されたAPIシークレットのいずれかを使用して生成されます。 Webhookを検証するには、APIキー、シークレット、および生のHTTPボディを使用してSHA-256ハッシュを生成し、リスト内の署名と比較します。

一致した場合、リクエストが本物であり、お客様が管理するシークレットで署名されていることが確認されます。

コード例

$signaturesHeader = (getallheaders() ?? [])['X-Signatures'] ?? ''; // list of signatures
$key = getenv('AUTH_KEY'); // Your API Key
$secret = getenv('AUTH_SECRET'); // Your API Secret
$payload = file_get_contents('php://input'); // The HTTP body of the incoming POST request

// Generate the expected signature
$expectedSignature = hash('sha256', $key . $secret . $payload);

// Split the header into individual signatures
$providedSignatures = explode(';', $signaturesHeader);

// Check if any signature matches
$valid = false;
foreach ($providedSignatures as $sig) {
    if (hash_equals($expectedSignature, $sig)) {
        $valid = true;
        break;
    }
}

ヘッダーに含まれる署名のいずれかが、APIキー、シークレット、およびHTTPボディを連結した文字列から計算されたSHA256ハッシュと一致する場合、リクエストは有効です。

受信確認

お客様のサーバーは、正常に受信したことを確認するために、HTTPステータスコード200 OKで応答することが期待されます。他の応答コードが返された場合、タイムアウトが発生した場合(10秒)、またはその他の配信問題が発生した場合、システムは1分後に自動的にWebhookを再試行します。リクエストが失敗し続ける場合、再試行は指数バックオフ戦略に従い、2, 4, 8, 16, 32, 64, 128, 256, 512, 1024分後に再度試行されます。

この再試行メカニズムにより、お客様のインフラストラクチャへの検索結果の配信において最大限の信頼性が確保されます。一時的なネットワークの問題やサーバーのダウンタイムによるデータ損失のリスクを最小限に抑えます。

Webhookペイロード

{
    "type":"MNP",
    "results":[
        {
           "id":"e428acb1c0ae",
           "msisdn":"+14156226819",
           "query_status":"OK",
           "mccmnc":"310260",
           "mcc":"310",
           "mnc":"260",
           "is_ported":true,
           "original_network_name":"Verizon Wireless:6006 - SVR/2",
           "original_country_name":"United States",
           "original_country_code":"US",
           "original_country_prefix":"+1415",
           "ported_network_name":"T-Mobile US:6529 - SVR/2",
           "ported_country_name":"United States",
           "ported_country_code":"US",
           "ported_country_prefix":"+1",
           "extra":"LRN:4154250000",
           "cost":"0.0050",
           "timestamp":"2020-08-05 21:21:33.490+0300",
           "storage":"WEB-CLIENT-SOLO-MNP-2020-08",
           "route":"PTX",
           "error_code":null
        }
    ]
}

Webhookペイロード属性

JSONオブジェクトには、type => MNP属性と、以下に記載されているルックアップオブジェクトのリストを含むresults属性が含まれています。

名前	タイプ	説明	NULL許可
`id`	string(12)	この照会の一意の12文字識別子です。	false
`msisdn`	string	この照会リクエストで評価された携帯電話番号です。	false
`query_status`	string	ポータビリティおよびネットワーク情報の取得が成功したかどうかを示します。可能な値は`OK`または`FAILED`です。	false
`mccmnc`	string(5\|6)	携帯電話番号が現在所属するネットワークを識別する5桁または6桁のMCCMNC(移動体国コードと移動体ネットワークコードの組み合わせ)です。	true
`mcc`	string(3)	携帯電話番号の現在のネットワークに関連付けられた国を表す3桁のMCC(移動体国コード)です。	true
`mnc`	string(2\|3)	携帯電話番号の現在のネットワーク事業者を識別する2桁または3桁のMNC(移動体ネットワークコード)です。	true
`is_ported`	boolean	電話番号が元のネットワークから新しい事業者に番号ポータビリティされたかどうかを示します。	true
`original_network_name`	string	照会対象の携帯電話番号の元のネットワーク事業者名を指定する任意の文字列(英語)です。	true
`original_country_name`	string	照会対象の携帯電話番号の元の国を示す任意の文字列(英語)です。	true
`original_country_code`	string(2)	照会対象の携帯電話番号の元の国を表す2文字のISO国コードです。	true
`original_country_prefix`	string	照会対象の携帯電話番号に関連付けられた元の国の国際電話番号です。	true
`ported_network_name`	string	該当する場合、照会対象の携帯電話番号が番号ポータビリティされた先のネットワーク事業者を指定します。	true
`ported_country_name`	string	該当する場合、照会対象の携帯電話番号が番号ポータビリティされた先の国を指定します。	true
`ported_country_code`	string(2)	該当する場合、照会対象の携帯電話番号が番号ポータビリティされた先の国を表す2文字のISO国コードです。	true
`ported_country_prefix`	string	該当する場合、照会対象の携帯電話番号が番号ポータビリティされた先の国の国際電話番号です。	true
`extra`	string	電話番号に関するオプションの追加詳細を提供する任意の文字列です。	true
`cost`	string	この照会のコストをユーロ(EUR)で示す、文字列として表現された小数値です。	true
`timestamp`	string	照会が完了した日時を示す、タイムゾーン情報を含むW3C形式のタイムスタンプです。	true
`storage`	string	照会結果が追加されたストレージ名(またはレポート名)です。これはCSVダウンロードおよびWebインターフェース経由のレポート作成に使用されます。	true
`route`	string(3)	この照会リクエストに使用されたルートを指定する3文字の識別子です。	true
`error_code`	integer	カスタマーサポートの診断に追加のコンテキストを提供するオプションの内部エラーコードです。	true

上にスクロール

POST/nt-lookup保護済み

同期番号種別(NT)照会を実行します。このエンドポイントは、提供された電話番号が固定電話、携帯電話、プレミアムレート、VoIP、ポケベル、またはその他の番号計画範囲に属するかをリアルタイムで判定することが主な目的の場合に最適です。

NT照会は電話番号の種別を確実に検出しますが、対象番号が現在ネットワークに接続されており到達可能であるかは示しません。リアルタイムの接続情報を取得するには、POST /hlr-lookupエンドポイントをご利用ください。

お客様のユースケースで正確なネットワークおよびポータビリティ情報(MCCMNC)が必要だがリアルタイムの接続状態は不要な場合は、携帯電話番号ポータビリティ照会用のPOST /mnp-lookupエンドポイントをご利用ください。

リクエスト成功レスポンスエラーレスポンス種別リファレンス

curl -X POST 'https://www.hlr-lookups.com/api/v2/nt-lookup' \
          -d "@payload.json"

ペイロード

{
   "number":"+14156226819",
   "route":null,
   "storage":null
}

リクエストパラメータ

キー	タイプ	説明	デフォルト	必須
`number`	string	国際形式の電話番号(例: +4989702626または004989702626)。	null	mandatory
`route`	string(3)	この照会のルートを指定する3文字の識別子(オプション)。`null`に設定するか、このパラメータを省略すると、お客様のカスタムルーティングマップが適用されるか、システムがこのリクエストに最適なルートを自動的に決定します。	null	任意
`storage`	string	手動レビュー、分析、レポート作成のために結果を保存するレポートを指定するストレージ識別子(オプション)。システムは自動的に現在の月のタイムスタンプを追加します。省略または`null`に設定した場合、システムはレポート目的で結果を月ごとに自動的にグループ化します。	null	任意

{
     "id":"2ed0788379c6",
     "number":"+4989702626",
     "number_type":"LANDLINE",
     "query_status":"OK",
     "is_valid":true,
     "invalid_reason":null,
     "is_possibly_ported":false,
     "is_vanity_number":false,
     "qualifies_for_hlr_lookup":false,
     "mccmnc":null,
     "mcc":null,
     "mnc":null,
     "original_network_name":null,
     "original_country_name":"Germany",
     "original_country_code":"DE",
     "regions":[
        "Munich"
     ],
     "timezones":[
        "Europe/Berlin"
     ],
     "info_text":"This is a landline number.",
     "cost":"0.0050",
     "timestamp":"2015-12-04 10:36:41.866283+00",
     "storage":"SYNC-API-NT-2015-12",
     "route":"LC1"
}

成功レスポンス属性

名前	タイプ	説明	NULL許可
`id`	string(12)	この照会リクエストに割り当てられた一意の識別子です。	false
`number`	string	この照会リクエストで評価された電話番号。	false
`number_type`	string	検出された番号タイプ。可能な値: `LANDLINE` , `MOBILE` , `MOBILE_OR_LANDLINE` , `TOLL_FREE` , `PREMIUM_RATE` , `SHARED_COST` , `VOIP` , `PAGER` , `UAN` , `VOICEMAIL` , `UNKNOWN` 。	false
`query_status`	string	番号タイプ情報が正常に取得されたかどうかを示します。成功した場合は`OK`、照会に失敗した場合は`FAILED`を返します。	false
`is_valid`	boolean	電話番号が構文的に有効かどうかを示します。	true
`invalid_reason`	string	電話番号が無効と見なされる理由を英語で説明する平文メッセージ(例: "too short"または"invalid prefix")。番号が有効な場合は`null`。	true
`is_possibly_ported`	boolean	電話番号が元の事業者から別のキャリアに移行された可能性があるかどうかを示します。確実な移行情報については、MNP照会をご利用ください。	true
`is_vanity_number`	boolean	電話番号がバニティ番号(アルファベット文字を含む番号)であるかどうかを示します。	true
`qualifies_for_hlr_lookup`	boolean	HLR照会による追加クエリの対象となる電話番号かどうかを示します。	true
`mccmnc`	string(5\|6)	携帯電話番号の元のネットワークを識別するMCCMNCタプル(移動体国コードと移動体ネットワークコード)を表す5文字または6文字の文字列。	true
`mcc`	string(3)	電話番号の元の携帯電話ネットワークに関連する国を識別するMCC(移動体国コード)を表す3文字の文字列。	true
`mnc`	string(2\|3)	電話番号の元の携帯電話ネットワーク事業者を識別するMNC(移動体ネットワークコード)を表す2文字または3文字の文字列。	true
`original_network_name`	string	検査された携帯電話番号の元のネットワーク事業者名を英語で指定する任意の平文文字列。	true
`original_country_name`	string	検査された携帯電話番号に関連する元の国を英語で指定する任意の平文文字列。	true
`original_country_code`	string(2)	検査された携帯電話番号の元の国を示す2文字のISO国コード。	true
`regions`	array	この電話番号に関連する地理的地域を英語で指定する人間が読める文字列のリスト。	true
`timezones`	array	この電話番号に関連するタイムゾーン(Olson形式)のリスト。	true
`info_text`	string	電話番号に関する追加情報を含む可能性のある任意の文字列。	true
`cost`	string	この照会のコスト(ユーロ)を示す文字列として表される10進数値。	true
`timestamp`	string	照会が完了した日時を示すW3C形式のタイムスタンプ(タイムゾーン含む)。	true
`storage`	string	照会結果が追加されたストレージ名を指定します。これは、Webインターフェースを介したCSVダウンロードおよび分析に使用されるレポート名に対応します。	true
`route`	string(3)	この照会リクエストに使用されたルートを指定する3文字の識別子です。	true

{
    "errors":[
        "Service unavailable."
    ]
}

エラーレスポンスパラメータ

名前	タイプ	説明	NULL許可
`errors[]`	string[]	エラーを説明する文字列のリスト。	false

タイプ	説明
LANDLINE	固定電話番号
MOBILE	携帯電話番号。接続状態、ネットワーク、番号ポータビリティ、ローミング情報を取得するためのHLRルックアップに対応しています。
MOBILE_OR_LANDLINE	固定電話または携帯電話番号。HLRルックアップに対応している可能性があります。
TOLL_FREE	フリーダイヤル番号
PREMIUM_RATE	追加料金が発生するプレミアムレート番号
SHARED_COST	通話料金分担番号。通常、プレミアムレート番号より低料金です。
VOIP	VoIP電話番号。TSoIP電話番号(Telephony Service over IP)を含みます。
PAGER	ポケットベル番号。通常、音声通話機能はありません。
UAN	代表番号(企業番号)。特定の事業所に転送される場合がありますが、企業全体で1つの番号を使用できます。
VOICEMAIL	ボイスメール番号
UNKNOWN	番号種別を判別できませんでした。

上にスクロール

POST/nt-lookups 保護済み

このエンドポイントは、一連の非同期番号タイプルックアップを実行し、結果をWebhook経由でお客様のサーバーに送信します。指定された電話番号が固定電話、携帯電話、プレミアムレート、VoIP、ポケベル、またはその他の番号計画範囲に属するかどうかを判断することが主な目的である場合に適しています。大量の番号を高速処理するために最適化されており、このエンドポイントは一括処理(データベースのサニタイゼーションなど)に最適です。リアルタイムトラフィックや時間的制約のあるユースケースには、代わりにPOST /nt-lookupエンドポイントをご使用ください。

このエンドポイントを呼び出すには、事前にAPI設定でWebhook URLを指定する必要があります。

リクエスト成功レスポンスエラーレスポンス Webhook 種別リファレンス

curl -X POST 'https://www.hlr-lookups.com/api/v2/nt-lookups' \
          -d "@payload.json"

ペイロード

{
   "numbers":["+14156226819","+4989702626"],
   "route":null,
   "storage":null
}

リクエストパラメータ

キー	タイプ	説明	デフォルト	必須
`numbers`	array	国際形式の電話番号の配列(+14156226819または004989702626など)。1リクエストあたり最大1000件の番号を含めることができます。	null	必須
`route`	string(3)	このルックアップのルートを指定する3文字のオプション識別子。`null`に設定するか、このパラメータを省略すると、カスタムルーティングマップが適用されるか、システムがこのリクエストに最適なルートを自動的に決定します。	null	任意
`storage`	string	手動レビュー、分析、レポート作成のために結果を保存するレポートを指定するストレージ識別子(オプション)。システムは自動的に現在の月のタイムスタンプを追加します。省略または`null`に設定した場合、システムはレポート目的で結果を月ごとに自動的にグループ化します。	null	任意

{
   "accepted":[
      {
         "id":"9f8a52cfa7d2",
         "number":"+905536939460"
      }
   ],
   "accepted_count":1,
   "rejected":[
      {
         "id":null,
         "number":"+31"
      }
   ],
   "rejected_count":2,
   "total_count":3,
   "cost":0.005,
   "storage":"ASYNC-API-NT-2020-08",
   "route":"LC1",
   "webhook_urls":[
      "https://your-server.com/endpoint"
   ]
}

成功レスポンス属性

名前	タイプ	説明	NULL許可
`accepted`	array	処理が受け付けられた一意の識別子と電話番号を含むオブジェクトの配列。	false
`accepted_count`	integer	処理が受け付けられた電話番号の総数。	false
`rejected`	array	処理が拒否された一意の識別子と電話番号を含むオブジェクトの配列。通常、これらの番号は無効であり、課金されません。	false
`rejected_count`	integer	処理が拒否された電話番号の総数。	false
`total_count`	integer	処理のために送信された受付済みおよび拒否済み電話番号の総数。	false
`cost`	string	これらのルックアップのEUR建てコストを示す10進数値を表す文字列。	false
`storage`	string	ルックアップ結果が追加されたストレージ(レポート)の名前。この名前は、Webインターフェースを介したCSVダウンロードと分析に使用されます。	false
`route`	string(3)	このルックアップリクエストに使用されたルートを指定する3文字の識別子。	false
`webhook_urls`	array	API設定で設定されたWebhook URL。結果はここにポストバックされます。	false

{
    "errors":[
        "Service unavailable."
    ]
}

エラーレスポンスパラメータ

名前	タイプ	説明	NULL許可
`errors[]`	string[]	エラーを説明する文字列のリスト。	false

Webhookの処理

送信されると、当社のプラットフォームは提供された電話番号の処理を開始し、事前に指定されたお客様のサーバー上のWebhook URLに結果を送信します。結果は、リクエストボディにJSONオブジェクトを含むHTTP POSTリクエストとして送信されます。

認証

X-Signatures HTTPヘッダーを検証することでWebhookを認証します。

X-Signaturesヘッダーには、セミコロンで区切られた署名のリストが含まれています。リスト内の各署名は、お客様のアカウントで設定されたAPIシークレットのいずれかを使用して生成されます。 Webhookを検証するには、APIキー、シークレット、および生のHTTPボディを使用してSHA-256ハッシュを生成し、リスト内の署名と比較します。

一致した場合、リクエストが本物であり、お客様が管理するシークレットで署名されていることが確認されます。

コード例

$signaturesHeader = (getallheaders() ?? [])['X-Signatures'] ?? ''; // list of signatures
$key = getenv('AUTH_KEY'); // Your API Key
$secret = getenv('AUTH_SECRET'); // Your API Secret
$payload = file_get_contents('php://input'); // The HTTP body of the incoming POST request

// Generate the expected signature
$expectedSignature = hash('sha256', $key . $secret . $payload);

// Split the header into individual signatures
$providedSignatures = explode(';', $signaturesHeader);

// Check if any signature matches
$valid = false;
foreach ($providedSignatures as $sig) {
    if (hash_equals($expectedSignature, $sig)) {
        $valid = true;
        break;
    }
}

ヘッダーに含まれる署名のいずれかが、APIキー、シークレット、およびHTTPボディを連結した文字列から計算されたSHA256ハッシュと一致する場合、リクエストは有効です。

受信確認

お客様のサーバーは、正常に受信したことを確認するために、HTTPステータスコード200 OKで応答することが期待されます。他の応答コードが返された場合、タイムアウトが発生した場合(10秒)、またはその他の配信問題が発生した場合、システムは1分後に自動的にWebhookを再試行します。リクエストが失敗し続ける場合、再試行は指数バックオフ戦略に従い、2, 4, 8, 16, 32, 64, 128, 256, 512, 1024分後に再度試行されます。

この再試行メカニズムにより、お客様のインフラストラクチャへの検索結果の配信において最大限の信頼性が確保されます。一時的なネットワークの問題やサーバーのダウンタイムによるデータ損失のリスクを最小限に抑えます。

Webhookペイロード

{
   "type":"NT",
   "results":[
      {
         "id":"9f8a52cfa7d2",
         "number":"+905536939460",
         "numbertype":"MOBILE",
         "state":"COMPLETED",
         "isvalid":"Yes",
         "invalidreason":null,
         "ispossiblyported":"Yes",
         "isvanitynumber":"No",
         "qualifiesforhlrlookup":"Yes",
         "originalcarrier":"Turk Telekom (AVEA)",
         "mccmnc":"28603",
         "mcc":"286",
         "mnc":"03",
         "countrycode":"TR",
         "regions":[
            "Turkey"
         ],
         "timezones":[
            "Europe\/Istanbul"
         ],
         "infotext":"This number qualifies for HLR lookups. Determine if this subscriber number is connected, absent or invalid by running an HLR lookup. This is a mobile number and might be in roaming state. Run an HLR lookup to obtain roaming information (if available). This number is possibly ported and the carrier information might be inaccurate. To obtain portability information run an HLR lookup.",
         "usercharge":"0.0050",
         "inserttime":"2020-08-13 01:57:15.897+0300",
         "storage":"ASYNC-API-NT-2020-08",
         "route":"LC1",
         "interface":"Async API"
      }
   ]
}

Webhookペイロード属性

JSONオブジェクトには、type => NT属性と、以下に記載されているルックアップオブジェクトのリストを含むresults属性が含まれています。

名前	タイプ	説明	NULL許可
`id`	string(12)	この照会リクエストに割り当てられた一意の識別子です。	false
`number`	string	この照会リクエストで評価された電話番号。	false
`number_type`	string	検出された番号タイプ。可能な値: `LANDLINE` , `MOBILE` , `MOBILE_OR_LANDLINE` , `TOLL_FREE` , `PREMIUM_RATE` , `SHARED_COST` , `VOIP` , `PAGER` , `UAN` , `VOICEMAIL` , `UNKNOWN` 。	false
`query_status`	string	番号タイプ情報が正常に取得されたかどうかを示します。成功した場合は`OK`、照会に失敗した場合は`FAILED`を返します。	false
`is_valid`	boolean	電話番号が構文的に有効かどうかを示します。	true
`invalid_reason`	string	電話番号が無効と見なされる理由を英語で説明する平文メッセージ(例: "too short"または"invalid prefix")。番号が有効な場合は`null`。	true
`is_possibly_ported`	boolean	電話番号が元の事業者から別のキャリアに移行された可能性があるかどうかを示します。確実な移行情報については、MNP照会をご利用ください。	true
`is_vanity_number`	boolean	電話番号がバニティ番号(アルファベット文字を含む番号)であるかどうかを示します。	true
`qualifies_for_hlr_lookup`	boolean	HLR照会による追加クエリの対象となる電話番号かどうかを示します。	true
`mccmnc`	string(5\|6)	携帯電話番号の元のネットワークを識別するMCCMNCタプル(移動体国コードと移動体ネットワークコード)を表す5文字または6文字の文字列。	true
`mcc`	string(3)	電話番号の元の携帯電話ネットワークに関連する国を識別するMCC(移動体国コード)を表す3文字の文字列。	true
`mnc`	string(2\|3)	電話番号の元の携帯電話ネットワーク事業者を識別するMNC(移動体ネットワークコード)を表す2文字または3文字の文字列。	true
`original_network_name`	string	検査された携帯電話番号の元のネットワーク事業者名を英語で指定する任意の平文文字列。	true
`original_country_name`	string	検査された携帯電話番号に関連する元の国を英語で指定する任意の平文文字列。	true
`original_country_code`	string(2)	検査された携帯電話番号の元の国を示す2文字のISO国コード。	true
`regions`	array	この電話番号に関連する地理的地域を英語で指定する人間が読める文字列のリスト。	true
`timezones`	array	この電話番号に関連するタイムゾーン(Olson形式)のリスト。	true
`info_text`	string	電話番号に関する追加情報を含む可能性のある任意の文字列。	true
`cost`	string	この照会のコスト(ユーロ)を示す文字列として表される10進数値。	true
`timestamp`	string	照会が完了した日時を示すW3C形式のタイムスタンプ(タイムゾーン含む)。	true
`storage`	string	照会結果が追加されたストレージ名を指定します。これは、Webインターフェースを介したCSVダウンロードおよび分析に使用されるレポート名に対応します。	true
`route`	string(3)	この照会リクエストに使用されたルートを指定する3文字の識別子です。	true

タイプ	説明
LANDLINE	固定電話番号
MOBILE	携帯電話番号。接続状態、ネットワーク、番号ポータビリティ、ローミング情報を取得するためのHLRルックアップに対応しています。
MOBILE_OR_LANDLINE	固定電話または携帯電話番号。HLRルックアップに対応している可能性があります。
TOLL_FREE	フリーダイヤル番号
PREMIUM_RATE	追加料金が発生するプレミアムレート番号
SHARED_COST	通話料金分担番号。通常、プレミアムレート番号より低料金です。
VOIP	VoIP電話番号。TSoIP電話番号(Telephony Service over IP)を含みます。
PAGER	ポケットベル番号。通常、音声通話機能はありません。
UAN	代表番号(企業番号)。特定の事業所に転送される場合がありますが、企業全体で1つの番号を使用できます。
VOICEMAIL	ボイスメール番号
UNKNOWN	番号種別を判別できませんでした。

上にスクロール

GET/route保護済み

routeパラメータを指定せずにHLRルックアップを実行した際に自動的に選択されるルートを取得します。

自動ルート選択は、GET /hlr-coverageエンドポイントで取得可能なルーティングマップに基づいており、主にGET /routing-mapから派生しています。ルーティングマップをカスタマイズし、アカウント設定でカスタムルールを定義できます。

リクエスト成功レスポンスエラーレスポンス

curl 'https://www.hlr-lookups.com/api/v2/route?msisdn=+491788735000'

リクエストパラメータ

キー	タイプ	説明	デフォルト	必須
`msisdn`	string	自動選択されたルーティング情報を取得する対象のMSISDN。	null	必須

{
   "route":"V11",
   "confidence_level":"HIGH",
   "mccmnc":"26203",
   "origin":"SCORE"
}

成功レスポンス属性

名前	タイプ	説明	NULL許可
`route`	string	推奨ルート。	false
`confidence_level`	string	このルートが選択された信頼度レベル。`LOW`、`NORMAL`、`HIGH`、`MNP_FALLBACK`のいずれか。	false
`mccmnc`	string	この番号の番号計画ベースのMCCMNC。	false
`origin`	string	ルーティング判定の基準となるオリジン、例: `SCORE`, `CUSTOM_GLOBAL_COUNTRY`, `CUSTOM_GLOBAL_MCCMNC`, `CUSTOM_GLOBAL_PREFIX`, `CUSTOM_USER_COUNTRY`, `CUSTOM_USER_MCCMNC`, `CUSTOM_USER_PREFIX`, `MNP_FALLBACK`, `PLATFORM_DEFAULT`, `USER_DEFAULT`	false

{
    "errors":[
        "Service unavailable."
    ]
}

エラーレスポンスパラメータ

名前	タイプ	説明	NULL許可
`errors[]`	string[]	エラーを説明する文字列のリスト。	false

上にスクロール

GET/routes保護済み

このエンドポイントは、利用可能なHLR、MNP、NTルートのリストを返します。各ルートの機能と制限については、ルーティング詳細ページで説明されています。

リクエスト成功レスポンスエラーレスポンス

curl 'https://www.hlr-lookups.com/api/v2/routes'

{
   "routes":{
      "HLR":[
         "V11",
         "E10",
         "MS9",
         "DV8",
         "SV3",
         "IP1"
      ],
      "MNP":[
         "PTX",
         "IP4"
      ],
      "NT":[
         "LC1"
      ]
   }
}

成功レスポンス属性

名前	タイプ	説明	NULL許可
`routes`	object	ルートタイプ別にグループ化されたルートを含むオブジェクト。	false
`HLR\|MNP\|NT`	string[]	ルート識別子のリストを含みます。	false

{
    "errors":[
        "Service unavailable."
    ]
}

エラーレスポンスパラメータ

名前	タイプ	説明	NULL許可
`errors[]`	string[]	エラーを説明する文字列のリスト。	false

上にスクロール

GET/routing-map保護済み

お客様のアカウントに現在適用されているHLRルックアップの自動ルーティング設定を取得します。このデフォルト設定は、routeパラメータを指定せずにHLRルックアップを送信する際に使用されます。アカウント設定でルーティングマップをカスタマイズし、カスタムルールを作成できます。

設定の階層構造は、国レベルのルールからMCCMNCレベルのルール、そして最終的に個別の電話番号プレフィックスマッピングへと段階的に適用されます。実際には、個別の電話番号プレフィックスマッピングが競合するMCCMNC割り当てより優先され、MCCMNC割り当ては国レベルのルールより優先されます。 MNPフォールバックが有効な場合、競合するカスタムルールより優先されますのでご注意ください。

リクエスト成功レスポンスエラーレスポンス

curl 'https://www.hlr-lookups.com/api/v2/routing-map'

{
   "routing":{
      "map":{
         "defaultRoute":"V11",
         "mnpFallback":true,
         "mccmncs":[
            {
               "mccmnc":20201,
               "countrycode":"GR",
               "route":"E10",
               "mno":"Cosmote",
               "confidence":"HIGH",
               "origin":"SCORE"
            }
         ],
         "prefixes":[
            {
               "countrycode":"DE",
               "cns":"+4917821",
               "route":"DV8",
               "mccmnc":"26203",
               "mno":"O2"
            }
         ],
         "countries":[
            {
               "countrycode":"US",
               "route":"DV8"
            }
         ]
      }
   }
}

成功レスポンス属性

名前	タイプ	説明	NULL許可
`default_route`	string	MSISDNに対して優先ルーティングオプションを決定できず、カスタムルーティングルールも適用されない場合に使用されるデフォルトルートです。	false
`mnp_fallback`	boolean	MNPフォールバックが有効かどうかを示します。有効な場合、ネットワークでHLRクエリがサポートされていない(接続ステータスが利用不可)ときに、システムは代わりにMNPルックアップを実行します。	false
`mccmncs`	array	MCCMNCコードと自動選択されたルートのマッピングです。特定のMCCMNCの番号に対してHLRルックアップを実行する際、対応するルートが使用されます。	false
`mccmnc`	string(5\|6)	携帯電話事業者を識別する5文字または6文字のMCCMNC(移動体国コードと移動体ネットワークコードの組み合わせ)。	false
`countrycode`	string(2)	ネットワークの国を識別する2文字のISO国コードです。	false
`route`	string(3)	ネットワークに対して選択されたルートです。	false
`mno`	string	このネットワークが運営される消費者向けブランド名。	false
`confidence`	string	選択が行われた信頼度レベルです。可能な値は、HIGH、NORMAL、LOW、MNP_REDIRECTです。MNP_REDIRECTの場合、この動作がアカウントで有効になっていれば、システムはこのネットワークへのトラフィックをMNPにリダイレクトします。そうでない場合は、アカウントのデフォルトルートを使用します。	false
`origin`	string	選択の基準となる起点です。可能な値は`SCORE`, `CUSTOM_GLOBAL_COUNTRY`, `CUSTOM_GLOBAL_MCCMNC`, `CUSTOM_GLOBAL_PREFIX`, `CUSTOM_USER_COUNTRY`, `CUSTOM_USER_MCCMNC`, `CUSTOM_USER_PREFIX`, `MNP_FALLBACK`, `PLATFORM_DEFAULT`, `USER_DEFAULT`です。	false
`prefixes`	array	アカウントに設定されているカスタムプレフィックスベースのルーティングルールのリストです(存在する場合)。	false
`countrycode`	string(2)	プレフィックスの国を識別する2文字のISO国コードです。	false
`cns`	string	ルーティングルールが適用されるプレフィックスです。	false
`route`	string(3)	プレフィックスに対して選択されたルートです。	false
`mccmnc`	string(5\|6)	携帯電話事業者を識別する5文字または6文字のMCCMNC(移動体国コードと移動体ネットワークコードの組み合わせ)。	true
`mno`	string	このネットワークが運営される消費者向けブランド名。	true
`countries`	array	アカウントに設定されているカスタム国ベースのルールのリストです(存在する場合)。	false
`countrycode`	string(2)	国を識別する2文字のISO国コードです。	false
`route`	string(3)	国に対して選択されたルートです。	false

{
    "errors":[
        "Service unavailable."
    ]
}

エラーレスポンスパラメータ

名前	タイプ	説明	NULL許可
`errors[]`	string[]	エラーを説明する文字列のリスト。	false

上にスクロール

GET/hlr-coverage 保護済み

データに基づいた意思決定を支援するHLRカバレッジインサイトを返します。このエンドポイントは、モバイルネットワーク全体のリアルタイムHLRルーティングオプションの分析、ターゲット地域に最適なパスの特定、自動ルーティングの設定をサポートします。

GET /routeからの推奨ルートは、ここで取得されたカバレッジデータに基づいています。カバレッジデータはネットワークカバレッジページでもご確認いただけます。アカウント設定でルーティングマップをさらにカスタマイズし、ルールを定義できます。

結果の解釈に役立つこちらのガイドをご確認いただくことをお勧めします。

リクエスト成功レスポンスエラーレスポンスステータスリファレンス

curl 'https://www.hlr-lookups.com/api/v2/hlr-coverage?countrycode=XX'

リクエストパラメータ

キー	タイプ	説明	デフォルト	必須
`countrycode`	string(2)	結果をフィルタリングするために使用される必須の2文字のISO国コードで、指定された国に関連するレコードのみを返します。	null	必須
`sample_size`	string	サンプルサイズを指定するオプションパラメータです。指定可能な値は`LARGE`、`MEDIUM`、`SMALL`です。サンプルサイズが大きいほど長期間をカバーし、小さいほど直近の期間をカバーします。	LARGE	任意

{
   "name":"Germany",
   "countrycode":"DE",
   "prefix":"+49",
   "mccs":[
      "262"
   ],
   "carriers":[
      {
         "mno":"Telekom",
         "mccmnc":"26201",
         "mcc":"262",
         "mnc":"01 ",
         "routes":[
            {
               "route":"V11",
               "selected":true,
               "selection_confidence":"HIGH",
               "n":361579,
               "CONNECTED":275273,
               "CONNECTED_PCT":76.13,
               "ABSENT":21529,
               "ABSENT_PCT":5.95,
               "INVALID_MSISDN":62582,
               "INVALID_MSISDN_PCT":17.3,
               "UNDETERMINED":2195,
               "UNDETERMINED_PCT":0.6
            },
            {
               "route":"E10",
               "selected":false,
               "selection_confidence":null,
               "n":122600,
               "CONNECTED":13721,
               "CONNECTED_PCT":11.19,
               "ABSENT":133,
               "ABSENT_PCT":0.1,
               "INVALID_MSISDN":55,
               "INVALID_MSISDN_PCT":0.04,
               "UNDETERMINED":108691,
               "UNDETERMINED_PCT":88.65
            }
         ]
      }
   ]
}

成功レスポンス属性

名前	タイプ	説明	NULL許可
`name`	string	選択された国の英語名(プレーンテキスト)。	false
`countrycode`	string(2)	選択された国の2文字のISO国コード。	false
`prefix`	string	選択された国の国際ダイヤルプレフィックス。	false
`mccs`	string[]	選択された国に関連付けられたMCC(モバイル国コード)のリスト。	false
`carriers`	object[]	ルート固有の接続メトリクスを含むキャリアオブジェクトのリスト。	false
`mno`	string	モバイルネットワークオペレーターの英語名(プレーンテキスト)。	false
`mccmnc`	string	モバイルネットワークオペレーターのMCCMNC。	false
`mcc`	string	モバイルネットワークオペレーターのMCC(モバイル国コード)。	false
`mnc`	string	モバイルネットワークオペレーターのMNC(モバイルネットワークコード)。	false
`routes`	object[]	ルート固有の接続結果のリスト。	false
`route`	string	接続情報が適用されるルート。	false
`selected`	bool	自動ルーティングで選択されたルートであるかどうかを示します。	false
`selection_confidence`	string	このルートが選択された信頼度レベル。`LOW`、`NORMAL`、`HIGH`、`MNP_FALLBACK`のいずれか。選択されたルートでない場合はnullを含みます。	true
`n`	int	このサンプル内のルックアップの総数。	false
`CONNECTED`	int	CONNECTEDステータスを返したHLRルックアップの数。	false
`CONNECTED_PCT`	float	CONNECTEDステータスを返したHLRルックアップの割合。	false
`ABSENT`	int	ABSENTステータスを返したHLRルックアップの数。	false
`ABSENT_PCT`	float	ABSENTステータスを返したHLRルックアップの割合。	false
`INVALID_MSISDN`	int	INVALID_MSISDNステータスを返したHLRルックアップの数。	false
`INVALID_MSISDN_PCT`	float	INVALID_MSISDNステータスを返したHLRルックアップの割合。	false
`UNDETERMINED`	int	UNDETERMINEDステータスを返したHLRルックアップの数。	false
`UNDETERMINED_PCT`	float	UNDETERMINEDステータスを返したHLRルックアップの割合。	false

{
    "errors":[
        "Service unavailable."
    ]
}

エラーレスポンスパラメータ

名前	タイプ	説明	NULL許可
`errors[]`	string[]	エラーを説明する文字列のリスト。	false

ステータス	説明
CONNECTED	番号は有効で、対象端末は現在モバイルネットワークに接続されています。通話、SMS、その他のサービスは正常に受信者に届きます。
ABSENT	番号は有効ですが、対象端末は電源がオフになっているか、一時的にネットワーク圏外にあります。端末がネットワークに再接続するまで、メッセージや通話が配信されない可能性があります。
INVALID_MSISDN	番号が無効であるか、モバイルネットワーク上のいずれの加入者にも現在割り当てられていません。この番号への通話やメッセージは失敗します。
UNDETERMINED	番号の接続状態を判定できませんでした。無効な番号、SS7エラー応答、または対象ネットワーク事業者との接続不足が原因である可能性があります。追加の診断情報については、エラーコードとその説明フィールドを確認してください。

上にスクロール

GET/mnp-coverage保護済み

このエンドポイントは、モバイル番号ポータビリティ検索で現在サポートされている携帯電話事業者のリストと、対応するMCCMNC識別子を返します。

リクエスト成功レスポンスエラーレスポンス

curl 'https://www.hlr-lookups.com/api/v2/mnp-coverage?countrycode=XX'

リクエストパラメータ

キー	タイプ	説明	デフォルト	必須
`countrycode`	string(2)	MCCMNCの結果をフィルタリングするために使用されるオプションの2文字ISO国コードで、指定された国に関連するデータのみを返します。	null	任意

{
   "items":[
      {
         "country_name":"Germany",
         "country_code":"DE",
         "mccmnc":"26201",
         "mcc":"262",
         "mnc":"01 ",
         "brand":"Telekom",
         "operator":"Telekom Deutschland GmbH"
      },
      {
         "country_name":"Germany",
         "country_code":"DE",
         "mccmnc":"26202",
         "mcc":"262",
         "mnc":"02 ",
         "brand":"Vodafone",
         "operator":"Vodafone D2 GmbH"
      }
}

成功レスポンス属性

名前	タイプ	説明	NULL許可
`items[]`	array	モバイルネットワーク事業者のリスト。	false
`country_name`	string	英語表記の国名。	false
`country_code`	string(2)	2文字のISO国コード。	false
`mccmnc`	string(5\|6)	携帯電話事業者を識別する5文字または6文字のMCCMNC(移動体国コードと移動体ネットワークコードの組み合わせ)。	false
`mcc`	string(3)	ネットワークの国を表す3文字のMCC(移動体国コード)。	false
`mnc`	string(2\|3)	特定の携帯電話事業者を表す2文字または3文字のMNC(移動体ネットワークコード)。	false
`brand`	string	このネットワークが運営される消費者向けブランド名。	true
`operator`	string	携帯電話事業者の法的名称。	true

{
    "errors":[
        "Service unavailable."
    ]
}

エラーレスポンスパラメータ

名前	タイプ	説明	NULL許可
`errors[]`	string[]	エラーを説明する文字列のリスト。	false

上にスクロール

GET/price-list保護済み

このエンドポイントは、MNPルックアップのみがサポートされ、HLRクエリが利用できない国のリストを返します。

リクエスト成功レスポンスエラーレスポンス

curl 'https://www.hlr-lookups.com/api/v2/mnp-countries'

{
   "countries":[
      "AG",
      "AI",
      "AR",
      "AS",
      "AW",
      "BB",
      "BM",
      ...
      "US",
      "UY",
      "VC",
      "VE",
      "VG",
      "VN"
   ]
}

成功レスポンス属性

名前	タイプ	説明	NULL許可
`countries`	string[]	2文字のISO国コードのリスト。	false

{
    "errors":[
        "Service unavailable."
    ]
}

エラーレスポンスパラメータ

名前	タイプ	説明	NULL許可
`errors[]`	string[]	エラーを説明する文字列のリスト。	false

上にスクロール

GET/mccmncs保護済み

このエンドポイントは、モバイルネットワーク事業者の包括的なリストと、対応するMCCMNC識別子および追加のコンテキスト情報を返します。

リクエスト成功レスポンスエラーレスポンス

curl 'https://www.hlr-lookups.com/api/v2/mccmncs?countrycode=XX'

リクエストパラメータ

キー	タイプ	説明	デフォルト	必須
`countrycode`	string(2)	MCCMNC結果をフィルタリングするために使用されるオプションの2文字のISO国コードで、指定された国に関連付けられたレコードのみを返します。	null	任意

{
   "items":[
      {
         "country_name":"Germany",
         "country_code":"DE",
         "mccmnc":"26201",
         "mcc":"262",
         "mnc":"01 ",
         "brand":"Telekom",
         "operator":"Telekom Deutschland GmbH"
      },
      {
         "country_name":"Germany",
         "country_code":"DE",
         "mccmnc":"26202",
         "mcc":"262",
         "mnc":"02 ",
         "brand":"Vodafone",
         "operator":"Vodafone D2 GmbH"
      }
}

成功レスポンス属性

名前	タイプ	説明	NULL許可
`items`	object[]	モバイルネットワーク事業者のリスト。	false
`country_name`	string	英語での完全な国名。	false
`country_code`	string(2)	モバイル事業者の国を表す2文字のISO国コード。	false
`mccmnc`	string(5\|6)	モバイルネットワーク事業者を一意に識別する5文字または6文字のMCCMNC文字列。	false
`mcc`	string(3)	モバイルネットワークが運営されている国を識別する3文字のモバイル国コード(MCC)。	false
`mnc`	string(2\|3)	指定されたMCC内のモバイルネットワークを特定する2文字または3文字のモバイルネットワークコード(MNC)。	false
`brand`	string	ネットワークが運営され、消費者に認識される商業ブランド名。	true
`operator`	string	モバイルネットワーク事業者の正式名称。通常、ネットワークを管理する法人。	true
`parent_mccmnc`	string(5\|6)	親モバイルネットワーク事業者のMCCMNCを表す5文字または6文字の文字列(存在する場合)。	true

{
    "errors":[
        "Service unavailable."
    ]
}

エラーレスポンスパラメータ

名前	タイプ	説明	NULL許可
`errors[]`	string[]	エラーを説明する文字列のリスト。	false

上にスクロール

GET/price保護済み

このエンドポイントは、HLR、MNP、またはNT照会の料金を返します。

リクエスト成功レスポンスエラーレスポンス

curl 'https://www.hlr-lookups.com/api/v2/price?msisdn=+491788735000&route_type=HLR'

リクエストパラメータ

キー	タイプ	説明	デフォルト	必須
`msisdn`	string	料金を取得する電話番号。国際形式で指定してください。	null	必須
`route_type`	string	ルートタイプ。`HLR`、`MNP`、`NT`のいずれかを指定します。	null	必須
`route`	string(3)	料金を計算するルート。デフォルトでは自動ルーティングで決定されたルートが使用されます。	null	任意

{
   "price":{
      "amount":"0.01000",
      "msisdn":"+491788735000",
      "route_type":"HLR",
      "route":"DV8"
   }
}

成功レスポンス属性

名前	タイプ	説明	NULL許可
`price`	object	料金詳細を含むオブジェクト。	false
`amount`	string	ユーロ建ての金額。	false
`msisdn`	string	この料金が適用されるMSISDN。	false
`route_type`	string(2\|3)	この料金が適用されるルートタイプ。	false
`route`	string(3)	この料金が適用されるルート。	false

{
    "errors":[
        "Service unavailable."
    ]
}

エラーレスポンスパラメータ

名前	タイプ	説明	NULL許可
`errors[]`	string[]	エラーを説明する文字列のリスト。	false

上にスクロール

GET/price-list保護済み

このエンドポイントは、お客様のアカウントの料金情報を返します。

リクエスト成功レスポンスエラーレスポンス

curl 'https://www.hlr-lookups.com/api/v2/price-list'

{
   "pricing":[
      {
         "route":"V11",
         "countrycode":null,
         "countryname":null,
         "mccmnc":null,
         "cns":null,
         "route_type":"HLR",
         "price":"0.0090"
      },
      {
         "route":"V11",
         "countrycode":"DE",
         "countryname":"Germany",
         "mccmnc":"26201",
         "cns":null,
         "route_type":"HLR",
         "price":"0.0070"
      },
      {
         "route":"V11",
         "countrycode":"DE",
         "countryname":"Germany",
         "mccmnc":"26203",
         "cns":"4917821",
         "route_type":"HLR",
         "price":"0.0070"
      },
      {
         "route":"V11",
         "countrycode":"DE",
         "countryname":"Germany",
         "mccmnc":null,
         "cns":null,
         "route_type":"HLR",
         "price":"0.0070"
      },
      {
         "route":"PTX",
         "countrycode":null,
         "countryname":null,
         "mccmnc":null,
         "cns":null,
         "route_type":"MNP",
         "price":"0.00500"
      },
      ...
      {
         "route":"IP1",
         "countrycode":null,
         "countryname":null,
         "mccmnc":null,
         "cns":null,
         "route_type":"MIX",
         "price":"0.01000"
      },
      {
         "route":"LC1",
         "countrycode":null,
         "countryname":null,
         "mccmnc":null,
         "cns":null,
         "route_type":"NT",
         "price":"0.00500"
      }
   ]
}

成功レスポンス属性

名前	タイプ	説明	NULL許可
`pricing`	object[]	料金情報を含むオブジェクトのリスト。	false
`route`	string	この料金が適用されるルート。	false
`countrycode`	string	対応するルートにおいて、この料金が適用される2文字のISO国コード(該当する場合)。	true
`countryname`	string	国コードに対応する英語の国名(該当する場合)。	true
`mccmnc`	string	対応するルートにおいて、この料金が適用されるMCCMNC(該当する場合)。国レベルの料金を上書きします。	true
`cns`	string	対応するルートにおいて、この料金が適用されるダイヤルプレフィックス(該当する場合)。国レベルの料金およびMCCMNCレベルの料金を上書きします。	true
`route_type`	string	対応するルートタイプ(`HLR`、`MNP`、`NT`)。	false
`route_type`	string	対応する料金(EUR)。	false

{
    "errors":[
        "Service unavailable."
    ]
}

エラーレスポンスパラメータ

名前	タイプ	説明	NULL許可
`errors[]`	string[]	エラーを説明する文字列のリスト。	false

上にスクロール

GET/balance保護済み

このエンドポイントは現在のアカウント残高を取得し、クレジット状況に基づいてプロセスを自動化できます。お支払いページで設定可能な残高不足通知メールとシームレスに連携します。

リクエスト成功レスポンスエラーレスポンス

curl 'https://www.hlr-lookups.com/api/v2/balance'

{
    "balance":"1002.90"
}

成功レスポンス属性

名前	タイプ	説明	NULL許可
`balance`	string	現在のアカウント残高(EUR)。文字列型の小数値です。	false

{
    "errors":[
        "Service unavailable."
    ]
}

エラーレスポンスパラメータ

名前	タイプ	説明	NULL許可
`errors[]`	string[]	エラーを説明する文字列のリスト。	false

上にスクロール

GET/ping公開

このエンドポイントはAPIにpingリクエストを送信し、HLR Lookups APIへの接続をテストするシンプルな方法を提供します。

リクエスト成功レスポンスエラーレスポンス

curl 'https://www.hlr-lookups.com/api/v2/ping'

{
    "success":true
}

成功レスポンス属性

名前	タイプ	説明	NULL許可
`success`	boolean	リクエストが正常に処理されたことを示します。	false

{
    "errors":[
        "Service unavailable."
    ]
}

エラーレスポンスパラメータ

名前	タイプ	説明	NULL許可
`errors[]`	string[]	エラーを説明する文字列のリスト。	false

上にスクロール

GET/time公開

このエンドポイントは、HLR Lookupsサーバーの現在時刻を表すUnixタイムスタンプを返します。認証用のDigest-Auth署名を生成する際に、お客様のサーバーの時刻を同期するために使用してください。これにより、お客様のサーバー時刻とHLR Lookupsサーバー時刻の間の差異が修正されます。

リクエスト成功レスポンスエラーレスポンス

curl 'https://www.hlr-lookups.com/api/v2/time'

{
    "time":1525898643
}

成功レスポンス属性

名前	タイプ	説明	NULL許可
`time`	integer	HLR Lookupsサーバーの現在時刻を表すUnixタイムスタンプ。	false

{
    "errors":[
        "Service unavailable."
    ]
}

エラーレスポンスパラメータ

名前	タイプ	説明	NULL許可
`errors[]`	string[]	エラーを説明する文字列のリスト。	false

上にスクロール

GET/auth-test保護済み

このエンドポイントは、Basic-Authまたは推奨されるDigest-Authの実装を検証するための初期テストとして機能します。

ベーシック認証リクエストダイジェスト認証リクエスト成功レスポンスエラーレスポンス

curl 'https://www.hlr-lookups.com/api/v2/auth-test' \
  -H "X-Basic: YOUR_API_KEY"

リクエストヘッダー

キー	タイプ	説明
`X-Basic`	string	`YOUR_API_KEY:YOUR_API_SECRET`のSHA256ハッシュ。ハッシュにコロン記号(:)を含めてください。

curl 'https://www.hlr-lookups.com/api/v2/auth-test' \
  -H "X-Digest-Key: YOUR_API_KEY" \
  -H "X-Digest-Signature: DIGEST_AUTH_SIGNATURE" \
  -H "X-Digest-Timestamp: UNIX_TIMESTAMP"

リクエストヘッダー

キー	タイプ	説明
`X-Digest-Key`	string	HLR Lookups APIキー
`X-Digest-Signature`	string	一意のダイジェスト認証署名(認証を参照)
`X-Digest-Timestamp`	integer	現在のUnixタイムスタンプ(`GET /time`も参照)

{
    "success":true
}

成功レスポンス属性

名前	タイプ	説明	NULL許可
`success`	boolean	リクエストが正常に処理されたことを示します。	false

{
    "errors":[
        "Service unavailable."
    ]
}

エラーレスポンスパラメータ

名前	タイプ	説明	NULL許可
`errors[]`	string[]	エラーを説明する文字列のリスト。	false

上にスクロール

レガシーAPIドキュメント

レガシーAPIは非推奨となっており、将来的に廃止予定です。できるだけ早く最新バージョンへのアップグレードを強くお勧めいたします。

2013年から2020年初頭の間に当社のHLR Lookups APIを実装された場合は、レガシーAPIをご利用いただいております。その場合はレガシーAPIドキュメントをご参照ください。

レガシーAPIドキュメント

APIドキュメント

はじめに

HLR検索

MNP検索

NT検索

ルーティング

料金

ツール

はじめに

HLR Lookups APIの使用方法

リクエスト例

ペイロード例

成功レスポンス application/json

追加のルックアップサービス

モバイル番号ポータビリティ(MNP)ルックアップ

番号タイプ検出(NT)ルックアップ

ソフトウェア開発キット(SDK)

ツール

開発者ではありませんか?

認証

APIキーとAPIシークレット

HTTPベーシック認証

推奨: SHA256を使用したX-Basicヘッダー

ベーシック認証リクエスト

ベーシック認証ヘッダー

コード例

リクエスト例

リクエストヘッダー

署名の構築

ダイジェスト署名コンポーネント

コード例

コンセプト

同期HLRルックアップAPI

非同期HLR検索API

SDK（ソフトウェア開発キット）

PHP SDK

NodeJS SDK

Ruby SDK

POST/hlr-lookup保護済み

ペイロード

リクエストパラメータ

成功レスポンス属性

エラーレスポンスパラメータ

POST/hlr-lookups保護済み

ペイロード

リクエストパラメータ

成功レスポンス属性

エラーレスポンスパラメータ

Webhookの処理

認証

コード例

受信確認

Webhookペイロード

Webhookペイロード属性

POST/mnp-lookup保護済み

ペイロード

リクエストパラメータ

成功レスポンス属性

エラーレスポンスパラメータ

POST/mnp-lookups保護済み

ペイロード

リクエストパラメータ

成功レスポンス属性

エラーレスポンスパラメータ

Webhookの処理

認証

コード例

受信確認

Webhookペイロード

Webhookペイロード属性

POST/nt-lookup保護済み

ペイロード

リクエストパラメータ

成功レスポンス属性

エラーレスポンスパラメータ

POST/nt-lookups 保護済み

ペイロード

リクエストパラメータ

成功レスポンス属性

エラーレスポンスパラメータ