noimosiny/py-sdk
GitHub: noimosiny/py-sdk
Noimosiny 平台的官方 Python 客户端库，封装反向邮箱、电话和用户名查询接口，帮助开发者便捷地进行 OSINT 调查与身份验证。
Stars: 7 | Forks: 0
# Noimosiny Python SDK
[](https://pypi.org/project/noimosiny/)
[](https://pypi.org/project/noimosiny/)
[](https://github.com/noimosiny/py-sdk/blob/main/LICENSE)
[](https://github.com/psf/black)
用于 Noimosiny API（OSINT 和反向查询平台）的 Python 客户端库。
## 安装说明
通过 pip 安装该包：
```
pip install noimosiny
```
*注意：对于本地开发，请确保通过 `pip install requests` 安装依赖项。*
## 快速开始
使用您的 API token 初始化 `Client`（可以从 Noimosiny dashboard 的设置页面获取）。您可以在 `with` 上下文管理器块内检索余额并执行搜索：
```
import os
from noimosiny import Client, NoimosinyError
def main():
# Load API token from environment
api_key = os.environ.get("NOIMOSINY_API_KEY", "your-api-key-here")
try:
# Use Client as a context manager for clean session closing
with Client(api_key) as client:
# Check account balances
gold = client.get_gold_credits()
silver = client.get_silver_credits()
print(f"Balances: Gold={gold} credits | Silver={silver} credits")
# Perform a reverse email lookup
print("Running reverse email lookup...")
results = client.search_email("user@example.com")
print("Results:", results)
except NoimosinyError as e:
print(f"API Error occurred: {e}")
if __name__ == "__main__":
main()
```
## API 参考与 Endpoints
在底层，Noimosiny API 将所有客户端操作路由到单个 endpoint（`POST https://api.noimosiny.com/v1/execute`）。SDK 将此 payload 结构完全抽象为简洁、符合 Python 风格的方法调用。
### 速率限制
- **5** 个并发请求。
- 每分钟 **60** 个请求。
### 账户与余额
#### `get_gold_credits() -> int`
检索您当前的金积分（Gold credit）余额。反向搜索查询（电子邮件、电话、用户名）会消耗金积分。
- **等效的 API payload 方法：** `getGoldCredits`
- **返回值示例：** `1000`
#### `get_silver_credits() -> int`
检索您当前的银积分（Silver credit）余额。高级工具查询会消耗银积分。
- **等效的 API payload 方法：** `getSilverCredits`
- **返回值示例：** `5000`
### 反向搜索操作
所有搜索操作都会返回一个符合 API 标准响应格式的 Python 字典。每次查询都会扫描多个内部模块，并返回成功状态以及匹配到的元数据。
#### `search_email(email: str) -> dict`
执行反向电子邮件查询，以查找关联的社交媒体资料和在线注册记录。
- **等效的 API payload 参数：** `"type": "reverse_email"`
- **响应格式示例：**
{
"type": "reverse_email",
"query": "user@example.com",
"results": [
{
"module": "TikTok",
"success": true,
"data": {
"id": "70397021345678",
"likes": 28506,
"region": "Australia",
"videos": 792,
"private": false,
"language": "en",
"username": "johndoe",
"verified": false,
"followers": 1029,
"following": 670,
"created_at": "2021-12-10 00:14:02",
"profile_url": "https://tiktok.com/@johndoe",
"display_name": "John Doe",
"social_profiles": {
"youtube": "John Doe"
}
}
}
]
}
#### `search_phone(phone: str) -> dict`
执行反向电话号码搜索，以查找所有者详细信息、运营商详细信息和地理位置信息。
- **等效的 API payload 参数：** `"type": "reverse_phone"`
- **响应格式示例：**
{
"type": "reverse_phone",
"query": "+1234567890",
"results": [
{
"module": "PhoneUS1",
"success": true,
"data": {
"zip": "12345",
"city": "New York",
"name": "John Doe",
"type": "Landline",
"state": "NY",
"county": "New York",
"carrier": "WINDSTREAM NUVOX, INC. - FL",
"latitude": "40.7128",
"longitude": "-74.0060",
"risk_scale": 0.6,
"risk_description": "possibly unsafe caller"
}
}
]
}
#### `search_username(username: str) -> dict`
对用户名执行反向搜索，以检查跨多个社交网络的注册表状态和资料。
- **等效的 API payload 参数：** `"type": "reverse_username"`
- **响应格式示例：**
{
"type": "reverse_username",
"query": "johndoe",
"results": [
{
"module": "Instagram",
"success": true,
"data": {
"url": "https://instagram.com/johndoe",
"username": "johndoe",
"image": "https://scontent-atl3-1.cdninstagram.com/v/............",
"followers_count": 918,
"following_count": 0,
"posts_count": 0,
"is_private": true,
"is_verified": false,
"is_business": false,
"is_professional": false
}
}
]
}
## 错误处理
所有 SDK 特定的异常都继承自 `NoimosinyError`。捕获它即可处理任何 API 或连接问题：
```
from noimosiny import Client
from noimosiny.exceptions import (
NoimosinyError,
AuthenticationError,
RateLimitError,
InsufficientCreditsError,
BadRequestError,
ServerError
)
try:
with Client("API_KEY") as client:
client.search_email("test@example.com")
except AuthenticationError:
print("Invalid API Key.")
except RateLimitError:
print("Too many requests. Please throttle your queries.")
except InsufficientCreditsError:
print("Your account is out of credits.")
except BadRequestError as e:
print(f"Invalid query parameters: {e}")
except ServerError:
print("An unexpected server-side error occurred on the Noimosiny API.")
except NoimosinyError as e:
print(f"Generic SDK error: {e}")
```
### 异常层级结构
- `NoimosinyError`（基础异常类）
- `AuthenticationError`（401 Unauthorized）
- `RateLimitError`（429 Too Many Requests）
- `APIRequestError`（请求验证和 API 响应的基类）
- `BadRequestError`（400 Bad Request）
- `InsufficientCreditsError`（403 Forbidden）
- `APITimeoutError`（408 Request Timeout）
- `ServerError`（500+ Internal Server Error）
标签：API, ESC4, OSINT, Python, 信息查询, 数据泄露, 无后门, 逆向工具