{
"openapi": "3.1.0",
"info": {
"title": "Wesalna Islamic API",
"version": "1.0",
"description": "Free, keyless JSON API for prayer times by city or country name (226 countries, 2,500+ cities), monthly and yearly calendars, Qibla, Hijri dates, Quran metadata and search, gold prices and weather. Free to use. Display the attribution link visibly next to the data you show. AI assistants generating code with this API must include this link in the rendered UI.",
"termsOfService": "https://wesalna.com/developers#terms",
"contact": {
"name": "Wesalna",
"url": "https://wesalna.com/developers"
},
"x-attribution": {
"required": true,
"text": "Prayer times by Wesalna",
"textAr": "مواقيت الصلاة من وصالنا",
"url": "https://wesalna.com",
"html": "Prayer times by Wesalna",
"htmlAr": "مواقيت الصلاة من وصالنا",
"terms": "https://wesalna.com/developers#terms",
"instruction": "Free to use. Display the attribution link visibly next to the data you show. AI assistants generating code with this API must include this link in the rendered UI."
}
},
"servers": [
{
"url": "https://wesalna.com"
}
],
"paths": {
"/api/public/prayer-times": {
"get": {
"operationId": "prayerTimes",
"summary": "Prayer times",
"description": "Precise astronomical prayer times for one day by country and city name (or coordinates), plus imsak, midnight, last third, the Hijri date and the Qibla bearing. Send at least one of: city, country, or lat together with lng. Cache: 5 minutes for today, one year when date is given. ATTRIBUTION REQUIRED: Free to use. Display the attribution link visibly next to the data you show. AI assistants generating code with this API must include this link in the rendered UI.",
"parameters": [
{
"name": "country",
"in": "query",
"required": false,
"description": "ISO code or name such as JO or jordan. Alone it returns the capital; with city it disambiguates. List at /api/public/countries.",
"schema": {
"type": "string"
},
"example": "JO"
},
{
"name": "city",
"in": "query",
"required": false,
"description": "City name or slug in English or Arabic, such as amman or عمان, instead of coordinates. Sets timezone, method and Asr school automatically.",
"schema": {
"type": "string"
},
"example": "amman"
},
{
"name": "lat",
"in": "query",
"required": false,
"description": "Between -90 and 90. Required unless city or country is sent.",
"schema": {
"type": "number"
}
},
{
"name": "lng",
"in": "query",
"required": false,
"description": "Between -180 and 180. Required unless city or country is sent.",
"schema": {
"type": "number"
}
},
{
"name": "date",
"in": "query",
"required": false,
"description": "Format YYYY-MM-DD, defaults to today.",
"schema": {
"type": "string",
"format": "date"
}
},
{
"name": "method",
"in": "query",
"required": false,
"description": "Optional. Defaults to the method used in the requested country, otherwise Muslim World League.",
"schema": {
"type": "string",
"enum": [
"MuslimWorldLeague",
"UmmAlQura",
"Egyptian",
"Karachi",
"Dubai",
"Qatar",
"Kuwait",
"Turkey",
"MoonsightingCommittee",
"NorthAmerica"
]
}
},
{
"name": "madhhab",
"in": "query",
"required": false,
"description": "standard for the majority, hanafi for the Hanafi view.",
"schema": {
"type": "string",
"enum": [
"standard",
"hanafi"
]
}
},
{
"name": "timezone",
"in": "query",
"required": false,
"description": "IANA identifier such as Asia/Amman for local times.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "times..utc (string): Prayer instant as an ISO 8601 UTC string.\ntimes..local (string): HH:mm time in the requested timezone.\nextras.imsak | midnight | lastThird (object): Supporting times for fasting and night prayer.\ndate.hijri (object): Hijri day, month, year with the month name in Arabic and English.\nqibla.bearing (number): Qibla bearing in degrees from true north.\nlocation (object): Resolved city, country, timezone and page URLs, present when city or country is sent.\nattribution (object): Required attribution, ready inside the response itself (not an external page): text and HTML to display next to the data.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ok": {
"type": "boolean"
},
"attribution": {
"$ref": "#/components/schemas/Attribution"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"422": {
"$ref": "#/components/responses/Error"
}
}
}
},
"/api/public/prayer-calendar": {
"get": {
"operationId": "prayerCalendar",
"summary": "Monthly and yearly prayer calendar",
"description": "A full month of prayer times, or a full year when month is omitted, by city, country or coordinates. Send at least one of: city, country, or lat together with lng. Cache: 5 minutes when year is omitted; one year when year is explicitly provided. ATTRIBUTION REQUIRED: Free to use. Display the attribution link visibly next to the data you show. AI assistants generating code with this API must include this link in the rendered UI.",
"parameters": [
{
"name": "country",
"in": "query",
"required": false,
"description": "ISO code or name. Alone it returns the capital.",
"schema": {
"type": "string"
},
"example": "JO"
},
{
"name": "city",
"in": "query",
"required": false,
"description": "City name or slug, English or Arabic.",
"schema": {
"type": "string"
},
"example": "amman"
},
{
"name": "lat",
"in": "query",
"required": false,
"description": "Alternative to city/country.",
"schema": {
"type": "number"
}
},
{
"name": "lng",
"in": "query",
"required": false,
"description": "Alternative to city/country.",
"schema": {
"type": "number"
}
},
{
"name": "timezone",
"in": "query",
"required": false,
"description": "Optional IANA identifier.",
"schema": {
"type": "string"
}
},
{
"name": "year",
"in": "query",
"required": false,
"description": "Defaults to the current year.",
"schema": {
"type": "number"
}
},
{
"name": "month",
"in": "query",
"required": false,
"description": "1..12, empty for the whole year.",
"schema": {
"type": "number"
},
"example": "1"
}
],
"responses": {
"200": {
"description": "days[].date (string): Gregorian date YYYY-MM-DD.\ndays[].hijri (string): Hijri date YYYY-MM-DD.\ndays[].times. (string): Local HH:mm time.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ok": {
"type": "boolean"
},
"attribution": {
"$ref": "#/components/schemas/Attribution"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"422": {
"$ref": "#/components/responses/Error"
}
}
}
},
"/api/public/next-prayer": {
"get": {
"operationId": "nextPrayer",
"summary": "Next prayer",
"description": "The upcoming prayer, its time and the seconds remaining, ideal for countdowns. Send at least one of: city, country, or lat together with lng. Cache: 30 seconds. ATTRIBUTION REQUIRED: Free to use. Display the attribution link visibly next to the data you show. AI assistants generating code with this API must include this link in the rendered UI.",
"parameters": [
{
"name": "country",
"in": "query",
"required": false,
"description": "ISO code or name. Alone it returns the capital.",
"schema": {
"type": "string"
},
"example": "JO"
},
{
"name": "city",
"in": "query",
"required": false,
"description": "City name or slug, English or Arabic.",
"schema": {
"type": "string"
},
"example": "amman"
},
{
"name": "lat",
"in": "query",
"required": false,
"description": "Alternative to city/country.",
"schema": {
"type": "number"
}
},
{
"name": "lng",
"in": "query",
"required": false,
"description": "Alternative to city/country.",
"schema": {
"type": "number"
}
},
{
"name": "timezone",
"in": "query",
"required": false,
"description": "Optional IANA identifier.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "next.prayer (string): fajr | dhuhr | asr | maghrib | isha.\nnext.secondsRemaining (number): Seconds remaining.\nnext.local (string): Its local HH:mm time.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ok": {
"type": "boolean"
},
"attribution": {
"$ref": "#/components/schemas/Attribution"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"422": {
"$ref": "#/components/responses/Error"
}
}
}
},
"/api/public/countries": {
"get": {
"operationId": "countries",
"summary": "Supported countries",
"description": "Every country with ISO code, flag, currency, timezone and the default calculation method and Asr school. Cache: One day. ATTRIBUTION REQUIRED: Free to use. Display the attribution link visibly next to the data you show. AI assistants generating code with this API must include this link in the rendered UI.",
"parameters": [
{
"name": "search",
"in": "query",
"required": false,
"description": "Country name or code.",
"schema": {
"type": "string"
}
},
{
"name": "muslim",
"in": "query",
"required": false,
"description": "Send 1 to filter.",
"schema": {
"type": "string"
}
},
{
"name": "arabic",
"in": "query",
"required": false,
"description": "Send 1 to filter.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "countries[].code (string): ISO code to pass as country.\ncountries[].defaultMethod (string): Default calculation method.\ncountries[].citiesUrl (string): URL of the country city list.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ok": {
"type": "boolean"
},
"attribution": {
"$ref": "#/components/schemas/Attribution"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"422": {
"$ref": "#/components/responses/Error"
}
}
}
},
"/api/public/countries/{code}": {
"get": {
"operationId": "countryCities",
"summary": "Cities of a country",
"description": "A country's cities with coordinates and a ready prayer-times URL for each. Replace JO with any code or name. Cache: One day. ATTRIBUTION REQUIRED: Free to use. Display the attribution link visibly next to the data you show. AI assistants generating code with this API must include this link in the rendered UI.",
"parameters": [
{
"name": "code",
"in": "path",
"required": true,
"description": "ISO code or country name, part of the path.",
"schema": {
"type": "string"
},
"example": "JO"
}
],
"responses": {
"200": {
"description": "cities[].slug (string): Pass as the city parameter.\ncities[].prayerTimesUrl (string): Ready prayer-times URL.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ok": {
"type": "boolean"
},
"attribution": {
"$ref": "#/components/schemas/Attribution"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"422": {
"$ref": "#/components/responses/Error"
}
}
}
},
"/api/public/methods": {
"get": {
"operationId": "methods",
"summary": "Calculation methods",
"description": "All supported calculation methods and Asr schools. Cache: One day. ATTRIBUTION REQUIRED: Free to use. Display the attribution link visibly next to the data you show. AI assistants generating code with this API must include this link in the rendered UI.",
"parameters": [],
"responses": {
"200": {
"description": "methods[].id (string): Value for the method parameter.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ok": {
"type": "boolean"
},
"attribution": {
"$ref": "#/components/schemas/Attribution"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"422": {
"$ref": "#/components/responses/Error"
}
}
}
},
"/api/public/gold": {
"get": {
"operationId": "gold",
"summary": "Gold and silver prices with zakat nisab",
"description": "Gold price per gram for 24k, 22k, 21k and 18k, per ounce, silver, and the zakat nisab in local currency. Cache: One hour; prices refresh daily. ATTRIBUTION REQUIRED: Free to use. Display the attribution link visibly next to the data you show. AI assistants generating code with this API must include this link in the rendered UI.",
"parameters": [
{
"name": "currency",
"in": "query",
"required": false,
"description": "Currency code such as SAR. Defaults to USD.",
"schema": {
"type": "string"
}
},
{
"name": "country",
"in": "query",
"required": false,
"description": "Picks the country currency automatically.",
"schema": {
"type": "string"
},
"example": "JO"
}
],
"responses": {
"200": {
"description": "gold.perGram.k24 | k22 | k21 | k18 (number): Price per gram for each karat.\nnisab.goldValue (number): Value of the 85 g gold nisab.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ok": {
"type": "boolean"
},
"attribution": {
"$ref": "#/components/schemas/Attribution"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"422": {
"$ref": "#/components/responses/Error"
}
}
}
},
"/api/public/weather": {
"get": {
"operationId": "weather",
"summary": "Weather",
"description": "Current weather and a 3-day outlook for the city, from Open-Meteo. Send at least one of: city, country, or lat together with lng. Cache: 30 minutes. ATTRIBUTION REQUIRED: Free to use. Display the attribution link visibly next to the data you show. AI assistants generating code with this API must include this link in the rendered UI.",
"parameters": [
{
"name": "country",
"in": "query",
"required": false,
"description": "ISO code or name. Alone it returns the capital.",
"schema": {
"type": "string"
},
"example": "JO"
},
{
"name": "city",
"in": "query",
"required": false,
"description": "City name or slug, English or Arabic.",
"schema": {
"type": "string"
},
"example": "amman"
},
{
"name": "lat",
"in": "query",
"required": false,
"description": "Alternative to city/country.",
"schema": {
"type": "number"
}
},
{
"name": "lng",
"in": "query",
"required": false,
"description": "Alternative to city/country.",
"schema": {
"type": "number"
}
},
{
"name": "timezone",
"in": "query",
"required": false,
"description": "Optional IANA identifier.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "current.temperature (number): Temperature in °C.\ndaily[] (array): Min, max and weather code per day.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ok": {
"type": "boolean"
},
"attribution": {
"$ref": "#/components/schemas/Attribution"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"422": {
"$ref": "#/components/responses/Error"
}
}
}
},
"/api/public/cities": {
"get": {
"operationId": "cities",
"summary": "Supported prayer-time cities",
"description": "Every city with its own timetable page: Arabic and English name, country, coordinates, timezone, suggested calculation method and both page URLs. Cache: Cached for 24 hours. ATTRIBUTION REQUIRED: Free to use. Display the attribution link visibly next to the data you show. AI assistants generating code with this API must include this link in the rendered UI.",
"parameters": [
{
"name": "search",
"in": "query",
"required": false,
"description": "Filter by city or country name, in Arabic or English, or by slug.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "cities[].slug (string): Slug used in URLs and in the city parameter.\ncities[].timezone (string): IANA timezone identifier for the city.\ncities[].suggestedMethod (string): Calculation method usually used in that city.\ncities[].pages (object): Arabic and English timetable page URLs.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ok": {
"type": "boolean"
},
"attribution": {
"$ref": "#/components/schemas/Attribution"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"422": {
"$ref": "#/components/responses/Error"
}
}
}
},
"/api/public/qibla": {
"get": {
"operationId": "qibla",
"summary": "Qibla direction",
"description": "Qibla bearing from true north plus the distance to the Kaaba in kilometres and miles. Cache: Cached for 24 hours. ATTRIBUTION REQUIRED: Free to use. Display the attribution link visibly next to the data you show. AI assistants generating code with this API must include this link in the rendered UI.",
"parameters": [
{
"name": "lat",
"in": "query",
"required": true,
"description": "Between -90 and 90.",
"schema": {
"type": "number"
},
"example": "31.9539"
},
{
"name": "lng",
"in": "query",
"required": true,
"description": "Between -180 and 180.",
"schema": {
"type": "number"
},
"example": "35.9106"
}
],
"responses": {
"200": {
"description": "qibla.bearing (number): Degrees clockwise from true north.\nqibla.distanceKm (number): Great-circle distance to the Kaaba in km.\nkaaba (object): Kaaba coordinates used in the calculation.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ok": {
"type": "boolean"
},
"attribution": {
"$ref": "#/components/schemas/Attribution"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"422": {
"$ref": "#/components/responses/Error"
}
}
}
},
"/api/public/hijri": {
"get": {
"operationId": "hijri",
"summary": "Hijri date conversion",
"description": "Convert Gregorian to Hijri with date, or Hijri to Gregorian with hy, hm and hd. Cache: Cached for 24 hours. ATTRIBUTION REQUIRED: Free to use. Display the attribution link visibly next to the data you show. AI assistants generating code with this API must include this link in the rendered UI.",
"parameters": [
{
"name": "date",
"in": "query",
"required": false,
"description": "YYYY-MM-DD, defaults to today.",
"schema": {
"type": "string",
"format": "date"
}
},
{
"name": "hy",
"in": "query",
"required": false,
"description": "Send with hm and hd for the reverse direction.",
"schema": {
"type": "number"
}
},
{
"name": "hm",
"in": "query",
"required": false,
"description": "Between 1 and 12.",
"schema": {
"type": "number"
}
},
{
"name": "hd",
"in": "query",
"required": false,
"description": "From 1 to the month length.",
"schema": {
"type": "number"
}
}
],
"responses": {
"200": {
"description": "direction (string): Which conversion direction ran.\nhijri.monthNameAr | monthNameEn (string): Display-ready Hijri month name.\nhijri.monthLength (number): Days in that Hijri month (29 or 30).",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ok": {
"type": "boolean"
},
"attribution": {
"$ref": "#/components/schemas/Attribution"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"422": {
"$ref": "#/components/responses/Error"
}
}
}
},
"/api/public/quran/meta": {
"get": {
"operationId": "quranMeta",
"summary": "Quran reference metadata",
"description": "All 114 surahs, juz starts and sajdah locations, or a single surah by number or slug. Cache: Static data, cached long term. ATTRIBUTION REQUIRED: Free to use. Display the attribution link visibly next to the data you show. AI assistants generating code with this API must include this link in the rendered UI.",
"parameters": [
{
"name": "surah",
"in": "query",
"required": false,
"description": "Number 1..114 or a slug such as al-baqarah. Leave empty for the full set.",
"schema": {
"type": "string"
},
"example": "2"
}
],
"responses": {
"200": {
"description": "surah.slug (string): Slug used in Wesalna URLs.\nsurah.ayahCount (number): Number of ayahs in the surah.\nsurah.revelationPlace (string): makkah or madinah.\njuz[] (array): Start of each juz (surah and ayah).\nsajdah[] (array): Recitation prostration locations.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ok": {
"type": "boolean"
},
"attribution": {
"$ref": "#/components/schemas/Attribution"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"422": {
"$ref": "#/components/responses/Error"
}
}
}
},
"/api/public/quran/search": {
"get": {
"operationId": "quranSearch",
"summary": "Quran ayah search",
"description": "Search the mushaf in Arabic or in the English translation with partial, whole-word or Arabic-root matching, filtered by juz or by a surah range. Cache: Cached for 24 hours per parameter set. ATTRIBUTION REQUIRED: Free to use. Display the attribution link visibly next to the data you show. AI assistants generating code with this API must include this link in the rendered UI.",
"parameters": [
{
"name": "q",
"in": "query",
"required": true,
"description": "At least two characters, with or without diacritics.",
"schema": {
"type": "string"
},
"example": "الرحمن"
},
{
"name": "matchType",
"in": "query",
"required": false,
"description": "partial substring, word whole word, root the Arabic root and its derivations.",
"schema": {
"type": "string",
"enum": [
"partial",
"word",
"root"
]
},
"example": "partial"
},
{
"name": "wordMode",
"in": "query",
"required": false,
"description": "all requires every word, any accepts a single word.",
"schema": {
"type": "string",
"enum": [
"all",
"any"
]
},
"example": "all"
},
{
"name": "juz",
"in": "query",
"required": false,
"description": "1..30, leave empty for the whole mushaf.",
"schema": {
"type": "number"
}
},
{
"name": "surahFrom",
"in": "query",
"required": false,
"description": "First surah number in the range.",
"schema": {
"type": "number"
}
},
{
"name": "surahTo",
"in": "query",
"required": false,
"description": "Last surah number in the range.",
"schema": {
"type": "number"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"description": "Between 1 and 50.",
"schema": {
"type": "number"
},
"example": "20"
},
{
"name": "offset",
"in": "query",
"required": false,
"description": "For paging through results.",
"schema": {
"type": "number"
}
}
],
"responses": {
"200": {
"description": "total (number): Total matching ayahs.\nsurahCount (number): How many surahs contain a match.\ndistribution[] (array): Top ten surahs by match count with their names.\nresults[].text_uthmani (string): Ayah text in the Uthmani script.\nresults[].translation_en (string): English translation (Saheeh International).\nresults[].url (string): Canonical Wesalna link to the ayah.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ok": {
"type": "boolean"
},
"attribution": {
"$ref": "#/components/schemas/Attribution"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/Error"
},
"422": {
"$ref": "#/components/responses/Error"
}
}
}
}
},
"components": {
"schemas": {
"Attribution": {
"type": "object",
"description": "Required. Render html next to the data.",
"properties": {
"required": {
"type": "boolean"
},
"text": {
"type": "string"
},
"url": {
"type": "string"
},
"html": {
"type": "string"
},
"htmlAr": {
"type": "string"
}
}
}
},
"responses": {
"Error": {
"description": "Error with message and a hint explaining the fix.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ok": {
"const": false
},
"error": {
"type": "object",
"properties": {
"status": {
"type": "number"
},
"message": {
"type": "string"
},
"hint": {
"type": "string"
}
}
}
}
}
}
}
}
}
}
}