# 📞 Phone Number Validation & Formatter API (Python SDK)
The `phone-validator` library uses the official [GenderAPI Phone Number Validation & Formatter API](https://www.genderapi.io) to validate and format phone numbers from over 240 countries.
Whether your users enter phone numbers in various formats (e.g., `12128675309`, `+1 212 867 5309`, `001–212–867–5309`), this SDK intelligently detects, validates, and converts them into the standardized E.164 format (e.g., `+12128675309`).
---
## ✅ 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:
```bash
pip install phone-validator
```
Or manually from GitHub:
```bash
git clone https://github.com/GenderAPI/phone-validator-python.git
cd phone-validator-python
pip install .
```
---
## 🚀 Usage
```python
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="+1 212 867 5309", 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:**
```python
validator.validate("2128675309", "US")
```
---
## 🌐 API Response
```json
{
"status": true,
"remaining_credits": 15709,
"expires": 0,
"duration": "18ms",
"regionCode": "US",
"countryCode": 1,
"country": "United 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)"
}
```
---
## 📘 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](./LICENSE) file for details.
---
## 🌍 Links
- 🧪 [API Playground](https://www.genderapi.io/docs-phone-validation-formatter-api)
Raw data
{
"_id": null,
"home_page": null,
"name": "genderapi-phone-validator",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "gender, genderapi, phone validator, phone validation, phone number formatting, phone metadata, E.164, API client, python sdk",
"author": null,
"author_email": "Onur Ozturk <support@genderapi.io>",
"download_url": "https://files.pythonhosted.org/packages/41/f0/fa45577ae7d3fb5d8a001e3d8a8022b0fa95e7eb6e8eab9acd541d40b414/genderapi_phone_validator-1.0.2.tar.gz",
"platform": null,
"description": "# \ud83d\udcde Phone Number Validation & Formatter API (Python SDK)\n\nThe `phone-validator` library uses the official [GenderAPI Phone Number Validation & Formatter API](https://www.genderapi.io) to validate and format phone numbers from over 240 countries.\n\nWhether your users enter phone numbers in various formats (e.g., `12128675309`, `+1 212 867 5309`, `001\u2013212\u2013867\u20135309`), this SDK intelligently detects, validates, and converts them into the standardized E.164 format (e.g., `+12128675309`).\n\n---\n\n## \u2705 Features\n\n- Converts phone numbers to **E.164** format \n- Validates if number is real and structurally possible \n- Detects number type: mobile, landline, VoIP, etc. \n- Identifies region/city based on area code \n- Includes country-level metadata (e.g. ISO code, carrier, city) \n- Built with Python, uses the `requests` package \n\n---\n\n## \ud83d\udd27 Installation\n\nInstall via pip:\n\n```bash\npip install phone-validator\n```\n\nOr manually from GitHub:\n\n```bash\ngit clone https://github.com/GenderAPI/phone-validator-python.git\ncd phone-validator-python\npip install .\n```\n\n---\n\n## \ud83d\ude80 Usage\n\n```python\nfrom phone_validator import PhoneValidator\n\n# Replace with your actual API key\nAPI_KEY = \"YOUR_API_KEY\"\n\nvalidator = PhoneValidator(api_key=API_KEY)\n\nresult = validator.validate(number=\"+1 212 867 5309\", address=\"US\")\n\nprint(result)\n```\n\n---\n\n## \ud83e\uddfe Input Parameters\n\n### `validate(number, address=None)`\n\n| Parameter | Type | Required | Description |\n|-----------|--------|----------|-----------------------------------------------------------------------------|\n| number | string | \u2705 Yes | Phone number in any format |\n| address | string | Optional | ISO country code (`US`), full country name (`Turkey`), or city name (`Berlin`) \u2014 helps resolve local numbers |\n\n**Example:**\n\n```python\nvalidator.validate(\"2128675309\", \"US\")\n```\n\n---\n\n## \ud83c\udf10 API Response\n\n```json\n{\n \"status\": true,\n \"remaining_credits\": 15709,\n \"expires\": 0,\n \"duration\": \"18ms\",\n \"regionCode\": \"US\",\n \"countryCode\": 1,\n \"country\": \"United States\",\n \"national\": \"(212) 867-5309\",\n \"international\": \"+1 212-867-5309\",\n \"e164\": \"+12128675309\",\n \"isValid\": true,\n \"isPossible\": true,\n \"numberType\": \"FIXED_LINE_OR_MOBILE\",\n \"nationalSignificantNumber\": \"2128675309\",\n \"rawInput\": \"+1 212 867 5309\",\n \"isGeographical\": true,\n \"areaCode\": \"212\",\n \"location\": \"New York City (Manhattan)\"\n}\n```\n\n---\n\n## \ud83d\udcd8 Response Field Reference\n\n| Field | Description |\n|---------------------------|----------------------------------------------------------|\n| `e164` | Number formatted in E.164 standard |\n| `isValid`, `isPossible` | Validity and structure confirmation |\n| `numberType` | Type of line: mobile, landline, VoIP, etc. |\n| `country`, `regionCode` | Country name and ISO code |\n| `location`, `areaCode` | Geo-location details based on number |\n| `carrier` | Carrier (if available) |\n| `rawInput`, `national` | Original and normalized formats |\n| `remaining_credits` | API credits left in your account |\n\n---\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the terms of the MIT license. \nSee the [LICENSE](./LICENSE) file for details.\n\n---\n\n## \ud83c\udf0d Links\n\n- \ud83e\uddea [API Playground](https://www.genderapi.io/docs-phone-validation-formatter-api)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Official Python SDK for validating and formatting phone numbers using the GenderAPI.io service.",
"version": "1.0.2",
"project_urls": {
"Documentation": "https://www.genderapi.io/docs-phone-validation-formatter-api",
"Homepage": "https://www.genderapi.io",
"Issues": "https://github.com/GenderAPI/phone-validator-python/issues",
"Repository": "https://github.com/GenderAPI/phone-validator-python"
},
"split_keywords": [
"gender",
" genderapi",
" phone validator",
" phone validation",
" phone number formatting",
" phone metadata",
" e.164",
" api client",
" python sdk"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "0a63287580ccc8ae50ad29d2efec9bef8917aac75e648d4c49c77f52b26dda21",
"md5": "500f60d3e582313a1041e2f2774ad5dd",
"sha256": "1e58c0bd5e73d8d5bb620aad964be921797fb73fd8f5a3dd2d9c01a2e33e3177"
},
"downloads": -1,
"filename": "genderapi_phone_validator-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "500f60d3e582313a1041e2f2774ad5dd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 5118,
"upload_time": "2025-08-03T10:55:59",
"upload_time_iso_8601": "2025-08-03T10:55:59.512340Z",
"url": "https://files.pythonhosted.org/packages/0a/63/287580ccc8ae50ad29d2efec9bef8917aac75e648d4c49c77f52b26dda21/genderapi_phone_validator-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "41f0fa45577ae7d3fb5d8a001e3d8a8022b0fa95e7eb6e8eab9acd541d40b414",
"md5": "6f3d06bc80cdd2ff947cf6eb3d80e2a3",
"sha256": "ba88c4c34bedc96b3900974e066b54c4165518e889661b9468c638b746e75b86"
},
"downloads": -1,
"filename": "genderapi_phone_validator-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "6f3d06bc80cdd2ff947cf6eb3d80e2a3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 4850,
"upload_time": "2025-08-03T10:56:00",
"upload_time_iso_8601": "2025-08-03T10:56:00.684882Z",
"url": "https://files.pythonhosted.org/packages/41/f0/fa45577ae7d3fb5d8a001e3d8a8022b0fa95e7eb6e8eab9acd541d40b414/genderapi_phone_validator-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-03 10:56:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "GenderAPI",
"github_project": "phone-validator-python",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "requests",
"specs": [
[
">=",
"2.28.0"
],
[
"<",
"3.0.0"
]
]
}
],
"lcname": "genderapi-phone-validator"
}
JSON
