Ověření a formátování telefonních čísel – API

API pro ověření telefonních čísel je podporováno ve 242 zemích.

API pro ověření a formátování telefonních čísel vám umožňuje snadno zpracovat telefonní čísla zadaná uživateli v různých formátech. Ať už je vstup například 1(212)-867-53-09, +1 212 8675309, 001-212.867.5309 nebo jednoduše 2128675309, naše API inteligentně rozpozná strukturu a vrátí standardizovanou verzi.

Tento nástroj automaticky převede zadané číslo do formátu E.164, což je celosvětově uznávaný formát pro mezinárodní telefonní čísla. Například +1 212 867 5309 se vrátí jako +12128675309, což je vhodné pro mezinárodní telefonní systémy a integrace.

Kromě formátování poskytuje API podrobné možnosti ověření telefonního čísla. Ověřuje, zda je číslo isValid: true, tedy zda je platné podle národních číslovacích plánů. Nabízí také kontrolu isPossible: true, která naznačuje, zda číslo může potenciálně existovat, i když aktuálně není přiřazeno. To je užitečné pro předběžné ověření před uložením nebo zpracováním.

Parametr numberType pomáhá určit, zda je číslo mobilní, pevná linka nebo VoIP. To je zvláště užitečné ve scénářích, kde chcete povolit pouze mobilní čísla pro ověření SMS nebo pevné linky pro firemní kontakty.

Díky podpoře rozpoznání směrového čísla oblasti může API také zjistit geografický původ čísla. Například číslo začínající směrovým kódem 212 je automaticky přiřazeno k New York City (Manhattan). Tato funkce je ideální pro aplikace, které vyžadují segmentaci nebo analýzu podle polohy.

Každé číslo je také spojeno s podrobnými metadaty na úrovni země, jako je regionální kód ISO (např. US) a číselný kód země (např. 1), což umožňuje logiku a formátování specifické pro daný region ve vašich aplikacích.

✅ Odpověď API

Příklad odpovědi ve formátu JSON:

{
  "status": true,
  "remaining_credits": 15709,
  "expires": 0,
  "duration": "18ms",
  "regionCode": "US",
  "countryCode": 1,
  "country":"Spojené státy",
  "national": "(212) 867-5309",
  "international": "+1 212-867-5309",
  "e164": "+12128675309",
  "isValid": true,
  "isPossible": true,
  "numberType": "PEVNÁ_LINKA_NEBO_MOBILNÍ",
  "nationalSignificantNumber": "2128675309",
  "rawInput": "+1 212 867 5309",
  "isGeographical": true,
  "areaCode": "212",
  "location": "New York City (Manhattan)"
}

Vyzkoušejte API pro ověření telefonního čísla

Základní použití

Odešlete telefonní číslo na následující endpoint:

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

Svůj denní bezplatný API klíč se 200 kredity získáte z tohoto odkazu.

Parametr Address

API také podporuje volitelný parametr address, který je velmi užitečný v případech, kdy je telefonní číslo zadáno bez mezinárodní předvolby. Toto pole pomáhá systému rozpoznat zamýšlený region a správně číslo interpretovat. Například pokud je vstupní číslo 2128675309 a není uvedena žádná předvolba, nastavení address=US, address=United States nebo address=New York pomůže API určit, že číslo patří do USA.

Parametr address akceptuje více formátů, včetně:

• kódů ISO 3166-1 alpha-2, jako US, DE nebo TR
• Názvy zemí, jako Germany, Turkey nebo America
• Názvy měst nebo regionů, jako Berlin, Istanbul nebo New York

Přestože je volitelný, address je povinný, pokud telefonní číslo nezačíná znakem plus a mezinárodní předvolbou (např. +1, +44, +90). Bez těchto informací nemusí být API schopno správně interpretovat národní formát čísla.

Příklad s parametrem address:

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

Odpovědní pole

Hodnoty typu čísla

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"

API pro ověření telefonního čísla pomocí POST požadavku

Můžete použít metodu POST pro ověření telefonního čísla ve Spojených státech. Stačí zadat telefonní číslo ve formátu E.164, národním nebo mezinárodním formátu spolu se zemí nebo adresou. Váš API klíč musí být odeslán jako Bearer token.

