API do Walidacji i Formatowania Numerów Telefonów

API do weryfikacji numerów telefonów jest obsługiwane w 242 krajach.

API do Walidacji i Formatowania Numerów Telefonów umożliwia łatwe przetwarzanie numerów telefonów wprowadzanych przez użytkowników w różnych formatach. Niezależnie od tego, czy dane wejściowe wyglądają jak 1(212)-867-53-09, +1 212 8675309, 001-212.867.5309, czy po prostu 2128675309, nasze API inteligentnie rozpozna strukturę i zwróci wystandaryzowaną wersję.

Narzędzie automatycznie konwertuje dane wejściowe na format E.164, który jest globalnie uznawanym standardem numerów międzynarodowych. Na przykład +1 212 867 5309 zostanie zwrócony jako +12128675309, co sprawia, że jest gotowy do użycia w systemach i integracjach telefonicznych.

Oprócz formatowania, API zapewnia szczegółową weryfikację numeru telefonu. Sprawdza, czy numer ma status isValid: true — oznacza to, że numer jest zgodny z krajowym planem numeracyjnym. Udostępnia także pole isPossible: true, które wskazuje, czy taki numer mógłby potencjalnie istnieć, nawet jeśli nie jest aktualnie przydzielony. To przydatne w przypadku wstępnej walidacji przed zapisaniem lub przetwarzaniem.

Parametr numberType pomaga zidentyfikować, czy numer telefonu to komórkowy, stacjonarny czy VoIP. Jest to szczególnie przydatne w sytuacjach, gdy np. chcesz zezwolić tylko na numery komórkowe dla weryfikacji SMS lub stacjonarne dla kontaktów biurowych.

Dzięki obsłudze rozpoznawania kodu obszaru, API może również wykrywać geograficzne pochodzenie numeru. Na przykład numer rozpoczynający się od kodu 212 jest automatycznie przypisywany do Nowego Jorku (Manhattan). Funkcja ta idealnie nadaje się do zastosowań wymagających segmentacji lub analizy lokalizacyjnej.

Każdy numer jest również powiązany ze szczegółowymi danymi krajowymi, takimi jak kod regionu ISO (np. US) oraz numeryczny kod kraju (np. 1), co umożliwia stosowanie logiki i formatów specyficznych dla danego regionu w aplikacjach.

✅ Odpowiedź API

Przykładowa odpowiedź JSON:

{
  "status": true,
  "remaining_credits": 15709,
  "expires": 0,
  "duration": "18ms",
  "regionCode": "US",
  "countryCode": 1,
  "country":"Stany Zjednoczone",
  "national": "(212) 867-5309",
  "international": "+1 212-867-5309",
  "e164": "+12128675309",
  "isValid": true,
  "isPossible": true,
  "numberType": "FIXED_LINE_OR_MOBILE",
  "nationalSignificantNumber": "2128675309",
  "rawInput": "+1 212 867 5309",
  "isGeographical": true,
  "areaCode": "212",
  "location": "Nowy Jork (Manhattan)"
}

Wypróbuj API do Weryfikacji Numerów Telefonów

Podstawowe użycie

Wyślij numer telefonu pod poniższy adres URL:

https://api.genderapi.io/api/phone?key=YOUR_API_KEY&number=12128675309

Możesz uzyskać swój codzienny darmowy klucz API z 200 kredytami pod tym linkiem.

Parametr address

API obsługuje również opcjonalny parametr address, który może być bardzo przydatny w przypadkach, gdy numer telefonu jest podany bez międzynarodowego kodu kraju. Pole to pomaga systemowi wykryć zamierzony region i prawidłowo zinterpretować numer. Na przykład, jeśli numer to 2128675309 i nie podano kodu kraju, ustawienie address=US, address=United States lub nawet address=New York pomoże API ustalić, że numer pochodzi ze Stanów Zjednoczonych.

Parametr address akceptuje dane w różnych formatach, w tym:

• Kody ISO 3166-1 alpha-2, takie jak US, DE lub TR
• Nazwy krajów, np. Germany, Turkey, America
• Nazwy miast lub regionów, takie jak Berlin, Istanbul, New York

Chociaż opcjonalny, parametr address staje się obowiązkowy, jeśli numer telefonu nie zaczyna się od znaku plus i kodu międzynarodowego (np. +1, +44, +90). Bez tych informacji kontekstowych API może nie być w stanie prawidłowo zinterpretować formatu numeru krajowego.

Przykład z parametrem address:

https://api.genderapi.io/api/phone?key=YOUR_API_KEY&number=12128675309&address=US

Pola odpowiedzi

Typy numerów

curl "https://api.genderapi.io/api/phone?number=+49 151 12345678&address=United States&key=YOUR_API_KEY"

curl "https://api.genderapi.io/api/phone?number=%2B49%20151%2012345678&address=United%20States&key=YOUR_API_KEY"

Walidacja numeru telefonu za pomocą żądania POST

Możesz użyć metody POST do walidacji numeru telefonu ze Stanów Zjednoczonych. Wystarczy podać numer telefonu w formacie E.164, krajowym lub międzynarodowym wraz z krajem/adresem. Twój klucz API musi zostać przesłany jako token Bearer.

Przykład z użyciem cURL

curl -X POST "https://api.genderapi.io/api/phone" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"number": "+12128675309", "address": "US"}'

Przykład użycia cURL w PHP

