# Fast Source: the full API guide

> Saudi public data for AI apps and developers. Every answer cites its source and the date it was checked. Base URL: https://source.fast.sa. REST API with a key; MCP connector without one: https://source.fast.sa/mcp

## Quick start
1. Get a key: fill in the form at https://source.fast.sa/#key (email, name, company, what you will build). During v0 we issue keys by hand and email them. A key starts with `sdl_live_`. Keep it secret.
2. Call the API with the key in the Authorization header:
   curl -H "Authorization: Bearer $SDL_KEY" "https://source.fast.sa/v1/calendar/convert?gregorian=2026-10-23"
3. Use `data` and cite `citations`: show each source and its link with the answer, and keep any `notice`.
4. Handle errors by their `code` (see Errors). After `429 rate_limited`, wait the Retry-After seconds and try again.

No key yet? The MCP connector needs none.

## Base URL and versions
https://source.fast.sa. This is v0: paths start with /v1/ and every answer carries "meta": {"version": "v0"}. We may add fields; existing fields keep their meaning.

## Authentication
Every /v1/ call needs `Authorization: Bearer sdl_live_…` (the prefix plus 32 characters). A missing, unknown or revoked key gets 401 unauthorized. We store only a hash of your key: if you lose it, ask for a new one.

## Answer format
Every successful answer, REST or MCP, has this shape:

{
  "data": { … },
  "citations": [
    {
      "source": "Saudi Building Code 2024 catalogue (sbc.gov.sa)",
      "url": "https://www.sbc.gov.sa/En/BC/Pages/BuildingCode/BC.aspx?year=2024",
      "checked_at": "2026-10-23T10:00:00.000Z",
      "licence": "Facts only: code numbers, names and editions",
      "notice": "Full text sold by the Saudi Building Code Center"
    }
  ],
  "meta": { "shelf": "standards", "version": "v0" }
}

- data: the answer itself, an object or a list.
- citations: one entry per source used: source (who published it), url, checked_at (when we last checked that source), licence, and a notice when the source asks for one.
- notice: present when a whole shelf needs one.
- meta: the shelf that answered and the API version.

Field names are snake_case. Dates are YYYY-MM-DD, timestamps are ISO 8601 in UTC, and times of day (prayer times) are Asia/Riyadh.

## Errors
{"error": {"code": "not_found", "message": "No standard with that id"}}

- bad_request (400): a parameter is missing or invalid; the message names it. Fix the request.
- out_of_range (400): the date or year is outside the data we hold (Hijri 1300 to 1600 AH; holidays for 2026 and 2027). Ask within range.
- unauthorized (401): no key, an unknown key or a revoked key. Check the header.
- not_found (404): no such endpoint, record or article. Check the path and the id.
- quota_exceeded (429): this month's calls are used up. They reset on the 1st (Riyadh time); email us if you need more.
- rate_limited (429): too many requests at once. Wait the Retry-After seconds.
- internal_error (500): our fault. Try again later, and tell us if it keeps happening.

## Limits
- Free plan: 250 counted calls per calendar month, Asia/Riyadh time. /v1/usage shows what you have used.
- /v1/sources and /v1/usage are not counted either.
- Up to 10 requests a second per key, and 30 a second from one IP address.
- Answers are bounded: at most 50 results per call.
- MCP connector: up to 60 requests a minute per IP address.

## Endpoints
All endpoints are GET and answer JSON. Full schemas: https://source.fast.sa/openapi.json (OpenAPI 3.1).

### GET /v1/calendar/convert
Convert a date between Gregorian and Hijri (Umm al-Qura) Counts toward the monthly quota.
- gregorian (query, optional): date, YYYY-MM-DD
- hijri (query, optional): date, YYYY-MM-DD

### GET /v1/calendar/prayer-times
Prayer times for a Saudi city or coordinates (Umm al-Qura method, Asia/Riyadh time) Counts toward the monthly quota.
- city (query, optional): text
- lat (query, optional): number
- lng (query, optional): number
- date (query, optional): date, YYYY-MM-DD

### GET /v1/calendar/holidays
Official holidays by sector, each with the regulation it comes from. Counts toward the monthly quota.
- year (query, optional): integer
- sector (query, optional): one of government, private

### GET /v1/calendar/working-day
Whether a date is a working day for a sector, and why. Counts toward the monthly quota.
- date (query, optional): date, YYYY-MM-DD
- sector (query, required): one of government, private

### GET /v1/standards/search
Search Saudi standards and building codes by number or title (facts and where to buy, never the text) Counts toward the monthly quota.
- q (query, required): text
- body (query, optional): one of SASO, SBC
- kind (query, optional): one of standard, technical_regulation, building_code
- limit (query, optional): integer 1–50, default 10

