# 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. Canonical HTML: https://www.genderapi.io/cs/docs/v2/phone-validation Last reviewed: 2026-09-25 ## 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. 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. 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. 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. | Pole JSON | Typ | Pravidlo | | --- | --- | --- | | number | string | Povinné, 3–32 znaků. ASCII číslice, mezery, závorky a pomlčky, s volitelným znakem +. Rozšíření a abecední znaky nejsou akceptovány. | | country | string | Kó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. | **cURL** cURL 7.76+ v prostředí POSIX. Spusťte ve svém terminálu. ```bash 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" }' ``` **JavaScript / Node.js** Node.js 22+; vestavěný aport. Uložte jako example.mjs a spusťte node example.mjs. ```javascript // 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. } ``` **Python** Python 3.10+; standardní knihovna. Uložte jako example.py a spusťte python3 example.py. ```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. ``` **PHP** PHP 8+ s rozšířením cURL. Uložte jako example.php a spusťte php example.php. ```php '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. ``` **Java** Java 17+; standardní klient HTTP. Uložte jako GenderApiExample.java a spusťte java GenderApiExample.java. ```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 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. } } ``` **C# / .NET** Konzolová aplikace .NET 8+. Použijte jako Program.cs v projektu konzoly a poté spusťte dotnet run. ```csharp 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. } ``` **Go** Go 1,22+; standardní knihovna. Uložte jako main.go a spusťte go run main.go. ```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) } } ``` ```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ř data | Meaning | | --- | --- | | valid | Zda číslo odpovídá ověřovacím pravidlům číslovacího plánu. | | possible | Zda 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. | | country | Oblast 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 +. - [Autentizace](https://www.genderapi.io/cs/docs/v2/authentication) - [Chyby a opakování](https://www.genderapi.io/cs/docs/v2/errors-and-retries) - [Kredity a využití](https://www.genderapi.io/cs/docs/v2/credits-and-usage)