<?php
$url = "https://api.genderapi.io/api/phone";

$data = array(
    "number" => "+12128675309",
    "address" => "US"
);

$payload = json_encode($data);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    "Content-Type: application/json",
    "Authorization: Bearer YOUR_API_KEY"
));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

Przykład użycia fetch w JavaScript

fetch("https://api.genderapi.io/api/phone", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
  },
  body: JSON.stringify({
    number: "+12128675309",
    address: "United States"
  })
})
.then(response => response.json())
.then(data => console.log(data));

Przykład użycia biblioteki requests w Pythonie

import requests

url = "https://api.genderapi.io/api/phone"

payload = {
    "number": "+12128675309",
    "address": "United States"
}

headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
}

response = requests.post(url, headers=headers, json=payload)

print(response.json())

Biblioteki klienckie

Aby jeszcze bardziej ułatwić integrację, oferujemy szereg oficjalnych i wspieranych przez społeczność bibliotek klienckich dla różnych języków programowania. Biblioteki te umożliwiają komunikację z endpointami GenderAPI — takimi jak API do Walidacji Numerów Telefonów — bez konieczności ręcznego obsługiwania żądań HTTP czy parsowania JSON. Wystarczy wybrać odpowiednią bibliotekę dla swojego środowiska, zainstalować ją i rozpocząć wysyłanie zapytań przy minimalnej konfiguracji.

Dostępne biblioteki klienckie oraz instrukcje instalacji znajdziesz na poniższej stronie:
https://www.genderapi.io/pl/docs-client-libraries

Najczęściej zadawane pytania (FAQ)

1. Czym jest API do Walidacji i Formatowania Numerów Telefonów?

API to narzędzie, które umożliwia walidację, formatowanie i analizowanie numerów telefonów z całego świata. Może przekształcić numer do standardowego formatu E.164 i określić metadane takie jak region, typ (komórkowy/stacjonarny), ważność i inne.

2. Do czego służy Walidacja Numerów Telefonów?

Służy do sprawdzania, czy numer telefonu jest ważny, formatowania go do użytku międzynarodowego, identyfikacji typu numeru (np. komórkowy, VoIP), wykrywania danych regionalnych oraz zapewnienia czystych i wystandaryzowanych danych wejściowych dla CRM, narzędzi marketingowych lub formularzy rejestracyjnych.

3. Ile krajów jest obsługiwanych?

API obsługuje numery telefonów z 242 krajów i terytoriów na całym świecie. Gwarantuje to globalny zasięg dla każdej aplikacji międzynarodowej lub regionalnej.

4. Jakie formaty są obsługiwane?

API akceptuje numery w różnych formatach, takich jak krajowy, międzynarodowy lub E.164. Automatycznie je wykrywa i normalizuje do prawidłowego formatu.

5. Co się stanie, jeśli pominę parametr kraju lub adresu?

Jeśli numer telefonu nie zaczyna się od znaku „+” i nie podano kraju/adresu, API może nie być w stanie prawidłowo zinterpretować numeru. Zalecane jest podanie parametru address (np. US, United States lub New York).

6. Czy API potrafi wykryć typ numeru?

Tak. API zwraca pole numberType, które wskazuje, czy numer to MOBILE, FIXED_LINE, VOIP itd.

7. Jaka jest różnica między isValid a isPossible?

isValid oznacza, że numer jest oficjalnie przypisany i zgodny z zasadami regionalnymi. isPossible oznacza, że numer może teoretycznie istnieć na podstawie swojej struktury, nawet jeśli nie został jeszcze przypisany.

8. Jaką odpowiedź zwraca API?

Prawidłowa odpowiedź zawiera status, różne formaty numerów (krajowy, międzynarodowy, E.164), dane regionalne, typ numeru, zużycie kredytów i więcej. Przykład pełnej odpowiedzi znajduje się w sekcji z przykładem odpowiedzi API.

9. Jak powinienem przesłać swój klucz API?

Dla zapytań GET dołącz klucz jako ?key=YOUR_API_KEY. Dla zapytań POST użyj nagłówka Bearer token w ten sposób:
"Authorization: Bearer YOUR_API_KEY".

10. Co jeśli otrzymam odpowiedź status: false?

Oznacza to, że żądanie zakończyło się niepowodzeniem. Pole message zawiera szczegółowy powód błędu, taki jak brakujące parametry, nieprawidłowy numer telefonu lub niewystarczająca liczba kredytów.

11. Czy znaki specjalne lub spacje są dozwolone w danych wejściowych?

Tak, ale muszą być zakodowane w formacie URL w przypadku zapytań GET. Na przykład zamiast spacji użyj %20. Poprawne użycie opisano w sekcji ostrzeżenia powyżej.

12. Czy mogę używać adresów w różnych formatach lub językach?

Tak. Oprócz kodów ISO 3166-1 alpha-2 (takich jak US, DE, TR), parametr address akceptuje również pełne nazwy krajów lub miast — nawet w różnych językach. API wykorzystuje wbudowaną sztuczną inteligencję, aby inteligentnie wykryć i zinterpretować właściwy kraj lub region. Na przykład:

address=Deutschland
address=États-Unis
address=İstanbul
address=New York
address=Estados Unidos

Wszystkie te dane wejściowe zostaną prawidłowo zmapowane na odpowiednie kraje lub regiony przez API bez żadnych problemów.