電話番号検証API

GET

電話番号検証API

curl --request GET \
  --url https://phonevalidation.cleariflow.com/v1

import requests

url = "https://phonevalidation.cleariflow.com/v1"

response = requests.get(url)

print(response.text)

const options = {method: 'GET'};

fetch('https://phonevalidation.cleariflow.com/v1', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://phonevalidation.cleariflow.com/v1",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://phonevalidation.cleariflow.com/v1"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://phonevalidation.cleariflow.com/v1")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://phonevalidation.cleariflow.com/v1")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

{
  "phone": "14155552671",
  "valid": true,
  "possible": true,
  "format": {
    "international": "+14155552671",
    "local": "(415) 555-2671"
  },
  "country": {
    "code": "US",
    "name": "United States",
    "prefix": "+1"
  },
  "location": "San Francisco, CA",
  "type": "Landline_or_Mobile",
  "carrier": "",
  "carrier_display": "",
  "timezones": ["America/Los_Angeles"],
  "geographical": true,
  "internationally_dialable": true
}

使い方は簡単です。API キーと電話番号を送信するだけです。API は番号が 構造的に有効かを返し、有効な場合は正規化された E.164 形式と、回線種別・ジオコーディング・キャリア・タイムゾーン・ダイヤル可否などのメタデータを返します。

valid: true は、番号が地域の書式ルール（桁数、プレフィックス、構文）に一致することを意味します。回線がアクティブであること、加入者に割り当てられていること、到達可能であることは確認しません。リアルタイムの回線状態には carrier lookup が必要で、これは本 API の範囲外です。

はじめに

REST

電話番号検証 API は、他のすべての Cleariflow API と同様に REST を基盤としています。予測可能なリソース指向の URL と HTTP ステータスコードでエラーを示すよう設計されています。

HTTPS

電話番号検証 API では、すべての通信を TLS 1.2 以上で保護する必要があります。

API バージョン

すべての Cleariflow API はバージョン管理されています。電話番号検証 API は現在バージョン 1 です。

API キー

API キーは Cleariflow 電話番号検証 API への認証用の固有キーです。各 Cleariflow API には固有の API キーがあるため、たとえば電話番号検証とメール検証では異なるキーが必要です。リクエストを認証するには、API キーをベース URL に付加してください。

ベース URL

https://phonevalidation.cleariflow.com/v1/

`valid` の意味

`valid`	意味
`true`	検出された地域に対して番号が構造的に有効（）。
`false`	番号を解析できないか、地域のフォーマット規則に適合しません。`valid` が false のとき `format`、`country`、`location`、`type`、`carrier`、`carrier_display`、`timezones`、`geographical`、`internationally_dialable` は常に空または false です。入力を解析できた場合は `possible` と `invalid_reason` が返されます。`phone` には入力の数字のみが含まれます。

架空の米国 555 番号や、その他構造的に有効だが未割り当ての番号帯でも valid: true が返る場合があります。carrier と location は主に US/CA のメタデータから入力され、他の地域では多くの場合空です。

検証エンドポイント

API には固有の API キーと検証する電話番号が必要です：

https://phonevalidation.cleariflow.com/v1/
? api_key = YOUR_UNIQUE_API_KEY
& phone = 14155552671
& country = US

有効なレスポンス（phone=14155552671、country=US）：

{
  "phone": "14155552671",
  "valid": true,
  "possible": true,
  "format": {
    "international": "+14155552671",
    "local": "(415) 555-2671"
  },
  "country": {
    "code": "US",
    "name": "United States",
    "prefix": "+1"
  },
  "location": "San Francisco, CA",
  "type": "Landline_or_Mobile",
  "carrier": "",
  "carrier_display": "",
  "timezones": ["America/Los_Angeles"],
  "geographical": true,
  "internationally_dialable": true
}

無効なレスポンス（phone=123、country=US）：

{
  "phone": "123",
  "valid": false,
  "possible": false,
  "invalid_reason": "too_short",
  "format": {
    "international": "",
    "local": ""
  },
  "country": {
    "code": "",
    "name": "",
    "prefix": ""
  },
  "location": "",
  "type": "Unknown",
  "carrier": "",
  "carrier_display": "",
  "timezones": null,
  "geographical": false,
  "internationally_dialable": false
}

リクエストパラメータ

api_key

String

必須

固有の API キー。各ユーザーは Cleariflow API ごとに固有の API キーを持つため、たとえば Phone Validation のキーは IP ジオロケーション API では動作しません。

phone

String

必須

検証する電話番号。

country

String

先頭に + のない国内形式番号向けの任意の ISO 3166-1 alpha-2 ヒント。たとえば country=US は 4155552671 の解析に役立ちます。国際プレフィックス付きの番号は国コードから解析されます。レスポンスの検出された country.code はこのヒントと異なる場合があります（例：一部の +44 モバイル帯で GG）。

レスポンスパラメータ

API レスポンスは汎用的で軽量な JSON 形式で返されます。

phone

String

valid が true のとき、正規化された E.164 桁（+ なし）。valid が false のときは入力の数字のみ。

valid

Boolean

番号が構造的に有効なとき true。これは回線状態や加入者の検証ではありません。

possible

Boolean

緩い桁数チェック（）。valid が false でも、桁数と数字が実在番号に該当しうる場合は true。

invalid_reason

String

valid が false のときに返されます。not_a_number、possible、possible_local_only、invalid_country_code、too_short、invalid_length、too_long、unknown のいずれか。valid が true のときは省略。

format

Object

international と local 形式。valid が false のときは空文字列。

format.international

String

先頭に + がある E.164 形式。valid が false のときは空。

format.local

String

検出された地域の国内形式。valid が false のときは空。

country

Object

検出された国/地域。valid が false のときはフィールドが空。

country.code

String

検出された地域の 2 文字 ISO 3166-1 alpha-2 コード。

country.name

String

country.code の英語表示名。

country.prefix

String

国際電話番号の国番号（例：+1）。

location

String

ジオコーディングヒント（地域、州/県、または都市）。US/CA 以外では多くの場合空。valid が false のときは空。

type

String

valid が true のときの回線種別：Landline、Mobile、Landline_or_Mobile、Toll_Free、Premium、Paging、Special、または Unknown。valid が false のときは常に Unknown。

carrier

String

利用可能な場合のキャリア名（最も多いのは US/CA）。それ以外は空文字列。valid が false のときも含む。

carrier_display

String

エンドユーザー向けの安全なキャリア名（有効な番号で MNP 非対応地域の場合）。valid が false、または安全に表示できない場合は空。

timezones

Array

番号に対応するタイムゾーン ID（例: America/New_York）。valid が true でマッピングがない場合は空配列、valid が false の場合は null。

geographical

Boolean

番号が地理的な地域に紐づくか。valid が false のときは常に false。

internationally_dialable

Boolean

自地域外からダイヤル可能か。valid が false のときは常に false。

一括アップロード（CSV）

CSV ファイルを一括アップロードする際のベストプラクティス：

最初の列に分析する電話番号が含まれていることを確認してください。
ファイルから空行を削除してください。
1 行に 1 つの電話番号のみを含めてください。
許可される最大ファイルサイズは 50,000 行です。

レスポンスおよびエラーコード

何らかの理由でリクエストが失敗した場合、エラーも JSON 形式で返されます。エラーにはコードと説明が含まれ、以下に詳細を示します。

Code	Type	Details
200	OK	すべて期待どおりに動作しました。
400	Bad request	不正なリクエスト。
401	Unauthorized	リクエストが受け付けられませんでした。通常は API キーが欠落しているか不正です。
422	Quota reached	API クレジット不足のためリクエストが中断されました。（無料プラン）
429	Too many requests	秒あたりの許可リクエスト数に達したためリクエストが中断されました。無料プランでは 1 秒あたり 1 リクエストに制限されます。
500	Internal server error	サーバー側のエラーのためリクエストを完了できませんでした。
503	Service unavailable	サーバーが利用できませんでした。

その他の注意事項

従量課金に関する注意：送信する各電話番号は 1 クレジットとしてカウントされます。クレジットは成功したレスポンスごとではなく、リクエストごとにカウントされます。したがって、（無効な）電話番号「kasj8929hs」のリクエストを送信しても、1 クレジットとしてカウントされます。

はじめにCleariflowのVAT検証APIは、洗練されたモダンなRESTful JSONインターフェースを通じて包括的な税務コンプライアンスソリューションを提供し、国内・国際ビジネスにおけるシームレスな検証と計算を可能にします。

電話番号検証API

curl --request GET \
  --url https://phonevalidation.cleariflow.com/v1

import requests

url = "https://phonevalidation.cleariflow.com/v1"

response = requests.get(url)

print(response.text)

const options = {method: 'GET'};

fetch('https://phonevalidation.cleariflow.com/v1', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://phonevalidation.cleariflow.com/v1",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://phonevalidation.cleariflow.com/v1"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://phonevalidation.cleariflow.com/v1")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://phonevalidation.cleariflow.com/v1")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

{
  "phone": "14155552671",
  "valid": true,
  "possible": true,
  "format": {
    "international": "+14155552671",
    "local": "(415) 555-2671"
  },
  "country": {
    "code": "US",
    "name": "United States",
    "prefix": "+1"
  },
  "location": "San Francisco, CA",
  "type": "Landline_or_Mobile",
  "carrier": "",
  "carrier_display": "",
  "timezones": ["America/Los_Angeles"],
  "geographical": true,
  "internationally_dialable": true
}

検証

ルックアップ

作成

はじめに

REST

HTTPS

API バージョン

API キー

ベース URL

`valid` の意味

検証エンドポイント

リクエストパラメータ

レスポンスパラメータ

一括アップロード（CSV）

レスポンスおよびエラーコード

その他の注意事項

​はじめに

​REST

​HTTPS

​API バージョン

​API キー

​ベース URL

​valid の意味

​検証エンドポイント

​リクエストパラメータ

​レスポンスパラメータ

​一括アップロード（CSV）

​レスポンスおよびエラーコード

​その他の注意事項

はじめに

REST

HTTPS

API バージョン

API キー

ベース URL

`valid` の意味

検証エンドポイント

リクエストパラメータ

レスポンスパラメータ

一括アップロード（CSV）

レスポンスおよびエラーコード

その他の注意事項