전화번호 유효성 검사 및 포맷터 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

이 링크를 통해 하루 200 크레딧이 포함된 무료 API 키를 받을 수 있습니다.

주소(address) 매개변수

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과 같은 도시 또는 지역 이름

선택 사항이긴 하지만, 전화번호가 국제 국가 번호(예: +1, +44, +90)로 시작하지 않는 경우에는 address 매개변수가 필수입니다. 이와 같은 문맥 정보 없이 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())

클라이언트 라이브러리

통합을 더욱 쉽게 하기 위해 다양한 프로그래밍 언어에 대한 공식 및 커뮤니티 지원 클라이언트 라이브러리를 제공합니다. 이러한 라이브러리를 사용하면 GenderAPI의 엔드포인트 — 예: 전화번호 유효성 검사 API — 와 상호 작용할 때, HTTP 요청이나 JSON 파싱을 수동으로 처리할 필요가 없습니다. 환경에 맞는 라이브러리를 선택하고 설치한 후, 최소한의 설정으로 요청을 시작할 수 있습니다.

사용 가능한 클라이언트 라이브러리 및 설치 지침은 다음 페이지에서 확인할 수 있습니다:
https://www.genderapi.io/ko/docs-client-libraries

자주 묻는 질문 (FAQ)

1. 전화번호 유효성 검사 및 포맷터 API란 무엇인가요?

이 API는 전 세계 전화번호를 유효성 검사하고, 포맷을 표준화하며, 메타데이터를 분석할 수 있도록 도와주는 도구입니다. 번호를 E.164 표준 형식으로 변환하고, 지역, 유형(모바일/유선), 유효성 등과 같은 메타 정보를 파악할 수 있습니다.

2. 전화번호 유효성 검사는 무엇에 사용되나요?

번호가 유효한지 확인하고, 국제 표준 형식으로 변환하며, 번호 유형(예: 모바일, VoIP)을 식별하고, 지역 기반 메타데이터를 감지하여 CRM, 마케팅 도구 또는 사용자 가입 폼에 표준화된 전화번호 입력을 보장하는 데 사용됩니다.

3. 몇 개국이 지원되나요?

이 API는 전 세계 242개국 및 지역의 전화번호를 지원합니다. 이는 국제 또는 지역 기반 애플리케이션을 위한 전 세계적인 범위를 보장합니다.

4. 어떤 형식들이 지원되나요?

API는 국가 형식, 국제 형식, E.164 형식 등 다양한 전화번호 형식을 수용하며, 자동으로 이를 감지하고 올바른 형식으로 표준화합니다.

5. country 또는 address 파라미터를 생략하면 어떻게 되나요?

전화번호가 ‘+’로 시작하지 않고 국가 또는 주소 정보가 없는 경우, API가 해당 번호를 정확히 해석하지 못할 수 있습니다. address 파라미터(예: US, United States, New York)를 포함시키는 것이 권장됩니다.

6. API는 번호 유형을 감지할 수 있나요?

네. API는 numberType 필드를 반환하여 해당 번호가 MOBILE, FIXED_LINE, VOIP 등인지 알려줍니다.

7. isValid와 isPossible의 차이는 무엇인가요?

isValid는 번호가 실제로 할당되었고, 지역 규칙에 부합함을 의미합니다. isPossible는 구조상 번호가 존재할 수 있음을 의미하며, 현재 할당되지 않았더라도 가능한 번호입니다.

8. API 응답은 어떤 형태인가요?

성공적인 응답에는 상태(status), 포맷된 번호(국가, 국제, E.164 형식), 지역 정보, 번호 유형, 크레딧 사용량 등 다양한 정보가 포함됩니다. 전체 응답 예시는 "API 응답 예시" 섹션을 참고하세요.

9. API 키는 어떻게 전송하나요?

GET 요청의 경우, ?key=YOUR_API_KEY처럼 쿼리 파라미터로 추가하세요. 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

위의 입력 값들은 API에 의해 정확히 해당 국가 또는 지역으로 매핑됩니다.