nameapi-client-python
===================
Python Client for the NameAPI Web Services at https://www.nameapi.org.
There are functional tests that demonstrate how to use this library.
All you need to send requests is your own api key which you can get from nameapi.org.
This library requires at least Python 3.8.
## Library setup
Create virtual environment and activate it:
python -m venv myenv
myenv\Scripts\activate
Install the required libraries:
pip install -r requirements.txt
## Send a ping
This code sends a simple ping to nameapi to test the connection:
```python
client = NameApiClient(None)
response = client.ping() # return the string 'pong'
```
## Input / Output
#### Person input object
Most services accept a 'Person' as input. This person contains a name, and optionally
more data such as gender, birth date etc.
The name can be just a single "full name" string, or it can be composed of multiple
fields like given name, middle name, surname.
This standardized api makes it simple to use different services in a consistent way,
and is very convenient in accepting the data however you have it at hands.
Creating a simple person looks something like this:
```python
name_object = WesternInputPersonNameBuilder().fullname("John F. Kennedy").build()
input_person = NaturalInputPersonBuilder().name(name_object).build()
```
Creating name objects:
```python
name_object_1 = WesternInputPersonNameBuilder() \
.fullname("Petra Müller") \
.build()
name_object_2 = WesternInputPersonNameBuilder() \
.given_name("Petra") \
.surname("Müller") \
.build()
name_object_3 = WesternInputPersonNameBuilder() \
.name_field(NameField("Petra", CommonNameFieldType.GIVENNAME)) \
.name_field(NameField("Müller", CommonNameFieldType.SURNAME)) \
.build()
name_object_4 = InputPersonName([NameField("petra müller", CommonNameFieldType.FULLNAME)])
```
Creating complex input person objects:
```python
input_person = NaturalInputPersonBuilder() \
.name(name_object_1) \
.gender(StoragePersonGender.MALE) \
.add_email("email@example.com") \
.add_tel_number("+5555555") \
.age(BirthDate(year=1999, month=2, day=1))\
.build()
```
#### Result objects
Response from the requests, displayed as json: https://api.nameapi.org/rest/swagger-ui/
Access the link above to see all the return types and their json format.
## Commands
The web service methods are implemented as commands. This brings the advantage that the
command can be passed around and wrapped with other useful goodies such as logging
in a unified way, without the need to put a wrapper around every service.
For more specialized concerns such as auto-retry on failure this concept becomes
a real advantage.
## Name Parser
Name parsing is the process of splitting a full name into its components.
```python
api_key = None # Set your api_key here
client = NameApiClient(api_key)
response = client.person_name_parser(input_person)
```
## Name Genderizer
Name genderizing is the process of identifying the gender based on a person's name.
```python
api_key = None # Set your api_key here
client = NameApiClient(api_key)
response = client.person_genderizer(input_person)
```
## Name Matcher
The Name Matcher compares names and name pairs to discover whether the people could possibly be one and the same person.
This service takes 2 people as input:
```python
api_key = None # Set your api_key here
client = NameApiClient(api_key)
name_object_1 = WesternInputPersonNameBuilder().fullname("John F. Kennedy").build()
input_person_1 = NaturalInputPersonBuilder().name(name_object).build()
name_object_2 = WesternInputPersonNameBuilder().fullname("Jack Kennedy").build()
input_person_2 = NaturalInputPersonBuilder().name(name_object).build()
response = client.person_matcher(input_person_1, input_person_2)
```
## Name Formatter
The Name Formatter displays personal names in the desired form. This includes the order as well as upper and lower case writing.
```python
api_key = None # Set your api_key here
client = NameApiClient(api_key)
response = client.person_name_formatter(input_person)
```
## Risk Detector
Detects various types of possibly fake data in person records.
```python
api_key = None # Set your api_key here
client = NameApiClient(api_key)
response = client.risk_detector(input_person)
```
## Email Name Parser
The Email Name Parser extracts names out of email addresses.
```python
api_key = None # Set your api_key here
client = NameApiClient(api_key)
email_address="daniela.meyer@example.de"
response = client.email_name_parser(email_address)
```
## Disposable Email Address Detector
The DEA-Detector checks email addresses against a list of known "trash domains" such as mailinator.com.
```python
api_key = None # Set your api_key here
client = NameApiClient(api_key)
email_address="someone@10minutemail.com"
response = client.disposable_email_detector(email_address)
```
Raw data
{
"_id": null,
"home_page": "https://www.nameapi.org/",
"name": "nameapi-client-python",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "nameapi, rest nameapi, nameapi client, name parser, name matcher, person risk detector, name genderizer, email name parser, email parser, disposable email detector, dea detector",
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/d4/c1/d989362c77a35a62d9b5bb08e80ed3d971057a8afeff59bff3392bdbe9ef/nameapi-client-python-1.0.1.tar.gz",
"platform": null,
"description": "nameapi-client-python\r\n===================\r\n\r\nPython Client for the NameAPI Web Services at https://www.nameapi.org.\r\n\r\nThere are functional tests that demonstrate how to use this library.\r\n\r\nAll you need to send requests is your own api key which you can get from nameapi.org.\r\n\r\nThis library requires at least Python 3.8.\r\n\r\n\r\n\r\n## Library setup\r\n\r\nCreate virtual environment and activate it:\r\n\r\n python -m venv myenv\r\n myenv\\Scripts\\activate\r\n\r\nInstall the required libraries:\r\n\r\n pip install -r requirements.txt\r\n\r\n\r\n\r\n## Send a ping\r\n\r\nThis code sends a simple ping to nameapi to test the connection:\r\n\r\n\r\n```python\r\nclient = NameApiClient(None)\r\nresponse = client.ping() # return the string 'pong'\r\n```\r\n\r\n## Input / Output\r\n\r\n\r\n#### Person input object\r\n\r\nMost services accept a 'Person' as input. This person contains a name, and optionally\r\nmore data such as gender, birth date etc.\r\nThe name can be just a single \"full name\" string, or it can be composed of multiple\r\nfields like given name, middle name, surname.\r\nThis standardized api makes it simple to use different services in a consistent way,\r\nand is very convenient in accepting the data however you have it at hands.\r\n\r\nCreating a simple person looks something like this:\r\n\r\n```python\r\nname_object = WesternInputPersonNameBuilder().fullname(\"John F. Kennedy\").build()\r\ninput_person = NaturalInputPersonBuilder().name(name_object).build()\r\n```\r\n\r\nCreating name objects:\r\n\r\n```python\r\nname_object_1 = WesternInputPersonNameBuilder() \\\r\n .fullname(\"Petra M\u00fcller\") \\\r\n .build()\r\n\r\nname_object_2 = WesternInputPersonNameBuilder() \\\r\n .given_name(\"Petra\") \\\r\n .surname(\"M\u00fcller\") \\\r\n .build()\r\n\r\nname_object_3 = WesternInputPersonNameBuilder() \\\r\n .name_field(NameField(\"Petra\", CommonNameFieldType.GIVENNAME)) \\\r\n .name_field(NameField(\"M\u00fcller\", CommonNameFieldType.SURNAME)) \\\r\n .build()\r\n\r\nname_object_4 = InputPersonName([NameField(\"petra m\u00fcller\", CommonNameFieldType.FULLNAME)])\r\n```\r\n\r\nCreating complex input person objects:\r\n\r\n```python\r\ninput_person = NaturalInputPersonBuilder() \\\r\n .name(name_object_1) \\\r\n .gender(StoragePersonGender.MALE) \\\r\n .add_email(\"email@example.com\") \\\r\n .add_tel_number(\"+5555555\") \\\r\n .age(BirthDate(year=1999, month=2, day=1))\\\r\n .build()\r\n```\r\n\r\n#### Result objects\r\n\r\nResponse from the requests, displayed as json: https://api.nameapi.org/rest/swagger-ui/\r\n\r\nAccess the link above to see all the return types and their json format.\r\n\r\n\r\n## Commands\r\n\r\nThe web service methods are implemented as commands. This brings the advantage that the\r\ncommand can be passed around and wrapped with other useful goodies such as logging\r\nin a unified way, without the need to put a wrapper around every service.\r\nFor more specialized concerns such as auto-retry on failure this concept becomes\r\na real advantage.\r\n\r\n\r\n\r\n## Name Parser\r\n\r\nName parsing is the process of splitting a full name into its components.\r\n\r\n\r\n```python\r\napi_key = None # Set your api_key here\r\nclient = NameApiClient(api_key)\r\nresponse = client.person_name_parser(input_person)\r\n```\r\n\r\n\r\n## Name Genderizer\r\n\r\nName genderizing is the process of identifying the gender based on a person's name.\r\n\r\n\r\n```python\r\napi_key = None # Set your api_key here\r\nclient = NameApiClient(api_key)\r\nresponse = client.person_genderizer(input_person)\r\n```\r\n\r\n\r\n## Name Matcher\r\n\r\nThe Name Matcher compares names and name pairs to discover whether the people could possibly be one and the same person.\r\n\r\nThis service takes 2 people as input:\r\n\r\n```python\r\napi_key = None # Set your api_key here\r\nclient = NameApiClient(api_key)\r\n\r\nname_object_1 = WesternInputPersonNameBuilder().fullname(\"John F. Kennedy\").build()\r\ninput_person_1 = NaturalInputPersonBuilder().name(name_object).build()\r\nname_object_2 = WesternInputPersonNameBuilder().fullname(\"Jack Kennedy\").build()\r\ninput_person_2 = NaturalInputPersonBuilder().name(name_object).build()\r\n\r\nresponse = client.person_matcher(input_person_1, input_person_2)\r\n```\r\n\r\n\r\n## Name Formatter\r\n\r\nThe Name Formatter displays personal names in the desired form. This includes the order as well as upper and lower case writing.\r\n\r\n```python\r\napi_key = None # Set your api_key here\r\nclient = NameApiClient(api_key)\r\nresponse = client.person_name_formatter(input_person)\r\n```\r\n\r\n## Risk Detector\r\n\r\nDetects various types of possibly fake data in person records.\r\n\r\n```python\r\napi_key = None # Set your api_key here\r\nclient = NameApiClient(api_key)\r\nresponse = client.risk_detector(input_person)\r\n```\r\n\r\n\r\n\r\n## Email Name Parser\r\n\r\nThe Email Name Parser extracts names out of email addresses.\r\n\r\n```python\r\napi_key = None # Set your api_key here\r\nclient = NameApiClient(api_key)\r\nemail_address=\"daniela.meyer@example.de\"\r\nresponse = client.email_name_parser(email_address)\r\n```\r\n\r\n\r\n## Disposable Email Address Detector\r\n\r\nThe DEA-Detector checks email addresses against a list of known \"trash domains\" such as mailinator.com.\r\n\r\n```python\r\napi_key = None # Set your api_key here\r\nclient = NameApiClient(api_key)\r\nemail_address=\"someone@10minutemail.com\"\r\nresponse = client.disposable_email_detector(email_address)\r\n```\r\n\r\n",
"bugtrack_url": null,
"license": null,
"summary": "Python Client for the NameAPI Web Services",
"version": "1.0.1",
"project_urls": {
"Bug Tracker": "https://github.com/optimaize/nameapi-client-python/issues",
"Homepage": "https://www.nameapi.org/",
"Source Code": "https://github.com/optimaize/nameapi-client-python"
},
"split_keywords": [
"nameapi",
" rest nameapi",
" nameapi client",
" name parser",
" name matcher",
" person risk detector",
" name genderizer",
" email name parser",
" email parser",
" disposable email detector",
" dea detector"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d4c1d989362c77a35a62d9b5bb08e80ed3d971057a8afeff59bff3392bdbe9ef",
"md5": "c54464df823c8dc4fe1b0ce5bd2a0790",
"sha256": "eccb3bdb8151aaeae815b5662d497230a9ea9c58eca8352de24481418c1ef065"
},
"downloads": -1,
"filename": "nameapi-client-python-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "c54464df823c8dc4fe1b0ce5bd2a0790",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 36285,
"upload_time": "2024-11-01T14:40:04",
"upload_time_iso_8601": "2024-11-01T14:40:04.266301Z",
"url": "https://files.pythonhosted.org/packages/d4/c1/d989362c77a35a62d9b5bb08e80ed3d971057a8afeff59bff3392bdbe9ef/nameapi-client-python-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-01 14:40:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "optimaize",
"github_project": "nameapi-client-python",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "certifi",
"specs": [
[
"==",
"2024.2.2"
]
]
},
{
"name": "charset-normalizer",
"specs": [
[
"==",
"3.3.2"
]
]
},
{
"name": "idna",
"specs": [
[
"==",
"3.6"
]
]
},
{
"name": "requests",
"specs": [
[
"==",
"2.31.0"
]
]
},
{
"name": "urllib3",
"specs": [
[
"==",
"2.2.1"
]
]
}
],
"lcname": "nameapi-client-python"
}
JSON
