API-DOKUMENTATION V2

GenderAPI.io V2: Validering och formatering av telefonnummer

Kontrollera strukturen i ett telefonnummer med GenderAPI.io V2 utifrån number och country. Läs data.valid, data.possible, formateringsfälten och metadata om användningen.

Validera och formatera ett telefonnummer

ParameterTypObligatoriskStandardvärdeBeskrivning
numberstringJa—Krävs, 3–32 tecken. ASCII-siffror, mellanslag, parenteser och bindestreck, med valfritt inledande +. Anknytningar och bokstäver godtas inte.
countrystringVillkorligt—ISO 3166-1 alpha-2-kod med versaler. Krävs för ett nationellt nummer, valfritt när number börjar med +. Utelämna fältet om det inte behövs.

Skicka number och valfritt country till POST https://api.genderapi.io/api/v2/phone/validate. Använd ett internationellt nummer som börjar med +, eller ange en ISO-landskod med versaler för ett nationellt nummer. GenderAPI.io V2 returnerar data.valid, data.possible, data.e164, data.country och data.country_calling_code samt meta för åtkomst och debitering. Kontrollen gäller nummerstrukturen, inte om abonnemanget finns. Varje slutförd validering kostar 1 kredit, även när resultatet är ogiltigt. Det syntetiska svaret nedan visar ett ogiltigt nummer, oberoende av exemplet på förfrågan.

Välj ett programmeringsspråk. Konfigurera din API-nyckel, kör sedan exemplet på din server.

Varje prediktionsförfrågan är en ny debiterbar åtgärd, även vid nya försök. Exemplen gör inga automatiska nya försök. Kontrollera debiteringsstatus innan du skickar en ny förfrågan.

Innan du kör: åtkomst och felhantering

Kör exemplen på din server. Sätt GENDERAPI_API_KEY i processmiljön till din befintliga API-nyckel. Kontrollera att meta.access.mode är api_key: en nyckel som inte känns igen kan leda till IP-provperioden.

Vid JSON-svar med HTTP 4xx och 5xx behålls felinnehållet och exemplet avslutas med en slutstatus som inte är noll. Kontrollera code, action och meta.usage.billing_status innan du försöker igen.

Guide om fel och nya försök →
cURL
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"
}'

cURL 7.76+ i ett POSIX-skal. Kör i terminalen. Dokumentation för körmiljön

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+; inbyggd fetch. Spara som example.mjs och kör node example.mjs. Dokumentation för körmiljön

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.

Python 3.10+; standardbiblioteket. Spara som example.py och kör python3 example.py. Dokumentation för körmiljön

PHP
<?php
$apiKey = getenv('GENDERAPI_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('Set GENDERAPI_API_KEY');
}
$body = json_decode('{"number":"+905321234567"}', true, 512, JSON_THROW_ON_ERROR);

$ch = curl_init('https://api.genderapi.io/api/v2/phone/validate');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => '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.

PHP 8+ med tillägget cURL. Spara som example.php och kör php example.php. Dokumentation för körmiljön

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+; inbyggd HTTP-klient. Spara som GenderApiExample.java och kör java GenderApiExample.java. Dokumentation för körmiljön

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.
}

Konsolapplikation med .NET 8+. Använd som Program.cs i ett konsolprojekt och kör sedan dotnet run. Dokumentation för körmiljön

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)
    }
}

Go 1.22+; standardbiblioteket. Spara som main.go och kör go run main.go. Dokumentation för körmiljön

Illustrativt JSON-svar
{
  "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
    }
  }
}

Läs fälten för telefonvalidering

Ett 422-svar avvisar felaktiga indata före debitering. En korrekt utformad förfrågan vars nummer inte kan tolkas kan slutföras med HTTP 200, valid: false och null i formateringsfälten; den slutförda valideringen kostar 1 kredit. Ett nummer som kan tolkas men är ogiltigt kan ändå ha ett e164-värde. Kontrollera valid i stället för att se ett formaterat nummer som bevis på giltighet.

FältTypKan vara nullExempelBeskrivning
data.validbooleanNejfalseOm numret följer valideringsreglerna i nummerplanen.
data.possiblebooleanNejfalseOm numret har en rimlig längd för sin nummerplan; svagare än valid.
data.e164stringJanullInternationellt formaterat nummer om tolkningen lyckas, annars null.
data.countrystringJanullRegion som härleds från numret, eller null om den saknas; den visar inte var abonnenten finns.
data.country_calling_codeintegerJanullNumerisk internationell landsnummerkod, eller null om den saknas.

Metadata om åtkomst, debitering och förfrågan

FältTypKan vara nullExempelBeskrivning
meta.request_idstringNej"550e8400-e29b-41d4-a716-446655440000"Unik identifierare för det här HTTP-försöket; skickas även i X-Request-ID.
meta.duration_msintegerNej42Bearbetningstid för förfrågan i millisekunder.
meta.access.modestringNej"api_key"api_key, ip_trial eller unauthenticated. Kontrollera att api_key rapporteras när du använder ett betalt konto.
meta.access.reasonstringJanullOrsak till att IP-provperioden användes: api_key_missing, api_key_invalid eller api_key_not_found; annars null.
meta.usage.charged_creditsintegerJa1Debiterade krediter netto. 0 före debitering eller efter en bekräftad fullständig återbetalning; null när debiteringen är obekräftad.
meta.usage.remaining_creditsintegerJa99Saldo när åtgärden slutförs. Kan vara negativt; null om saldot saknas eller debiteringen är obekräftad.
meta.usage.billing_statusstringNej"confirmed"not_charged, confirmed eller unconfirmed. Kontrollera detta innan du gör ett nytt försök med en misslyckad prediktion.
meta.usage.resets_atstringJa"2026-09-27T12:00:00.000Z"Tidpunkt i UTC (ISO 8601) då IP-provperioden återställs; null för konton med API-nyckel eller om tidpunkten är okänd.
meta.usage.limitintegerJa10Kvot för IP-provperioden; null för konton med API-nyckel.
meta.usage.period_secondsintegerJa86400IP-provperiodens tidsfönster i sekunder; null för konton med API-nyckel.

Autentisering och nya försök

Skicka din befintliga API-nyckel i Bearer-rubriken och Content-Type: application/json. Kodexemplen läser GENDERAPI_API_KEY från miljön. Nationella nummer kräver country; fältet är valfritt när number börjar med +.