zhijing-jin/email2country

Python package to look up the country of an email address

email2country (Python Package)

This is an easy-to-use Python package to look up the country given an email address.

• GitHub project: https://github.com/zhijing-jin/email2country.
• PyPI package: pip installemail2country

Installation

Requirement: Python 3

pip install --upgrade git+git://github.com/zhijing-jin/email2country.git

How to Run

(All country names are consistent with ISO 3166-1.)

Function 1: Find the country where the email server is located

>>> from email2country import email2country
>>> email2country('[email protected]')
'United States'

Or you can just use the domain

>>> email2country('connect.hku.hk')
'Hong Kong'

Function 2: Find the country where the institution of this email address is located

>>> from email2country import email2institution_country

>>> email2institution_country('[email protected]')
'United States'

>>> email2institution_country('[email protected]')
[Info] Email domain "gmail.com" is generic. There is no specific country.

>>> email2institution_country('[email protected]')
[Info] Country not found for "gmail.com111"

Function 3: Look up in batches

>>> from email2country import batch_email2institution_country
>>> batch_email2institution_country(['nyu.edu','gmail.com', 'hku.hk'])
['United States', None, 'Hong Kong']

# or you can enable the "enable warning" option:
>>> batch_email2institution_country(['nyu.edu','gmail.com', 'hku.hk'], enable_warning=True)
[Info] Email domain "gmail.com" is generic. There is no specific country.
['United States', None, 'Hong Kong']

# Similarly, you can try email2country lookup
>>> from email2country import batch_email2country
>>> batch_email2country(['nyu.edu','gmail.com', 'hku.hk'])
['United States', 'United States', 'Hong Kong']

Function 4: Customize your own function

You can use the EmailCountryChecker object directly:

>>> from email2country import EmailCountryChecker
>>> checker = EmailCountryChecker()
>>> checker.get_institution_country('hku.hk', enable_warning=True)
'Hong Kong'
>>> # ... Perform your own actions

Or you can use the Email object

>>> from email2country import Email 
>>> addr = '[email protected]'
>>> email = Email(addr)
>>> email.country
'United States'
>>> email.institution_country
'United States'

In Case of Unexpected Outputs

The main mechanism is in EmailCountryChecker > get_country()here.

1. Not distinguishable if domain is in generic_emails (e.g. gmail.com). domain is email_addr.rsplit('@')[-1].strip('.').
2. Return country if code2country[suffix] exists. suffix is domain.rsplit('.')[-1].
3. Return country if uni_domain2country[domain] exists.
4. domain2 is '.'.join(domain.rsplit('.', 2)[-2:]). Return country if uni_domain2country[domain2] exists.
5. Last resort is domain2ip2country(domain), first looking up the IP of the domain, and then look up the country of the IP.

Contact

If you have more questions, feel free to Q&A, or raise a new GitHub issue.

In case of really urgent needs, contact the author Zhijing Jin (Miss).