# Puhelimen vahvistus ja alustus API v2:lla > Tarkista ja muotoile kansainvälisiä ja kansallisia puhelinnumeroita GenderAPI V2:lla. Tutustu maatietoon, JSON-kenttiin ja yhden krediitin veloitukseen. Canonical HTML: https://www.genderapi.io/fi/docs/v2/phone-validation Last reviewed: 2026-09-25 ## Vahvista ja muotoile puhelinnumero POST /phone/validate hyväksyy number-kentän ja valinnaisen country-kentän. Käytä +-merkillä alkavaa kansainvälistä numeroa; kansallinen numero tarvitsee ISO-maakoodin isoilla kirjaimilla. Vastauksen data sisältää kentät valid, possible, e164, country ja country_calling_code sekä yhteisen meta-objektin. Tarkistus koskee numeron rakennetta, ei liittymän olemassaoloa. Jokainen loppuun käsitelty tarkistus maksaa 1 krediitin, myös virheellisen numeron tulos. Alla oleva havainnollistava vastaus on riippumaton esimerkkipyynnöstä. Suorita nämä esimerkit palvelimellasi. Aseta GENDERAPI_API_KEY prosessiympäristössä olemassa olevaan API-avaimeen. Varmista, että meta.access.mode on api_key: tunnistamaton avain voi pudota takaisin IP-kokeeseen. Jokainen ennustepyyntö on uusi laskutettava toiminto, mukaan lukien uudelleenyritykset. Nämä esimerkit eivät yritä automaattisesti uudelleen. Tarkista laskutuksen tila ennen uuden pyynnön lähettämistä. HTTP 4xx- ja 5xx JSON -vastaukset säilyttävät virheen rungon ja palauttavat nollasta poikkeavan poistumistilan. Tarkista code, action ja meta.usage.billing_status ennen kuin yrität uudelleen. | JSON -kenttä | Tyyppi | Sääntö | | --- | --- | --- | | number | string | Pakollinen, 3–32 merkkiä. ASCII numeroita, välilyöntejä, sulkeita ja yhdysmerkkejä, valinnainen etupään +. Laajennuksia ja aakkosmerkkejä ei hyväksytä. | | country | string | ISO 3166-1 -alpha-2-koodi isoilla kirjaimilla. Vaaditaan kansallista puhelinnumeroa varten. Valinnainen, kun number-arvo alkaa +. Jätä tämä kenttä pois, kun sitä ei tarvita. | **cURL** cURL 7.76+ POSIX-kuoressa. Suorita terminaalissasi. ```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+; sisäänrakennettu haku. Tallenna nimellä example.mjs ja suorita 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+; tavallinen kirjasto. Tallenna nimellä example.py ja suorita 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+ cURL-laajennuksella. Tallenna nimellä example.php ja suorita 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+; tavallinen HTTP-asiakas. Tallenna nimellä GenderApiExample.java ja suorita 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** .NET 8+ -konsolisovellus. Käytä konsoliprojektissa nimellä Program.cs ja suorita sitten 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+; tavallinen kirjasto. Tallenna nimellä main.go ja suorita 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 } } } ``` ## Lue puhelimen vahvistuskentät Virheellinen syöte hylätään HTTP 422:lla ennen laskutusta. Jos pyynnön muoto on oikea, mutta puhelinnumeroa ei voida jäsentää, toiminto voi palauttaa HTTP 200:n valid: false- ja null-muotoilukentillä. Tämä suoritettu vahvistus maksaa 1 hyvityksen. Numerolla, joka voidaan jäsentää, mutta joka on virheellinen, voi silti olla e164-arvo. Tarkista valid; muotoiltu numero ei yksinään ole todiste pätevyydestä. | Kenttä sisällä data | Merkitys | | --- | --- | | valid | Vastaako numero numerointisuunnitelman vahvistussääntöjä. | | possible | Onko numerolla uskottava pituus sen numerointisuunnitelmassa; heikompi kuin voimassa. | | e164 | Kansainvälinen muotoiltu numero, kun jäsentäminen onnistuu, muuten null. | | country | Alue johdettu numerosta tai null, kun se ei ole käytettävissä; se ei löydä tilaajaa. | | country_calling_code | Numeerinen ulkomaanpuhelukoodi tai null, kun se ei ole käytettävissä. | ## Todennus ja uudelleenyritykset Lähetä olemassa oleva API-avaimesi siirtotietodennuksen ja Content-Type:n avulla: application/json. Esimerkit lukevat ympäristöstä GENDERAPI_API_KEY. country-kenttä on pakollinen kansallisille puhelinnumeroille ja valinnainen, kun number-arvo alkaa +:lla. - [Todennus](https://www.genderapi.io/fi/docs/v2/authentication) - [Virheet ja uudelleenyritykset](https://www.genderapi.io/fi/docs/v2/errors-and-retries) - [Krediitit ja käyttö](https://www.genderapi.io/fi/docs/v2/credits-and-usage)