Clock API documentation

Use this API to build your own adhan clock with the same JSON the My Adhan apps use (prayer times, Qibla, weather, Hijri, alerts, theme, labels). Free self-serve keys — no credit card.

• 1. How it works
• 2. Create account & key
• 3. How to test
• 4. Code samples
• 5. Rate limits
• 6. Response fields

1. How the Clock API works

Base URL: https://adhan.ticktock.space

Main endpoint: GET /v1/clock

Pass a location with one of:

• city — e.g. Toronto or Calgary (geocoded)
• lat + lon — decimal degrees
• address — full street address (geocoded)

Optional: lang=en, prayer method, asr, forecast_days.

Auth (required for /v1/clock):

• Query: ?api_key=YOUR_KEY
• Or header: X-API-Key: YOUR_KEY

Health (no key): GET /healthz → {"ok": true, ...}

Invalid / missing key → HTTP 401. Over limit → HTTP 429 with Retry-After.

2. Create an account and generate an API key

1. Open /developers/register (or /developers).
2. Sign up with email + password (min 8 characters).
3. On the dashboard, enter an optional label and click Generate API key.
4. Copy the key (starts with mac_) and store it privately — treat it like a password.
5. You may have up to 5 keys; revoke unused ones anytime.

Keys are not shown inside the My Adhan mobile/desktop apps — only on this portal (and Admin → API for operators).

3. How to test

Replace YOUR_KEY with your key from the dashboard.

curl — city

curl "https://adhan.ticktock.space/v1/clock?api_key=YOUR_KEY&city=Toronto&lang=en"

curl — X-API-Key header

curl -H "X-API-Key: YOUR_KEY" \
  "https://adhan.ticktock.space/v1/clock?city=Toronto&lang=en"

curl — health

curl "https://adhan.ticktock.space/healthz"

Expect HTTP 200 and JSON with prayers, weather, qibla. You should also see a green PASS in the local demo tool (tools/ClockAPIDemo in the My Adhan repo) once a valid key is configured.

4. How to code it

Same call: /v1/clock?city=Toronto&api_key=… (or header). Snippets below are ready to paste.

Python — urllib

import json, urllib.parse, urllib.request

BASE = "https://adhan.ticktock.space"
KEY = "YOUR_KEY"
q = urllib.parse.urlencode({"api_key": KEY, "city": "Toronto", "lang": "en"})
req = urllib.request.Request(
    f"{BASE}/v1/clock?{q}",
    headers={"User-Agent": "MyClock/1.0"},
)
with urllib.request.urlopen(req, timeout=60) as r:
    data = json.load(r)
print(data["prayers"])
print(data.get("weather", {}).get("current"))
print(data.get("qibla", {}).get("bearing"))

Python — requests

import requests

BASE = "https://adhan.ticktock.space"
r = requests.get(
    f"{BASE}/v1/clock",
    params={"api_key": "YOUR_KEY", "city": "Toronto", "lang": "en"},
    timeout=60,
)
r.raise_for_status()
data = r.json()
print(data["prayers"])

JavaScript — fetch

const BASE = "https://adhan.ticktock.space";
const KEY = "YOUR_KEY";
const url = `${BASE}/v1/clock?` + new URLSearchParams({
  api_key: KEY, city: "Toronto", lang: "en",
});
const res = await fetch(url);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const data = await res.json();
console.log(data.prayers, data.weather?.current, data.qibla?.bearing);

Swift — URLSession

import Foundation

let base = "https://adhan.ticktock.space"
var comps = URLComponents(string: "\(base)/v1/clock")!
comps.queryItems = [
  URLQueryItem(name: "api_key", value: "YOUR_KEY"),
  URLQueryItem(name: "city", value: "Toronto"),
  URLQueryItem(name: "lang", value: "en"),
]
let (data, resp) = try await URLSession.shared.data(from: comps.url!)
guard let http = resp as? HTTPURLResponse, http.statusCode == 200 else {
  throw URLError(.badServerResponse)
}
let json = try JSONSerialization.jsonObject(with: data) as? [String: Any]
print(json?["prayers"] as Any)

5. Rate limits

Per API key (sliding windows):

• 60 requests / minute
• 600 requests / hour

Over limit returns HTTP 429 with a Retry-After header. Cache responses on your side when possible.

6. What comes back

Top-level JSON (same shape as the app clock bundle), including:

• prayers — Fajr, Sunrise, Dhuhr, Asr, Maghrib, Isha (local times for the resolved city)
• next_prayer — key, localized name, time
• weather — current conditions + daily forecast
• qibla — bearing toward the Kaaba, optional map / Street View URLs
• date — Gregorian + Hijri
• location — lat, lon, city label, timezone offset
• alerts, moon, events, theme, labels, branding URLs
• _meta — resolved_city, bundle health flags, key label

Adhan audio for third-party apps is not served as download blobs from this API — ship or host your own audio; the My Adhan apps use on-device / bundled MP3s.