IP2Location.io Jupyter Notebook Examples

A collection of 10 practical Jupyter notebooks demonstrating how to use the IP2Location.io API with Python. The examples cover IP geolocation, website analytics, cybersecurity, content localization, marketing, geofencing, and network intelligence.

Each example is self-contained, with its own README.md, notebook, and sample input file(s) where needed. You can explore a notebook interactively in JupyterLab or execute it from the terminal.

Notebook examples

#	Example	What you'll learn	Notebook
01	Basic IP Geolocation Lookup	Look up one IP address and inspect the API response.	Open
02	Batch IP Lookup from CSV	Enrich a CSV of IP addresses while avoiding duplicate requests.	Open
03	Website Visitor Geolocation	Analyze Apache/Nginx access logs by visitor geography.	Open
04	VPN, Proxy, and Tor Detection	Review available anonymous-network and security signals.	Open
05	Suspicious Login Detection	Investigate country changes and possible impossible travel.	Open
06	Website Content Localization	Suggest language, currency, and regional content from an IP location.	Open
07	Geographic Audience Segmentation	Compare website traffic, conversions, and revenue by market.	Open
08	International Campaign Scheduling	Plan send times across time zones with daylight-saving awareness.	Open
09	Geofencing and Regional Access Control	Evaluate country/region policies with allow, deny, and review results.	Open
10	Network and ISP Intelligence	Analyze ASN, ISP, network types, and traffic distribution.	Open

Requirements

• Python 3.9 or newer
• Internet access for live API lookups
• An IP2Location.io API key for authenticated lookups (optional for supported keyless requests)
• JupyterLab and the Python packages used by the examples

Getting started

1. Clone the repository:

git clone https://github.com/ip2location/ip2location-io-notebook-examples.git
cd ip2location-io-notebook-examples

2. Create and activate a virtual environment (recommended):

macOS / Linux:

python3 -m venv .venv
source .venv/bin/activate

Windows PowerShell:

python -m venv .venv
.\.venv\Scripts\Activate.ps1

3. Install the dependencies:

python -m pip install jupyterlab nbconvert ipykernel requests pandas matplotlib tzdata

4. Open an example notebook:

cd 01_basic_ip_lookup
python -m jupyter lab 01_ip2locationio_basic_ip_lookup.ipynb

To run a notebook entirely from the terminal, without starting JupyterLab, use nbconvert in the example's directory:

python -m jupyter nbconvert --to notebook --execute --ExecutePreprocessor.timeout=600 --output executed_01.ipynb 01_ip2locationio_basic_ip_lookup.ipynb

The executed copy saves cell outputs. Replace the notebook filename with the example you want to run, and keep its sample input files in the same directory. See each example's README.md for its exact command, settings, and output files.

API key configuration

Set your API key as an environment variable before starting JupyterLab or running the notebook:

macOS / Linux:

export IP2LOCATION_API_KEY="YOUR_API_KEY"
export IP2LOCATION_IO_API_KEY="YOUR_API_KEY"

Windows PowerShell:

$env:IP2LOCATION_API_KEY="YOUR_API_KEY"
$env:IP2LOCATION_IO_API_KEY="YOUR_API_KEY"

Most notebooks read IP2LOCATION_API_KEY; examples 04 and 05 read IP2LOCATION_IO_API_KEY. Both variables may contain the same key. Never commit real API keys to GitHub.

Demo mode and live mode

• Examples 01–03 make live API requests when executed and require internet access.
• Examples 04–10 default to MODE = "demo", using explicitly synthetic data without calling the API. To query real IP addresses, change the configuration cell to MODE = "live" and rerun the notebook.
• Some API response fields, such as detailed proxy, ISP, or time-zone information, depend on the subscription plan. Notebooks handle missing fields where applicable.
• Live queries may count toward your API usage limits. Review each notebook's maximum lookup setting before processing larger files.

Data and results

Sample CSV and log files are provided for learning and testing. Many notebooks generate CSV reports, summary tables, or charts; output locations are documented in their individual READMEs. Demo-mode results are illustrative, not real IP2Location.io lookups.

Note: IP geolocation provides an estimated network location, not a device's GPS position. Security flags, impossible-travel indicators, and geofencing examples are intended as demonstrations and should not be used as the sole basis for high-impact decisions.

Resources

• IP2Location.io website
• IP2Location.io API documentation
• IP2Location GitHub organization

Questions or suggestions? Open an issue in this repository.