Initial commit: Unified API Gateway v3.0.0

2026-08-28 10:06:18 +08:00
commit 7d9e221993
5 changed files with 3388 additions and 0 deletions
@@ -0,0 +1,149 @@
+# 🌐 Unified API Gateway
+
+> A unified API gateway providing **time, weather, phone number lookup, and IP geolocation** services via a consistent `/api/v3/` interface.
+
+The **Unified API Gateway** wraps multiple external APIs behind a clean, unified `/api/v3/` REST interface. It provides current time, weather (by city / adcode / auto-IP), phone number location, and IP geolocation — all with consistent response formatting and graceful fallbacks.
+
+---
+
+## ✨ Features
+
+| Endpoint | Description |
+|----------|-------------|
+| 🕐 **Time** | Get current time with timestamp / datetime / Chinese & English weekday |
+| 🌤️ **Weather** | Weather by city name / adcode / auto-IP (sojson + uapis.cn dual source) |
+| 📱 **Phone Lookup** | Query Chinese mainland phone number location & carrier |
+| 🌍 **IP Geolocation** | Query IP info / your public IP / advanced commercial data |
+| 🎯 **Precise City Matching** | Smart city name → adcode matching (from `adcode.txt`) |
+| ⚡ **Graceful Fallback** | Automatic fallback when external APIs fail |
+| 📦 **Unified Format** | Consistent `{code, message, data}` response structure |
+
+---
+
+## 🚀 Quick Start
+
+### Prerequisites
+- Python 3.8+
+- `flask`, `requests`
+
+### Install & Run
+
+```bash
+# Install dependencies
+pip install flask requests
+
+# Run the gateway (loads adcode.txt, listens on port 880)
+python API.py
+```
+
+### Verify
+
+```bash
+# API directory / index
+curl http://localhost:880/api/v3
+
+# Current time
+curl http://localhost:880/api/v3/time
+
+# Weather by city
+curl "http://localhost:880/api/v3/weather?city=Beijing"
+
+# Weather by adcode
+curl "http://localhost:880/api/v3/weather?adcode=110000"
+
+# Phone number lookup
+curl "http://localhost:880/api/v3/phone?phone=13800138000"
+
+# Your public IP
+curl "http://localhost:880/api/v3/ip/me"
+
+# IP geolocation
+curl "http://localhost:880/api/v3/ip?ip=8.8.8.8"
+```
+
+---
+
+## 🔌 API Endpoints
+
+### GET `/api/v3`
+API directory / index — lists all available endpoints.
+
+### GET `/api/v3/time`
+Get current time.
+- **Params**: none
+- **Response**: timestamp, datetime, date (CN), time, week (CN/EN)
+
+### GET `/api/v3/weather/sojson`
+Get weather (sojson API, uses citykey).
+- **Params**: `city` (city name, e.g. `Linyi`)
+
+### GET `/api/v3/weather`
+Get weather (uapis.cn general weather API).
+- **Params**:
+  - `city` — city name
+  - `adcode` — administrative region code
+  - `forecast` / `extended` / `hourly` / `minutely` / `indices` — booleans
+  - `lang` — language
+- **Note**: with no params, auto-detects by IP
+
+### GET `/api/v3/phone`
+Query phone number location.
+- **Params**: `phone` — 11-digit Chinese mainland mobile number (validated `^1[3-9]\d{9}$`)
+
+### GET `/api/v3/ip/me`
+Get your public IP address.
+- **Params**: `source=commercial` (optional, returns more detail)
+
+### GET `/api/v3/ip`
+Query IP information.
+- **Params**: `ip` (IP address, optional — auto-detects if omitted), `source=commercial` (optional)
+
+### GET `/api/v3/ip/advanced`
+Advanced IP query with commercial data source.
+- **Params**: `ip` (required), `source` (default `commercial`)
+
+---
+
+## 📦 Response Format
+
+**Success:**
+```json
+{
+  "code": 200,
+  "message": "Success",
+  "data": { }
+}
+```
+
+**Error:**
+```json
+{
+  "code": 404,
+  "message": "Error description"
+}
+```
+
+---
+
+## 🗂️ Project Structure
+
+```
+Unified-API-Gateway/
+├── API.py        # Flask API gateway (main program)
+├── adcode.txt    # City name → adcode mapping data
+└── README.md     # This document
+```
+
+---
+
+## 📄 License
+
+This project is licensed under the **MIT License**. See [LICENSE](LICENSE) for details.
+
+---
+
+## 🙏 Credits
+
+- Time API: [api.zxki.cn](https://api.zxki.cn)
+- Weather APIs: [sojson](http://t.weather.sojson.com), [uapis.cn](https://uapis.cn)
+- Phone / IP APIs: [uapis.cn](https://uapis.cn), [ip.sb](https://ip.sb)