電話番号の検証およびフォーマットAPI

電話番号検証APIは242の国と地域でサポートされています。

電話番号の検証およびフォーマットAPIを使用すると、ユーザーがさまざまな形式で入力した電話番号を簡単に処理できます。たとえば、1(212)-867-53-09、+1 212 8675309、001-212.867.5309、または単に2128675309のように不規則な形式でも、当APIは構造をインテリジェントに検出し、標準化された形式に変換します。

このツールは、入力を自動的にE.164形式に変換します。これは国際電話番号の標準形式です。たとえば、+1 212 867 5309は+12128675309として返され、国際的な通話システムや統合に適しています。

フォーマットだけでなく、APIは詳細な電話番号検証機能も提供します。番号がisValid: true（国内の番号計画に従って有効）かどうかをチェックし、isPossible: true（現時点で割り当てられていなくても存在する可能性があるか）も判定します。これは、保存や処理前の事前検証に役立ちます。

numberTypeパラメータにより、電話番号が携帯電話、固定電話、またはVoIPかを識別できます。SMS認証では携帯電話番号のみを許可したい場合や、オフィス連絡先では固定電話のみを使用したい場合などに役立ちます。

市外局番認識をサポートしており、APIは電話番号の地理的な由来も特定できます。たとえば、212で始まる番号はニューヨーク市（マンハッタン）に自動的にマッピングされます。この機能は、位置情報に基づくセグメンテーションや分析に最適です。

各電話番号には、ISO地域コード（例：US）や数値の国コード（例：1）などの国レベルの詳細メタデータも付随しており、アプリケーション内で地域ごとのロジックや表示形式を実現できます。

✅ APIレスポンス

JSONレスポンス例：

{
  "status": true,
  "remaining_credits": 15709,
  "expires": 0,
  "duration": "18ms",
  "regionCode": "US",
  "countryCode": 1,
  "country": "Unites States",
  "national": "(212) 867-5309",
  "international": "+1 212-867-5309",
  "e164": "+12128675309",
  "isValid": true,
  "isPossible": true,
  "numberType": "FIXED_LINE_OR_MOBILE",
  "nationalSignificantNumber": "2128675309",
  "rawInput": "+1 212 867 5309",
  "isGeographical": true,
  "areaCode": "212",
  "location": "New York City (Manhattan)"
}

電話番号検証APIを試してみる

基本的な使い方

次のエンドポイントに電話番号を送信してください：

https://api.genderapi.io/api/phone?key=YOUR_API_KEY&number=12128675309

こちらのリンクから1日200クレジット付きの無料APIキーを取得できます。

アドレスパラメータ

APIは、addressというオプションのパラメータもサポートしており、国際電話コードが含まれていない電話番号を処理する場合に非常に役立ちます。このフィールドを使うことで、想定される地域をシステムが判定し、正確に番号を解析できます。たとえば、入力が2128675309で、国コードが指定されていない場合、address=US、address=United States、またはaddress=New Yorkを指定することで、APIはその番号がアメリカ合衆国に属すると判断します。

addressパラメータは、以下のような形式に対応しています：

• ISO 3166-1 alpha-2コード（例：US、DE、TR）
• Germany、Turkey、Americaのような国名
• Berlin、Istanbul、New Yorkなどの都市名または地域名

addressパラメータは任意ですが、電話番号が国際電話コード（例：+1、+44、+90）で始まっていない場合は必須となります。この文脈情報がないと、APIは国内番号形式を正しく解釈できない可能性があります。

アドレスパラメータ付きの例：

https://api.genderapi.io/api/phone?key=YOUR_API_KEY&number=12128675309&address=US

レスポンスフィールド

番号タイプの値

curl "https://api.genderapi.io/api/phone?number=+49 151 12345678&address=United States&key=YOUR_API_KEY"

curl "https://api.genderapi.io/api/phone?number=%2B49%20151%2012345678&address=United%20States&key=YOUR_API_KEY"

POSTリクエストによる電話番号検証API

POSTメソッドを使用して、アメリカの電話番号を検証できます。
E.164形式、国内形式、または国際形式の電話番号とともに、国名/住所を指定するだけです。
APIキーはBearerトークンとして送信する必要があります。

cURLの例

curl -X POST "https://api.genderapi.io/api/phone" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"number": "+12128675309", "address": "US"}'

