API v2를 사용한 전화 검증 및 포맷

전화번호 확인 및 형식 지정

POST /phone/validate는 number 및 선택적 country 필드를 허용합니다. +로 시작하는 국제전화번호를 사용하세요. 국내 전화번호의 경우 대문자 ISO 국가 코드를 제공하세요. 응답에는 data 내부에 valid, possible, e164, country 및 country_calling_code와 공유 meta 개체가 있습니다. 이는 가입자 존재 여부가 아닌 전화번호의 구조를 확인하는 것입니다. 유효하지 않은 결과를 포함하여 완료된 각 검증 비용은 1크레딧입니다. 아래 예시 응답은 잘못된 숫자를 표시하며 요청 예시와 무관합니다.

JSON 필드	유형	규칙
number	string	필수, 3~32자. ASCII 숫자, 공백, 괄호 및 하이픈(선택 사항으로 앞에 +가 있음). 확장자 및 알파벳 문자는 허용되지 않습니다.
country	string	대문자 ISO 3166-1 alpha-2 코드입니다. 국내 전화번호에 필요합니다. number 값이 +로 시작하는 경우 선택 사항입니다. 필요하지 않은 경우 이 필드를 생략하세요.

프로그래밍 언어를 선택하세요. API 키 설정, 그런 다음 서버에서 예제를 실행하십시오.

모든 예측 요청은 재시도를 포함하여 청구 가능한 새로운 작업입니다. 이러한 예제는 자동으로 재시도하지 않습니다. 다른 요청을 보내기 전에 청구 상태를 확인하세요.

실행하기 전: 액세스 및 오류 처리

서버에서 다음 예제를 실행하세요. 프로세스 환경에서 GENDERAPI_API_KEY를 기존 API 키로 설정합니다. meta.access.mode가 api_key인지 확인하세요. 인식되지 않은 키는 IP 평가판으로 대체될 수 있습니다.

HTTP 4xx 및 5xx JSON 응답은 오류 본문을 보존하고 0이 아닌 종료 상태를 반환합니다. 다시 시도하기 전에 code, action 및 meta.usage.billing_status를 확인하세요.

오류 및 재시도 안내 →

curl --silent --show-error --fail-with-body --max-time 30 \
  --request POST 'https://api.genderapi.io/api/v2/phone/validate' \
  --header "Authorization: Bearer ${GENDERAPI_API_KEY:?Set GENDERAPI_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{
  "number": "+905321234567"
}'

POSIX 셸의 cURL 7.76+. 터미널에서 실행하세요. 런타임 문서

// Server-side Node.js. Save as example.mjs.
const apiKey = process.env.GENDERAPI_API_KEY;
if (!apiKey) throw new Error("Set GENDERAPI_API_KEY");
const body = {
  "number": "+905321234567"
};

const response = await fetch("https://api.genderapi.io/api/v2/phone/validate", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(body),
  signal: AbortSignal.timeout(30_000),
  redirect: "error",
});
const raw = await response.text();
if (!(response.headers.get("content-type") ?? "").includes("json")) {
  throw new Error(`HTTP ${response.status}: expected JSON; request ID ${response.headers.get("x-request-id")}`);
}
const result = JSON.parse(raw); // Also accepts application/problem+json.
if (!response.ok) {
  console.error(`HTTP ${response.status}`, result);
  process.exitCode = 1; // A retry is a new operation; inspect billing first.
} else {
  console.log(JSON.stringify(result, null, 2));
  // For batches, inspect every item: HTTP 200 may contain item errors.
}

Node.js 22+; 내장된 가져오기. example.mjs로 저장하고 node example.mjs를 실행합니다. 런타임 문서

import json
import os
import sys
import urllib.error
import urllib.request

api_key = os.environ.get("GENDERAPI_API_KEY")
if not api_key:
    raise RuntimeError("Set GENDERAPI_API_KEY")
body = json.loads("{\"number\":\"+905321234567\"}")

class NoRedirect(urllib.request.HTTPRedirectHandler):
    def redirect_request(self, req, fp, code, msg, headers, newurl):
        return None

request = urllib.request.Request(
    "https://api.genderapi.io/api/v2/phone/validate",
    method="POST",
    data=json.dumps(body).encode("utf-8"),
    headers={
        "Authorization": "Bearer " + api_key,
        "Content-Type": "application/json",
    },
)
opener = urllib.request.build_opener(NoRedirect())
try:
    response = opener.open(request, timeout=30)
