전화번호 검증 및 형식 변환 API

글로벌 전화번호 정보

하나의 번호를 일관된 형식으로

국내·국제 형식과 불규칙한 형식의 입력을 받아 242개 국가 및 지역에 대한 표준 형식과 검증 메타데이터를 반환합니다.

원본 입력+1 212 867 5309

E.164 결과+12128675309

유효성 검증isValid and isPossible

형식 변환국내, 국제 및 E.164

번호 분류휴대전화, 유선전화, VoIP 등

위치지역, 지역 번호 및 위치

입력 매개변수

전화번호와 지역 맥락

매개변수	필수 여부	설명
`number`	필수	국내, 국제 또는 E.164 형식의 전화번호입니다.
`address`	조건부	국내 번호를 해석하는 데 사용할 ISO 국가 코드, 국가명, 도시 또는 지역입니다.

address가 필요한 경우

number가 +와 국제 전화 코드로 시작하지 않으면 KR,South Korea 또는 Seoul 같은 지역 정보를 제공하세요.

USGermanyİstanbulNew YorkÉtats-Unis

GET

쿼리 문자열 인증

기본 GET 요청

cURL

curl "https://api.genderapi.io/api/phone?key=YOUR_API_KEY&number=%2B12128675309&address=US"

URL 인코딩:+는 %2B, 공백은 %20으로 인코딩하세요. 문자열을 직접 조합하지 말고 사용하는 언어의 URL 또는 URLSearchParams 기능을 권장합니다.

POST

Bearer 인증

서버 측 POST 요청

번호와 선택적 address를 JSON으로 보내고 API 키는 Authorization 헤더에 포함하세요.

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"}'

JavaScript

const response = await 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" })
});

API 응답

유효성 검증, 형식 변환 및 메타데이터

JSON

{
  "status": true, "remaining_credits": 15709, "expires": 0, "duration": "18ms",
  "regionCode": "US", "countryCode": 1, "country": "United 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)"
}

응답 필드

필드	유형	설명
`status`	boolean	요청이 정상적으로 완료되었는지 나타냅니다.
`remaining_credits`	integer	요청 후 남은 크레딧입니다.
`expires`	integer	크레딧 만료 시각의 UNIX 타임스탬프입니다.
`duration`	string	서버 처리 시간입니다.
`regionCode`	string	감지된 ISO 3166-1 alpha-2 지역 코드입니다.
`countryCode`	integer	국제 전화 국가 코드입니다.
`country`	string	사람이 읽을 수 있는 국가 이름입니다.
`national`	string	국내 사용 형식으로 변환한 번호입니다.
`international`	string	국제 표기 형식으로 변환한 번호입니다.
`e164`	string	표준 E.164 형식입니다.
`isValid`	boolean	번호가 지역별 유효성 규칙을 충족하는지 나타냅니다.
`isPossible`	boolean	번호 구조상 존재 가능한지 나타냅니다.
`numberType`	string	감지된 전화번호 유형입니다.
`nationalSignificantNumber`	string	국가 전화 코드를 제외한 국내 번호입니다.
`rawInput`	string	요청에 전송한 원래 번호입니다.
`isGeographical`	boolean	번호를 지리적 지역과 연결할 수 있는지 나타냅니다.
`areaCode`	string	감지된 지역 번호입니다.
`location`	string	지역 번호와 연결된 위치입니다.

번호 분류 reference

전화번호 유형 값

FIXED_LINE

특정 지역에 연결된 유선 전화번호입니다.

MOBILE

휴대전화 번호입니다.

FIXED_LINE_OR_MOBILE

번호 체계에서 유선과 휴대전화를 구분하지 않습니다.

TOLL_FREE

수신자 부담 무료 전화번호입니다.

PREMIUM_RATE

고액 요금 서비스 번호입니다.

SHARED_COST

발신자와 수신자가 통화료를 나누어 부담합니다.

VOIP

VoIP 인터넷 전화번호입니다.

PERSONAL_NUMBER

다른 회선으로 연결할 수 있는 개인 번호입니다.

PAGER

호출기 알림 번호입니다.

UAN

기업의 공용 연락처로 사용하는 범용 액세스 번호입니다.

VOICEMAIL

전용 음성 사서함 접속 번호입니다.

UNKNOWN

전화번호 유형을 확인할 수 없습니다.

자주 묻는 질문

전화번호 API FAQ

전화번호 검증 API는 무엇을 하나요?

전화번호를 검증하고 표준화하며 국내·국제·E.164 형식과 가능한 경우 지역, 번호 유형 및 위치 메타데이터를 반환합니다.

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

isValid는 지역 번호 규칙에 따른 유효성을 확인하고, isPossible은 유효성이 확정되지 않아도 구조상 가능한 번호인지를 나타냅니다.

address는 언제 필요한가요?

번호가 더하기 기호와 국제 전화 코드로 시작하지 않을 때 address를 제공하세요. ISO 국가 코드, 국가명, 도시 또는 지역을 사용할 수 있습니다.

특수 문자는 어떻게 전송해야 하나요?

GET 쿼리 매개변수의 공백, 더하기 기호와 특수 문자는 URL 인코딩하세요. JSON POST 본문은 HTTP 클라이언트가 인코딩합니다.

다음 참고 문서

사용량 및 할당량 확인

사용량 및 할당량크레딧과 한도 이해하기 →클라이언트 라이브러리전화번호 검증 패키지 설치하기 →