Valideer en formatteer internationale of nationale telefoonnummers met GenderAPI v2. Zie de vereiste landcontext, JSON-velden en de kosten voor één krediet.
Valideer en formatteer een telefoonnummer
POST /phone/validate accepteert number en het optionele veld country. Gebruik een internationaal telefoonnummer dat begint met +. Voor een nationaal telefoonnummer dient u een ISO-landcode in hoofdletters op te geven. Het antwoord bevat valid, possible, e164, country en country_calling_code in data, plus het gedeelde meta-object. Hiermee wordt de structuur van het telefoonnummer gecontroleerd, niet of de abonnee bestaat. Elke voltooide validatie kost 1 credit, inclusief ongeldige resultaten. Het onderstaande illustratieve antwoord toont een ongeldig nummer en is onafhankelijk van het verzoekvoorbeeld.
JSON-veld
Typen
Regel
number
string
Vereist, 3–32 tekens. ASCII cijfers, spaties, haakjes en koppeltekens, met optionele voorloop +. Extensies en alfabetische tekens worden niet geaccepteerd.
country
string
ISO 3166-1 alpha-2-code in hoofdletters. Vereist voor een landelijk telefoonnummer. Optioneel als de number-waarde begint met +. Laat dit veld weg als het niet nodig is.
Kies een programmeertaal.Stel uw API-sleutel in, voer vervolgens het voorbeeld uit op uw server.
Elk voorspellingsverzoek is een nieuwe factureerbare bewerking, inclusief nieuwe pogingen. Deze voorbeelden proberen niet automatisch opnieuw. Controleer de factureringsstatus voordat u een nieuw verzoek verzendt.
Voordat u begint: toegang en foutafhandeling
Voer deze voorbeelden uit op uw server. Stel GENDERAPI_API_KEY in de procesomgeving in op uw bestaande API-sleutel. Bevestig dat meta.access.mode api_key is: een niet-herkende sleutel kan terugvallen op de IP-proefversie.
HTTP 4xx en 5xx JSON-antwoorden behouden de fouttekst en retourneren een afsluitstatus die niet nul is. Controleer code, action en meta.usage.billing_status voordat u het opnieuw probeert.
// 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+; ingebouwde ophaalfunctie. Opslaan als example.mjs en voer node example.mjs uit. Runtime-documentatie
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+; standaard bibliotheek. Opslaan als example.py en voer python3 example.py uit. Runtime-documentatie
PHP 8+ met de cURL-extensie. Opslaan als example.php en voer php example.php uit. Runtime-documentatie
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+; standaard HTTP-client. Opslaan als GenderApiExample.java en voer java GenderApiExample.java uit. Runtime-documentatie
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+ console-applicatie. Gebruik als Program.cs in een consoleproject en voer vervolgens dotnet run uit. Runtime-documentatie
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+; standaard bibliotheek. Opslaan als main.go en voer go run main.go uit. Runtime-documentatie
Verkeerd opgemaakte invoer wordt vóór facturering afgewezen met HTTP 422. Als het verzoekformaat correct is maar het telefoonnummer niet kan worden geparseerd, kan de bewerking HTTP 200 retourneren met de opmaakvelden valid: false en null. Deze ingevulde validatie kost 1 credit. Een getal dat kan worden geparseerd maar ongeldig is, kan nog steeds de waarde e164 hebben. Controleer valid; een opgemaakt nummer alleen is geen bewijs van geldigheid.
Veld binnen data
Betekenis
valid
Of het nummer overeenkomt met de validatieregels van het nummerplan.
possible
Of het nummer een plausibele lengte heeft voor zijn nummerplan; zwakker dan geldig.
e164
Internationaal opgemaakt nummer wanneer het parseren slaagt, anders null.
country
Regio afgeleid van het nummer, of null indien niet beschikbaar; het lokaliseert de abonnee niet.
country_calling_code
Numerieke internationale belcode, of null indien niet beschikbaar.
Authenticatie en nieuwe pogingen
Verzend uw bestaande API-sleutel met behulp van Bearer-authenticatie en Content-Type: application/json. In de voorbeelden wordt GENDERAPI_API_KEY uit de omgeving gelezen. Het veld country is verplicht voor nationale telefoonnummers en optioneel als de number-waarde begint met +.