Developer documentation
Read-only JSON and file access to the figures behind this site: what exists, the parameters, the response shape, the errors, and how to cite it.
What is available
Everything here is read-only and exposes only figures already published on this site. There is no key and no sign-up. These are the endpoints that exist today; nothing else is promised.
| Endpoint | Returns |
|---|---|
| /data/catalog.json | Machine-readable catalogue of the downloadable datasets: source, as-of date, update cadence, and each column's name, unit and meaning. |
| /data/<file> | The datasets themselves as CSV or JSON. File names are listed in the catalogue. |
| /api/metrics | Index of every time series: its key, unit, period types, number of geographies and property types, first and last period, and number of points. |
| /api/metrics/<key> | One time series as JSON, filtered by the parameters below. Each value carries its reporting period, unit, source address and the date this site collected it. |
| /api/public/v1/snapshot?lang=en | A compact market snapshot used by the KW Saudi Arabia website's insights section (query: lang=en or ar). |
| /llms.txt · /llms-full.txt · <page>.md | The site as plain text for assistants and crawlers, and a markdown version of guides, city and district pages (add .md to the address). |
Time-series parameters
All parameters are optional. Text comparison is used for periods, so 2025-Q1 sorts before 2025-Q2.
| Parameter | Meaning | Default |
|---|---|---|
| geography | Only this geography, for example KSA, Riyadh, Makkah. | — |
| property_type | Only this property type, for example * (all), apartment, villa. | — |
| from | First reporting period to include (inclusive): 2025, 2025-Q1, 2025-06 or 2025-06-30. | — |
| to | Last reporting period to include (inclusive). | — |
| order | asc (oldest first) or desc (newest first). | asc |
| limit | Rows to return, 1 to 5000. | 1000 |
| offset | Rows to skip, for paging. | 0 |
Response shape
observedAt is the period a value describes. source.collectedAt is when this site fetched it, not when the source published it.
{
"metricKey": "kapsarc.repi.national",
"count": "<rows returned>", "limit": 2, "offset": 0, "order": "desc",
"data": [{
"observedAt": "2026-Q1",
"periodType": "quarterly",
"geography": "KSA",
"propertyType": "*",
"value": "<number>",
"unit": "index",
"changePercent": null,
"sourceSnapshotId": "…",
"source": { "collector": "…", "url": "…", "collectedAt": "…" }
}]
}Errors, caching and limits
400 invalid_request: a parameter is malformed. 404 unknown_metric: the key does not exist (a typo is never returned as an empty success). CORS is open for browser use. Responses are cached for a few minutes, so a value can lag the daily refresh. The server rate-limits heavy use; the limits are not published, so cache what you fetch and do not poll more often than the data changes. There is no uptime guarantee and no versioning promise beyond the version field in the index.
Citation, reuse and licence
Cite as: KW Saudi Arabia Market Insights, the dataset or series name, the URL of the page or endpoint, and the date you accessed it. Quote the reporting period with every figure; a value without its period is not a market statement. The figures come from official publishers (Ministry of Justice, REGA, SAMA, GASTAT and its republisher KAPSARC) and from KW calculations, labelled as such on each page and in the source register. Reuse follows the terms of those underlying sources, which we have not re-licensed: where a dataset came through a community copy, check the original publisher's terms before redistributing it. KW calculations such as gross yield are our computation, not an official figure.
