Qibla API, widget and AI connector

JSON API

Send a GET request with lat and lon in decimal degrees, or with city: any city of 15,000 people or more, written in many languages. Add country when a name is shared by several places.

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

The answer gives the bearing from true north, the bearing on a magnetic compass and the magnetic declination for today, the compass direction, the distance in kilometres and miles, a one-line sentence, the credit line and a link to the live compass for that place:

{
  "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"
}

Cross-origin requests are allowed from any website. Please keep to about one request per second; faster clients are slowed down.

AI assistants

Awwab runs a remote MCP server, so AI assistants can find the Qibla for their users and credit Awwab. It needs no sign-in.

https://awwab.app/mcp

Its Qibla tool, find_qibla, takes coordinates or a city. In ChatGPT the answer comes with a small compass card; in Claude and other assistants it arrives as text and data with the same link to the live compass. To try it, add the address above as a custom connector in Claude, or as an app in ChatGPT’s developer mode.

The same server runs the Awwab Knowledge quiz with two more tools. start_quiz takes an optional topic and language and returns one round of five questions without their answers; check_answer grades one answer and returns the explanation and its sources. In hosts that support app widgets the round plays in a quiz card; in other clients it arrives as text and data. Results carry the credit “Quiz by Awwab · awwab.app”.

Connect your AI app

Copy the setting for your app. Every one points to the same server and needs no key.

Claude (custom connector)

In Claude, open Settings → Connectors → Add custom connector, then fill in:

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 (developer mode)

In ChatGPT, open Settings → Apps → Advanced settings, turn on developer mode, choose Create app, then fill in:

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 and 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])

Discovery

The server card is at /mcp/server-card and is listed in /.well-known/ai-catalog.json. The JSON API is described in OpenAPI 3.1, for GPT actions and other agent frameworks.

Mosques, schools and blogs can show the Qibla on their own pages with a few lines of code. Choose a city or each visitor’s location, a light or dark look and a language on the Qibla finder page.

Privacy

We do not log or store the coordinates or the cities that are sent to the API or the connector. Nothing is kept after the answer, and no cookies are set. To prevent abuse, Cloudflare counts requests per IP address for about a minute. The full details are in our privacy policy.

How the numbers are worked out

The bearing is the starting direction of the great circle from the place to the Kaaba (21.422487° N, 39.826206° E) on a sphere, which is how the Qibla is usually computed. It differs from a calculation on the Earth’s ellipsoid by less than half a degree. The distance uses the Earth’s mean radius. Magnetic declination comes from the World Magnetic Model 2025, valid until the end of 2029.

Terms

Free to use, on the condition that you credit “Qibla direction by Awwab” with a link to awwab.app/qibla wherever the result is shown. City names and positions come from GeoNames under CC BY 4.0; credit GeoNames too if you reuse them. Questions: support@awwab.app.