genderapi-phone-validator 1.0.2

Official Python SDK for validating and formatting phone numbers using the GenderAPI.io service.

📞 Phone Number Validation & Formatter API (Python SDK)

The phone-validator library uses the official GenderAPI Phone Number Validation & Formatter API to validate and format phone numbers from over 240 countries.

Whether your users enter phone numbers in various formats (e.g., 12128675309, [phone], 001–212–867–5309), this SDK intelligently detects, validates, and converts them into the standardized E.164 format (e.g., [phone]).

---

✅ Features

• Converts phone numbers to E.164 format
• Validates if number is real and structurally possible
• Detects number type: mobile, landline, VoIP, etc.
• Identifies region/city based on area code
• Includes country-level metadata (e.g. ISO code, carrier, city)
• Built with Python, uses the requests package

---

🔧 Installation

Install via pip:

pip install phone-validator

Or manually from GitHub:

git clone https://github.com/GenderAPI/phone-validator-python.git
cd phone-validator-python
pip install .

---

🚀 Usage

from phone_validator import PhoneValidator

# Replace with your actual API key
API_KEY = "YOUR_API_KEY"

validator = PhoneValidator(api_key=API_KEY)

result = validator.validate(number="[phone]", address="US")

print(result)

---

🧾 Input Parameters

validate(number, address=None)

Parameter	Type	Required	Description
number	string	✅ Yes	Phone number in any format
address	string	Optional	ISO country code (US), full country name (Turkey), or city name (Berlin) — helps resolve local numbers

Example:

validator.validate("2128675309", "US")

---

🌐 API Response

{
  "status": true,
  "remaining_credits": 15709,
  "expires": 0,
  "duration": "18ms",
  "regionCode": "US",
  "countryCode": 1,
  "country": "United States",
  "national": "[phone]",
  "international": "[phone]",
  "e164": "[phone]",
  "isValid": true,
  "isPossible": true,
  "numberType": "FIXED_LINE_OR_MOBILE",
  "nationalSignificantNumber": "2128675309",
  "rawInput": "[phone]",
  "isGeographical": true,
  "areaCode": "212",
  "location": "New York City (Manhattan)"
}

---

📘 Response Field Reference

Field	Description
e164	Number formatted in E.164 standard
isValid, isPossible	Validity and structure confirmation
numberType	Type of line: mobile, landline, VoIP, etc.
country, regionCode	Country name and ISO code
location, areaCode	Geo-location details based on number
carrier	Carrier (if available)
rawInput, national	Original and normalized formats
remaining_credits	API credits left in your account

---

📄 License

This project is licensed under the terms of the MIT license.
See the LICENSE file for details.

---

🌍 Links

• 🧪 API Playground