DOKUMENTACE API V2

Ověření a formátování telefonu pomocí API v2

Ověřujte a formátujte mezinárodní nebo národní telefonní čísla pomocí GenderAPI v2. Viz požadovaný kontext země, pole JSON a poplatek za jeden kredit.

Ověřte a naformátujte telefonní číslo

POST /phone/validate přijímá number a volitelné pole country. Použijte mezinárodní telefonní číslo začínající +. Pro národní telefonní číslo zadejte velký kód země ISO. Odpověď obsahuje valid, possible, e164, country a country_calling_code uvnitř data plus sdílený objekt meta. Tím se kontroluje struktura telefonního čísla, nikoli to, zda účastník existuje. Každá dokončená validace stojí 1 kredit včetně neplatných výsledků. Ilustrativní odpověď níže ukazuje neplatné číslo a je nezávislá na příkladu požadavku.

Pole JSONTypPravidlo
numberstringPovinné, 3–32 znaků. ASCII číslice, mezery, závorky a pomlčky, s volitelným znakem +. Rozšíření a abecední znaky nejsou akceptovány.
countrystringKód ISO 3166-1 alpha-2 velkými písmeny. Vyžadováno pro národní telefonní číslo. Volitelné, když hodnota number začíná +. Pokud toto pole není potřeba, vynechejte ho.

Vyberte programovací jazyk. Nastavte klíč API, poté spusťte příklad na svém serveru.

Každý požadavek na predikci je nová zúčtovatelná operace, včetně opakování. Tyto příklady se automaticky neopakují. Před odesláním další žádosti zkontrolujte stav fakturace.

Než spustíte: přístup a zpracování chyb

Spusťte tyto příklady na svém serveru. Nastavte GENDERAPI_API_KEY v procesním prostředí na váš stávající klíč API. Potvrďte, že meta.access.mode je api_key: Nerozpoznaný klíč se může vrátit ke zkušební verzi IP.

Odpovědi HTTP 4xx a 5xx JSON zachovají tělo chyby a vrátí nenulový stav ukončení. Před dalším pokusem zkontrolujte code, action a meta.usage.billing_status.

Chyba a opakujte průvodce →
cURL
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"
}'

cURL 7.76+ v prostředí POSIX. Spusťte ve svém terminálu. Runtime dokumentace

JavaScript / Node.js
// 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+; vestavěný aport. Uložte jako example.mjs a spusťte node example.mjs. Runtime dokumentace

Python
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+; standardní knihovna. Uložte jako example.py a spusťte python3 example.py. Runtime dokumentace

PHP
<?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+ s rozšířením cURL. Uložte jako example.php a spusťte php example.php. Runtime dokumentace

Java
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+; standardní klient HTTP. Uložte jako GenderApiExample.java a spusťte java GenderApiExample.java. Runtime dokumentace

C# / .NET
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.
}

Konzolová aplikace .NET 8+. Použijte jako Program.cs v projektu konzoly a poté spusťte dotnet run. Runtime dokumentace

Go
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+; standardní knihovna. Uložte jako main.go a spusťte go run main.go. Runtime dokumentace

Ilustrativní odpověď JSON
{
  "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
    }
  }
}

Přečtěte si pole ověření telefonu

Chybný vstup je před fakturací odmítnut pomocí HTTP 422. Pokud je formát požadavku správný, ale telefonní číslo nelze analyzovat, může operace vrátit HTTP 200 s poli formátování valid: false a null. Toto dokončené ověření stojí 1 kredit. Číslo, které lze analyzovat, ale je neplatné, může mít stále hodnotu e164. Zkontrolujte valid; samotné formátované číslo není důkazem platnosti.

Pole uvnitř dataMeaning
validZda číslo odpovídá ověřovacím pravidlům číslovacího plánu.
possibleZda má číslo přijatelnou délku pro svůj plán číslování; slabší než platný.
e164Číslo v mezinárodním formátu při úspěšné analýze, jinak null.
countryOblast odvozená z čísla nebo null, když není k dispozici; nenalezne předplatitele.
country_calling_codeČíselný mezinárodní volací kód nebo null, pokud není k dispozici.

Autentizace a opakované pokusy

Odešlete svůj stávající klíč API pomocí ověřování nosiče a Content-Type: application/json. Příklady čtou GENDERAPI_API_KEY z prostředí. Pole country je povinné pro národní telefonní čísla a volitelné, pokud hodnota number začíná znakem +.