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 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.
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.
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 jsonimport osimport sysimport urllib.errorimport urllib.requestapi_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 Nonerequest = 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 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 mainimport ( "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
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 +.