Universal Lookup is a high-performance intelligence service that aggregates multiple APIs for phone numbers, IP addresses, emails, locations, and parcels. It features smart response merging, multi-layered caching, and a premium web interface.
- 🚀 Instant Execution: Run via
npxwithout any setup. - 🔄 Multi-Provider Aggregation: Merges results from dozens of sources (Tellows, MaxMind, Google, etc.).
- 📦 Multi-Arch Docker: Native support for ARM64 (Apple Silicon), ARMv7 (RPi), AMD64, and x86.
- ⚡ Smart Caching: Persistent SQLite storage with configurable TTL per data type.
- 🎨 Premium UI: Modern dark-mode web interface for real-time lookups.
- 📖 OpenAPI 3.0: Fully documented REST API with Swagger UI.
- 🏠 Unraid Ready: Optimized for Unraid with Community Applications templates.
Run the server instantly from any terminal:
npx universal-lookupNote: Ensure you have Node.js 20+ installed.
Pull the multi-arch image from GitHub or Docker Hub:
# Using Docker Hub
docker run -d -p 24010:24010 --name lookup bluscream1/universal-lookup:latest
# Using GHCR
docker run -d -p 24010:24010 --name lookup ghcr.io/bluscream/universal-lookup:latestgit clone https://github.com/Bluscream/universal-lookup.git
cd universal-lookup
npm install
npm run build
npm startAll endpoints are available at http://localhost:24010/api/*.
| Endpoint | Description | Example Query |
|---|---|---|
GET /api/tel/:query |
Reverse phone lookup | +493012345678 |
GET /api/ip/:query |
IP/Domain intelligence | 8.8.8.8 |
GET /api/email/:query |
Email validation & risk | user@example.com |
GET /api/location/:query |
Geocoding & Reverse Geocoding | Berlin, Germany |
GET /api/parcel/:query |
Package tracking | 00340434515310596216 |
📖 Full Documentation: Explore the interactive Swagger UI at http://localhost:24010/docs.
Copy .env.example to .env to customize the service.
| Variable | Default | Description |
|---|---|---|
PORT |
24010 |
Server port |
HOST |
0.0.0.0 |
Binding address |
LOG_LEVEL |
info |
Logging verbosity (debug, info, warn, error) |
REQUIRE_TOKEN |
null |
If set, requires ?token= for all API calls |
RATE_LIMIT_MAX |
100 |
Max requests per time window |
RATE_LIMIT_WINDOW |
1 minute |
Rate limit time window |
| Variable | Default | Description |
|---|---|---|
DB_PATH |
./data/cache.db |
Path to SQLite database |
CACHE_TTL |
86400 |
Default cache duration (seconds) |
CACHE_TTL_PARCEL |
3600 |
Cache duration for parcels (seconds) |
PROVIDER_TIMEOUT |
10000 |
Max wait time for API providers (ms) |
PUPPETEER_TIMEOUT |
15000 |
Max wait time for headless browser (ms) |
| Variable | Description |
|---|---|
IP_API_COM_KEY |
Commercial key for ip-api.com |
IP_API_IO_KEY |
API key for ip-api.io features |
TELLOWS_API_KEY |
Partner key for Tellows |
MAXMIND_LICENSE_KEY |
License for GeoLite2 downloads |
GOOGLE_API_KEY |
Key for Google Maps & Search API |
GOOGLE_SEARCH_CX |
Google Custom Search Engine ID |
PARCELSAPP_API_KEY |
Key for ParcelsApp tracking |
DHL_API_KEY |
Key for official DHL API |
| Variable | Default | Description |
|---|---|---|
FRITZBOX_HOST |
fritz.box |
FritzBox address for phone lookups |
PHONE_COUNTRY_PREFIX |
0049 |
Default country code |
PHONE_LOCAL_PREFIX |
null |
Default local area code |
UNIVERSAL_RESULTS_LIMIT |
3 |
Max results shown per provider |
PUPPETEER_SKIP_DOWNLOAD |
false |
Skip downloading Chromium |
The project includes a robust automation script for contributors:
# Run QA, bump version, push to Git, build Docker (all archs), and publish to npm
.\scripts\update.ps1 -Bump patchDistributed under the MIT License. See LICENSE for more information.
- Lead Developer: Bluscream
- AI Coding Assistant: Antigravity (Google DeepMind)
Note
AI Disclaimer: Parts of this codebase, including core logic, documentation, and deployment scripts, were generated or optimized using Advanced Agentic AI. While thoroughly tested, users are encouraged to review critical components for their specific use cases.