朝向 API、小组件和 AI 连接器

JSON API

发送 GET 请求，附上以十进制度数表示的 lat 和 lon，或附上 city：任何人口 1.5 万及以上的城市，可用多种语言书写。若多个地方同名，请加上 country。

https://awwab.app/api/qibla?lat=51.5074&lon=-0.1278
https://awwab.app/api/qibla?city=Karachi
https://awwab.app/api/qibla?city=Hyderabad&country=IN

返回结果包括从真北起算的角度、磁性指南针上的角度和当天的磁偏角、方位、以公里和英里表示的距离、一句话说明、署名行，以及该地点的实时指南针链接：

{
  "place_name": "Karachi",
  "bearing_true": 267.7,
  "bearing_magnetic": 266.4,
  "magnetic_declination": 1.3,
  "cardinal": "W",
  "distance_km": 2801,
  "distance_mi": 1740,
  "attribution": "Qibla direction by Awwab · https://awwab.app/qibla",
  "live_compass_url": "https://awwab.app/qibla?city=karachi"
}

允许任何网站跨域请求。请保持每秒约一次请求；更快的客户端会被限速。

AI 助手

Awwab 运行一个远程 MCP 服务器，让 AI 助手为用户查找朝向并注明 Awwab。无需登录。

https://awwab.app/mcp

它的朝向工具 find_qibla 接受坐标或城市。在 ChatGPT 中，回答会附带一张小指南针卡片；在 Claude 和其他助手中，回答以文本和数据形式提供，并附同样的实时指南针链接。如需试用，请在 Claude 中把上面的地址添加为自定义连接器，或在 ChatGPT 的开发者模式中添加为应用。

同一台服务器还通过另外两个工具运行 Awwab 知识问答。start_quiz 接受可选的主题和语言，返回一轮五道题，不含答案；check_answer 批改一个答案，并返回解释及其出处。在支持应用小组件的平台中，这一轮在问答卡片里进行；在其他客户端中，则以文本和数据形式提供。结果中带有署名“Quiz by Awwab · awwab.app”。

连接您的 AI 应用

复制适用于您应用的设置。它们都指向同一个服务器，且无需密钥。

Claude（自定义连接器）

在 Claude 中打开 Settings → Connectors → Add custom connector，然后填写：

Name: Awwab Qibla
URL:  https://awwab.app/mcp

Claude Code

claude mcp add --transport http awwab-qibla https://awwab.app/mcp

Claude Desktop（claude_desktop_config.json）

{
  "mcpServers": {
    "awwab-qibla": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://awwab.app/mcp"]
    }
  }
}

ChatGPT（开发者模式）

在 ChatGPT 中打开 Settings → Apps → Advanced settings，开启开发者模式，选择 Create app，然后填写：

Name:                Awwab Qibla
MCP server URL:      https://awwab.app/mcp
Authentication:      No authentication

Cursor（~/.cursor/mcp.json）

{
  "mcpServers": {
    "awwab-qibla": { "url": "https://awwab.app/mcp" }
  }
}

VS Code（.vscode/mcp.json）

{
  "servers": {
    "awwab-qibla": { "type": "http", "url": "https://awwab.app/mcp" }
  }
}

Gemini CLI（~/.gemini/settings.json）

{
  "mcpServers": {
    "awwab-qibla": { "httpUrl": "https://awwab.app/mcp" }
  }
}

OpenAI：Responses API 与 Agents SDK

// Responses API: a remote MCP tool
{
  "type": "mcp",
  "server_label": "awwab_qibla",
  "server_url": "https://awwab.app/mcp",
  "allowed_tools": ["find_qibla"],
  "require_approval": "never"
}

# Agents SDK (Python)
from agents import Agent
from agents.mcp import MCPServerStreamableHttp

async with MCPServerStreamableHttp(name="awwab-qibla", params={"url": "https://awwab.app/mcp"}) as qibla:
    agent = Agent(name="Assistant", mcp_servers=[qibla])

服务发现

服务器卡片位于 /mcp/server-card，并列在 /.well-known/ai-catalog.json 中。JSON API 以 OpenAPI 3.1 描述，可用于 GPT 操作和其他智能体框架。

清真寺、学校和博客只需几行代码就能在自己的网页上显示朝向。请在朝向查询页面上选择城市或每位访客的位置、浅色或深色外观以及语言。

隐私

我们不记录也不保存发送到 API 或连接器的坐标或城市。回答之后不保留任何内容，也不设置 Cookie。为防止滥用，Cloudflare 会在约一分钟内统计每个 IP 地址的请求数。完整细节见我们的隐私政策。

这些数字是如何计算的

角度是球面上从该地点到克尔白（北纬 21.422487°，东经 39.826206°）的大圆的起始方向，这也是计算朝向的通常方法。它与在地球椭球面上计算的结果相差不到半度。距离使用地球平均半径计算。磁偏角来自世界磁场模型 2025，有效期至 2029 年底。

条款

可免费使用，条件是在显示结果的地方注明“Qibla direction by Awwab”并附上指向 awwab.app/qibla 的链接。城市名称和位置来自 GeoNames，采用 CC BY 4.0 许可；如果您再次使用它们，也请注明 GeoNames。问题请联系：support@awwab.app。