API Walidacji i Formatowania Numerów Telefonu

Globalna analiza numerów

Jeden numer, spójny format wyniku

Przekaż numer w formacie krajowym, międzynarodowym lub nieregularnym i otrzymaj ustandaryzowane warianty oraz metadane dla 242 krajów i terytoriów.

Dane wejściowe+48 22 307 12 34

Format E.164+48223071234

WalidacjaisValid i isPossible

FormatowanieKrajowe, międzynarodowe i E.164

KlasyfikacjaKomórkowy, stacjonarny, VoIP i inne

LokalizacjaRegion, numer kierunkowy i miejsce

Parametry wejściowe

Numer i kontekst lokalizacji

Parametr	Status	Opis
`number`	Wymagany	Numer telefonu w formacie krajowym, międzynarodowym lub E.164.
`address`	Warunkowy	Kod ISO kraju, nazwa kraju, miasto albo region potrzebny do interpretacji numeru krajowego.

Kiedy parametr address jest wymagany?

Jeśli number nie zaczyna się od + i międzynarodowego numeru kierunkowego, podaj kontekst, np. PL, Polska lub Warszawa.

PLPolskaWarszawaGermanyNew York

GET

Klucz w parametrach URL

Podstawowe zapytanie GET

cURL

curl "https://api.genderapi.io/api/phone?key=YOUR_API_KEY&number=%2B48223071234&address=PL"

Kodowanie URL: Zapisz + jako %2B, a spacje jako %20. Używaj narzędzi URL lub URLSearchParams dostępnych w języku programowania.

POST

Uwierzytelnianie Bearer

Zapytanie POST po stronie serwera

Wyślij numer i opcjonalny adres jako JSON, a klucz API umieść w nagłówku Authorization.

cURL

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

JavaScript

const response = await fetch("https://api.genderapi.io/api/phone", {
  method: "POST", headers: { "Content-Type": "application/json", "Authorization": "Bearer YOUR_API_KEY" },
  body: JSON.stringify({ number: "+48223071234", address: "PL" })
});

Odpowiedź API

Walidacja, formaty i metadane

JSON

{
  "status": true, "remaining_credits": 15709, "expires": 0, "duration": "18ms",
  "regionCode": "PL", "countryCode": 48, "country": "Poland",
  "national": "22 307 12 34", "international": "+48 22 307 12 34", "e164": "+48223071234",
  "isValid": true, "isPossible": true, "numberType": "FIXED_LINE",
  "nationalSignificantNumber": "223071234", "rawInput": "+48 22 307 12 34",
  "isGeographical": true, "areaCode": "22", "location": "Warsaw"
}

Pola odpowiedzi

Pole	Typ	Opis
`status`	boolean	Informuje, czy zapytanie zakończyło się powodzeniem.
`remaining_credits`	integer	Liczba kredytów dostępnych po zapytaniu.
`expires`	integer	Czas wygaśnięcia kredytów jako znacznik UNIX.
`duration`	string	Czas przetwarzania po stronie serwera.
`regionCode`	string	Wykryty kod regionu ISO 3166-1 alpha-2.
`countryCode`	integer	Międzynarodowy numer kierunkowy kraju.
`country`	string	Czytelna nazwa kraju.
`national`	string	Numer sformatowany do użytku krajowego.
`international`	string	Numer sformatowany w zapisie międzynarodowym.
`e164`	string	Kanoniczny zapis zgodny ze standardem E.164.
`isValid`	boolean	Czy numer spełnia reguły numeracji dla regionu.
`isPossible`	boolean	Czy numer może istnieć na podstawie swojej struktury.
`numberType`	string	Wykryta kategoria numeru.
`nationalSignificantNumber`	string	Numer krajowy bez międzynarodowego kodu kraju.
`rawInput`	string	Oryginalny numer przesłany w zapytaniu.
`isGeographical`	boolean	Czy numer można powiązać z obszarem geograficznym.
`areaCode`	string	Wykryty numer kierunkowy obszaru.
`location`	string	Lokalizacja powiązana z numerem kierunkowym.

Klasyfikacja numerów

Wartości pola numberType

FIXED_LINE

Telefon stacjonarny powiązany z lokalizacją.

MOBILE

Numer telefonu komórkowego.

FIXED_LINE_OR_MOBILE

Plan numeracji nie rozróżnia telefonu stacjonarnego i komórkowego.

TOLL_FREE

Bezpłatny numer, za który płaci odbiorca.

PREMIUM_RATE

Numer usługi o podwyższonej opłacie.

SHARED_COST

Koszt połączenia dzielony między rozmówcami.

VOIP

Numer telefonii internetowej VoIP.

PERSONAL_NUMBER

Numer osobisty mogący przekierowywać na inną linię.

PAGER

Numer urządzenia przywoławczego.

UAN

Uniwersalny numer dostępowy używany przez firmę.

VOICEMAIL

Dedykowany numer dostępu do poczty głosowej.

UNKNOWN

Nie udało się ustalić kategorii numeru.

Częste pytania

FAQ dotyczące API telefonu

Co robi API walidacji numerów telefonu?

Sprawdza i normalizuje numery, zwraca format krajowy, międzynarodowy i E.164 oraz — gdy dane są dostępne — region, typ numeru i informacje geograficzne.

Czym różnią się isValid i isPossible?

isValid sprawdza numer według reguł numeracji danego regionu. isPossible wskazuje, że jego struktura może odpowiadać numerowi, nawet gdy nie można potwierdzić pełnej poprawności.

Kiedy parametr address jest wymagany?

Podaj address, gdy numer nie zaczyna się od znaku plus i międzynarodowego numeru kierunkowego. Może to być kod ISO kraju, nazwa kraju, miasto lub region.

Jak przesyłać znaki specjalne?

W parametrach GET zakoduj spacje, znak plus i inne znaki specjalne. W treści JSON POST kodowanie wykonuje klient HTTP.

Następny przewodnik

Monitoruj wykorzystanie i limit

Wykorzystanie i limitPoznaj zasady kredytów i limitów →Biblioteki klienckieZainstaluj bibliotekę do walidacji telefonu →