A tool to automatically find and categorize Telegram's IP ranges by geolocation.
English ยท ็ฎไฝไธญๆ
Table of Contents
TGeoIP is an automated tool that fetches the latest official IP ranges from Telegram, checks for reachable hosts, and categorizes them by geolocation. The resulting IP lists and CIDR blocks are automatically committed to the geoip branch for easy use.
This project aims to provide an up-to-date, reliable source of categorized Telegram IPs for developers and network administrators.
- ๐ค Fully Automated: Updates hourly via GitHub Actions.
- โก๏ธ Fast & Concurrent: High-concurrency checks with memory-efficient
net/netipbased IP processing, pre-parsed sorting, and streaming file I/O. - ๐ชถ Lightweight: Only one external dependency (
maxminddb-golang). Core IP logic is pure Go stdlib. - ๐ก๏ธ Reliable: Defaults to a TCP port 443 check with HTTP timeouts, more reliable than ICMP ping in cloud environments.
- ๐ Geolocation Lookup: Uses a local MMDB database for fast and offline geo-lookups.
- ๐ Dual-Format Output: Generates both plain IP lists (
US.txt) and aggregated CIDR lists (US-CIDR.txt). - ๐ Retry Mechanism: Implements 3-retry logic with 200ms intervals for better reliability.
- โฑ๏ธ Optimized Timeouts: Uses 3-second timeouts for checks, 30-second timeout for HTTP requests.
- ๐ Dual Check Modes: Support for ICMP-only, TCP-only, or combined ICMP/TCP checks.
- โก Skip Check Option: Bypass connectivity checks for faster processing when needed.
- A GitHub Actions workflow runs on an hourly schedule.
- It downloads the latest Telegram CIDR list and the free IPinfo geo database.
- The Go application processes all IPs, checking for live hosts.
- Results are grouped by country and saved as
.txtfiles. wbxBotautomatically commits the updated files to thegeoipbranch.
The generated data is available on the geoip branch of this repository. This branch contains only the data files for easy integration.
โก๏ธ Go to the geoip branch to view the data
You can use these files directly in your firewall, routing rules, or other applications.
To run this application locally, you need:
- Go (version 1.26+ recommended)
- An
ipinfo_lite.mmdbfile from IPinfo in the project root.
Clone the repository and run:
# Run with default TCP check
go run . -local
# Run with a limit of 1000 IPs for a quick test
go run . -local -limit 1000
# Run using the ICMP ping method
go run . -local -icmp
# Skip connectivity checks for faster processing
go run . -local -skip-check
# Use dual ICMP/TCP check mode (either passes)
go run . -local -full 1
# Use dual ICMP/TCP check mode (both must pass)
go run . -local -full 2
# Combine multiple flags for specific use cases
go run . -local -full 1 -limit 500-local: Enables local mode (usesipinfo_lite.mmdbfrom the current directory).-icmp: Switches the check method from the default TCP dial to ICMP ping.-limit <number>: Limits the number of IPs to check (e.g.,-limit 500).0means no limit.-skip-check: Skips connectivity checks and classifies all expanded IPs (useful for faster processing).-full <mode>: Uses both ICMP and TCP checks together:-full 1: Either ICMP or TCP passes (more lenient)-full 2: Both ICMP and TCP must pass (more strict)
For the GitHub Actions workflow to run, you must set one secret in your repository settings (Settings > Secrets and variables > Actions):
IPINFO_TOKEN: Your API token from ipinfo.io, which is required to download the MMDB database.
Contributions are welcome! Please feel free to open an issue or submit a pull request.
This project is licensed under the GNU General Public License v3.0. See the LICENSE file for details.
Copyright ยฉ 2025-2026 Babywbx.