PHP cURLの例

<?php
$url = "https://api.genderapi.io/api/phone";

$data = array(
    "number" => "+12128675309",
    "address" => "US"
);

$payload = json_encode($data);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    "Content-Type: application/json",
    "Authorization: Bearer YOUR_API_KEY"
));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

JavaScript fetch の例

fetch("https://api.genderapi.io/api/phone", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
  },
  body: JSON.stringify({
    number: "+12128675309",
    address: "United States"
  })
})
.then(response => response.json())
.then(data => console.log(data));

Python requests の例

import requests

url = "https://api.genderapi.io/api/phone"

payload = {
    "number": "+12128675309",
    "address": "United States"
}

headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
}

response = requests.post(url, headers=headers, json=payload)

print(response.json())

クライアントライブラリ

統合をより簡単にするために、さまざまなプログラミング言語向けの公式およびコミュニティ提供のクライアントライブラリを用意しています。
これらのライブラリを使用すれば、Phone Number Validation APIなどのGenderAPIエンドポイントとやり取りする際に、HTTPリクエストやJSON解析を手動で行う必要はありません。
環境に合ったライブラリを選択し、インストールするだけで、簡単にリクエストを実行できます。

利用可能なクライアントライブラリとインストール手順は以下のページで確認できます：
https://www.genderapi.io/ja/docs-client-libraries

よくある質問（FAQ）

1. Phone Number Validation & Formatter APIとは？

世界中の電話番号を検証、フォーマット、および解析できるツールです。番号をE.164の標準形式に変換し、地域、タイプ（携帯/固定）、有効性などのメタデータを特定できます。

2. このAPIは何に使われますか？

電話番号が有効かどうかのチェック、国際利用向けのフォーマット、番号タイプの識別（例：モバイル、VoIP）、地域メタデータの検出、CRMやマーケティング、ユーザー登録などでのクリーンな電話番号入力に使用されます。

3. 何カ国に対応していますか？

このAPIは242の国と地域の電話番号をサポートしています。国際的または地域的なアプリケーションにも対応可能です。

4. どのフォーマットに対応していますか？

国内形式、国際形式、E.164形式など、さまざまな形式の番号を受け付け、自動的に正しい形式に変換します。

5. 国または住所パラメータを省略するとどうなりますか？

電話番号が「+」で始まらず、かつaddressパラメータが指定されていない場合、APIは番号を正しく解釈できない可能性があります。US、United States、New Yorkなどのaddressパラメータの指定を推奨します。

6. 番号タイプの検出は可能ですか？

はい。APIはnumberTypeフィールドを返し、MOBILE、FIXED_LINE、VOIPなどを示します。

7. isValidとisPossibleの違いは？

isValidはその番号が正式に割り当てられ、地域のルールに準拠していることを意味します。isPossibleはその番号構造が理論上は存在可能かを示し、まだ割り当てられていない場合も含みます。

8. APIレスポンスの内容は？

成功したレスポンスには、ステータス、フォーマット済みの番号（国内・国際・E.164）、地域情報、番号タイプ、クレジット使用量などが含まれます。詳細は「APIレスポンス例」セクションをご覧ください。

9. APIキーの送信方法は？

GETリクエストでは、?key=YOUR_API_KEYとしてURLに追加します。
POSTリクエストでは、ヘッダーにBearerトークン形式で送信します：
"Authorization: Bearer YOUR_API_KEY"

10. status: false が返された場合は？

リクエストが失敗したことを意味します。messageフィールドに、パラメータ不足・無効な電話番号・クレジット不足などのエラー理由が記載されます。

11. 入力に特殊文字やスペースを含めても良いですか？

はい、ただしGETリクエストではURLエンコードが必要です。たとえばスペースは%20に置き換える必要があります。正しい使用法については上記の警告セクションをご覧ください。

12. 異なる形式や言語で住所を指定できますか？

はい。addressパラメータは、US、DE、TRなどのISO 3166-1 alpha-2コードに加え、国名や都市名（異なる言語も含む）も受け付けます。
APIは内蔵AIを用いて適切な国や地域をインテリジェントに解釈します。例：

address=Deutschland
address=États-Unis
address=İstanbul
address=New York
address=Estados Unidos

これらの入力はすべて、問題なくそれぞれの国や地域に正しくマッピングされます。