### GET /v1/standards/{id}
One standard's facts: titles, edition, what it adopts, where to read or buy it. Counts toward the monthly quota.
- id (path, required): text

### GET /v1/sources
The public source register: verdict, licence and when each source was last checked. Not counted toward the quota.
No parameters.

### GET /v1/usage
Calls counted this month (Riyadh time) across all of the account's keys, and calls by shelf. Not counted toward the quota.
No parameters.

## MCP connector
URL: https://source.fast.sa/mcp. Streamable HTTP, stateless (POST only, JSON answers), no key, up to 60 requests a minute per IP address. In Claude, add a custom connector with this URL; in ChatGPT, add it as a connector in developer mode. Any MCP client that speaks streamable HTTP works too.

Every tool is read-only. A result has two text parts: a one-paragraph summary that ends with its source line, then the same JSON answer as the REST API. Errors come back as {"error": {"code", "message"}} with isError set.

### convert_saudi_date (Convert Hijri and Gregorian dates)
Converts a date between the Gregorian calendar and the Umm al-Qura Hijri calendar, the official calendar of Saudi Arabia. Give exactly one of gregorian or hijri. Returns both dates, the weekday and the Hijri month name in Arabic and English. Covers 1300 to 1600 AH.
- gregorian (optional): date, YYYY-MM-DD — A Gregorian date, YYYY-MM-DD.
- hijri (optional): date, YYYY-MM-DD — An Umm al-Qura Hijri date, YYYY-MM-DD, e.g. 1447-09-01.

### saudi_prayer_times (Saudi prayer times)
Returns the times of the five daily prayers and sunrise for a Saudi city, or for coordinates inside Saudi Arabia, on a date (default: today in Riyadh). Computed with the Umm al-Qura method, in Asia/Riyadh time. Give a city, or both lat and lng.
- city (optional): text, up to 100 characters — A Saudi city in English or Arabic, e.g. riyadh, jeddah or الدمام.
- lat (optional): number -90–90 — Latitude of a place inside Saudi Arabia (with lng).
- lng (optional): number -180–180 — Longitude of a place inside Saudi Arabia (with lat).
- date (optional): date, YYYY-MM-DD — YYYY-MM-DD; default: today in Riyadh.

### saudi_holidays (Saudi official holidays)
Returns the official holidays of a year for the government sector, the private sector, or both: dates, names in Arabic and English, and the regulation or announcement each rests on, with its link. Years covered: 2026 and 2027.
- year (optional): integer — Gregorian year (2026 or 2027); default: the current year in Riyadh.
- sector (optional): one of government, private — government or private; leave out for both.

### is_saudi_working_day (Check a Saudi working day)
Says whether a date is a working day in Saudi Arabia for the government or the private sector, and why: a weekend, an official holiday (with the regulation it rests on and its link), or a normal working day. Default date: today in Riyadh.
- date (optional): date, YYYY-MM-DD — YYYY-MM-DD; default: today in Riyadh.
- sector (required): one of government, private — government or private.

### search_saudi_standards (Search Saudi standards)
Searches Saudi standards (SASO) and the Saudi Building Code (SBC) by number, e.g. «SBC 201» or «SASO 2902», or by words of the Arabic or English title. Returns the matching standards with number, titles, kind, status, edition year, the international standard adopted, the official page and where the issuing body provides the full text. It never returns the text of a standard.
- query (required): text, up to 500 characters — A standard number (e.g. SBC 201, SASO 2902) or title words in Arabic or English.
- body (optional): one of SASO, SBC — SASO or SBC, to search one body only.
- kind (optional): one of standard, technical_regulation, building_code — standard, technical_regulation or building_code.
- limit (optional): integer 1–50, default 10 — How many results to return, 1 to 50 (default 10).

### get_saudi_standard (Get a Saudi standard)
Returns one Saudi standard or building code by its id (from search_saudi_standards): number, titles, kind, status, edition, the international standard adopted, the official page and where the issuing body provides the full text, with the source and the date it was checked.
- id (required): text, up to 100 characters — The standard id returned by search_saudi_standards, e.g. sbc-201.

## About the data
- Standards come from SASO's open-data list and the Saudi Building Code catalogue: facts and links only. The full texts are sold by their publishers.
- Calendar: Umm al-Qura dates from 1300 to 1600 AH; prayer times computed with the Umm al-Qura method; holidays for 2026 and 2027 from the Civil Service and Labor Law regulations and official announcements.
- /v1/sources lists every source with its licence and the date we last checked it.

## Help
Email data@fast.sa. Terms: https://source.fast.sa/terms. Privacy: https://source.fast.sa/privacy. Support: https://source.fast.sa/support.