Puhelinnumeron validointi- ja muotoilu-API

Phone Validator API on tuettu 242 maassa.

Puhelinnumeron validointi- ja muotoilu-API mahdollistaa käyttäjien syöttämien puhelinnumeroiden helpon käsittelyn riippumatta niiden kirjoitusmuodosta. Olipa syöte niin epäsäännöllinen kuin 1(212)-867-53-09, +1 212 8675309, 001-212.867.5309 tai pelkkä 2128675309, API tunnistaa älykkäästi rakenteen ja palauttaa standardoidun version.

Tämä työkalu muuntaa annetun syötteen automaattisesti E.164-muotoon, joka on kansainvälisesti tunnustettu muoto puhelinnumeroille. Esimerkiksi +1 212 867 5309 palautetaan muodossa +12128675309, mikä sopii kansainvälisiin puhelujärjestelmiin ja integraatioihin.

Muotoilun lisäksi API tarjoaa yksityiskohtaiset puhelinnumeron validointiominaisuudet. Se tarkistaa, onko numero isValid: true — eli onko se kansallisten numerointisuunnitelmien mukaan kelvollinen. Se tarjoaa myös isPossible: true-tarkistuksen, joka osoittaa, voisiko numero mahdollisesti olla olemassa, vaikka se ei olisi tällä hetkellä käytössä. Tämä on hyödyllistä esivalidoinnissa ennen tallentamista tai käsittelyä.

numberType-parametri auttaa tunnistamaan, onko puhelinnumero mobiili-, lankapuhelin- vai VoIP-numero. Tämä on erityisen hyödyllistä tilanteissa, joissa sallitaan vain mobiilinumeroita esimerkiksi SMS-vahvistuksiin tai lankapuhelimia toimistokontakteihin.

Aluekoodin tunnistuksen tuen ansiosta API voi myös tunnistaa numeron maantieteellisen alkuperän. Esimerkiksi aluekoodilla 212 alkava numero yhdistetään automaattisesti New York Cityyn (Manhattan). Tämä ominaisuus on erinomainen sovelluksille, jotka vaativat sijaintiperusteista segmentointia tai analyysiä.

Jokainen numero yhdistetään myös yksityiskohtaiseen maakohtaiseen metadataan, kuten ISO-aluekoodiin (esim. US) ja numeeriseen maakoodiin (esim. 1), mahdollistaen aluekohtaisen logiikan ja esitysmuodot sovelluksissasi.

✅ API-vastaus

Esimerkki JSON-vastauksesta:

{
  "status": true,
  "remaining_credits": 15709,
  "expires": 0,
  "duration": "18ms",
  "regionCode": "US",
  "countryCode": 1,
  "country":"Unites States",
  "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": "New York City (Manhattan)"
}

Kokeile puhelinnumeron validointia itse

Peruskäyttö

Lähetä puhelinnumero seuraavaan päätepisteeseen:

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

Saat päivittäisen ilmaisen API-avaimen, jolla on 200 krediittiä, tästä linkistä.

Address-parametri

API tukee myös valinnaista address-parametria, joka on erittäin hyödyllinen tapauksissa, joissa puhelinnumero annetaan ilman kansainvälistä maakoodia. Tämä kenttä auttaa järjestelmää tunnistamaan tarkoitetun alueen ja jäsentämään numeron oikein. Esimerkiksi jos syötenumero on 2128675309 eikä maakoodia ole annettu, address=US, address=United States tai address=New York auttaa APIa päättelemään, että numero kuuluu Yhdysvaltoihin.

address-parametri hyväksyy useita muotoja, mukaan lukien:

• ISO 3166-1 alpha-2 -koodit kuten US, DE tai TR
• Maakunnat kuten Saksa, Turkki tai Amerikka
• Kaupunki- tai aluenimet kuten Berliini, Istanbul tai New York

Vaikka se on valinnainen, address on pakollinen, jos puhelinnumero ei ala plusmerkillä ja kansainvälisellä suuntanumerolla (esim. +1, +44, +90). Ilman tätä kontekstia API ei ehkä pysty tulkitsemaan kansallista numeroformaattia oikein.

Esimerkki address-parametrin käytöstä:

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

Vastauskentät

Numerotyyppien arvot

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"

Puhelinnumeron validointi POST-pyynnöllä

Voit käyttää POST-menetelmää puhelinnumeron validointiin Yhdysvalloissa. Toimita puhelinnumero E.164-, kansallisessa tai kansainvälisessä muodossa sekä maa- tai aluekenttä. API-avaimesi on lähetettävä Bearer-tunnuksena.

cURL-esimerkki

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-esimerkki

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

JavaScript fetch -esimerkki

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