except urllib.error.HTTPError as error:
    response = error  # Keep the Problem Details body on non-2xx responses.
with response:
    status = response.status
    raw = response.read().decode("utf-8")
    if "json" not in response.headers.get("Content-Type", ""):
        raise RuntimeError(f"HTTP {status}: expected a JSON response")
    result = json.loads(raw)
print(json.dumps(result, indent=2), file=sys.stderr if status >= 300 else sys.stdout)
if not 200 <= status < 300:
    sys.exit(1)  # Inspect code, action and billing before retrying.
# For batches, inspect every item even when HTTP status is 200.

Python 3.10+; 표준 라이브러리. example.py로 저장하고 python3 example.py를 실행합니다. 런타임 문서

<?php
$apiKey = getenv('GENDERAPI_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('Set GENDERAPI_API_KEY');
}
$body = json_decode('{"number":"+905321234567"}', true, 512, JSON_THROW_ON_ERROR);

$ch = curl_init('https://api.genderapi.io/api/v2/phone/validate');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_FOLLOWLOCATION => false,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($body, JSON_THROW_ON_ERROR),
]);
$raw = curl_exec($ch);
if ($raw === false) {
    throw new RuntimeException(curl_error($ch));
}
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$contentType = curl_getinfo($ch, CURLINFO_CONTENT_TYPE) ?: '';
curl_close($ch);
if (strpos($contentType, 'json') === false) {
    throw new RuntimeException("HTTP $status: expected a JSON response");
}
$result = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
$output = json_encode($result, JSON_PRETTY_PRINT | JSON_THROW_ON_ERROR) . PHP_EOL;
if ($status < 200 || $status >= 300) {
    fwrite(STDERR, $output); // Preserve the Problem Details body.
    exit(1);
}
echo $output;
// For batches, inspect every item; HTTP 200 can contain item errors.

PHP 8+(cURL 확장 포함). example.php로 저장하고 php example.php를 실행합니다. 런타임 문서

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.time.Duration;

public class GenderApiExample {
    private static String requiredEnv(String name) {
        String value = System.getenv(name);
        if (value == null || value.isBlank()) throw new IllegalStateException("Set " + name);
        return value;
    }

    public static void main(String[] args) throws Exception {
        String apiKey = requiredEnv("GENDERAPI_API_KEY");
        String body = "{\"number\":\"+905321234567\"}";
        HttpClient client = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(10))
            .followRedirects(HttpClient.Redirect.NEVER)
            .build();
        HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.genderapi.io/api/v2/phone/validate"))
            .timeout(Duration.ofSeconds(30))
            .header("Authorization", "Bearer " + apiKey)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body, StandardCharsets.UTF_8))
            .build();
        HttpResponse<String> response = client.send(request,
            HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8));
        if (!response.headers().firstValue("content-type").orElse("").contains("json")) {
            throw new IllegalStateException("HTTP " + response.statusCode() + ": expected JSON");
        }
        // JSON text; parse with your application's JSON library when integrating.
        if (response.statusCode() < 200 || response.statusCode() >= 300) {
            System.err.println(response.body()); // Includes Problem Details.
            System.exit(1);
        }
        System.out.println(response.body());
        // For batches, inspect each item's data or error, including on HTTP 200.
    }
}

Java 17+; 표준 HTTP 클라이언트. GenderApiExample.java로 저장하고 java GenderApiExample.java를 실행합니다. 런타임 문서

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

string RequiredEnv(string name) =>
    !string.IsNullOrWhiteSpace(Environment.GetEnvironmentVariable(name))
        ? Environment.GetEnvironmentVariable(name)!
        : throw new InvalidOperationException($"Set {name}");

var apiKey = RequiredEnv("GENDERAPI_API_KEY");
using var handler = new HttpClientHandler { AllowAutoRedirect = false };
using var client = new HttpClient(handler) { Timeout = TimeSpan.FromSeconds(30) };
using var request = new HttpRequestMessage(HttpMethod.Post, "https://api.genderapi.io/api/v2/phone/validate");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", apiKey);
request.Content = new StringContent("{\"number\":\"+905321234567\"}", Encoding.UTF8, "application/json");

using var response = await client.SendAsync(request);
var raw = await response.Content.ReadAsStringAsync();
if (!(response.Content.Headers.ContentType?.MediaType?.Contains("json") ?? false))
    throw new InvalidOperationException($"HTTP {(int)response.StatusCode}: expected JSON");