Příklad s 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"}'

PHP cURL Example

<?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;
?>

Příklad použití JavaScript fetch

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

Příklad použití Python requests

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

Klientské knihovny

Aby byla integrace ještě jednodušší, nabízíme řadu oficiálních a komunitně podporovaných klientských knihoven pro různé programovací jazyky. Tyto knihovny vám umožní pracovat s GenderAPI endpointy — jako je například API pro ověření telefonních čísel — bez nutnosti ručního zpracování HTTP požadavků nebo parsování JSON. Stačí si vybrat vhodnou knihovnu pro své prostředí, nainstalovat ji a můžete začít s minimálním nastavením.

Dostupné klientské knihovny a instrukce k instalaci naleznete na následující stránce:
https://www.genderapi.io/cs/docs-client-libraries

Často kladené otázky (FAQ)

1. Co je Phone Number Validation & Formatter API?

Phone Number Validation & Formatter API je nástroj, který umožňuje ověřovat, formátovat a analyzovat telefonní čísla z celého světa. Umí převést čísla do standardizovaného formátu E.164 a zjistit metadata jako region, typ (mobilní/pevná linka), platnost a další.

2. K čemu slouží ověření telefonního čísla?

Slouží ke kontrole, zda je telefonní číslo platné, formátování pro mezinárodní použití, identifikaci typu čísla (např. mobilní, VoIP), detekci metadat na základě regionu a zajištění čistého a standardizovaného vstupu pro CRM, marketingové nástroje nebo registrace uživatelů.

3. Kolik zemí je podporováno?

API podporuje telefonní čísla ze 242 zemí a území po celém světě. To zajišťuje globální pokrytí pro jakoukoli mezinárodní nebo regionální aplikaci.

4. Jaké formáty jsou podporovány?

API přijímá čísla v různých formátech jako národní, mezinárodní nebo E.164. Automaticky je detekuje a normalizuje do správného formátu.

5. Co se stane, když vynechám parametr country nebo address?

Pokud telefonní číslo nezačíná znakem '+' a není zadán žádný parametr country/address, API nemusí být schopno číslo správně interpretovat. Doporučuje se přidat parametr address (např. US, United States, nebo New York).

6. Umí API detekovat typ čísla?

Ano. API vrací pole numberType, které určuje, zda se jedná o MOBILE, FIXED_LINE, VOIP atd.

7. Jaký je rozdíl mezi isValid a isPossible?

isValid znamená, že číslo je oficiálně přidělené a odpovídá všem regionálním pravidlům. isPossible kontroluje, zda číslo může teoreticky existovat na základě své struktury, i když ještě není přiděleno.

8. Jaký typ odpovědi API vrací?

Úspěšná odpověď obsahuje status, varianty formátovaných čísel (národní, mezinárodní, E.164), údaje o regionu, typ čísla, využití kreditů a další. Kompletní příklad odpovědi najdete v sekci Příklad odpovědi API.

9. Jak mám poslat svůj API klíč?

U GET požadavků přidejte klíč jako ?key=YOUR_API_KEY. U POST požadavků použijte Bearer token v hlavičce takto:
"Authorization: Bearer YOUR_API_KEY".

10. Co když se mi vrátí odpověď status: false?

To znamená, že požadavek selhal. Pole message bude obsahovat podrobný důvod chyby, například chybějící parametry, neplatné telefonní číslo nebo nedostatek kreditů.

11. Jsou ve vstupu povoleny speciální znaky nebo mezery?

Ano, ale musí být u GET požadavků URL-kódované. Například místo mezery použijte %20. Správné použití najdete v sekci upozornění výše.

12. Mohu použít adresy v různých formátech nebo jazycích?

Ano. Kromě kódů ISO 3166-1 alpha-2 (např. US, DE, TR) parametr address akceptuje také celé názvy zemí nebo měst — i v různých jazycích. API využívá vestavěnou AI k inteligentní detekci a interpretaci správné země nebo regionu. Například:

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

Všechny tyto vstupy budou správně mapovány na příslušné země nebo regiony bez problémů.