Python requests -esimerkki

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

Asiakaskirjastot

Integraation helpottamiseksi tarjoamme joukon virallisia ja yhteisön tukemia asiakaskirjastoja eri ohjelmointikielille. Näiden kirjastojen avulla voit käyttää GenderAPI:n päätepisteitä — kuten Phone Number Validation API:ta — ilman, että sinun tarvitsee käsitellä HTTP-pyyntöjä tai jäsentää JSON-dataa itse. Valitse vain ympäristöösi sopiva kirjasto, asenna se ja aloita pyyntöjen lähettäminen vähäisellä määrityksellä.

Saatavilla olevat asiakaskirjastot ja asennusohjeet löytyvät seuraavalta sivulta:
https://www.genderapi.io/fi/docs-client-libraries

Usein kysytyt kysymykset (UKK)

1. Mikä on Phone Number Validation & Formatter API?

Phone Number Validation & Formatter API on työkalu, jonka avulla voit validoida, muotoilla ja analysoida puhelinnumeroita ympäri maailmaa. Se voi muuntaa numerot standardoituun E.164-muotoon ja palauttaa metatietoja, kuten alue, tyyppi (mobiili/lankapuhelin), voimassaolo ja paljon muuta.

2. Mihin puhelinnumeron validointia käytetään?

Sillä tarkistetaan, onko puhelinnumero kelvollinen, muotoillaan se kansainväliseen käyttöön, tunnistetaan numerotyyppi (esim. mobiili, VoIP), havaitaan alueellisia metatietoja ja varmistetaan siisti ja yhtenäinen syöte esimerkiksi CRM- tai markkinointityökaluille.

3. Kuinka monta maata on tuettu?

API tukee puhelinnumeroita 242 maasta ja alueelta maailmanlaajuisesti. Tämä takaa globaalin kattavuuden kaikille kansainvälisille tai alueellisille sovelluksille.

4. Mitä formaatteja tuetaan?

API hyväksyy numeroita eri muodoissa, kuten kansallisessa, kansainvälisessä tai E.164-muodossa. Se tunnistaa ja normalisoi ne automaattisesti oikeaan muotoon.

5. Mitä tapahtuu, jos jätän country- tai address-parametrin pois?

Jos puhelinnumero ei ala '+'-merkillä eikä country/address-parametria anneta, API ei välttämättä osaa tulkita numeroa oikein. On suositeltavaa sisällyttää address-parametri (esim. US, United States tai New York).

6. Voiko API tunnistaa numerotyypin?

Kyllä. API palauttaa numberType-kentän, joka kertoo, onko numero esimerkiksi MOBILE, FIXED_LINE, VOIP, jne.

7. Mikä on ero isValid ja isPossible välillä?

isValid tarkoittaa, että numero on virallisesti osoitettu ja täyttää kaikki alueelliset säännöt. isPossible tarkistaa, voisiko numero teoriassa olla olemassa rakenteensa perusteella, vaikka sitä ei olisi vielä otettu käyttöön.

8. Millaisen vastauksen API palauttaa?

Onnistunut vastaus sisältää statuksen, muotoillut numeroversiot (kansallinen, kansainvälinen, E.164), alueelliset tiedot, numerotyypin, käytetyt krediitit ja paljon muuta. Katso esimerkkivastaus API Response -osiossa.

9. Miten API-avain tulisi lähettää?

GET-pyynnöissä liitä avain näin: ?key=YOUR_API_KEY. POST-pyynnöissä käytä Bearer-tunnistetta otsikossa seuraavasti:
"Authorization: Bearer YOUR_API_KEY".

10. Mitä tarkoittaa, jos saan status: false -vastauksen?

Tämä tarkoittaa, että pyyntö epäonnistui. message-kenttä sisältää tarkemman virheselityksen, kuten puuttuvat parametrit, virheellinen puhelinnumero tai riittämättömät krediitit.

11. Sallitaanko erikoismerkit tai välilyönnit syötteessä?

Kyllä, mutta ne on URL-koodattava GET-pyynnöissä. Esimerkiksi käytä %20 välilyönnin sijaan. Katso varoitusosio oikeasta käytöstä.

12. Voinko käyttää osoitteita eri muodoissa tai kielillä?

Kyllä. address-parametri hyväksyy ISO 3166-1 alpha-2 -koodien (kuten US, DE, TR) lisäksi myös kokonaiset maan tai kaupungin nimet – myös eri kielillä. API käyttää sisäänrakennettua tekoälyä tulkitakseen oikean maan tai alueen älykkäästi. Esimerkiksi:

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

Kaikki nämä syötteet kohdistetaan oikein niiden vastaaviin maihin tai alueisiin ilman ongelmia.