using var result = JsonDocument.Parse(raw);
if (!response.IsSuccessStatusCode)
{
    Console.Error.WriteLine(result.RootElement); // Preserve Problem Details.
    Environment.ExitCode = 1;
}
else
{
    Console.WriteLine(result.RootElement);
    // For batches, inspect every item even on HTTP 200.
}

.NET 8+ 콘솔 애플리케이션. 콘솔 프로젝트에서 Program.cs로 사용한 후 dotnet run를 실행하세요. 런타임 문서

package main

import (
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "os"
    "strings"
    "time"
)

func requiredEnv(name string) string {
    value := os.Getenv(name)
    if value == "" { panic("Set " + name) }
    return value
}

func run() error {
    apiKey := requiredEnv("GENDERAPI_API_KEY")
    body := "{\"number\":\"+905321234567\"}"
    request, err := http.NewRequest("POST", "https://api.genderapi.io/api/v2/phone/validate", strings.NewReader(body))
    if err != nil { return err }
    request.Header.Set("Authorization", "Bearer " + apiKey)
    request.Header.Set("Content-Type", "application/json")
    client := &http.Client{
        Timeout: 30 * time.Second,
        CheckRedirect: func(req *http.Request, via []*http.Request) error {
            return http.ErrUseLastResponse
        },
    }
    response, err := client.Do(request)
    if err != nil { return err }
    defer response.Body.Close()
    raw, err := io.ReadAll(response.Body)
    if err != nil { return err }
    if !strings.Contains(response.Header.Get("Content-Type"), "json") || !json.Valid(raw) {
        return fmt.Errorf("HTTP %d: expected a JSON response", response.StatusCode)
    }
    if response.StatusCode < 200 || response.StatusCode >= 300 {
        return fmt.Errorf("HTTP %d: %s", response.StatusCode, raw)
    }
    fmt.Println(string(raw))
    // For batches, inspect every item even on HTTP 200.
    return nil
}

func main() {
    if err := run(); err != nil {
        fmt.Fprintln(os.Stderr, err) // Keep Problem Details for error handling.
        os.Exit(1)
    }
}

Go 1.22+; 표준 라이브러리. main.go로 저장하고 go run main.go를 실행합니다. 런타임 문서

{
  "data": {
    "valid": false,
    "possible": false,
    "e164": null,
    "country": null,
    "country_calling_code": null
  },
  "meta": {
    "request_id": "11111111-1111-4111-8111-111111111111",
    "duration_ms": 12,
    "access": {
      "mode": "ip_trial",
      "reason": "api_key_missing"
    },
    "usage": {
      "charged_credits": 1,
      "remaining_credits": 7,
      "billing_status": "confirmed",
      "resets_at": "2026-09-26T12:00:00.000Z",
      "limit": 10,
      "period_seconds": 86400
    }
  }
}

전화 확인 필드 읽기

잘못된 입력은 청구 전에 HTTP 422로 거부됩니다. 요청 형식은 정확하지만 전화번호를 구문 분석할 수 없는 경우 작업은 valid: false 및 null 형식 필드와 함께 HTTP 200을 반환할 수 있습니다. 완료된 검증 비용은 1크레딧입니다. 구문 분석할 수 있지만 유효하지 않은 숫자에도 여전히 e164 값이 있을 수 있습니다. valid를 확인하세요. 형식이 지정된 숫자만으로는 유효성을 증명할 수 없습니다.

data 내부 필드	의미
valid	번호가 번호 매기기 계획 유효성 검사 규칙과 일치하는지 여부입니다.
possible	번호 매기기 계획에 적합한 길이가 있는지 여부 유효한 것보다 약합니다.
e164	구문 분석이 성공하면 국제 형식의 숫자이고, 그렇지 않으면 null입니다.
country	사용할 수 없는 경우 번호 또는 null에서 파생된 지역입니다. 가입자를 찾지 않습니다.
country_calling_code	숫자로 된 국제 전화 코드 또는 사용할 수 없는 경우 null.

인증 및 재시도

Bearer 인증 및 Content-Type: application/json을 사용하여 기존 API 키를 보냅니다. 예제에서는 환경에서 GENDERAPI_API_KEY를 읽습니다. country 필드는 국내 전화번호에 필수이며 number 값이 +로 시작하는 경우 선택 사항입니다.