Valider og formater internationale eller nationale telefonnumre med GenderAPI v2. Se påkrævet landekontekst, JSON-felter og 1-kreditgebyr.
Valider og formater et telefonnummer
POST /phone/validate accepterer number og det valgfrie country-felt. Brug et internationalt telefonnummer, der begynder med +. For et nationalt telefonnummer skal du angive en ISO-landekode med store bogstaver. Svaret har valid, possible, e164, country og country_calling_code inde i data, plus det delte meta-objekt. Dette kontrollerer strukturen af telefonnummeret, ikke om abonnenten eksisterer. Hver gennemført validering koster 1 kredit, inklusive ugyldige resultater. Det illustrative svar nedenfor viser et ugyldigt nummer og er uafhængigt af anmodningseksemplet.
JSON felt
Type
Regel
number
string
Påkrævet, 3–32 tegn. ASCII cifre, mellemrum, parenteser og bindestreger, med et valgfrit indledende +. Udvidelser og alfabetiske tegn accepteres ikke.
country
string
ISO 3166-1 alpha-2-kode med store bogstaver. Kræves for et nationalt telefonnummer. Valgfrit, når number-værdien begynder med +. Udelad dette felt, når det ikke er nødvendigt.
Vælg et programmeringssprog.Indstil din API nøgle, kør derefter eksemplet på din server.
Hver forudsigelsesanmodning er en ny fakturerbar operation, inklusive genforsøg. Disse eksempler forsøger ikke automatisk igen. Tjek faktureringsstatus, før du sender endnu en anmodning.
Før du kører: adgang og fejlhåndtering
Kør disse eksempler på din server. Indstil GENDERAPI_API_KEY i procesmiljøet til din eksisterende API nøgle. Bekræft, at meta.access.mode er api_key: en ikke-genkendt nøgle kan falde tilbage til IP-prøveversionen.
HTTP 4xx og 5xx JSON-svar bevarer fejlteksten og returnerer en udgangsstatus, der ikke er nul. Tjek code, action og meta.usage.billing_status, før du prøver igen.
// 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+; indbygget apport. Gem som example.mjs og kør node example.mjs. Kørselsdokumentation
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+; standard bibliotek. Gem som example.py og kør python3 example.py. Kørselsdokumentation
PHP 8+ med cURL-udvidelsen. Gem som example.php og kør php example.php. Kørselsdokumentation
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+; standard HTTP klient. Gem som GenderApiExample.java og kør java GenderApiExample.java. Kørselsdokumentation
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.}
.NET 8+ konsolapplikation. Brug som Program.cs i et konsolprojekt, og kør derefter dotnet run. Kørselsdokumentation
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+; standard bibliotek. Gem som main.go og kør go run main.go. Kørselsdokumentation
Forkert input afvises med HTTP 422 før fakturering. Hvis anmodningsformatet er korrekt, men telefonnummeret ikke kan parses, kan handlingen returnere HTTP 200 med valid: false og null formateringsfelter. Denne gennemførte validering koster 1 kredit. Et tal, der kan parses, men er ugyldigt, kan stadig have en e164-værdi. Tjek valid; et formateret tal alene er ikke bevis for gyldighed.
Felt inde i data
Betydning
valid
Om nummeret matcher nummereringsplanens valideringsregler.
possible
Om nummeret har en plausibel længde for dets nummereringsplan; svagere end gyldigt.
e164
Internationalt formateret nummer, når parsing lykkes, ellers null.
country
Region afledt af nummeret, eller null, når den ikke er tilgængelig; den finder ikke abonnenten.
country_calling_code
Numerisk international opkaldskode eller null, når den ikke er tilgængelig.
Godkendelse og genforsøg
Send din eksisterende API-nøgle ved hjælp af Bearer-godkendelse og Content-Type: application/json. Eksemplerne læser GENDERAPI_API_KEY fra miljøet. country-feltet er påkrævet for nationale telefonnumre og valgfrit, når number-værdien starter med +.