{ "openapi": "3.1.0", "info": { "title": "All Masjids Public Timetable API", "version": "1.0.0", "summary": "Masjids' prayer and jamaat times, for other people's websites, apps and screens.", "description": "Only masjids with a published timetable. Every answer says whose times they are (timetable.source: committee = the masjid's own, checked = checked by All Masjids, pending = not yet checked) and marks calculated days. Times are 24-hour HH:MM in the masjid's own timezone. Each key may make 600 requests an hour; past that the API answers 429 with Retry-After. Please show the attribution wherever you use the times. Docs and keys: https://allmasjids.com/developers", "contact": { "name": "All Masjids", "url": "https://allmasjids.com/developers" } }, "servers": [ { "url": "https://allmasjids.com/api/public/v1" } ], "security": [ { "bearerAuth": [] }, { "keyQuery": [] } ], "paths": { "/masjids": { "get": { "operationId": "searchMasjids", "summary": "Find published masjids", "description": "By name or address (q), town, or near a point (lat and lng, nearest first, within radius_km). 50 a page, A to Z unless near a point.", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string", "minLength": 2, "maxLength": 60 }, "description": "Words in the name or address." }, { "name": "town", "in": "query", "schema": { "type": "string", "maxLength": 80 }, "description": "The town, as the masjid's page names it." }, { "name": "lat", "in": "query", "schema": { "type": "number", "minimum": -90, "maximum": 90 }, "description": "Latitude, with lng." }, { "name": "lng", "in": "query", "schema": { "type": "number", "minimum": -180, "maximum": 180 }, "description": "Longitude, with lat." }, { "name": "radius_km", "in": "query", "schema": { "type": "number", "minimum": 0.1, "maximum": 100, "default": 10 }, "description": "How far from lat/lng, in kilometres." }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } } ], "responses": { "200": { "description": "Masjids", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "attribution" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Masjid" } }, "meta": { "type": "object", "required": [ "page", "per_page", "total" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } } }, "attribution": { "$ref": "#/components/schemas/Attribution" } } }, "example": { "data": [ { "slug": "riverside-masjid", "name": "Riverside Masjid", "address": "12 River Street, Hillford, HF1 2AB", "town": "Hillford", "postcode": "HF1 2AB", "latitude": 53.7957, "longitude": -1.5492, "distance_km": null, "timetable": { "source": "committee" }, "page_url": "https://allmasjids.com/masjid/riverside-masjid" } ], "meta": { "page": 1, "per_page": 50, "total": 1 }, "attribution": { "text": "Prayer times from All Masjids (allmasjids.com)", "url": "https://allmasjids.com" } } } } }, "401": { "$ref": "#/components/responses/Unauthorised" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/masjids/{slug}": { "get": { "operationId": "getMasjid", "summary": "One masjid", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "The masjid's slug, from /masjids.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The masjid", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "attribution" ], "properties": { "data": { "$ref": "#/components/schemas/MasjidDetail" }, "attribution": { "$ref": "#/components/schemas/Attribution" } } }, "example": { "data": { "slug": "riverside-masjid", "name": "Riverside Masjid", "address": "12 River Street, Hillford, HF1 2AB", "town": "Hillford", "postcode": "HF1 2AB", "latitude": 53.7957, "longitude": -1.5492, "distance_km": null, "timetable": { "source": "committee" }, "page_url": "https://allmasjids.com/masjid/riverside-masjid", "timezone": "Europe/London", "published_at": "2026-10-30T18:04:11+00:00" }, "attribution": { "text": "Prayer times from All Masjids (allmasjids.com)", "url": "https://allmasjids.com/masjid/riverside-masjid" } } } } }, "401": { "$ref": "#/components/responses/Unauthorised" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/masjids/{slug}/times": { "get": { "operationId": "getTimes", "summary": "Daily times for a range of dates", "description": "Today to six days on unless from/to are given. At most 366 days, from the start of the month 12 months back to 13 months ahead.", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "The masjid's slug, from /masjids.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "First date, YYYY-MM-DD. Default today, in the masjid's timezone." }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Last date, YYYY-MM-DD. Default six days after from." } ], "responses": { "200": { "description": "The days", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "attribution" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Day" } }, "meta": { "type": "object", "required": [ "masjid", "timezone", "source", "from", "to" ], "properties": { "masjid": { "type": "string", "description": "The masjid's slug." }, "timezone": { "type": "string", "examples": [ "Europe/London" ] }, "source": { "$ref": "#/components/schemas/Source" }, "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" } } }, "attribution": { "$ref": "#/components/schemas/Attribution" } } }, "example": { "data": [ { "date": "2026-11-06", "weekday": "Friday", "begins": { "fajr": "05:41", "sunrise": "07:12", "dhuhr": "11:56", "asr": "14:08", "maghrib": "16:30", "isha": "17:58" }, "jamaat": { "fajr": "06:15", "dhuhr": "12:45", "asr": "14:30", "maghrib": "16:35", "isha": "19:30" }, "jumuah": [ "12:45", "13:30" ], "calculated": false } ], "meta": { "masjid": "riverside-masjid", "timezone": "Europe/London", "source": "committee", "from": "2026-11-06", "to": "2026-11-06" }, "attribution": { "text": "Prayer times from All Masjids (allmasjids.com)", "url": "https://allmasjids.com/masjid/riverside-masjid" } } } } }, "401": { "$ref": "#/components/responses/Unauthorised" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "A range we don't offer (error bad_range), or a date not written YYYY-MM-DD.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/ValidationError" } ] }, "example": { "error": "bad_range", "message": "Ask for at most 366 days, from 2025-10-01 to 2027-11-30, with from before to." } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/masjids/{slug}/month.csv": { "get": { "operationId": "getMonthCsv", "summary": "A month as CSV", "description": "UTF-8 with a byte-order mark, one row a day: Date, Day, Fajr, Fajr Jamaat, Sunrise, Dhuhr, Dhuhr Jamaat, Asr, Asr Jamaat, Maghrib, Maghrib Jamaat, Isha, Isha Jamaat, Jumuah (space-separated), Calculated (yes or empty).", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "The masjid's slug, from /masjids.", "schema": { "type": "string" } }, { "name": "month", "in": "query", "schema": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}$" }, "description": "YYYY-MM. Default this month." } ], "responses": { "200": { "description": "The month", "content": { "text/csv": { "schema": { "type": "string" }, "example": "Date,Day,Fajr,Fajr Jamaat,Sunrise,Dhuhr,Dhuhr Jamaat,Asr,Asr Jamaat,Maghrib,Maghrib Jamaat,Isha,Isha Jamaat,Jumuah,Calculated\n2026-11-06,Friday,05:41,06:15,07:12,11:56,12:45,14:08,14:30,16:30,16:35,17:58,19:30,12:45 13:30,\n" } } }, "401": { "$ref": "#/components/responses/Unauthorised" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "A month outside the times we offer, or not written YYYY-MM.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Message" }, { "$ref": "#/components/schemas/ValidationError" } ] } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/masjids/{slug}/calendar.ics": { "get": { "operationId": "getCalendar", "summary": "Jamaat times as a calendar feed", "description": "Each jamaat (and Jumu'ah on Fridays, in place of Dhuhr) of the next 60 days as a 10-minute event. Calendar apps can't send headers, so subscribe with ?key= in the address; the feed asks to be refreshed hourly.", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "The masjid's slug, from /masjids.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "An iCalendar feed", "content": { "text/calendar": { "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthorised" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/widget/{slug}": { "get": { "operationId": "getWidget", "summary": "Today and tomorrow, for the website widget", "description": "No key needed; 120 requests a minute per address. Used by https://allmasjids.com/widget.js.", "security": [], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "The masjid's slug, from /masjids.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Today and tomorrow", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta", "attribution" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Day" }, "description": "Today, then tomorrow, in the masjid's timezone." }, "meta": { "type": "object", "required": [ "masjid", "slug", "timezone", "source", "page_url" ], "properties": { "masjid": { "type": "string", "description": "The masjid's name." }, "slug": { "type": "string" }, "timezone": { "type": "string" }, "source": { "$ref": "#/components/schemas/Source" }, "page_url": { "type": "string", "format": "uri" } } }, "attribution": { "$ref": "#/components/schemas/Attribution" } } }, "example": { "data": [ { "date": "2026-11-06", "weekday": "Friday", "begins": { "fajr": "05:41", "sunrise": "07:12", "dhuhr": "11:56", "asr": "14:08", "maghrib": "16:30", "isha": "17:58" }, "jamaat": { "fajr": "06:15", "dhuhr": "12:45", "asr": "14:30", "maghrib": "16:35", "isha": "19:30" }, "jumuah": [ "12:45", "13:30" ], "calculated": false } ], "meta": { "masjid": "Riverside Masjid", "slug": "riverside-masjid", "timezone": "Europe/London", "source": "committee", "page_url": "https://allmasjids.com/masjid/riverside-masjid" }, "attribution": { "text": "Prayer times from All Masjids (allmasjids.com)", "url": "https://allmasjids.com/masjid/riverside-masjid" } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "description": "Too many requests from this address.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Authorization: Bearer amk_..." }, "keyQuery": { "type": "apiKey", "in": "query", "name": "key", "description": "?key=amk_..., for calendar feeds and quick tries." } }, "schemas": { "Source": { "type": "string", "enum": [ "committee", "checked", "pending" ], "description": "Whose times they are: committee = the masjid's own; checked = checked by All Masjids; pending = not yet checked." }, "Attribution": { "type": "object", "required": [ "text", "url" ], "properties": { "text": { "type": "string", "const": "Prayer times from All Masjids (allmasjids.com)" }, "url": { "type": "string", "format": "uri", "description": "Link to it: the masjid's page, or the website." } } }, "Masjid": { "type": "object", "required": [ "slug", "name", "address", "town", "postcode", "latitude", "longitude", "distance_km", "timetable", "page_url" ], "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "address": { "type": "string" }, "town": { "type": [ "string", "null" ] }, "postcode": { "type": [ "string", "null" ] }, "latitude": { "type": [ "number", "null" ] }, "longitude": { "type": [ "number", "null" ] }, "distance_km": { "type": [ "number", "null" ], "description": "From lat/lng when searching near a point, else null." }, "timetable": { "type": "object", "required": [ "source" ], "properties": { "source": { "$ref": "#/components/schemas/Source" } } }, "page_url": { "type": "string", "format": "uri" } } }, "MasjidDetail": { "allOf": [ { "$ref": "#/components/schemas/Masjid" }, { "type": "object", "required": [ "timezone", "published_at" ], "properties": { "timezone": { "type": "string", "examples": [ "Europe/London" ] }, "published_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the masjid last published its timetable." } } } ] }, "Day": { "type": "object", "required": [ "date", "weekday", "begins", "jamaat", "jumuah", "calculated" ], "properties": { "date": { "type": "string", "format": "date" }, "weekday": { "type": "string", "enum": [ "Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday" ] }, "begins": { "type": "object", "required": [ "fajr", "sunrise", "dhuhr", "asr", "maghrib", "isha" ], "properties": { "fajr": { "type": "string", "pattern": "^[0-2][0-9]:[0-5][0-9]$", "description": "24-hour HH:MM in the masjid's timezone.", "examples": [ "06:15" ] }, "sunrise": { "type": "string", "pattern": "^[0-2][0-9]:[0-5][0-9]$", "description": "24-hour HH:MM in the masjid's timezone.", "examples": [ "06:15" ] }, "dhuhr": { "type": "string", "pattern": "^[0-2][0-9]:[0-5][0-9]$", "description": "24-hour HH:MM in the masjid's timezone.", "examples": [ "06:15" ] }, "asr": { "type": "string", "pattern": "^[0-2][0-9]:[0-5][0-9]$", "description": "24-hour HH:MM in the masjid's timezone.", "examples": [ "06:15" ] }, "maghrib": { "type": "string", "pattern": "^[0-2][0-9]:[0-5][0-9]$", "description": "24-hour HH:MM in the masjid's timezone.", "examples": [ "06:15" ] }, "isha": { "type": "string", "pattern": "^[0-2][0-9]:[0-5][0-9]$", "description": "24-hour HH:MM in the masjid's timezone.", "examples": [ "06:15" ] } } }, "jamaat": { "type": "object", "required": [ "fajr", "dhuhr", "asr", "maghrib", "isha" ], "properties": { "fajr": { "type": [ "string", "null" ], "pattern": "^[0-2][0-9]:[0-5][0-9]$", "description": "24-hour HH:MM in the masjid's timezone, or null when the masjid hasn't set one." }, "dhuhr": { "type": [ "string", "null" ], "pattern": "^[0-2][0-9]:[0-5][0-9]$", "description": "24-hour HH:MM in the masjid's timezone, or null when the masjid hasn't set one." }, "asr": { "type": [ "string", "null" ], "pattern": "^[0-2][0-9]:[0-5][0-9]$", "description": "24-hour HH:MM in the masjid's timezone, or null when the masjid hasn't set one." }, "maghrib": { "type": [ "string", "null" ], "pattern": "^[0-2][0-9]:[0-5][0-9]$", "description": "24-hour HH:MM in the masjid's timezone, or null when the masjid hasn't set one." }, "isha": { "type": [ "string", "null" ], "pattern": "^[0-2][0-9]:[0-5][0-9]$", "description": "24-hour HH:MM in the masjid's timezone, or null when the masjid hasn't set one." } } }, "jumuah": { "type": "array", "items": { "type": "string", "pattern": "^[0-2][0-9]:[0-5][0-9]$", "description": "24-hour HH:MM in the masjid's timezone.", "examples": [ "06:15" ] }, "description": "Jumu'ah jamaat times on Fridays; empty other days." }, "calculated": { "type": "boolean", "description": "True when the masjid's own times don't cover this day: begin times are calculated, and a past day has no jamaat." } } }, "Error": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "key_missing", "key_invalid", "rate_limited", "not_found", "bad_range" ] }, "message": { "type": "string" } } }, "Message": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } }, "ValidationError": { "type": "object", "required": [ "message", "errors" ], "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } } }, "responses": { "Unauthorised": { "description": "No key (key_missing), or one we don't know or that was turned off (key_invalid).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "key_missing", "message": "Send your API key as \"Authorization: Bearer \". Get one free at https://allmasjids.com/developers." } } } }, "NotFound": { "description": "No masjid with that slug has a published timetable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "not_found", "message": "No masjid with that slug has a published timetable. Search /masjids to find one." } } } }, "Invalid": { "description": "A parameter we can't read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "RateLimited": { "description": "More than 600 requests in an hour with this key.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "rate_limited", "message": "Too many requests: try again in 1200 seconds." } } } } } } }