Metadata-Version: 2.4
Name: ipspot
Version: 0.5
Summary: IPSpot: A Python Tool to Fetch the System's IP Address
Home-page: https://github.com/openscilab/ipspot
Download-URL: https://github.com/openscilab/ipspot/tarball/v0.5
Author: IPSpot Development Team
Author-email: ipspot@openscilab.com
License: MIT
Project-URL: Source, https://github.com/openscilab/ipspot
Keywords: ip ipv4 geo geolocation network location ipspot cli
Classifier: Development Status :: 3 - Alpha
Classifier: Natural Language :: English
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: End Users/Desktop
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: System :: Networking :: Monitoring
Classifier: Topic :: Utilities
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: AUTHORS.md
Requires-Dist: art>=5.3
Requires-Dist: requests>=2.20.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: download-url
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary


<div align="center">
<img src="https://github.com/openscilab/ipspot/raw/main/otherfiles/logo.png" width="350">
<h1>IPSpot: A Python Tool to Fetch the System's IP Address</h1>
<br/>
<a href="https://badge.fury.io/py/ipspot"><img src="https://badge.fury.io/py/ipspot.svg" alt="PyPI version"></a>
<a href="https://www.python.org/"><img src="https://img.shields.io/badge/built%20with-Python3-green.svg" alt="built with Python3"></a>
<a href="https://github.com/openscilab/ipspot"><img alt="GitHub repo size" src="https://img.shields.io/github/repo-size/openscilab/ipspot"></a>
<a href="https://discord.gg/yyDV3T4cwU"><img src="https://img.shields.io/discord/1064533716615049236.svg" alt="Discord Channel"></a>
</div>			
				
## Overview	

<p align="justify">					
<b>IPSpot</b> is a Python library for retrieving the current system's IP address and location information. It currently supports public and private <b>IPv4</b> detection using multiple API providers with a fallback mechanism for reliability. Designed with simplicity and modularity in mind, <b>IPSpot</b> offers quick IP and geolocation lookups directly from your machine.
</p>

<table>
	<tr>
		<td align="center">PyPI Counter</td>
		<td align="center"><a href="http://pepy.tech/project/ipspot"><img src="http://pepy.tech/badge/ipspot"></a></td>
	</tr>
	<tr>
		<td align="center">Github Stars</td>
		<td align="center"><a href="https://github.com/openscilab/ipspot"><img src="https://img.shields.io/github/stars/openscilab/ipspot.svg?style=social&label=Stars"></a></td>
	</tr>
</table>



<table>
	<tr> 
		<td align="center">Branch</td>
		<td align="center">main</td>	
		<td align="center">dev</td>	
	</tr>
	<tr>
		<td align="center">CI</td>
		<td align="center"><img src="https://github.com/openscilab/ipspot/actions/workflows/test.yml/badge.svg?branch=main"></td>
		<td align="center"><img src="https://github.com/openscilab/ipspot/actions/workflows/test.yml/badge.svg?branch=dev"></td>
	</tr>
</table>

<table>
	<tr> 
		<td align="center">Code Quality</td>
		<td align="center"><a href="https://app.codacy.com/gh/openscilab/ipspot/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade"><img src="https://app.codacy.com/project/badge/Grade/cb2ab6584eb443b8a33da4d4252480bc"/></a></td>
		<td align="center"><a href="https://www.codefactor.io/repository/github/openscilab/ipspot"><img src="https://www.codefactor.io/repository/github/openscilab/ipspot/badge" alt="CodeFactor"></a></td>
	</tr>
</table>


## Installation		

