Validera och formatera internationella eller nationella telefonnummer med GenderAPI v2. Se obligatoriskt landsammanhang, JSON-fält och enkreditavgiften.
Validera och formatera ett telefonnummer
POST /phone/validate accepterar number och det valfria country-fältet. Använd ett internationellt telefonnummer som börjar med +. För ett nationellt telefonnummer anger du en ISO-landskod med versaler. Svaret har valid, possible, e164, country och country_calling_code inuti data, plus det delade meta-objektet. Detta kontrollerar strukturen på telefonnumret, inte om abonnenten finns. Varje genomförd validering kostar 1 kredit, inklusive ogiltiga resultat. Det illustrativa svaret nedan visar ett ogiltigt nummer och är oberoende av exemplet på begäran.
JSON fält
Typ
Regel
number
string
Obligatoriskt, 3–32 tecken. ASCII siffror, mellanslag, parenteser och bindestreck, med ett valfritt inledande +. Tillägg och alfabetiska tecken accepteras inte.
country
string
ISO 3166-1 alpha-2-kod med stora bokstäver. Krävs för ett nationellt telefonnummer. Valfritt när number-värdet börjar med +. Utelämna detta fält när det inte behövs.
Varje förutsägelseförfrågan är en ny fakturerbar operation, inklusive omförsök. Dessa exempel försöker inte automatiskt igen. Kontrollera faktureringsstatus innan du skickar en ny förfrågan.
Innan du kör: åtkomst och felhantering
Kör dessa exempel på din server. Ställ in GENDERAPI_API_KEY i processmiljön till din befintliga API-nyckel. Bekräfta att meta.access.mode är api_key: en okänd nyckel kan falla tillbaka till IP-testversionen.
HTTP 4xx och 5xx JSON svar bevarar felkroppen och returnerar en utgångsstatus som inte är noll. Kontrollera code, action och meta.usage.billing_status innan du försöker 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+; inbyggd apport. Spara som example.mjs och kör node example.mjs. Körtidsdokumentation
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+; standardbibliotek. Spara som example.py och kör python3 example.py. Körtidsdokumentation
PHP 8+ med tillägget cURL. Spara som example.php och kör php example.php. Körtidsdokumentation
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. Spara som GenderApiExample.java och kör java GenderApiExample.java. Körtidsdokumentation
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. Använd som Program.cs i ett konsolprojekt och kör sedan dotnet run. Körtidsdokumentation
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+; standardbibliotek. Spara som main.go och kör go run main.go. Körtidsdokumentation
Felaktig inmatning avvisas med HTTP 422 före fakturering. Om begäransformatet är korrekt men telefonnumret inte kan analyseras, kan operationen returnera HTTP 200 med formateringsfälten valid: false och null. Denna genomförda validering kostar 1 kredit. Ett nummer som kan analyseras men är ogiltigt kan fortfarande ha ett e164-värde. Kontrollera valid; enbart ett formaterat nummer är inte bevis på giltighet.
Fält inuti data
Betydelse
valid
Om numret matchar reglerna för validering av numreringsplanen.
possible
Om numret har en rimlig längd för sin numreringsplan; svagare än giltigt.
e164
Internationellt formaterat nummer när analysen lyckas, annars null.
country
Region härledd från numret, eller null när den inte är tillgänglig; den hittar inte abonnenten.
country_calling_code
Numerisk internationell samtalskod, eller null när den inte är tillgänglig.
Autentisering och försök igen
Skicka din befintliga API-nyckel med Bearer-autentisering och Content-Type: application/json. Exemplen läser GENDERAPI_API_KEY från miljön. Fältet country krävs för nationella telefonnummer och valfritt när number-värdet börjar med +.