### Source Code
- Download [Version 0.5](https://github.com/openscilab/ipspot/archive/v0.5.zip) or [Latest Source](https://github.com/openscilab/ipspot/archive/dev.zip)
- `pip install .`				

### PyPI

- Check [Python Packaging User Guide](https://packaging.python.org/installing/)     
- `pip install ipspot==0.5`						


## Usage

### Library

#### Public IPv4

```pycon
>>> from ipspot import get_public_ipv4, IPv4API
>>> get_public_ipv4(api=IPv4API.IP_API_COM)
{'status': True, 'data': {'ip': 'xx.xx.xx.xx', 'api': 'ip-api.com'}}
>>> get_public_ipv4(api=IPv4API.IP_API_COM, geo=True, timeout=10)
{'data': {'country_code': 'GB', 'latitude': 50.9097, 'longitude': -1.4043, 'api': 'ip-api.com', 'country': 'United Kingdom', 'timezone': 'Europe/London', 'organization': '', 'region': 'England', 'ip': 'xx.xx.xx.xx', 'city': 'Southampton'}, 'status': True}
>>> get_public_ipv4(api=IPv4API.IP_API_COM, geo=True, timeout=10, max_retries=5, retry_delay=4)
{'data': {'country_code': 'GB', 'latitude': 50.9097, 'longitude': -1.4043, 'api': 'ip-api.com', 'country': 'United Kingdom', 'timezone': 'Europe/London', 'organization': '', 'region': 'England', 'ip': 'xx.xx.xx.xx', 'city': 'Southampton'}, 'status': True}
```

#### Private IPv4

```pycon
>>> from ipspot import get_private_ipv4
>>> get_private_ipv4()
{'status': True, 'data': {'ip': '10.36.18.154'}}
```

#### Public IPv6

```pycon
>>> from ipspot import get_public_ipv6, IPv6API
>>> get_public_ipv6(api=IPv6API.IP_SB)
{'data': {'api': 'ip.sb', 'ip': 'xx:xx:xx:xx::xx'}, 'status': True}
>>> get_public_ipv6(api=IPv6API.IP_SB, geo=True, timeout=10)
{'data': {'latitude': 51.2993, 'region': None, 'city': None, 'country_code': 'DE', 'api': 'ip.sb', 'longitude': 9.491, 'country': 'Germany', 'organization': 'Hetzner Online', 'timezone': 'Europe/Berlin', 'ip': 'xx:xx:xx:xx::xx'}, 'status': True}
>>> get_public_ipv6(api=IPv6API.IP_SB, geo=True, timeout=10, max_retries=5, retry_delay=4)
{'data': {'latitude': 51.2993, 'region': None, 'city': None, 'country_code': 'DE', 'api': 'ip.sb', 'longitude': 9.491, 'country': 'Germany', 'organization': 'Hetzner Online', 'timezone': 'Europe/Berlin', 'ip': 'xx:xx:xx:xx::xx'}, 'status': True}
```

#### Private IPv6

```pycon
>>> from ipspot import get_private_ipv6
>>> get_private_ipv6()
{'status': True, 'data': {'ip': 'fe80::e1bd:f78:b233:21c9'}}
```

### CLI

ℹ️ You can use `ipspot` or `python -m ipspot` to run this program

#### Version

```console
> ipspot --version

0.5
```

#### Info

```console
> ipspot --info

 ___  ____   ____                 _
|_ _||  _ \ / ___|  _ __    ___  | |_
 | | | |_) |\___ \ | '_ \  / _ \ | __|
 | | |  __/  ___) || |_) || (_) || |_
|___||_|    |____/ | .__/  \___/  \__|
                   |_|

__     __     ___      ____
\ \   / / _  / _ \    | ___|
 \ \ / / (_)| | | |   |___ \
  \ V /   _ | |_| | _  ___) |
   \_/   (_) \___/ (_)|____/



IPSpot is a Python library for retrieving the current system's IP address and location information.
It currently supports public and private IPv4 detection using multiple API providers with a fallback mechanism for reliability.
Designed with simplicity and modularity in mind, IPSpot offers quick IP and geolocation lookups directly from your machine.

Repo : https://github.com/openscilab/ipspot

```

#### Basic

```console
> ipspot
Private IP:

  IPv4: 192.168.1.35

  IPv6: fe80::e1bd:f78:b233:21c9

Public IP and Location Info:

  API: ip-api.com
  City: Southampton
  Country: United Kingdom
  Country Code: GB
  IP: xx.xx.xx.xx
  Latitude: 50.9097
  Longitude: -1.4043
  Organization: N/A
  Region: England
  Timezone: Europe/London
```

#### IPv4 API

ℹ️ `ipv4-api` valid choices: [`auto-safe`, `auto`, `ip-api.com`, `ipinfo.io`, `ip.sb`, `ident.me`, `tnedi.me`, `ipapi.co`, `ipleak.net`, `my-ip.io`, `ifconfig.co`, `reallyfreegeoip.org`, `freeipapi.com`, `myip.la`, `ipquery.io`, `ipwho.is`, `wtfismyip.com`]

ℹ️ The default value: `auto-safe`

```console
> ipspot --ipv4-api="ipinfo.io"
Private IP:

  IPv4: 192.168.1.35

  IPv6: fe80::e1bd:f78:b233:21c9

Public IP and Location Info:

  IPv4:

    API: ipinfo.io
    City: Nuremberg
    Country: Germany
    Country Code: DE
    IP: xx.xx.xx.xx
    Latitude: 49.4527
    Longitude: 11.0783
    Organization: Hetzner Online GmbH
    Region: Bavaria
    Timezone: Europe/Berlin

  IPv6:

    API: ip.sb
    City: N/A
    Country: Germany
    Country Code: DE
    IP: xx:xx:xx:xx::xx
    Latitude: 51.2993
    Longitude: 9.491
    Organization: Hetzner Online
    Region: N/A
    Timezone: Europe/Berlin
```

#### IPv6 API

ℹ️ `ipv6-api` valid choices: [`auto-safe`, `auto`, `ip.sb`, `ident.me`, `tnedi.me`, `ipleak.net`, `my-ip.io`]

ℹ️ The default value: `auto-safe`

```console
> ipspot --ipv6-api="ip.sb"
Private IP:

  IPv4: 192.168.1.35

  IPv6: fe80::e1bd:f78:b233:21c9

Public IP and Location Info:

  IPv4:

    API: ipinfo.io
    City: Nuremberg
    Country: Germany
    Country Code: DE
    IP: xx.xx.xx.xx
    Latitude: 49.4527
    Longitude: 11.0783
    Organization: Hetzner Online GmbH
    Region: Bavaria
    Timezone: Europe/Berlin

  IPv6:

    API: ip.sb
    City: N/A
    Country: Germany
    Country Code: DE
    IP: xx:xx:xx:xx::xx
    Latitude: 51.2993
    Longitude: 9.491
    Organization: Hetzner Online
    Region: N/A
    Timezone: Europe/Berlin
```

#### No Geolocation

```console
> ipspot --no-geo
Private IP:

  IPv4: 192.168.1.35

  IPv6: fe80::5c40:769f:22de:c196

Public IP:

  IPv4:

    API: tnedi.me
    IP: xx.xx.xx.xx

  IPv6:

    API: ip.sb
    IP: xx:xx:xx:xx::xx
```

## Issues & Bug Reports			

Just fill an issue and describe it. We'll check it ASAP!

- Please complete the issue template

You can also join our discord server

<a href="https://discord.gg/yyDV3T4cwU">
  <img src="https://img.shields.io/discord/1064533716615049236.svg?style=for-the-badge" alt="Discord Channel">
</a>

## Show Your Support
								
<h3>Star This Repo</h3>					

Give a ⭐️ if this project helped you!

<h3>Donate to Our Project</h3>	

If you do like our project and we hope that you do, can you please support us? Our project is not and is never going to be working for profit. We need the money just so we can continue doing what we do ;-)			

<a href="https://openscilab.com/#donation" target="_blank"><img src="https://github.com/openscilab/ipspot/raw/main/otherfiles/donation.png" height="90px" width="270px" alt="IPSpot Donation"></a>


# Changelog
All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).

## [Unreleased]
## [0.5] - 2025-10-17
### Added
- `setup-warp` action
- Support [ipwho.is](https://ipwho.is/)
- Support [ipquery.io](http://api.ipquery.io/?format=json)
- Support [wtfismyip.com](https://wtfismyip.com/json)
- Support [ident.me](https://ident.me/json) IPv6 API
- Support [tnedi.me](https://tnedi.me/json) IPv6 API
- Support [ip.sb](https://api.ip.sb/geoip) IPv6 API
- Support [ipleak.net](https://ipleak.net/json/) IPv6 API
- Support [my-ip.io](https://www.my-ip.io/) IPv6 API
- `is_ipv6` function
- `get_private_ipv6` function
- `get_public_ipv6` function
- `IPv6API` enum
- `--ipv6-api` argument
### Changed
- Test system modified
- `README.md` updated
## [0.4] - 2025-06-09
### Added
- Support [ipapi.co](https://ipapi.co/json/)
- Support [ipleak.net](https://ipleak.net/json/)
- Support [my-ip.io](https://www.my-ip.io/)
- Support [ifconfig.co](https://ifconfig.co/json)
- Support [reallyfreegeoip.org](https://reallyfreegeoip.org/json/)
- Support [myip.la](https://api.myip.la/en?json)
- Support [freeipapi.com](https://freeipapi.com/api/json/)
- `AUTO_SAFE` mode
- `_get_json_standard` function
- `_get_json_ipv4_forced` function
- `--max-retries` argument
- `--retry-delay` argument
### Changed
- `IPv4API.IPAPI` renamed to `IPv4API.IP_API_COM`
- `IPv4API.IPINFO` renamed to `IPv4API.IPINFO_IO`
- `IPv4API.IPSB` renamed to `IPv4API.IP_SB`
- `IPv4API.IDENTME` renamed to `IPv4API.IDENT_ME`
- `IPv4API.TNEDIME` renamed to `IPv4API.TNEDI_ME`
- `get_public_ipv4` function modified
- `filter_parameter` function renamed to `_filter_parameter`
- `README.md` updated
## [0.3] - 2025-05-19
### Added
- `is_ipv4` function
- `is_loopback` function
- `IPv4HTTPAdapter` class
- Support [ident.me](https://ident.me/json)
- Support [tnedi.me](https://tnedi.me/json)
### Changed
- `get_private_ipv4` function modified
- `get_public_ipv4` function modified
- `_ipsb_ipv4` function modified
- `_ipapi_ipv4` function modified
- `_ipinfo_ipv4` function modified
- `functions.py` renamed to `utils.py` 
- CLI functions moved to `cli.py`
- IPv4 functions moved to `ipv4.py`
- Test system modified
## [0.2] - 2025-05-04
### Added
- Support [ip.sb](https://api.ip.sb/geoip)
- `--timeout` argument
### Changed
- `README.md` updated
- Requests header updated
- Test system modified
## [0.1] - 2025-04-25
### Added
- Support [ipinfo.io](https://ipinfo.io)
- Support [ip-api.com](https://ip-api.com)
- `get_private_ipv4` function
- `get_public_ipv4` function
- `--info` and `--version` arguments
- `--ipv4-api` argument
- `--no-geo` argument
- Logo

[Unreleased]: https://github.com/openscilab/ipspot/compare/v0.5...dev
[0.5]: https://github.com/openscilab/ipspot/compare/v0.4...v0.5
[0.4]: https://github.com/openscilab/ipspot/compare/v0.3...v0.4
[0.3]: https://github.com/openscilab/ipspot/compare/v0.2...v0.3
[0.2]: https://github.com/openscilab/ipspot/compare/v0.1...v0.2
[0.1]: https://github.com/openscilab/ipspot/compare/3216fb7...v0.1



