{"openapi":"3.1.0","info":{"title":"Kite API","version":"1.0.0","description":"Saudi real-estate listings and market data, aggregated from 20+ sources, deduplicated and quality-filtered. The same inventory powers [kite.sa](https://kite.sa).\n\n## Quickstart\n\n1. [Create a free Kite account](/sign-in?signup=1) and get an API key (`dk_live_…`).\n2. Make a request:\n\n```bash\ncurl \"https://api.kite.sa/v1/listings?city=riyadh&listing_type=rent&limit=5\" \\\n  -H \"Authorization: Bearer $KITE_API_KEY\"\n```\n\n   Or with an official SDK, which adds types, paging and retries. Both cover every endpoint here and are generated from this spec.\n\n```ts\n// npm install @kite-sa/sdk\nimport { Kite } from \"@kite-sa/sdk\";\n\nconst kite = new Kite(); // reads KITE_API_KEY\nconst page = await kite.listings.search({ city: \"riyadh\", listing_type: \"rent\", limit: 5 });\n```\n\n```python\n# pip install kite-sa\nfrom kite_sa import Kite\n\nkite = Kite()  # reads KITE_API_KEY\npage = kite.listings.search(city=\"riyadh\", listing_type=\"rent\", limit=5)\n```\n\n3. Use `GET /cities` and `GET /cities/{city}/neighborhoods` to find the city slugs and neighborhood ids that filters accept, and `GET /enums` for allowed values.\n\nAll responses are JSON. Single objects come back as `{ \"data\": { … } }`, lists as `{ \"data\": [ … ], \"pagination\": { … } }`.\n\n**Where things are.** The OpenAPI document is at [`/v1/openapi.json`](https://api.kite.sa/v1/openapi.json) — no key needed — and generates both SDKs, so you can generate your own client from it too. [`@kite-sa/sdk`](https://www.npmjs.com/package/@kite-sa/sdk) is on npm and [`kite-sa`](https://pypi.org/project/kite-sa/) on PyPI. Changes are announced in the [changelog](https://platform.kite.sa/changelog), which has an RSS feed, and availability is on the [status page](https://platform.kite.sa/status). If something is wrong, look the call up yourself with `GET /organization/request-logs?request_id=…` — it carries the status, the error and the parameter at fault — or email [hello@kite.sa](mailto:hello@kite.sa) quoting the `request_id`.\n\n## Authentication\n\nSend your key in the `Authorization` header on every request:\n\n```\nAuthorization: Bearer dk_live_…\n```\n\n- Keys are secret. Call the API from your servers only: never from browsers, mobile apps or public repositories.\n- A key passed in the URL (`?api_key=`) is rejected with `api_key_in_query`. Rotate any key that was ever put in a URL.\n- Accounts can hold several keys, grouped into projects. A key can be limited to some APIs and given an expiry date; calls outside its APIs fail with `scope_not_in_key`, and an expired key gets `expired_api_key`.\n- To rotate a key, use **Rotate** in the dashboard: you get a new key with the same settings, and the old one keeps working for the grace period you choose, so you can deploy without downtime. Revocation takes effect immediately.\n\n**Storing a key.** Keep it in an environment variable or a secret manager, never in source control. Keys carry a fixed `dk_live_` or `dk_admin_` prefix so secret scanners can spot one easily — if a key does reach a public repository, rotate it straight away and revoke the old one once your deploy is through.\n\n**Two kinds of key.** A data key (`dk_live_…`) reads listings, market data, analytics and projects. An admin key (`dk_admin_…`), created by an organization owner, manages the organization itself — keys, projects, members, usage and audit events — and is the only thing the `/v1/organization` endpoints accept. The two never overlap: a data key on an admin endpoint gets `admin_key_required`, an admin key anywhere else gets `admin_key_not_allowed`. Admin calls aren't metered.\n\n**Test keys.** A `dk_test_…` key reads the same live data as a live key, under a fixed allowance of 10,000 units a month (never more than your plan's own quota) at 300 units a minute, 25 results a page and 250 deep. It counts against its own buckets, so a test key left running in CI can't eat the quota your production integration depends on, and it can never generate a bill — overage is off whatever the plan allows. It reaches the same APIs your plan does, so what you build against is what you ship against. Create one on the API keys page; an organization can hold three, separate from the plan's limit on live keys.\n\n**OAuth is for the MCP server, not direct calls.** People connect AI assistants through [Kite MCP](/docs/guides/mcp) by signing in with OAuth. The MCP server exchanges their token for a short-lived API credential bound to the organization they chose at consent, so those calls count against that organization's plan and appear in its logs. Tokens issued to MCP clients are not accepted by the API directly: a server, script or scheduled job should hold a key.\n\n## What a listing is\n\n- **Prices.** `price.yearly_sar` is the comparable number: rentals posted monthly, weekly or daily are converted to a yearly amount, and sales are the total price. `price.as_posted` keeps the advertiser's original amount and period.\n- **One listing per property.** When the same property is posted on several sources, Kite keeps one listing and lists the others in `also_listed_on`.\n- **Quality filtering.** Search and counts exclude listings with implausible prices or sizes, the same filter kite.sa uses. `GET /listings/{id}` and `/listings/batch` skip that filter, so they return listings search won't.\n- **Photos are a condition of being served.** A listing is only available once Kite has copied its photos to its own CDN — a newly scraped listing appears a little later, and one that never gets photos never appears at all. Land is exempt, since land is routinely advertised without any. This applies to detail and batch lookups too: a photo-less apartment is a `404`, and comes back in `missing_ids`.\n- **Freshness.** `first_seen_at` is when Kite first saw a listing. `updated_at` is its last update at the source, or the last time Kite saw it if the source doesn't publish update times. `last_seen_at` is when Kite last confirmed it is live.\n- **Asking prices.** Listings are asking prices, not transaction prices. Data comes from third-party sources and may be incomplete or out of date.\n- **Attribution.** Where you show listings to your users, credit Kite, link the listing's `url`, and credit its source by name (`source.name`). On paid plans `source.url` is a kite.sa link that forwards to the original ad; on Sandbox it and `source.listing_id` are null.\n\n## Limits and quotas\n\nEvery request costs **units** (shown in `X-Request-Units`, and as `x-units` on each endpoint in this reference):\n\nOne unit is one record.\n\n- List endpoints (listing search, project lists): 1 unit per result asked for with `limit`, counted up to your plan's page size. A page of 100 costs 100.\n- Listing batch: 1 unit per id.\n- Single resources (a listing, its price history, a project) and listing counts: 1 unit.\n- Market statistics (the /market endpoints), a listing's market position and its price band: 50 units.\n- Comparables, rental yield, trends and neighborhood comparison: 75 units.\n- Deals: 2 units per result.\n- Reference data, government open data and transactions: free.\n\nYour plan sets:\n\n- **Rate limit:** units per minute. Headers: `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` (seconds).\n- **Monthly quota:** units per calendar month (UTC). Headers: `X-Quota-Limit`, `X-Quota-Remaining`, `X-Quota-Reset`.\n- **Page size:** the largest `limit` you can request.\n- **Paging depth:** how many results of a single query you can page through. Past it you get `result_window_exceeded`; narrow the query, or sync with `updated_since`.\n\n| Plan | Units / minute | Units / month | Page size | Paging depth | Active keys |\n| --- | --- | --- | --- | --- | --- |\n| Sandbox | 300 | 1,000 | 25 | 500 | 5 |\n| Starter | 600 | 25,000 | 50 | 5,000 | 25 |\n| Growth | 1,500 | 150,000 | 100 | 5,000 | 25 |\n| Pro | 3,000 | 600,000 | 100 | 20,000 | 25 |\n\n**APIs by plan.** Sandbox can try every self-serve API below within its monthly units, to evaluate before you buy. Among paid plans, Starter has listings, reference data, market statistics and, for a listing, its comparables, market position and price band. Growth adds rental yield, trends, neighborhood comparison and below-market listings. Pro adds off-plan projects. Enterprise adds bulk exports of listing data (`POST /exports`). An advertiser's contact details (`GET /listings/{id}/contact`) are in no plan; we enable them for an organization on request. A call to an API your plan doesn't include returns `403 scope_not_in_plan`. When a self-serve plan includes it, `details.upgrade_plan` names that plan and `details.upgrade_url` links to it; for exports and contact details there is no `upgrade_plan`, and the message says whom to contact.\n\nPrices: Sandbox is free and needs no card. Starter is SAR 399 a month, Growth SAR 1,499 and Pro SAR 4,799. Every paid plan can also be billed annually, for less: Starter SAR 3,948 a year, Growth SAR 14,988 and Pro SAR 47,988. Prices exclude 15% VAT; Saudi businesses account for it under the reverse charge. Enterprise starts at SAR 60,000 a year.\n\n**Trial.** Starter and Growth each come with a 7-day trial of that plan: its APIs, up to 20,000 units. It needs a card, which is checked with your bank but not charged until the trial ends; it then continues as that plan, billed monthly or yearly as you chose when you started it (Starter: SAR 399 a month or SAR 3,948 a year; Growth: SAR 1,499 a month or SAR 14,988 a year), unless you cancel, and cancelling returns you to Sandbox. Until it ends you can switch between the Starter and Growth trials, and between monthly and yearly billing. We email you before the first charge. Each person and each card can start one trial.\n\nEnterprise plans set these individually. Your own are on the Plan page in the dashboard, and `GET /limits` returns them to the key making the call — it costs no units, so read it at start-up rather than hard-coding a page size, and the same code works on every plan. A `limit` above your page size is refused with `400 invalid_value` (`param: limit`); `details.max_page_size` gives your page size and, where a self-serve plan allows the size you asked for, `details.upgrade_plan` and `details.upgrade_url` name it.\n\n**Extra usage.** On any paid subscription (Starter, Growth or Pro), requests past the monthly quota keep working and are billed per 1,000 units at the end of the billing period (SAR 20 on Starter, 12 on Growth, 8 on Pro), up to the monthly spend cap an owner sets on the Billing page. At the cap you get `429 spend_cap_reached` until the quota resets. With a cap of 0, the quota is a hard limit (`429 monthly_quota_exceeded`).\n\nOver a limit you get `429` with a `Retry-After` header. Wait that many seconds, then retry. Requests that fail (4xx, 5xx, and 429s) don't count toward your monthly quota.\n\n## Pagination\n\nList endpoints return a page plus:\n\n```json\n\"pagination\": { \"limit\": 25, \"next_cursor\": \"eyJvIjoy….pkFEfJUOpRbZ…\", \"has_more\": true, \"result_window_reached\": false }\n```\n\n- To get the next page, repeat the request with `cursor=<next_cursor>` and **the same parameters**. A cursor used with different filters or sort is rejected.\n- Treat a cursor as an opaque string: pass back exactly what you were given. Cursors are signed, so an edited or hand-built one is rejected with `invalid_cursor`, and their contents will change when the underlying pagination does.\n- `result_window_reached: true` means more results exist but your plan's paging depth is reached. Narrow the query (neighborhood, price, property type) instead of paging deeper.\n- Listing search doesn't return a total. Use `GET /listings/count` with the same filters.\n\nCursors carry an offset, so under `sort=newest` or a price sort a listing added or removed between two pages can shift rows across the boundary and be served twice or skipped. That is inherent to paging a live table, and it is why a sync uses `sort=updated_asc` — see [Keeping a copy in sync](https://platform.kite.sa/docs/guides/sync).\n\n## Retrying safely\n\nA `GET` can be repeated freely. For a `POST`, send an `Idempotency-Key` header — any unique string of up to 255 characters, a UUID is ideal — and the call will happen at most once however many times you send it:\n\n```\nIdempotency-Key: 8f14e45f-ea6a-4cbb-9a2f-3d1c0b7e21aa\n```\n\n- Retry with the **same key and the same body** and you get the first call's response back, with `Idempotent-Replay: true`. Nothing runs twice.\n- The same key with a **different body** is rejected with `409 idempotency_key_reuse`. Generate a key per logical operation, not per process.\n- A call that failed doesn't hold its key: retrying it runs again, which is what you want after a timeout or a `5xx`.\n- Keys are remembered for 24 hours.\n\nWithout the header a retried `POST` runs again in full. On `POST /organization/keys` that means a second key you were only ever shown the secret for once, so send the header.\n\n## Errors\n\nEvery error has the same shape:\n\n```json\n{\n  \"error\": {\n    \"type\": \"invalid_request\",\n    \"code\": \"unknown_parameter\",\n    \"message\": \"Unknown parameter 'bed'.\",\n    \"param\": \"bed\",\n    \"request_id\": \"req_4f1c2d9a8b7e6f5a4b3c2d1e\",\n    \"doc_url\": \"https://platform.kite.sa/docs/guides/errors#unknown-parameter\"\n  }\n}\n```\n\nBranch on `code`: codes are never renamed, though new ones may be added. `message` is for humans and may change. Unknown query parameters are errors, not ignored, so typos surface immediately. Quote `request_id` when you contact us.\n\n- **400 `invalid_request`** — The request is wrong. Fix it; sending it again unchanged fails the same way.\n  - `invalid_value` — A parameter's value isn't accepted. `param` names it.\n  - `missing_parameter` — A required parameter was omitted. `param` names it.\n  - `unknown_parameter` — No such parameter. Unknown ones are rejected, not ignored, so typos surface.\n  - `invalid_body` — The JSON body was malformed or didn't match the schema.\n  - `unknown_city` — That city isn't covered. `GET /cities` lists the slugs that are.\n  - `result_window_exceeded` — Paging past your plan's depth. Narrow the query instead.\n  - `limit_reached` — An account limit is already at its maximum.\n  - `invalid_cursor` — The cursor is malformed, or belongs to a query with different filters or sort. Start the query again.\n\n- **401 `authentication_error`** — The key was missing, malformed or is no longer usable. Don't retry.\n  - `missing_api_key` — No `Authorization: Bearer` header.\n  - `invalid_api_key` — No key matches. Check for a truncated or wrong-environment key.\n  - `revoked_api_key` — This key was revoked. Create a new one.\n  - `expired_api_key` — This key passed its expiry date. Create a new one.\n  - `api_key_in_query` — A key was passed in the URL, where it leaks into logs. Move it to the header and rotate it.\n\n- **403 `permission_error`** — The key is valid but isn't allowed this call. Don't retry.\n  - `scope_not_in_plan` — Your plan doesn't include this API. Upgrade to reach it.\n  - `scope_not_in_key` — Your plan includes this API but this key isn't allowed it. Edit the key.\n  - `admin_key_required` — This endpoint needs an admin key (`dk_admin_…`).\n  - `admin_key_not_allowed` — Admin keys only reach `/v1/organization`. Use a data key here.\n  - `forbidden_action` — Your role in the organization doesn't allow this.\n  - `cr_outside_allowlist` — That commercial registration isn't on your account's allowlist.\n  - `ip_not_allowed` — Your organization's IP allowlist doesn't include this caller's address.\n  - `client_suspended` — The account is suspended. Contact us.\n  - `client_expired` — The account's term has ended. Contact us.\n\n- **404 `not_found`** — No such resource. For a listing, it may simply no longer be live.\n  - `not_found` — No such resource.\n  - `city_not_found` — No such city. `GET /cities` lists them.\n  - `route_not_found` — No such endpoint. The spec is at `/v1/openapi.json`.\n  - `listing_not_found` — No live listing with that id. It may have been delisted.\n  - `neighborhood_not_found` — No such neighborhood in that city.\n  - `project_not_found` — No such off-plan project.\n  - `period_not_found` — The source has published nothing for that period. `details.available_periods` lists what it has.\n  - `release_not_found` — No published release of the Kite Property Index matches. `details.available_releases` lists them.\n  - `export_not_found` — No export with that id for this organization. Exports are kept for 90 days, their files for 7.\n\n- **405 `method_not_allowed`** — Right path, wrong HTTP method. `Allow` lists the ones it takes.\n  - `method_not_allowed` — That path exists, but not for this method.\n\n- **409 `conflict`** — The request can't be applied as things stand. Change it, then retry.\n  - `conflict` — The resource's current state rules this out.\n  - `idempotency_key_reuse` — This `Idempotency-Key` was already used with a different body. Use a new key.\n  - `key_limit` — You already hold the most keys your plan allows. Revoke one first.\n  - `project_limit` — You already hold the most projects your plan allows.\n  - `name_taken` — Something with that name already exists.\n  - `export_limit` — Too many exports in progress, or created today. Wait for one to finish; `details` says which limit.\n\n- **429 `rate_limit_error`** — Slow down. `Retry-After` says how long to wait.\n  - `rate_limited` — Over your per-minute unit rate. Wait `Retry-After` seconds.\n  - `monthly_quota_exceeded` — This month's unit quota is spent. It resets at the start of the next UTC month, or raise the spend cap.\n  - `spend_cap_reached` — Extra usage hit the monthly spend cap an owner set. Raise it to continue.\n  - `project_cap_exceeded` — This key's project hit its own monthly unit cap.\n  - `contact_daily_cap_exceeded` — Your organization received its daily allowance of advertiser phone numbers, across all its keys. It resets at midnight Riyadh time (UTC+3); `Retry-After` says when.\n\n- **500 `api_error`** — Our fault. Retry with exponential backoff.\n  - `internal_error` — Something broke on our side. Retry with backoff; quote `request_id` if it lasts.\n\n`5xx` errors are safe to retry with exponential backoff.\n\n## Versioning\n\nThe version is in the path (`/v1`). Within a version we only make additive changes: new endpoints, optional parameters, response fields and enum values. Your code must ignore fields and values it doesn't recognize.\n\nBreaking changes ship as a new version. The old version keeps working for at least 12 months after the new one launches. Anything deprecated is announced in the [changelog](https://platform.kite.sa/changelog) (with an RSS feed) and by email, and its responses carry a `Deprecation` header (RFC 9745) and, once the date is set, a `Sunset` header (RFC 8594). Watch for those headers in your logs.\n\n## Terms in practice\n\nUse of the API is subject to the [Kite API terms of use](https://platform.kite.sa/legal/terms). Five clauses shape how you build, so they are worth knowing before you design a sync rather than after:\n\n- **Storage is capped at 30 days.** You may keep Kite data to run your application for up to 30 days from when you retrieved it; after that, refresh it through the API or delete it. Aggregated statistics you derive for internal reporting may be kept longer, as long as they can't be reversed into listing-level data. The sync recipe above is built for exactly this: it keeps a copy current rather than accumulating one.\n- **Delisted listings come down within 7 days.** Once a listing stops being returned — sold, rented, withdrawn, merged as a duplicate — stop showing it within 7 days. A listing you can no longer fetch by id, or that comes back in `missing_ids`, is your signal.\n- **Takedowns are 3 business days.** If we tell you specific data must be removed, delete it and stop showing it within 3 business days. Keep the listing ids you have stored addressable so you can act on that.\n- **Attribution is required where you display data.** Show \"Data by Kite\" near it with a link to [kite.sa](https://kite.sa), and where you show an individual listing, link its `url` and credit the source by name (\"Listed on Aqar\"), or link `source.url`, which forwards to the original ad. That credits the original publisher and lets people verify the ad.\n- **Showing data to your users needs a paid plan.** Sandbox is for building and testing, with your own team and test users. No self-serve plan lets you redistribute Kite data as a dataset, feed or API; Enterprise can license redistribution of derived aggregates (medians, indices, yields) that can't be reversed into listings.\n- **Government open data is different.** Responses that carry an `attribution` object (the registered-transaction endpoints under /transactions and /market/transactions, and /market/land-prices) serve Saudi open data under the Saudi Open Data License. None of the rules above apply to it: store it, publish it and resell it as you like, as long as the `attribution` notice and dataset links travel with it (section 3.4 of the API terms).\n\nListings name the advertiser only when the ad carries a REGA licence, and no listing response carries a phone number. Phone numbers come only from `GET /listings/{id}/contact`, one listing at a time, under the `listings:contact` scope, which is enabled per organization on request; use them only to contact the advertiser about that listing. Listing text and images may still contain personal data an advertiser chose to include, and you are an independent controller of whatever you store — the Saudi Personal Data Protection Law applies to you directly.\n","contact":{"name":"Kite","url":"https://platform.kite.sa/docs"},"termsOfService":"https://platform.kite.sa/legal/terms"},"servers":[{"url":"https://api.kite.sa/v1"}],"externalDocs":{"description":"Guides, changelog and status","url":"https://platform.kite.sa"},"security":[{"apiKey":[]}],"tags":[{"name":"Reference data","description":"The cities, neighborhoods, directions and enumerated values that every other filter is expressed in. Start here to learn the slugs and ids the API accepts. Included in every plan."},{"name":"Listings","description":"Every live rental and sale listing in Saudi Arabia, deduplicated across 20+ sources into one listing per property, with photos, full detail and price history. Search them, count them, fetch them by id, and follow a listing's price over time. Included in every plan."},{"name":"Market data","description":"Aggregates over those listings: median asking rents and prices, price and area distributions, supply, and a vacancy indicator, for a city or a single neighborhood. Built for reports and market pages. Starter and up; Sandbox can try it."},{"name":"Official data","description":"Figures from registered contracts rather than listings: REGA's registered rents per neighborhood, and the Kite Property Index as published each month (contracted rent and asking rent). Every price says `price_source: \"registered\"` or `\"asking\"`. Figures built on Saudi open data carry the open-data licence notice and source dataset links, which must travel with them. Served free (0 units) on every plan, including Sandbox."},{"name":"Analytics","description":"Valuation and investment questions answered against the same inventory: comparables for a listing, where its price sits in its market, gross rental yields, price trends, and listings asking noticeably less than their peers. A listing's comparables, market position and price band are on Starter and up; the rest is Growth and up. Sandbox can try all of it."},{"name":"Registered transactions","description":"Sale deals registered with the Ministry of Justice, from its quarterly open data: individual deals by month, neighborhood and land-use class, quarterly price statistics, and land prices per m² with their trend. Prices are registered, not asking, and residential-class deals are mostly vacant plots. Saudi open data, served at no charge under the ODC Attribution License with the notice in every response: free on every plan, and costs no units."},{"name":"Off-plan projects","description":"New developments with their units, price ranges, developers and linked listings, for buyers and lenders tracking new supply. Pro and up; Sandbox can try it."},{"name":"Exports","description":"Whole datasets as files for your warehouse: a snapshot of every listing, a date range of listing changes (new, repriced, delisted), and the free open data (registered deals, registered rents). Exports run in the background and hand back signed links to gzip NDJSON or CSV parts. Listing exports are on Enterprise and cost units per 1,000 rows; open-data exports are free on every plan."},{"name":"Administration","description":"Manage your own organization — keys, projects, members, usage and audit events — with an admin key (`dk_admin_…`). These endpoints are unmetered, and a data key is refused here."}],"paths":{"/cities":{"get":{"operationId":"reference.cities","summary":"List cities","description":"Cities Kite covers. Use `slug` wherever a `city` parameter is accepted. Free on every plan: it costs no units.","tags":["Reference data"],"x-scope":"reference","x-units":0,"security":[{"apiKey":[]}],"parameters":[],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Units allowed per minute.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Units left this minute.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-Request-Units":{"description":"Units this request cost.","schema":{"type":"integer"}},"X-Quota-Limit":{"description":"Units allowed this calendar month (UTC). Absent on unlimited plans.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Units left this calendar month (UTC). Absent on unlimited plans. Reads `0` once a plan with overage is past its quota and still serving.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Seconds until the monthly quota resets. Absent on unlimited plans.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string","description":"Identifier used by every `city` parameter.","example":"riyadh"},"name_en":{"type":"string","example":"Riyadh"},"name_ar":{"type":"string","example":"الرياض"}},"required":["slug","name_en","name_ar"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false},"example":{"data":[{"slug":"riyadh","name_en":"Riyadh","name_ar":"الرياض"}]}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cities/{city}/neighborhoods":{"get":{"operationId":"reference.neighborhoods","summary":"List neighborhoods","description":"Active neighborhoods in a city. Neighborhood `id`s are stable and are how listings and market endpoints refer to neighborhoods. Free on every plan: it costs no units.","tags":["Reference data"],"x-scope":"reference","x-units":0,"security":[{"apiKey":[]}],"parameters":[{"name":"city","in":"path","required":true,"description":"City slug from GET /cities. A town inside a covered region is accepted and resolved to its city (`dammam`, `khobar`, `dhahran`, `jubail` and `qatif` to `eastern_province`; `buraydah` and `unaizah` to `qassim`; `hofuf` to `al_ahsa`), as are Arabic city names. The response's `filters.city` and the `X-Resolved-City` header show the slug used.","example":"riyadh","schema":{"type":"string","pattern":"^[a-z_]+$"}}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Units allowed per minute.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Units left this minute.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-Request-Units":{"description":"Units this request cost.","schema":{"type":"integer"}},"X-Quota-Limit":{"description":"Units allowed this calendar month (UTC). Absent on unlimited plans.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Units left this calendar month (UTC). Absent on unlimited plans. Reads `0` once a plan with overage is past its quota and still serving.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Seconds until the monthly quota resets. Absent on unlimited plans.","schema":{"type":"integer"}},"X-Resolved-City":{"description":"The covered city slug the request's `city` was resolved to, when it differs from what was sent (`city=dammam` answers for `eastern_province`). Absent when the slug was sent as is.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Stable id. Pass as `neighborhood_id` to filter listings and market data.","example":1287},"slug":{"type":"string","example":"al-malqa"},"name_ar":{"type":"string","example":"الملقا"},"name_en":{"type":"string","example":"Al Malqa"},"direction_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"The city direction (north, east, …) it belongs to, if mapped."},"town":{"$ref":"#/components/schemas/NeighborhoodTown"},"center":{"anyOf":[{"type":"object","properties":{"lat":{"type":"number"},"lng":{"type":"number"}},"required":["lat","lng"],"additionalProperties":false},{"type":"null"}],"description":"Approximate centroid."}},"required":["id","slug","name_ar","name_en","direction_id","town","center"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false},"example":{"data":[{"id":1287,"slug":"al-malqa","name_ar":"الملقا","name_en":"Al Malqa","direction_id":null,"town":{"name_en":"Khobar","name_ar":"الخبر"},"center":{"lat":24.8136,"lng":46.6097}}]}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cities/{city}/directions":{"get":{"operationId":"reference.directions","summary":"List city directions","description":"Groupings of neighborhoods by part of the city (north, east, …). Empty for cities that aren't mapped yet. Free on every plan: it costs no units.","tags":["Reference data"],"x-scope":"reference","x-units":0,"security":[{"apiKey":[]}],"parameters":[{"name":"city","in":"path","required":true,"description":"City slug from GET /cities. A town inside a covered region is accepted and resolved to its city (`dammam`, `khobar`, `dhahran`, `jubail` and `qatif` to `eastern_province`; `buraydah` and `unaizah` to `qassim`; `hofuf` to `al_ahsa`), as are Arabic city names. The response's `filters.city` and the `X-Resolved-City` header show the slug used.","example":"riyadh","schema":{"type":"string","pattern":"^[a-z_]+$"}}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Units allowed per minute.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Units left this minute.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-Request-Units":{"description":"Units this request cost.","schema":{"type":"integer"}},"X-Quota-Limit":{"description":"Units allowed this calendar month (UTC). Absent on unlimited plans.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Units left this calendar month (UTC). Absent on unlimited plans. Reads `0` once a plan with overage is past its quota and still serving.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Seconds until the monthly quota resets. Absent on unlimited plans.","schema":{"type":"integer"}},"X-Resolved-City":{"description":"The covered city slug the request's `city` was resolved to, when it differs from what was sent (`city=dammam` answers for `eastern_province`). Absent when the slug was sent as is.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name_en":{"type":"string","example":"North Riyadh"},"name_ar":{"type":"string","example":"شمال الرياض"},"neighborhood_ids":{"type":"array","items":{"type":"integer"}}},"required":["id","name_en","name_ar","neighborhood_ids"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false},"example":{"data":[{"id":3,"name_en":"North Riyadh","name_ar":"شمال الرياض","neighborhood_ids":[342]}]}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/enums":{"get":{"operationId":"reference.enums","summary":"List enumerated values","description":"Allowed values for enumerated fields and filters. New values may be added at any time; clients must tolerate values they don't recognize. Free on every plan: it costs no units.","tags":["Reference data"],"x-scope":"reference","x-units":0,"security":[{"apiKey":[]}],"parameters":[],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Units allowed per minute.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Units left this minute.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-Request-Units":{"description":"Units this request cost.","schema":{"type":"integer"}},"X-Quota-Limit":{"description":"Units allowed this calendar month (UTC). Absent on unlimited plans.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Units left this calendar month (UTC). Absent on unlimited plans. Reads `0` once a plan with overage is past its quota and still serving.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Seconds until the monthly quota resets. Absent on unlimited plans.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"listing_types":{"type":"array","items":{"type":"string"}},"listing_categories":{"type":"array","items":{"type":"string"}},"property_types":{"type":"object","properties":{"residential":{"type":"array","items":{"type":"string"}},"commercial":{"type":"array","items":{"type":"string"}}},"required":["residential","commercial"],"additionalProperties":false},"rent_frequencies":{"type":"array","items":{"type":"string"}},"advertiser_types":{"type":"array","items":{"type":"string"}},"amenities":{"type":"array","items":{"type":"string"}},"project_features":{"type":"array","items":{"type":"string"}},"project_banks":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}}},"required":["listing_types","listing_categories","property_types","rent_frequencies","advertiser_types","amenities","project_features","project_banks","sources"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"listing_types":["rent"],"listing_categories":["residential"],"property_types":{"residential":["apartment"],"commercial":["office"]},"rent_frequencies":["yearly"],"advertiser_types":["company"],"amenities":["parking"],"project_features":["elevator"],"project_banks":["alrajhi"],"sources":[{"id":"aqar","name":"Aqar"}]}}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/limits":{"get":{"operationId":"reference.limits","summary":"Get this key's limits","description":"The plan, rate limit, monthly quota, page size and paging depth that apply to the key making the request, and the APIs it can reach. Free on every plan: it costs no units. Read it at start-up rather than hard-coding a page size, and the same code works on every plan.","tags":["Reference data"],"x-scope":"reference","x-units":0,"security":[{"apiKey":[]}],"parameters":[],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Units allowed per minute.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Units left this minute.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-Request-Units":{"description":"Units this request cost.","schema":{"type":"integer"}},"X-Quota-Limit":{"description":"Units allowed this calendar month (UTC). Absent on unlimited plans.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Units left this calendar month (UTC). Absent on unlimited plans. Reads `0` once a plan with overage is past its quota and still serving.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Seconds until the monthly quota resets. Absent on unlimited plans.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"plan":{"type":"string","description":"Plan id.","example":"growth"},"scopes":{"type":"array","items":{"type":"string"},"description":"APIs this key can reach.","example":["reference","listings"]},"rate_limit_per_minute":{"type":"integer","example":150},"monthly_quota_units":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Null on plans with no monthly quota.","example":200000},"max_page_size":{"type":"integer","description":"The largest `limit` a request may ask for.","example":100},"max_result_depth":{"type":"integer","description":"How many results of one query can be paged through before `result_window_reached`.","example":5000}},"required":["plan","scopes","rate_limit_per_minute","monthly_quota_units","max_page_size","max_result_depth"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"plan":"growth","scopes":["reference","listings"],"rate_limit_per_minute":150,"monthly_quota_units":200000,"max_page_size":100,"max_result_depth":5000}}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/coverage":{"get":{"operationId":"reference.coverage","summary":"What the API covers","description":"What the API can answer, per city: active listings by listing type and kind of property, how many neighborhoods have at least 10 of them, the share with a published nearby price band, the latest registered-deal quarter and how much of it is placed in neighborhoods, and whether registered rents exist. Check it before building on a city or a segment: an empty answer elsewhere can mean nothing matched, or that the data is thin there.\n\nFigures are computed for every city together and refreshed every 3 hours; `computed_at` says when. Free on every plan: it costs no units.","tags":["Reference data"],"x-scope":"reference","x-units":0,"security":[{"apiKey":[]}],"parameters":[{"name":"city","in":"query","required":false,"description":"One city. Omit for all of them.","example":"riyadh","schema":{"type":"string","pattern":"^[a-z_]+$"}}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Units allowed per minute.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Units left this minute.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-Request-Units":{"description":"Units this request cost.","schema":{"type":"integer"}},"X-Quota-Limit":{"description":"Units allowed this calendar month (UTC). Absent on unlimited plans.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Units left this calendar month (UTC). Absent on unlimited plans. Reads `0` once a plan with overage is past its quota and still serving.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Seconds until the monthly quota resets. Absent on unlimited plans.","schema":{"type":"integer"}},"X-Resolved-City":{"description":"The covered city slug the request's `city` was resolved to, when it differs from what was sent (`city=dammam` answers for `eastern_province`). Absent when the slug was sent as is.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"computed_at":{"type":"string","description":"When the figures were computed (ISO 8601).","example":"2026-11-06T09:00:00.000Z"},"cities":{"type":"array","items":{"type":"object","properties":{"city":{"type":"string","example":"riyadh"},"name_en":{"type":"string","example":"Riyadh"},"name_ar":{"type":"string","example":"الرياض"},"listings":{"type":"array","items":{"type":"object","properties":{"listing_type":{"type":"string","enum":["rent","sale"]},"property_family":{"type":"string","enum":["apartment","villa","land","commercial"],"description":"`apartment`; `villa` (villas, floors and duplexes); `land`; `commercial` (offices, shops, warehouses and buildings). `property_types` lists the members."},"property_types":{"type":"array","items":{"type":"string"},"example":["apartment"]},"active_listings":{"type":"integer","description":"Active, deduplicated listings of this kind, counted before the quality filter that search and market statistics apply, so slightly above what they see.","example":21408},"neighborhoods_with_10_listings":{"type":"integer","description":"Neighborhoods with at least 10 of those listings: where neighborhood-level statistics have something to work with.","example":118},"price_band_ready_pct":{"description":"Percent of those listings with a published nearby asking-price comparison (GET /listings/{id}/price-band `status: available`, and the basis of GET /market/below-market). Null when there are no listings.","example":41.3,"type":["number","null"]}},"required":["listing_type","property_family","property_types","active_listings","neighborhoods_with_10_listings","price_band_ready_pct"],"additionalProperties":false},"description":"One row per listing type and property family, zeros included."},"registered_deals":{"type":"object","properties":{"latest_quarter":{"description":"Latest Ministry of Justice quarter GET /transactions serves for the city. Null when there is none.","example":"2026-Q2","type":["string","null"]},"neighborhood_mapped_pct":{"description":"Percent of that quarter's deals that carry a neighborhood, among deals whose district MOJ names (`أخرى` and `خارج حدود الاحياء` name none). Neighborhood filters and groupings on the registered-transaction endpoints see only those.","example":95.3,"type":["number","null"]},"mappable_deals":{"type":"integer","description":"The base of `neighborhood_mapped_pct`.","example":1654}},"required":["latest_quarter","neighborhood_mapped_pct","mappable_deals"],"additionalProperties":false,"description":"Ministry of Justice registered sale deals (open data)."},"registered_rents":{"type":"object","properties":{"available":{"type":"boolean","description":"Whether GET /market/registered-rents has REGA rent index data for the city."},"latest_quarter":{"example":"2026-Q1","type":["string","null"]}},"required":["available","latest_quarter"],"additionalProperties":false,"description":"REGA's registered rent index (open data)."}},"required":["city","name_en","name_ar","listings","registered_deals","registered_rents"],"additionalProperties":false}}},"required":["computed_at","cities"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"computed_at":"2026-11-06T09:00:00.000Z","cities":[{"city":"riyadh","name_en":"Riyadh","name_ar":"الرياض","listings":[{"listing_type":"rent","property_family":"apartment","property_types":["apartment"],"active_listings":21408,"neighborhoods_with_10_listings":118,"price_band_ready_pct":41.3}],"registered_deals":{"latest_quarter":"2026-Q2","neighborhood_mapped_pct":95.3,"mappable_deals":1654},"registered_rents":{"available":true,"latest_quarter":"2026-Q1"}}]}}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/listings":{"get":{"operationId":"listings.search","summary":"Search listings","description":"Active, deduplicated listings in one city, quality-filtered like kite.sa. Paginate with `cursor`. Paging depth per query is limited by plan; to mirror inventory, sort by `updated_asc` and advance `updated_since`.\n\n**Watching for new listings? Subscribe instead of polling.** A webhook (POST /organization/webhooks) posts `listing.created`, `listing.price_changed` and `listing.delisted` to your URL for the same filters as this endpoint, so you don't re-run this query with `sort=newest` on a timer. Deliveries aren't metered: you pay only for the listings you then fetch. See the Webhooks guide.\n\nPrices are asking prices: each listing's `price.price_basis` says whether `price.yearly_sar` is a yearly rent or a total sale price.","tags":["Listings"],"x-scope":"listings","x-units":"1 per result asked for with `limit` (default 25), up to your plan's page size","security":[{"apiKey":[]}],"parameters":[{"name":"city","in":"query","required":true,"description":"City slug from GET /cities. A town inside a covered region is accepted and resolved to its city (`dammam`, `khobar`, `dhahran`, `jubail` and `qatif` to `eastern_province`; `buraydah` and `unaizah` to `qassim`; `hofuf` to `al_ahsa`), as are Arabic city names. The response's `filters.city` and the `X-Resolved-City` header show the slug used.","example":"riyadh","schema":{"type":"string","pattern":"^[a-z_]+$"}},{"name":"listing_type","in":"query","required":true,"schema":{"type":"string","enum":["rent","sale"]}},{"name":"listing_category","in":"query","required":false,"description":"Omit for both.","schema":{"type":"string","enum":["residential","commercial"]}},{"name":"property_type","in":"query","required":false,"description":"One or more, comma-separated.","example":["apartment","villa"],"schema":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"string","enum":["apartment","villa","floor","duplex","office","shop","warehouse","land","building"]}},"style":"form","explode":false},{"name":"neighborhood_id","in":"query","required":false,"description":"Neighborhood ids from GET /cities/{city}/neighborhoods.","schema":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"integer","minimum":1,"maximum":2147483647}},"style":"form","explode":false},{"name":"beds","in":"query","required":false,"description":"Exact number of bedrooms. Exact at every value, including 5 — kite.sa's own filter treats 5 as five-or-more, so the same number returns different sets here. Use `beds_min` for a range.","schema":{"type":"integer","minimum":0,"maximum":20}},{"name":"beds_min","in":"query","required":false,"description":"Minimum number of bedrooms.","schema":{"type":"integer","minimum":0,"maximum":20}},{"name":"beds_max","in":"query","required":false,"description":"Maximum number of bedrooms.","schema":{"type":"integer","minimum":0,"maximum":20}},{"name":"bathrooms_min","in":"query","required":false,"description":"Minimum number of bathrooms.","schema":{"type":"integer","minimum":0,"maximum":20}},{"name":"price_min","in":"query","required":false,"description":"SAR. Yearly for rentals (see `price.yearly_sar`).","schema":{"type":"integer","minimum":0,"maximum":2000000000}},{"name":"price_max","in":"query","required":false,"description":"SAR. Yearly for rentals (see `price.yearly_sar`).","schema":{"type":"integer","minimum":0,"maximum":2000000000}},{"name":"area_min","in":"query","required":false,"description":"Square meters.","schema":{"type":"number","minimum":0,"maximum":10000000}},{"name":"area_max","in":"query","required":false,"description":"Square meters.","schema":{"type":"number","minimum":0,"maximum":10000000}},{"name":"furnished","in":"query","required":false,"description":"`true` matches listings confirmed furnished. `false` matches listings not confirmed furnished: those stated unfurnished and those that don't say. Omit to include all.","schema":{"type":"string","enum":["true","false"]}},{"name":"source","in":"query","required":false,"description":"Source platforms, see GET /enums. Values aren't checked against the list, so a misspelled source narrows to nothing rather than erroring.","schema":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string","pattern":"^[a-z_]+$"}},"style":"form","explode":false},{"name":"bbox","in":"query","required":false,"description":"Bounding box `west,south,east,north` in degrees (GeoJSON order).","example":"46.60,24.70,46.75,24.85","schema":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?(,-?\\d+(\\.\\d+)?){3}$"}},{"name":"updated_since","in":"query","required":false,"description":"Only listings whose `updated_at` is at or after this ISO 8601 time. Combine with `sort=updated_asc` to sync.","example":"2026-09-01T00:00:00Z","schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},{"name":"bathrooms","in":"query","required":false,"description":"Exact number of bathrooms.","schema":{"type":"integer","minimum":0,"maximum":20}},{"name":"bathrooms_max","in":"query","required":false,"description":"Maximum number of bathrooms.","schema":{"type":"integer","minimum":0,"maximum":20}},{"name":"livings_min","in":"query","required":false,"description":"Minimum number of living rooms.","schema":{"type":"integer","minimum":0,"maximum":20}},{"name":"neighborhood_id_exclude","in":"query","required":false,"description":"Exclude these neighborhoods. Ids from GET /cities/{city}/neighborhoods. Listings Kite could not place in a neighborhood are kept — unlike `neighborhood_id`, which drops them.","schema":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"integer","minimum":1,"maximum":2147483647}},"style":"form","explode":false},{"name":"q","in":"query","required":false,"description":"Free-text match on the advertiser's title and description, as posted — not on `headline`, which Kite builds for the response. Several words must all appear; `\"quote a phrase\"` to match it whole, and `|` between words for either. Sources that post no title (Aqar among them) are matched on description alone.","example":"مسبح","schema":{"type":"string","minLength":2,"maxLength":120}},{"name":"amenities","in":"query","required":false,"description":"Only listings that have all of these. See GET /enums.","example":["parking","lift"],"schema":{"minItems":1,"maxItems":11,"type":"array","items":{"type":"string","enum":["ac","kitchen","maid_room","parking","private_roof","lift","pool","gym","balcony","garden","laundry_room"]}},"style":"form","explode":false},{"name":"amenities_exclude","in":"query","required":false,"description":"Exclude listings that have any of these.","schema":{"minItems":1,"maxItems":11,"type":"array","items":{"type":"string","enum":["ac","kitchen","maid_room","parking","private_roof","lift","pool","gym","balcony","garden","laundry_room"]}},"style":"form","explode":false},{"name":"photo_features","in":"query","required":false,"description":"Only listings whose photos show all of these: `real_photos` (photos of the actual property, not renders or stock images), `kitchen_installed` (fitted kitchen cabinets), `ac_split`, `pool`, `roof_terrace`, `balcony`, `large_windows` (a living room or bedroom with large windows). Read from the listing's photos by an automated vision model and published only for features it identifies with high precision, so this is a must-have filter and nothing else: a listing whose photos don't show a feature, or that hasn't been analysed yet, simply doesn't match, and there is no way to ask for listings without a feature. Coverage is homes with photos; recently added listings may not be analysed yet.","example":["kitchen_installed","ac_split"],"schema":{"minItems":1,"maxItems":7,"type":"array","items":{"type":"string","enum":["real_photos","kitchen_installed","ac_split","pool","roof_terrace","balcony","large_windows"]}},"style":"form","explode":false},{"name":"floor","in":"query","required":false,"description":"`ground` for ground-floor listings, `upper` for any stated floor above it. The two do not partition the results: a listing whose floor the source didn't state is in neither.","schema":{"type":"string","enum":["ground","upper"]}},{"name":"source_exclude","in":"query","required":false,"description":"Exclude these source platforms, see GET /enums.","schema":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string","pattern":"^[a-z_]+$"}},"style":"form","explode":false},{"name":"max_age","in":"query","required":false,"description":"Maximum property age in years. In Riyadh the age is checked against municipal building permits from 2018 on: when the ad claims a building at least four years younger than its latest permit allows, the permit's age (the permit year plus a year to build) is used instead. A permit never makes a building younger than its ad says. Aqar records an age of 0 when the advertiser leaves it blank, so an Aqar listing at 0 counts as new only when a Riyadh permit or the ad's own text (first occupant, never lived in, newly built) backs it; otherwise its age is unknown and it doesn't match. Where an ad's own description states the building's age (\"العمر 8 سنوات\") at least three years older than its age field, or the field is empty, the description's age is used.","schema":{"type":"integer","minimum":0,"maximum":100}},{"name":"verified","in":"query","required":false,"description":"`true` for listings the source marks as verified. `false` means everything else — both listings it marked unverified and listings it said nothing about.","schema":{"type":"string","enum":["true","false"]}},{"name":"advertiser_type","in":"query","required":false,"description":"Who posted the ad, where the source says. `company` groups agencies, brokerage companies and developers; `individual` groups individual brokers and owners. Many listings match neither: their source states no category (Aqar, the largest source, states none), or names an intermediary without saying whether it is a firm or a person. So the two values together are well short of all listings; don't use this filter to size a market.","schema":{"type":"string","enum":["company","individual"]}},{"name":"compound","in":"query","required":false,"description":"Compound name, partial match.","schema":{"type":"string","minLength":2,"maxLength":120}},{"name":"in_compound","in":"query","required":false,"description":"Only listings that belong to a compound, whichever one.","schema":{"type":"string","enum":["true","false"]}},{"name":"rent_frequency","in":"query","required":false,"description":"How the rent is advertised. `price.yearly_sar` stays yearly either way; see `price.as_posted`.","schema":{"type":"string","enum":["monthly","yearly"]}},{"name":"days_on_market_min","in":"query","required":false,"description":"Days since Kite first saw the listing.","schema":{"type":"integer","minimum":0,"maximum":3650}},{"name":"days_on_market_max","in":"query","required":false,"description":"Days since Kite first saw the listing.","schema":{"type":"integer","minimum":0,"maximum":3650}},{"name":"zoning","in":"query","required":false,"description":"Only listings whose plot is zoned any of these (`plot.zoning`), comma-separated. Like every plot filter, it matches only listings with a `plot`.","example":["residential"],"schema":{"minItems":1,"maxItems":7,"type":"array","items":{"type":"string","enum":["residential","commercial","mixed","industrial","agricultural","public","other"]}},"style":"form","explode":false},{"name":"corner","in":"query","required":false,"description":"`true`: corner plots only (`plot.is_corner`); `false`: plots not on a corner.","schema":{"type":"string","enum":["true","false"]}},{"name":"street_width_min","in":"query","required":false,"description":"Minimum width in metres of the widest street the plot fronts (`plot.street_width_m`).","example":20,"schema":{"type":"number","minimum":0,"maximum":500}},{"name":"white_land_fee","in":"query","required":false,"description":"`true`: plots in a white-land fee band (`plot.white_land_fee`); `false`: plots outside every band. Bands are mapped for Riyadh only, so `false` matches nothing in other cities.","schema":{"type":"string","enum":["true","false"]}},{"name":"last_sale_within_months","in":"query","required":false,"description":"Only listings whose parcel's last registered sale (`plot.last_registered_sale`) is at most this many calendar months old (`months_since`). Land, villas and buildings only: flats, floors and duplexes have no last sale.","example":12,"schema":{"type":"integer","minimum":0,"maximum":600}},{"name":"ask_to_last_sale_max","in":"query","required":false,"description":"Sale listings only: the asking price is at most this multiple of the parcel's last registered sale, among listings whose area agrees with the deed (`plot.last_registered_sale.ask_to_last_sale_ratio`). `1.05` finds plots offered for at most 5% above what they last sold for.","example":1.05,"schema":{"type":"number","minimum":0.01,"maximum":100}},{"name":"plot_sold","in":"query","required":false,"description":"`true`: only listings whose plot registered a sale while the ad was up (`plot.registered_sale_while_listed`), which on the market means plots most likely sold already. `false`: leaves those out, and keeps every listing with no such sale on record, including those without a `plot`. Land, villas and buildings for sale.","schema":{"type":"string","enum":["true","false"]}},{"name":"sort","in":"query","required":false,"description":"`newest` (first seen by Kite), `updated_desc`/`updated_asc` (by `updated_at`; use `updated_asc` to sync), `price_asc`/`price_desc`, `price_drop` (only listings whose price dropped, biggest drop first; drops over 50% are excluded as likely corrections), `days_on_market_desc`, and `recommended` — Kite's own ranking, blending asking price against comparable listings, how long the ad has been up, how complete it is, and how sought-after the neighborhood is, with no single source allowed to fill the top. It is a ranking rather than an ordering, so it is retuned from time to time and the same query can reorder between releases; page through it freely, but sync with `updated_asc`.","schema":{"default":"newest","type":"string","enum":["newest","updated_desc","updated_asc","price_asc","price_desc","price_drop","days_on_market_desc","recommended"]}},{"name":"limit","in":"query","required":false,"schema":{"default":25,"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":500}},{"name":"updated_after_id","in":"query","required":false,"description":"With updated_since and sort=updated_asc, continue strictly after the last (updated_at, id) pair. Pass the timestamp exactly as returned.","schema":{"type":"integer","minimum":1,"maximum":2147483647}}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Units allowed per minute.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Units left this minute.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-Request-Units":{"description":"Units this request cost.","schema":{"type":"integer"}},"X-Quota-Limit":{"description":"Units allowed this calendar month (UTC). Absent on unlimited plans.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Units left this calendar month (UTC). Absent on unlimited plans. Reads `0` once a plan with overage is past its quota and still serving.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Seconds until the monthly quota resets. Absent on unlimited plans.","schema":{"type":"integer"}},"X-Resolved-City":{"description":"The covered city slug the request's `city` was resolved to, when it differs from what was sent (`city=dammam` answers for `eastern_province`). Absent when the slug was sent as is.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Listing"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"],"additionalProperties":false},"example":{"data":[{"id":128647,"url":"https://kite.sa/en/listing/128647","title":"شقة للإيجار في حي الملقا","headline":"3-bedroom apartment for rent in Al Malqa, Riyadh","description":"شقة ثلاث غرف وصالة ومطبخ راكب، الدور الثاني، قريبة من الخدمات.","description_en":"Three-bedroom apartment with a living room and fitted kitchen, second floor, close to services.","listing_type":"rent","listing_category":"residential","property_type":"apartment","price":{"yearly_sar":60000,"as_posted":{"amount":5000,"frequency":"monthly"},"previous_yearly_sar":66000,"changed_at":"2026-09-21T10:00:00.000Z","price_basis":"yearly_rent","price_source":"asking"},"financing":{"rent_now_pay_later_monthly_sar":5450,"accepts_bank_financing":true,"landlord_payment_plans":{"monthly":true,"quarterly":true,"semiannually":true}},"bedrooms":3,"bathrooms":2,"livings":1,"area_sqm":140,"floor":"2","age_years":4,"furnished":false,"amenities":["ac","kitchen","parking"],"photo_features":[{"feature":"real_photos","image_index":0},{"feature":"kitchen_installed","image_index":3}],"location":{"city":"riyadh","city_name_en":"Riyadh","neighborhood_id":12,"neighborhood_name_ar":"الملقا","neighborhood_name_en":"Al Malqa","lat":24.7869,"lng":46.6215,"street_width_m":20},"plot":{"zoning":"residential","is_corner":false,"frontage_count":1,"facing":["north"],"street_width_m":25,"street_width_source":"official","plot_area_sqm":449.1,"buildable_area_sqm":747,"buildable_far":1.66,"price_per_buildable_sqm_sar":2410,"urban_growth_phase":"1440","urban_growth_year":1440,"white_land_fee":{"band":3,"rate_pct":5,"as_of":"2025-08-26"},"last_registered_sale":{"month":"2026-08","price_sar":1850000,"price_per_sqm_sar":4111,"area_sqm":450,"registry":"Real Estate Registry","areas_agree":true,"ask_to_last_sale_ratio":0.973,"months_since":3},"registered_sale_while_listed":{"month":"2026-10","price_sar":1800000,"registry":"Real Estate Registry","ask_at_sale_sar":1950000,"areas_agree":true,"deal_to_ask_ratio":0.923,"weeks_to_sell":7},"registered_sales_count":1,"match":{"method":"plan_parcel_and_pin","confidence":0.9}},"compound_name":"Sedra","project_id":null,"images":["https://images.darak.app/listings/128647/1.webp"],"image_count":8,"advertiser":{"type":"agency","name":"مكتب الملقا للعقار","name_en":"Al Malqa Real Estate","company":"Al Malqa Real Estate Company","logo":"https://images.example.com/advertisers/al-malqa.png","fal_number":"1100012345","cr":"1010012345","ad_license":"7100232271","contact_available":true},"verified_by_source":true,"source":{"name":"aqar","listing_id":"7788123","url":"https://kite.sa/r/128647"},"also_listed_on":["bayut"],"first_seen_at":"2026-09-21T10:00:00.000Z","updated_at":"2026-09-21T10:00:00.000Z","last_seen_at":"2026-09-21T10:00:00.000Z","days_on_market":12}],"pagination":{"limit":25,"next_cursor":"eyJvIjoyNSwiZiI6IksweTFfU1F3d1BXSiJ9.pkFEfJUOpRbZRS279EDC4v","has_more":true,"result_window_reached":false}}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/listings/count":{"get":{"operationId":"listings.count","summary":"Count listings","description":"How many listings match the same filters as search.","tags":["Listings"],"x-scope":"listings","x-units":1,"security":[{"apiKey":[]}],"parameters":[{"name":"city","in":"query","required":true,"description":"City slug from GET /cities. A town inside a covered region is accepted and resolved to its city (`dammam`, `khobar`, `dhahran`, `jubail` and `qatif` to `eastern_province`; `buraydah` and `unaizah` to `qassim`; `hofuf` to `al_ahsa`), as are Arabic city names. The response's `filters.city` and the `X-Resolved-City` header show the slug used.","example":"riyadh","schema":{"type":"string","pattern":"^[a-z_]+$"}},{"name":"listing_type","in":"query","required":true,"schema":{"type":"string","enum":["rent","sale"]}},{"name":"listing_category","in":"query","required":false,"description":"Omit for both.","schema":{"type":"string","enum":["residential","commercial"]}},{"name":"property_type","in":"query","required":false,"description":"One or more, comma-separated.","example":["apartment","villa"],"schema":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"string","enum":["apartment","villa","floor","duplex","office","shop","warehouse","land","building"]}},"style":"form","explode":false},{"name":"neighborhood_id","in":"query","required":false,"description":"Neighborhood ids from GET /cities/{city}/neighborhoods.","schema":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"integer","minimum":1,"maximum":2147483647}},"style":"form","explode":false},{"name":"beds","in":"query","required":false,"description":"Exact number of bedrooms. Exact at every value, including 5 — kite.sa's own filter treats 5 as five-or-more, so the same number returns different sets here. Use `beds_min` for a range.","schema":{"type":"integer","minimum":0,"maximum":20}},{"name":"beds_min","in":"query","required":false,"description":"Minimum number of bedrooms.","schema":{"type":"integer","minimum":0,"maximum":20}},{"name":"beds_max","in":"query","required":false,"description":"Maximum number of bedrooms.","schema":{"type":"integer","minimum":0,"maximum":20}},{"name":"bathrooms_min","in":"query","required":false,"description":"Minimum number of bathrooms.","schema":{"type":"integer","minimum":0,"maximum":20}},{"name":"price_min","in":"query","required":false,"description":"SAR. Yearly for rentals (see `price.yearly_sar`).","schema":{"type":"integer","minimum":0,"maximum":2000000000}},{"name":"price_max","in":"query","required":false,"description":"SAR. Yearly for rentals (see `price.yearly_sar`).","schema":{"type":"integer","minimum":0,"maximum":2000000000}},{"name":"area_min","in":"query","required":false,"description":"Square meters.","schema":{"type":"number","minimum":0,"maximum":10000000}},{"name":"area_max","in":"query","required":false,"description":"Square meters.","schema":{"type":"number","minimum":0,"maximum":10000000}},{"name":"furnished","in":"query","required":false,"description":"`true` matches listings confirmed furnished. `false` matches listings not confirmed furnished: those stated unfurnished and those that don't say. Omit to include all.","schema":{"type":"string","enum":["true","false"]}},{"name":"source","in":"query","required":false,"description":"Source platforms, see GET /enums. Values aren't checked against the list, so a misspelled source narrows to nothing rather than erroring.","schema":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string","pattern":"^[a-z_]+$"}},"style":"form","explode":false},{"name":"bbox","in":"query","required":false,"description":"Bounding box `west,south,east,north` in degrees (GeoJSON order).","example":"46.60,24.70,46.75,24.85","schema":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?(,-?\\d+(\\.\\d+)?){3}$"}},{"name":"updated_since","in":"query","required":false,"description":"Only listings whose `updated_at` is at or after this ISO 8601 time. Combine with `sort=updated_asc` to sync.","example":"2026-09-01T00:00:00Z","schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},{"name":"bathrooms","in":"query","required":false,"description":"Exact number of bathrooms.","schema":{"type":"integer","minimum":0,"maximum":20}},{"name":"bathrooms_max","in":"query","required":false,"description":"Maximum number of bathrooms.","schema":{"type":"integer","minimum":0,"maximum":20}},{"name":"livings_min","in":"query","required":false,"description":"Minimum number of living rooms.","schema":{"type":"integer","minimum":0,"maximum":20}},{"name":"neighborhood_id_exclude","in":"query","required":false,"description":"Exclude these neighborhoods. Ids from GET /cities/{city}/neighborhoods. Listings Kite could not place in a neighborhood are kept — unlike `neighborhood_id`, which drops them.","schema":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"integer","minimum":1,"maximum":2147483647}},"style":"form","explode":false},{"name":"q","in":"query","required":false,"description":"Free-text match on the advertiser's title and description, as posted — not on `headline`, which Kite builds for the response. Several words must all appear; `\"quote a phrase\"` to match it whole, and `|` between words for either. Sources that post no title (Aqar among them) are matched on description alone.","example":"مسبح","schema":{"type":"string","minLength":2,"maxLength":120}},{"name":"amenities","in":"query","required":false,"description":"Only listings that have all of these. See GET /enums.","example":["parking","lift"],"schema":{"minItems":1,"maxItems":11,"type":"array","items":{"type":"string","enum":["ac","kitchen","maid_room","parking","private_roof","lift","pool","gym","balcony","garden","laundry_room"]}},"style":"form","explode":false},{"name":"amenities_exclude","in":"query","required":false,"description":"Exclude listings that have any of these.","schema":{"minItems":1,"maxItems":11,"type":"array","items":{"type":"string","enum":["ac","kitchen","maid_room","parking","private_roof","lift","pool","gym","balcony","garden","laundry_room"]}},"style":"form","explode":false},{"name":"photo_features","in":"query","required":false,"description":"Only listings whose photos show all of these: `real_photos` (photos of the actual property, not renders or stock images), `kitchen_installed` (fitted kitchen cabinets), `ac_split`, `pool`, `roof_terrace`, `balcony`, `large_windows` (a living room or bedroom with large windows). Read from the listing's photos by an automated vision model and published only for features it identifies with high precision, so this is a must-have filter and nothing else: a listing whose photos don't show a feature, or that hasn't been analysed yet, simply doesn't match, and there is no way to ask for listings without a feature. Coverage is homes with photos; recently added listings may not be analysed yet.","example":["kitchen_installed","ac_split"],"schema":{"minItems":1,"maxItems":7,"type":"array","items":{"type":"string","enum":["real_photos","kitchen_installed","ac_split","pool","roof_terrace","balcony","large_windows"]}},"style":"form","explode":false},{"name":"floor","in":"query","required":false,"description":"`ground` for ground-floor listings, `upper` for any stated floor above it. The two do not partition the results: a listing whose floor the source didn't state is in neither.","schema":{"type":"string","enum":["ground","upper"]}},{"name":"source_exclude","in":"query","required":false,"description":"Exclude these source platforms, see GET /enums.","schema":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string","pattern":"^[a-z_]+$"}},"style":"form","explode":false},{"name":"max_age","in":"query","required":false,"description":"Maximum property age in years. In Riyadh the age is checked against municipal building permits from 2018 on: when the ad claims a building at least four years younger than its latest permit allows, the permit's age (the permit year plus a year to build) is used instead. A permit never makes a building younger than its ad says. Aqar records an age of 0 when the advertiser leaves it blank, so an Aqar listing at 0 counts as new only when a Riyadh permit or the ad's own text (first occupant, never lived in, newly built) backs it; otherwise its age is unknown and it doesn't match. Where an ad's own description states the building's age (\"العمر 8 سنوات\") at least three years older than its age field, or the field is empty, the description's age is used.","schema":{"type":"integer","minimum":0,"maximum":100}},{"name":"verified","in":"query","required":false,"description":"`true` for listings the source marks as verified. `false` means everything else — both listings it marked unverified and listings it said nothing about.","schema":{"type":"string","enum":["true","false"]}},{"name":"advertiser_type","in":"query","required":false,"description":"Who posted the ad, where the source says. `company` groups agencies, brokerage companies and developers; `individual` groups individual brokers and owners. Many listings match neither: their source states no category (Aqar, the largest source, states none), or names an intermediary without saying whether it is a firm or a person. So the two values together are well short of all listings; don't use this filter to size a market.","schema":{"type":"string","enum":["company","individual"]}},{"name":"compound","in":"query","required":false,"description":"Compound name, partial match.","schema":{"type":"string","minLength":2,"maxLength":120}},{"name":"in_compound","in":"query","required":false,"description":"Only listings that belong to a compound, whichever one.","schema":{"type":"string","enum":["true","false"]}},{"name":"rent_frequency","in":"query","required":false,"description":"How the rent is advertised. `price.yearly_sar` stays yearly either way; see `price.as_posted`.","schema":{"type":"string","enum":["monthly","yearly"]}},{"name":"days_on_market_min","in":"query","required":false,"description":"Days since Kite first saw the listing.","schema":{"type":"integer","minimum":0,"maximum":3650}},{"name":"days_on_market_max","in":"query","required":false,"description":"Days since Kite first saw the listing.","schema":{"type":"integer","minimum":0,"maximum":3650}},{"name":"zoning","in":"query","required":false,"description":"Only listings whose plot is zoned any of these (`plot.zoning`), comma-separated. Like every plot filter, it matches only listings with a `plot`.","example":["residential"],"schema":{"minItems":1,"maxItems":7,"type":"array","items":{"type":"string","enum":["residential","commercial","mixed","industrial","agricultural","public","other"]}},"style":"form","explode":false},{"name":"corner","in":"query","required":false,"description":"`true`: corner plots only (`plot.is_corner`); `false`: plots not on a corner.","schema":{"type":"string","enum":["true","false"]}},{"name":"street_width_min","in":"query","required":false,"description":"Minimum width in metres of the widest street the plot fronts (`plot.street_width_m`).","example":20,"schema":{"type":"number","minimum":0,"maximum":500}},{"name":"white_land_fee","in":"query","required":false,"description":"`true`: plots in a white-land fee band (`plot.white_land_fee`); `false`: plots outside every band. Bands are mapped for Riyadh only, so `false` matches nothing in other cities.","schema":{"type":"string","enum":["true","false"]}},{"name":"last_sale_within_months","in":"query","required":false,"description":"Only listings whose parcel's last registered sale (`plot.last_registered_sale`) is at most this many calendar months old (`months_since`). Land, villas and buildings only: flats, floors and duplexes have no last sale.","example":12,"schema":{"type":"integer","minimum":0,"maximum":600}},{"name":"ask_to_last_sale_max","in":"query","required":false,"description":"Sale listings only: the asking price is at most this multiple of the parcel's last registered sale, among listings whose area agrees with the deed (`plot.last_registered_sale.ask_to_last_sale_ratio`). `1.05` finds plots offered for at most 5% above what they last sold for.","example":1.05,"schema":{"type":"number","minimum":0.01,"maximum":100}},{"name":"plot_sold","in":"query","required":false,"description":"`true`: only listings whose plot registered a sale while the ad was up (`plot.registered_sale_while_listed`), which on the market means plots most likely sold already. `false`: leaves those out, and keeps every listing with no such sale on record, including those without a `plot`. Land, villas and buildings for sale.","schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Units allowed per minute.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Units left this minute.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-Request-Units":{"description":"Units this request cost.","schema":{"type":"integer"}},"X-Quota-Limit":{"description":"Units allowed this calendar month (UTC). Absent on unlimited plans.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Units left this calendar month (UTC). Absent on unlimited plans. Reads `0` once a plan with overage is past its quota and still serving.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Seconds until the monthly quota resets. Absent on unlimited plans.","schema":{"type":"integer"}},"X-Resolved-City":{"description":"The covered city slug the request's `city` was resolved to, when it differs from what was sent (`city=dammam` answers for `eastern_province`). Absent when the slug was sent as is.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"total":{"type":"integer"}},"required":["total"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"total":1842}}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/listings/batch":{"get":{"operationId":"listings.batch","summary":"Get listings by id","description":"Up to 100 listings in one call, in the order requested. Ids that are no longer active (sold, rented, removed, or merged as a duplicate) come back in `missing_ids`.","tags":["Listings"],"x-scope":"listings","x-units":"1 per id","security":[{"apiKey":[]}],"parameters":[{"name":"ids","in":"query","required":true,"description":"Comma-separated listing ids.","example":[128647,128650],"schema":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"integer","minimum":1,"maximum":2147483647}},"style":"form","explode":false}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Units allowed per minute.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Units left this minute.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-Request-Units":{"description":"Units this request cost.","schema":{"type":"integer"}},"X-Quota-Limit":{"description":"Units allowed this calendar month (UTC). Absent on unlimited plans.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Units left this calendar month (UTC). Absent on unlimited plans. Reads `0` once a plan with overage is past its quota and still serving.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Seconds until the monthly quota resets. Absent on unlimited plans.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Listing"}},"missing_ids":{"type":"array","items":{"type":"integer"}}},"required":["data","missing_ids"],"additionalProperties":false},"example":{"data":[{"id":128647,"url":"https://kite.sa/en/listing/128647","title":"شقة للإيجار في حي الملقا","headline":"3-bedroom apartment for rent in Al Malqa, Riyadh","description":"شقة ثلاث غرف وصالة ومطبخ راكب، الدور الثاني، قريبة من الخدمات.","description_en":"Three-bedroom apartment with a living room and fitted kitchen, second floor, close to services.","listing_type":"rent","listing_category":"residential","property_type":"apartment","price":{"yearly_sar":60000,"as_posted":{"amount":5000,"frequency":"monthly"},"previous_yearly_sar":66000,"changed_at":"2026-09-21T10:00:00.000Z","price_basis":"yearly_rent","price_source":"asking"},"financing":{"rent_now_pay_later_monthly_sar":5450,"accepts_bank_financing":true,"landlord_payment_plans":{"monthly":true,"quarterly":true,"semiannually":true}},"bedrooms":3,"bathrooms":2,"livings":1,"area_sqm":140,"floor":"2","age_years":4,"furnished":false,"amenities":["ac","kitchen","parking"],"photo_features":[{"feature":"real_photos","image_index":0},{"feature":"kitchen_installed","image_index":3}],"location":{"city":"riyadh","city_name_en":"Riyadh","neighborhood_id":12,"neighborhood_name_ar":"الملقا","neighborhood_name_en":"Al Malqa","lat":24.7869,"lng":46.6215,"street_width_m":20},"plot":{"zoning":"residential","is_corner":false,"frontage_count":1,"facing":["north"],"street_width_m":25,"street_width_source":"official","plot_area_sqm":449.1,"buildable_area_sqm":747,"buildable_far":1.66,"price_per_buildable_sqm_sar":2410,"urban_growth_phase":"1440","urban_growth_year":1440,"white_land_fee":{"band":3,"rate_pct":5,"as_of":"2025-08-26"},"last_registered_sale":{"month":"2026-08","price_sar":1850000,"price_per_sqm_sar":4111,"area_sqm":450,"registry":"Real Estate Registry","areas_agree":true,"ask_to_last_sale_ratio":0.973,"months_since":3},"registered_sale_while_listed":{"month":"2026-10","price_sar":1800000,"registry":"Real Estate Registry","ask_at_sale_sar":1950000,"areas_agree":true,"deal_to_ask_ratio":0.923,"weeks_to_sell":7},"registered_sales_count":1,"match":{"method":"plan_parcel_and_pin","confidence":0.9}},"compound_name":"Sedra","project_id":null,"images":["https://images.darak.app/listings/128647/1.webp"],"image_count":8,"advertiser":{"type":"agency","name":"مكتب الملقا للعقار","name_en":"Al Malqa Real Estate","company":"Al Malqa Real Estate Company","logo":"https://images.example.com/advertisers/al-malqa.png","fal_number":"1100012345","cr":"1010012345","ad_license":"7100232271","contact_available":true},"verified_by_source":true,"source":{"name":"aqar","listing_id":"7788123","url":"https://kite.sa/r/128647"},"also_listed_on":["bayut"],"first_seen_at":"2026-09-21T10:00:00.000Z","updated_at":"2026-09-21T10:00:00.000Z","last_seen_at":"2026-09-21T10:00:00.000Z","days_on_market":12}],"missing_ids":[128650]}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/listings/{id}":{"get":{"operationId":"listings.get","summary":"Get a listing","description":"One active listing. Returns 404 once it's sold, rented or removed, or if it was merged into another listing as a duplicate.","tags":["Listings"],"x-scope":"listings","x-units":1,"security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Listing id.","example":128647,"schema":{"type":"integer","minimum":1,"maximum":2147483647}}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Units allowed per minute.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Units left this minute.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-Request-Units":{"description":"Units this request cost.","schema":{"type":"integer"}},"X-Quota-Limit":{"description":"Units allowed this calendar month (UTC). Absent on unlimited plans.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Units left this calendar month (UTC). Absent on unlimited plans. Reads `0` once a plan with overage is past its quota and still serving.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Seconds until the monthly quota resets. Absent on unlimited plans.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Listing"}},"required":["data"],"additionalProperties":false},"example":{"data":{"id":128647,"url":"https://kite.sa/en/listing/128647","title":"شقة للإيجار في حي الملقا","headline":"3-bedroom apartment for rent in Al Malqa, Riyadh","description":"شقة ثلاث غرف وصالة ومطبخ راكب، الدور الثاني، قريبة من الخدمات.","description_en":"Three-bedroom apartment with a living room and fitted kitchen, second floor, close to services.","listing_type":"rent","listing_category":"residential","property_type":"apartment","price":{"yearly_sar":60000,"as_posted":{"amount":5000,"frequency":"monthly"},"previous_yearly_sar":66000,"changed_at":"2026-09-21T10:00:00.000Z","price_basis":"yearly_rent","price_source":"asking"},"financing":{"rent_now_pay_later_monthly_sar":5450,"accepts_bank_financing":true,"landlord_payment_plans":{"monthly":true,"quarterly":true,"semiannually":true}},"bedrooms":3,"bathrooms":2,"livings":1,"area_sqm":140,"floor":"2","age_years":4,"furnished":false,"amenities":["ac","kitchen","parking"],"photo_features":[{"feature":"real_photos","image_index":0},{"feature":"kitchen_installed","image_index":3}],"location":{"city":"riyadh","city_name_en":"Riyadh","neighborhood_id":12,"neighborhood_name_ar":"الملقا","neighborhood_name_en":"Al Malqa","lat":24.7869,"lng":46.6215,"street_width_m":20},"plot":{"zoning":"residential","is_corner":false,"frontage_count":1,"facing":["north"],"street_width_m":25,"street_width_source":"official","plot_area_sqm":449.1,"buildable_area_sqm":747,"buildable_far":1.66,"price_per_buildable_sqm_sar":2410,"urban_growth_phase":"1440","urban_growth_year":1440,"white_land_fee":{"band":3,"rate_pct":5,"as_of":"2025-08-26"},"last_registered_sale":{"month":"2026-08","price_sar":1850000,"price_per_sqm_sar":4111,"area_sqm":450,"registry":"Real Estate Registry","areas_agree":true,"ask_to_last_sale_ratio":0.973,"months_since":3},"registered_sale_while_listed":{"month":"2026-10","price_sar":1800000,"registry":"Real Estate Registry","ask_at_sale_sar":1950000,"areas_agree":true,"deal_to_ask_ratio":0.923,"weeks_to_sell":7},"registered_sales_count":1,"match":{"method":"plan_parcel_and_pin","confidence":0.9}},"compound_name":"Sedra","project_id":null,"images":["https://images.darak.app/listings/128647/1.webp"],"image_count":8,"advertiser":{"type":"agency","name":"مكتب الملقا للعقار","name_en":"Al Malqa Real Estate","company":"Al Malqa Real Estate Company","logo":"https://images.example.com/advertisers/al-malqa.png","fal_number":"1100012345","cr":"1010012345","ad_license":"7100232271","contact_available":true},"verified_by_source":true,"source":{"name":"aqar","listing_id":"7788123","url":"https://kite.sa/r/128647"},"also_listed_on":["bayut"],"first_seen_at":"2026-09-21T10:00:00.000Z","updated_at":"2026-09-21T10:00:00.000Z","last_seen_at":"2026-09-21T10:00:00.000Z","days_on_market":12}}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/listings/{id}/price-history":{"get":{"operationId":"listings.price_history","summary":"Get a listing's price history","description":"Every price change Kite recorded for an active listing, oldest first. The Sandbox plan sees the last 90 days; paid plans see the full history.","tags":["Listings"],"x-scope":"listings","x-units":1,"security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Listing id.","example":128647,"schema":{"type":"integer","minimum":1,"maximum":2147483647}}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Units allowed per minute.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Units left this minute.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-Request-Units":{"description":"Units this request cost.","schema":{"type":"integer"}},"X-Quota-Limit":{"description":"Units allowed this calendar month (UTC). Absent on unlimited plans.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Units left this calendar month (UTC). Absent on unlimited plans. Reads `0` once a plan with overage is past its quota and still serving.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Seconds until the monthly quota resets. Absent on unlimited plans.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"listing_id":{"type":"integer"},"current_price_yearly_sar":{"anyOf":[{"type":"integer"},{"type":"null"}]},"first_seen_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","example":"2026-09-21T10:00:00.000Z"},{"type":"null"}]},"history_window_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Days of history included: 90 on the Sandbox plan, null (all of it) on paid plans."},"changes":{"type":"array","items":{"type":"object","properties":{"changed_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","example":"2026-09-21T10:00:00.000Z"},"from_yearly_sar":{"type":"integer"},"to_yearly_sar":{"anyOf":[{"type":"integer"},{"type":"null"}]}},"required":["changed_at","from_yearly_sar","to_yearly_sar"],"additionalProperties":false}}},"required":["listing_id","current_price_yearly_sar","first_seen_at","history_window_days","changes"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"listing_id":128647,"current_price_yearly_sar":null,"first_seen_at":"2026-09-21T10:00:00.000Z","history_window_days":null,"changes":[{"changed_at":"2026-09-21T10:00:00.000Z","from_yearly_sar":80000,"to_yearly_sar":null}]}}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/listings/{id}/contact":{"get":{"operationId":"listings.contact","summary":"Get a listing's advertiser contact","description":"The advertiser's phone number for one active listing. **Only to contact the advertiser about this listing. Not for marketing lists or resale.**\n\nA number is returned only when the ad carries a REGA licence (an advertising licence, which owners posting their own property also hold, or a FAL brokerage licence), Kite holds a number for it, and no takedown or removal request covers it. Otherwise `available` is false and `reason` says why; `source_url` still leads to the original ad. `advertiser.contact_available` on a listing tells you in advance.\n\nNeeds the `listings:contact` scope, which no plan includes: Kite enables it for an organization on request. Test keys and the dashboard playground can't call it. Each organization can receive 200 numbers per day across all its keys; the allowance resets at midnight Riyadh time (UTC+3), and past it the call returns 429 `contact_daily_cap_exceeded` with `Retry-After`. Answers without a number don't count toward it. Every lookup is logged with your organization, key and the listing. Responses are `Cache-Control: private, no-store`: don't cache or store the number beyond the conversation it was fetched for.","tags":["Listings"],"x-scope":"listings:contact","x-units":1,"security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Listing id.","example":128647,"schema":{"type":"integer","minimum":1,"maximum":2147483647}}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Units allowed per minute.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Units left this minute.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-Request-Units":{"description":"Units this request cost.","schema":{"type":"integer"}},"X-Quota-Limit":{"description":"Units allowed this calendar month (UTC). Absent on unlimited plans.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Units left this calendar month (UTC). Absent on unlimited plans. Reads `0` once a plan with overage is past its quota and still serving.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Seconds until the monthly quota resets. Absent on unlimited plans.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"available":{"type":"boolean","example":true},"reason":{"anyOf":[{"type":"string","enum":["unlicensed","removal_requested","suppressed","no_phone"]},{"type":"null"}],"description":"Why no number is returned; null when `available` is true. `unlicensed`: the ad carries no REGA licence (neither an advertising licence nor a FAL brokerage licence). `removal_requested`: the advertiser or owner asked for the listing to be removed. `suppressed`: a takedown covers this advertiser or listing. `no_phone`: the ad is licensed but Kite holds no number for it.","example":null},"phone":{"description":"The advertiser's phone number, as posted.","example":"0555000000","type":["string","null"]},"whatsapp":{"description":"WhatsApp number, when the source gives one apart from the phone.","example":null,"type":["string","null"]},"source_url":{"description":"A kite.sa link that forwards to the original ad, where the advertiser can be reached through the source. Null on the Sandbox plan, or when the source has no ad page.","example":"https://kite.sa/r/128647","type":["string","null"]}},"required":["available","reason","phone","whatsapp","source_url"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"available":true,"reason":null,"phone":"0555000000","whatsapp":null,"source_url":"https://kite.sa/r/128647"}}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/market/summary":{"get":{"operationId":"market.summary","summary":"Market summary","description":"Headline numbers for a city (or neighborhoods): listing count, median and quartile price, median area and price per m², how recently listings were updated, and breakdowns by property type, top neighborhoods by volume, and source.\n\nComputed over the market sample: active, deduplicated listings updated in the last 30 days (`updated_at`), after the same outlier filter kite.sa uses (per-tier price fences from the median and MAD of log price, bedroom and area sanity checks, and a floor at 30% of the neighborhood median). Prices are asking prices in SAR: yearly rent for `listing_type=rent` (monthly, weekly and daily postings are converted to a yearly amount), total price for `listing_type=sale`. Check `sample_size` before relying on a number; small samples are noisy.","tags":["Market data"],"x-scope":"market","x-units":50,"security":[{"apiKey":[]}],"parameters":[{"name":"city","in":"query","required":true,"description":"City slug from GET /cities. A town inside a covered region is accepted and resolved to its city (`dammam`, `khobar`, `dhahran`, `jubail` and `qatif` to `eastern_province`; `buraydah` and `unaizah` to `qassim`; `hofuf` to `al_ahsa`), as are Arabic city names. The response's `filters.city` and the `X-Resolved-City` header show the slug used.","example":"riyadh","schema":{"type":"string","pattern":"^[a-z_]+$"}},{"name":"listing_type","in":"query","required":true,"description":"`rent` (prices are yearly rent) or `sale` (prices are total price).","schema":{"type":"string","enum":["rent","sale"]}},{"name":"listing_category","in":"query","required":false,"description":"Defaults to `residential` when `property_type` is omitted, so dwellings and commercial stock are never mixed into one median. With a `property_type`, omit it to include both categories of that type.","schema":{"type":"string","enum":["residential","commercial"]}},{"name":"property_type","in":"query","required":false,"description":"One property type, see GET /enums.","example":"apartment","schema":{"type":"string","enum":["apartment","villa","floor","duplex","office","shop","warehouse","land","building"]}},{"name":"beds","in":"query","required":false,"description":"Exact number of bedrooms (0 = studio).","example":2,"schema":{"type":"integer","minimum":0,"maximum":20}},{"name":"neighborhood_id","in":"query","required":false,"description":"Limit to one or more neighborhoods (comma-separated ids from GET /cities/{city}/neighborhoods). Unknown ids are a 404.","example":[1287],"schema":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"integer","minimum":1,"maximum":2147483647}},"style":"form","explode":false}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Units allowed per minute.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Units left this minute.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-Request-Units":{"description":"Units this request cost.","schema":{"type":"integer"}},"X-Quota-Limit":{"description":"Units allowed this calendar month (UTC). Absent on unlimited plans.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Units left this calendar month (UTC). Absent on unlimited plans. Reads `0` once a plan with overage is past its quota and still serving.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Seconds until the monthly quota resets. Absent on unlimited plans.","schema":{"type":"integer"}},"X-Resolved-City":{"description":"The covered city slug the request's `city` was resolved to, when it differs from what was sent (`city=dammam` answers for `eastern_province`). Absent when the slug was sent as is.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"filters":{"type":"object","properties":{"city":{"type":"string","example":"riyadh"},"listing_type":{"type":"string","enum":["rent","sale"]},"listing_category":{"anyOf":[{"type":"string","enum":["residential","commercial"]},{"type":"null"}],"description":"The category applied; null when both are included."},"property_type":{"example":"apartment","type":["string","null"]},"neighborhood_ids":{"anyOf":[{"type":"array","items":{"type":"integer"}},{"type":"null"}],"example":[12]},"beds":{"anyOf":[{"type":"integer"},{"type":"null"}],"example":3}},"required":["city","listing_type","listing_category","property_type","neighborhood_ids","beds"],"additionalProperties":false,"description":"The filters the numbers were computed for, after defaults."},"price_basis":{"type":"string","enum":["yearly_rent","sale_price"],"description":"What the `*_sar` price fields mean: `yearly_rent` (SAR per year) for rentals, `sale_price` (total SAR) for sales."},"price_source":{"type":"string","enum":["asking","registered"],"description":"Where the prices come from: `asking` = advertised asking prices from listings; `registered` = registered transactions or rent contracts. Asking prices typically sit above what is finally agreed.","example":"asking"},"sample_size":{"type":"integer","description":"Listings in the sample.","example":18234},"median_price_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Median price.","example":60000},"p25_price_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"25th percentile price.","example":48000},"p75_price_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"75th percentile price.","example":78000},"median_area_sqm":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Median area in m², over listings that state an area.","example":140},"median_price_per_sqm_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Median of each listing's price divided by its area.","example":430},"area_sample_size":{"type":"integer","description":"Listings that state an area (the base of the area medians).","example":16102},"updated_last_3_days":{"type":"integer","example":6120},"updated_last_7_days":{"type":"integer","example":11480},"by_property_type":{"type":"array","items":{"type":"object","properties":{"property_type":{"type":"string","example":"apartment"},"sample_size":{"type":"integer","example":18234},"median_price_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"example":60000}},"required":["property_type","sample_size","median_price_sar"],"additionalProperties":false}},"top_neighborhoods":{"type":"array","items":{"type":"object","properties":{"neighborhood_id":{"type":"integer","example":12},"name_ar":{"type":"string","example":"الملقا"},"name_en":{"type":"string","example":"Al Malqa"},"town":{"$ref":"#/components/schemas/NeighborhoodTown"},"sample_size":{"type":"integer","example":214},"median_price_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"example":85000}},"required":["neighborhood_id","name_ar","name_en","town","sample_size","median_price_sar"],"additionalProperties":false},"description":"Up to 10 neighborhoods with the most listings in the sample."},"sources":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string","example":"aqar"},"count":{"type":"integer","example":9120}},"required":["source","count"],"additionalProperties":false},"description":"Listings in the sample per source (after deduplication)."},"window":{"type":"object","properties":{"updated_within_days":{"type":"integer","example":30},"from":{"type":"string","description":"Listings updated at or after this time are included (ISO 8601).","example":"2026-08-23T09:00:00.000Z"},"to":{"type":"string","description":"When the numbers were computed (ISO 8601). Results are cached up to an hour.","example":"2026-09-22T09:00:00.000Z"}},"required":["updated_within_days","from","to"],"additionalProperties":false,"description":"The freshness window every market number uses."}},"required":["filters","price_basis","price_source","sample_size","median_price_sar","p25_price_sar","p75_price_sar","median_area_sqm","median_price_per_sqm_sar","area_sample_size","updated_last_3_days","updated_last_7_days","by_property_type","top_neighborhoods","sources","window"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"filters":{"city":"riyadh","listing_type":"rent","listing_category":"residential","property_type":"apartment","neighborhood_ids":[12],"beds":3},"price_basis":"yearly_rent","price_source":"asking","sample_size":18234,"median_price_sar":60000,"p25_price_sar":48000,"p75_price_sar":78000,"median_area_sqm":140,"median_price_per_sqm_sar":430,"area_sample_size":16102,"updated_last_3_days":6120,"updated_last_7_days":11480,"by_property_type":[{"property_type":"apartment","sample_size":18234,"median_price_sar":60000}],"top_neighborhoods":[{"neighborhood_id":12,"name_ar":"الملقا","name_en":"Al Malqa","town":{"name_en":"Khobar","name_ar":"الخبر"},"sample_size":214,"median_price_sar":85000}],"sources":[{"source":"aqar","count":9120}],"window":{"updated_within_days":30,"from":"2026-08-23T09:00:00.000Z","to":"2026-09-22T09:00:00.000Z"}}}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/market/price-distribution":{"get":{"operationId":"market.price_distribution","summary":"Price distribution","description":"Histogram and percentiles of price. Buckets are equal-width between `range_sar.min` (the lowest outlier fence, rounded down) and `range_sar.max` (kite.sa's price-slider maximum for the property type); listings outside that range are reported in `below_range_count` / `above_range_count` and still count toward the median and percentiles.\n\nComputed over the market sample: active, deduplicated listings updated in the last 30 days (`updated_at`), after the same outlier filter kite.sa uses (per-tier price fences from the median and MAD of log price, bedroom and area sanity checks, and a floor at 30% of the neighborhood median). Prices are asking prices in SAR: yearly rent for `listing_type=rent` (monthly, weekly and daily postings are converted to a yearly amount), total price for `listing_type=sale`. Check `sample_size` before relying on a number; small samples are noisy.","tags":["Market data"],"x-scope":"market","x-units":50,"security":[{"apiKey":[]}],"parameters":[{"name":"city","in":"query","required":true,"description":"City slug from GET /cities. A town inside a covered region is accepted and resolved to its city (`dammam`, `khobar`, `dhahran`, `jubail` and `qatif` to `eastern_province`; `buraydah` and `unaizah` to `qassim`; `hofuf` to `al_ahsa`), as are Arabic city names. The response's `filters.city` and the `X-Resolved-City` header show the slug used.","example":"riyadh","schema":{"type":"string","pattern":"^[a-z_]+$"}},{"name":"listing_type","in":"query","required":true,"description":"`rent` (prices are yearly rent) or `sale` (prices are total price).","schema":{"type":"string","enum":["rent","sale"]}},{"name":"listing_category","in":"query","required":false,"description":"Defaults to `residential` when `property_type` is omitted, so dwellings and commercial stock are never mixed into one median. With a `property_type`, omit it to include both categories of that type.","schema":{"type":"string","enum":["residential","commercial"]}},{"name":"property_type","in":"query","required":false,"description":"One property type, see GET /enums.","example":"apartment","schema":{"type":"string","enum":["apartment","villa","floor","duplex","office","shop","warehouse","land","building"]}},{"name":"beds","in":"query","required":false,"description":"Exact number of bedrooms (0 = studio).","example":2,"schema":{"type":"integer","minimum":0,"maximum":20}},{"name":"neighborhood_id","in":"query","required":false,"description":"Limit to one or more neighborhoods (comma-separated ids from GET /cities/{city}/neighborhoods). Unknown ids are a 404.","example":[1287],"schema":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"integer","minimum":1,"maximum":2147483647}},"style":"form","explode":false},{"name":"bucket_count","in":"query","required":false,"description":"Number of equal-width histogram buckets.","schema":{"default":30,"type":"integer","minimum":5,"maximum":100}}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Units allowed per minute.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Units left this minute.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-Request-Units":{"description":"Units this request cost.","schema":{"type":"integer"}},"X-Quota-Limit":{"description":"Units allowed this calendar month (UTC). Absent on unlimited plans.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Units left this calendar month (UTC). Absent on unlimited plans. Reads `0` once a plan with overage is past its quota and still serving.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Seconds until the monthly quota resets. Absent on unlimited plans.","schema":{"type":"integer"}},"X-Resolved-City":{"description":"The covered city slug the request's `city` was resolved to, when it differs from what was sent (`city=dammam` answers for `eastern_province`). Absent when the slug was sent as is.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"filters":{"type":"object","properties":{"city":{"type":"string","example":"riyadh"},"listing_type":{"type":"string","enum":["rent","sale"]},"listing_category":{"anyOf":[{"type":"string","enum":["residential","commercial"]},{"type":"null"}],"description":"The category applied; null when both are included."},"property_type":{"example":"apartment","type":["string","null"]},"neighborhood_ids":{"anyOf":[{"type":"array","items":{"type":"integer"}},{"type":"null"}],"example":[12]},"beds":{"anyOf":[{"type":"integer"},{"type":"null"}],"example":3}},"required":["city","listing_type","listing_category","property_type","neighborhood_ids","beds"],"additionalProperties":false,"description":"The filters the numbers were computed for, after defaults."},"price_basis":{"type":"string","enum":["yearly_rent","sale_price"],"description":"What the `*_sar` price fields mean: `yearly_rent` (SAR per year) for rentals, `sale_price` (total SAR) for sales."},"price_source":{"type":"string","enum":["asking","registered"],"description":"Where the prices come from: `asking` = advertised asking prices from listings; `registered` = registered transactions or rent contracts. Asking prices typically sit above what is finally agreed.","example":"asking"},"sample_size":{"type":"integer","example":214},"median_price_sar":{"anyOf":[{"type":"integer"},{"type":"null"}]},"mean_price_sar":{"anyOf":[{"type":"integer"},{"type":"null"}]},"percentiles_sar":{"type":"object","properties":{"p10":{"anyOf":[{"type":"integer"},{"type":"null"}]},"p25":{"anyOf":[{"type":"integer"},{"type":"null"}]},"p75":{"anyOf":[{"type":"integer"},{"type":"null"}]},"p90":{"anyOf":[{"type":"integer"},{"type":"null"}]}},"required":["p10","p25","p75","p90"],"additionalProperties":false,"description":"Price percentiles in SAR."},"range_sar":{"type":"object","properties":{"min":{"type":"integer"},"max":{"type":"integer"}},"required":["min","max"],"additionalProperties":false},"buckets":{"type":"array","items":{"type":"object","properties":{"min_sar":{"type":"integer","description":"Inclusive lower bound."},"max_sar":{"type":"integer","description":"Exclusive upper bound."},"count":{"type":"integer"}},"required":["min_sar","max_sar","count"],"additionalProperties":false}},"below_range_count":{"type":"integer"},"above_range_count":{"type":"integer"},"window":{"type":"object","properties":{"updated_within_days":{"type":"integer","example":30},"from":{"type":"string","description":"Listings updated at or after this time are included (ISO 8601).","example":"2026-08-23T09:00:00.000Z"},"to":{"type":"string","description":"When the numbers were computed (ISO 8601). Results are cached up to an hour.","example":"2026-09-22T09:00:00.000Z"}},"required":["updated_within_days","from","to"],"additionalProperties":false,"description":"The freshness window every market number uses."}},"required":["filters","price_basis","price_source","sample_size","median_price_sar","mean_price_sar","percentiles_sar","range_sar","buckets","below_range_count","above_range_count","window"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"filters":{"city":"riyadh","listing_type":"rent","listing_category":"residential","property_type":"apartment","neighborhood_ids":[12],"beds":3},"price_basis":"yearly_rent","price_source":"asking","sample_size":214,"median_price_sar":null,"mean_price_sar":null,"percentiles_sar":{"p10":null,"p25":null,"p75":null,"p90":null},"range_sar":{"min":55000,"max":95000},"buckets":[{"min_sar":60000,"max_sar":70000,"count":38}],"below_range_count":4,"above_range_count":6,"window":{"updated_within_days":30,"from":"2026-08-23T09:00:00.000Z","to":"2026-09-22T09:00:00.000Z"}}}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/market/area-distribution":{"get":{"operationId":"market.area_distribution","summary":"Area distribution","description":"Histogram and percentiles of floor/plot area (m²) over listings in the sample that state an area (`without_area_count` did not). Buckets are equal-width from 0 to `range_sqm.max` (kite.sa's area-slider maximum for the property type); larger listings are counted in `above_range_count` and still count toward the median and percentiles.\n\nComputed over the market sample: active, deduplicated listings updated in the last 30 days (`updated_at`), after the same outlier filter kite.sa uses (per-tier price fences from the median and MAD of log price, bedroom and area sanity checks, and a floor at 30% of the neighborhood median). Prices are asking prices in SAR: yearly rent for `listing_type=rent` (monthly, weekly and daily postings are converted to a yearly amount), total price for `listing_type=sale`. Check `sample_size` before relying on a number; small samples are noisy.","tags":["Market data"],"x-scope":"market","x-units":50,"security":[{"apiKey":[]}],"parameters":[{"name":"city","in":"query","required":true,"description":"City slug from GET /cities. A town inside a covered region is accepted and resolved to its city (`dammam`, `khobar`, `dhahran`, `jubail` and `qatif` to `eastern_province`; `buraydah` and `unaizah` to `qassim`; `hofuf` to `al_ahsa`), as are Arabic city names. The response's `filters.city` and the `X-Resolved-City` header show the slug used.","example":"riyadh","schema":{"type":"string","pattern":"^[a-z_]+$"}},{"name":"listing_type","in":"query","required":true,"description":"`rent` (prices are yearly rent) or `sale` (prices are total price).","schema":{"type":"string","enum":["rent","sale"]}},{"name":"listing_category","in":"query","required":false,"description":"Defaults to `residential` when `property_type` is omitted, so dwellings and commercial stock are never mixed into one median. With a `property_type`, omit it to include both categories of that type.","schema":{"type":"string","enum":["residential","commercial"]}},{"name":"property_type","in":"query","required":false,"description":"One property type, see GET /enums.","example":"apartment","schema":{"type":"string","enum":["apartment","villa","floor","duplex","office","shop","warehouse","land","building"]}},{"name":"beds","in":"query","required":false,"description":"Exact number of bedrooms (0 = studio).","example":2,"schema":{"type":"integer","minimum":0,"maximum":20}},{"name":"neighborhood_id","in":"query","required":false,"description":"Limit to one or more neighborhoods (comma-separated ids from GET /cities/{city}/neighborhoods). Unknown ids are a 404.","example":[1287],"schema":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"integer","minimum":1,"maximum":2147483647}},"style":"form","explode":false},{"name":"bucket_count","in":"query","required":false,"description":"Number of equal-width histogram buckets.","schema":{"default":30,"type":"integer","minimum":5,"maximum":100}}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Units allowed per minute.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Units left this minute.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-Request-Units":{"description":"Units this request cost.","schema":{"type":"integer"}},"X-Quota-Limit":{"description":"Units allowed this calendar month (UTC). Absent on unlimited plans.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Units left this calendar month (UTC). Absent on unlimited plans. Reads `0` once a plan with overage is past its quota and still serving.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Seconds until the monthly quota resets. Absent on unlimited plans.","schema":{"type":"integer"}},"X-Resolved-City":{"description":"The covered city slug the request's `city` was resolved to, when it differs from what was sent (`city=dammam` answers for `eastern_province`). Absent when the slug was sent as is.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"filters":{"type":"object","properties":{"city":{"type":"string","example":"riyadh"},"listing_type":{"type":"string","enum":["rent","sale"]},"listing_category":{"anyOf":[{"type":"string","enum":["residential","commercial"]},{"type":"null"}],"description":"The category applied; null when both are included."},"property_type":{"example":"apartment","type":["string","null"]},"neighborhood_ids":{"anyOf":[{"type":"array","items":{"type":"integer"}},{"type":"null"}],"example":[12]},"beds":{"anyOf":[{"type":"integer"},{"type":"null"}],"example":3}},"required":["city","listing_type","listing_category","property_type","neighborhood_ids","beds"],"additionalProperties":false,"description":"The filters the numbers were computed for, after defaults."},"sample_size":{"type":"integer","description":"Listings that state an area."},"without_area_count":{"type":"integer"},"median_area_sqm":{"anyOf":[{"type":"integer"},{"type":"null"}]},"mean_area_sqm":{"anyOf":[{"type":"integer"},{"type":"null"}]},"percentiles_sqm":{"type":"object","properties":{"p10":{"anyOf":[{"type":"integer"},{"type":"null"}]},"p25":{"anyOf":[{"type":"integer"},{"type":"null"}]},"p75":{"anyOf":[{"type":"integer"},{"type":"null"}]},"p90":{"anyOf":[{"type":"integer"},{"type":"null"}]}},"required":["p10","p25","p75","p90"],"additionalProperties":false,"description":"Area percentiles in m²."},"range_sqm":{"type":"object","properties":{"min":{"type":"integer"},"max":{"type":"integer"}},"required":["min","max"],"additionalProperties":false},"buckets":{"type":"array","items":{"type":"object","properties":{"min_sqm":{"type":"integer","description":"Inclusive lower bound."},"max_sqm":{"type":"integer","description":"Exclusive upper bound."},"count":{"type":"integer"}},"required":["min_sqm","max_sqm","count"],"additionalProperties":false}},"above_range_count":{"type":"integer"},"window":{"type":"object","properties":{"updated_within_days":{"type":"integer","example":30},"from":{"type":"string","description":"Listings updated at or after this time are included (ISO 8601).","example":"2026-08-23T09:00:00.000Z"},"to":{"type":"string","description":"When the numbers were computed (ISO 8601). Results are cached up to an hour.","example":"2026-09-22T09:00:00.000Z"}},"required":["updated_within_days","from","to"],"additionalProperties":false,"description":"The freshness window every market number uses."}},"required":["filters","sample_size","without_area_count","median_area_sqm","mean_area_sqm","percentiles_sqm","range_sqm","buckets","above_range_count","window"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"filters":{"city":"riyadh","listing_type":"rent","listing_category":"residential","property_type":"apartment","neighborhood_ids":[12],"beds":3},"sample_size":214,"without_area_count":12,"median_area_sqm":null,"mean_area_sqm":null,"percentiles_sqm":{"p10":null,"p25":null,"p75":null,"p90":null},"range_sqm":{"min":95,"max":220},"buckets":[{"min_sqm":100,"max_sqm":150,"count":38}],"above_range_count":6,"window":{"updated_within_days":30,"from":"2026-08-23T09:00:00.000Z","to":"2026-09-22T09:00:00.000Z"}}}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/market/supply":{"get":{"operationId":"market.supply","summary":"New supply","description":"How many listings came onto the market recently: listings first seen in the last 7 days vs the 7 days before, and the last 30 days vs the 30 days before (rolling windows ending now). Counts only include listings that are still live and in the sample, so listings taken down since are missing from the earlier periods: `change_pct` leans upward and is best compared between filters or over time, not read as absolute growth.\n\nComputed over the market sample: active, deduplicated listings updated in the last 30 days (`updated_at`), after the same outlier filter kite.sa uses (per-tier price fences from the median and MAD of log price, bedroom and area sanity checks, and a floor at 30% of the neighborhood median). Prices are asking prices in SAR: yearly rent for `listing_type=rent` (monthly, weekly and daily postings are converted to a yearly amount), total price for `listing_type=sale`. Check `sample_size` before relying on a number; small samples are noisy.","tags":["Market data"],"x-scope":"market","x-units":50,"security":[{"apiKey":[]}],"parameters":[{"name":"city","in":"query","required":true,"description":"City slug from GET /cities. A town inside a covered region is accepted and resolved to its city (`dammam`, `khobar`, `dhahran`, `jubail` and `qatif` to `eastern_province`; `buraydah` and `unaizah` to `qassim`; `hofuf` to `al_ahsa`), as are Arabic city names. The response's `filters.city` and the `X-Resolved-City` header show the slug used.","example":"riyadh","schema":{"type":"string","pattern":"^[a-z_]+$"}},{"name":"listing_type","in":"query","required":true,"description":"`rent` (prices are yearly rent) or `sale` (prices are total price).","schema":{"type":"string","enum":["rent","sale"]}},{"name":"listing_category","in":"query","required":false,"description":"Defaults to `residential` when `property_type` is omitted, so dwellings and commercial stock are never mixed into one median. With a `property_type`, omit it to include both categories of that type.","schema":{"type":"string","enum":["residential","commercial"]}},{"name":"property_type","in":"query","required":false,"description":"One property type, see GET /enums.","example":"apartment","schema":{"type":"string","enum":["apartment","villa","floor","duplex","office","shop","warehouse","land","building"]}},{"name":"beds","in":"query","required":false,"description":"Exact number of bedrooms (0 = studio).","example":2,"schema":{"type":"integer","minimum":0,"maximum":20}},{"name":"neighborhood_id","in":"query","required":false,"description":"Limit to one or more neighborhoods (comma-separated ids from GET /cities/{city}/neighborhoods). Unknown ids are a 404.","example":[1287],"schema":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"integer","minimum":1,"maximum":2147483647}},"style":"form","explode":false}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Units allowed per minute.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Units left this minute.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-Request-Units":{"description":"Units this request cost.","schema":{"type":"integer"}},"X-Quota-Limit":{"description":"Units allowed this calendar month (UTC). Absent on unlimited plans.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Units left this calendar month (UTC). Absent on unlimited plans. Reads `0` once a plan with overage is past its quota and still serving.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Seconds until the monthly quota resets. Absent on unlimited plans.","schema":{"type":"integer"}},"X-Resolved-City":{"description":"The covered city slug the request's `city` was resolved to, when it differs from what was sent (`city=dammam` answers for `eastern_province`). Absent when the slug was sent as is.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"filters":{"type":"object","properties":{"city":{"type":"string","example":"riyadh"},"listing_type":{"type":"string","enum":["rent","sale"]},"listing_category":{"anyOf":[{"type":"string","enum":["residential","commercial"]},{"type":"null"}],"description":"The category applied; null when both are included."},"property_type":{"example":"apartment","type":["string","null"]},"neighborhood_ids":{"anyOf":[{"type":"array","items":{"type":"integer"}},{"type":"null"}],"example":[12]},"beds":{"anyOf":[{"type":"integer"},{"type":"null"}],"example":3}},"required":["city","listing_type","listing_category","property_type","neighborhood_ids","beds"],"additionalProperties":false,"description":"The filters the numbers were computed for, after defaults."},"sample_size":{"type":"integer","description":"All listings in the sample."},"last_7_days":{"type":"object","properties":{"new_listings":{"type":"integer","description":"Listings in the sample first seen by Kite in this period."},"previous_new_listings":{"type":"integer","description":"The same count for the period of equal length just before."},"change_pct":{"description":"Percent change from the previous period; null when it had none.","type":["number","null"]}},"required":["new_listings","previous_new_listings","change_pct"],"additionalProperties":false},"last_30_days":{"type":"object","properties":{"new_listings":{"type":"integer","description":"Listings in the sample first seen by Kite in this period."},"previous_new_listings":{"type":"integer","description":"The same count for the period of equal length just before."},"change_pct":{"description":"Percent change from the previous period; null when it had none.","type":["number","null"]}},"required":["new_listings","previous_new_listings","change_pct"],"additionalProperties":false},"window":{"type":"object","properties":{"updated_within_days":{"type":"integer","example":30},"from":{"type":"string","description":"Listings updated at or after this time are included (ISO 8601).","example":"2026-08-23T09:00:00.000Z"},"to":{"type":"string","description":"When the numbers were computed (ISO 8601). Results are cached up to an hour.","example":"2026-09-22T09:00:00.000Z"}},"required":["updated_within_days","from","to"],"additionalProperties":false,"description":"The freshness window every market number uses."}},"required":["filters","sample_size","last_7_days","last_30_days","window"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"filters":{"city":"riyadh","listing_type":"rent","listing_category":"residential","property_type":"apartment","neighborhood_ids":[12],"beds":3},"sample_size":214,"last_7_days":{"new_listings":42,"previous_new_listings":37,"change_pct":13.5},"last_30_days":{"new_listings":168,"previous_new_listings":181,"change_pct":-7.2},"window":{"updated_within_days":30,"from":"2026-08-23T09:00:00.000Z","to":"2026-09-22T09:00:00.000Z"}}}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/market/vacancy":{"get":{"operationId":"market.vacancy","summary":"Vacancy indicator","description":"How long listings in the sample have been on the market, as a proxy for vacancy (actual occupancy isn't observed). Days on market count from when Kite first saw the listing: listings that were already up before then, or before Kite covered their source, are undercounted, and an ad re-posted under a new id starts again at zero. Compare these numbers between neighborhoods, property types or over time rather than reading them as absolute vacancy.\n\nComputed over the market sample: active, deduplicated listings updated in the last 30 days (`updated_at`), after the same outlier filter kite.sa uses (per-tier price fences from the median and MAD of log price, bedroom and area sanity checks, and a floor at 30% of the neighborhood median). Prices are asking prices in SAR: yearly rent for `listing_type=rent` (monthly, weekly and daily postings are converted to a yearly amount), total price for `listing_type=sale`. Check `sample_size` before relying on a number; small samples are noisy.","tags":["Market data"],"x-scope":"market","x-units":50,"security":[{"apiKey":[]}],"parameters":[{"name":"city","in":"query","required":true,"description":"City slug from GET /cities. A town inside a covered region is accepted and resolved to its city (`dammam`, `khobar`, `dhahran`, `jubail` and `qatif` to `eastern_province`; `buraydah` and `unaizah` to `qassim`; `hofuf` to `al_ahsa`), as are Arabic city names. The response's `filters.city` and the `X-Resolved-City` header show the slug used.","example":"riyadh","schema":{"type":"string","pattern":"^[a-z_]+$"}},{"name":"listing_type","in":"query","required":true,"description":"`rent` (prices are yearly rent) or `sale` (prices are total price).","schema":{"type":"string","enum":["rent","sale"]}},{"name":"listing_category","in":"query","required":false,"description":"Defaults to `residential` when `property_type` is omitted, so dwellings and commercial stock are never mixed into one median. With a `property_type`, omit it to include both categories of that type.","schema":{"type":"string","enum":["residential","commercial"]}},{"name":"property_type","in":"query","required":false,"description":"One property type, see GET /enums.","example":"apartment","schema":{"type":"string","enum":["apartment","villa","floor","duplex","office","shop","warehouse","land","building"]}},{"name":"beds","in":"query","required":false,"description":"Exact number of bedrooms (0 = studio).","example":2,"schema":{"type":"integer","minimum":0,"maximum":20}},{"name":"neighborhood_id","in":"query","required":false,"description":"Limit to one or more neighborhoods (comma-separated ids from GET /cities/{city}/neighborhoods). Unknown ids are a 404.","example":[1287],"schema":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"integer","minimum":1,"maximum":2147483647}},"style":"form","explode":false}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Units allowed per minute.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Units left this minute.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-Request-Units":{"description":"Units this request cost.","schema":{"type":"integer"}},"X-Quota-Limit":{"description":"Units allowed this calendar month (UTC). Absent on unlimited plans.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Units left this calendar month (UTC). Absent on unlimited plans. Reads `0` once a plan with overage is past its quota and still serving.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Seconds until the monthly quota resets. Absent on unlimited plans.","schema":{"type":"integer"}},"X-Resolved-City":{"description":"The covered city slug the request's `city` was resolved to, when it differs from what was sent (`city=dammam` answers for `eastern_province`). Absent when the slug was sent as is.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"filters":{"type":"object","properties":{"city":{"type":"string","example":"riyadh"},"listing_type":{"type":"string","enum":["rent","sale"]},"listing_category":{"anyOf":[{"type":"string","enum":["residential","commercial"]},{"type":"null"}],"description":"The category applied; null when both are included."},"property_type":{"example":"apartment","type":["string","null"]},"neighborhood_ids":{"anyOf":[{"type":"array","items":{"type":"integer"}},{"type":"null"}],"example":[12]},"beds":{"anyOf":[{"type":"integer"},{"type":"null"}],"example":3}},"required":["city","listing_type","listing_category","property_type","neighborhood_ids","beds"],"additionalProperties":false,"description":"The filters the numbers were computed for, after defaults."},"sample_size":{"type":"integer","example":214},"median_days_on_market":{"anyOf":[{"type":"integer"},{"type":"null"}]},"on_market_over_30_days":{"type":"object","properties":{"count":{"type":"integer"},"pct":{"description":"Share of `sample_size`, in percent.","type":["number","null"]}},"required":["count","pct"],"additionalProperties":false},"on_market_over_60_days":{"type":"object","properties":{"count":{"type":"integer"},"pct":{"description":"Share of `sample_size`, in percent.","type":["number","null"]}},"required":["count","pct"],"additionalProperties":false},"on_market_over_90_days":{"type":"object","properties":{"count":{"type":"integer"},"pct":{"description":"Share of `sample_size`, in percent.","type":["number","null"]}},"required":["count","pct"],"additionalProperties":false},"window":{"type":"object","properties":{"updated_within_days":{"type":"integer","example":30},"from":{"type":"string","description":"Listings updated at or after this time are included (ISO 8601).","example":"2026-08-23T09:00:00.000Z"},"to":{"type":"string","description":"When the numbers were computed (ISO 8601). Results are cached up to an hour.","example":"2026-09-22T09:00:00.000Z"}},"required":["updated_within_days","from","to"],"additionalProperties":false,"description":"The freshness window every market number uses."}},"required":["filters","sample_size","median_days_on_market","on_market_over_30_days","on_market_over_60_days","on_market_over_90_days","window"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"filters":{"city":"riyadh","listing_type":"rent","listing_category":"residential","property_type":"apartment","neighborhood_ids":[12],"beds":3},"sample_size":214,"median_days_on_market":null,"on_market_over_30_days":{"count":96,"pct":45},"on_market_over_60_days":{"count":51,"pct":24},"on_market_over_90_days":{"count":23,"pct":11},"window":{"updated_within_days":30,"from":"2026-08-23T09:00:00.000Z","to":"2026-09-22T09:00:00.000Z"}}}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/market/neighborhoods":{"get":{"operationId":"market.neighborhoods","summary":"Prices by neighborhood","description":"Median and quartile price per neighborhood in a city, most expensive first. Neighborhoods with fewer than `min_sample_size` listings are left out (one unusual listing would swing their median); `suppressed_neighborhoods` says how many. Listings without a known neighborhood are not counted. Pass a `property_type` (and `beds`) for like-for-like comparisons; otherwise a neighborhood's median depends on its mix of apartments and villas.\n\nComputed over the market sample: active, deduplicated listings updated in the last 30 days (`updated_at`), after the same outlier filter kite.sa uses (per-tier price fences from the median and MAD of log price, bedroom and area sanity checks, and a floor at 30% of the neighborhood median). Prices are asking prices in SAR: yearly rent for `listing_type=rent` (monthly, weekly and daily postings are converted to a yearly amount), total price for `listing_type=sale`. Check `sample_size` before relying on a number; small samples are noisy.","tags":["Market data"],"x-scope":"market","x-units":50,"security":[{"apiKey":[]}],"parameters":[{"name":"city","in":"query","required":true,"description":"City slug from GET /cities. A town inside a covered region is accepted and resolved to its city (`dammam`, `khobar`, `dhahran`, `jubail` and `qatif` to `eastern_province`; `buraydah` and `unaizah` to `qassim`; `hofuf` to `al_ahsa`), as are Arabic city names. The response's `filters.city` and the `X-Resolved-City` header show the slug used.","example":"riyadh","schema":{"type":"string","pattern":"^[a-z_]+$"}},{"name":"listing_type","in":"query","required":true,"description":"`rent` (prices are yearly rent) or `sale` (prices are total price).","schema":{"type":"string","enum":["rent","sale"]}},{"name":"listing_category","in":"query","required":false,"description":"Defaults to `residential` when `property_type` is omitted, so dwellings and commercial stock are never mixed into one median. With a `property_type`, omit it to include both categories of that type.","schema":{"type":"string","enum":["residential","commercial"]}},{"name":"property_type","in":"query","required":false,"description":"One property type, see GET /enums.","example":"apartment","schema":{"type":"string","enum":["apartment","villa","floor","duplex","office","shop","warehouse","land","building"]}},{"name":"beds","in":"query","required":false,"description":"Exact number of bedrooms (0 = studio).","example":2,"schema":{"type":"integer","minimum":0,"maximum":20}},{"name":"min_sample_size","in":"query","required":false,"description":"Leave out neighborhoods with fewer listings than this.","schema":{"default":5,"type":"integer","minimum":3,"maximum":1000}}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Units allowed per minute.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Units left this minute.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-Request-Units":{"description":"Units this request cost.","schema":{"type":"integer"}},"X-Quota-Limit":{"description":"Units allowed this calendar month (UTC). Absent on unlimited plans.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Units left this calendar month (UTC). Absent on unlimited plans. Reads `0` once a plan with overage is past its quota and still serving.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Seconds until the monthly quota resets. Absent on unlimited plans.","schema":{"type":"integer"}},"X-Resolved-City":{"description":"The covered city slug the request's `city` was resolved to, when it differs from what was sent (`city=dammam` answers for `eastern_province`). Absent when the slug was sent as is.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"filters":{"type":"object","properties":{"city":{"type":"string","example":"riyadh"},"listing_type":{"type":"string","enum":["rent","sale"]},"listing_category":{"anyOf":[{"type":"string","enum":["residential","commercial"]},{"type":"null"}],"description":"The category applied; null when both are included."},"property_type":{"example":"apartment","type":["string","null"]},"neighborhood_ids":{"anyOf":[{"type":"array","items":{"type":"integer"}},{"type":"null"}],"example":[12]},"beds":{"anyOf":[{"type":"integer"},{"type":"null"}],"example":3}},"required":["city","listing_type","listing_category","property_type","neighborhood_ids","beds"],"additionalProperties":false,"description":"The filters the numbers were computed for, after defaults."},"price_basis":{"type":"string","enum":["yearly_rent","sale_price"],"description":"What the `*_sar` price fields mean: `yearly_rent` (SAR per year) for rentals, `sale_price` (total SAR) for sales."},"price_source":{"type":"string","enum":["asking","registered"],"description":"Where the prices come from: `asking` = advertised asking prices from listings; `registered` = registered transactions or rent contracts. Asking prices typically sit above what is finally agreed.","example":"asking"},"min_sample_size":{"type":"integer"},"neighborhoods":{"type":"array","items":{"type":"object","properties":{"neighborhood_id":{"type":"integer"},"name_ar":{"type":"string"},"name_en":{"type":"string"},"town":{"$ref":"#/components/schemas/NeighborhoodTown"},"center":{"anyOf":[{"type":"object","properties":{"lat":{"type":"number"},"lng":{"type":"number"}},"required":["lat","lng"],"additionalProperties":false},{"type":"null"}],"description":"Approximate centroid."},"sample_size":{"type":"integer","example":214},"median_price_sar":{"anyOf":[{"type":"integer"},{"type":"null"}]},"p25_price_sar":{"anyOf":[{"type":"integer"},{"type":"null"}]},"p75_price_sar":{"anyOf":[{"type":"integer"},{"type":"null"}]},"median_price_per_sqm_sar":{"anyOf":[{"type":"integer"},{"type":"null"}]}},"required":["neighborhood_id","name_ar","name_en","town","center","sample_size","median_price_sar","p25_price_sar","p75_price_sar","median_price_per_sqm_sar"],"additionalProperties":false}},"suppressed_neighborhoods":{"type":"integer"},"suppressed_sample_size":{"type":"integer","description":"Listings in the neighborhoods left out."},"window":{"type":"object","properties":{"updated_within_days":{"type":"integer","example":30},"from":{"type":"string","description":"Listings updated at or after this time are included (ISO 8601).","example":"2026-08-23T09:00:00.000Z"},"to":{"type":"string","description":"When the numbers were computed (ISO 8601). Results are cached up to an hour.","example":"2026-09-22T09:00:00.000Z"}},"required":["updated_within_days","from","to"],"additionalProperties":false,"description":"The freshness window every market number uses."}},"required":["filters","price_basis","price_source","min_sample_size","neighborhoods","suppressed_neighborhoods","suppressed_sample_size","window"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"filters":{"city":"riyadh","listing_type":"rent","listing_category":"residential","property_type":"apartment","neighborhood_ids":[12],"beds":3},"price_basis":"yearly_rent","price_source":"asking","min_sample_size":5,"neighborhoods":[{"neighborhood_id":342,"name_ar":"الملقا","name_en":"Al Malqa","town":{"name_en":"Khobar","name_ar":"الخبر"},"center":{"lat":24.8136,"lng":46.6097},"sample_size":214,"median_price_sar":null,"p25_price_sar":null,"p75_price_sar":null,"median_price_per_sqm_sar":null}],"suppressed_neighborhoods":4,"suppressed_sample_size":3,"window":{"updated_within_days":30,"from":"2026-08-23T09:00:00.000Z","to":"2026-09-22T09:00:00.000Z"}}}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/market/commercial-rents":{"get":{"operationId":"market.commercial_rents","summary":"Commercial rent per m² by neighborhood","description":"Asking rent per m² of commercial space (shops, offices, warehouses, commercial land and whole buildings) by neighborhood, with the city-wide figure for each type as a benchmark. Built for site selection: compare what a shop of a given size costs a year across neighborhoods.\n\n**Unit.** Every `*_rent_per_sqm_sar` field is yearly asking rent divided by the stated area, in SAR per m² per year. Monthly and other postings are converted to a yearly amount first. These are asking rents from active listings, not signed leases.\n\n**Sample.** Active, deduplicated commercial rentals seen in the last 30 days, after the site's outlier filter (the market sample of every /market endpoint), and then only listings whose rent per m² can be trusted:\n- the area is stated and was not rejected by Kite's area check, and the price was not flagged;\n- the ad is not a lease takeover (تقبيل), whose price mixes key money with rent;\n- listings in the same neighborhood with the same type, rent and area count once (one advertiser often posts the same unit many times);\n- rent per m² is at least a floor per type (office 150, shop 100, warehouse 30, land 10, building 100 SAR/m²/yr), which removes business centres that post the whole centre's area with one desk's price, and within median ± 3·MAD of ln(rent per m²) for the city and type (applied with 20 or more listings). The fence is computed city-wide, so it does not move with `neighborhood_id`, `area_min` or `area_max`.\n\n`city_totals[].exclusions` counts what each step removed, and `price_per_sqm_fence_sar` gives the bounds.\n\n**Small samples.** A neighborhood with fewer than `min_sample_size` listings is still listed with its `sample_size`, but its statistics are null. Street width is reported where at least `min_sample_size` listings state it; it is the width of the street the property faces, as the ad gives it, and is often missing for offices.\n\n**Like for like.** Rent per m² falls as units get larger, so a neighborhood of big showrooms looks cheaper than one of small shops. Check `median_area_sqm`, or pass `area_min`/`area_max` to compare units of the size you need. For `building` and `land` the area is the one the ad states, usually the plot.","tags":["Market data"],"x-scope":"market","x-units":50,"security":[{"apiKey":[]}],"parameters":[{"name":"city","in":"query","required":true,"description":"City slug from GET /cities. A town inside a covered region is accepted and resolved to its city (`dammam`, `khobar`, `dhahran`, `jubail` and `qatif` to `eastern_province`; `buraydah` and `unaizah` to `qassim`; `hofuf` to `al_ahsa`), as are Arabic city names. The response's `filters.city` and the `X-Resolved-City` header show the slug used.","example":"riyadh","schema":{"type":"string","pattern":"^[a-z_]+$"}},{"name":"property_type","in":"query","required":false,"description":"One or more commercial property types, comma-separated. Defaults to all of them; each is reported separately, never pooled.","example":["shop"],"schema":{"minItems":1,"maxItems":5,"type":"array","items":{"type":"string","enum":["office","shop","warehouse","land","building"]}},"style":"form","explode":false},{"name":"neighborhood_id","in":"query","required":false,"description":"Limit the neighborhood rows to these ids (comma-separated, from GET /cities/{city}/neighborhoods). City totals are unaffected. Unknown ids are a 404.","example":[77,117],"schema":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"integer","minimum":1,"maximum":2147483647}},"style":"form","explode":false},{"name":"area_min","in":"query","required":false,"description":"Only units of at least this many m².","example":80,"schema":{"type":"integer","minimum":1,"maximum":1000000}},{"name":"area_max","in":"query","required":false,"description":"Only units of at most this many m².","example":300,"schema":{"type":"integer","minimum":1,"maximum":1000000}},{"name":"min_sample_size","in":"query","required":false,"description":"Statistics are null for a neighborhood (or city total) with fewer listings than this.","schema":{"default":5,"type":"integer","minimum":3,"maximum":1000}}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Units allowed per minute.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Units left this minute.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-Request-Units":{"description":"Units this request cost.","schema":{"type":"integer"}},"X-Quota-Limit":{"description":"Units allowed this calendar month (UTC). Absent on unlimited plans.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Units left this calendar month (UTC). Absent on unlimited plans. Reads `0` once a plan with overage is past its quota and still serving.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Seconds until the monthly quota resets. Absent on unlimited plans.","schema":{"type":"integer"}},"X-Resolved-City":{"description":"The covered city slug the request's `city` was resolved to, when it differs from what was sent (`city=dammam` answers for `eastern_province`). Absent when the slug was sent as is.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"filters":{"type":"object","properties":{"city":{"type":"string","example":"riyadh"},"listing_type":{"type":"string","const":"rent"},"listing_category":{"type":"string","const":"commercial"},"property_types":{"type":"array","items":{"type":"string","enum":["office","shop","warehouse","land","building"]},"example":["shop"]},"neighborhood_ids":{"anyOf":[{"type":"array","items":{"type":"integer"}},{"type":"null"}],"example":[77]},"area_min":{"anyOf":[{"type":"integer"},{"type":"null"}]},"area_max":{"anyOf":[{"type":"integer"},{"type":"null"}]}},"required":["city","listing_type","listing_category","property_types","neighborhood_ids","area_min","area_max"],"additionalProperties":false,"description":"The filters the numbers were computed for, after defaults."},"price_basis":{"type":"string","const":"yearly_rent","description":"Rents are yearly; per-m² figures are SAR per m² per year."},"price_source":{"type":"string","enum":["asking","registered"],"description":"Where the prices come from: `asking` = advertised asking prices from listings; `registered` = registered transactions or rent contracts. Asking prices typically sit above what is finally agreed.","example":"asking"},"min_sample_size":{"type":"integer","example":5},"city_totals":{"type":"array","items":{"type":"object","properties":{"property_type":{"type":"string","enum":["office","shop","warehouse","land","building"]},"sample_size":{"type":"integer","description":"Listings in the sample after every exclusion.","example":17},"median_rent_per_sqm_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Median asking rent per m², SAR per year. Null below `min_sample_size`.","example":721},"p25_rent_per_sqm_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"25th percentile of asking rent per m², SAR per year.","example":395},"p75_rent_per_sqm_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"75th percentile of asking rent per m², SAR per year.","example":1383},"median_area_sqm":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Median stated area in m².","example":640},"median_rent_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Median yearly asking rent in SAR (whole unit).","example":300000},"street_width":{"type":"object","properties":{"sample_size":{"type":"integer","description":"Listings in the sample that state a street width.","example":12},"median_m":{"description":"Median width in metres of the street the property faces; null below `min_sample_size`.","example":40,"type":["number","null"]}},"required":["sample_size","median_m"],"additionalProperties":false,"description":"Frontage street width, where ads state it."},"exclusions":{"type":"object","properties":{"listings_in_scope":{"type":"integer","description":"Commercial rentals of this type in the market sample, before the steps below and before `area_min`/`area_max`.","example":1219},"lease_takeover":{"type":"integer","example":26},"implausible_area_or_price":{"type":"integer","example":6},"repeated_listing":{"type":"integer","example":237},"outside_price_per_sqm_fence":{"type":"integer","example":247}},"required":["listings_in_scope","lease_takeover","implausible_area_or_price","repeated_listing","outside_price_per_sqm_fence"],"additionalProperties":false,"description":"Listings each quality step removed, city-wide."},"price_per_sqm_fence_sar":{"type":"object","properties":{"lower":{"type":"integer","example":116},"upper":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Null when too few listings to fit the fence (floor only).","example":6151}},"required":["lower","upper"],"additionalProperties":false,"description":"Rent per m² bounds a listing had to fall within."}},"required":["property_type","sample_size","median_rent_per_sqm_sar","p25_rent_per_sqm_sar","p75_rent_per_sqm_sar","median_area_sqm","median_rent_sar","street_width","exclusions","price_per_sqm_fence_sar"],"additionalProperties":false},"description":"One row per requested property type, for the whole city."},"neighborhoods":{"type":"array","items":{"type":"object","properties":{"neighborhood_id":{"type":"integer"},"name_ar":{"type":"string"},"name_en":{"type":"string"},"town":{"$ref":"#/components/schemas/NeighborhoodTown"},"center":{"anyOf":[{"type":"object","properties":{"lat":{"type":"number"},"lng":{"type":"number"}},"required":["lat","lng"],"additionalProperties":false},{"type":"null"}],"description":"Approximate centroid."},"property_type":{"type":"string","enum":["office","shop","warehouse","land","building"]},"sample_size":{"type":"integer","description":"Listings in the sample after every exclusion.","example":17},"median_rent_per_sqm_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Median asking rent per m², SAR per year. Null below `min_sample_size`.","example":721},"p25_rent_per_sqm_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"25th percentile of asking rent per m², SAR per year.","example":395},"p75_rent_per_sqm_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"75th percentile of asking rent per m², SAR per year.","example":1383},"median_area_sqm":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Median stated area in m².","example":640},"median_rent_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Median yearly asking rent in SAR (whole unit).","example":300000},"street_width":{"type":"object","properties":{"sample_size":{"type":"integer","description":"Listings in the sample that state a street width.","example":12},"median_m":{"description":"Median width in metres of the street the property faces; null below `min_sample_size`.","example":40,"type":["number","null"]}},"required":["sample_size","median_m"],"additionalProperties":false,"description":"Frontage street width, where ads state it."}},"required":["neighborhood_id","name_ar","name_en","town","center","property_type","sample_size","median_rent_per_sqm_sar","p25_rent_per_sqm_sar","p75_rent_per_sqm_sar","median_area_sqm","median_rent_sar","street_width"],"additionalProperties":false},"description":"One row per neighborhood and property type with at least one listing in the sample: grouped by property type in the order requested, then highest median rent per m² first; rows below `min_sample_size` come last within their type."},"window":{"type":"object","properties":{"updated_within_days":{"type":"integer","example":30},"from":{"type":"string"},"to":{"type":"string","description":"When the numbers were computed (ISO 8601). Results are cached up to an hour."}},"required":["updated_within_days","from","to"],"additionalProperties":false}},"required":["filters","price_basis","price_source","min_sample_size","city_totals","neighborhoods","window"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"filters":{"city":"riyadh","listing_type":"rent","listing_category":"commercial","property_types":["shop"],"neighborhood_ids":[77],"area_min":null,"area_max":null},"price_basis":"yearly_rent","price_source":"asking","min_sample_size":5,"city_totals":[{"property_type":"office","sample_size":17,"median_rent_per_sqm_sar":721,"p25_rent_per_sqm_sar":395,"p75_rent_per_sqm_sar":1383,"median_area_sqm":640,"median_rent_sar":300000,"street_width":{"sample_size":12,"median_m":40},"exclusions":{"listings_in_scope":1219,"lease_takeover":26,"implausible_area_or_price":6,"repeated_listing":237,"outside_price_per_sqm_fence":247},"price_per_sqm_fence_sar":{"lower":116,"upper":6151}}],"neighborhoods":[{"neighborhood_id":342,"name_ar":"الملقا","name_en":"Al Malqa","town":{"name_en":"Khobar","name_ar":"الخبر"},"center":{"lat":24.8136,"lng":46.6097},"property_type":"office","sample_size":17,"median_rent_per_sqm_sar":721,"p25_rent_per_sqm_sar":395,"p75_rent_per_sqm_sar":1383,"median_area_sqm":640,"median_rent_sar":300000,"street_width":{"sample_size":12,"median_m":40}}],"window":{"updated_within_days":30,"from":"2026-06-01","to":"2026-09-21"}}}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/market/land-resale":{"get":{"operationId":"market.land_resale","summary":"Plots for sale against their last registered sale","description":"How the plots on the market compare with what they last sold for. Kite places sale listings on official parcels (see `plot` on a listing) and pairs each with the parcel's most recent registered sale of the same kind, registered with the Ministry of Justice (through a notary) or the Real Estate Registry. Per city, or per neighborhood (`group_by=neighborhood`), it reports how many listings were bought within the last 12 months, and the asking price over the last sale price.\n\n**Kinds.** `land` (the default) pairs land listings with land sales. `built` pairs villas and buildings with sales of a plot with its building: the Real Estate Registry files villas and residential buildings alike, so the two are one kind here. Flats, floors and duplexes aren't covered: their plot holds other units.\n\n**The ratio** is computed only over pairs whose areas agree (the listing's stated area within 5% of the deed's), because villa ads often state the built-up area rather than the plot's. It compares an asking price today with a registered price at some earlier date, so it mixes price growth with the seller's margin; read it with `median_months_since_last_sale`. Built pairs have a long upper tail (a plot sold vacant, then built on), so use the quartiles, not the mean.\n\n**Sample.** Active, deduplicated sale listings after the same outlier filter as GET /market/summary, in neighborhoods whose parcels are mapped: Riyadh is covered best, and cities without parcel maps return empty cells. Each figure is null when the count it is computed over is below `min_sample_size`. Recomputed after every scrape.","tags":["Market data"],"x-scope":"market","x-units":50,"security":[{"apiKey":[]}],"parameters":[{"name":"city","in":"query","required":true,"description":"City slug from GET /cities. A town inside a covered region is accepted and resolved to its city (`dammam`, `khobar`, `dhahran`, `jubail` and `qatif` to `eastern_province`; `buraydah` and `unaizah` to `qassim`; `hofuf` to `al_ahsa`), as are Arabic city names. The response's `filters.city` and the `X-Resolved-City` header show the slug used.","example":"riyadh","schema":{"type":"string","pattern":"^[a-z_]+$"}},{"name":"neighborhood_id","in":"query","required":false,"description":"Up to 50 neighborhood ids from GET /cities/{city}/neighborhoods, comma-separated. Unknown ids are a 404.","example":[25],"schema":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"integer","minimum":1,"maximum":2147483647}},"style":"form","explode":false},{"name":"group_by","in":"query","required":false,"description":"`city`: one cell for the city (or for the neighborhoods in `neighborhood_id` together). `neighborhood`: one cell per neighborhood, for the ids in `neighborhood_id`, or for every neighborhood with listings when it is omitted. Defaults to `neighborhood` when `neighborhood_id` is given, `city` otherwise.","schema":{"type":"string","enum":["city","neighborhood"]}},{"name":"kind","in":"query","required":false,"description":"`land` (the default): land listings and land sales. `built`: villas and buildings, and sales of a plot with its building.","schema":{"default":"land","type":"string","enum":["land","built"]}},{"name":"min_sample_size","in":"query","required":false,"description":"Figures computed over fewer listings than this are null. At least 5.","schema":{"default":10,"type":"integer","minimum":5,"maximum":1000}}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Units allowed per minute.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Units left this minute.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-Request-Units":{"description":"Units this request cost.","schema":{"type":"integer"}},"X-Quota-Limit":{"description":"Units allowed this calendar month (UTC). Absent on unlimited plans.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Units left this calendar month (UTC). Absent on unlimited plans. Reads `0` once a plan with overage is past its quota and still serving.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Seconds until the monthly quota resets. Absent on unlimited plans.","schema":{"type":"integer"}},"X-Resolved-City":{"description":"The covered city slug the request's `city` was resolved to, when it differs from what was sent (`city=dammam` answers for `eastern_province`). Absent when the slug was sent as is.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"filters":{"type":"object","properties":{"city":{"type":"string","example":"riyadh"},"neighborhood_ids":{"anyOf":[{"type":"array","items":{"type":"integer"}},{"type":"null"}]},"group_by":{"type":"string","enum":["city","neighborhood"]},"kind":{"type":"string","enum":["land","built"]},"property_types":{"type":"array","items":{"type":"string"},"example":["land"]}},"required":["city","neighborhood_ids","group_by","kind","property_types"],"additionalProperties":false},"min_sample_size":{"type":"integer","example":10},"cells":{"type":"array","items":{"type":"object","properties":{"neighborhood":{"anyOf":[{"type":"object","properties":{"id":{"type":"integer","example":25},"name_ar":{"type":"string","example":"النرجس"},"name_en":{"type":"string","example":"Al Narjis"},"town":{"$ref":"#/components/schemas/NeighborhoodTown"}},"required":["id","name_ar","name_en","town"],"additionalProperties":false},{"type":"null"}],"description":"Null for the city-wide cell."},"listings_on_parcel":{"type":"integer","description":"Active sale listings of this kind that Kite placed on an official parcel. The base of every other figure.","example":412},"with_last_sale":{"type":"integer","description":"Of those, listings whose parcel has a registered sale of the same kind on record.","example":63},"sold_within_12_months":{"type":"integer","description":"Listings whose parcel's last registered sale is at most 12 calendar months old: plots back on the market within a year of being bought.","example":21},"sold_within_12_months_share":{"description":"`sold_within_12_months` ÷ `listings_on_parcel`, 0 to 1. Null when `listings_on_parcel` is below `min_sample_size`.","example":0.051,"type":["number","null"]},"sample_size":{"type":"integer","description":"Listings with a last sale whose stated area is within 5% of the deed's area: the pairs the ask-to-last-sale figures are computed over.","example":58},"median_ask_to_last_sale":{"description":"Median of the asking price ÷ the last registered sale price, over `sample_size` pairs. 1.10 means listings ask 10% more than the plot last sold for, over however long ago that was (see `median_months_since_last_sale`). Null when `sample_size` is below `min_sample_size`.","example":1.112,"type":["number","null"]},"p25_ask_to_last_sale":{"description":"25th percentile of the same ratio.","type":["number","null"]},"p75_ask_to_last_sale":{"description":"75th percentile of the same ratio.","type":["number","null"]},"median_months_since_last_sale":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Median calendar months since the last registered sale, over `with_last_sale`. Null when `with_last_sale` is below `min_sample_size`.","example":14}},"required":["neighborhood","listings_on_parcel","with_last_sale","sold_within_12_months","sold_within_12_months_share","sample_size","median_ask_to_last_sale","p25_ask_to_last_sale","p75_ask_to_last_sale","median_months_since_last_sale"],"additionalProperties":false}},"attribution":{"type":"object","properties":{"notice":{"type":"string","description":"Credit the registries this way wherever you show these figures."},"sources":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Real Estate Registry"},"name_ar":{"type":"string","example":"السجل العقاري"},"url":{"type":"string","example":"https://rer.sa"}},"required":["name","name_ar","url"],"additionalProperties":false}}},"required":["notice","sources"],"additionalProperties":false,"description":"Where the registered sale prices come from."}},"required":["filters","min_sample_size","cells","attribution"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"filters":{"city":"riyadh","neighborhood_ids":[342],"group_by":"city","kind":"land","property_types":["land"]},"min_sample_size":10,"cells":[{"neighborhood":{"id":25,"name_ar":"النرجس","name_en":"Al Narjis","town":{"name_en":"Khobar","name_ar":"الخبر"}},"listings_on_parcel":412,"with_last_sale":63,"sold_within_12_months":21,"sold_within_12_months_share":0.051,"sample_size":58,"median_ask_to_last_sale":1.112,"p25_ask_to_last_sale":0,"p75_ask_to_last_sale":0,"median_months_since_last_sale":14}],"attribution":{"notice":"Contains information from \"الصفقات العقارية\" (Real estate transactions, Ministry of Justice, open.data.gov.sa; links in `datasets`), which is made available under the ODC Attribution License, as adapted by the Open Data License of the Kingdom of Saudi Arabia.","sources":[{"name":"Real Estate Registry","name_ar":"السجل العقاري","url":"https://rer.sa"}]}}}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/market/ask-to-deal":{"get":{"operationId":"market.ask_to_deal","summary":"Registered sale price against the asking price","description":"What plots advertised for sale went on to register at, as a share of what their ads were asking: a negotiation margin to set bids by. Kite places sale listings on official parcels (see `plot` on a listing) and finds the plots that registered a sale of the same kind while the ad was up, with the Ministry of Justice (through a notary) or the Real Estate Registry. Per city, or per neighborhood (`group_by=neighborhood`), it gives the registered price ÷ the asking price on the day of the sale, and the days from the first ad to the sale, overall and per registry.\n\n**Which sales.** A sale registered from a week before Kite first saw the plot's ad to 90 days after the ad was taken down, for ads on the market or taken down since April 2026 (`plot.registered_sale_while_listed` on a listing). One sale counts once however many ads offered the plot. Plots whose plan and parcel numbers more than 5 separate ads share are left out: that is usually a compound's master deed, not one plot.\n\n**Kinds.** `land` (the default) pairs land listings with land sales. `built` pairs villas and buildings with sales of a plot with its building: the Real Estate Registry files villas and residential buildings alike, so the two are one kind here. Flats, floors and duplexes aren't covered: their plot holds other units.\n\n**The ratio** compares a registered price with an asking price, two different things: the ask is what the ad said on the day the sale was registered, from Kite's price history of the ad. It is computed only over sales with an ad whose area agrees with the deed's (within 5%), because villa ads often state the built-up area rather than the plot's. Each figure is null when the count it is computed over is below `min_sample_size`. Recomputed after every scrape.","tags":["Market data"],"x-scope":"market","x-units":50,"security":[{"apiKey":[]}],"parameters":[{"name":"city","in":"query","required":true,"description":"City slug from GET /cities. A town inside a covered region is accepted and resolved to its city (`dammam`, `khobar`, `dhahran`, `jubail` and `qatif` to `eastern_province`; `buraydah` and `unaizah` to `qassim`; `hofuf` to `al_ahsa`), as are Arabic city names. The response's `filters.city` and the `X-Resolved-City` header show the slug used.","example":"riyadh","schema":{"type":"string","pattern":"^[a-z_]+$"}},{"name":"neighborhood_id","in":"query","required":false,"description":"Up to 50 neighborhood ids from GET /cities/{city}/neighborhoods, comma-separated. Unknown ids are a 404.","example":[25],"schema":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"integer","minimum":1,"maximum":2147483647}},"style":"form","explode":false},{"name":"group_by","in":"query","required":false,"description":"`city`: one cell for the city (or for the neighborhoods in `neighborhood_id` together). `neighborhood`: one cell per neighborhood, for the ids in `neighborhood_id`, or for every neighborhood with a sale when it is omitted. Defaults to `neighborhood` when `neighborhood_id` is given, `city` otherwise.","schema":{"type":"string","enum":["city","neighborhood"]}},{"name":"kind","in":"query","required":false,"description":"`land` (the default): land listings and land sales. `built`: villas and buildings, and sales of a plot with its building.","schema":{"default":"land","type":"string","enum":["land","built"]}},{"name":"min_sample_size","in":"query","required":false,"description":"Figures computed over fewer sales than this are null. At least 5.","schema":{"default":10,"type":"integer","minimum":5,"maximum":1000}}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Units allowed per minute.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Units left this minute.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-Request-Units":{"description":"Units this request cost.","schema":{"type":"integer"}},"X-Quota-Limit":{"description":"Units allowed this calendar month (UTC). Absent on unlimited plans.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Units left this calendar month (UTC). Absent on unlimited plans. Reads `0` once a plan with overage is past its quota and still serving.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Seconds until the monthly quota resets. Absent on unlimited plans.","schema":{"type":"integer"}},"X-Resolved-City":{"description":"The covered city slug the request's `city` was resolved to, when it differs from what was sent (`city=dammam` answers for `eastern_province`). Absent when the slug was sent as is.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"filters":{"type":"object","properties":{"city":{"type":"string","example":"riyadh"},"neighborhood_ids":{"anyOf":[{"type":"array","items":{"type":"integer"}},{"type":"null"}]},"group_by":{"type":"string","enum":["city","neighborhood"]},"kind":{"type":"string","enum":["land","built"]},"property_types":{"type":"array","items":{"type":"string"},"example":["land"]}},"required":["city","neighborhood_ids","group_by","kind","property_types"],"additionalProperties":false},"period":{"type":"object","properties":{"first_month":{"example":"2026-04","type":["string","null"]},"last_month":{"example":"2026-11","type":["string","null"]}},"required":["first_month","last_month"],"additionalProperties":false,"description":"Months of the earliest and latest sale counted, `YYYY-MM`. Null when there is none."},"min_sample_size":{"type":"integer","example":10},"cells":{"type":"array","items":{"type":"object","properties":{"neighborhood":{"anyOf":[{"type":"object","properties":{"id":{"type":"integer","example":25},"name_ar":{"type":"string","example":"النرجس"},"name_en":{"type":"string","example":"Al Narjis"},"town":{"$ref":"#/components/schemas/NeighborhoodTown"}},"required":["id","name_ar","name_en","town"],"additionalProperties":false},{"type":"null"}],"description":"Null for the city-wide cell."},"deals":{"type":"integer","description":"Registered sales of a plot while it was advertised for sale (each sale counted once, however many ads offered it). The base of every other figure.","example":1806},"listings":{"type":"integer","description":"Ads paired with those sales, an ad listed on several sites counted once. Several brokers often advertise one plot.","example":2413},"listings_still_active":{"type":"integer","description":"Of those ads, the ones still on the market today, after their plot sold.","example":861},"sample_size":{"type":"integer","description":"Sales with at least one ad whose stated area is within 5% of the deed's area: the like-for-like pairs the ratios are computed over. With several such ads, a sale's ratio is their median.","example":1793},"median_deal_to_ask":{"description":"Median of the registered sale price ÷ the ad's asking price on the day the sale was registered, over `sample_size` sales. 0.91 means plots registered 9% below what their ads were asking. Null when `sample_size` is below `min_sample_size`.","example":0.909,"type":["number","null"]},"p25_deal_to_ask":{"description":"25th percentile of the same ratio.","type":["number","null"]},"p75_deal_to_ask":{"description":"75th percentile of the same ratio.","type":["number","null"]},"days_sample_size":{"type":"integer","description":"Sales whose earliest ad has a known posting date. Ads Kite first saw while importing a source's back catalogue have none.","example":1102},"median_days_to_sell":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Median days from when Kite first saw the plot's earliest ad to the sale. Null when `days_sample_size` is below `min_sample_size`.","example":32},"by_registry":{"type":"array","items":{"type":"object","properties":{"registry":{"type":"string","enum":["MOJ","Real Estate Registry"],"description":"`MOJ`: deeds registered through a notary of the Ministry of Justice. `Real Estate Registry`: deeds registered with the Real Estate Registry.","example":"Real Estate Registry"},"deals":{"type":"integer","description":"Sales registered there.","example":1210},"sample_size":{"type":"integer","description":"Of those, sales with at least one ad whose area agrees with the deed's.","example":1188},"median_deal_to_ask":{"description":"Median of the registered sale price ÷ the ad's asking price on the day the sale was registered, over `sample_size` sales. 0.91 means plots registered 9% below what their ads were asking. Null when `sample_size` is below `min_sample_size`.","example":0.909,"type":["number","null"]},"median_days_to_sell":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Median days from when Kite first saw the plot's earliest ad to the sale. Null below `min_sample_size` sales with a known posting date.","example":32}},"required":["registry","deals","sample_size","median_deal_to_ask","median_days_to_sell"],"additionalProperties":false},"description":"The same figures for each registry that has sales in the cell. Notary sales (`MOJ`) and Real Estate Registry sales come from different parts of the market and can differ."}},"required":["neighborhood","deals","listings","listings_still_active","sample_size","median_deal_to_ask","p25_deal_to_ask","p75_deal_to_ask","days_sample_size","median_days_to_sell","by_registry"],"additionalProperties":false}},"attribution":{"type":"object","properties":{"notice":{"type":"string","description":"Credit the registries this way wherever you show these figures."},"sources":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Real Estate Registry"},"name_ar":{"type":"string","example":"السجل العقاري"},"url":{"type":"string","example":"https://rer.sa"}},"required":["name","name_ar","url"],"additionalProperties":false}}},"required":["notice","sources"],"additionalProperties":false,"description":"Where the registered sale prices come from."}},"required":["filters","period","min_sample_size","cells","attribution"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"filters":{"city":"riyadh","neighborhood_ids":[342],"group_by":"city","kind":"land","property_types":["land"]},"period":{"first_month":"2026-04","last_month":"2026-11"},"min_sample_size":10,"cells":[{"neighborhood":{"id":25,"name_ar":"النرجس","name_en":"Al Narjis","town":{"name_en":"Khobar","name_ar":"الخبر"}},"deals":1806,"listings":2413,"listings_still_active":861,"sample_size":1793,"median_deal_to_ask":0.909,"p25_deal_to_ask":0,"p75_deal_to_ask":0,"days_sample_size":1102,"median_days_to_sell":32,"by_registry":[{"registry":"Real Estate Registry","deals":1210,"sample_size":1188,"median_deal_to_ask":0.909,"median_days_to_sell":32}]}],"attribution":{"notice":"Contains information from \"الصفقات العقارية\" (Real estate transactions, Ministry of Justice, open.data.gov.sa; links in `datasets`), which is made available under the ODC Attribution License, as adapted by the Open Data License of the Kingdom of Saudi Arabia.","sources":[{"name":"Real Estate Registry","name_ar":"السجل العقاري","url":"https://rer.sa"}]}}}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/market/area-context":{"get":{"operationId":"market.area_context","summary":"Places, population and landmarks around a point or in a neighborhood","description":"What is around a location: mapped places by category, the resident population and how it changed over five years, and the nearest landmarks. Pass a point (`lat`, `lng`, optional `radius_m`) or a neighborhood (`city`, `neighborhood_id`).\n\n**The area.** A point is read as a circle of `radius_m` (default 1000, at most 3000). A neighborhood is read as the official district polygon containing its centre, or a 1000 m circle where no polygon is loaded. `area` says which was used.\n\n**How figures are counted.** Places and population come on hexagon grids (H3 resolution 9, about 0.1 km², for places; resolution 8, about 0.7 km², for population). A hexagon counts when its centre is inside the area, so figures for small areas are approximate.\n\n**Places** are mapped features (schools, mosques, clinics and hospitals, shops, restaurants and cafés, offices) from OpenStreetMap and Overture; each category takes the larger of the two counts. Mapping is uneven across neighbourhoods. **Population** is WorldPop's modelled estimate, not a census count. **Landmarks** (malls, hospitals, parks, universities, metro stations, airports, museums, attractions) are covered in Riyadh, Jeddah, Makkah, Madinah and the Eastern Province; elsewhere the list is empty.\n\nCoverage is Kite's 14 established cities; outside them `places` and `population` are null. Credit the sources as `attribution.notice` says.","tags":["Market data"],"x-scope":"market","x-units":10,"security":[{"apiKey":[]}],"parameters":[{"name":"lat","in":"query","required":false,"description":"Latitude (WGS84).","example":24.8251,"schema":{"type":"number","minimum":15,"maximum":33}},{"name":"lng","in":"query","required":false,"description":"Longitude (WGS84).","example":46.6627,"schema":{"type":"number","minimum":34,"maximum":56}},{"name":"radius_m","in":"query","required":false,"description":"With `lat`/`lng`: the circle's radius in metres. Default 1000.","schema":{"type":"integer","minimum":100,"maximum":3000}},{"name":"city","in":"query","required":false,"description":"With `neighborhood_id`.","example":"riyadh","schema":{"type":"string","pattern":"^[a-z_]+$"}},{"name":"neighborhood_id","in":"query","required":false,"description":"A neighborhood id from GET /cities/{city}/neighborhoods. Needs `city`.","example":25,"schema":{"type":"integer","minimum":1,"maximum":2147483647}}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Units allowed per minute.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Units left this minute.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-Request-Units":{"description":"Units this request cost.","schema":{"type":"integer"}},"X-Quota-Limit":{"description":"Units allowed this calendar month (UTC). Absent on unlimited plans.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Units left this calendar month (UTC). Absent on unlimited plans. Reads `0` once a plan with overage is past its quota and still serving.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Seconds until the monthly quota resets. Absent on unlimited plans.","schema":{"type":"integer"}},"X-Resolved-City":{"description":"The covered city slug the request's `city` was resolved to, when it differs from what was sent (`city=dammam` answers for `eastern_province`). Absent when the slug was sent as is.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"area":{"type":"object","properties":{"method":{"type":"string","enum":["district","radius"],"description":"`district`: the official district polygon containing the neighbourhood's centre. `radius`: a circle of `radius_m` around `center` (a point query, or a neighbourhood without a district polygon)."},"center":{"type":"object","properties":{"lat":{"type":"number","example":24.8251},"lng":{"type":"number","example":46.6627}},"required":["lat","lng"],"additionalProperties":false},"radius_m":{"anyOf":[{"type":"integer"},{"type":"null"}],"example":1000},"district_name":{"description":"The official district's name (Arabic), for `method=district`.","example":"النرجس","type":["string","null"]},"area_sqkm":{"type":"number","example":3.14},"neighborhood":{"anyOf":[{"type":"object","properties":{"id":{"type":"integer","example":25},"name_ar":{"type":"string","example":"النرجس"},"name_en":{"type":"string","example":"Al Narjis"},"town":{"$ref":"#/components/schemas/NeighborhoodTown"}},"required":["id","name_ar","name_en","town"],"additionalProperties":false},{"type":"null"}]}},"required":["method","center","radius_m","district_name","area_sqkm","neighborhood"],"additionalProperties":false},"places":{"anyOf":[{"type":"object","properties":{"sources":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","enum":["openstreetmap","overture"]},"as_of":{"type":"string","description":"The snapshot date.","example":"2026-09-26"}},"required":["name","as_of"],"additionalProperties":false},"description":"The place layers read, each at its latest snapshot."},"counts":{"type":"object","properties":{"education":{"type":"integer","example":12},"worship":{"type":"integer","example":12},"health":{"type":"integer","example":12},"retail":{"type":"integer","example":12},"food":{"type":"integer","example":12},"office":{"type":"integer","example":12},"all":{"type":"integer","example":12}},"required":["education","worship","health","retail","food","office","all"],"additionalProperties":false,"description":"Mapped places in the area, by category: for each category, the larger of the OpenStreetMap and Overture counts (each misses places the other has; Overture has more shops, food and offices, OpenStreetMap more mosques). `all` counts every mapped place, including ones in no listed category. A low count can mean few places or few mapped."},"per_sqkm":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"number"},"description":"The same counts per square kilometre, to compare areas of different sizes."}},"required":["sources","counts","per_sqkm"],"additionalProperties":false},{"type":"null"}]},"population":{"anyOf":[{"type":"object","properties":{"source":{"type":"string","const":"worldpop"},"kind":{"type":"string","const":"modelled_estimate","description":"WorldPop's gridded estimate of residents, modelled from census totals and building footprints. Not a count."},"year":{"type":"integer","example":2026},"residents":{"type":"integer","example":41200},"per_sqkm":{"type":"integer","example":13100},"change":{"anyOf":[{"type":"object","properties":{"from_year":{"type":"integer","example":2021},"residents_then":{"type":"integer","example":33800},"change_pct":{"type":"number","example":21.9}},"required":["from_year","residents_then","change_pct"],"additionalProperties":false},{"type":"null"}]}},"required":["source","kind","year","residents","per_sqkm","change"],"additionalProperties":false},{"type":"null"}]},"landmarks":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"Riyadh Park"},"name_ar":{"example":"الرياض بارك","type":["string","null"]},"category":{"type":"string","enum":["mall","hospital","park","university","metro","airport","museum","attraction"]},"distance_m":{"type":"integer","description":"Straight-line distance from `center`.","example":2400}},"required":["name","name_ar","category","distance_m"],"additionalProperties":false}},"attribution":{"type":"object","properties":{"notice":{"type":"string","description":"Credit the sources this way wherever you show these figures."},"sources":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"WorldPop"},"licence":{"type":"string","example":"CC BY 4.0"},"url":{"type":"string","example":"https://www.worldpop.org"}},"required":["name","licence","url"],"additionalProperties":false}}},"required":["notice","sources"],"additionalProperties":false}},"required":["area","places","population","landmarks","attribution"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"area":{"method":"district","center":{"lat":24.8251,"lng":46.6627},"radius_m":1000,"district_name":"النرجس","area_sqkm":3.14,"neighborhood":{"id":25,"name_ar":"النرجس","name_en":"Al Narjis","town":{"name_en":"Khobar","name_ar":"الخبر"}}},"places":{"sources":[{"name":"openstreetmap","as_of":"2026-09-26"}],"counts":{"education":12,"worship":12,"health":12,"retail":12,"food":12,"office":12,"all":12},"per_sqkm":{}},"population":{"source":"worldpop","kind":"modelled_estimate","year":2026,"residents":41200,"per_sqkm":13100,"change":{"from_year":2021,"residents_then":33800,"change_pct":21.9}},"landmarks":[{"name":"Riyadh Park","name_ar":"الرياض بارك","category":"mall","distance_m":2400}],"attribution":{"notice":"Contains information from \"الصفقات العقارية\" (Real estate transactions, Ministry of Justice, open.data.gov.sa; links in `datasets`), which is made available under the ODC Attribution License, as adapted by the Open Data License of the Kingdom of Saudi Arabia.","sources":[{"name":"WorldPop","licence":"CC BY 4.0","url":"https://www.worldpop.org"}]}}}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/market/registered-rents":{"get":{"operationId":"official.registered_rents","summary":"Registered rents (REGA)","description":"**Free on every plan (0 units).** This is Saudi open data, served at no charge under the Saudi Open Data License v2.0 with attribution: show `attribution.notice` wherever you display or pass on the figures.\n\nRegistered rents from REGA's quarterly rent index (\"مؤشر الايجار\", published on open.data.gov.sa): for each neighborhood and property type, the **mean** yearly rent of the residential leases registered on Ejar that quarter, the mean yearly rent per m², and the number of contracts behind them.\n\n- **These are means, not medians.** REGA publishes the mean; a few large leases pull it up, so it usually sits above a median. Compare them with other means, and `price_source: \"registered\"` figures with other registered figures: asking prices from /market/summary are a different quantity.\n- **Money is yearly:** `mean_rent_sar` is SAR per year and `mean_rent_per_sqm_sar` SAR per m² per year.\n- **Cells with fewer than 5 contracts are withheld** (`min_sample_size`, which you can raise but not lower). 41% of REGA's cells in Kite's cities hold 1–4 contracts, but only 0.8% of contracts; at that size the same cell's mean moves 20–29% from one quarter to the next, which is noise, not rent. `coverage` says how many cells and contracts were withheld.\n- **`neighborhood_id`** is Kite's neighborhood where REGA's name has been matched to one (daily). Unmatched cells are still returned with `neighborhood_id: null` and REGA's own names; filtering by `neighborhood_id` returns matched cells only. `town_ar` is REGA's city: for `eastern_province` and `qassim` a Kite city spans many towns whose neighborhood names repeat, so read the two together.\n- **`city_totals`** is the mean over every contract REGA counted in the city that quarter, withheld cells included (each cell's mean weighted by its contracts). It moves with where leases were signed, so a change from one quarter to the next is partly mix; for a rent trend use the `rent_contracted` series of GET /market/property-index. Per m² is not totalled, because REGA doesn't say how its per-m² mean is weighted.\n- REGA publishes a quarter some weeks after it ends; `available_periods` lists what it has for the city.","tags":["Official data"],"x-scope":"reference","x-units":0,"x-units-note":"0: Saudi open data is served free on every plan, including Sandbox","security":[{"apiKey":[]}],"parameters":[{"name":"city","in":"query","required":true,"description":"City slug from GET /cities. A town inside a covered region is accepted and resolved to its city (`dammam`, `khobar`, `dhahran`, `jubail` and `qatif` to `eastern_province`; `buraydah` and `unaizah` to `qassim`; `hofuf` to `al_ahsa`), as are Arabic city names. The response's `filters.city` and the `X-Resolved-City` header show the slug used.","example":"riyadh","schema":{"type":"string","pattern":"^[a-z_]+$"}},{"name":"neighborhood_id","in":"query","required":false,"description":"Limit to one or more neighborhoods (comma-separated ids from GET /cities/{city}/neighborhoods). Unknown ids are a 404; a known neighborhood with no matched REGA cell returns no cells.","example":[1287],"schema":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"integer","minimum":1,"maximum":2147483647}},"style":"form","explode":false},{"name":"property_type","in":"query","required":false,"description":"REGA's residential property types (comma-separated): `apartment` (شقة), `studio` (استديو), `floor` (دور), `villa` (فيلا), `duplex` (دوبلاكس). Default all. Studios are their own type in REGA's index and are not included in `apartment`.","example":["apartment"],"schema":{"minItems":1,"maxItems":5,"type":"array","items":{"type":"string","enum":["apartment","studio","floor","villa","duplex"]}},"style":"form","explode":false},{"name":"period","in":"query","required":false,"description":"Quarter as `YYYY-Qn`. Default: the latest REGA has published for the city.","example":"2026-Q1","schema":{"type":"string","pattern":"^\\d{4}-Q[1-4]$"}},{"name":"min_sample_size","in":"query","required":false,"description":"Withhold cells with fewer contracts than this. At least 5.","schema":{"default":5,"type":"integer","minimum":5,"maximum":1000}}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Units allowed per minute.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Units left this minute.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-Request-Units":{"description":"Units this request cost.","schema":{"type":"integer"}},"X-Quota-Limit":{"description":"Units allowed this calendar month (UTC). Absent on unlimited plans.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Units left this calendar month (UTC). Absent on unlimited plans. Reads `0` once a plan with overage is past its quota and still serving.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Seconds until the monthly quota resets. Absent on unlimited plans.","schema":{"type":"integer"}},"X-Resolved-City":{"description":"The covered city slug the request's `city` was resolved to, when it differs from what was sent (`city=dammam` answers for `eastern_province`). Absent when the slug was sent as is.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"filters":{"type":"object","properties":{"city":{"type":"string","example":"riyadh"},"neighborhood_ids":{"anyOf":[{"type":"array","items":{"type":"integer"}},{"type":"null"}]},"property_types":{"type":"array","items":{"type":"string","enum":["apartment","studio","floor","villa","duplex"]}}},"required":["city","neighborhood_ids","property_types"],"additionalProperties":false},"period":{"type":"object","properties":{"label":{"type":"string","example":"2026-Q1"},"start":{"type":"string","example":"2026-01-01"},"end":{"type":"string","example":"2026-03-31"}},"required":["label","start","end"],"additionalProperties":false},"available_periods":{"type":"array","items":{"type":"string"},"description":"Quarters REGA has published for this city, newest first."},"price_source":{"type":"string","enum":["asking","registered"],"description":"Where the prices come from: `asking` = advertised asking prices from listings; `registered` = registered transactions or rent contracts. Asking prices typically sit above what is finally agreed.","example":"asking"},"price_basis":{"type":"string","const":"yearly_rent"},"statistic":{"type":"string","const":"mean"},"min_sample_size":{"type":"integer"},"cells":{"type":"array","items":{"type":"object","properties":{"neighborhood_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Kite neighborhood id (GET /cities/{city}/neighborhoods), or null when REGA's name is not matched to one.","example":1287},"neighborhood_name_ar":{"type":"string","description":"REGA's name for the neighborhood."},"neighborhood_name_en":{"description":"Kite's English name, when matched.","type":["string","null"]},"town_ar":{"type":"string","description":"REGA's city (المدينة) for the cell."},"property_type":{"type":"string","enum":["apartment","studio","floor","villa","duplex"]},"property_type_ar":{"type":"string","description":"REGA's property type (نوع العقار)."},"contract_count":{"type":"integer","description":"Registered contracts behind the means.","example":214},"mean_rent_sar":{"type":"integer","description":"Mean yearly rent, SAR/year.","example":31500},"mean_rent_per_sqm_sar":{"description":"Mean yearly rent per m², SAR/m²/year.","example":241.99,"type":["number","null"]},"source_url":{"description":"The open.data.gov.sa dataset this cell came from.","type":["string","null"]}},"required":["neighborhood_id","neighborhood_name_ar","neighborhood_name_en","town_ar","property_type","property_type_ar","contract_count","mean_rent_sar","mean_rent_per_sqm_sar","source_url"],"additionalProperties":false}},"coverage":{"type":"object","properties":{"cells":{"type":"integer","description":"Cells REGA published for these filters."},"cells_served":{"type":"integer"},"cells_withheld":{"type":"integer"},"contracts":{"type":"integer"},"contracts_withheld":{"type":"integer"},"cells_served_with_neighborhood_id":{"type":"integer"}},"required":["cells","cells_served","cells_withheld","contracts","contracts_withheld","cells_served_with_neighborhood_id"],"additionalProperties":false},"city_totals":{"type":"array","items":{"type":"object","properties":{"property_type":{"type":"string","enum":["apartment","studio","floor","villa","duplex"]},"contract_count":{"type":"integer"},"mean_rent_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Mean yearly rent over every contract counted in the city; null when fewer than 5."},"cells":{"type":"integer"},"towns":{"type":"integer","description":"REGA towns the total spans."}},"required":["property_type","contract_count","mean_rent_sar","cells","towns"],"additionalProperties":false},"description":"City-wide mean per property type, over all cells including withheld ones. Not filtered by `neighborhood_id`."},"attribution":{"type":"object","properties":{"notice":{"type":"string","description":"Display this wherever you show or pass on these figures. The licence requires it."},"license":{"type":"object","properties":{"name":{"type":"string","example":"Saudi Open Data License v2.0 (an adaptation of the Open Data Commons Attribution License)"},"url":{"type":"string","example":"https://open.data.gov.sa/en/pages/policies/license"},"base_license":{"type":"string","example":"Open Data Commons Attribution License v1.0 (ODC-By)"},"base_license_url":{"type":"string","example":"https://opendatacommons.org/licenses/by/1-0/"}},"required":["name","url","base_license","base_license_url"],"additionalProperties":false},"datasets":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string","enum":["rega_rent_index","moj_transactions"]},"title":{"type":"string","description":"The dataset's title on the portal (Arabic)."},"title_en":{"type":"string"},"publisher":{"type":"string"},"urls":{"type":"array","items":{"type":"string"},"description":"The open.data.gov.sa datasets these figures came from (one per region-quarter for REGA, per quarter for MOJ)."}},"required":["source","title","title_en","publisher","urls"],"additionalProperties":false}}},"required":["notice","license","datasets"],"additionalProperties":false,"description":"Licence notice, licence links and source datasets. Figures derived from Saudi open data are served under the Saudi Open Data License (an adaptation of ODC-By), which requires this attribution to travel with them."}},"required":["filters","period","available_periods","price_source","price_basis","statistic","min_sample_size","cells","coverage","city_totals","attribution"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"filters":{"city":"riyadh","neighborhood_ids":[342],"property_types":["apartment"]},"period":{"label":"2026-Q1","start":"2026-01-01","end":"2026-03-31"},"available_periods":["2026-Q1"],"price_source":"asking","price_basis":"yearly_rent","statistic":"mean","min_sample_size":5,"cells":[{"neighborhood_id":1287,"neighborhood_name_ar":"الملقا","neighborhood_name_en":"Al Malqa","town_ar":"الرياض","property_type":"apartment","property_type_ar":"شقة","contract_count":214,"mean_rent_sar":31500,"mean_rent_per_sqm_sar":241.99,"source_url":"https://open.data.gov.sa/en/datasets"}],"coverage":{"cells":1240,"cells_served":1180,"cells_withheld":60,"contracts":48200,"contracts_withheld":310,"cells_served_with_neighborhood_id":1105},"city_totals":[{"property_type":"apartment","contract_count":48200,"mean_rent_sar":null,"cells":1240,"towns":6}],"attribution":{"notice":"Contains information from \"الصفقات العقارية\" (Real estate transactions, Ministry of Justice, open.data.gov.sa; links in `datasets`), which is made available under the ODC Attribution License, as adapted by the Open Data License of the Kingdom of Saudi Arabia.","license":{"name":"Saudi Open Data License v2.0 (an adaptation of the Open Data Commons Attribution License)","url":"https://open.data.gov.sa/en/pages/policies/license","base_license":"Open Data Commons Attribution License v1.0 (ODC-By)","base_license_url":"https://opendatacommons.org/licenses/by/1-0/"},"datasets":[{"source":"rega_rent_index","title":"الصفقات العقارية","title_en":"Real estate transactions","publisher":"Ministry of Justice","urls":["https://open.data.gov.sa/en/datasets"]}]}}}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/market/property-index":{"get":{"operationId":"official.market_index","summary":"Kite Property Index","description":"**Free on every plan (0 units).** Series built on Saudi open data are served under the Saudi Open Data License v2.0 with attribution: show `attribution.notice` wherever you display or pass on those figures.\n\nThe Kite Property Index, as published: the series of a **published monthly release**, frozen when it was released. Figures in a release never change; a correction is issued as a new revision with a note (`release.revision`, `release.revision_note`), and this endpoint returns the latest revision. Unreleased computations are never served. Methodology: https://kite.sa/en/market/methodology.\n\nSeries:\n\n- `rent_contracted`: mean yearly apartment rent of registered Ejar contracts, from REGA's open-data rent index. `price_source: \"registered\"`. Quarterly. City figures chain neighborhood means over a matched neighborhood basket, so a shift in where leases were signed doesn't read as a rent change.\n- `land_registered` and `home_registered` (registered sale prices) are temporarily unavailable. Requesting them is not an error: the response has no series for them.\n- `rent_asking`: median yearly asking rent of apartments listed on Kite. `price_source: \"asking\"`. Monthly, from March 2026. The national figure weights cities by REGA contract counts.\n\nA release drafted before 2026-11 may carry land from the Ministry of Justice open data (`source_key: \"moj_transactions\"`, `property: \"residential_land\"`); there, Riyadh-city points from 2024-Q1 carry `coverage_flag: \"notary_only\"` and the national series leaves Riyadh out.\n\nEach point has its `sample_size` (contracts, deals or listings: `sample_unit`); points with fewer than `min_sample_size` observations are withheld, and `withheld_periods` lists the gaps inside a series so a missing period is never read as zero. Levels of asking and contracted rent are different quantities; compare each series with its own history.","tags":["Official data"],"x-scope":"reference","x-units":0,"x-units-note":"0: Saudi open data is served free on every plan, including Sandbox","security":[{"apiKey":[]}],"parameters":[{"name":"series","in":"query","required":false,"description":"Series to return (comma-separated). Default all.","example":["rent_contracted"],"schema":{"minItems":1,"maxItems":4,"type":"array","items":{"type":"string","enum":["rent_contracted","rent_asking","land_registered","home_registered"]}},"style":"form","explode":false},{"name":"city","in":"query","required":false,"description":"`national`, or a city slug from GET /cities for that city's series. Default: national and every city.","example":"riyadh","schema":{"type":"string","pattern":"^[a-z_]+$"}},{"name":"release","in":"query","required":false,"description":"Release month, `YYYY-MM`. Default: the latest published release.","example":"2026-09","schema":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"}}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Units allowed per minute.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Units left this minute.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-Request-Units":{"description":"Units this request cost.","schema":{"type":"integer"}},"X-Quota-Limit":{"description":"Units allowed this calendar month (UTC). Absent on unlimited plans.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Units left this calendar month (UTC). Absent on unlimited plans. Reads `0` once a plan with overage is past its quota and still serving.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Seconds until the monthly quota resets. Absent on unlimited plans.","schema":{"type":"integer"}},"X-Resolved-City":{"description":"The covered city slug the request's `city` was resolved to, when it differs from what was sent (`city=dammam` answers for `eastern_province`). Absent when the slug was sent as is.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"release":{"type":"object","properties":{"slug":{"type":"string","example":"2026-09"},"revision":{"type":"integer","example":1},"published_at":{"type":"string","example":"2026-10-05T09:00:00.000Z"},"methodology_version":{"type":"string","example":"v1-2026-10"},"revision_note":{"type":["string","null"]},"headline":{"type":["string","null"]},"url":{"type":"string","example":"https://kite.sa/en/market/releases/2026-09"},"methodology_url":{"type":"string"}},"required":["slug","revision","published_at","methodology_version","revision_note","headline","url","methodology_url"],"additionalProperties":false},"available_releases":{"type":"array","items":{"type":"string"},"description":"Published releases, newest first."},"notes":{"type":"array","items":{"type":"string"},"description":"Caveats published with the release. Show them with the figures."},"series":{"type":"array","items":{"type":"object","properties":{"series":{"type":"string","enum":["rent_contracted","rent_asking","land_registered","home_registered"]},"label":{"type":"string"},"metric":{"type":"string","example":"mean_rent"},"statistic":{"type":"string","description":"`mean`, `median`, `chained_matched_index` or `hedonic_time_dummy` (a constant-quality index: log price per m² on period, location and size effects).","example":"mean"},"kind":{"type":"string","enum":["level","index"],"description":"`level`: a price in `unit`. `index`: read for change only; 100 in its base period (the first period, or 2025-Q1 for land since 2026-11)."},"unit":{"type":"string","example":"SAR/year"},"price_source":{"type":"string","enum":["asking","registered"],"description":"Where the prices come from: `asking` = advertised asking prices from listings; `registered` = registered transactions or rent contracts. Asking prices typically sit above what is finally agreed.","example":"asking"},"property":{"type":"string","enum":["apartment","land","residential_land","home"],"description":"`apartment` (rent), `land` (plots, not homes), `home` (apartments and floors), or `residential_land` (MOJ open-data land, releases before 2026-11)."},"source_key":{"type":"string","enum":["rega_rent_index","moj_transactions","rega_rei","darak_listings"],"description":"What the series is built on. `rega_rent_index` and `moj_transactions` are Saudi open data (see `attribution`); `darak_listings` is Kite's own listing panel. `rega_rei` series are temporarily unavailable.","example":"rega_rent_index"},"source":{"type":"string","description":"How to credit the series, verbatim.","example":"REGA Rent Index (open data)"},"geography":{"type":"string","enum":["national","city"]},"city":{"type":["string","null"]},"granularity":{"type":"string","example":"quarter"},"sample_unit":{"type":"string","enum":["contracts","deals","listings"]},"min_sample_size":{"type":"integer"},"withheld_periods":{"type":"array","items":{"type":"string"},"description":"Periods inside the series with no published point (withheld, not zero)."},"points":{"type":"array","items":{"type":"object","properties":{"period":{"type":"string","example":"2026-Q1"},"period_start":{"type":"string","example":"2026-01-01"},"value":{"type":"number","example":22923},"sample_size":{"type":"integer","example":612453},"coverage_flag":{"$ref":"#/components/schemas/CoverageFlag"}},"required":["period","period_start","value","sample_size","coverage_flag"],"additionalProperties":false}}},"required":["series","label","metric","statistic","kind","unit","price_source","property","source_key","source","geography","city","granularity","sample_unit","min_sample_size","withheld_periods","points"],"additionalProperties":false}},"attribution":{"anyOf":[{"type":"object","properties":{"notice":{"type":"string","description":"Display this wherever you show or pass on these figures. The licence requires it."},"license":{"type":"object","properties":{"name":{"type":"string","example":"Saudi Open Data License v2.0 (an adaptation of the Open Data Commons Attribution License)"},"url":{"type":"string","example":"https://open.data.gov.sa/en/pages/policies/license"},"base_license":{"type":"string","example":"Open Data Commons Attribution License v1.0 (ODC-By)"},"base_license_url":{"type":"string","example":"https://opendatacommons.org/licenses/by/1-0/"}},"required":["name","url","base_license","base_license_url"],"additionalProperties":false},"datasets":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string","enum":["rega_rent_index","moj_transactions"]},"title":{"type":"string","description":"The dataset's title on the portal (Arabic)."},"title_en":{"type":"string"},"publisher":{"type":"string"},"urls":{"type":"array","items":{"type":"string"},"description":"The open.data.gov.sa datasets these figures came from (one per region-quarter for REGA, per quarter for MOJ)."}},"required":["source","title","title_en","publisher","urls"],"additionalProperties":false}}},"required":["notice","license","datasets"],"additionalProperties":false,"description":"Licence notice, licence links and source datasets. Figures derived from Saudi open data are served under the Saudi Open Data License (an adaptation of ODC-By), which requires this attribution to travel with them."},{"type":"null"}],"description":"The open-data licence notice for the returned series built on Saudi open data. Null when none is (only Kite's asking-price panel)."}},"required":["release","available_releases","notes","series","attribution"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"release":{"slug":"2026-09","revision":1,"published_at":"2026-10-05T09:00:00.000Z","methodology_version":"v1-2026-10","revision_note":"2026-Q2 revised after late registrations.","headline":"Apartment prices rose 1.8% on the quarter.","url":"https://kite.sa/en/market/releases/2026-09","methodology_url":"https://platform.kite.sa/docs/guides/coverage"},"available_releases":["2026-q3"],"notes":["Riyadh city figures cover notary-registered deals only."],"series":[{"series":"rent_contracted","label":"Riyadh, apartments","metric":"mean_rent","statistic":"mean","kind":"level","unit":"SAR/year","price_source":"asking","property":"apartment","source_key":"rega_rent_index","source":"REGA Rent Index (open data)","geography":"national","city":"riyadh","granularity":"quarter","sample_unit":"contracts","min_sample_size":5,"withheld_periods":["2025-Q2"],"points":[{"period":"2026-Q1","period_start":"2026-01-01","value":22923,"sample_size":612453,"coverage_flag":"full"}]}],"attribution":{"notice":"Contains information from \"الصفقات العقارية\" (Real estate transactions, Ministry of Justice, open.data.gov.sa; links in `datasets`), which is made available under the ODC Attribution License, as adapted by the Open Data License of the Kingdom of Saudi Arabia.","license":{"name":"Saudi Open Data License v2.0 (an adaptation of the Open Data Commons Attribution License)","url":"https://open.data.gov.sa/en/pages/policies/license","base_license":"Open Data Commons Attribution License v1.0 (ODC-By)","base_license_url":"https://opendatacommons.org/licenses/by/1-0/"},"datasets":[{"source":"rega_rent_index","title":"الصفقات العقارية","title_en":"Real estate transactions","publisher":"Ministry of Justice","urls":["https://open.data.gov.sa/en/datasets"]}]}}}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/listings/{id}/comparables":{"get":{"operationId":"analytics.listing_comparables","summary":"Get comparable listings","description":"Active listings similar to this one, nearest first, with how each one differs.\n\nA comparable has the same city, listing type and property type, is within about 5 km, and has an area between 2/3 and 1.5 times this listing's (the comparison-approach caliper). Residential comparables also have the same bedroom count and must pass Kite's price, bedroom, area, property-type and location quality checks. Both this listing's and each comparable's area must be trustworthy, so listings without coordinates or with an unreliable area return no comparables and say why in `unavailable_reason`.\n\n`summary` describes the comparables returned (it depends on `limit`). Prices are asking prices in SAR: yearly rent for rentals (monthly, weekly and daily postings are converted to a yearly amount), total price for sales.","tags":["Analytics"],"x-scope":"market","x-units":75,"security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Listing id.","example":128647,"schema":{"type":"integer","minimum":1,"maximum":2147483647}},{"name":"limit","in":"query","required":false,"description":"How many comparables to return.","schema":{"default":20,"type":"integer","minimum":1,"maximum":50}}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Units allowed per minute.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Units left this minute.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-Request-Units":{"description":"Units this request cost.","schema":{"type":"integer"}},"X-Quota-Limit":{"description":"Units allowed this calendar month (UTC). Absent on unlimited plans.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Units left this calendar month (UTC). Absent on unlimited plans. Reads `0` once a plan with overage is past its quota and still serving.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Seconds until the monthly quota resets. Absent on unlimited plans.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"listing_id":{"type":"integer","example":128647},"price_basis":{"type":"string","enum":["yearly_rent","sale_price"],"description":"What the `*_sar` price fields mean: `yearly_rent` (SAR per year) for rentals, `sale_price` (total SAR) for sales."},"price_source":{"type":"string","enum":["asking","registered"],"description":"Where the prices come from: `asking` = advertised asking prices from listings; `registered` = registered transactions or rent contracts. Asking prices typically sit above what is finally agreed.","example":"asking"},"unavailable_reason":{"anyOf":[{"type":"string","enum":["no_coordinates","unreliable_area"]},{"type":"null"}],"description":"Why no comparables could be searched for: the listing has no coordinates, or its area is missing or failed Kite's area checks. Null when the search ran."},"criteria":{"type":"object","properties":{"max_distance_m":{"type":"integer","example":5000},"area_range_sqm":{"anyOf":[{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"],"additionalProperties":false},{"type":"null"}],"description":"Area band comparables fall in."},"same_bedrooms":{"type":"boolean","description":"Whether comparables must match the bedroom count."}},"required":["max_distance_m","area_range_sqm","same_bedrooms"],"additionalProperties":false},"summary":{"type":"object","properties":{"sample_size":{"type":"integer","description":"Comparables returned.","example":24},"median_price_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Median price of the comparables returned; null below 5.","example":52000},"listing_price_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"This listing's price."},"diff_from_median_pct":{"description":"This listing's price vs that median, in percent (negative = cheaper).","example":-8.5,"type":["number","null"]}},"required":["sample_size","median_price_sar","listing_price_sar","diff_from_median_pct"],"additionalProperties":false},"comparables":{"type":"array","items":{"type":"object","properties":{"listing":{"$ref":"#/components/schemas/Listing"},"similarity":{"type":"object","properties":{"distance_m":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Straight-line distance from this listing."},"area_diff_pct":{"description":"Comparable's area vs this listing's, in percent.","type":["number","null"]},"price_diff_pct":{"description":"Comparable's price vs this listing's, in percent.","type":["number","null"]}},"required":["distance_m","area_diff_pct","price_diff_pct"],"additionalProperties":false}},"required":["listing","similarity"],"additionalProperties":false}}},"required":["listing_id","price_basis","price_source","unavailable_reason","criteria","summary","comparables"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"listing_id":128647,"price_basis":"yearly_rent","price_source":"asking","unavailable_reason":"no_coordinates","criteria":{"max_distance_m":5000,"area_range_sqm":{"min":95,"max":220},"same_bedrooms":true},"summary":{"sample_size":24,"median_price_sar":52000,"listing_price_sar":null,"diff_from_median_pct":-8.5},"comparables":[{"listing":{"id":128647,"url":"https://kite.sa/en/listing/128647","title":"شقة للإيجار في حي الملقا","headline":"3-bedroom apartment for rent in Al Malqa, Riyadh","description":"شقة ثلاث غرف وصالة ومطبخ راكب، الدور الثاني، قريبة من الخدمات.","description_en":"Three-bedroom apartment with a living room and fitted kitchen, second floor, close to services.","listing_type":"rent","listing_category":"residential","property_type":"apartment","price":{"yearly_sar":60000,"as_posted":{"amount":5000,"frequency":"monthly"},"previous_yearly_sar":66000,"changed_at":"2026-09-21T10:00:00.000Z","price_basis":"yearly_rent","price_source":"asking"},"financing":{"rent_now_pay_later_monthly_sar":5450,"accepts_bank_financing":true,"landlord_payment_plans":{"monthly":true,"quarterly":true,"semiannually":true}},"bedrooms":3,"bathrooms":2,"livings":1,"area_sqm":140,"floor":"2","age_years":4,"furnished":false,"amenities":["ac","kitchen","parking"],"photo_features":[{"feature":"real_photos","image_index":0},{"feature":"kitchen_installed","image_index":3}],"location":{"city":"riyadh","city_name_en":"Riyadh","neighborhood_id":12,"neighborhood_name_ar":"الملقا","neighborhood_name_en":"Al Malqa","lat":24.7869,"lng":46.6215,"street_width_m":20},"plot":{"zoning":"residential","is_corner":false,"frontage_count":1,"facing":["north"],"street_width_m":25,"street_width_source":"official","plot_area_sqm":449.1,"buildable_area_sqm":747,"buildable_far":1.66,"price_per_buildable_sqm_sar":2410,"urban_growth_phase":"1440","urban_growth_year":1440,"white_land_fee":{"band":3,"rate_pct":5,"as_of":"2025-08-26"},"last_registered_sale":{"month":"2026-08","price_sar":1850000,"price_per_sqm_sar":4111,"area_sqm":450,"registry":"Real Estate Registry","areas_agree":true,"ask_to_last_sale_ratio":0.973,"months_since":3},"registered_sale_while_listed":{"month":"2026-10","price_sar":1800000,"registry":"Real Estate Registry","ask_at_sale_sar":1950000,"areas_agree":true,"deal_to_ask_ratio":0.923,"weeks_to_sell":7},"registered_sales_count":1,"match":{"method":"plan_parcel_and_pin","confidence":0.9}},"compound_name":"Sedra","project_id":null,"images":["https://images.darak.app/listings/128647/1.webp"],"image_count":8,"advertiser":{"type":"agency","name":"مكتب الملقا للعقار","name_en":"Al Malqa Real Estate","company":"Al Malqa Real Estate Company","logo":"https://images.example.com/advertisers/al-malqa.png","fal_number":"1100012345","cr":"1010012345","ad_license":"7100232271","contact_available":true},"verified_by_source":true,"source":{"name":"aqar","listing_id":"7788123","url":"https://kite.sa/r/128647"},"also_listed_on":["bayut"],"first_seen_at":"2026-09-21T10:00:00.000Z","updated_at":"2026-09-21T10:00:00.000Z","last_seen_at":"2026-09-21T10:00:00.000Z","days_on_market":12},"similarity":{"distance_m":null,"area_diff_pct":4.2,"price_diff_pct":-3.5}}]}}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/listings/{id}/market-position":{"get":{"operationId":"analytics.listing_market_position","summary":"Get a listing's market position","description":"Where a listing's price sits in its market: percentile, quartiles and difference from the median, against like-for-like listings in its neighborhood and in its city.\n\nThe cohort is listings with the same listing type, category and property type, and for residential listings the same bedroom count. `basis` says which cohort the top-level `price_percentile` and `diff_from_median_pct` use: the neighborhood when it has at least 30 listings, otherwise the city.\n\nComputed over the market sample: active, deduplicated listings updated in the last 30 days (`updated_at`), after the same outlier filter kite.sa uses (per-tier price fences from the median and MAD of log price, bedroom and area sanity checks, and a floor at 30% of the neighborhood median). Prices are asking prices in SAR: yearly rent for rentals (monthly, weekly and daily postings are converted to a yearly amount), total price for sales. Medians and quartiles are null when fewer than 5 listings back them; check `sample_size` before relying on a number. `listing_in_sample` says whether the listing itself passed those filters (a listing not updated in 30 days, or priced as an outlier, is compared but not counted).","tags":["Analytics"],"x-scope":"market","x-units":50,"security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Listing id.","example":128647,"schema":{"type":"integer","minimum":1,"maximum":2147483647}}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Units allowed per minute.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Units left this minute.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-Request-Units":{"description":"Units this request cost.","schema":{"type":"integer"}},"X-Quota-Limit":{"description":"Units allowed this calendar month (UTC). Absent on unlimited plans.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Units left this calendar month (UTC). Absent on unlimited plans. Reads `0` once a plan with overage is past its quota and still serving.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Seconds until the monthly quota resets. Absent on unlimited plans.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"listing_id":{"type":"integer","example":128647},"price_basis":{"type":"string","enum":["yearly_rent","sale_price"],"description":"What the `*_sar` price fields mean: `yearly_rent` (SAR per year) for rentals, `sale_price` (total SAR) for sales."},"price_source":{"type":"string","enum":["asking","registered"],"description":"Where the prices come from: `asking` = advertised asking prices from listings; `registered` = registered transactions or rent contracts. Asking prices typically sit above what is finally agreed.","example":"asking"},"price_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"This listing's price.","example":50000},"price_per_sqm_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"This listing's price per m², when it states an area."},"cohort":{"type":"object","properties":{"city":{"type":"string","example":"riyadh"},"listing_type":{"anyOf":[{"type":"string","enum":["rent","sale"]},{"type":"null"}]},"listing_category":{"anyOf":[{"type":"string","enum":["residential","commercial"]},{"type":"null"}],"description":"The category applied; null when both are included."},"property_type":{"type":["string","null"]},"neighborhood_ids":{"anyOf":[{"type":"array","items":{"type":"integer"}},{"type":"null"}],"example":[12]},"beds":{"anyOf":[{"type":"integer"},{"type":"null"}]}},"required":["city","listing_type","listing_category","property_type","neighborhood_ids","beds"],"additionalProperties":false,"description":"The filters the numbers were computed for, after defaults."},"basis":{"anyOf":[{"type":"string","enum":["neighborhood","city"]},{"type":"null"}],"description":"Which cohort the top-level percentile and difference come from. Null when no cohort could be computed (no price, or a city Kite doesn't cover)."},"price_percentile":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"From the `basis` cohort."},"diff_from_median_pct":{"description":"From the `basis` cohort.","type":["number","null"]},"neighborhood":{"anyOf":[{"type":"object","properties":{"sample_size":{"type":"integer","description":"Listings in the cohort.","example":214},"median_price_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Median price of the cohort.","example":55000},"p25_price_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"25th percentile price."},"p75_price_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"75th percentile price."},"median_price_per_sqm_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Median price per m², over cohort listings that state an area."},"price_percentile":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Share of the cohort priced below this listing (ties count half), 0-100. 20 means cheaper than 80% of the cohort.","example":38},"diff_from_median_pct":{"description":"This listing's price vs the cohort median, in percent (negative = cheaper).","example":-9.1,"type":["number","null"]},"neighborhood_id":{"type":"integer"},"name_en":{"type":["string","null"]},"name_ar":{"type":["string","null"]},"town":{"$ref":"#/components/schemas/NeighborhoodTown"}},"required":["sample_size","median_price_sar","p25_price_sar","p75_price_sar","median_price_per_sqm_sar","price_percentile","diff_from_median_pct","neighborhood_id","name_en","name_ar","town"],"additionalProperties":false},{"type":"null"}],"description":"Null when the listing has no neighborhood, no price, or is in a city Kite doesn't cover."},"city":{"anyOf":[{"type":"object","properties":{"sample_size":{"type":"integer","description":"Listings in the cohort.","example":214},"median_price_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Median price of the cohort.","example":55000},"p25_price_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"25th percentile price."},"p75_price_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"75th percentile price."},"median_price_per_sqm_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Median price per m², over cohort listings that state an area."},"price_percentile":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Share of the cohort priced below this listing (ties count half), 0-100. 20 means cheaper than 80% of the cohort.","example":38},"diff_from_median_pct":{"description":"This listing's price vs the cohort median, in percent (negative = cheaper).","example":-9.1,"type":["number","null"]}},"required":["sample_size","median_price_sar","p25_price_sar","p75_price_sar","median_price_per_sqm_sar","price_percentile","diff_from_median_pct"],"additionalProperties":false},{"type":"null"}],"description":"Null when the listing has no price or is in a city Kite doesn't cover."},"listing_in_sample":{"type":"boolean"},"window":{"type":"object","properties":{"updated_within_days":{"type":"integer","example":30},"from":{"type":"string","description":"Listings updated at or after this time are included (ISO 8601).","example":"2026-08-23T09:00:00.000Z"},"to":{"type":"string","description":"When the numbers were computed (ISO 8601). Results may be cached up to an hour.","example":"2026-09-22T09:00:00.000Z"}},"required":["updated_within_days","from","to"],"additionalProperties":false,"description":"The freshness window of the market sample."}},"required":["listing_id","price_basis","price_source","price_sar","price_per_sqm_sar","cohort","basis","price_percentile","diff_from_median_pct","neighborhood","city","listing_in_sample","window"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"listing_id":128647,"price_basis":"yearly_rent","price_source":"asking","price_sar":50000,"price_per_sqm_sar":null,"cohort":{"city":"riyadh","listing_type":"rent","listing_category":"residential","property_type":"apartment","neighborhood_ids":[12],"beds":null},"basis":"neighborhood","price_percentile":null,"diff_from_median_pct":7.1,"neighborhood":{"sample_size":214,"median_price_sar":55000,"p25_price_sar":null,"p75_price_sar":null,"median_price_per_sqm_sar":null,"price_percentile":38,"diff_from_median_pct":-9.1,"neighborhood_id":342,"name_en":"Al Malqa","name_ar":"الملقا","town":{"name_en":"Khobar","name_ar":"الخبر"}},"city":{"sample_size":214,"median_price_sar":55000,"p25_price_sar":null,"p75_price_sar":null,"median_price_per_sqm_sar":null,"price_percentile":38,"diff_from_median_pct":-9.1},"listing_in_sample":true,"window":{"updated_within_days":30,"from":"2026-08-23T09:00:00.000Z","to":"2026-09-22T09:00:00.000Z"}}}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/listings/{id}/price-band":{"get":{"operationId":"analytics.listing_price_band","summary":"Get a listing's nearby asking-price band","description":"The 25th percentile, median and 75th percentile of asking prices for comparable units near this listing, in SAR and per m², where this listing's price sits against them, and the cohort and stability behind the numbers. Use it as a fair-price check on an ask; it compares asking prices and is not a valuation.\n\nThe band comes from Kite's published nearby asking-price comparison (methodology `nearby-asking-v5`): the same snapshot the kite.sa listing page and GET /market/below-market use, so the three always agree.\n\nComparables are residential listings with the same listing type, property type and exact bedroom count, an area within a calibrated tolerance of this listing's, inside a calibrated radius and look-back. Each distinct unit counts once, at its latest asking price (copies across sources and reposts collapse into one), and this listing's own copies are left out. Every comparable passes Kite's price, bedroom, area, property-type and location checks. Radius, look-back, area tolerance and the minimum evidence are calibrated per city, property type, bedroom count and listing type, and a comparison is published only for cohorts that passed that calibration. Nothing falls back to a wider area or ignores bedrooms. A band needs the cohort's minimum number of distinct units, spread across independent evidence clusters (a project, or a ~100 m cell).\n\n`p25`–`p75` is the middle half of nearby asking prices. It is not a valuation, an appraisal or an expected achieved price. Prices are asking prices in SAR: yearly rent for rentals (monthly, weekly and daily postings are converted to a yearly amount), total price for sales. Snapshots are refreshed at least weekly, and retired as soon as this listing's price, bedrooms or property type change.\n\nGET /listings/{id}/market-position always answers, against the whole neighborhood and city. This endpoint answers only for a like-for-like nearby cohort, and otherwise says why not. `status` is `available` when there is a band. Otherwise `band`, `position` and `stability` are null and `status` gives the reason:\n\n- `insufficient_comparables`: the cohort is published but too few distinct units were observed nearby. `cohort` shows what was searched and found.\n- `unsupported_cohort`: this city, property type, bedroom count and listing type hasn't passed calibration, so no comparison is published for it.\n- `not_residential`, `multi_unit` (the ad prices several units together), `no_price`, `no_location`: the listing can't be compared.\n- `plot_area_only`: the listing gives only the building plot's area, not the unit's, and comparables are matched on unit area.\n- `area_unusable`: the area is missing or failed Kite's area checks.\n- `fields_unusable`: the price, bedrooms, property type or location failed Kite's checks.","tags":["Analytics"],"x-scope":"market","x-units":50,"security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Listing id.","example":128647,"schema":{"type":"integer","minimum":1,"maximum":2147483647}}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Units allowed per minute.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Units left this minute.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-Request-Units":{"description":"Units this request cost.","schema":{"type":"integer"}},"X-Quota-Limit":{"description":"Units allowed this calendar month (UTC). Absent on unlimited plans.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Units left this calendar month (UTC). Absent on unlimited plans. Reads `0` once a plan with overage is past its quota and still serving.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Seconds until the monthly quota resets. Absent on unlimited plans.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"listing_id":{"type":"integer","example":128647},"status":{"type":"string","enum":["available","insufficient_comparables","unsupported_cohort","not_residential","multi_unit","no_price","no_location","plot_area_only","area_unusable","fields_unusable"],"description":"`available`, or why there is no band. See the endpoint description.","example":"available"},"price_basis":{"type":"string","enum":["yearly_rent","sale_price"],"description":"What the `*_sar` price fields mean: `yearly_rent` (SAR per year) for rentals, `sale_price` (total SAR) for sales."},"price_source":{"type":"string","enum":["asking","registered"],"description":"Where the prices come from: `asking` = advertised asking prices from listings; `registered` = registered transactions or rent contracts. Asking prices typically sit above what is finally agreed.","example":"asking"},"price_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"This listing's asking price.","example":50000},"price_per_sqm_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"This listing's asking price per m². Null unless its area passed Kite's checks.","example":500},"band":{"anyOf":[{"type":"object","properties":{"price":{"type":"object","properties":{"p25_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"25th percentile.","example":48000},"median_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Median.","example":55000},"p75_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"75th percentile.","example":62000}},"required":["p25_sar","median_sar","p75_sar"],"additionalProperties":false},"price_per_sqm":{"type":"object","properties":{"p25_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"25th percentile.","example":480},"median_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Median.","example":550},"p75_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"75th percentile.","example":620}},"required":["p25_sar","median_sar","p75_sar"],"additionalProperties":false,"description":"Percentiles of each comparable's own price per m² (not the price percentiles divided by an area)."},"spread_pct":{"description":"(p75 − p25) ÷ median of price, in percent: how dispersed nearby asks are.","example":26.4,"type":["number","null"]}},"required":["price","price_per_sqm","spread_pct"],"additionalProperties":false},{"type":"null"}],"description":"Null unless `status` is `available`."},"position":{"anyOf":[{"type":"object","properties":{"diff_from_median_pct":{"description":"This listing's price vs the median, in percent (negative = cheaper).","example":-9.1,"type":["number","null"]},"placement":{"type":"string","enum":["below_band","within_band","above_band"],"description":"Where the price falls against p25–p75.","example":"within_band"},"direction":{"type":"string","enum":["below","near","above","inconclusive"],"description":"`below` or `above` the median only when the median's 95% interval (`stability.median_interval_sar`) excludes this price and the difference, rounded to the nearest 5%, is at least 5%; `near` when that interval excludes the price but the rounded difference is under 5%; `inconclusive` when the interval includes the price. The same rule as the kite.sa listing page."}},"required":["diff_from_median_pct","placement","direction"],"additionalProperties":false},{"type":"null"}],"description":"Null unless `status` is `available`."},"stability":{"anyOf":[{"type":"object","properties":{"median_interval_sar":{"anyOf":[{"type":"object","properties":{"low":{"type":"integer","example":52000},"high":{"type":"integer","example":58000}},"required":["low","high"],"additionalProperties":false},{"type":"null"}],"description":"95% cluster-bootstrap interval of the median: evidence clusters are resampled, not single ads, so one building with many units can't fake precision."},"direction_stable":{"type":"boolean","description":"True when this listing's price lies outside `median_interval_sar`."},"limited_evidence":{"type":"boolean","description":"True when the cohort is only just above its calibrated minimum.","example":false}},"required":["median_interval_sar","direction_stable","limited_evidence"],"additionalProperties":false},{"type":"null"}],"description":"Null unless `status` is `available`."},"cohort":{"anyOf":[{"type":"object","properties":{"listing_type":{"type":"string","enum":["rent","sale"]},"property_type":{"type":"string","example":"apartment"},"bedrooms":{"type":"integer","example":2},"radius_m":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Search radius.","example":2000},"look_back_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Comparables were observed within this many days.","example":90},"area_tolerance_pct":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Comparables' area is within this percent of this listing's.","example":20},"distinct_units":{"type":"integer","description":"Distinct comparable units found.","example":23},"evidence_clusters":{"type":"integer","description":"Independent evidence clusters among them (projects or ~100 m cells).","example":17}},"required":["listing_type","property_type","bedrooms","radius_m","look_back_days","area_tolerance_pct","distinct_units","evidence_clusters"],"additionalProperties":false},{"type":"null"}],"description":"The comparison that was run. Null when none was (`unsupported_cohort`, or a reason about the listing itself)."},"methodology":{"anyOf":[{"type":"object","properties":{"version":{"type":"string","example":"nearby-asking-v5"},"calibration_version":{"example":"global-2026-07-16","type":["string","null"]},"comparison_id":{"type":"string","description":"Id of the immutable comparison snapshot.","example":"6f1d2c1e-8f7a-4c1b-9d7e-2a3b4c5d6e7f"},"computed_at":{"type":"string","description":"When the comparison was computed (ISO 8601).","example":"2026-09-25T04:12:09.000Z"},"expires_at":{"type":"string","description":"When it is due to be recomputed (ISO 8601).","example":"2026-10-02T04:12:09.000Z"}},"required":["version","calibration_version","comparison_id","computed_at","expires_at"],"additionalProperties":false},{"type":"null"}],"description":"Null when no comparison was run."}},"required":["listing_id","status","price_basis","price_source","price_sar","price_per_sqm_sar","band","position","stability","cohort","methodology"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"listing_id":128647,"status":"available","price_basis":"yearly_rent","price_source":"asking","price_sar":50000,"price_per_sqm_sar":500,"band":{"price":{"p25_sar":48000,"median_sar":55000,"p75_sar":62000},"price_per_sqm":{"p25_sar":480,"median_sar":550,"p75_sar":620},"spread_pct":26.4},"position":{"diff_from_median_pct":-9.1,"placement":"within_band","direction":"below"},"stability":{"median_interval_sar":{"low":52000,"high":58000},"direction_stable":true,"limited_evidence":false},"cohort":{"listing_type":"rent","property_type":"apartment","bedrooms":2,"radius_m":2000,"look_back_days":90,"area_tolerance_pct":20,"distinct_units":23,"evidence_clusters":17},"methodology":{"version":"nearby-asking-v5","calibration_version":"global-2026-07-16","comparison_id":"6f1d2c1e-8f7a-4c1b-9d7e-2a3b4c5d6e7f","computed_at":"2026-09-25T04:12:09.000Z","expires_at":"2026-10-02T04:12:09.000Z"}}}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/market/below-market":{"get":{"operationId":"analytics.below_market","summary":"Find below-market listings","description":"Residential listings asking noticeably less than similar listings nearby, biggest gap first. These are listings, not deals: \"deal\" in this API means a registered transaction (GET /transactions).\n\nEach listing is compared with Kite's published nearby asking-price comparison: the same property type and bedroom count, a similar area, within a calibrated radius and look-back (disclosed per listing in `comparison`), one observation per distinct unit, and the subject's own duplicates excluded. A listing appears only when the comparison is published for its cohort and its direction is stable under a 95% cluster bootstrap, so thin or noisy evidence never puts a listing here. This is an asking-price comparison, not a valuation.\n\nListings are drawn from the market sample: active, deduplicated listings updated in the last 30 days (`updated_at`), after the same outlier filter kite.sa uses (per-tier price fences from the median and MAD of log price, bedroom and area sanity checks, and a floor at 30% of the neighborhood median). Prices are asking prices in SAR: yearly rent for rentals (monthly, weekly and daily postings are converted to a yearly amount), total price for sales. Paginate with `cursor`.","tags":["Analytics"],"x-scope":"analytics","x-units":"2 per result asked for with `limit` (default 25), up to your plan's page size","security":[{"apiKey":[]}],"parameters":[{"name":"city","in":"query","required":true,"description":"City slug from GET /cities. A town inside a covered region is accepted and resolved to its city (`dammam`, `khobar`, `dhahran`, `jubail` and `qatif` to `eastern_province`; `buraydah` and `unaizah` to `qassim`; `hofuf` to `al_ahsa`), as are Arabic city names. The response's `filters.city` and the `X-Resolved-City` header show the slug used.","example":"riyadh","schema":{"type":"string","pattern":"^[a-z_]+$"}},{"name":"listing_type","in":"query","required":true,"description":"`rent` (prices are yearly rent) or `sale` (prices are total price).","schema":{"type":"string","enum":["rent","sale"]}},{"name":"property_type","in":"query","required":false,"description":"One residential property type.","example":"apartment","schema":{"type":"string","enum":["apartment","villa","floor","duplex"]}},{"name":"beds","in":"query","required":false,"description":"Exact number of bedrooms (0 = studio).","example":2,"schema":{"type":"integer","minimum":0,"maximum":20}},{"name":"neighborhood_id","in":"query","required":false,"description":"Limit to one or more neighborhoods (comma-separated ids from GET /cities/{city}/neighborhoods). Unknown ids are a 404.","example":[1287,1301],"schema":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"integer","minimum":1,"maximum":2147483647}},"style":"form","explode":false},{"name":"min_discount_pct","in":"query","required":false,"description":"Minimum percent below the nearby median.","example":15,"schema":{"default":10,"type":"number","minimum":5,"maximum":90}},{"name":"max_discount_pct","in":"query","required":false,"description":"Maximum percent below the nearby median. Listings priced far below their neighbors are usually mispriced or mislabeled, so they're left out by default.","example":50,"schema":{"default":50,"type":"number","minimum":10,"maximum":95}},{"name":"limit","in":"query","required":false,"schema":{"default":25,"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":500}}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Units allowed per minute.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Units left this minute.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-Request-Units":{"description":"Units this request cost.","schema":{"type":"integer"}},"X-Quota-Limit":{"description":"Units allowed this calendar month (UTC). Absent on unlimited plans.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Units left this calendar month (UTC). Absent on unlimited plans. Reads `0` once a plan with overage is past its quota and still serving.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Seconds until the monthly quota resets. Absent on unlimited plans.","schema":{"type":"integer"}},"X-Resolved-City":{"description":"The covered city slug the request's `city` was resolved to, when it differs from what was sent (`city=dammam` answers for `eastern_province`). Absent when the slug was sent as is.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"listing":{"$ref":"#/components/schemas/Listing"},"comparison":{"type":"object","properties":{"median_price_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Median asking price of the nearby comparables.","example":60000},"p25_price_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"25th percentile of the nearby comparables."},"p75_price_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"75th percentile of the nearby comparables."},"percent_vs_median":{"description":"This listing's price vs that median, in percent (negative = cheaper).","example":-18.4,"type":["number","null"]},"sample_size":{"type":"integer","description":"Distinct comparable units.","example":87},"radius_m":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Search radius used."},"look_back_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"How far back comparables were observed."},"price_basis":{"type":"string","enum":["yearly_rent","sale_price"],"description":"What the `*_sar` price fields mean: `yearly_rent` (SAR per year) for rentals, `sale_price` (total SAR) for sales."},"price_source":{"type":"string","enum":["asking","registered"],"description":"Where the prices come from: `asking` = advertised asking prices from listings; `registered` = registered transactions or rent contracts. Asking prices typically sit above what is finally agreed.","example":"asking"}},"required":["median_price_sar","p25_price_sar","p75_price_sar","percent_vs_median","sample_size","radius_m","look_back_days","price_basis","price_source"],"additionalProperties":false}},"required":["listing","comparison"],"additionalProperties":false}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"],"additionalProperties":false},"example":{"data":[{"listing":{"id":128647,"url":"https://kite.sa/en/listing/128647","title":"شقة للإيجار في حي الملقا","headline":"3-bedroom apartment for rent in Al Malqa, Riyadh","description":"شقة ثلاث غرف وصالة ومطبخ راكب، الدور الثاني، قريبة من الخدمات.","description_en":"Three-bedroom apartment with a living room and fitted kitchen, second floor, close to services.","listing_type":"rent","listing_category":"residential","property_type":"apartment","price":{"yearly_sar":60000,"as_posted":{"amount":5000,"frequency":"monthly"},"previous_yearly_sar":66000,"changed_at":"2026-09-21T10:00:00.000Z","price_basis":"yearly_rent","price_source":"asking"},"financing":{"rent_now_pay_later_monthly_sar":5450,"accepts_bank_financing":true,"landlord_payment_plans":{"monthly":true,"quarterly":true,"semiannually":true}},"bedrooms":3,"bathrooms":2,"livings":1,"area_sqm":140,"floor":"2","age_years":4,"furnished":false,"amenities":["ac","kitchen","parking"],"photo_features":[{"feature":"real_photos","image_index":0},{"feature":"kitchen_installed","image_index":3}],"location":{"city":"riyadh","city_name_en":"Riyadh","neighborhood_id":12,"neighborhood_name_ar":"الملقا","neighborhood_name_en":"Al Malqa","lat":24.7869,"lng":46.6215,"street_width_m":20},"plot":{"zoning":"residential","is_corner":false,"frontage_count":1,"facing":["north"],"street_width_m":25,"street_width_source":"official","plot_area_sqm":449.1,"buildable_area_sqm":747,"buildable_far":1.66,"price_per_buildable_sqm_sar":2410,"urban_growth_phase":"1440","urban_growth_year":1440,"white_land_fee":{"band":3,"rate_pct":5,"as_of":"2025-08-26"},"last_registered_sale":{"month":"2026-08","price_sar":1850000,"price_per_sqm_sar":4111,"area_sqm":450,"registry":"Real Estate Registry","areas_agree":true,"ask_to_last_sale_ratio":0.973,"months_since":3},"registered_sale_while_listed":{"month":"2026-10","price_sar":1800000,"registry":"Real Estate Registry","ask_at_sale_sar":1950000,"areas_agree":true,"deal_to_ask_ratio":0.923,"weeks_to_sell":7},"registered_sales_count":1,"match":{"method":"plan_parcel_and_pin","confidence":0.9}},"compound_name":"Sedra","project_id":null,"images":["https://images.darak.app/listings/128647/1.webp"],"image_count":8,"advertiser":{"type":"agency","name":"مكتب الملقا للعقار","name_en":"Al Malqa Real Estate","company":"Al Malqa Real Estate Company","logo":"https://images.example.com/advertisers/al-malqa.png","fal_number":"1100012345","cr":"1010012345","ad_license":"7100232271","contact_available":true},"verified_by_source":true,"source":{"name":"aqar","listing_id":"7788123","url":"https://kite.sa/r/128647"},"also_listed_on":["bayut"],"first_seen_at":"2026-09-21T10:00:00.000Z","updated_at":"2026-09-21T10:00:00.000Z","last_seen_at":"2026-09-21T10:00:00.000Z","days_on_market":12},"comparison":{"median_price_sar":60000,"p25_price_sar":null,"p75_price_sar":null,"percent_vs_median":-18.4,"sample_size":87,"radius_m":null,"look_back_days":null,"price_basis":"yearly_rent","price_source":"asking"}}],"pagination":{"limit":25,"next_cursor":"eyJvIjoyNSwiZiI6IksweTFfU1F3d1BXSiJ9.pkFEfJUOpRbZRS279EDC4v","has_more":true,"result_window_reached":false}}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/market/deals":{"get":{"operationId":"analytics.deals","summary":"Find below-market listings (old path)","description":"**Deprecated:** use GET /market/below-market, which takes the same parameters and returns the same response. This path keeps working until 2027-06-30.\n\nResidential listings asking noticeably less than similar listings nearby, biggest gap first. These are listings, not deals: \"deal\" in this API means a registered transaction (GET /transactions).\n\nEach listing is compared with Kite's published nearby asking-price comparison: the same property type and bedroom count, a similar area, within a calibrated radius and look-back (disclosed per listing in `comparison`), one observation per distinct unit, and the subject's own duplicates excluded. A listing appears only when the comparison is published for its cohort and its direction is stable under a 95% cluster bootstrap, so thin or noisy evidence never puts a listing here. This is an asking-price comparison, not a valuation.\n\nListings are drawn from the market sample: active, deduplicated listings updated in the last 30 days (`updated_at`), after the same outlier filter kite.sa uses (per-tier price fences from the median and MAD of log price, bedroom and area sanity checks, and a floor at 30% of the neighborhood median). Prices are asking prices in SAR: yearly rent for rentals (monthly, weekly and daily postings are converted to a yearly amount), total price for sales. Paginate with `cursor`.","tags":["Analytics"],"deprecated":true,"x-scope":"analytics","x-units":"2 per result asked for with `limit` (default 25), up to your plan's page size","security":[{"apiKey":[]}],"parameters":[{"name":"city","in":"query","required":true,"description":"City slug from GET /cities. A town inside a covered region is accepted and resolved to its city (`dammam`, `khobar`, `dhahran`, `jubail` and `qatif` to `eastern_province`; `buraydah` and `unaizah` to `qassim`; `hofuf` to `al_ahsa`), as are Arabic city names. The response's `filters.city` and the `X-Resolved-City` header show the slug used.","example":"riyadh","schema":{"type":"string","pattern":"^[a-z_]+$"}},{"name":"listing_type","in":"query","required":true,"description":"`rent` (prices are yearly rent) or `sale` (prices are total price).","schema":{"type":"string","enum":["rent","sale"]}},{"name":"property_type","in":"query","required":false,"description":"One residential property type.","example":"apartment","schema":{"type":"string","enum":["apartment","villa","floor","duplex"]}},{"name":"beds","in":"query","required":false,"description":"Exact number of bedrooms (0 = studio).","example":2,"schema":{"type":"integer","minimum":0,"maximum":20}},{"name":"neighborhood_id","in":"query","required":false,"description":"Limit to one or more neighborhoods (comma-separated ids from GET /cities/{city}/neighborhoods). Unknown ids are a 404.","example":[1287,1301],"schema":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"integer","minimum":1,"maximum":2147483647}},"style":"form","explode":false},{"name":"min_discount_pct","in":"query","required":false,"description":"Minimum percent below the nearby median.","example":15,"schema":{"default":10,"type":"number","minimum":5,"maximum":90}},{"name":"max_discount_pct","in":"query","required":false,"description":"Maximum percent below the nearby median. Listings priced far below their neighbors are usually mispriced or mislabeled, so they're left out by default.","example":50,"schema":{"default":50,"type":"number","minimum":10,"maximum":95}},{"name":"limit","in":"query","required":false,"schema":{"default":25,"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":500}}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Units allowed per minute.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Units left this minute.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-Request-Units":{"description":"Units this request cost.","schema":{"type":"integer"}},"X-Quota-Limit":{"description":"Units allowed this calendar month (UTC). Absent on unlimited plans.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Units left this calendar month (UTC). Absent on unlimited plans. Reads `0` once a plan with overage is past its quota and still serving.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Seconds until the monthly quota resets. Absent on unlimited plans.","schema":{"type":"integer"}},"Deprecation":{"description":"RFC 9745. `@<unix seconds>` from when this endpoint was deprecated.","schema":{"type":"string"}},"Sunset":{"description":"RFC 8594. The date it stops working, once one is set.","schema":{"type":"string"}},"Link":{"description":"The changelog entry explaining it, as `rel=\"deprecation\"`.","schema":{"type":"string"}},"X-Resolved-City":{"description":"The covered city slug the request's `city` was resolved to, when it differs from what was sent (`city=dammam` answers for `eastern_province`). Absent when the slug was sent as is.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"listing":{"$ref":"#/components/schemas/Listing"},"comparison":{"type":"object","properties":{"median_price_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Median asking price of the nearby comparables.","example":60000},"p25_price_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"25th percentile of the nearby comparables."},"p75_price_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"75th percentile of the nearby comparables."},"percent_vs_median":{"description":"This listing's price vs that median, in percent (negative = cheaper).","example":-18.4,"type":["number","null"]},"sample_size":{"type":"integer","description":"Distinct comparable units.","example":87},"radius_m":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Search radius used."},"look_back_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"How far back comparables were observed."},"price_basis":{"type":"string","enum":["yearly_rent","sale_price"],"description":"What the `*_sar` price fields mean: `yearly_rent` (SAR per year) for rentals, `sale_price` (total SAR) for sales."},"price_source":{"type":"string","enum":["asking","registered"],"description":"Where the prices come from: `asking` = advertised asking prices from listings; `registered` = registered transactions or rent contracts. Asking prices typically sit above what is finally agreed.","example":"asking"}},"required":["median_price_sar","p25_price_sar","p75_price_sar","percent_vs_median","sample_size","radius_m","look_back_days","price_basis","price_source"],"additionalProperties":false}},"required":["listing","comparison"],"additionalProperties":false}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"],"additionalProperties":false},"example":{"data":[{"listing":{"id":128647,"url":"https://kite.sa/en/listing/128647","title":"شقة للإيجار في حي الملقا","headline":"3-bedroom apartment for rent in Al Malqa, Riyadh","description":"شقة ثلاث غرف وصالة ومطبخ راكب، الدور الثاني، قريبة من الخدمات.","description_en":"Three-bedroom apartment with a living room and fitted kitchen, second floor, close to services.","listing_type":"rent","listing_category":"residential","property_type":"apartment","price":{"yearly_sar":60000,"as_posted":{"amount":5000,"frequency":"monthly"},"previous_yearly_sar":66000,"changed_at":"2026-09-21T10:00:00.000Z","price_basis":"yearly_rent","price_source":"asking"},"financing":{"rent_now_pay_later_monthly_sar":5450,"accepts_bank_financing":true,"landlord_payment_plans":{"monthly":true,"quarterly":true,"semiannually":true}},"bedrooms":3,"bathrooms":2,"livings":1,"area_sqm":140,"floor":"2","age_years":4,"furnished":false,"amenities":["ac","kitchen","parking"],"photo_features":[{"feature":"real_photos","image_index":0},{"feature":"kitchen_installed","image_index":3}],"location":{"city":"riyadh","city_name_en":"Riyadh","neighborhood_id":12,"neighborhood_name_ar":"الملقا","neighborhood_name_en":"Al Malqa","lat":24.7869,"lng":46.6215,"street_width_m":20},"plot":{"zoning":"residential","is_corner":false,"frontage_count":1,"facing":["north"],"street_width_m":25,"street_width_source":"official","plot_area_sqm":449.1,"buildable_area_sqm":747,"buildable_far":1.66,"price_per_buildable_sqm_sar":2410,"urban_growth_phase":"1440","urban_growth_year":1440,"white_land_fee":{"band":3,"rate_pct":5,"as_of":"2025-08-26"},"last_registered_sale":{"month":"2026-08","price_sar":1850000,"price_per_sqm_sar":4111,"area_sqm":450,"registry":"Real Estate Registry","areas_agree":true,"ask_to_last_sale_ratio":0.973,"months_since":3},"registered_sale_while_listed":{"month":"2026-10","price_sar":1800000,"registry":"Real Estate Registry","ask_at_sale_sar":1950000,"areas_agree":true,"deal_to_ask_ratio":0.923,"weeks_to_sell":7},"registered_sales_count":1,"match":{"method":"plan_parcel_and_pin","confidence":0.9}},"compound_name":"Sedra","project_id":null,"images":["https://images.darak.app/listings/128647/1.webp"],"image_count":8,"advertiser":{"type":"agency","name":"مكتب الملقا للعقار","name_en":"Al Malqa Real Estate","company":"Al Malqa Real Estate Company","logo":"https://images.example.com/advertisers/al-malqa.png","fal_number":"1100012345","cr":"1010012345","ad_license":"7100232271","contact_available":true},"verified_by_source":true,"source":{"name":"aqar","listing_id":"7788123","url":"https://kite.sa/r/128647"},"also_listed_on":["bayut"],"first_seen_at":"2026-09-21T10:00:00.000Z","updated_at":"2026-09-21T10:00:00.000Z","last_seen_at":"2026-09-21T10:00:00.000Z","days_on_market":12},"comparison":{"median_price_sar":60000,"p25_price_sar":null,"p75_price_sar":null,"percent_vs_median":-18.4,"sample_size":87,"radius_m":null,"look_back_days":null,"price_basis":"yearly_rent","price_source":"asking"}}],"pagination":{"limit":25,"next_cursor":"eyJvIjoyNSwiZiI6IksweTFfU1F3d1BXSiJ9.pkFEfJUOpRbZRS279EDC4v","has_more":true,"result_window_reached":false}}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Deprecation":{"description":"RFC 9745. `@<unix seconds>` from when this endpoint was deprecated.","schema":{"type":"string"}},"Sunset":{"description":"RFC 8594. The date it stops working, once one is set.","schema":{"type":"string"}},"Link":{"description":"The changelog entry explaining it, as `rel=\"deprecation\"`.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Deprecation":{"description":"RFC 9745. `@<unix seconds>` from when this endpoint was deprecated.","schema":{"type":"string"}},"Sunset":{"description":"RFC 8594. The date it stops working, once one is set.","schema":{"type":"string"}},"Link":{"description":"The changelog entry explaining it, as `rel=\"deprecation\"`.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Deprecation":{"description":"RFC 9745. `@<unix seconds>` from when this endpoint was deprecated.","schema":{"type":"string"}},"Sunset":{"description":"RFC 8594. The date it stops working, once one is set.","schema":{"type":"string"}},"Link":{"description":"The changelog entry explaining it, as `rel=\"deprecation\"`.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Deprecation":{"description":"RFC 9745. `@<unix seconds>` from when this endpoint was deprecated.","schema":{"type":"string"}},"Sunset":{"description":"RFC 8594. The date it stops working, once one is set.","schema":{"type":"string"}},"Link":{"description":"The changelog entry explaining it, as `rel=\"deprecation\"`.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Deprecation":{"description":"RFC 9745. `@<unix seconds>` from when this endpoint was deprecated.","schema":{"type":"string"}},"Sunset":{"description":"RFC 8594. The date it stops working, once one is set.","schema":{"type":"string"}},"Link":{"description":"The changelog entry explaining it, as `rel=\"deprecation\"`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Deprecation":{"description":"RFC 9745. `@<unix seconds>` from when this endpoint was deprecated.","schema":{"type":"string"}},"Sunset":{"description":"RFC 8594. The date it stops working, once one is set.","schema":{"type":"string"}},"Link":{"description":"The changelog entry explaining it, as `rel=\"deprecation\"`.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/market/rental-yield":{"get":{"operationId":"analytics.rental_yield","summary":"Get gross rental yield","description":"Gross rental yield (median yearly asking rent ÷ median asking sale price) for one property type, over the whole city (or the requested neighborhoods) and per neighborhood, highest yield first.\n\nRent and sale medians come from the same cohort (property type, and bedrooms if given) in the same area. Neighborhoods are listed only when both sides have at least `min_sample_size` listings. Gross yield ignores vacancy, service charges, maintenance and transaction costs, and compares asking prices, not achieved rents or sale prices; use it to rank areas, not to value a property.\n\nBoth sides use the market sample: active, deduplicated listings updated in the last 30 days (`updated_at`), after the same outlier filter kite.sa uses (per-tier price fences from the median and MAD of log price, bedroom and area sanity checks, and a floor at 30% of the neighborhood median).","tags":["Analytics"],"x-scope":"analytics","x-units":75,"security":[{"apiKey":[]}],"parameters":[{"name":"city","in":"query","required":true,"description":"City slug from GET /cities. A town inside a covered region is accepted and resolved to its city (`dammam`, `khobar`, `dhahran`, `jubail` and `qatif` to `eastern_province`; `buraydah` and `unaizah` to `qassim`; `hofuf` to `al_ahsa`), as are Arabic city names. The response's `filters.city` and the `X-Resolved-City` header show the slug used.","example":"riyadh","schema":{"type":"string","pattern":"^[a-z_]+$"}},{"name":"property_type","in":"query","required":true,"description":"Required, so rents and prices of different kinds of property are never mixed.","example":"apartment","schema":{"type":"string","enum":["apartment","villa","floor","duplex","office","shop","warehouse","land","building"]}},{"name":"beds","in":"query","required":false,"description":"Exact number of bedrooms (0 = studio).","example":2,"schema":{"type":"integer","minimum":0,"maximum":20}},{"name":"neighborhood_id","in":"query","required":false,"description":"Limit to these neighborhoods (comma-separated ids). Unknown ids are a 404.","example":[1287,1301],"schema":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"integer","minimum":1,"maximum":2147483647}},"style":"form","explode":false},{"name":"min_sample_size","in":"query","required":false,"description":"Minimum listings on each side for a yield to be computed.","schema":{"default":20,"type":"integer","minimum":5,"maximum":100}}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Units allowed per minute.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Units left this minute.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-Request-Units":{"description":"Units this request cost.","schema":{"type":"integer"}},"X-Quota-Limit":{"description":"Units allowed this calendar month (UTC). Absent on unlimited plans.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Units left this calendar month (UTC). Absent on unlimited plans. Reads `0` once a plan with overage is past its quota and still serving.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Seconds until the monthly quota resets. Absent on unlimited plans.","schema":{"type":"integer"}},"X-Resolved-City":{"description":"The covered city slug the request's `city` was resolved to, when it differs from what was sent (`city=dammam` answers for `eastern_province`). Absent when the slug was sent as is.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"filters":{"type":"object","properties":{"city":{"type":"string","example":"riyadh"},"listing_type":{"anyOf":[{"type":"string","enum":["rent","sale"]},{"type":"null"}]},"listing_category":{"anyOf":[{"type":"string","enum":["residential","commercial"]},{"type":"null"}],"description":"The category applied; null when both are included."},"property_type":{"type":["string","null"]},"neighborhood_ids":{"anyOf":[{"type":"array","items":{"type":"integer"}},{"type":"null"}],"example":[12]},"beds":{"anyOf":[{"type":"integer"},{"type":"null"}]}},"required":["city","listing_type","listing_category","property_type","neighborhood_ids","beds"],"additionalProperties":false,"description":"The filters the numbers were computed for, after defaults."},"overall":{"type":"object","properties":{"median_yearly_rent_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Median yearly asking rent.","example":55000},"median_sale_price_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Median asking sale price.","example":1150000},"gross_yield_pct":{"description":"Median yearly asking rent ÷ median asking sale price × 100. Both sides are asking prices (`price_source: asking`), not achieved rents or sale prices.","example":4.78,"type":["number","null"]},"rent_sample_size":{"type":"integer","example":214},"sale_sample_size":{"type":"integer","example":214}},"required":["median_yearly_rent_sar","median_sale_price_sar","gross_yield_pct","rent_sample_size","sale_sample_size"],"additionalProperties":false,"description":"The city, or the requested neighborhoods together."},"neighborhoods":{"type":"array","items":{"type":"object","properties":{"median_yearly_rent_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Median yearly asking rent.","example":55000},"median_sale_price_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Median asking sale price.","example":1150000},"gross_yield_pct":{"description":"Median yearly asking rent ÷ median asking sale price × 100. Both sides are asking prices (`price_source: asking`), not achieved rents or sale prices.","example":4.78,"type":["number","null"]},"rent_sample_size":{"type":"integer","example":214},"sale_sample_size":{"type":"integer","example":214},"neighborhood_id":{"type":"integer"},"name_en":{"type":["string","null"]},"name_ar":{"type":["string","null"]},"town":{"$ref":"#/components/schemas/NeighborhoodTown"}},"required":["median_yearly_rent_sar","median_sale_price_sar","gross_yield_pct","rent_sample_size","sale_sample_size","neighborhood_id","name_en","name_ar","town"],"additionalProperties":false}},"price_source":{"type":"string","enum":["asking","registered"],"description":"Where the prices come from: `asking` = advertised asking prices from listings; `registered` = registered transactions or rent contracts. Asking prices typically sit above what is finally agreed.","example":"asking"},"window":{"type":"object","properties":{"updated_within_days":{"type":"integer","example":30},"from":{"type":"string","description":"Listings updated at or after this time are included (ISO 8601).","example":"2026-08-23T09:00:00.000Z"},"to":{"type":"string","description":"When the numbers were computed (ISO 8601). Results may be cached up to an hour.","example":"2026-09-22T09:00:00.000Z"}},"required":["updated_within_days","from","to"],"additionalProperties":false,"description":"The freshness window of the market sample."}},"required":["filters","overall","neighborhoods","price_source","window"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"filters":{"city":"riyadh","listing_type":"rent","listing_category":"residential","property_type":"apartment","neighborhood_ids":[12],"beds":null},"overall":{"median_yearly_rent_sar":55000,"median_sale_price_sar":1150000,"gross_yield_pct":4.78,"rent_sample_size":214,"sale_sample_size":214},"neighborhoods":[{"median_yearly_rent_sar":55000,"median_sale_price_sar":1150000,"gross_yield_pct":4.78,"rent_sample_size":214,"sale_sample_size":214,"neighborhood_id":342,"name_en":"Al Malqa","name_ar":"الملقا","town":{"name_en":"Khobar","name_ar":"الخبر"}}],"price_source":"asking","window":{"updated_within_days":30,"from":"2026-08-23T09:00:00.000Z","to":"2026-09-22T09:00:00.000Z"}}}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/market/trends":{"get":{"operationId":"analytics.trends","summary":"Get price trends","description":"Monthly asking prices over recent months (up to 36), for a city or for up to five neighborhoods (one series each): the median and quartiles for the price level, and a constant-quality price index (`price_index`) for change over time. The median is not a price index; see the methodology.\n\nComputed from Kite's listing history, not from today's listings: every listing Kite has recorded, including ones since rented, sold or removed, and every price change (the price in force at each point in time, not the current one).\n\n- `on_market` (default): a listing counts in a month if it was live at any point that month (first seen before the month ended, and still active or last seen on or after the month started), at the price it had at the end of the month, or when last seen if it went off the market earlier.\n- `new_listings`: a listing counts in the month Kite first saw it, at its first recorded asking price.\n\nListings are deduplicated across sources and pass the same outlier filter as the current market (fences are today's), but not the 30-day freshness window, which doesn't apply to history. Prices are asking prices in SAR: yearly rent for rentals (monthly, weekly and daily postings are converted to a yearly amount), total price for sales. Medians and quartiles are null when fewer than 5 listings back them; check `sample_size` before relying on a number.\n\n**The median is not a price index.** Asking prices cluster on round numbers, so a monthly median can sit on the same figure for months while prices move (Riyadh rent apartments: 45,000 SAR in every month from March to November 2026), and it moves when the mix of what is listed changes even if no price does. Use `price_index` for change over time; use the median and quartiles for the price level.\n\n`price_index` is a constant-quality (same-basket) index, 100 at `index_base_month`, the first month in the window with enough data. Listings are grouped into cells of neighborhood × property type × bedrooms (0-4, 5+, or not stated); a cell counts in a month when it has at least 5 listings, and its level is the geometric mean of their prices. Each month is linked to the previous month with a value over the cells present in both, each weighted by the smaller of its two counts, and the links are chained. A cell entering or leaving doesn't move the index, so a change in mix doesn't read as a price change. A link needs 100 matched listings (`index_sample_size`); below that the month's `price_index` is null and the next month links to the last month that has one. A series with no link that passes is null throughout. Listings without a neighborhood are left out of the index. For property types without bedrooms (land, most commercial types) a cell is neighborhood × property type, so a shift in the plot or unit sizes listed within a neighborhood can still show up in the index. With `neighborhood_id`, each neighborhood's index is built from its own cells and is often null for small neighborhoods. The index uses the same listings, prices and filters as the median, under either `basis`.\n\nHistory starts on 2026-03-09: nothing before it can be rebuilt, so you can ask for up to 36 months, but months before March 2026 come back empty with `coverage: \"no_history\"`. March 2026 itself is `history_start`: part of the month is missing, and under `new_listings` every listing already live on 2026-03-09 counts as new that month. Kite also added sources over time, so the earliest months under-cover the market and a change between months can reflect coverage as well as prices. The current month is `in_progress` (and `partial`). `change_pct` and `index_change_pct` use `complete` months only.","tags":["Analytics"],"x-scope":"analytics","x-units":75,"security":[{"apiKey":[]}],"parameters":[{"name":"city","in":"query","required":true,"description":"City slug from GET /cities. A town inside a covered region is accepted and resolved to its city (`dammam`, `khobar`, `dhahran`, `jubail` and `qatif` to `eastern_province`; `buraydah` and `unaizah` to `qassim`; `hofuf` to `al_ahsa`), as are Arabic city names. The response's `filters.city` and the `X-Resolved-City` header show the slug used.","example":"riyadh","schema":{"type":"string","pattern":"^[a-z_]+$"}},{"name":"listing_type","in":"query","required":true,"description":"`rent` (prices are yearly rent) or `sale` (prices are total price).","schema":{"type":"string","enum":["rent","sale"]}},{"name":"listing_category","in":"query","required":false,"description":"Defaults to `residential` when `property_type` is omitted, so dwellings and commercial stock are never mixed into one median. With a `property_type`, omit it to include both categories of that type.","schema":{"type":"string","enum":["residential","commercial"]}},{"name":"property_type","in":"query","required":false,"description":"One property type, see GET /enums.","example":"apartment","schema":{"type":"string","enum":["apartment","villa","floor","duplex","office","shop","warehouse","land","building"]}},{"name":"beds","in":"query","required":false,"description":"Exact number of bedrooms (0 = studio).","example":2,"schema":{"type":"integer","minimum":0,"maximum":20}},{"name":"neighborhood_id","in":"query","required":false,"description":"One series per neighborhood (comma-separated ids, up to 5). Omit for one city-wide series. Unknown ids are a 404.","example":[1287,1301],"schema":{"minItems":1,"maxItems":5,"type":"array","items":{"type":"integer","minimum":1,"maximum":2147483647}},"style":"form","explode":false},{"name":"months","in":"query","required":false,"description":"Calendar months to return, ending with the current one. Up to 36; history begins 2026-03-09, and earlier months come back with `coverage: \"no_history\"`.","schema":{"default":6,"type":"integer","minimum":2,"maximum":36}},{"name":"basis","in":"query","required":false,"description":"`on_market`: listings live during the month, at their price then. `new_listings`: listings first seen that month, at their first asking price.","schema":{"default":"on_market","type":"string","enum":["on_market","new_listings"]}}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Units allowed per minute.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Units left this minute.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-Request-Units":{"description":"Units this request cost.","schema":{"type":"integer"}},"X-Quota-Limit":{"description":"Units allowed this calendar month (UTC). Absent on unlimited plans.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Units left this calendar month (UTC). Absent on unlimited plans. Reads `0` once a plan with overage is past its quota and still serving.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Seconds until the monthly quota resets. Absent on unlimited plans.","schema":{"type":"integer"}},"X-Resolved-City":{"description":"The covered city slug the request's `city` was resolved to, when it differs from what was sent (`city=dammam` answers for `eastern_province`). Absent when the slug was sent as is.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"filters":{"type":"object","properties":{"city":{"type":"string","example":"riyadh"},"listing_type":{"anyOf":[{"type":"string","enum":["rent","sale"]},{"type":"null"}]},"listing_category":{"anyOf":[{"type":"string","enum":["residential","commercial"]},{"type":"null"}],"description":"The category applied; null when both are included."},"property_type":{"type":["string","null"]},"neighborhood_ids":{"anyOf":[{"type":"array","items":{"type":"integer"}},{"type":"null"}],"example":[12]},"beds":{"anyOf":[{"type":"integer"},{"type":"null"}]}},"required":["city","listing_type","listing_category","property_type","neighborhood_ids","beds"],"additionalProperties":false,"description":"The filters the numbers were computed for, after defaults."},"price_basis":{"type":"string","enum":["yearly_rent","sale_price"],"description":"What the `*_sar` price fields mean: `yearly_rent` (SAR per year) for rentals, `sale_price` (total SAR) for sales."},"price_source":{"type":"string","enum":["asking","registered"],"description":"Where the prices come from: `asking` = advertised asking prices from listings; `registered` = registered transactions or rent contracts. Asking prices typically sit above what is finally agreed.","example":"asking"},"basis":{"type":"string","enum":["on_market","new_listings"]},"series":{"type":"array","items":{"type":"object","properties":{"neighborhood_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Null for the city-wide series."},"name_en":{"type":["string","null"]},"name_ar":{"type":["string","null"]},"town":{"$ref":"#/components/schemas/NeighborhoodTown"},"change_pct":{"description":"Change in median from the first to the last month with `coverage: \"complete\"` that has a median, in percent. Excludes the current month and the month history began. A change in the median is not a price change (it moves with the mix of listings and sticks on round numbers); use `index_change_pct` for that.","example":2.3,"type":["number","null"]},"index_change_pct":{"description":"Change in `price_index` from the first to the last month with `coverage: \"complete\"` that has an index value, in percent (1 dp). Same months rule as `change_pct`. This is the figure to use for how much asking prices changed.","example":1.6,"type":["number","null"]},"index_base_month":{"description":"The month where `price_index` is 100 (YYYY-MM): the first month in the window with enough data. Null when the series has no index.","example":"2026-03","type":["string","null"]},"points":{"type":"array","items":{"type":"object","properties":{"month":{"type":"string","description":"YYYY-MM (UTC).","example":"2026-08"},"sample_size":{"type":"integer","example":214},"median_price_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Median asking price. A price level, not a price index: compare `price_index` across months instead.","example":45000},"p25_price_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"25th percentile."},"p75_price_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"75th percentile."},"price_index":{"description":"Constant-quality asking-price index (same basket of neighborhood × property type × bedroom cells), 100 at `index_base_month`, 1 dp. Null when fewer than 100 matched listings back the month's link.","example":101.6,"type":["number","null"]},"index_cells":{"type":"integer","description":"Cells behind `price_index`: every cell at the base month, the cells matched with the previous indexed month otherwise. Reported even when `price_index` is null.","example":502},"index_sample_size":{"type":"integer","description":"Listings behind `price_index`: all listings in cells at the base month, otherwise the matched listings in the link (each cell at the smaller of its two months' counts). A link needs at least 100.","example":38427},"partial":{"type":"boolean","description":"True for the current, unfinished month."},"coverage":{"type":"string","enum":["no_history","history_start","complete","in_progress"],"description":"How much of the month Kite's listing history covers. `no_history`: before 2026-03-09, no data exists (not zero listings). `history_start`: March 2026, only partly covered; under `new_listings` it counts the whole initial stock as new. `complete`: a finished month inside the history. `in_progress`: the current month.","example":"complete"}},"required":["month","sample_size","median_price_sar","p25_price_sar","p75_price_sar","price_index","index_cells","index_sample_size","partial","coverage"],"additionalProperties":false}}},"required":["neighborhood_id","name_en","name_ar","town","change_pct","index_change_pct","index_base_month","points"],"additionalProperties":false}},"history":{"type":"object","properties":{"starts_on":{"type":"string","description":"First day of Kite's listing history (YYYY-MM-DD).","example":"2026-03-09"},"first_complete_month":{"type":"string","description":"First month the history covers in full (YYYY-MM).","example":"2026-04"}},"required":["starts_on","first_complete_month"],"additionalProperties":false,"description":"Where the listing history behind these series begins."},"methodology":{"type":"string","description":"How the numbers were computed."}},"required":["filters","price_basis","price_source","basis","series","history","methodology"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"filters":{"city":"riyadh","listing_type":"rent","listing_category":"residential","property_type":"apartment","neighborhood_ids":[12],"beds":null},"price_basis":"yearly_rent","price_source":"asking","basis":"on_market","series":[{"neighborhood_id":null,"name_en":"Al Malqa","name_ar":"الملقا","town":{"name_en":"Khobar","name_ar":"الخبر"},"change_pct":2.3,"index_change_pct":1.6,"index_base_month":"2026-03","points":[{"month":"2026-08","sample_size":214,"median_price_sar":45000,"p25_price_sar":null,"p75_price_sar":null,"price_index":101.6,"index_cells":502,"index_sample_size":38427,"partial":true,"coverage":"complete"}]}],"history":{"starts_on":"2026-03-09","first_complete_month":"2026-04"},"methodology":"Median asking price of active listings in each month, after quality filtering. Months under the minimum sample are withheld."}}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/market/neighborhoods/compare":{"get":{"operationId":"analytics.neighborhoods_compare","summary":"Compare neighborhoods","description":"Side-by-side profile of 2 to 5 neighborhoods: price quartiles, area, price per m², amenity shares, bedroom and property-type mix, and for rentals the gross yield against the same cohort's sale prices. Neighborhoods come back in the order requested, including ones with no listings in the sample.\n\nComputed over the market sample: active, deduplicated listings updated in the last 30 days (`updated_at`), after the same outlier filter kite.sa uses (per-tier price fences from the median and MAD of log price, bedroom and area sanity checks, and a floor at 30% of the neighborhood median). Prices are asking prices in SAR: yearly rent for rentals (monthly, weekly and daily postings are converted to a yearly amount), total price for sales. Medians and quartiles are null when fewer than 5 listings back them; check `sample_size` before relying on a number.","tags":["Analytics"],"x-scope":"analytics","x-units":75,"security":[{"apiKey":[]}],"parameters":[{"name":"city","in":"query","required":true,"description":"City slug from GET /cities. A town inside a covered region is accepted and resolved to its city (`dammam`, `khobar`, `dhahran`, `jubail` and `qatif` to `eastern_province`; `buraydah` and `unaizah` to `qassim`; `hofuf` to `al_ahsa`), as are Arabic city names. The response's `filters.city` and the `X-Resolved-City` header show the slug used.","example":"riyadh","schema":{"type":"string","pattern":"^[a-z_]+$"}},{"name":"listing_type","in":"query","required":true,"description":"`rent` (prices are yearly rent) or `sale` (prices are total price).","schema":{"type":"string","enum":["rent","sale"]}},{"name":"listing_category","in":"query","required":false,"description":"Defaults to `residential` when `property_type` is omitted, so dwellings and commercial stock are never mixed into one median. With a `property_type`, omit it to include both categories of that type.","schema":{"type":"string","enum":["residential","commercial"]}},{"name":"property_type","in":"query","required":false,"description":"One property type, see GET /enums.","example":"apartment","schema":{"type":"string","enum":["apartment","villa","floor","duplex","office","shop","warehouse","land","building"]}},{"name":"beds","in":"query","required":false,"description":"Exact number of bedrooms (0 = studio).","example":2,"schema":{"type":"integer","minimum":0,"maximum":20}},{"name":"neighborhood_id","in":"query","required":true,"description":"2 to 5 comma-separated neighborhood ids from GET /cities/{city}/neighborhoods. Unknown ids are a 404.","example":[1287,1301],"schema":{"minItems":1,"maxItems":5,"type":"array","items":{"type":"integer","minimum":1,"maximum":2147483647}},"style":"form","explode":false}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Units allowed per minute.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Units left this minute.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-Request-Units":{"description":"Units this request cost.","schema":{"type":"integer"}},"X-Quota-Limit":{"description":"Units allowed this calendar month (UTC). Absent on unlimited plans.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Units left this calendar month (UTC). Absent on unlimited plans. Reads `0` once a plan with overage is past its quota and still serving.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Seconds until the monthly quota resets. Absent on unlimited plans.","schema":{"type":"integer"}},"X-Resolved-City":{"description":"The covered city slug the request's `city` was resolved to, when it differs from what was sent (`city=dammam` answers for `eastern_province`). Absent when the slug was sent as is.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"filters":{"type":"object","properties":{"city":{"type":"string","example":"riyadh"},"listing_type":{"anyOf":[{"type":"string","enum":["rent","sale"]},{"type":"null"}]},"listing_category":{"anyOf":[{"type":"string","enum":["residential","commercial"]},{"type":"null"}],"description":"The category applied; null when both are included."},"property_type":{"type":["string","null"]},"neighborhood_ids":{"anyOf":[{"type":"array","items":{"type":"integer"}},{"type":"null"}],"example":[12]},"beds":{"anyOf":[{"type":"integer"},{"type":"null"}]}},"required":["city","listing_type","listing_category","property_type","neighborhood_ids","beds"],"additionalProperties":false,"description":"The filters the numbers were computed for, after defaults."},"price_basis":{"type":"string","enum":["yearly_rent","sale_price"],"description":"What the `*_sar` price fields mean: `yearly_rent` (SAR per year) for rentals, `sale_price` (total SAR) for sales."},"price_source":{"type":"string","enum":["asking","registered"],"description":"Where the prices come from: `asking` = advertised asking prices from listings; `registered` = registered transactions or rent contracts. Asking prices typically sit above what is finally agreed.","example":"asking"},"neighborhoods":{"type":"array","items":{"type":"object","properties":{"neighborhood_id":{"type":"integer"},"name_en":{"type":"string"},"name_ar":{"type":"string"},"town":{"$ref":"#/components/schemas/NeighborhoodTown"},"sample_size":{"type":"integer","example":214},"median_price_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Median price.","example":48000},"p25_price_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"25th percentile price."},"p75_price_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"75th percentile price."},"median_area_sqm":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Median area in m², over listings that state an area."},"median_price_per_sqm_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Median of each listing's price divided by its area."},"amenity_share_pct":{"type":"object","properties":{"ac":{"description":"Percent of the neighborhood's sample.","type":["number","null"]},"parking":{"description":"Percent of the neighborhood's sample.","type":["number","null"]},"pool":{"description":"Percent of the neighborhood's sample.","type":["number","null"]},"lift":{"description":"Percent of the neighborhood's sample.","type":["number","null"]},"furnished":{"description":"Percent of the neighborhood's sample.","type":["number","null"]}},"required":["ac","parking","pool","lift","furnished"],"additionalProperties":false},"bedrooms_mix":{"type":"object","properties":{"0":{"type":"integer"},"1":{"type":"integer"},"2":{"type":"integer"},"3":{"type":"integer"},"4":{"type":"integer"},"5_plus":{"type":"integer"}},"required":["0","1","2","3","4","5_plus"],"additionalProperties":false,"description":"Listings by bedroom count."},"property_type_mix":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"integer"},"description":"Listings by property type.","example":{"apartment":120}},"median_sale_price_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Rentals only: median asking sale price of the same cohort in the neighborhood."},"sale_sample_size":{"description":"Rentals only.","example":96,"type":"integer"},"gross_yield_pct":{"description":"Rentals only: median_price_sar / median_sale_price_sar × 100.","type":["number","null"]}},"required":["neighborhood_id","name_en","name_ar","town","sample_size","median_price_sar","p25_price_sar","p75_price_sar","median_area_sqm","median_price_per_sqm_sar","amenity_share_pct","bedrooms_mix","property_type_mix"],"additionalProperties":false}},"window":{"type":"object","properties":{"updated_within_days":{"type":"integer","example":30},"from":{"type":"string","description":"Listings updated at or after this time are included (ISO 8601).","example":"2026-08-23T09:00:00.000Z"},"to":{"type":"string","description":"When the numbers were computed (ISO 8601). Results may be cached up to an hour.","example":"2026-09-22T09:00:00.000Z"}},"required":["updated_within_days","from","to"],"additionalProperties":false,"description":"The freshness window of the market sample."}},"required":["filters","price_basis","price_source","neighborhoods","window"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"filters":{"city":"riyadh","listing_type":"rent","listing_category":"residential","property_type":"apartment","neighborhood_ids":[12],"beds":null},"price_basis":"yearly_rent","price_source":"asking","neighborhoods":[{"neighborhood_id":342,"name_en":"Al Malqa","name_ar":"الملقا","town":{"name_en":"Khobar","name_ar":"الخبر"},"sample_size":214,"median_price_sar":48000,"p25_price_sar":null,"p75_price_sar":null,"median_area_sqm":null,"median_price_per_sqm_sar":null,"amenity_share_pct":{"ac":82,"parking":71,"pool":6,"lift":64,"furnished":18},"bedrooms_mix":{"0":3,"1":12,"2":24,"3":38,"4":15,"5_plus":8},"property_type_mix":{"apartment":120},"median_sale_price_sar":null,"sale_sample_size":96,"gross_yield_pct":6.4}],"window":{"updated_within_days":30,"from":"2026-08-23T09:00:00.000Z","to":"2026-09-22T09:00:00.000Z"}}}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/advertisers":{"get":{"operationId":"analytics.advertisers","summary":"List advertisers by matching listings","description":"The advertisers behind the listings a search matches: one row per advertiser, with how many matching listings they hold, their price range and where they list. Takes every filter GET /listings takes, so \"brokers with apartments above 40,000 SAR a year in north Riyadh\" is one call instead of paging the listings and grouping them yourself.\n\n**Which listings count.** The same active, deduplicated, quality-filtered listings GET /listings returns for these filters, and of those only the ones whose advertiser GET /listings would name: the ad carries a REGA licence (an advertising licence or a FAL brokerage licence) and no takedown or removal request covers it. Listings by unlicensed or unnamed advertisers are left out, so `totals.listings` is usually below GET /listings/count for the same filters.\n\n**Who is one advertiser.** Listings are grouped by the office name the ad shows (the company, or the person's name when the ad names no company), ignoring case. Kite does not merge spellings, so an office that posts under an Arabic name on one source and an English name on another appears twice. `fal_number` is the FAL licence its matching listings most often carry; an office whose agents each hold their own licence has several, counted in `fal_licences`.\n\n**Above the median.** Pass `above_median_pct` to count only listings priced more than that percentage above the median asking price of comparable listings: same city, listing type, neighborhood, property type and bedroom count, where at least 5 such listings exist. `0` means any amount above. A listing with no comparable group (no neighborhood, or too few like it) never matches. The median is taken over all quality-filtered listings of the city and listing type, not only those matching your other filters.\n\n**No phone numbers.** Contact details are not part of this response. `sample_listing_ids` are an advertiser's highest-priced matching listings; pass one to GET /listings/{id}/contact (which needs the `listings:contact` scope) or to GET /listings/batch.\n\nPrices are asking prices of active listings, in SAR; rents are yearly.","tags":["Analytics"],"x-scope":"analytics","x-units":50,"security":[{"apiKey":[]}],"parameters":[{"name":"city","in":"query","required":true,"description":"City slug from GET /cities. A town inside a covered region is accepted and resolved to its city (`dammam`, `khobar`, `dhahran`, `jubail` and `qatif` to `eastern_province`; `buraydah` and `unaizah` to `qassim`; `hofuf` to `al_ahsa`), as are Arabic city names. The response's `filters.city` and the `X-Resolved-City` header show the slug used.","example":"riyadh","schema":{"type":"string","pattern":"^[a-z_]+$"}},{"name":"listing_type","in":"query","required":true,"schema":{"type":"string","enum":["rent","sale"]}},{"name":"listing_category","in":"query","required":false,"description":"Omit for both.","schema":{"type":"string","enum":["residential","commercial"]}},{"name":"property_type","in":"query","required":false,"description":"One or more, comma-separated.","example":["apartment","villa"],"schema":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"string","enum":["apartment","villa","floor","duplex","office","shop","warehouse","land","building"]}},"style":"form","explode":false},{"name":"neighborhood_id","in":"query","required":false,"description":"Neighborhood ids from GET /cities/{city}/neighborhoods.","schema":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"integer","minimum":1,"maximum":2147483647}},"style":"form","explode":false},{"name":"beds","in":"query","required":false,"description":"Exact number of bedrooms. Exact at every value, including 5 — kite.sa's own filter treats 5 as five-or-more, so the same number returns different sets here. Use `beds_min` for a range.","schema":{"type":"integer","minimum":0,"maximum":20}},{"name":"beds_min","in":"query","required":false,"description":"Minimum number of bedrooms.","schema":{"type":"integer","minimum":0,"maximum":20}},{"name":"beds_max","in":"query","required":false,"description":"Maximum number of bedrooms.","schema":{"type":"integer","minimum":0,"maximum":20}},{"name":"bathrooms_min","in":"query","required":false,"description":"Minimum number of bathrooms.","schema":{"type":"integer","minimum":0,"maximum":20}},{"name":"price_min","in":"query","required":false,"description":"SAR. Yearly for rentals (see `price.yearly_sar`).","schema":{"type":"integer","minimum":0,"maximum":2000000000}},{"name":"price_max","in":"query","required":false,"description":"SAR. Yearly for rentals (see `price.yearly_sar`).","schema":{"type":"integer","minimum":0,"maximum":2000000000}},{"name":"area_min","in":"query","required":false,"description":"Square meters.","schema":{"type":"number","minimum":0,"maximum":10000000}},{"name":"area_max","in":"query","required":false,"description":"Square meters.","schema":{"type":"number","minimum":0,"maximum":10000000}},{"name":"furnished","in":"query","required":false,"description":"`true` matches listings confirmed furnished. `false` matches listings not confirmed furnished: those stated unfurnished and those that don't say. Omit to include all.","schema":{"type":"string","enum":["true","false"]}},{"name":"source","in":"query","required":false,"description":"Source platforms, see GET /enums. Values aren't checked against the list, so a misspelled source narrows to nothing rather than erroring.","schema":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string","pattern":"^[a-z_]+$"}},"style":"form","explode":false},{"name":"bbox","in":"query","required":false,"description":"Bounding box `west,south,east,north` in degrees (GeoJSON order).","example":"46.60,24.70,46.75,24.85","schema":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?(,-?\\d+(\\.\\d+)?){3}$"}},{"name":"updated_since","in":"query","required":false,"description":"Only listings whose `updated_at` is at or after this ISO 8601 time. Combine with `sort=updated_asc` to sync.","example":"2026-09-01T00:00:00Z","schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},{"name":"bathrooms","in":"query","required":false,"description":"Exact number of bathrooms.","schema":{"type":"integer","minimum":0,"maximum":20}},{"name":"bathrooms_max","in":"query","required":false,"description":"Maximum number of bathrooms.","schema":{"type":"integer","minimum":0,"maximum":20}},{"name":"livings_min","in":"query","required":false,"description":"Minimum number of living rooms.","schema":{"type":"integer","minimum":0,"maximum":20}},{"name":"neighborhood_id_exclude","in":"query","required":false,"description":"Exclude these neighborhoods. Ids from GET /cities/{city}/neighborhoods. Listings Kite could not place in a neighborhood are kept — unlike `neighborhood_id`, which drops them.","schema":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"integer","minimum":1,"maximum":2147483647}},"style":"form","explode":false},{"name":"q","in":"query","required":false,"description":"Free-text match on the advertiser's title and description, as posted — not on `headline`, which Kite builds for the response. Several words must all appear; `\"quote a phrase\"` to match it whole, and `|` between words for either. Sources that post no title (Aqar among them) are matched on description alone.","example":"مسبح","schema":{"type":"string","minLength":2,"maxLength":120}},{"name":"amenities","in":"query","required":false,"description":"Only listings that have all of these. See GET /enums.","example":["parking","lift"],"schema":{"minItems":1,"maxItems":11,"type":"array","items":{"type":"string","enum":["ac","kitchen","maid_room","parking","private_roof","lift","pool","gym","balcony","garden","laundry_room"]}},"style":"form","explode":false},{"name":"amenities_exclude","in":"query","required":false,"description":"Exclude listings that have any of these.","schema":{"minItems":1,"maxItems":11,"type":"array","items":{"type":"string","enum":["ac","kitchen","maid_room","parking","private_roof","lift","pool","gym","balcony","garden","laundry_room"]}},"style":"form","explode":false},{"name":"photo_features","in":"query","required":false,"description":"Only listings whose photos show all of these: `real_photos` (photos of the actual property, not renders or stock images), `kitchen_installed` (fitted kitchen cabinets), `ac_split`, `pool`, `roof_terrace`, `balcony`, `large_windows` (a living room or bedroom with large windows). Read from the listing's photos by an automated vision model and published only for features it identifies with high precision, so this is a must-have filter and nothing else: a listing whose photos don't show a feature, or that hasn't been analysed yet, simply doesn't match, and there is no way to ask for listings without a feature. Coverage is homes with photos; recently added listings may not be analysed yet.","example":["kitchen_installed","ac_split"],"schema":{"minItems":1,"maxItems":7,"type":"array","items":{"type":"string","enum":["real_photos","kitchen_installed","ac_split","pool","roof_terrace","balcony","large_windows"]}},"style":"form","explode":false},{"name":"floor","in":"query","required":false,"description":"`ground` for ground-floor listings, `upper` for any stated floor above it. The two do not partition the results: a listing whose floor the source didn't state is in neither.","schema":{"type":"string","enum":["ground","upper"]}},{"name":"source_exclude","in":"query","required":false,"description":"Exclude these source platforms, see GET /enums.","schema":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string","pattern":"^[a-z_]+$"}},"style":"form","explode":false},{"name":"max_age","in":"query","required":false,"description":"Maximum property age in years. In Riyadh the age is checked against municipal building permits from 2018 on: when the ad claims a building at least four years younger than its latest permit allows, the permit's age (the permit year plus a year to build) is used instead. A permit never makes a building younger than its ad says. Aqar records an age of 0 when the advertiser leaves it blank, so an Aqar listing at 0 counts as new only when a Riyadh permit or the ad's own text (first occupant, never lived in, newly built) backs it; otherwise its age is unknown and it doesn't match. Where an ad's own description states the building's age (\"العمر 8 سنوات\") at least three years older than its age field, or the field is empty, the description's age is used.","schema":{"type":"integer","minimum":0,"maximum":100}},{"name":"verified","in":"query","required":false,"description":"`true` for listings the source marks as verified. `false` means everything else — both listings it marked unverified and listings it said nothing about.","schema":{"type":"string","enum":["true","false"]}},{"name":"advertiser_type","in":"query","required":false,"description":"Who posted the ad, where the source says. `company` groups agencies, brokerage companies and developers; `individual` groups individual brokers and owners. Many listings match neither: their source states no category (Aqar, the largest source, states none), or names an intermediary without saying whether it is a firm or a person. So the two values together are well short of all listings; don't use this filter to size a market.","schema":{"type":"string","enum":["company","individual"]}},{"name":"compound","in":"query","required":false,"description":"Compound name, partial match.","schema":{"type":"string","minLength":2,"maxLength":120}},{"name":"in_compound","in":"query","required":false,"description":"Only listings that belong to a compound, whichever one.","schema":{"type":"string","enum":["true","false"]}},{"name":"rent_frequency","in":"query","required":false,"description":"How the rent is advertised. `price.yearly_sar` stays yearly either way; see `price.as_posted`.","schema":{"type":"string","enum":["monthly","yearly"]}},{"name":"days_on_market_min","in":"query","required":false,"description":"Days since Kite first saw the listing.","schema":{"type":"integer","minimum":0,"maximum":3650}},{"name":"days_on_market_max","in":"query","required":false,"description":"Days since Kite first saw the listing.","schema":{"type":"integer","minimum":0,"maximum":3650}},{"name":"zoning","in":"query","required":false,"description":"Only listings whose plot is zoned any of these (`plot.zoning`), comma-separated. Like every plot filter, it matches only listings with a `plot`.","example":["residential"],"schema":{"minItems":1,"maxItems":7,"type":"array","items":{"type":"string","enum":["residential","commercial","mixed","industrial","agricultural","public","other"]}},"style":"form","explode":false},{"name":"corner","in":"query","required":false,"description":"`true`: corner plots only (`plot.is_corner`); `false`: plots not on a corner.","schema":{"type":"string","enum":["true","false"]}},{"name":"street_width_min","in":"query","required":false,"description":"Minimum width in metres of the widest street the plot fronts (`plot.street_width_m`).","example":20,"schema":{"type":"number","minimum":0,"maximum":500}},{"name":"white_land_fee","in":"query","required":false,"description":"`true`: plots in a white-land fee band (`plot.white_land_fee`); `false`: plots outside every band. Bands are mapped for Riyadh only, so `false` matches nothing in other cities.","schema":{"type":"string","enum":["true","false"]}},{"name":"last_sale_within_months","in":"query","required":false,"description":"Only listings whose parcel's last registered sale (`plot.last_registered_sale`) is at most this many calendar months old (`months_since`). Land, villas and buildings only: flats, floors and duplexes have no last sale.","example":12,"schema":{"type":"integer","minimum":0,"maximum":600}},{"name":"ask_to_last_sale_max","in":"query","required":false,"description":"Sale listings only: the asking price is at most this multiple of the parcel's last registered sale, among listings whose area agrees with the deed (`plot.last_registered_sale.ask_to_last_sale_ratio`). `1.05` finds plots offered for at most 5% above what they last sold for.","example":1.05,"schema":{"type":"number","minimum":0.01,"maximum":100}},{"name":"plot_sold","in":"query","required":false,"description":"`true`: only listings whose plot registered a sale while the ad was up (`plot.registered_sale_while_listed`), which on the market means plots most likely sold already. `false`: leaves those out, and keeps every listing with no such sale on record, including those without a `plot`. Land, villas and buildings for sale.","schema":{"type":"string","enum":["true","false"]}},{"name":"above_median_pct","in":"query","required":false,"description":"Count only listings priced more than this percentage above the median of comparable listings (same neighborhood, property type and bedrooms, at least 5 listings). `0` = any amount above.","example":20,"schema":{"type":"number","minimum":0,"maximum":500}},{"name":"min_listings","in":"query","required":false,"description":"Only advertisers with at least this many matching listings.","example":5,"schema":{"default":1,"type":"integer","minimum":1,"maximum":10000}},{"name":"sort","in":"query","required":false,"description":"`listings_desc` (most matching listings first) or `median_price_desc` (highest median asking price first).","schema":{"default":"listings_desc","type":"string","enum":["listings_desc","median_price_desc"]}},{"name":"limit","in":"query","required":false,"schema":{"default":25,"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":500}}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Units allowed per minute.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Units left this minute.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-Request-Units":{"description":"Units this request cost.","schema":{"type":"integer"}},"X-Quota-Limit":{"description":"Units allowed this calendar month (UTC). Absent on unlimited plans.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Units left this calendar month (UTC). Absent on unlimited plans. Reads `0` once a plan with overage is past its quota and still serving.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Seconds until the monthly quota resets. Absent on unlimited plans.","schema":{"type":"integer"}},"X-Resolved-City":{"description":"The covered city slug the request's `city` was resolved to, when it differs from what was sent (`city=dammam` answers for `eastern_province`). Absent when the slug was sent as is.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"price_basis":{"type":"string","enum":["yearly_rent","sale_price"],"description":"What the `*_sar` price fields mean: `yearly_rent` (SAR per year) for rentals, `sale_price` (total SAR) for sales."},"price_source":{"type":"string","enum":["asking","registered"],"description":"Where the prices come from: `asking` = advertised asking prices from listings; `registered` = registered transactions or rent contracts. Asking prices typically sit above what is finally agreed.","example":"asking"},"totals":{"type":"object","properties":{"advertisers":{"type":"integer","example":412},"listings":{"type":"integer","example":9120}},"required":["advertisers","listings"],"additionalProperties":false,"description":"Across every page: advertisers with at least `min_listings` matching listings, and the listings they hold."},"advertisers":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"The office name as its ads show it most often: the company, or the person's name when the ad names no company.","example":"مكتب الملقا للعقارات"},"advertiser_types":{"type":"array","items":{"type":"string"},"description":"Advertiser categories its matching listings carry, verbatim from the sources (`agency`, `company`, `developer` and similar; see `advertiser.type` on a listing). Empty when no source states one.","example":["agency"]},"fal_number":{"description":"The REGA FAL brokerage licence its matching listings most often carry. Null when they qualify through per-ad licences only.","example":"1200012911","type":["string","null"]},"fal_licences":{"type":"integer","description":"Distinct FAL licence numbers across its matching listings.","example":3},"sources":{"type":"array","items":{"type":"string"},"description":"Source platforms its matching listings were posted on.","example":["aqar","bayut"]},"listings":{"type":"integer","description":"Its listings that match the filters.","example":42},"median_price_sar":{"type":"integer","description":"Median asking price of those listings, SAR (yearly for rentals).","example":65000},"min_price_sar":{"type":"integer","example":41000},"max_price_sar":{"type":"integer","example":180000},"top_neighborhoods":{"type":"array","items":{"type":"object","properties":{"neighborhood_id":{"type":"integer","example":77},"name_ar":{"type":"string","example":"الملقا"},"name_en":{"type":"string","example":"Al Malqa"},"listings":{"type":"integer","example":18}},"required":["neighborhood_id","name_ar","name_en","listings"],"additionalProperties":false},"description":"Up to 3 neighborhoods holding most of its matching listings, largest first."},"sample_listing_ids":{"type":"array","items":{"type":"integer"},"description":"Up to 5 of its matching listings, highest price first. Ids for GET /listings/batch or GET /listings/{id}/contact.","example":[128647,128650]}},"required":["name","advertiser_types","fal_number","fal_licences","sources","listings","median_price_sar","min_price_sar","max_price_sar","top_neighborhoods","sample_listing_ids"],"additionalProperties":false}}},"required":["price_basis","price_source","totals","advertisers"],"additionalProperties":false},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"],"additionalProperties":false},"example":{"data":{"price_basis":"yearly_rent","price_source":"asking","totals":{"advertisers":412,"listings":9120},"advertisers":[{"name":"مكتب الملقا للعقارات","advertiser_types":["agency"],"fal_number":"1200012911","fal_licences":3,"sources":["aqar","bayut"],"listings":42,"median_price_sar":65000,"min_price_sar":41000,"max_price_sar":180000,"top_neighborhoods":[{"neighborhood_id":77,"name_ar":"الملقا","name_en":"Al Malqa","listings":18}],"sample_listing_ids":[128647,128650]}]},"pagination":{"limit":25,"next_cursor":"eyJvIjoyNSwiZiI6IksweTFfU1F3d1BXSiJ9.pkFEfJUOpRbZRS279EDC4v","has_more":true,"result_window_reached":false}}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/valuations/asking-range":{"get":{"operationId":"valuations.asking_range","summary":"Check the asking price for any home","description":"The asking-price range for a home you describe, from the asking prices of similar homes nearby: like an appraiser's comparables, but for any unit, not just one listed on Kite. These figures are advertised asking prices of similar homes nearby, not achieved rents or sale prices, and not a valuation. Asking prices usually sit above what is finally agreed.\n\n**Answers.** Always HTTP 200, with `status`:\n- `estimate`: `range.low`, `range.mid` and `range.high` (25th percentile, median and 75th percentile of the comparables' asking price per m², times `area_sqm`), `confidence` `high` or `medium`.\n- `range_only`: `range.low` and `range.high` without a mid, `confidence` `low`. Use it as a bracket, not a number.\n- `insufficient_evidence`: no range. `cohort` and `comparables` still show what was found.\n\n`reasons` lists every code that applies:\n- `location_unresolved`: the neighborhood has no centre to search from (give `lat`/`lng`).\n- `insufficient_comparables`: fewer distinct units, or evidence clusters, than the cohort's calibrated floor.\n- `dispersion_too_high`: asking prices per m² vary too much to bracket the unit (coefficient of dispersion above 35%).\n- `uncalibrated_cohort`: no published calibration covers this city, type, bedroom count and listing type, so default search settings were used.\n- `neighborhood_only_location`: no point was given, so the whole neighborhood was searched.\n- `listing_type_not_calibrated`: rent only can return `estimate` for now.\n- `median_interval_unavailable`, `median_interval_too_wide`: the median is not stable enough to state.\n\n**Evidence.** Comparables have the same city, listing type, property type and bedroom count, an area within the cohort's tolerance, and passed Kite's price, bedroom, area, type and location checks. They were live or seen within the look-back, and each marketed unit counts once (duplicates across portals collapse). With `lat`/`lng` the search is a calibrated radius round the point; with only `neighborhood_id` it is the neighborhood's own listings. `furnished` narrows rentals to furnished ads (`true`) or drops them (`false`). `median_interval` is a 95% bootstrap interval of the median asking price per m², times `area_sqm`, that resamples evidence clusters (projects or ~100 m cells), not single ads. `range`, `median_interval` and `claimed_price_position` are all on that one basis.\n\n**Not used.** `age_years` and `floor` are accepted and listed in `inputs_ignored`, as is `furnished` for sales. **Registered rents** for the neighborhood are free at GET /market/registered-rents (`see_also.registered_rents`); they are not mixed into this answer.\n\n**Confidence tiers are provisional** (`methodology_version` ends in `-provisional`) until they are frozen on a published forward hold-out test.\n\nCosts 250 units a call, whatever the `status`.","tags":["Analytics"],"x-scope":"market","x-units":250,"security":[{"apiKey":[]}],"parameters":[{"name":"city","in":"query","required":true,"description":"City slug from GET /cities. A town inside a covered region is accepted and resolved to its city (`dammam`, `khobar`, `dhahran`, `jubail` and `qatif` to `eastern_province`; `buraydah` and `unaizah` to `qassim`; `hofuf` to `al_ahsa`), as are Arabic city names. The response's `filters.city` and the `X-Resolved-City` header show the slug used.","example":"riyadh","schema":{"type":"string","pattern":"^[a-z_]+$"}},{"name":"neighborhood_id","in":"query","required":false,"description":"Neighborhood id from GET /cities/{city}/neighborhoods. Give it, `lat` and `lng`, or both. Unknown ids are a 404.","example":136,"schema":{"type":"integer","minimum":1,"maximum":2147483647}},{"name":"lat","in":"query","required":false,"description":"Latitude of the home (WGS 84). Give with `lng`.","example":24.8314,"schema":{"type":"number","minimum":15,"maximum":33}},{"name":"lng","in":"query","required":false,"description":"Longitude of the home (WGS 84). Give with `lat`.","example":46.6402,"schema":{"type":"number","minimum":34,"maximum":56}},{"name":"property_type","in":"query","required":true,"description":"The home's property type.","example":"apartment","schema":{"type":"string","enum":["apartment","villa","floor","duplex"]}},{"name":"listing_type","in":"query","required":true,"description":"`rent` (yearly rent) or `sale`.","example":"rent","schema":{"type":"string","enum":["rent","sale"]}},{"name":"bedrooms","in":"query","required":true,"description":"Bedrooms; comparables must match exactly.","example":3,"schema":{"type":"integer","minimum":0,"maximum":20}},{"name":"area_sqm","in":"query","required":true,"description":"Built-up area of the home in m².","example":150,"schema":{"type":"number","minimum":10,"maximum":100000}},{"name":"furnished","in":"query","required":false,"description":"Rentals: `true` compares with furnished ads only, `false` leaves furnished ads out. Ignored for sales.","schema":{"type":"string","enum":["true","false"]}},{"name":"age_years","in":"query","required":false,"description":"Building age in years. Accepted, not used yet (see `inputs_ignored`).","schema":{"type":"integer","minimum":0,"maximum":100}},{"name":"floor","in":"query","required":false,"description":"Floor the unit is on (0 = ground). Accepted, not used yet.","schema":{"type":"integer","minimum":-3,"maximum":200}},{"name":"claimed_price","in":"query","required":false,"description":"A price to position against the comparables (asked, offered or applied for): SAR per year for rent, total SAR for sale.","example":65000,"schema":{"type":"integer","minimum":1,"maximum":2000000000}}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Units allowed per minute.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Units left this minute.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-Request-Units":{"description":"Units this request cost.","schema":{"type":"integer"}},"X-Quota-Limit":{"description":"Units allowed this calendar month (UTC). Absent on unlimited plans.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Units left this calendar month (UTC). Absent on unlimited plans. Reads `0` once a plan with overage is past its quota and still serving.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Seconds until the monthly quota resets. Absent on unlimited plans.","schema":{"type":"integer"}},"X-Resolved-City":{"description":"The covered city slug the request's `city` was resolved to, when it differs from what was sent (`city=dammam` answers for `eastern_province`). Absent when the slug was sent as is.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string","enum":["estimate","range_only","insufficient_evidence"],"description":"`estimate`, `range_only` or `insufficient_evidence`. See the endpoint description.","example":"estimate"},"reasons":{"type":"array","items":{"type":"string","enum":["location_unresolved","insufficient_comparables","dispersion_too_high","uncalibrated_cohort","neighborhood_only_location","listing_type_not_calibrated","median_interval_unavailable","median_interval_too_wide"]},"description":"Why the answer is not a higher tier; empty for an unqualified estimate.","example":[]},"basis":{"type":"string","const":"asking_prices","description":"Every figure is built from advertised asking prices."},"notice":{"type":"string","const":"These figures are advertised asking prices of similar homes nearby, not achieved rents or sale prices, and not a valuation. Asking prices usually sit above what is finally agreed.","description":"Show this wherever you show the figures."},"price_basis":{"type":"string","enum":["yearly_rent","sale_price"],"description":"What the `*_sar` price fields mean: `yearly_rent` (SAR per year) for rentals, `sale_price` (total SAR) for sales."},"range":{"anyOf":[{"type":"object","properties":{"low":{"type":"integer","description":"25th percentile, SAR.","example":58000},"mid":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Median, SAR. Null unless `status` is `estimate`.","example":63000},"high":{"type":"integer","description":"75th percentile, SAR.","example":69000}},"required":["low","mid","high"],"additionalProperties":false},{"type":"null"}],"description":"Comparables' asking price per m² percentiles times `area_sqm`. Null for `insufficient_evidence`."},"median_interval":{"anyOf":[{"type":"object","properties":{"low":{"type":"integer","example":60000},"high":{"type":"integer","example":66000}},"required":["low","high"],"additionalProperties":false},{"type":"null"}],"description":"95% cluster-bootstrap interval of the comparables' median asking price per m², times `area_sqm` (the basis of `range`). Null without a range."},"confidence":{"anyOf":[{"type":"string","enum":["high","medium","low"]},{"type":"null"}],"description":"`high` or `medium` with an estimate, `low` with `range_only`, null otherwise.","example":"medium"},"claimed_price_position":{"anyOf":[{"type":"object","properties":{"claimed_price_sar":{"type":"integer","example":65000},"percentile":{"type":"number","description":"Mid-rank percentile of `claimed_price` ÷ `area_sqm` among the comparables' asking prices per m².","example":62.5},"diff_from_median_pct":{"type":"number","description":"`claimed_price` vs the median asking price per m² times `area_sqm` (`range.mid`'s statistic), in percent.","example":3.2},"outside_median_interval":{"type":"boolean","description":"True when `claimed_price` lies outside `median_interval`."}},"required":["claimed_price_sar","percentile","diff_from_median_pct","outside_median_interval"],"additionalProperties":false},{"type":"null"}],"description":"Null without `claimed_price` or without a range."},"location":{"anyOf":[{"type":"object","properties":{"lat":{"type":"number"},"lng":{"type":"number"},"point_source":{"type":"string","enum":["given","neighborhood_centroid"],"description":"Whether the point is yours or the neighborhood's centre."},"neighborhood":{"anyOf":[{"type":"object","properties":{"id":{"type":"integer","example":136},"name_en":{"type":"string","example":"Al Narjis"},"name_ar":{"type":"string","example":"النرجس"}},"required":["id","name_en","name_ar"],"additionalProperties":false},{"type":"null"}],"description":"The neighborhood the home is in, given or inferred; null if none."}},"required":["lat","lng","point_source","neighborhood"],"additionalProperties":false},{"type":"null"}],"description":"Null when the location could not be resolved."},"cohort":{"anyOf":[{"type":"object","properties":{"search":{"type":"string","enum":["radius","neighborhood"],"description":"A radius round the point, or the neighborhood's listings."},"radius_m":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Search radius; null for a neighborhood search.","example":2000},"look_back_days":{"type":"integer","example":90},"area_tolerance_pct":{"type":"integer","example":20},"furnished":{"description":"The furnishing filter applied; null for none.","type":["boolean","null"]},"calibrated":{"type":"boolean","description":"Whether a published calibration set the search, rather than defaults."},"calibration_version":{"type":"string","example":"global-2026-07-16"},"distinct_units":{"type":"integer","example":23},"evidence_clusters":{"type":"integer","example":14},"live_units":{"type":"integer","description":"Comparables still advertised."},"delisted_units":{"type":"integer","description":"Comparables taken down within the look-back."},"dispersion_pct":{"description":"Coefficient of dispersion of asking price per m², in percent.","example":14.2,"type":["number","null"]}},"required":["search","radius_m","look_back_days","area_tolerance_pct","furnished","calibrated","calibration_version","distinct_units","evidence_clusters","live_units","delisted_units","dispersion_pct"],"additionalProperties":false},{"type":"null"}],"description":"What was searched and found. Null when the location is unresolved."},"comparables":{"type":"array","items":{"type":"object","properties":{"listing_id":{"type":"integer","description":"Kite id of the ad observed, which may since have been delisted or be a duplicate of another ad. GET /listings/{id} serves it only while it is live and is the listing Kite shows for its duplicate group; otherwise that call returns 404."},"price_sar":{"type":"integer"},"area_sqm":{"type":"number"},"price_per_sqm_sar":{"type":"integer"},"bedrooms":{"type":"integer"},"distance_m":{"type":"integer"},"days_since_seen":{"type":"integer"},"live":{"type":"boolean"}},"required":["listing_id","price_sar","area_sqm","price_per_sqm_sar","bedrooms","distance_m","days_since_seen","live"],"additionalProperties":false},"description":"Up to 15 comparables, nearest first."},"inputs_ignored":{"type":"array","items":{"type":"string","enum":["age_years","floor","furnished"]},"description":"Inputs you sent that did not affect this answer.","example":[]},"methodology_version":{"type":"string","example":"asking-range-v1-provisional"},"see_also":{"type":"object","properties":{"registered_rents":{"description":"Path, relative to the API server, of REGA's registered rents for this city (and neighborhood) at GET /market/registered-rents, free on every plan. Null for sales.","example":"/market/registered-rents?city=riyadh&neighborhood_id=136&property_type=apartment","type":["string","null"]}},"required":["registered_rents"],"additionalProperties":false,"description":"Related free data, not part of this answer."}},"required":["status","reasons","basis","notice","price_basis","range","median_interval","confidence","claimed_price_position","location","cohort","comparables","inputs_ignored","methodology_version","see_also"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"status":"estimate","reasons":[],"basis":"asking_prices","notice":"These figures are advertised asking prices of similar homes nearby, not achieved rents or sale prices, and not a valuation. Asking prices usually sit above what is finally agreed.","price_basis":"yearly_rent","range":{"low":58000,"mid":63000,"high":69000},"median_interval":{"low":60000,"high":66000},"confidence":"medium","claimed_price_position":{"claimed_price_sar":65000,"percentile":62.5,"diff_from_median_pct":3.2,"outside_median_interval":true},"location":{"lat":24.8136,"lng":46.6097,"point_source":"given","neighborhood":{"id":136,"name_en":"Al Narjis","name_ar":"النرجس"}},"cohort":{"search":"radius","radius_m":2000,"look_back_days":90,"area_tolerance_pct":20,"furnished":true,"calibrated":true,"calibration_version":"global-2026-07-16","distinct_units":23,"evidence_clusters":14,"live_units":0,"delisted_units":0,"dispersion_pct":14.2},"comparables":[{"listing_id":128647,"price_sar":0,"area_sqm":145,"price_per_sqm_sar":0,"bedrooms":0,"distance_m":0,"days_since_seen":0,"live":true}],"inputs_ignored":[],"methodology_version":"asking-range-v1-provisional","see_also":{"registered_rents":"/market/registered-rents?city=riyadh&neighborhood_id=136&property_type=apartment"}}}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/transactions":{"get":{"operationId":"transactions.search","summary":"Search registered deals","description":"Individual registered sale deals in one city: month, neighborhood, land-use class, area, price and price per m². The Ministry of Justice's quarterly open data, plus notary deals newer than its latest quarter and Real Estate Registry deals (`source`). Newest month first; paginate with `cursor`.\n\nEach deal has a `source`. `moj_open_data`: the Ministry of Justice's quarterly open data. `moj_notary`: a notary-registered deal dated after the latest open-data quarter; when that quarter is published, the open-data copy replaces it under the same `id`. `real_estate_registry`: a deal registered with the Real Estate Registry (السجل العقاري), which the open data never carries. Notary deals are a partial set (from a few percent to about two thirds of a city's notary deals), so count them as a sample, not the market. Registry deals are every deal the Registry registered from July 2023 to 19 October 2026 (REGA's own feed), and a partial set after it (about half of Riyadh's Registry deals). Their `land_use` is the parcel's zoning (`land_use_basis: zoning`), not MOJ's deed class, and they say what changed hands (`property_type`).\n\nMOJ classes each open-data deal by land use (`residential` = سكني, `commercial` = تجاري, …), not by what stands on the plot. Residential-class deals are mostly vacant land: 97.5% carry no building type and the median plot is about 500 m². Read prices per m² as land prices, not home prices.\n\nDates are served to the month. MOJ publishes the day, but a neighbourhood and a day single out one deal in 23% of cases against 1% for a neighbourhood and a month, so the day is withheld, and rows within a month are in a fixed order unrelated to the date. Plan, parcel and deed numbers and reference numbers are never served. Quarters published with misaligned columns (2020-Q2, 2023-Q1) are excluded. Prices are as registered and unfiltered: very low prices per m² usually mean a partial-share or family transfer, so filter with `price_per_sqm_min` or `market_sales_only` for market comparables.\n\n**Token prices.** A deal registered at zero, under 10,000 SAR in total, or under 10 SAR per m² of its area is a transfer without a market price: a gift, an inheritance split, a grant (most of them are 1,000 SAR land deeds), never a sale. GET /transactions serves these rows with `token_price: true`; the statistics leave them out unless `include_token_prices=true` (until 2026-11-20 they counted every deal priced above zero; see the changelog). They are about 3% of open-data deals and under 1% of Registry deals, but in some towns a fifth of the land deals: Afif's residential median per m² doubles without them.\n\n**Property type.** Only deals from the registers say what changed hands (`property_type`: vacant land, a flat, a floor, a residential building, …); open-data deals never do, because MOJ's files class a deal by land use, not by property. So `property_type` matches notary and Real Estate Registry deals with a recorded type and leaves every open-data deal out, and its coverage is theirs, which differs by city and period:\n\n- **Notary deals** (`moj_notary`) are served only for the months after the latest open-data quarter (from July 2026 as of November 2026). When MOJ publishes that quarter, its open-data copies, which carry no type, replace them, so notary deals drop out of a property-type figure as the open data catches up. In Riyadh city notaries register almost no sales since its move to the Registry.\n- **Real Estate Registry deals** (`real_estate_registry`) stay, and start where the Registry did: Riyadh July 2023; Eastern Province, Madinah, Makkah and Qassim in 2024; Al Ahsa, Jeddah, Al Kharj, Hafar Al Batin and Hail in 2025; Arar, Tabuk and most northern towns in early 2026. Many towns in the south and west (Taif, Jazan, Najran, Khamis Mushait, Abha) have no Registry deals, so their typed deals are notary deals only.\n- Notary deals are a partial set (from a few percent to about two thirds of a town's notary deals); Registry deals are all of them through 19 October 2026 and a partial set after it (about half of Riyadh's). So a property-type figure is a sample, not the market, and most of all for the latest months. `floor` and `residential_building` come almost entirely from the Registry; the Registry files most villa sales as a residential building, so `villa` and `house` are rare.\n\nThe months from November 2025 held about 89,000 typed deals in all: about 44,000 in Riyadh, 12,000 in Eastern Province, 7,700 in Qassim, 5,500 in Jeddah, 1,700 to 2,800 each in Madinah, Makkah, Al Ahsa and Hail, about 1,100 in Al Kharj, and under 1,000 in every other city.\n\n**Cities whose sales moved to the Real Estate Registry.** The open data carries notary deals only. Riyadh city moved to the Registry district by district from 2024 and wholly on 19 May 2026; Hail and nine Eastern Province cities (Dammam, Khobar, Dhahran, Qatif, Jubail, Khafji, Al-Bayda, Ras Tanura, Abqaiq) on 22 September 2026. Open-data figures there are flagged `notary_only` from Riyadh 2024-Q1, Eastern Province 2025-Q1 and Hail 2026-Q1, and open-data deals after each move are not served. After the move, figures are built on Registry deals instead, flagged `registry_sample` (`coverage.registry_sample_from_quarter`): residential-zoned deals only, every Registry deal through 19 October 2026, a partial feed after it (about half of Riyadh's Registry deals; its vacant-land median per m² was 4% below the whole Registry's in September 2026), never `complete`, so no change is computed across the switch. In Riyadh, 2026-Q2 joins open-data deals through 18 May with Registry deals from 19 May (`incomplete`) and 2026-Q3 is Registry deals alone. Other Riyadh-region towns are unaffected. `coverage.notes` states each city's dates. Registry deals from before a city's move are served as rows too.\n\nFree on every plan and costs no units. Rows and figures from the open data (`source: moj_open_data`) are Saudi government open data, served at no charge under the ODC Attribution License: not Kite Data, and our API terms put no restriction on reusing or redistributing them; keep the `attribution` notice with them wherever you show or pass them on. Deals with another `source` come from the registers themselves, not the open-data files, so that licence does not cover them; `attribution.other_sources` names them.","tags":["Registered transactions"],"x-scope":"reference","x-units":0,"x-units-note":"Free on every plan: Saudi open data, served at no charge","security":[{"apiKey":[]}],"parameters":[{"name":"city","in":"query","required":true,"description":"City slug from GET /cities. A town inside a covered region is accepted and resolved to its city (`dammam`, `khobar`, `dhahran`, `jubail` and `qatif` to `eastern_province`; `buraydah` and `unaizah` to `qassim`; `hofuf` to `al_ahsa`), as are Arabic city names. The response's `filters.city` and the `X-Resolved-City` header show the slug used.","example":"riyadh","schema":{"type":"string","pattern":"^[a-z_]+$"}},{"name":"neighborhood_id","in":"query","required":false,"description":"Up to 50 neighborhood ids from GET /cities/{city}/neighborhoods, comma-separated. Deals Kite could not place in a neighborhood are left out when this is set.","example":[25],"schema":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"integer","minimum":1,"maximum":2147483647}},"style":"form","explode":false},{"name":"land_use","in":"query","required":false,"description":"One or more classes, comma-separated. Omit for all.","schema":{"minItems":1,"maxItems":6,"type":"array","items":{"type":"string","enum":["residential","commercial","agricultural","industrial","mixed_use","other"],"description":"Land-use class: `residential` (سكني), `commercial` (تجاري), `agricultural` (زراعي), `industrial` (صناعي), `mixed_use` (سكني تجاري), `other` (أخرى). `other` also covers unclassified deals. MOJ's deed class on open-data deals; the parcel's zoning on deals from the registers (see `land_use_basis`).","example":"residential"}},"style":"form","explode":false},{"name":"source","in":"query","required":false,"description":"One or more sources, comma-separated. Omit for all; `moj_open_data` alone returns the open data only, as before 2026-11-17.","schema":{"minItems":1,"maxItems":3,"type":"array","items":{"type":"string","enum":["moj_open_data","moj_notary","real_estate_registry"]}},"style":"form","explode":false},{"name":"property_type","in":"query","required":false,"description":"What changed hands, one or more, comma-separated. Matches only deals whose register recorded a type (notary and Real Estate Registry deals), never open-data deals; see **Property type** above. Omit for all deals.","schema":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"string","enum":["vacant_land","agricultural_land","apartment","floor","villa","house","residential_building","mixed_use_building","commercial","other"]}},"style":"form","explode":false},{"name":"market_sales_only","in":"query","required":false,"description":"`true` leaves out what the property-type statistics leave out: deals at a token price (`token_price` on GET /transactions rows), deals the register flags as a token price, deals of more than one property (whose price and area are totals), and `apartment` and `floor` deals under 500 SAR per m², which are transfers rather than sales. Open-data deals carry no register flag, so for them it drops deals at a token price and deals of more than one property. Combined with `property_type` and a month range, the rows are the deals behind GET /market/transactions' figures for that type.","schema":{"type":"string","enum":["true","false"]}},{"name":"month_from","in":"query","required":false,"description":"First month to include, `YYYY-MM`.","example":"2026-03","schema":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"}},{"name":"month_to","in":"query","required":false,"description":"Last month to include, `YYYY-MM`.","example":"2026-03","schema":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"}},{"name":"price_min","in":"query","required":false,"description":"Total price, SAR.","schema":{"type":"integer","minimum":0,"maximum":100000000000}},{"name":"price_max","in":"query","required":false,"description":"Total price, SAR.","schema":{"type":"integer","minimum":0,"maximum":100000000000}},{"name":"area_min","in":"query","required":false,"description":"m².","schema":{"type":"number","minimum":0,"maximum":1000000000}},{"name":"area_max","in":"query","required":false,"description":"m².","schema":{"type":"number","minimum":0,"maximum":1000000000}},{"name":"price_per_sqm_min","in":"query","required":false,"description":"SAR per m².","schema":{"type":"number","minimum":0,"maximum":10000000}},{"name":"price_per_sqm_max","in":"query","required":false,"description":"SAR per m².","schema":{"type":"number","minimum":0,"maximum":10000000}},{"name":"sort","in":"query","required":false,"description":"`month_desc` (newest month first) or `month_asc`.","schema":{"default":"month_desc","type":"string","enum":["month_desc","month_asc"]}},{"name":"limit","in":"query","required":false,"schema":{"default":25,"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":500}}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Units allowed per minute.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Units left this minute.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-Request-Units":{"description":"Units this request cost.","schema":{"type":"integer"}},"X-Quota-Limit":{"description":"Units allowed this calendar month (UTC). Absent on unlimited plans.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Units left this calendar month (UTC). Absent on unlimited plans. Reads `0` once a plan with overage is past its quota and still serving.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Seconds until the monthly quota resets. Absent on unlimited plans.","schema":{"type":"integer"}},"X-Resolved-City":{"description":"The covered city slug the request's `city` was resolved to, when it differs from what was sent (`city=dammam` answers for `eastern_province`). Absent when the slug was sent as is.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Transaction"}},"pagination":{"$ref":"#/components/schemas/Pagination"},"price_basis":{"type":"string","enum":["yearly_rent","sale_price"],"description":"What the `*_sar` price fields mean: `yearly_rent` (SAR per year) for rentals, `sale_price` (total SAR) for sales."},"price_source":{"type":"string","enum":["asking","registered"],"description":"Where the prices come from: `asking` = advertised asking prices from listings; `registered` = registered transactions or rent contracts. Asking prices typically sit above what is finally agreed.","example":"asking"},"coverage":{"$ref":"#/components/schemas/TransactionCoverage"},"attribution":{"$ref":"#/components/schemas/TransactionAttribution"}},"required":["data","pagination","price_basis","price_source","coverage","attribution"],"additionalProperties":false},"example":{"data":[{"id":"txn_4f1c9a0b7e2d5c8a1b3e","month":"2026-03","source":"moj_open_data","source_quarter":"2026-Q1","city":"riyadh","city_name_ar":"الرياض","district_name_ar":"النرجس","neighborhood":{"id":25,"name_ar":"النرجس","name_en":"Al Narjis","town":{"name_en":"Khobar","name_ar":"الخبر"}},"land_use":"residential","land_use_ar":"سكني","land_use_basis":"moj_class","property_type":"vacant_land","area_sqm":400,"price_sar":1150000,"price_per_sqm_sar":2875,"property_count":1,"token_price":false}],"pagination":{"limit":25,"next_cursor":"eyJvIjoyNSwiZiI6IksweTFfU1F3d1BXSiJ9.pkFEfJUOpRbZRS279EDC4v","has_more":true,"result_window_reached":false},"price_basis":"yearly_rent","price_source":"asking","coverage":{"city":"riyadh","first_deal_date":"2020-01-01","last_deal_date":"2026-06-30","latest_quarter":"2026-Q2","complete_through_quarter":"2026-Q1","notary_only_from_quarter":"2024-Q1","registry_sample_from_quarter":"2026-Q3","excluded_quarters":[{"quarter":"2023-Q1","reason":"Different schema: property classes and prices do not match the archive."}],"notes":["Riyadh city figures cover notary-registered deals only."]},"attribution":{"notice":"Contains information from \"الصفقات العقارية\" (Real estate transactions, Ministry of Justice, open.data.gov.sa; links in `datasets`), which is made available under the ODC Attribution License, as adapted by the Open Data License of the Kingdom of Saudi Arabia.","license":{"name":"Saudi Open Data License v2.0 (an adaptation of the Open Data Commons Attribution License)","url":"https://open.data.gov.sa/en/pages/policies/license","base_license":"Open Data Commons Attribution License v1.0 (ODC-By)","base_license_url":"https://opendatacommons.org/licenses/by/1-0/"},"datasets":[{"source":"rega_rent_index","title":"الصفقات العقارية","title_en":"Real estate transactions","publisher":"Ministry of Justice","urls":["https://open.data.gov.sa/en/datasets"]}],"quarters":[{"quarter":"2026-Q1","url":"https://open.data.gov.sa/en/datasets"}],"modifications":"Aggregated by neighborhood and period; implausible prices removed.","other_sources":[{"source":"moj_notary","publisher":"Real Estate Registry (السجل العقاري)","title_en":"Sale deals registered with the Real Estate Registry","note":"Not from the open-data files, so the open-data licence notice does not cover these rows."}]}}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/market/transactions":{"get":{"operationId":"market.transactions","summary":"Registered deal statistics","description":"Deal counts and median, 25th and 75th percentile price per m² and total price, per quarter and land-use class, for a city, a set of neighborhoods combined (`group_by=city` with `neighborhood_id`), or each neighborhood (`group_by=neighborhood`). Computed from the Ministry of Justice's registered sale deals (open data), so `price_source` is `registered`.\n\nNotary deals newer than the open data (GET /transactions `source: moj_notary`) are not counted, being a partial set. In cities whose sales moved to the Real Estate Registry, cells after the move are built on Registry deals (below), classed by the parcel's zoning and residential only.\n\nMOJ classes each open-data deal by land use (`residential` = سكني, `commercial` = تجاري, …), not by what stands on the plot. Residential-class deals are mostly vacant land: 97.5% carry no building type and the median plot is about 500 m². Read prices per m² as land prices, not home prices.\n\nQuarters are calendar quarters of the registration date in Saudi time. Cells under `min_sample_size` deals keep their count and drop their prices. City-level cells include deals Kite could not place in a neighborhood; neighborhood cells don't. Per-neighborhood grouping over a whole city spans at most 8 quarters per call. Check `coverage` and each cell's `coverage_flag` before comparing quarters.\n\n**By property type.** With `property_type`, the figures are built from the deals that record what changed hands instead (notary and Real Estate Registry deals, never the open data), one cell per quarter and type, pooling every zoning (`land_use` null; the `land_use` parameter still narrows the zoning). Only market sales count: deals at a token price (`token_price` on GET /transactions rows), deals the register flags as a token price, deals of more than one property (whose price and area are totals), and `apartment` and `floor` deals under 500 SAR per m², which are transfers rather than sales. Each type also gets a `window_totals` row pooling the whole window, the figure to quote where quarters are thin. Every such figure is a sample (`complete: false`, `coverage_flag: registry_sample`). Without `quarter_from` and `quarter_to` the window is the current quarter and the three before it, which is what the website's city and neighbourhood pages show for flats and floors (`window_totals` with `min_sample_size=10`, rounded to the thousand). `coverage` describes the open-data figures, not these.\n\n**Token prices.** A deal registered at zero, under 10,000 SAR in total, or under 10 SAR per m² of its area is a transfer without a market price: a gift, an inheritance split, a grant (most of them are 1,000 SAR land deeds), never a sale. GET /transactions serves these rows with `token_price: true`; the statistics leave them out unless `include_token_prices=true` (until 2026-11-20 they counted every deal priced above zero; see the changelog). They are about 3% of open-data deals and under 1% of Registry deals, but in some towns a fifth of the land deals: Afif's residential median per m² doubles without them.\n\n**Property type.** Only deals from the registers say what changed hands (`property_type`: vacant land, a flat, a floor, a residential building, …); open-data deals never do, because MOJ's files class a deal by land use, not by property. So `property_type` matches notary and Real Estate Registry deals with a recorded type and leaves every open-data deal out, and its coverage is theirs, which differs by city and period:\n\n- **Notary deals** (`moj_notary`) are served only for the months after the latest open-data quarter (from July 2026 as of November 2026). When MOJ publishes that quarter, its open-data copies, which carry no type, replace them, so notary deals drop out of a property-type figure as the open data catches up. In Riyadh city notaries register almost no sales since its move to the Registry.\n- **Real Estate Registry deals** (`real_estate_registry`) stay, and start where the Registry did: Riyadh July 2023; Eastern Province, Madinah, Makkah and Qassim in 2024; Al Ahsa, Jeddah, Al Kharj, Hafar Al Batin and Hail in 2025; Arar, Tabuk and most northern towns in early 2026. Many towns in the south and west (Taif, Jazan, Najran, Khamis Mushait, Abha) have no Registry deals, so their typed deals are notary deals only.\n- Notary deals are a partial set (from a few percent to about two thirds of a town's notary deals); Registry deals are all of them through 19 October 2026 and a partial set after it (about half of Riyadh's). So a property-type figure is a sample, not the market, and most of all for the latest months. `floor` and `residential_building` come almost entirely from the Registry; the Registry files most villa sales as a residential building, so `villa` and `house` are rare.\n\nThe months from November 2025 held about 89,000 typed deals in all: about 44,000 in Riyadh, 12,000 in Eastern Province, 7,700 in Qassim, 5,500 in Jeddah, 1,700 to 2,800 each in Madinah, Makkah, Al Ahsa and Hail, about 1,100 in Al Kharj, and under 1,000 in every other city.\n\n**Cities whose sales moved to the Real Estate Registry.** The open data carries notary deals only. Riyadh city moved to the Registry district by district from 2024 and wholly on 19 May 2026; Hail and nine Eastern Province cities (Dammam, Khobar, Dhahran, Qatif, Jubail, Khafji, Al-Bayda, Ras Tanura, Abqaiq) on 22 September 2026. Open-data figures there are flagged `notary_only` from Riyadh 2024-Q1, Eastern Province 2025-Q1 and Hail 2026-Q1, and open-data deals after each move are not served. After the move, figures are built on Registry deals instead, flagged `registry_sample` (`coverage.registry_sample_from_quarter`): residential-zoned deals only, every Registry deal through 19 October 2026, a partial feed after it (about half of Riyadh's Registry deals; its vacant-land median per m² was 4% below the whole Registry's in September 2026), never `complete`, so no change is computed across the switch. In Riyadh, 2026-Q2 joins open-data deals through 18 May with Registry deals from 19 May (`incomplete`) and 2026-Q3 is Registry deals alone. Other Riyadh-region towns are unaffected. `coverage.notes` states each city's dates.\n\nFree on every plan and costs no units. Rows and figures from the open data (`source: moj_open_data`) are Saudi government open data, served at no charge under the ODC Attribution License: not Kite Data, and our API terms put no restriction on reusing or redistributing them; keep the `attribution` notice with them wherever you show or pass them on. Deals with another `source` come from the registers themselves, not the open-data files, so that licence does not cover them; `attribution.other_sources` names them.","tags":["Registered transactions"],"x-scope":"reference","x-units":0,"x-units-note":"Free on every plan: Saudi open data, served at no charge","security":[{"apiKey":[]}],"parameters":[{"name":"city","in":"query","required":true,"description":"City slug from GET /cities. A town inside a covered region is accepted and resolved to its city (`dammam`, `khobar`, `dhahran`, `jubail` and `qatif` to `eastern_province`; `buraydah` and `unaizah` to `qassim`; `hofuf` to `al_ahsa`), as are Arabic city names. The response's `filters.city` and the `X-Resolved-City` header show the slug used.","example":"riyadh","schema":{"type":"string","pattern":"^[a-z_]+$"}},{"name":"neighborhood_id","in":"query","required":false,"description":"Up to 50 neighborhood ids from GET /cities/{city}/neighborhoods, comma-separated. Deals Kite could not place in a neighborhood are left out when this is set.","example":[25],"schema":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"integer","minimum":1,"maximum":2147483647}},"style":"form","explode":false},{"name":"group_by","in":"query","required":false,"description":"`city`: one cell per quarter and class. `neighborhood`: one per neighborhood too.","schema":{"default":"city","type":"string","enum":["city","neighborhood"]}},{"name":"land_use","in":"query","required":false,"description":"Classes to include, comma-separated. Omit for all; each class is its own cell. With `property_type`, the zonings to keep, pooled into one cell per type.","schema":{"minItems":1,"maxItems":6,"type":"array","items":{"type":"string","enum":["residential","commercial","agricultural","industrial","mixed_use","other"],"description":"Land-use class: `residential` (سكني), `commercial` (تجاري), `agricultural` (زراعي), `industrial` (صناعي), `mixed_use` (سكني تجاري), `other` (أخرى). `other` also covers unclassified deals. MOJ's deed class on open-data deals; the parcel's zoning on deals from the registers (see `land_use_basis`).","example":"residential"}},"style":"form","explode":false},{"name":"property_type","in":"query","required":false,"description":"What changed hands, one or more, comma-separated; each type is its own cell. Builds the figures from notary and Real Estate Registry deals that record a type instead of the open data (see **By property type**). Omit for land-use statistics.","schema":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"string","enum":["vacant_land","agricultural_land","apartment","floor","villa","house","residential_building","mixed_use_building","commercial","other"]}},"style":"form","explode":false},{"name":"quarter_from","in":"query","required":false,"description":"First quarter, `YYYY-Qn`.","example":"2026-Q1","schema":{"type":"string","pattern":"^\\d{4}-Q[1-4]$"}},{"name":"quarter_to","in":"query","required":false,"description":"Last quarter, `YYYY-Qn`. Defaults to the city's latest published quarter.","example":"2026-Q1","schema":{"type":"string","pattern":"^\\d{4}-Q[1-4]$"}},{"name":"min_sample_size","in":"query","required":false,"description":"Cells with fewer deals than this report their count but no prices. At least 5.","schema":{"default":5,"type":"integer","minimum":5,"maximum":1000}},{"name":"include_token_prices","in":"query","required":false,"description":"`true` counts deals at a token price too (zero, under 10,000 SAR, or under 10 SAR per m²; see **Token prices**). Omitted or `false`, they are left out, as they are no sales.","schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Units allowed per minute.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Units left this minute.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-Request-Units":{"description":"Units this request cost.","schema":{"type":"integer"}},"X-Quota-Limit":{"description":"Units allowed this calendar month (UTC). Absent on unlimited plans.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Units left this calendar month (UTC). Absent on unlimited plans. Reads `0` once a plan with overage is past its quota and still serving.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Seconds until the monthly quota resets. Absent on unlimited plans.","schema":{"type":"integer"}},"X-Resolved-City":{"description":"The covered city slug the request's `city` was resolved to, when it differs from what was sent (`city=dammam` answers for `eastern_province`). Absent when the slug was sent as is.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"filters":{"type":"object","properties":{"city":{"type":"string"},"neighborhood_ids":{"anyOf":[{"type":"array","items":{"type":"integer"}},{"type":"null"}]},"group_by":{"type":"string","enum":["city","neighborhood"]},"land_use":{"anyOf":[{"type":"array","items":{"type":"string","enum":["residential","commercial","agricultural","industrial","mixed_use","other"],"description":"Land-use class: `residential` (سكني), `commercial` (تجاري), `agricultural` (زراعي), `industrial` (صناعي), `mixed_use` (سكني تجاري), `other` (أخرى). `other` also covers unclassified deals. MOJ's deed class on open-data deals; the parcel's zoning on deals from the registers (see `land_use_basis`).","example":"residential"}},{"type":"null"}]},"property_type":{"anyOf":[{"type":"array","items":{"type":"string","enum":["vacant_land","agricultural_land","apartment","floor","villa","house","residential_building","mixed_use_building","commercial","other"]}},{"type":"null"}]},"include_token_prices":{"type":"boolean"}},"required":["city","neighborhood_ids","group_by","land_use","property_type","include_token_prices"],"additionalProperties":false},"price_basis":{"type":"string","enum":["yearly_rent","sale_price"],"description":"What the `*_sar` price fields mean: `yearly_rent` (SAR per year) for rentals, `sale_price` (total SAR) for sales."},"price_source":{"type":"string","enum":["asking","registered"],"description":"Where the prices come from: `asking` = advertised asking prices from listings; `registered` = registered transactions or rent contracts. Asking prices typically sit above what is finally agreed.","example":"asking"},"window":{"type":"object","properties":{"quarter_from":{"type":"string","example":"2024-Q3"},"quarter_to":{"type":"string","example":"2026-Q2"}},"required":["quarter_from","quarter_to"],"additionalProperties":false},"min_sample_size":{"type":"integer"},"cells":{"type":"array","items":{"type":"object","properties":{"quarter":{"type":"string","example":"2026-Q1"},"period_start":{"type":"string","example":"2026-01-01"},"neighborhood":{"anyOf":[{"$ref":"#/components/schemas/TransactionNeighborhood"},{"type":"null"}],"description":"Null for city-level cells (`group_by=city`)."},"land_use":{"anyOf":[{"type":"string","enum":["residential","commercial","agricultural","industrial","mixed_use","other"],"description":"Land-use class: `residential` (سكني), `commercial` (تجاري), `agricultural` (زراعي), `industrial` (صناعي), `mixed_use` (سكني تجاري), `other` (أخرى). `other` also covers unclassified deals. MOJ's deed class on open-data deals; the parcel's zoning on deals from the registers (see `land_use_basis`).","example":"residential"},{"type":"null"}],"description":"The cell's land-use class. Null on property-type cells (`property_type` set), which pool every zoning."},"property_type":{"anyOf":[{"type":"string","enum":["vacant_land","agricultural_land","apartment","floor","villa","house","residential_building","mixed_use_building","commercial","other"]},{"type":"null"}],"description":"What changed hands, on cells asked for with the `property_type` parameter; null on land-use cells.","example":null},"deal_count":{"type":"integer","example":1163},"suppressed":{"type":"boolean","description":"True when `deal_count` is under `min_sample_size`; prices are then null."},"complete":{"type":"boolean","description":"False for quarters past the city's `coverage.complete_through_quarter`."},"coverage_flag":{"$ref":"#/components/schemas/TransactionCoverageFlag"},"median_price_per_sqm_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"example":2828},"p25_price_per_sqm_sar":{"anyOf":[{"type":"integer"},{"type":"null"}]},"p75_price_per_sqm_sar":{"anyOf":[{"type":"integer"},{"type":"null"}]},"price_per_sqm_sample_size":{"type":"integer","description":"Deals with an area, the base of the per-m² figures."},"median_price_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"example":1150000},"p25_price_sar":{"anyOf":[{"type":"integer"},{"type":"null"}]},"p75_price_sar":{"anyOf":[{"type":"integer"},{"type":"null"}]},"median_area_sqm":{"anyOf":[{"type":"integer"},{"type":"null"}],"example":400}},"required":["quarter","period_start","neighborhood","land_use","property_type","deal_count","suppressed","complete","coverage_flag","median_price_per_sqm_sar","p25_price_per_sqm_sar","p75_price_per_sqm_sar","price_per_sqm_sample_size","median_price_sar","p25_price_sar","p75_price_sar","median_area_sqm"],"additionalProperties":false}},"window_totals":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"neighborhood":{"anyOf":[{"$ref":"#/components/schemas/TransactionNeighborhood"},{"type":"null"}],"description":"Null for city-level totals (`group_by=city`)."},"property_type":{"type":"string","enum":["vacant_land","agricultural_land","apartment","floor","villa","house","residential_building","mixed_use_building","commercial","other"],"example":"apartment"},"first_month":{"type":"string","description":"Month of the earliest deal counted, `YYYY-MM`.","example":"2026-03"},"last_month":{"type":"string","description":"Month of the latest deal counted, `YYYY-MM`.","example":"2026-11"},"deal_count":{"type":"integer","example":1955},"suppressed":{"type":"boolean","description":"True when `deal_count` is under `min_sample_size`; prices are then null."},"median_price_per_sqm_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"example":3505},"p25_price_per_sqm_sar":{"anyOf":[{"type":"integer"},{"type":"null"}]},"p75_price_per_sqm_sar":{"anyOf":[{"type":"integer"},{"type":"null"}]},"price_per_sqm_sample_size":{"type":"integer"},"median_price_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"example":601000},"p25_price_sar":{"anyOf":[{"type":"integer"},{"type":"null"}]},"p75_price_sar":{"anyOf":[{"type":"integer"},{"type":"null"}]},"median_area_sqm":{"anyOf":[{"type":"integer"},{"type":"null"}],"example":175},"sources":{"type":"array","items":{"type":"string","enum":["moj_notary","real_estate_registry"]},"description":"The registers whose deals the figure counts."}},"required":["neighborhood","property_type","first_month","last_month","deal_count","suppressed","median_price_per_sqm_sar","p25_price_per_sqm_sar","p75_price_per_sqm_sar","price_per_sqm_sample_size","median_price_sar","p25_price_sar","p75_price_sar","median_area_sqm","sources"],"additionalProperties":false}},{"type":"null"}],"description":"With `property_type`: one row per type (and neighborhood, with `group_by=neighborhood`) pooling every quarter of the window. Null without `property_type`."},"coverage":{"$ref":"#/components/schemas/TransactionCoverage"},"attribution":{"$ref":"#/components/schemas/TransactionAttribution"}},"required":["filters","price_basis","price_source","window","min_sample_size","cells","window_totals","coverage","attribution"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"filters":{"city":"riyadh","neighborhood_ids":[342],"group_by":"city","land_use":["residential"],"property_type":["vacant_land"],"include_token_prices":true},"price_basis":"yearly_rent","price_source":"asking","window":{"quarter_from":"2024-Q3","quarter_to":"2026-Q2"},"min_sample_size":5,"cells":[{"quarter":"2026-Q1","period_start":"2026-01-01","neighborhood":{"id":25,"name_ar":"النرجس","name_en":"Al Narjis","town":{"name_en":"Khobar","name_ar":"الخبر"}},"land_use":"residential","property_type":null,"deal_count":1163,"suppressed":true,"complete":true,"coverage_flag":"full","median_price_per_sqm_sar":2828,"p25_price_per_sqm_sar":null,"p75_price_per_sqm_sar":null,"price_per_sqm_sample_size":180,"median_price_sar":1150000,"p25_price_sar":null,"p75_price_sar":null,"median_area_sqm":400}],"window_totals":[{"neighborhood":{"id":25,"name_ar":"النرجس","name_en":"Al Narjis","town":{"name_en":"Khobar","name_ar":"الخبر"}},"property_type":"apartment","first_month":"2026-03","last_month":"2026-11","deal_count":1955,"suppressed":true,"median_price_per_sqm_sar":3505,"p25_price_per_sqm_sar":null,"p75_price_per_sqm_sar":null,"price_per_sqm_sample_size":180,"median_price_sar":601000,"p25_price_sar":null,"p75_price_sar":null,"median_area_sqm":175,"sources":["moj_notary"]}],"coverage":{"city":"riyadh","first_deal_date":"2020-01-01","last_deal_date":"2026-06-30","latest_quarter":"2026-Q2","complete_through_quarter":"2026-Q1","notary_only_from_quarter":"2024-Q1","registry_sample_from_quarter":"2026-Q3","excluded_quarters":[{"quarter":"2023-Q1","reason":"Different schema: property classes and prices do not match the archive."}],"notes":["Riyadh city figures cover notary-registered deals only."]},"attribution":{"notice":"Contains information from \"الصفقات العقارية\" (Real estate transactions, Ministry of Justice, open.data.gov.sa; links in `datasets`), which is made available under the ODC Attribution License, as adapted by the Open Data License of the Kingdom of Saudi Arabia.","license":{"name":"Saudi Open Data License v2.0 (an adaptation of the Open Data Commons Attribution License)","url":"https://open.data.gov.sa/en/pages/policies/license","base_license":"Open Data Commons Attribution License v1.0 (ODC-By)","base_license_url":"https://opendatacommons.org/licenses/by/1-0/"},"datasets":[{"source":"rega_rent_index","title":"الصفقات العقارية","title_en":"Real estate transactions","publisher":"Ministry of Justice","urls":["https://open.data.gov.sa/en/datasets"]}],"quarters":[{"quarter":"2026-Q1","url":"https://open.data.gov.sa/en/datasets"}],"modifications":"Aggregated by neighborhood and period; implausible prices removed.","other_sources":[{"source":"moj_notary","publisher":"Real Estate Registry (السجل العقاري)","title_en":"Sale deals registered with the Real Estate Registry","note":"Not from the open-data files, so the open-data licence notice does not cover these rows."}]}}}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/market/land-prices":{"get":{"operationId":"market.land_prices","summary":"Land prices per m²","description":"Median registered price per m² of land plots, per quarter, for a city, for each of up to 20 neighborhoods (`neighborhood_id`), or for every neighborhood in the city in one call (`group_by=neighborhood` without `neighborhood_id`, over at most 12 quarters), with quarter-on-quarter and year-on-year change. From the Ministry of Justice's registered sale deals (open data): `price_source` is `registered`.\n\nIn cities whose sales moved to the Real Estate Registry, residential points after the move are built on Registry deals of vacant land on residential-zoned parcels (below); commercial points have no Registry counterpart and end at the move.\n\nMOJ classes each open-data deal by land use (`residential` = سكني, `commercial` = تجاري, …), not by what stands on the plot. Residential-class deals are mostly vacant land: 97.5% carry no building type and the median plot is about 500 m². Read prices per m² as land prices, not home prices. This endpoint serves that land reading on purpose. `land_use` picks residential (default) or commercial plots.\n\nThe city-wide median is taken over whatever plots sold that quarter, so it moves with the mix of neighborhoods as well as with prices; for trend, per-neighborhood series are the like-for-like reading. Changes are only computed between complete quarters that both clear `min_sample_size`.\n\n**Token prices.** A deal registered at zero, under 10,000 SAR in total, or under 10 SAR per m² of its area is a transfer without a market price: a gift, an inheritance split, a grant (most of them are 1,000 SAR land deeds), never a sale. GET /transactions serves these rows with `token_price: true`; the statistics leave them out unless `include_token_prices=true` (until 2026-11-20 they counted every deal priced above zero; see the changelog). They are about 3% of open-data deals and under 1% of Registry deals, but in some towns a fifth of the land deals: Afif's residential median per m² doubles without them.\n\n**Cities whose sales moved to the Real Estate Registry.** The open data carries notary deals only. Riyadh city moved to the Registry district by district from 2024 and wholly on 19 May 2026; Hail and nine Eastern Province cities (Dammam, Khobar, Dhahran, Qatif, Jubail, Khafji, Al-Bayda, Ras Tanura, Abqaiq) on 22 September 2026. Open-data figures there are flagged `notary_only` from Riyadh 2024-Q1, Eastern Province 2025-Q1 and Hail 2026-Q1, and open-data deals after each move are not served. After the move, figures are built on Registry deals instead, flagged `registry_sample` (`coverage.registry_sample_from_quarter`): residential-zoned deals only, every Registry deal through 19 October 2026, a partial feed after it (about half of Riyadh's Registry deals; its vacant-land median per m² was 4% below the whole Registry's in September 2026), never `complete`, so no change is computed across the switch. In Riyadh, 2026-Q2 joins open-data deals through 18 May with Registry deals from 19 May (`incomplete`) and 2026-Q3 is Registry deals alone. Other Riyadh-region towns are unaffected. `coverage.notes` states each city's dates.\n\nFree on every plan and costs no units. Rows and figures from the open data (`source: moj_open_data`) are Saudi government open data, served at no charge under the ODC Attribution License: not Kite Data, and our API terms put no restriction on reusing or redistributing them; keep the `attribution` notice with them wherever you show or pass them on. Deals with another `source` come from the registers themselves, not the open-data files, so that licence does not cover them; `attribution.other_sources` names them.","tags":["Registered transactions"],"x-scope":"reference","x-units":0,"x-units-note":"Free on every plan: Saudi open data, served at no charge","security":[{"apiKey":[]}],"parameters":[{"name":"city","in":"query","required":true,"description":"City slug from GET /cities. A town inside a covered region is accepted and resolved to its city (`dammam`, `khobar`, `dhahran`, `jubail` and `qatif` to `eastern_province`; `buraydah` and `unaizah` to `qassim`; `hofuf` to `al_ahsa`), as are Arabic city names. The response's `filters.city` and the `X-Resolved-City` header show the slug used.","example":"riyadh","schema":{"type":"string","pattern":"^[a-z_]+$"}},{"name":"neighborhood_id","in":"query","required":false,"description":"Up to 20 neighborhood ids from GET /cities/{city}/neighborhoods, comma-separated. Deals Kite could not place in a neighborhood are left out when this is set.","example":[25],"schema":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"integer","minimum":1,"maximum":2147483647}},"style":"form","explode":false},{"name":"group_by","in":"query","required":false,"description":"`city`: one city-wide series. `neighborhood`: one series per neighborhood, for the ids in `neighborhood_id`, or for every neighborhood with registered deals in the city when it is omitted. Defaults to `neighborhood` when `neighborhood_id` is given, `city` otherwise.","schema":{"type":"string","enum":["city","neighborhood"]}},{"name":"land_use","in":"query","required":false,"description":"`residential` (سكني, the default) or `commercial` (تجاري) plots.","schema":{"default":"residential","type":"string","enum":["residential","commercial"]}},{"name":"quarter_from","in":"query","required":false,"description":"First quarter, `YYYY-Qn`.","example":"2026-Q1","schema":{"type":"string","pattern":"^\\d{4}-Q[1-4]$"}},{"name":"quarter_to","in":"query","required":false,"description":"Last quarter, `YYYY-Qn`. Defaults to the city's latest published quarter.","example":"2026-Q1","schema":{"type":"string","pattern":"^\\d{4}-Q[1-4]$"}},{"name":"min_sample_size","in":"query","required":false,"description":"Cells with fewer deals than this report their count but no prices. At least 5.","schema":{"default":5,"type":"integer","minimum":5,"maximum":1000}},{"name":"include_token_prices","in":"query","required":false,"description":"`true` counts deals at a token price too (zero, under 10,000 SAR, or under 10 SAR per m²; see **Token prices**). Omitted or `false`, they are left out, as they are no sales.","schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Units allowed per minute.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Units left this minute.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-Request-Units":{"description":"Units this request cost.","schema":{"type":"integer"}},"X-Quota-Limit":{"description":"Units allowed this calendar month (UTC). Absent on unlimited plans.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Units left this calendar month (UTC). Absent on unlimited plans. Reads `0` once a plan with overage is past its quota and still serving.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Seconds until the monthly quota resets. Absent on unlimited plans.","schema":{"type":"integer"}},"X-Resolved-City":{"description":"The covered city slug the request's `city` was resolved to, when it differs from what was sent (`city=dammam` answers for `eastern_province`). Absent when the slug was sent as is.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"filters":{"type":"object","properties":{"city":{"type":"string"},"neighborhood_ids":{"anyOf":[{"type":"array","items":{"type":"integer"}},{"type":"null"}]},"group_by":{"type":"string","enum":["city","neighborhood"]},"land_use":{"type":"string","enum":["residential","commercial"]},"include_token_prices":{"type":"boolean"}},"required":["city","neighborhood_ids","group_by","land_use","include_token_prices"],"additionalProperties":false},"asset":{"type":"string","const":"land","description":"What the prices are for: land plots, not built homes."},"price_basis":{"type":"string","enum":["yearly_rent","sale_price"],"description":"What the `*_sar` price fields mean: `yearly_rent` (SAR per year) for rentals, `sale_price` (total SAR) for sales."},"price_source":{"type":"string","enum":["asking","registered"],"description":"Where the prices come from: `asking` = advertised asking prices from listings; `registered` = registered transactions or rent contracts. Asking prices typically sit above what is finally agreed.","example":"asking"},"window":{"type":"object","properties":{"quarter_from":{"type":"string","example":"2024-Q3"},"quarter_to":{"type":"string","example":"2026-Q2"}},"required":["quarter_from","quarter_to"],"additionalProperties":false},"min_sample_size":{"type":"integer"},"series":{"type":"array","items":{"type":"object","properties":{"neighborhood":{"anyOf":[{"$ref":"#/components/schemas/TransactionNeighborhood"},{"type":"null"}],"description":"Null for the city-wide series."},"points":{"type":"array","items":{"type":"object","properties":{"quarter":{"type":"string","example":"2026-Q1"},"period_start":{"type":"string","example":"2026-01-01"},"deal_count":{"type":"integer","example":212},"suppressed":{"type":"boolean"},"complete":{"type":"boolean"},"coverage_flag":{"$ref":"#/components/schemas/TransactionCoverageFlag"},"median_price_per_sqm_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"example":3450},"p25_price_per_sqm_sar":{"anyOf":[{"type":"integer"},{"type":"null"}]},"p75_price_per_sqm_sar":{"anyOf":[{"type":"integer"},{"type":"null"}]},"median_plot_area_sqm":{"anyOf":[{"type":"integer"},{"type":"null"}],"example":450},"change_qoq_pct":{"description":"Change in the median per m² from the previous quarter, in percent. Null unless both quarters are complete and unsuppressed.","example":2.4,"type":["number","null"]},"change_yoy_pct":{"description":"Change from the same quarter a year earlier, in percent, on the same terms.","example":11.8,"type":["number","null"]}},"required":["quarter","period_start","deal_count","suppressed","complete","coverage_flag","median_price_per_sqm_sar","p25_price_per_sqm_sar","p75_price_per_sqm_sar","median_plot_area_sqm","change_qoq_pct","change_yoy_pct"],"additionalProperties":false}},"latest":{"anyOf":[{"type":"object","properties":{"quarter":{"type":"string","example":"2026-Q1"},"period_start":{"type":"string","example":"2026-01-01"},"deal_count":{"type":"integer","example":212},"suppressed":{"type":"boolean"},"complete":{"type":"boolean"},"coverage_flag":{"$ref":"#/components/schemas/TransactionCoverageFlag"},"median_price_per_sqm_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"example":3450},"p25_price_per_sqm_sar":{"anyOf":[{"type":"integer"},{"type":"null"}]},"p75_price_per_sqm_sar":{"anyOf":[{"type":"integer"},{"type":"null"}]},"median_plot_area_sqm":{"anyOf":[{"type":"integer"},{"type":"null"}],"example":450},"change_qoq_pct":{"description":"Change in the median per m² from the previous quarter, in percent. Null unless both quarters are complete and unsuppressed.","example":2.4,"type":["number","null"]},"change_yoy_pct":{"description":"Change from the same quarter a year earlier, in percent, on the same terms.","example":11.8,"type":["number","null"]}},"required":["quarter","period_start","deal_count","suppressed","complete","coverage_flag","median_price_per_sqm_sar","p25_price_per_sqm_sar","p75_price_per_sqm_sar","median_plot_area_sqm","change_qoq_pct","change_yoy_pct"],"additionalProperties":false},{"type":"null"}],"description":"The most recent complete, unsuppressed quarter."}},"required":["neighborhood","points","latest"],"additionalProperties":false}},"coverage":{"$ref":"#/components/schemas/TransactionCoverage"},"attribution":{"$ref":"#/components/schemas/TransactionAttribution"}},"required":["filters","asset","price_basis","price_source","window","min_sample_size","series","coverage","attribution"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"filters":{"city":"riyadh","neighborhood_ids":[342],"group_by":"city","land_use":"residential","include_token_prices":true},"asset":"land","price_basis":"yearly_rent","price_source":"asking","window":{"quarter_from":"2024-Q3","quarter_to":"2026-Q2"},"min_sample_size":5,"series":[{"neighborhood":{"id":25,"name_ar":"النرجس","name_en":"Al Narjis","town":{"name_en":"Khobar","name_ar":"الخبر"}},"points":[{"quarter":"2026-Q1","period_start":"2026-01-01","deal_count":212,"suppressed":true,"complete":true,"coverage_flag":"full","median_price_per_sqm_sar":3450,"p25_price_per_sqm_sar":null,"p75_price_per_sqm_sar":null,"median_plot_area_sqm":450,"change_qoq_pct":2.4,"change_yoy_pct":11.8}],"latest":{"quarter":"2026-Q1","period_start":"2026-01-01","deal_count":212,"suppressed":true,"complete":true,"coverage_flag":"full","median_price_per_sqm_sar":3450,"p25_price_per_sqm_sar":null,"p75_price_per_sqm_sar":null,"median_plot_area_sqm":450,"change_qoq_pct":2.4,"change_yoy_pct":11.8}}],"coverage":{"city":"riyadh","first_deal_date":"2020-01-01","last_deal_date":"2026-06-30","latest_quarter":"2026-Q2","complete_through_quarter":"2026-Q1","notary_only_from_quarter":"2024-Q1","registry_sample_from_quarter":"2026-Q3","excluded_quarters":[{"quarter":"2023-Q1","reason":"Different schema: property classes and prices do not match the archive."}],"notes":["Riyadh city figures cover notary-registered deals only."]},"attribution":{"notice":"Contains information from \"الصفقات العقارية\" (Real estate transactions, Ministry of Justice, open.data.gov.sa; links in `datasets`), which is made available under the ODC Attribution License, as adapted by the Open Data License of the Kingdom of Saudi Arabia.","license":{"name":"Saudi Open Data License v2.0 (an adaptation of the Open Data Commons Attribution License)","url":"https://open.data.gov.sa/en/pages/policies/license","base_license":"Open Data Commons Attribution License v1.0 (ODC-By)","base_license_url":"https://opendatacommons.org/licenses/by/1-0/"},"datasets":[{"source":"rega_rent_index","title":"الصفقات العقارية","title_en":"Real estate transactions","publisher":"Ministry of Justice","urls":["https://open.data.gov.sa/en/datasets"]}],"quarters":[{"quarter":"2026-Q1","url":"https://open.data.gov.sa/en/datasets"}],"modifications":"Aggregated by neighborhood and period; implausible prices removed.","other_sources":[{"source":"moj_notary","publisher":"Real Estate Registry (السجل العقاري)","title_en":"Sale deals registered with the Real Estate Registry","note":"Not from the open-data files, so the open-data licence notice does not cover these rows."}]}}}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects":{"get":{"operationId":"projects.search","summary":"Search projects","description":"Off-plan and newly built residential and commercial projects from Saudi developers and portals, one entry per project (copies from several sources are merged). Prices are developer-advertised purchase prices in SAR. Paginate with `cursor`.","tags":["Off-plan projects"],"x-scope":"projects","x-units":"1 per result asked for with `limit` (default 25), up to your plan's page size","security":[{"apiKey":[]}],"parameters":[{"name":"city","in":"query","required":false,"description":"Omit for all cities.","example":"riyadh","schema":{"type":"string","pattern":"^[a-z_]+$"}},{"name":"neighborhood_id","in":"query","required":false,"description":"Neighborhood ids from GET /cities/{city}/neighborhoods. Only projects mapped to a neighborhood match.","schema":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"integer","minimum":1,"maximum":2147483647}},"style":"form","explode":false},{"name":"developer","in":"query","required":false,"description":"Exact developer name, as returned by GET /developers.","example":"Retal Urban Development","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"status","in":"query","required":false,"description":"One or more, comma-separated.","example":["available","under_construction"],"schema":{"minItems":1,"maxItems":6,"type":"array","items":{"type":"string","enum":["available","coming_soon","not_started","under_construction","completed","sold_out"]}},"style":"form","explode":false},{"name":"project_type","in":"query","required":false,"schema":{"type":"string","enum":["off_plan","ready"]}},{"name":"listing_category","in":"query","required":false,"description":"Omit for both.","schema":{"type":"string","enum":["residential","commercial"]}},{"name":"features","in":"query","required":false,"description":"Only projects with all of these, see GET /enums.","example":["pool","gym"],"schema":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string","pattern":"^[a-z_]+$"}},"style":"form","explode":false},{"name":"banks","in":"query","required":false,"description":"Only projects financed by all of these, see GET /enums.","schema":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string","pattern":"^[a-z_]+$"}},"style":"form","explode":false},{"name":"q","in":"query","required":false,"description":"Matches project or developer name (Arabic or English), case-insensitive.","example":"Sedra","schema":{"type":"string","minLength":2,"maxLength":100}},{"name":"price_min","in":"query","required":false,"description":"Minimum starting price, SAR. Projects without a published price are excluded.","schema":{"type":"integer","minimum":0,"maximum":2000000000}},{"name":"price_max","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":2000000000}},{"name":"handover_from","in":"query","required":false,"description":"Only projects whose `timeline.handover_date` is on or after this day (`YYYY-MM-DD`). Projects with no stated handover date are excluded.","example":"2027-01-01","schema":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$"}},{"name":"handover_to","in":"query","required":false,"description":"Only projects whose `timeline.handover_date` is on or before this day.","example":"2028-12-31","schema":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$"}},{"name":"licensed","in":"query","required":false,"description":"`true`: only projects with a REGA off-plan sale licence on record (`offplan_licence_no`). `false`: only those without one. Omit for both.","schema":{"type":"string","enum":["true","false"]}},{"name":"sort","in":"query","required":false,"description":"`updated_desc` (most recently refreshed), `price_asc`/`price_desc` (by starting price, projects without one last).","schema":{"default":"updated_desc","type":"string","enum":["updated_desc","price_asc","price_desc"]}},{"name":"limit","in":"query","required":false,"schema":{"default":25,"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":500}}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Units allowed per minute.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Units left this minute.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-Request-Units":{"description":"Units this request cost.","schema":{"type":"integer"}},"X-Quota-Limit":{"description":"Units allowed this calendar month (UTC). Absent on unlimited plans.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Units left this calendar month (UTC). Absent on unlimited plans. Reads `0` once a plan with overage is past its quota and still serving.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Seconds until the monthly quota resets. Absent on unlimited plans.","schema":{"type":"integer"}},"X-Resolved-City":{"description":"The covered city slug the request's `city` was resolved to, when it differs from what was sent (`city=dammam` answers for `eastern_province`). Absent when the slug was sent as is.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":4812},"url":{"description":"The project's page on kite.sa.","type":["string","null"]},"name_ar":{"example":"مشروع سدرة","type":["string","null"]},"name_en":{"example":"Sedra","type":["string","null"]},"developer":{"description":"Developer name as published. Pass as `developer` to filter; see GET /developers.","example":"Retal Urban Development","type":["string","null"]},"status":{"anyOf":[{"type":"string","enum":["available","coming_soon","not_started","under_construction","completed","sold_out"]},{"type":"null"}],"description":"Sales/construction status. Null when the source doesn't say."},"project_type":{"anyOf":[{"type":"string","enum":["off_plan","ready"]},{"type":"null"}],"description":"`off_plan` (sold before completion) or `ready`. Null when unknown."},"listing_category":{"type":"string","example":"residential"},"location":{"type":"object","properties":{"city":{"description":"City slug (see GET /cities).","example":"riyadh","type":["string","null"]},"city_name_en":{"example":"Riyadh","type":["string","null"]},"neighborhood_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"See GET /cities/{city}/neighborhoods. Not every project is mapped to a neighborhood yet."},"neighborhood_name_ar":{"type":["string","null"]},"neighborhood_name_en":{"type":["string","null"]},"lat":{"type":["number","null"]},"lng":{"type":["number","null"]},"precision":{"anyOf":[{"type":"string","enum":["exact","neighborhood"]},{"type":"null"}],"description":"How far lat/lng can be trusted. `exact`: a point a source published for the project. `neighborhood`: the centre of the project's neighborhood, because no source gave a point (the project is somewhere in that neighborhood). Null when lat/lng is null.","example":"exact"}},"required":["city","city_name_en","neighborhood_id","neighborhood_name_ar","neighborhood_name_en","lat","lng","precision"],"additionalProperties":false},"price":{"type":"object","properties":{"starting_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Lowest advertised purchase price in SAR (a sale price, not a rent).","example":850000},"from_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Lower end of the advertised price range, SAR."},"to_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Upper end of the advertised price range, SAR."}},"required":["starting_sar","from_sar","to_sar"],"additionalProperties":false,"description":"Developer-advertised purchase prices in SAR (total price, not yearly). Null when not published or implausibly low."},"area_sqm":{"type":"object","properties":{"min":{"type":["number","null"]},"max":{"type":["number","null"]}},"required":["min","max"],"additionalProperties":false,"description":"Advertised unit size range in square meters."},"advertised_unit_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Total units in the project, as the developer advertises it."},"linked_units":{"type":"object","properties":{"count":{"type":"integer","description":"Active listings on Kite linked to this project (see GET /projects/{id}/units). Usually far fewer than `advertised_unit_count`."},"bedrooms_min":{"anyOf":[{"type":"integer"},{"type":"null"}]},"bedrooms_max":{"anyOf":[{"type":"integer"},{"type":"null"}]}},"required":["count","bedrooms_min","bedrooms_max"],"additionalProperties":false},"cover_image":{"description":"First image on Kite's CDN, if mirrored.","type":["string","null"]},"timeline":{"type":"object","properties":{"handover_date":{"description":"Expected handover (completion) date, `YYYY-MM-DD`, as the source states it. A date that moves between snapshots is a slip; see GET /projects/{id}/availability.","example":"2027-12-31","type":["string","null"]},"construction_progress_pct":{"description":"Construction progress in percent (0-100), as the source states it (on Wafi, the registry's achievement rate).","example":34.5,"type":["number","null"]},"sources":{"type":"object","properties":{"handover_date":{"description":"Source slug the value was read from; null when the value is null.","example":"wafi","type":["string","null"]},"construction_progress_pct":{"description":"Source slug the value was read from; null when the value is null.","example":"wafi","type":["string","null"]}},"required":["handover_date","construction_progress_pct"],"additionalProperties":false,"description":"Where each value came from (a source slug, see GET /enums)."}},"required":["handover_date","construction_progress_pct","sources"],"additionalProperties":false,"description":"Handover date and construction progress, from whichever copy of the project states them (the REGA off-plan registry, Wafi, first). Null where no source says."},"offplan_licence_no":{"description":"REGA off-plan sale licence number, where the project is on the off-plan registry (Wafi). GET /projects/{id} has the licence's dates and registered facts.","example":"1100012345","type":["string","null"]},"last_seen_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","example":"2026-09-21T10:00:00.000Z"},{"type":"null"}],"description":"Last time Kite refreshed the project from its source."}},"required":["id","url","name_ar","name_en","developer","status","project_type","listing_category","location","price","area_sqm","advertised_unit_count","linked_units","cover_image","timeline","offplan_licence_no","last_seen_at"],"additionalProperties":false}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"],"additionalProperties":false},"example":{"data":[{"id":4812,"url":"https://kite.sa/en/projects/4812","name_ar":"مشروع سدرة","name_en":"Sedra","developer":"Retal Urban Development","status":"available","project_type":"off_plan","listing_category":"residential","location":{"city":"riyadh","city_name_en":"Riyadh","neighborhood_id":null,"neighborhood_name_ar":"الملقا","neighborhood_name_en":"Al Malqa","lat":24.8136,"lng":46.6097,"precision":"exact"},"price":{"starting_sar":850000,"from_sar":null,"to_sar":null},"area_sqm":{"min":95,"max":220},"advertised_unit_count":null,"linked_units":{"count":18,"bedrooms_min":null,"bedrooms_max":null},"cover_image":"https://images.example.com/projects/4812/cover.jpg","timeline":{"handover_date":"2027-12-31","construction_progress_pct":34.5,"sources":{"handover_date":"wafi","construction_progress_pct":"wafi"}},"offplan_licence_no":"1100012345","last_seen_at":"2026-09-21T10:00:00.000Z"}],"pagination":{"limit":25,"next_cursor":"eyJvIjoyNSwiZiI6IksweTFfU1F3d1BXSiJ9.pkFEfJUOpRbZRS279EDC4v","has_more":true,"result_window_reached":false}}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{id}":{"get":{"operationId":"projects.get","summary":"Get a project","description":"One project with its description, boundary, amenities, financing banks and a summary of the units listed on Kite. Page through the units with GET /projects/{id}/units. Returns 404 for inactive projects and for copies merged into another project.","tags":["Off-plan projects"],"x-scope":"projects","x-units":1,"security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Project id.","example":4812,"schema":{"type":"integer","minimum":1,"maximum":2147483647}}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Units allowed per minute.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Units left this minute.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-Request-Units":{"description":"Units this request cost.","schema":{"type":"integer"}},"X-Quota-Limit":{"description":"Units allowed this calendar month (UTC). Absent on unlimited plans.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Units left this calendar month (UTC). Absent on unlimited plans. Reads `0` once a plan with overage is past its quota and still serving.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Seconds until the monthly quota resets. Absent on unlimited plans.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"integer","example":4812},"url":{"description":"The project's page on kite.sa.","type":["string","null"]},"name_ar":{"example":"مشروع سدرة","type":["string","null"]},"name_en":{"example":"Sedra","type":["string","null"]},"developer":{"description":"Developer name as published. Pass as `developer` to filter; see GET /developers.","example":"Retal Urban Development","type":["string","null"]},"status":{"anyOf":[{"type":"string","enum":["available","coming_soon","not_started","under_construction","completed","sold_out"]},{"type":"null"}],"description":"Sales/construction status. Null when the source doesn't say."},"project_type":{"anyOf":[{"type":"string","enum":["off_plan","ready"]},{"type":"null"}],"description":"`off_plan` (sold before completion) or `ready`. Null when unknown."},"listing_category":{"type":"string","example":"residential"},"location":{"type":"object","properties":{"city":{"description":"City slug (see GET /cities).","example":"riyadh","type":["string","null"]},"city_name_en":{"example":"Riyadh","type":["string","null"]},"neighborhood_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"See GET /cities/{city}/neighborhoods. Not every project is mapped to a neighborhood yet."},"neighborhood_name_ar":{"type":["string","null"]},"neighborhood_name_en":{"type":["string","null"]},"lat":{"type":["number","null"]},"lng":{"type":["number","null"]},"precision":{"anyOf":[{"type":"string","enum":["exact","neighborhood"]},{"type":"null"}],"description":"How far lat/lng can be trusted. `exact`: a point a source published for the project. `neighborhood`: the centre of the project's neighborhood, because no source gave a point (the project is somewhere in that neighborhood). Null when lat/lng is null.","example":"exact"}},"required":["city","city_name_en","neighborhood_id","neighborhood_name_ar","neighborhood_name_en","lat","lng","precision"],"additionalProperties":false},"price":{"type":"object","properties":{"starting_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Lowest advertised purchase price in SAR (a sale price, not a rent).","example":850000},"from_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Lower end of the advertised price range, SAR."},"to_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Upper end of the advertised price range, SAR."}},"required":["starting_sar","from_sar","to_sar"],"additionalProperties":false,"description":"Developer-advertised purchase prices in SAR (total price, not yearly). Null when not published or implausibly low."},"area_sqm":{"type":"object","properties":{"min":{"type":["number","null"]},"max":{"type":["number","null"]}},"required":["min","max"],"additionalProperties":false,"description":"Advertised unit size range in square meters."},"advertised_unit_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Total units in the project, as the developer advertises it."},"last_seen_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","example":"2026-09-21T10:00:00.000Z"},{"type":"null"}],"description":"Last time Kite refreshed the project from its source."},"description":{"description":"As published (usually Arabic).","type":["string","null"]},"description_en":{"type":["string","null"]},"address":{"type":["string","null"]},"boundary":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["Polygon","MultiPolygon"]},"coordinates":{"type":"array","items":{}}},"required":["type","coordinates"],"additionalProperties":false},{"type":"null"}],"description":"Project boundary as GeoJSON ([lng, lat] order), where published."},"images":{"type":"array","items":{"type":"string"},"description":"Image URLs on Kite's CDN."},"features":{"type":"array","items":{"type":"string"},"description":"Amenities, as stable ids.","example":["elevator","parking","smart_home"]},"supported_banks":{"type":"array","items":{"type":"string"},"description":"Banks the developer lists for mortgage financing.","example":["alrajhi","alahli"]},"warranty":{"type":"array","items":{"type":"object","properties":{"item":{"type":"string"},"duration":{"type":["string","null"]}},"required":["item","duration"],"additionalProperties":false},"description":"Warranties the developer offers, e.g. `{ item: \"plumbing\", duration: \"5\" }`. `duration` is as published, usually years."},"links":{"type":"object","properties":{"brochure":{"type":["string","null"]},"virtual_tour":{"type":["string","null"]},"video":{"type":["string","null"]}},"required":["brochure","virtual_tour","video"],"additionalProperties":false},"timeline":{"type":"object","properties":{"construction_start_date":{"description":"Construction start, `YYYY-MM-DD`.","example":"2025-03-01","type":["string","null"]},"sales_start_date":{"description":"Start of sales, `YYYY-MM-DD`.","example":"2025-05-10","type":["string","null"]},"handover_date":{"description":"Expected handover (completion) date, `YYYY-MM-DD`, as the source states it. A date that moves between snapshots is a slip; see GET /projects/{id}/availability.","example":"2027-12-31","type":["string","null"]},"construction_progress_pct":{"description":"Construction progress in percent (0-100), as the source states it (on Wafi, the registry's achievement rate).","example":34.5,"type":["number","null"]},"sources":{"type":"object","properties":{"construction_start_date":{"description":"Source slug the value was read from; null when the value is null.","example":"wafi","type":["string","null"]},"sales_start_date":{"description":"Source slug the value was read from; null when the value is null.","example":"propertyfinder","type":["string","null"]},"handover_date":{"description":"Source slug the value was read from; null when the value is null.","example":"wafi","type":["string","null"]},"construction_progress_pct":{"description":"Source slug the value was read from; null when the value is null.","example":"wafi","type":["string","null"]}},"required":["construction_start_date","sales_start_date","handover_date","construction_progress_pct"],"additionalProperties":false,"description":"Where each value came from (a source slug, see GET /enums)."}},"required":["construction_start_date","sales_start_date","handover_date","construction_progress_pct","sources"],"additionalProperties":false,"description":"Construction and sales dates and progress. Each field comes from the best copy of the project that states it: the REGA off-plan registry (Wafi) first, then the developer's site, then portals. Null where no source says; never estimated."},"sales_terms":{"type":"object","properties":{"down_payment_pct":{"description":"Down payment in percent of the price.","example":10,"type":["number","null"]},"payment_plans":{"anyOf":[{"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},{"type":"null"}],"description":"Payment plans exactly as the source publishes them (labels, percentages, milestones). Keys vary by source.","example":[{"label":"On booking","percentage":10}]},"sources":{"type":"object","properties":{"down_payment_pct":{"description":"Source slug the value was read from; null when the value is null.","example":"propertyfinder","type":["string","null"]},"payment_plans":{"description":"Source slug the value was read from; null when the value is null.","example":"propertyfinder","type":["string","null"]}},"required":["down_payment_pct","payment_plans"],"additionalProperties":false,"description":"Where each value came from (a source slug, see GET /enums)."}},"required":["down_payment_pct","payment_plans","sources"],"additionalProperties":false,"description":"Off-plan payment terms, from the developer's site or a portal first, then the registry. Null where no source says."},"licence":{"type":"object","properties":{"number":{"description":"REGA off-plan sale licence number. A project sold off-plan must hold one; it also appears on licensed ads.","example":"1100012345","type":["string","null"]},"valid_from":{"description":"Licence start, `YYYY-MM-DD`.","example":"2025-01-15","type":["string","null"]},"valid_to":{"description":"Licence end, `YYYY-MM-DD`.","example":"2028-01-14","type":["string","null"]},"land_area_sqm":{"description":"Land area of the project in square meters, as registered.","example":45000,"type":["number","null"]},"escrow_bank":{"description":"Bank holding the project's escrow account, as the registry names it.","example":"مصرف الراجحي","type":["string","null"]},"consultant":{"description":"Engineering consultant, as the registry names them.","example":"دار الهندسة للتصميم والاستشارات","type":["string","null"]},"sources":{"type":"object","properties":{"number":{"description":"Source slug the value was read from; null when the value is null.","example":"wafi","type":["string","null"]},"valid_from":{"description":"Source slug the value was read from; null when the value is null.","example":"wafi","type":["string","null"]},"valid_to":{"description":"Source slug the value was read from; null when the value is null.","example":"wafi","type":["string","null"]},"land_area_sqm":{"description":"Source slug the value was read from; null when the value is null.","example":"wafi","type":["string","null"]},"escrow_bank":{"description":"Source slug the value was read from; null when the value is null.","example":"wafi","type":["string","null"]},"consultant":{"description":"Source slug the value was read from; null when the value is null.","example":"wafi","type":["string","null"]}},"required":["number","valid_from","valid_to","land_area_sqm","escrow_bank","consultant"],"additionalProperties":false,"description":"Where each value came from (a source slug, see GET /enums)."}},"required":["number","valid_from","valid_to","land_area_sqm","escrow_bank","consultant","sources"],"additionalProperties":false,"description":"The off-plan sale licence and the facts registered with it, from the REGA off-plan registry (Wafi). All null for projects with no licence on record (ready projects, or not yet matched to the registry)."},"source":{"type":"object","properties":{"name":{"type":"string","example":"wafi"},"url":{"description":"The original page. Attribution is required, see the terms.","type":["string","null"]}},"required":["name","url"],"additionalProperties":false},"linked_units":{"type":"object","properties":{"count":{"type":"integer"},"for_sale":{"type":"integer"},"for_rent":{"type":"integer"},"bedrooms_min":{"anyOf":[{"type":"integer"},{"type":"null"}]},"bedrooms_max":{"anyOf":[{"type":"integer"},{"type":"null"}]},"area_sqm_min":{"type":["number","null"]},"area_sqm_max":{"type":["number","null"]},"sale_price_sar_min":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Cheapest linked unit for sale, SAR."},"sale_price_sar_max":{"anyOf":[{"type":"integer"},{"type":"null"}]},"yearly_rent_sar_min":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Cheapest linked rental, SAR per year."},"yearly_rent_sar_max":{"anyOf":[{"type":"integer"},{"type":"null"}]}},"required":["count","for_sale","for_rent","bedrooms_min","bedrooms_max","area_sqm_min","area_sqm_max","sale_price_sar_min","sale_price_sar_max","yearly_rent_sar_min","yearly_rent_sar_max"],"additionalProperties":false,"description":"Summary of the active listings linked to this project. Page through them with GET /projects/{id}/units."}},"required":["id","url","name_ar","name_en","developer","status","project_type","listing_category","location","price","area_sqm","advertised_unit_count","last_seen_at","description","description_en","address","boundary","images","features","supported_banks","warranty","links","timeline","sales_terms","licence","source","linked_units"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"id":4812,"url":"https://kite.sa/en/projects/4812","name_ar":"مشروع سدرة","name_en":"Sedra","developer":"Retal Urban Development","status":"available","project_type":"off_plan","listing_category":"residential","location":{"city":"riyadh","city_name_en":"Riyadh","neighborhood_id":null,"neighborhood_name_ar":"الملقا","neighborhood_name_en":"Al Malqa","lat":24.8136,"lng":46.6097,"precision":"exact"},"price":{"starting_sar":850000,"from_sar":null,"to_sar":null},"area_sqm":{"min":95,"max":220},"advertised_unit_count":null,"last_seen_at":"2026-09-21T10:00:00.000Z","description":"شقق وتاون هاوس في شمال الرياض، على مقربة من طريق الملك سلمان.","description_en":"Apartments and townhouses in north Riyadh, a short drive from King Salman Road.","address":"Anas Ibn Malik Road, Al Malqa, Riyadh","boundary":{"type":"Polygon","coordinates":[null]},"images":["https://images.example.com/projects/4812/1.jpg"],"features":["elevator","parking","smart_home"],"supported_banks":["alrajhi","alahli"],"warranty":[{"item":"Structure","duration":"10 years"}],"links":{"brochure":"https://images.example.com/projects/4812/brochure.pdf","virtual_tour":"https://example.com/tours/4812","video":"https://www.youtube.com/watch?v=EXAMPLE"},"timeline":{"construction_start_date":"2025-03-01","sales_start_date":"2025-05-10","handover_date":"2027-12-31","construction_progress_pct":34.5,"sources":{"construction_start_date":"wafi","sales_start_date":"propertyfinder","handover_date":"wafi","construction_progress_pct":"wafi"}},"sales_terms":{"down_payment_pct":10,"payment_plans":[{"label":"On booking","percentage":10}],"sources":{"down_payment_pct":"propertyfinder","payment_plans":"propertyfinder"}},"licence":{"number":"1100012345","valid_from":"2025-01-15","valid_to":"2028-01-14","land_area_sqm":45000,"escrow_bank":"مصرف الراجحي","consultant":"دار الهندسة للتصميم والاستشارات","sources":{"number":"wafi","valid_from":"wafi","valid_to":"wafi","land_area_sqm":"wafi","escrow_bank":"wafi","consultant":"wafi"}},"source":{"name":"wafi","url":"https://kite.sa/go/project/4812"},"linked_units":{"count":18,"for_sale":15,"for_rent":3,"bedrooms_min":null,"bedrooms_max":null,"area_sqm_min":95,"area_sqm_max":240,"sale_price_sar_min":null,"sale_price_sar_max":null,"yearly_rent_sar_min":null,"yearly_rent_sar_max":null}}}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{id}/units":{"get":{"operationId":"projects.units","summary":"List a project's units","description":"Active listings on Kite linked to one project: units for sale (total price) and, for some projects, rentals (yearly rent). Units priced implausibly low for their city are left out. Returns 404 if the project isn't active.","tags":["Off-plan projects"],"x-scope":"projects","x-units":"1 per result asked for with `limit` (default 25), up to your plan's page size","security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Project id.","example":4812,"schema":{"type":"integer","minimum":1,"maximum":2147483647}},{"name":"listing_type","in":"query","required":false,"description":"Omit for both. Most project units are for sale; some are rentals.","schema":{"type":"string","enum":["sale","rent"]}},{"name":"property_type","in":"query","required":false,"description":"One or more, comma-separated.","example":["apartment","villa"],"schema":{"minItems":1,"maxItems":7,"type":"array","items":{"type":"string","enum":["apartment","villa","floor","land","building","office","shop"]}},"style":"form","explode":false},{"name":"bedrooms","in":"query","required":false,"description":"Exact number of bedrooms.","schema":{"type":"integer","minimum":0,"maximum":20}},{"name":"bedrooms_min","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":20}},{"name":"bedrooms_max","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":20}},{"name":"bathrooms","in":"query","required":false,"description":"Exact number of bathrooms.","schema":{"type":"integer","minimum":0,"maximum":20}},{"name":"bathrooms_min","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":20}},{"name":"price_min","in":"query","required":false,"description":"SAR. Compared with `sale_price_sar` for sales and `yearly_rent_sar` for rentals; set `listing_type` to keep them apart.","schema":{"type":"integer","minimum":0,"maximum":2000000000}},{"name":"price_max","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":2000000000}},{"name":"area_min","in":"query","required":false,"description":"Square meters.","schema":{"type":"number","minimum":0,"maximum":10000000}},{"name":"area_max","in":"query","required":false,"schema":{"type":"number","minimum":0,"maximum":10000000}},{"name":"sort","in":"query","required":false,"description":"`price_asc`/`price_desc` (by SAR amount; sales and yearly rents sort together unless you set `listing_type`), `newest` (first seen by Kite), `area_desc`, `bedrooms_desc`.","schema":{"default":"price_asc","type":"string","enum":["price_asc","price_desc","newest","area_desc","bedrooms_desc"]}},{"name":"limit","in":"query","required":false,"schema":{"default":25,"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":500}}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Units allowed per minute.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Units left this minute.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-Request-Units":{"description":"Units this request cost.","schema":{"type":"integer"}},"X-Quota-Limit":{"description":"Units allowed this calendar month (UTC). Absent on unlimited plans.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Units left this calendar month (UTC). Absent on unlimited plans. Reads `0` once a plan with overage is past its quota and still serving.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Seconds until the monthly quota resets. Absent on unlimited plans.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Listing id; GET /listings/{id} returns the full listing (with the `listings` scope).","example":128647},"url":{"type":"string","description":"The listing's page on kite.sa."},"project":{"type":"object","properties":{"id":{"type":"integer"},"name_ar":{"type":["string","null"]},"name_en":{"type":["string","null"]}},"required":["id","name_ar","name_en"],"additionalProperties":false},"link":{"type":"object","properties":{"type":{"type":"string","example":"source"},"confidence":{"type":"number"}},"required":["type","confidence"],"additionalProperties":false,"description":"How the listing was tied to the project: `source` (the source says so, confidence 1), `geo` (inside or next to the project's boundary) or `text` (project named in the ad). New types may be added."},"title":{"type":["string","null"]},"listing_type":{"type":"string","enum":["sale","rent"]},"property_type":{"type":"string","example":"apartment"},"sale_price_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Total purchase price in SAR. Null for rentals.","example":980000},"yearly_rent_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Rent in SAR per year (monthly and daily postings normalized to yearly). Null for units for sale."},"bedrooms":{"anyOf":[{"type":"integer"},{"type":"null"}]},"bathrooms":{"anyOf":[{"type":"integer"},{"type":"null"}]},"area_sqm":{"type":["number","null"]},"floor":{"type":["string","null"]},"location":{"type":"object","properties":{"city":{"description":"City slug (see GET /cities).","example":"riyadh","type":["string","null"]},"city_name_en":{"example":"Riyadh","type":["string","null"]},"neighborhood_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"See GET /cities/{city}/neighborhoods. Not every project is mapped to a neighborhood yet."},"neighborhood_name_ar":{"type":["string","null"]},"neighborhood_name_en":{"type":["string","null"]},"lat":{"type":["number","null"]},"lng":{"type":["number","null"]},"precision":{"anyOf":[{"type":"string","enum":["exact","neighborhood"]},{"type":"null"}],"description":"How far lat/lng can be trusted. `exact`: a point a source published for the project. `neighborhood`: the centre of the project's neighborhood, because no source gave a point (the project is somewhere in that neighborhood). Null when lat/lng is null.","example":"exact"}},"required":["city","city_name_en","neighborhood_id","neighborhood_name_ar","neighborhood_name_en","lat","lng","precision"],"additionalProperties":false},"images":{"type":"array","items":{"type":"string"},"description":"Up to three image URLs on Kite's CDN."},"source":{"type":"object","properties":{"name":{"type":"string"},"url":{"description":"The original ad. Attribution is required, see the terms.","type":["string","null"]}},"required":["name","url"],"additionalProperties":false},"first_seen_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","example":"2026-09-21T10:00:00.000Z"},{"type":"null"}]},"last_seen_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","example":"2026-09-21T10:00:00.000Z"},{"type":"null"}]}},"required":["id","url","project","link","title","listing_type","property_type","sale_price_sar","yearly_rent_sar","bedrooms","bathrooms","area_sqm","floor","location","images","source","first_seen_at","last_seen_at"],"additionalProperties":false}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"],"additionalProperties":false},"example":{"data":[{"id":128647,"url":"https://kite.sa/en/projects/4812","project":{"id":4812,"name_ar":"مساكن الملقا","name_en":"Al Malqa Residences"},"link":{"type":"source","confidence":0.92},"title":"3-bedroom apartment, type B","listing_type":"sale","property_type":"apartment","sale_price_sar":980000,"yearly_rent_sar":null,"bedrooms":null,"bathrooms":null,"area_sqm":145,"floor":"3","location":{"city":"riyadh","city_name_en":"Riyadh","neighborhood_id":null,"neighborhood_name_ar":"الملقا","neighborhood_name_en":"Al Malqa","lat":24.8136,"lng":46.6097,"precision":"exact"},"images":["https://images.example.com/projects/4812/1.jpg"],"source":{"name":"Sakani","url":"https://kite.sa/go/project/4812"},"first_seen_at":"2026-09-21T10:00:00.000Z","last_seen_at":"2026-09-21T10:00:00.000Z"}],"pagination":{"limit":25,"next_cursor":"eyJvIjoyNSwiZiI6IksweTFfU1F3d1BXSiJ9.pkFEfJUOpRbZRS279EDC4v","has_more":true,"result_window_reached":false}}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{id}/availability":{"get":{"operationId":"projects.availability","summary":"Get a project's unit availability over time","description":"Daily snapshots of a project's unit count and the availability its source reports, as daily, weekly or monthly points, each with the units absorbed since the previous point.\n\nThis is **listed availability**, not contracts: it comes from what the project's source page showed on the day, so a unit counts as absorbed when the source stops showing it, not when it is sold or leased. Kite began keeping snapshots on 2026-09-26 (earlier dates have none); `coverage` gives the range held for this project. Only some sources report available units; where they don't, `available_units` and `absorbed_since_previous` are null and `total_units` is the project's unit count. `unit_type` narrows `total_units` and `unit_types` to one type for sources that send counts per type. Defaults to the last 90 days, up to 366. Returns 404 for inactive projects.","tags":["Off-plan projects"],"x-scope":"projects","x-units":10,"security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Project id.","example":4812,"schema":{"type":"integer","minimum":1,"maximum":2147483647}},{"name":"interval","in":"query","required":false,"description":"Point spacing; each point is the last snapshot in its day, week or month.","schema":{"default":"weekly","type":"string","enum":["daily","weekly","monthly"]}},{"name":"from","in":"query","required":false,"description":"First day (`YYYY-MM-DD`, Riyadh time). Defaults to 90 days before `to`.","example":"2026-09-26","schema":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$"}},{"name":"to","in":"query","required":false,"description":"Last day (`YYYY-MM-DD`). Defaults to today.","example":"2026-10-07","schema":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$"}},{"name":"unit_type","in":"query","required":false,"description":"Unit type as the source names it (for example `apartment`, `villa`); see `unit_types` in the response.","example":"apartment","schema":{"type":"string","minLength":1,"maxLength":60}}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Units allowed per minute.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Units left this minute.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-Request-Units":{"description":"Units this request cost.","schema":{"type":"integer"}},"X-Quota-Limit":{"description":"Units allowed this calendar month (UTC). Absent on unlimited plans.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Units left this calendar month (UTC). Absent on unlimited plans. Reads `0` once a plan with overage is past its quota and still serving.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Seconds until the monthly quota resets. Absent on unlimited plans.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project_id":{"type":"integer"},"interval":{"type":"string","enum":["daily","weekly","monthly"]},"from":{"type":"string","description":"First day of the range, `YYYY-MM-DD`."},"to":{"type":"string","description":"Last day of the range, `YYYY-MM-DD`."},"unit_type":{"type":["string","null"]},"coverage":{"type":"object","properties":{"first_snapshot":{"description":"Earliest snapshot Kite holds for this project.","type":["string","null"]},"last_snapshot":{"type":["string","null"]},"snapshots":{"type":"integer","description":"Snapshots held for this project, all dates."}},"required":["first_snapshot","last_snapshot","snapshots"],"additionalProperties":false},"points":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","description":"Date of the snapshot this point is read from: the last one in its day, week (Monday start) or month.","example":"2026-10-04"},"project_status":{"description":"The source's own status text, as scraped.","type":["string","null"]},"total_units":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Units in the project as the source counts them; with `unit_type`, the count of that type."},"available_units":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Units the source says are still available. Null when the source doesn't report it (most don't), and always null with `unit_type`."},"absorbed_since_previous":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Previous point's `available_units` minus this one's. Positive = units left the market; negative = units were added or came back. Null for the first point and wherever either side is unknown."},"unit_types":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"integer"}},{"type":"null"}],"description":"Unit counts by type (as the source names them) when it sends counts; else null."},"starting_price":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Advertised starting price, SAR."},"source":{"type":"string","description":"Source the snapshot was scraped from.","example":"mada"},"timeline":{"type":"object","properties":{"handover_date":{"description":"Expected handover (completion) date, `YYYY-MM-DD`, as the source states it. A date that moves between snapshots is a slip; see GET /projects/{id}/availability.","example":"2027-12-31","type":["string","null"]},"construction_progress_pct":{"description":"Construction progress in percent (0-100), as the source states it (on Wafi, the registry's achievement rate).","example":34.5,"type":["number","null"]},"sources":{"type":"object","properties":{"handover_date":{"description":"Source slug the value was read from; null when the value is null.","example":"wafi","type":["string","null"]},"construction_progress_pct":{"description":"Source slug the value was read from; null when the value is null.","example":"wafi","type":["string","null"]}},"required":["handover_date","construction_progress_pct"],"additionalProperties":false,"description":"Where each value came from (a source slug, see GET /enums)."}},"required":["handover_date","construction_progress_pct","sources"],"additionalProperties":false,"description":"Handover date and construction progress as stated in this point's day, week or month, from any copy of the project (the Wafi registry copy first; within a source, the latest snapshot). Compare `handover_date` across points to see a slip. Recorded since November 2026; null before then and where no source says."}},"required":["date","project_status","total_units","available_units","absorbed_since_previous","unit_types","starting_price","source","timeline"],"additionalProperties":false}}},"required":["project_id","interval","from","to","unit_type","coverage","points"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"project_id":4812,"interval":"daily","from":"2026-06-01","to":"2026-09-21","unit_type":"apartment","coverage":{"first_snapshot":"2026-06-01","last_snapshot":"2026-09-21","snapshots":64},"points":[{"date":"2026-10-04","project_status":"under_construction","total_units":null,"available_units":null,"absorbed_since_previous":null,"unit_types":{},"starting_price":null,"source":"mada","timeline":{"handover_date":"2027-12-31","construction_progress_pct":34.5,"sources":{"handover_date":"wafi","construction_progress_pct":"wafi"}}}]}}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/project-units":{"get":{"operationId":"projects.units_search","summary":"Search project units","description":"Units across all projects: active listings linked to a project, filtered by the unit (bedrooms, price, area) and by its project (city, developer, status). A listing linked to several projects appears once, under its strongest link. Units priced implausibly low for their city (installments, typos) are left out.","tags":["Off-plan projects"],"x-scope":"projects","x-units":"1 per result asked for with `limit` (default 25), up to your plan's page size","security":[{"apiKey":[]}],"parameters":[{"name":"city","in":"query","required":false,"description":"Omit for all cities.","example":"riyadh","schema":{"type":"string","pattern":"^[a-z_]+$"}},{"name":"neighborhood_id","in":"query","required":false,"description":"Neighborhood ids from GET /cities/{city}/neighborhoods; matches the unit's neighborhood, or its project's when the unit has none.","schema":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"integer","minimum":1,"maximum":2147483647}},"style":"form","explode":false},{"name":"developer","in":"query","required":false,"description":"Exact developer name, as returned by GET /developers.","example":"Retal Urban Development","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"status","in":"query","required":false,"description":"One or more, comma-separated.","example":["available","under_construction"],"schema":{"minItems":1,"maxItems":6,"type":"array","items":{"type":"string","enum":["available","coming_soon","not_started","under_construction","completed","sold_out"]}},"style":"form","explode":false},{"name":"project_type","in":"query","required":false,"schema":{"type":"string","enum":["off_plan","ready"]}},{"name":"listing_category","in":"query","required":false,"description":"Omit for both.","schema":{"type":"string","enum":["residential","commercial"]}},{"name":"features","in":"query","required":false,"description":"Only projects with all of these, see GET /enums.","example":["pool","gym"],"schema":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string","pattern":"^[a-z_]+$"}},"style":"form","explode":false},{"name":"banks","in":"query","required":false,"description":"Only projects financed by all of these, see GET /enums.","schema":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string","pattern":"^[a-z_]+$"}},"style":"form","explode":false},{"name":"listing_type","in":"query","required":false,"description":"Omit for both. Most project units are for sale; some are rentals.","schema":{"type":"string","enum":["sale","rent"]}},{"name":"property_type","in":"query","required":false,"description":"One or more, comma-separated.","example":["apartment","villa"],"schema":{"minItems":1,"maxItems":7,"type":"array","items":{"type":"string","enum":["apartment","villa","floor","land","building","office","shop"]}},"style":"form","explode":false},{"name":"bedrooms","in":"query","required":false,"description":"Exact number of bedrooms.","schema":{"type":"integer","minimum":0,"maximum":20}},{"name":"bedrooms_min","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":20}},{"name":"bedrooms_max","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":20}},{"name":"bathrooms","in":"query","required":false,"description":"Exact number of bathrooms.","schema":{"type":"integer","minimum":0,"maximum":20}},{"name":"bathrooms_min","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":20}},{"name":"price_min","in":"query","required":false,"description":"SAR. Compared with `sale_price_sar` for sales and `yearly_rent_sar` for rentals; set `listing_type` to keep them apart.","schema":{"type":"integer","minimum":0,"maximum":2000000000}},{"name":"price_max","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":2000000000}},{"name":"area_min","in":"query","required":false,"description":"Square meters.","schema":{"type":"number","minimum":0,"maximum":10000000}},{"name":"area_max","in":"query","required":false,"schema":{"type":"number","minimum":0,"maximum":10000000}},{"name":"sort","in":"query","required":false,"description":"`price_asc`/`price_desc` (by SAR amount; sales and yearly rents sort together unless you set `listing_type`), `newest` (first seen by Kite), `area_desc`, `bedrooms_desc`.","schema":{"default":"newest","type":"string","enum":["price_asc","price_desc","newest","area_desc","bedrooms_desc"]}},{"name":"limit","in":"query","required":false,"schema":{"default":25,"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":500}}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Units allowed per minute.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Units left this minute.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-Request-Units":{"description":"Units this request cost.","schema":{"type":"integer"}},"X-Quota-Limit":{"description":"Units allowed this calendar month (UTC). Absent on unlimited plans.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Units left this calendar month (UTC). Absent on unlimited plans. Reads `0` once a plan with overage is past its quota and still serving.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Seconds until the monthly quota resets. Absent on unlimited plans.","schema":{"type":"integer"}},"X-Resolved-City":{"description":"The covered city slug the request's `city` was resolved to, when it differs from what was sent (`city=dammam` answers for `eastern_province`). Absent when the slug was sent as is.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Listing id; GET /listings/{id} returns the full listing (with the `listings` scope).","example":128647},"url":{"type":"string","description":"The listing's page on kite.sa."},"project":{"type":"object","properties":{"id":{"type":"integer"},"name_ar":{"type":["string","null"]},"name_en":{"type":["string","null"]}},"required":["id","name_ar","name_en"],"additionalProperties":false},"link":{"type":"object","properties":{"type":{"type":"string","example":"source"},"confidence":{"type":"number"}},"required":["type","confidence"],"additionalProperties":false,"description":"How the listing was tied to the project: `source` (the source says so, confidence 1), `geo` (inside or next to the project's boundary) or `text` (project named in the ad). New types may be added."},"title":{"type":["string","null"]},"listing_type":{"type":"string","enum":["sale","rent"]},"property_type":{"type":"string","example":"apartment"},"sale_price_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Total purchase price in SAR. Null for rentals.","example":980000},"yearly_rent_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Rent in SAR per year (monthly and daily postings normalized to yearly). Null for units for sale."},"bedrooms":{"anyOf":[{"type":"integer"},{"type":"null"}]},"bathrooms":{"anyOf":[{"type":"integer"},{"type":"null"}]},"area_sqm":{"type":["number","null"]},"floor":{"type":["string","null"]},"location":{"type":"object","properties":{"city":{"description":"City slug (see GET /cities).","example":"riyadh","type":["string","null"]},"city_name_en":{"example":"Riyadh","type":["string","null"]},"neighborhood_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"See GET /cities/{city}/neighborhoods. Not every project is mapped to a neighborhood yet."},"neighborhood_name_ar":{"type":["string","null"]},"neighborhood_name_en":{"type":["string","null"]},"lat":{"type":["number","null"]},"lng":{"type":["number","null"]},"precision":{"anyOf":[{"type":"string","enum":["exact","neighborhood"]},{"type":"null"}],"description":"How far lat/lng can be trusted. `exact`: a point a source published for the project. `neighborhood`: the centre of the project's neighborhood, because no source gave a point (the project is somewhere in that neighborhood). Null when lat/lng is null.","example":"exact"}},"required":["city","city_name_en","neighborhood_id","neighborhood_name_ar","neighborhood_name_en","lat","lng","precision"],"additionalProperties":false},"images":{"type":"array","items":{"type":"string"},"description":"Up to three image URLs on Kite's CDN."},"source":{"type":"object","properties":{"name":{"type":"string"},"url":{"description":"The original ad. Attribution is required, see the terms.","type":["string","null"]}},"required":["name","url"],"additionalProperties":false},"first_seen_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","example":"2026-09-21T10:00:00.000Z"},{"type":"null"}]},"last_seen_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","example":"2026-09-21T10:00:00.000Z"},{"type":"null"}]}},"required":["id","url","project","link","title","listing_type","property_type","sale_price_sar","yearly_rent_sar","bedrooms","bathrooms","area_sqm","floor","location","images","source","first_seen_at","last_seen_at"],"additionalProperties":false}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"],"additionalProperties":false},"example":{"data":[{"id":128647,"url":"https://kite.sa/en/projects/4812","project":{"id":4812,"name_ar":"مساكن الملقا","name_en":"Al Malqa Residences"},"link":{"type":"source","confidence":0.92},"title":"3-bedroom apartment, type B","listing_type":"sale","property_type":"apartment","sale_price_sar":980000,"yearly_rent_sar":null,"bedrooms":null,"bathrooms":null,"area_sqm":145,"floor":"3","location":{"city":"riyadh","city_name_en":"Riyadh","neighborhood_id":null,"neighborhood_name_ar":"الملقا","neighborhood_name_en":"Al Malqa","lat":24.8136,"lng":46.6097,"precision":"exact"},"images":["https://images.example.com/projects/4812/1.jpg"],"source":{"name":"Sakani","url":"https://kite.sa/go/project/4812"},"first_seen_at":"2026-09-21T10:00:00.000Z","last_seen_at":"2026-09-21T10:00:00.000Z"}],"pagination":{"limit":25,"next_cursor":"eyJvIjoyNSwiZiI6IksweTFfU1F3d1BXSiJ9.pkFEfJUOpRbZRS279EDC4v","has_more":true,"result_window_reached":false}}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/developers":{"get":{"operationId":"projects.developers","summary":"List developers","description":"Developers with active projects on Kite, most projects first. Developers are identified by name as their projects publish it; the same company can appear under an Arabic and an English spelling.","tags":["Off-plan projects"],"x-scope":"projects","x-units":1,"security":[{"apiKey":[]}],"parameters":[{"name":"city","in":"query","required":false,"description":"Only developers with projects in this city.","example":"riyadh","schema":{"type":"string","pattern":"^[a-z_]+$"}},{"name":"limit","in":"query","required":false,"schema":{"default":25,"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":500}}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Units allowed per minute.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Units left this minute.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-Request-Units":{"description":"Units this request cost.","schema":{"type":"integer"}},"X-Quota-Limit":{"description":"Units allowed this calendar month (UTC). Absent on unlimited plans.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Units left this calendar month (UTC). Absent on unlimited plans. Reads `0` once a plan with overage is past its quota and still serving.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Seconds until the monthly quota resets. Absent on unlimited plans.","schema":{"type":"integer"}},"X-Resolved-City":{"description":"The covered city slug the request's `city` was resolved to, when it differs from what was sent (`city=dammam` answers for `eastern_province`). Absent when the slug was sent as is.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"As published. Pass as `developer` to GET /projects and GET /project-units.","example":"Retal Urban Development"},"project_count":{"type":"integer","description":"Active projects on Kite."},"active_project_count":{"type":"integer","description":"Projects whose status is available, coming_soon, not_started or under_construction."},"cities":{"type":"array","items":{"type":"string"},"description":"City slugs.","example":["riyadh","jeddah"]}},"required":["name","project_count","active_project_count","cities"],"additionalProperties":false}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"],"additionalProperties":false},"example":{"data":[{"name":"Retal Urban Development","project_count":22,"active_project_count":14,"cities":["riyadh","jeddah"]}],"pagination":{"limit":25,"next_cursor":"eyJvIjoyNSwiZiI6IksweTFfU1F3d1BXSiJ9.pkFEfJUOpRbZRS279EDC4v","has_more":true,"result_window_reached":false}}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{id}/absorption":{"get":{"operationId":"projects.absorption","summary":"Get a project's absorption by month","description":"How fast a project's offered units go, per calendar month: units on offer at the start and end, units gone, units re-added and released, the absorption rate (units gone ÷ units at the start), and months of stock left at that pace. Each month carries a `reliability` and the `flags` behind it; the project carries `history_days` and an overall `reliability`.\n\n**This is not a sales record.** A portal's or developer site's \"available\" count is what the page showed on the day. A unit counts as gone when the source stops offering it, which a sale, a reservation, a lease, or the developer pulling it off the page all look like from outside; reservations fall through, and developers hold units back. Read the figures as how fast the advertised offer shrinks, alongside registered deals where you need actual sales.\n\n**Which projects.** Only sources that publish an inventory count can be measured: unit tables with a status per unit (Asas Makeen, Rasan; `basis` `unit_status`), a stated available count (Mada; `reported_available`), or the number of units listed on the project's page (Wasalt, CompoundIn; `listed_units`). Every other source's unit count is the project's size, which doesn't move with sales, so most projects have `reliability` `no_inventory_signal`. No source reports available units by unit type, so there is no per-type split; `listing_type` separates sale and rent where the source does. Copies of one project from several sources are read once, from the source with the best basis. Snapshots began on 2026-09-26.\n\n**What is left out.** Movement that isn't the market is excluded from `units_gone` and named in each month's `flags`: readings more than 8 days apart (`gap`), the whole inventory vanishing at once without being marked sold or reserved (`withdrawal`), a day on which 40% or more of one source's projects changed (`source_change`), and, on unit tables, units that leave the table without being marked sold or reserved (`units_removed`). A project going inactive or a source dropping it ends its series; it is never read as a sell-out. Units appearing are reported as `units_released` (a new phase) or `units_re_added`, never netted against units gone.\n\nReturns 404 for inactive projects and for copies merged into another project; GET /projects/{id}/availability has the raw daily snapshots.","tags":["Off-plan projects"],"x-scope":"projects","x-units":10,"security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Project id.","example":4812,"schema":{"type":"integer","minimum":1,"maximum":2147483647}},{"name":"listing_type","in":"query","required":false,"description":"Which inventory to read: `sale` (the default) or `rent` units, where the source tells them apart, or `all` for both together. Rasan and Mada report only sale units, CompoundIn only rentals; Asas Makeen and Wasalt report both.","schema":{"default":"sale","type":"string","enum":["sale","rent","all"]}},{"name":"from","in":"query","required":false,"description":"First month (`YYYY-MM`). Defaults to 2026-09, the month snapshots began (2026-09-26).","example":"2026-10","schema":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"}},{"name":"to","in":"query","required":false,"description":"Last month (`YYYY-MM`). Defaults to the current month. At most 24 months.","example":"2026-11","schema":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"}}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Units allowed per minute.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Units left this minute.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-Request-Units":{"description":"Units this request cost.","schema":{"type":"integer"}},"X-Quota-Limit":{"description":"Units allowed this calendar month (UTC). Absent on unlimited plans.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Units left this calendar month (UTC). Absent on unlimited plans. Reads `0` once a plan with overage is past its quota and still serving.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Seconds until the monthly quota resets. Absent on unlimited plans.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"project_id":{"type":"integer"},"listing_type":{"type":"string","enum":["sale","rent","all"]},"from":{"type":"string","example":"2026-09"},"to":{"type":"string","example":"2026-11"},"basis":{"anyOf":[{"type":"string","enum":["unit_status","reported_available","listed_units"]},{"type":"null"}],"description":"What the inventory count is: `unit_status` (the source lists every unit with a status), `reported_available` (the source states an available count), `listed_units` (units listed on the project's page). Null when no source of this project reports inventory."},"basis_source":{"description":"The source the series is read from.","example":"asasmakeen","type":["string","null"]},"reliability":{"type":"string","enum":["usable","short_history","no_inventory_signal"],"description":"`usable`: at least one usable month. `short_history`: readings, but no usable month yet (too short, gaps, or nothing on offer). `no_inventory_signal`: no source of this project reports an inventory count for this `listing_type`."},"history_days":{"type":"integer","description":"Days from the first to the last reading of the series.","example":52},"first_observed":{"example":"2026-09-26","type":["string","null"]},"last_observed":{"example":"2026-11-17","type":["string","null"]},"readings":{"type":"integer","description":"Days with an inventory reading."},"latest_available":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Units on offer at the last reading."},"usable_months":{"type":"integer"},"units_gone_per_month":{"description":"Pace over the last (up to) three usable months, units a month.","type":["number","null"]},"months_of_stock":{"description":"`latest_available` ÷ `units_gone_per_month`. Null when nothing went.","type":["number","null"]},"months":{"type":"array","items":{"type":"object","properties":{"month":{"type":"string","example":"2026-10"},"window_start":{"description":"Date of the reading the month starts from: the last one before the 1st when it is at most 8 days earlier, else the first in the month.","example":"2026-09-30","type":["string","null"]},"window_end":{"description":"Date of the last reading in the month.","example":"2026-10-31","type":["string","null"]},"observed_days":{"type":"integer","description":"Days between the two."},"start_available":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Units on offer at `window_start`."},"end_available":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Units on offer at `window_end`."},"units_gone":{"type":"integer","description":"Units the source stopped offering over the window, after the exclusions in `flags`. From a unit table, only units marked sold or reserved (or let) count. Not a count of sales contracts."},"units_removed":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Unit-table sources only (`basis` `unit_status`): units that left the table without being marked sold or reserved, not counted in `units_gone`. Null for other sources."},"units_re_added":{"type":"integer","description":"Units that came back on offer (a reservation that fell through, a relisting)."},"units_released":{"type":"integer","description":"Units added to the project: a new phase or block. Reported apart, never netted against `units_gone`."},"units_not_counted":{"type":"integer","description":"Movement left out of the count because of a gap, a withdrawal or a source-wide change, in units."},"absorption_rate":{"description":"`units_gone` ÷ `start_available` over the window (to date, in the current month). Null when nothing was on offer.","example":0.08,"type":["number","null"]},"units_gone_per_month":{"description":"`units_gone` scaled to a 30.44-day month from `observed_days`. Null for windows under 14 days.","example":2.4,"type":["number","null"]},"months_of_stock":{"description":"`end_available` ÷ `units_gone_per_month`: months until the offer runs out at this pace. Null when nothing went.","example":6.2,"type":["number","null"]},"reliability":{"type":"string","enum":["ok","partial","unreliable"],"description":"`ok`: a clean window of 21 days or more. `partial`: clean but shorter, or the current month. `unreliable`: movement inside the window was left out (`gap`, `withdrawal` or `source_change`)."},"usable":{"type":"boolean","description":"Whether the month enters GET /market/absorption: not `unreliable`, something on offer at the start, and at least 14 observed days."},"flags":{"type":"array","items":{"type":"string","enum":["gap","withdrawal","source_change","released","units_removed","series_starts_mid_month","series_ends_mid_month","project_inactive","month_in_progress","no_inventory","no_observations"]},"description":"Why a month's figures need care: `gap` (the source was missing for more than 8 days in or just before the month; what moved over the gap is not counted), `withdrawal` (the whole inventory, or most of it, vanished in one step without being marked sold or reserved: a project taken down or a page that half loaded; not counted), `source_change` (a day on which 40% or more of one source's projects changed at once, read as a site or parser change; not counted), `released` (units added in a new phase; reported apart, never netted against units gone), `units_removed` (units left the source's unit table without being marked sold or reserved; not counted), `series_starts_mid_month` / `series_ends_mid_month` (observations cover only part of the month), `project_inactive` (the project left the source; its last reading is not read as a sell-out), `month_in_progress` (the current month, to date), `no_inventory` (nothing on offer at the start), `no_observations` (no reading in the month)."}},"required":["month","window_start","window_end","observed_days","start_available","end_available","units_gone","units_removed","units_re_added","units_released","units_not_counted","absorption_rate","units_gone_per_month","months_of_stock","reliability","usable","flags"],"additionalProperties":false}}},"required":["project_id","listing_type","from","to","basis","basis_source","reliability","history_days","first_observed","last_observed","readings","latest_available","usable_months","units_gone_per_month","months_of_stock","months"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"project_id":4812,"listing_type":"sale","from":"2026-09","to":"2026-11","basis":"unit_status","basis_source":"asasmakeen","reliability":"usable","history_days":52,"first_observed":"2026-09-26","last_observed":"2026-11-17","readings":0,"latest_available":null,"usable_months":0,"units_gone_per_month":0,"months_of_stock":0,"months":[{"month":"2026-10","window_start":"2026-09-30","window_end":"2026-10-31","observed_days":0,"start_available":null,"end_available":null,"units_gone":0,"units_removed":null,"units_re_added":0,"units_released":0,"units_not_counted":0,"absorption_rate":0.08,"units_gone_per_month":2.4,"months_of_stock":6.2,"reliability":"ok","usable":true,"flags":["gap"]}]}}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/market/absorption":{"get":{"operationId":"market.absorption","summary":"Project absorption by area, developer or type","description":"Month-by-month absorption pooled over projects: per city (the default), neighborhood, developer, property type or project type, the units on offer at the start and end of each month, units gone, released and re-added, the pooled and median absorption rate, and months of stock at the month's pace. The per-project series and its rules are GET /projects/{id}/absorption; only months that are `usable` there are pooled, and each figure is null when fewer than `min_sample_size` projects have one. `projects_observed`, `projects_usable` and `flagged` give the sample behind every month.\n\n**This is not a sales record.** A portal's or developer site's \"available\" count is what the page showed on the day. A unit counts as gone when the source stops offering it, which a sale, a reservation, a lease, or the developer pulling it off the page all look like from outside; reservations fall through, and developers hold units back. Read the figures as how fast the advertised offer shrinks, alongside registered deals where you need actual sales.\n\n**Which projects.** Only sources that publish an inventory count can be measured: unit tables with a status per unit (Asas Makeen, Rasan; `basis` `unit_status`), a stated available count (Mada; `reported_available`), or the number of units listed on the project's page (Wasalt, CompoundIn; `listed_units`). Every other source's unit count is the project's size, which doesn't move with sales, so most projects have `reliability` `no_inventory_signal`. No source reports available units by unit type, so there is no per-type split; `listing_type` separates sale and rent where the source does. Copies of one project from several sources are read once, from the source with the best basis. Snapshots began on 2026-09-26. Coverage is thin and uneven: most measurable projects are in Riyadh, and a city or developer may have none; check `projects_tracked` and `projects_usable` before reading a rate.\n\nProjects are counted by their latest location and developer, including projects that have since gone inactive (for the months they were on offer).","tags":["Off-plan projects"],"x-scope":"projects","x-units":50,"security":[{"apiKey":[]}],"parameters":[{"name":"city","in":"query","required":false,"description":"Omit for all cities.","example":"riyadh","schema":{"type":"string","pattern":"^[a-z_]+$"}},{"name":"neighborhood_id","in":"query","required":false,"description":"Neighborhood ids from GET /cities/{city}/neighborhoods. Only projects mapped to a neighborhood match.","schema":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"integer","minimum":1,"maximum":2147483647}},"style":"form","explode":false},{"name":"developer","in":"query","required":false,"description":"Exact developer name, as returned by GET /developers.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"property_type","in":"query","required":false,"description":"Projects whose units listed on Kite are mostly of this type.","schema":{"type":"string","enum":["apartment","villa","floor","duplex","land","building","office","shop"]}},{"name":"project_type","in":"query","required":false,"schema":{"type":"string","enum":["off_plan","ready"]}},{"name":"listing_type","in":"query","required":false,"description":"Which inventory to read: `sale` (the default) or `rent` units, where the source tells them apart, or `all` for both together. Rasan and Mada report only sale units, CompoundIn only rentals; Asas Makeen and Wasalt report both.","schema":{"default":"sale","type":"string","enum":["sale","rent","all"]}},{"name":"group_by","in":"query","required":false,"description":"One group per city (the default), neighborhood, developer, property type or project type. Projects without a value for the grouping field are left out and counted in `projects_ungrouped`.","schema":{"default":"city","type":"string","enum":["city","neighborhood","developer","property_type","project_type"]}},{"name":"from","in":"query","required":false,"description":"First month (`YYYY-MM`). Defaults to 2026-09, the month snapshots began (2026-09-26).","example":"2026-10","schema":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"}},{"name":"to","in":"query","required":false,"description":"Last month (`YYYY-MM`). Defaults to the current month. At most 24 months.","example":"2026-11","schema":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"}},{"name":"min_sample_size","in":"query","required":false,"description":"A month's figures are null when fewer projects than this have a usable month.","schema":{"default":3,"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Units allowed per minute.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Units left this minute.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-Request-Units":{"description":"Units this request cost.","schema":{"type":"integer"}},"X-Quota-Limit":{"description":"Units allowed this calendar month (UTC). Absent on unlimited plans.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Units left this calendar month (UTC). Absent on unlimited plans. Reads `0` once a plan with overage is past its quota and still serving.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Seconds until the monthly quota resets. Absent on unlimited plans.","schema":{"type":"integer"}},"X-Resolved-City":{"description":"The covered city slug the request's `city` was resolved to, when it differs from what was sent (`city=dammam` answers for `eastern_province`). Absent when the slug was sent as is.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"filters":{"type":"object","properties":{"city":{"type":["string","null"]},"neighborhood_ids":{"anyOf":[{"type":"array","items":{"type":"integer"}},{"type":"null"}]},"developer":{"example":"Retal Urban Development","type":["string","null"]},"property_type":{"example":"apartment","type":["string","null"]},"project_type":{"example":"ready","type":["string","null"]}},"required":["city","neighborhood_ids","developer","property_type","project_type"],"additionalProperties":false},"listing_type":{"type":"string","enum":["sale","rent","all"]},"group_by":{"type":"string","enum":["city","neighborhood","developer","property_type","project_type"]},"from":{"type":"string"},"to":{"type":"string"},"min_sample_size":{"type":"integer"},"projects_ungrouped":{"type":"integer"},"groups":{"type":"array","items":{"type":"object","properties":{"city":{"description":"City slug.","example":"riyadh","type":["string","null"]},"neighborhood_id":{"anyOf":[{"type":"integer"},{"type":"null"}]},"neighborhood_name_ar":{"type":["string","null"]},"neighborhood_name_en":{"type":["string","null"]},"developer":{"example":"Retal Urban Development","type":["string","null"]},"property_type":{"description":"The most common property type among the project's units listed on Kite (with `group_by=property_type`).","type":["string","null"]},"project_type":{"description":"`off_plan` or `ready`.","example":"ready","type":["string","null"]},"projects_tracked":{"type":"integer","description":"Projects in the group with an inventory reading in the range."},"projects_with_usable_month":{"type":"integer"},"months":{"type":"array","items":{"type":"object","properties":{"month":{"type":"string","example":"2026-10"},"projects_observed":{"type":"integer","description":"Projects in the group with a reading in the month."},"projects_usable":{"type":"integer","description":"Of those, projects whose month is `usable`; the figures below pool only these."},"start_available":{"anyOf":[{"type":"integer"},{"type":"null"}]},"end_available":{"anyOf":[{"type":"integer"},{"type":"null"}]},"units_gone":{"anyOf":[{"type":"integer"},{"type":"null"}]},"units_released":{"anyOf":[{"type":"integer"},{"type":"null"}]},"units_re_added":{"anyOf":[{"type":"integer"},{"type":"null"}]},"absorption_rate":{"description":"Pooled: units gone ÷ units on offer at the start, over the usable projects.","type":["number","null"]},"median_project_absorption_rate":{"description":"Median of the usable projects' own absorption rates.","type":["number","null"]},"units_gone_per_month":{"description":"Sum of the usable projects' monthly paces.","type":["number","null"]},"months_of_stock":{"description":"`end_available` ÷ `units_gone_per_month`. Null when nothing went.","type":["number","null"]},"flagged":{"type":"object","properties":{"gap":{"type":"integer"},"withdrawal":{"type":"integer"},"source_change":{"type":"integer"},"released":{"type":"integer"},"units_removed":{"type":"integer"},"series_starts_mid_month":{"type":"integer"},"series_ends_mid_month":{"type":"integer"},"project_inactive":{"type":"integer"},"month_in_progress":{"type":"integer"},"no_inventory":{"type":"integer"},"no_observations":{"type":"integer"}},"required":["gap","withdrawal","source_change","released","units_removed","series_starts_mid_month","series_ends_mid_month","project_inactive","month_in_progress","no_inventory","no_observations"],"additionalProperties":false,"description":"Projects whose month carries each flag (see GET /projects/{id}/absorption)."}},"required":["month","projects_observed","projects_usable","start_available","end_available","units_gone","units_released","units_re_added","absorption_rate","median_project_absorption_rate","units_gone_per_month","months_of_stock","flagged"],"additionalProperties":false}}},"required":["city","neighborhood_id","neighborhood_name_ar","neighborhood_name_en","developer","property_type","project_type","projects_tracked","projects_with_usable_month","months"],"additionalProperties":false}}},"required":["filters","listing_type","group_by","from","to","min_sample_size","projects_ungrouped","groups"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"filters":{"city":"riyadh","neighborhood_ids":[342],"developer":"Retal Urban Development","property_type":"apartment","project_type":"ready"},"listing_type":"sale","group_by":"city","from":"2026-06-01","to":"2026-09-21","min_sample_size":5,"projects_ungrouped":0,"groups":[{"city":"riyadh","neighborhood_id":null,"neighborhood_name_ar":"الملقا","neighborhood_name_en":"Al Malqa","developer":"Retal Urban Development","property_type":"apartment","project_type":"ready","projects_tracked":0,"projects_with_usable_month":0,"months":[{"month":"2026-10","projects_observed":0,"projects_usable":0,"start_available":null,"end_available":null,"units_gone":null,"units_released":null,"units_re_added":null,"absorption_rate":0,"median_project_absorption_rate":0,"units_gone_per_month":0,"months_of_stock":0,"flagged":{"gap":0,"withdrawal":0,"source_change":0,"released":0,"units_removed":0,"series_starts_mid_month":0,"series_ends_mid_month":0,"project_inactive":0,"month_in_progress":0,"no_inventory":0,"no_observations":0}}]}]}}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/exports":{"post":{"operationId":"exports.create","summary":"Create an export","description":"Starts an export of a whole dataset as files, for loading into a warehouse. Exports run in the background: poll GET /exports/{export_id} until `status` is `completed`, then download every file in `files` (links last an hour; GET again for fresh ones).\n\n**Datasets**\n\n- `listings`: every active listing matching `filters`, one row per listing in the shape GET /listings returns. Needs the `exports` scope (Enterprise).\n- `listing_changes`: what happened to listings between `filters.from` and `filters.to` (at most 366 days): `created`, `price_changed` (every change, with the price before and after) and `delisted` events, each with the listing as it is now. History begins 2026-03-09. Needs the `exports` scope.\n- `registered_transactions`: the Ministry of Justice's registered sale deals, rows as GET /transactions returns them. **Free on every plan**, open data under the Saudi Open Data License; ATTRIBUTION.txt comes with the files and must travel with the data.\n- `registered_rents`: REGA's rent index cells, as GET /market/registered-rents serves them (cells under 5 contracts withheld). **Free on every plan**, with ATTRIBUTION.txt.\n- `aggregate_layers`: asking rent and sale price quartiles, per-m² quartiles, listing counts and gross yield per city or neighborhood, property type and bedroom bucket, from the current market sample. No figure rests on fewer than 10 listings, amounts are rounded, and there are no minimums, maximums or listing ids. One CSV and one GeoJSON file, each stamped with `methodology_version` and `release_id`; `format` and `compression` are fixed. **In no plan**: Kite enables it for an organization that has signed an aggregate redistribution order form. No units are charged.\n\n**Files.** Data comes in parts of up to 25,000 rows (`part-00001.ndjson.gz`, …); each part stands alone (a CSV part repeats the header). NDJSON rows are exactly the API's objects; CSV flattens them into dotted columns (`price.yearly_sar`) with arrays as JSON. `manifest.json` lists the parts, row counts, columns, filters, licence and notes. Files are deleted 7 days after the export completes.\n\n**Cost.** Listing datasets are counted before anything is written and charged 1000 units per 1,000 rows, once, against your monthly quota (not the per-minute rate); `units` on the export shows the charge. If the quota, spend cap or project cap can't cover it, the export fails with nothing charged. Open-data exports cost nothing.\n\n**Limits.** 2 exports queued or running at once and 20 a day per organization (`export_limit`); 2,000,000 rows per export (split larger ones by city, listing type or range). Send an `Idempotency-Key` to make a retried POST safe.","tags":["Exports"],"x-scope":"reference","x-units":0,"x-units-note":"Free to call. A `listings` or `listing_changes` export is charged 1000 units per 1,000 rows (at least 1000) once its rows are counted; open-data exports are free","security":[{"apiKey":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"A unique string (a UUID is ideal) making this call safe to retry. The same key with the same body replays the first response and sets `Idempotent-Replay: true`; with a different body it returns `409 idempotency_key_reuse`. Remembered for 24 hours.","schema":{"type":"string","maxLength":255},"example":"8f14e45f-ea6a-4cbb-9a2f-3d1c0b7e21aa"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportRequest"}}}},"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Units allowed per minute.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Units left this minute.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-Request-Units":{"description":"Units this request cost.","schema":{"type":"integer"}},"X-Quota-Limit":{"description":"Units allowed this calendar month (UTC). Absent on unlimited plans.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Units left this calendar month (UTC). Absent on unlimited plans. Reads `0` once a plan with overage is past its quota and still serving.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Seconds until the monthly quota resets. Absent on unlimited plans.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Export"}},"required":["data"],"additionalProperties":false},"example":{"data":{"id":"exp_Q2hsYXVkZUV4cG9ydA","dataset":"listings","format":"ndjson","compression":"gzip","status":"queued","filters":{},"price_source":"asking","rows_estimated":null,"row_count":null,"units":3200,"progress":{"rows_written":25000,"parts_written":1},"error":{"code":"export_failed","message":"The export could not be completed. Start it again."},"attribution":{"notice":"Contains information from \"الصفقات العقارية\" (Real estate transactions, Ministry of Justice, open.data.gov.sa; links in `datasets`), which is made available under the ODC Attribution License, as adapted by the Open Data License of the Kingdom of Saudi Arabia.","license_url":"https://open.data.gov.sa/en/pages/policies/license"},"files":[{"name":"part-00001.ndjson.gz","kind":"data","rows":null,"bytes":1048576,"url":"https://downloads.example.com/exp_Q2hsYXVkZUV4cG9ydA/part-0001.jsonl.gz","url_expires_at":"2026-09-21T10:00:00.000Z"}],"created_at":"2026-09-21T10:00:00.000Z","started_at":"2026-09-21T10:00:00.000Z","completed_at":"2026-09-21T10:00:00.000Z","expires_at":"2026-09-21T10:00:00.000Z"}}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Clashes with the current state, or an `Idempotency-Key` was reused with a different body.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"exports.list","summary":"List exports","description":"Your organization's exports, newest first, without download links (GET one export for those). Records are kept 90 days. A test key sees only exports made with test keys.","tags":["Exports"],"x-scope":"reference","x-units":0,"security":[{"apiKey":[]}],"parameters":[{"name":"limit","in":"query","required":false,"description":"Default 20.","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Units allowed per minute.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Units left this minute.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-Request-Units":{"description":"Units this request cost.","schema":{"type":"integer"}},"X-Quota-Limit":{"description":"Units allowed this calendar month (UTC). Absent on unlimited plans.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Units left this calendar month (UTC). Absent on unlimited plans. Reads `0` once a plan with overage is past its quota and still serving.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Seconds until the monthly quota resets. Absent on unlimited plans.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Export"}}},"required":["data"],"additionalProperties":false},"example":{"data":[{"id":"exp_Q2hsYXVkZUV4cG9ydA","dataset":"listings","format":"ndjson","compression":"gzip","status":"queued","filters":{},"price_source":"asking","rows_estimated":null,"row_count":null,"units":3200,"progress":{"rows_written":25000,"parts_written":1},"error":{"code":"export_failed","message":"The export could not be completed. Start it again."},"attribution":{"notice":"Contains information from \"الصفقات العقارية\" (Real estate transactions, Ministry of Justice, open.data.gov.sa; links in `datasets`), which is made available under the ODC Attribution License, as adapted by the Open Data License of the Kingdom of Saudi Arabia.","license_url":"https://open.data.gov.sa/en/pages/policies/license"},"files":[{"name":"part-00001.ndjson.gz","kind":"data","rows":null,"bytes":1048576,"url":"https://downloads.example.com/exp_Q2hsYXVkZUV4cG9ydA/part-0001.jsonl.gz","url_expires_at":"2026-09-21T10:00:00.000Z"}],"created_at":"2026-09-21T10:00:00.000Z","started_at":"2026-09-21T10:00:00.000Z","completed_at":"2026-09-21T10:00:00.000Z","expires_at":"2026-09-21T10:00:00.000Z"}]}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/exports/{export_id}":{"get":{"operationId":"exports.get","summary":"Get an export","description":"An export's status and, once `completed`, a signed download link for every file, valid for 60 minutes; call again for fresh links. Poll every few seconds to a minute: an export starts within about a minute and a full listings snapshot takes a few minutes.","tags":["Exports"],"x-scope":"reference","x-units":0,"security":[{"apiKey":[]}],"parameters":[{"name":"export_id","in":"path","required":true,"schema":{"type":"string","maxLength":64}}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Units allowed per minute.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Units left this minute.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the minute window resets.","schema":{"type":"integer"}},"X-Request-Units":{"description":"Units this request cost.","schema":{"type":"integer"}},"X-Quota-Limit":{"description":"Units allowed this calendar month (UTC). Absent on unlimited plans.","schema":{"type":"integer"}},"X-Quota-Remaining":{"description":"Units left this calendar month (UTC). Absent on unlimited plans. Reads `0` once a plan with overage is past its quota and still serving.","schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Seconds until the monthly quota resets. Absent on unlimited plans.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Export"}},"required":["data"],"additionalProperties":false},"example":{"data":{"id":"exp_Q2hsYXVkZUV4cG9ydA","dataset":"listings","format":"ndjson","compression":"gzip","status":"queued","filters":{},"price_source":"asking","rows_estimated":null,"row_count":null,"units":3200,"progress":{"rows_written":25000,"parts_written":1},"error":{"code":"export_failed","message":"The export could not be completed. Start it again."},"attribution":{"notice":"Contains information from \"الصفقات العقارية\" (Real estate transactions, Ministry of Justice, open.data.gov.sa; links in `datasets`), which is made available under the ODC Attribution License, as adapted by the Open Data License of the Kingdom of Saudi Arabia.","license_url":"https://open.data.gov.sa/en/pages/policies/license"},"files":[{"name":"part-00001.ndjson.gz","kind":"data","rows":null,"bytes":1048576,"url":"https://downloads.example.com/exp_Q2hsYXVkZUV4cG9ydA/part-0001.jsonl.gz","url_expires_at":"2026-09-21T10:00:00.000Z"}],"created_at":"2026-09-21T10:00:00.000Z","started_at":"2026-09-21T10:00:00.000Z","completed_at":"2026-09-21T10:00:00.000Z","expires_at":"2026-09-21T10:00:00.000Z"}}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/organization":{"get":{"operationId":"organization.get","summary":"Get your organization","description":"Name, plan and limits, and this month's usage.","tags":["Administration"],"x-scope":"organization","x-units":0,"security":[{"adminKey":[]}],"parameters":[],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string","enum":["active","suspended"]},"plan":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"rate_limit_per_minute":{"type":"integer"},"monthly_quota_units":{"anyOf":[{"type":"integer"},{"type":"null"}]},"max_page_size":{"type":"integer"},"max_active_keys":{"type":"integer"}},"required":["id","name","scopes","rate_limit_per_minute","monthly_quota_units","max_page_size","max_active_keys"],"additionalProperties":false},"usage":{"type":"object","properties":{"month_units":{"type":"integer"},"resets_in_seconds":{"type":"integer"}},"required":["month_units","resets_in_seconds"],"additionalProperties":false}},"required":["id","name","slug","status","plan","usage"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"id":"org_9Qd4zL7pC2hV5sX8jF1m","name":"Example Proptech","slug":"example-proptech","status":"active","plan":{"id":"growth","name":"Growth","scopes":["listings:read"],"rate_limit_per_minute":1500,"monthly_quota_units":null,"max_page_size":100,"max_active_keys":10},"usage":{"month_units":48210,"resets_in_seconds":1209600}}}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/organization/keys":{"get":{"operationId":"organization.keys.list","summary":"List data keys","description":"Active data keys (`dk_live_…`). Secrets are never returned after creation.","tags":["Administration"],"x-scope":"organization","x-units":0,"security":[{"adminKey":[]}],"parameters":[],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"key_7Fh2kQ9cV1xZ3mB8nL0p"},"name":{"type":"string"},"hint":{"type":"string","description":"Last characters of the key","example":"dk_live_…a1b2"},"project_id":{"type":"string"},"scopes":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"APIs the key may call; null = every API on the plan."},"expires_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","example":"2026-09-21T10:00:00.000Z","description":"ISO 8601 time"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","example":"2026-09-21T10:00:00.000Z","description":"ISO 8601 time"},"last_used_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","example":"2026-09-21T10:00:00.000Z","description":"ISO 8601 time"},{"type":"null"}],"description":"Updated at most hourly."}},"required":["id","name","hint","project_id","scopes","expires_at","created_at","last_used_at"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false},"example":{"data":[{"id":"key_7Fh2kQ9cV1xZ3mB8nL0p","name":"Production","hint":"dk_live_…a1b2","project_id":"proj_5Rk1wU8eA3tG6yN0bM2x","scopes":["listings:read"],"expires_at":"2026-09-21T10:00:00.000Z","created_at":"2026-09-21T10:00:00.000Z","last_used_at":"2026-09-21T10:00:00.000Z"}]}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"organization.keys.create","summary":"Create a data key","description":"Creates a `dk_live_…` key. The secret is in the response once: store it now. Counts toward your plan's active-key limit.","tags":["Administration"],"x-scope":"organization","x-units":0,"security":[{"adminKey":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"A unique string (a UUID is ideal) making this call safe to retry. The same key with the same body replays the first response and sets `Idempotent-Replay: true`; with a different body it returns `409 idempotency_key_reuse`. Remembered for 24 hours.","schema":{"type":"string","maxLength":255},"example":"8f14e45f-ea6a-4cbb-9a2f-3d1c0b7e21aa"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60},"project_id":{"description":"Defaults to your first project.","type":"string","maxLength":64},"scopes":{"description":"Limit the key to these APIs; omit for every API on your plan.","maxItems":20,"type":"array","items":{"type":"string"}},"expires_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["name"]}}}},"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"key":{"type":"string","description":"The secret. Shown once."},"hint":{"type":"string"}},"required":["id","name","key","hint"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"id":"key_7Fh2kQ9cV1xZ3mB8nL0p","name":"Production","key":"dk_live_EXAMPLE_shown_once_at_creation","hint":"dk_live_…a1b2"}}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Clashes with the current state, or an `Idempotency-Key` was reused with a different body.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/organization/keys/{key_id}/revoke":{"post":{"operationId":"organization.keys.revoke","summary":"Revoke a key","description":"Requests with the key are rejected right away. An admin key can revoke itself.","tags":["Administration"],"x-scope":"organization","x-units":0,"security":[{"adminKey":[]}],"parameters":[{"name":"key_id","in":"path","required":true,"schema":{"type":"string","maxLength":64}},{"name":"Idempotency-Key","in":"header","required":false,"description":"A unique string (a UUID is ideal) making this call safe to retry. The same key with the same body replays the first response and sets `Idempotent-Replay: true`; with a different body it returns `409 idempotency_key_reuse`. Remembered for 24 hours.","schema":{"type":"string","maxLength":255},"example":"8f14e45f-ea6a-4cbb-9a2f-3d1c0b7e21aa"}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"revoked":{"type":"boolean","const":true}},"required":["id","revoked"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"id":"key_7Fh2kQ9cV1xZ3mB8nL0p","revoked":true}}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Clashes with the current state, or an `Idempotency-Key` was reused with a different body.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/organization/projects":{"get":{"operationId":"organization.projects.list","summary":"List projects","description":"The projects this organization's keys belong to. A project groups keys and can carry its own monthly unit cap, so usage can be attributed to one product or environment.","tags":["Administration"],"x-scope":"organization","x-units":0,"security":[{"adminKey":[]}],"parameters":[],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"monthly_unit_cap":{"anyOf":[{"type":"integer"},{"type":"null"}]},"active_keys":{"type":"integer"},"month_units":{"type":"integer"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","example":"2026-09-21T10:00:00.000Z","description":"ISO 8601 time"}},"required":["id","name","monthly_unit_cap","active_keys","month_units","created_at"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false},"example":{"data":[{"id":"proj_5Rk1wU8eA3tG6yN0bM2x","name":"Mobile app","monthly_unit_cap":null,"active_keys":2,"month_units":48210,"created_at":"2026-09-21T10:00:00.000Z"}]}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/organization/usage":{"get":{"operationId":"organization.usage","summary":"Daily usage","description":"Requests and units per UTC day, key, endpoint and result class, for the last 7, 30 or 90 days.","tags":["Administration"],"x-scope":"organization","x-units":0,"security":[{"adminKey":[]}],"parameters":[{"name":"days","in":"query","required":false,"description":"Default 30.","schema":{"type":"string","enum":["7","30","90"]}}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"day":{"type":"string","example":"2026-09-21"},"key_id":{"description":"null for dashboard playground calls","type":["string","null"]},"endpoint":{"type":"string","example":"listings.search"},"status_class":{"type":"integer","description":"2, 4 or 5"},"requests":{"type":"integer"},"units":{"type":"integer"}},"required":["day","key_id","endpoint","status_class","requests","units"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false},"example":{"data":[{"day":"2026-09-21","key_id":"key_7Fh2kQ9cV1xZ3mB8nL0p","endpoint":"listings.search","status_class":2,"requests":1280,"units":3200}]}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/organization/members":{"get":{"operationId":"organization.members.list","summary":"List members and invitations","description":"Everyone with access to this organization and every invitation not yet accepted, with each person's role.","tags":["Administration"],"x-scope":"organization","x-units":0,"security":[{"adminKey":[]}],"parameters":[],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"members":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string"},"name":{"type":["string","null"]},"role":{"type":"string","enum":["owner","admin","member"]},"joined_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","example":"2026-09-21T10:00:00.000Z","description":"ISO 8601 time"}},"required":["email","name","role","joined_at"],"additionalProperties":false}},"invitations":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string"},"role":{"type":"string","enum":["owner","admin","member"]},"expires_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","example":"2026-09-21T10:00:00.000Z","description":"ISO 8601 time"}},"required":["email","role","expires_at"],"additionalProperties":false}}},"required":["members","invitations"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"members":[{"email":"amal@example.com","name":"Amal Al-Harbi","role":"owner","joined_at":"2026-09-21T10:00:00.000Z"}],"invitations":[{"email":"amal@example.com","role":"owner","expires_at":"2026-09-21T10:00:00.000Z"}]}}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/organization/audit-events":{"get":{"operationId":"organization.audit_events.list","summary":"List audit events","description":"Newest first, 50 per page. Pass `next_cursor` back as `cursor` for older events.","tags":["Administration"],"x-scope":"organization","x-units":0,"security":[{"adminKey":[]}],"parameters":[{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":256}}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"action":{"type":"string","example":"key.created"},"target":{"type":["string","null"]},"actor":{"description":"Email of the person, or null for Kite or an admin key","type":["string","null"]},"actor_key_id":{"type":["string","null"]},"ip":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","example":"2026-09-21T10:00:00.000Z","description":"ISO 8601 time"}},"required":["action","target","actor","actor_key_id","ip","created_at"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"next_cursor":{"type":["string","null"]},"has_more":{"type":"boolean"}},"required":["next_cursor","has_more"],"additionalProperties":false}},"required":["data","pagination"],"additionalProperties":false},"example":{"data":[{"action":"key.created","target":"key_7Fh2kQ9cV1xZ3mB8nL0p","actor":"amal@example.com","actor_key_id":"key_7Fh2kQ9cV1xZ3mB8nL0p","ip":"203.0.113.24","created_at":"2026-09-21T10:00:00.000Z"}],"pagination":{"next_cursor":"eyJvIjoxMDB9","has_more":true}}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/organization/request-logs":{"get":{"operationId":"organization.request_logs.list","summary":"List request logs","description":"Calls this organization made, newest first, within its retention window (7, 30 or 90 days, set on the Settings page). Filter by `request_id` to look up one call — that ignores every other filter. Rows carry no parameters, IP or user agent for organizations that turn off request details.","tags":["Administration"],"x-scope":"organization","x-units":0,"security":[{"adminKey":[]}],"parameters":[{"name":"request_id","in":"query","required":false,"description":"One exact call. Overrides the other filters.","example":"req_4f1c2d9a8b7e6f5a4b3c2d1e","schema":{"type":"string","maxLength":64}},{"name":"key_id","in":"query","required":false,"description":"Only calls made with this key.","schema":{"type":"string","maxLength":64}},{"name":"route","in":"query","required":false,"description":"Endpoint id, as in the reference.","example":"listings.search","schema":{"type":"string","maxLength":64}},{"name":"status","in":"query","required":false,"description":"`errors` is anything at or above 400.","schema":{"type":"string","enum":["errors","2xx","4xx","5xx"]}},{"name":"since","in":"query","required":false,"schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},{"name":"until","in":"query","required":false,"schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},{"name":"limit","in":"query","required":false,"description":"Default 25.","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":500}}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"request_id":{"description":"Quote this to support.","type":["string","null"]},"at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","example":"2026-09-21T10:00:00.000Z"},"route":{"type":"string","example":"listings.search"},"status":{"type":"integer","example":200},"units":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"0 for anything that wasn't a 2xx."},"duration_ms":{"type":"integer","example":84},"key_id":{"description":"Null for calls made from the dashboard.","type":["string","null"]},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string","example":"invalid_value"},"message":{"description":"Null when the org stores no request details.","type":["string","null"]},"param":{"type":["string","null"]}},"required":["code","message","param"],"additionalProperties":false},{"type":"null"}],"description":"Present only on a failure."},"params":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}],"description":"The filters as sent, redacted. Null when details aren't stored."}},"required":["request_id","at","route","status","units","duration_ms","key_id","error","params"],"additionalProperties":false}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"],"additionalProperties":false},"example":{"data":[{"request_id":"req_4f1c2d9a8b7e6f5a4b3c2d1e","at":"2026-09-21T10:00:00.000Z","route":"listings.search","status":200,"units":null,"duration_ms":84,"key_id":"key_7Fh2kQ9cV1xZ3mB8nL0p","error":{"code":"invalid_value","message":"The export could not be completed. Start it again.","param":"city"},"params":{}}],"pagination":{"limit":25,"next_cursor":"eyJvIjoyNSwiZiI6IksweTFfU1F3d1BXSiJ9.pkFEfJUOpRbZRS279EDC4v","has_more":true,"result_window_reached":false}}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/organization/webhooks":{"post":{"operationId":"organization.webhooks.create","summary":"Create a webhook endpoint","description":"Subscribes an HTTPS URL to listing events. The signing secret is in the response once: store it now, you'll need it to verify deliveries. Filters must include a city.","tags":["Administration"],"x-scope":"organization","x-units":0,"security":[{"adminKey":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"A unique string (a UUID is ideal) making this call safe to retry. The same key with the same body replays the first response and sets `Idempotent-Replay: true`; with a different body it returns `409 idempotency_key_reuse`. Remembered for 24 hours.","schema":{"type":"string","maxLength":255},"example":"8f14e45f-ea6a-4cbb-9a2f-3d1c0b7e21aa"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","maxLength":500,"format":"uri","example":"https://example.com/kite-webhook"},"event_types":{"minItems":1,"type":"array","items":{"type":"string","enum":["listing.created","listing.price_changed","listing.delisted"]},"description":"See the webhooks guide.","example":["listing.created"]},"filters":{"type":"object","properties":{"city":{"description":"City slug from GET /cities. A town inside a covered region is accepted and resolved to its city (`dammam`, `khobar`, `dhahran`, `jubail` and `qatif` to `eastern_province`; `buraydah` and `unaizah` to `qassim`; `hofuf` to `al_ahsa`), as are Arabic city names. The response's `filters.city` and the `X-Resolved-City` header show the slug used.","example":"riyadh","type":"string","pattern":"^[a-z_]+$"},"listing_type":{"type":"string","enum":["rent","sale"]},"listing_category":{"type":"string","enum":["residential","commercial"]},"property_type":{"type":"string","maxLength":40},"neighborhood":{"type":"string","maxLength":200},"beds":{"type":"string","maxLength":10},"beds_min":{"type":"string","maxLength":10},"price_min":{"type":"string","maxLength":20},"price_max":{"type":"string","maxLength":20},"area_min":{"type":"string","maxLength":20},"area_max":{"type":"string","maxLength":20},"zoning":{"type":"string","maxLength":200,"pattern":"^(residential|commercial|mixed|industrial|agricultural|public|other)(,(residential|commercial|mixed|industrial|agricultural|public|other))*$"},"corner":{"type":"string","enum":["true","false"]},"street_width_min":{"type":"string","maxLength":10,"pattern":"^\\d{1,3}(\\.\\d+)?$"},"white_land_fee":{"type":"string","enum":["true","false"]},"last_sale_within_months":{"type":"string","pattern":"^\\d{1,3}$"},"ask_to_last_sale_max":{"type":"string","maxLength":10,"pattern":"^\\d{1,2}(\\.\\d+)?$"},"plot_sold":{"type":"string","enum":["true","false"]}},"required":["city"],"additionalProperties":false,"description":"Which listings this endpoint wants, in the vocabulary of GET /listings. The plot filters (`zoning`, `corner`, `street_width_min`, `white_land_fee`, `last_sale_within_months`, `ask_to_last_sale_max`) match a listing's `plot`; for `listing.delisted` they match only while the delisted listing's plot facts are still on record, which is until the next scrape. `plot_sold` matches the sale itself (see `plot.registered_sale_while_listed`), which stays on record after a listing is delisted."},"description":{"type":"string","maxLength":200}},"required":["url","event_types","filters"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","example":"whe_7Fh2kQ9cV1xZ"},"url":{"type":"string"},"event_types":{"type":"array","items":{"type":"string"},"example":["listing.created"]},"filters":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"description":{"type":["string","null"]},"status":{"type":"string","enum":["active","disabled"]},"disabled_reason":{"description":"`too_many_failures` when we stopped after repeated failures.","type":["string","null"]},"consecutive_failures":{"type":"integer"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","example":"2026-09-21T10:00:00.000Z","description":"ISO 8601 time"},"secret":{"type":"string","description":"The signing secret. Shown once."}},"required":["id","url","event_types","filters","description","status","disabled_reason","consecutive_failures","created_at","secret"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"id":"whe_7Fh2kQ9cV1xZ","url":"https://example.com/kite-webhook","event_types":["listing.created"],"filters":{},"description":"Price changes to the CRM","status":"active","disabled_reason":"Disabled after 20 consecutive failed deliveries.","consecutive_failures":0,"created_at":"2026-09-21T10:00:00.000Z","secret":"whsec_EXAMPLE_shown_once_at_creation"}}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Clashes with the current state, or an `Idempotency-Key` was reused with a different body.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"organization.webhooks.list","summary":"List webhook endpoints","description":"Every endpoint this organization has subscribed. Secrets are never returned.","tags":["Administration"],"x-scope":"organization","x-units":0,"security":[{"adminKey":[]}],"parameters":[],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"whe_7Fh2kQ9cV1xZ"},"url":{"type":"string"},"event_types":{"type":"array","items":{"type":"string"},"example":["listing.created"]},"filters":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"description":{"type":["string","null"]},"status":{"type":"string","enum":["active","disabled"]},"disabled_reason":{"description":"`too_many_failures` when we stopped after repeated failures.","type":["string","null"]},"consecutive_failures":{"type":"integer"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","example":"2026-09-21T10:00:00.000Z","description":"ISO 8601 time"}},"required":["id","url","event_types","filters","description","status","disabled_reason","consecutive_failures","created_at"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false},"example":{"data":[{"id":"whe_7Fh2kQ9cV1xZ","url":"https://example.com/kite-webhook","event_types":["listing.created"],"filters":{},"description":"Price changes to the CRM","status":"active","disabled_reason":"Disabled after 20 consecutive failed deliveries.","consecutive_failures":0,"created_at":"2026-09-21T10:00:00.000Z"}]}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/organization/webhooks/{webhook_id}/update":{"post":{"operationId":"organization.webhooks.update","summary":"Update a webhook endpoint","description":"Changes the URL, event types, filters or description of an endpoint; send only what changes. History and the signing secret are kept, and so is the position of every event type that stays subscribed. An event type you add starts from now and does not replay listings from before the change. Removing a type drops its position, so adding it back also starts from now. New filters apply to events not yet queued. Does not re-enable a disabled endpoint: use the enable call.","tags":["Administration"],"x-scope":"organization","x-units":0,"security":[{"adminKey":[]}],"parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","maxLength":64}},{"name":"Idempotency-Key","in":"header","required":false,"description":"A unique string (a UUID is ideal) making this call safe to retry. The same key with the same body replays the first response and sets `Idempotent-Replay: true`; with a different body it returns `409 idempotency_key_reuse`. Remembered for 24 hours.","schema":{"type":"string","maxLength":255},"example":"8f14e45f-ea6a-4cbb-9a2f-3d1c0b7e21aa"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","maxLength":500,"format":"uri"},"event_types":{"minItems":1,"type":"array","items":{"type":"string","enum":["listing.created","listing.price_changed","listing.delisted"]}},"filters":{"type":"object","properties":{"city":{"description":"City slug from GET /cities. A town inside a covered region is accepted and resolved to its city (`dammam`, `khobar`, `dhahran`, `jubail` and `qatif` to `eastern_province`; `buraydah` and `unaizah` to `qassim`; `hofuf` to `al_ahsa`), as are Arabic city names. The response's `filters.city` and the `X-Resolved-City` header show the slug used.","example":"riyadh","type":"string","pattern":"^[a-z_]+$"},"listing_type":{"type":"string","enum":["rent","sale"]},"listing_category":{"type":"string","enum":["residential","commercial"]},"property_type":{"type":"string","maxLength":40},"neighborhood":{"type":"string","maxLength":200},"beds":{"type":"string","maxLength":10},"beds_min":{"type":"string","maxLength":10},"price_min":{"type":"string","maxLength":20},"price_max":{"type":"string","maxLength":20},"area_min":{"type":"string","maxLength":20},"area_max":{"type":"string","maxLength":20},"zoning":{"type":"string","maxLength":200,"pattern":"^(residential|commercial|mixed|industrial|agricultural|public|other)(,(residential|commercial|mixed|industrial|agricultural|public|other))*$"},"corner":{"type":"string","enum":["true","false"]},"street_width_min":{"type":"string","maxLength":10,"pattern":"^\\d{1,3}(\\.\\d+)?$"},"white_land_fee":{"type":"string","enum":["true","false"]},"last_sale_within_months":{"type":"string","pattern":"^\\d{1,3}$"},"ask_to_last_sale_max":{"type":"string","maxLength":10,"pattern":"^\\d{1,2}(\\.\\d+)?$"},"plot_sold":{"type":"string","enum":["true","false"]}},"required":["city"],"additionalProperties":false,"description":"Which listings this endpoint wants, in the vocabulary of GET /listings. The plot filters (`zoning`, `corner`, `street_width_min`, `white_land_fee`, `last_sale_within_months`, `ask_to_last_sale_max`) match a listing's `plot`; for `listing.delisted` they match only while the delisted listing's plot facts are still on record, which is until the next scrape. `plot_sold` matches the sale itself (see `plot.registered_sale_while_listed`), which stays on record after a listing is delisted."},"description":{"description":"Null clears it.","anyOf":[{"type":"string","maxLength":200},{"type":"null"}]}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","example":"whe_7Fh2kQ9cV1xZ"},"url":{"type":"string"},"event_types":{"type":"array","items":{"type":"string"},"example":["listing.created"]},"filters":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"description":{"type":["string","null"]},"status":{"type":"string","enum":["active","disabled"]},"disabled_reason":{"description":"`too_many_failures` when we stopped after repeated failures.","type":["string","null"]},"consecutive_failures":{"type":"integer"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","example":"2026-09-21T10:00:00.000Z","description":"ISO 8601 time"}},"required":["id","url","event_types","filters","description","status","disabled_reason","consecutive_failures","created_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"id":"whe_7Fh2kQ9cV1xZ","url":"https://example.com/kite-webhook","event_types":["listing.created"],"filters":{},"description":"Price changes to the CRM","status":"active","disabled_reason":"Disabled after 20 consecutive failed deliveries.","consecutive_failures":0,"created_at":"2026-09-21T10:00:00.000Z"}}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Clashes with the current state, or an `Idempotency-Key` was reused with a different body.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/organization/webhooks/{webhook_id}/enable":{"post":{"operationId":"organization.webhooks.enable","summary":"Re-enable a webhook endpoint","description":"Turns a disabled endpoint back on and resets its failure count. Events that matched while it was off are queued from its watermark, so none are lost (at most 500 per run). Deliveries that already failed stay failed: replay them. Enabling an active endpoint only resets its failure count.","tags":["Administration"],"x-scope":"organization","x-units":0,"security":[{"adminKey":[]}],"parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","maxLength":64}},{"name":"Idempotency-Key","in":"header","required":false,"description":"A unique string (a UUID is ideal) making this call safe to retry. The same key with the same body replays the first response and sets `Idempotent-Replay: true`; with a different body it returns `409 idempotency_key_reuse`. Remembered for 24 hours.","schema":{"type":"string","maxLength":255},"example":"8f14e45f-ea6a-4cbb-9a2f-3d1c0b7e21aa"}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","example":"whe_7Fh2kQ9cV1xZ"},"url":{"type":"string"},"event_types":{"type":"array","items":{"type":"string"},"example":["listing.created"]},"filters":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"description":{"type":["string","null"]},"status":{"type":"string","enum":["active","disabled"]},"disabled_reason":{"description":"`too_many_failures` when we stopped after repeated failures.","type":["string","null"]},"consecutive_failures":{"type":"integer"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","example":"2026-09-21T10:00:00.000Z","description":"ISO 8601 time"}},"required":["id","url","event_types","filters","description","status","disabled_reason","consecutive_failures","created_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"id":"whe_7Fh2kQ9cV1xZ","url":"https://example.com/kite-webhook","event_types":["listing.created"],"filters":{},"description":"Price changes to the CRM","status":"active","disabled_reason":"Disabled after 20 consecutive failed deliveries.","consecutive_failures":0,"created_at":"2026-09-21T10:00:00.000Z"}}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Clashes with the current state, or an `Idempotency-Key` was reused with a different body.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/organization/webhooks/{webhook_id}/rotate-secret":{"post":{"operationId":"organization.webhooks.rotate_secret","summary":"Rotate a webhook signing secret","description":"Issues a new signing secret, shown once in the response. For `overlap_seconds` (default 86400, up to 7 days; 0 for none) every delivery carries a signature for both the new and the previous secret, so a receiver holding either one can verify during the overlap. A receiver must accept the header if any `v1` entry matches: the new secret's entry comes first, so a parser that reads only the last `v1` gets the previous secret's signature until the overlap ends. After a leak, use 0. Rotating again during an overlap drops the older secret.","tags":["Administration"],"x-scope":"organization","x-units":0,"security":[{"adminKey":[]}],"parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","maxLength":64}},{"name":"Idempotency-Key","in":"header","required":false,"description":"A unique string (a UUID is ideal) making this call safe to retry. The same key with the same body replays the first response and sets `Idempotent-Replay: true`; with a different body it returns `409 idempotency_key_reuse`. Remembered for 24 hours.","schema":{"type":"string","maxLength":255},"example":"8f14e45f-ea6a-4cbb-9a2f-3d1c0b7e21aa"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"overlap_seconds":{"description":"How long the previous secret keeps signing. Default 86400.","type":"integer","minimum":0,"maximum":604800}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"secret":{"type":"string","description":"The new signing secret. Shown once."},"previous_secret_expires_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","example":"2026-09-21T10:00:00.000Z"},{"type":"null"}],"description":"When the old secret stops signing; null if it already has."}},"required":["id","secret","previous_secret_expires_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"id":"wh_3Nf8sT2yQ6rJ1vK9dH4c","secret":"whsec_EXAMPLE_shown_once_at_creation","previous_secret_expires_at":"2026-09-21T10:00:00.000Z"}}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Clashes with the current state, or an `Idempotency-Key` was reused with a different body.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/organization/webhooks/{webhook_id}/delete":{"post":{"operationId":"organization.webhooks.delete","summary":"Delete a webhook endpoint","description":"Stops delivery and removes the endpoint and its delivery history.","tags":["Administration"],"x-scope":"organization","x-units":0,"security":[{"adminKey":[]}],"parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","maxLength":64}},{"name":"Idempotency-Key","in":"header","required":false,"description":"A unique string (a UUID is ideal) making this call safe to retry. The same key with the same body replays the first response and sets `Idempotent-Replay: true`; with a different body it returns `409 idempotency_key_reuse`. Remembered for 24 hours.","schema":{"type":"string","maxLength":255},"example":"8f14e45f-ea6a-4cbb-9a2f-3d1c0b7e21aa"}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean","const":true}},"required":["id","deleted"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"id":"wh_3Nf8sT2yQ6rJ1vK9dH4c","deleted":true}}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Clashes with the current state, or an `Idempotency-Key` was reused with a different body.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/organization/webhooks/{webhook_id}/deliveries":{"get":{"operationId":"organization.webhooks.deliveries","summary":"List deliveries","description":"What was sent to this endpoint, newest first, with what it answered. A delivery that ran out of attempts shows `failed`; replay it once the receiver is fixed. Pass `pagination.next_cursor` back as `cursor` for older deliveries.","tags":["Administration"],"x-scope":"organization","x-units":0,"security":[{"adminKey":[]}],"parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","maxLength":64}},{"name":"limit","in":"query","required":false,"description":"Default 25.","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":500}}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"event_id":{"type":"string","description":"Stable across retries and replays."},"event_type":{"type":"string"},"status":{"type":"string","enum":["pending","delivered","failed"]},"attempts":{"type":"integer"},"response_status":{"anyOf":[{"type":"integer"},{"type":"null"}]},"response_snippet":{"description":"First 500 characters of the reply.","type":["string","null"]},"next_attempt_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","example":"2026-09-21T10:00:00.000Z"},{"type":"null"}]},"delivered_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","example":"2026-09-21T10:00:00.000Z"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","example":"2026-09-21T10:00:00.000Z","description":"ISO 8601 time"}},"required":["id","event_id","event_type","status","attempts","response_status","response_snippet","next_attempt_at","delivered_at","created_at"],"additionalProperties":false}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"],"additionalProperties":false},"example":{"data":[{"id":48213,"event_id":"evt_2Hc7mP4xW9aB6qE1rT8k","event_type":"listing.price_changed","status":"pending","attempts":1,"response_status":null,"response_snippet":"OK","next_attempt_at":"2026-09-21T10:00:00.000Z","delivered_at":"2026-09-21T10:00:00.000Z","created_at":"2026-09-21T10:00:00.000Z"}],"pagination":{"limit":25,"next_cursor":"eyJvIjoyNSwiZiI6IksweTFfU1F3d1BXSiJ9.pkFEfJUOpRbZRS279EDC4v","has_more":true,"result_window_reached":false}}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/organization/webhooks/{webhook_id}/deliveries/{delivery_id}/replay":{"post":{"operationId":"organization.webhooks.replay","summary":"Replay a delivery","description":"Queues the same payload again, with its original `event_id` so a receiver that already handled it can recognise the repeat. Use after fixing whatever rejected it. A disabled endpoint holds the delivery as pending until it is re-enabled.","tags":["Administration"],"x-scope":"organization","x-units":0,"security":[{"adminKey":[]}],"parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","maxLength":64}},{"name":"delivery_id","in":"path","required":true,"schema":{"type":"string","maxLength":32}},{"name":"Idempotency-Key","in":"header","required":false,"description":"A unique string (a UUID is ideal) making this call safe to retry. The same key with the same body replays the first response and sets `Idempotent-Replay: true`; with a different body it returns `409 idempotency_key_reuse`. Remembered for 24 hours.","schema":{"type":"string","maxLength":255},"example":"8f14e45f-ea6a-4cbb-9a2f-3d1c0b7e21aa"}],"responses":{"200":{"description":"OK","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"integer"},"status":{"type":"string","const":"pending"}},"required":["id","status"],"additionalProperties":false}},"required":["data"],"additionalProperties":false},"example":{"data":{"id":48213,"status":"pending"}}}}},"400":{"description":"Invalid request: unknown or malformed parameters.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Your plan or account doesn't allow this request.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Wrong method for this path. `Allow` lists the ones it takes.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Allow":{"description":"The methods this path accepts.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Clashes with the current state, or an `Idempotency-Key` was reused with a different body.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly quota exceeded. See `Retry-After`.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying. Always sent with a 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Our fault. Safe to retry with backoff.","headers":{"X-Request-Id":{"description":"Quote this when contacting support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"Your secret API key, `dk_live_…`. Never put it in URLs or client-side code. Data endpoints also accept an OAuth access token issued by platform.kite.sa, which acts for the person who granted it and can only read."},"testKey":{"type":"http","scheme":"bearer","description":"A test key, `dk_test_…`. Reads the same live data as `dk_live_…` under a small fixed allowance that is metered separately and never billed. Accepted anywhere a data key is."},"adminKey":{"type":"http","scheme":"bearer","description":"An admin key, `dk_admin_…`, created by an organization owner. These reach only the Administration endpoints, and a `dk_live_…` key is refused there — the two kinds never overlap."}},"schemas":{"AggregateLayerExportFilters":{"type":"object","properties":{"city":{"description":"Default: every city.","minItems":1,"maxItems":113,"type":"array","items":{"description":"City slug from GET /cities. A town inside a covered region is accepted and resolved to its city (`dammam`, `khobar`, `dhahran`, `jubail` and `qatif` to `eastern_province`; `buraydah` and `unaizah` to `qassim`; `hofuf` to `al_ahsa`), as are Arabic city names. The response's `filters.city` and the `X-Resolved-City` header show the slug used.","example":"riyadh","type":"string","pattern":"^[a-z_]+$"}}},"additionalProperties":false},"CoverageFlag":{"type":"string","enum":["full","notary_only","incomplete"],"description":"How much of the market a registered-deal figure covers. `full`: every deal the source registers. `notary_only`: notary-registered deals only; Real Estate Registry deals are missing (Riyadh city from 2024-Q1, when the Registry began taking over its districts). Served, but not the whole market, and it may under-represent districts that moved early. `incomplete`: a period past `coverage.complete_through_quarter`, built on part of the usual deals.","example":"full"},"DealSource":{"type":"string","enum":["moj_open_data","moj_notary","real_estate_registry"],"description":"`moj_open_data`: the Ministry of Justice's quarterly open data. `moj_notary`: a notary-registered deal newer than the latest open-data quarter. `real_estate_registry`: a deal registered with the Real Estate Registry (السجل العقاري).","example":"moj_open_data"},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["type","code","message","request_id","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request","authentication_error","permission_error","not_found","method_not_allowed","conflict","rate_limit_error","api_error"]},"code":{"type":"string","description":"Machine-readable. Codes are never renamed; new ones may be added.","examples":["invalid_value"]},"message":{"type":"string","description":"Human-readable; may change."},"param":{"type":"string","description":"The parameter or field at fault, if any."},"details":{"type":"object","additionalProperties":true},"request_id":{"type":"string","examples":["req_4f1c2d9a8b7e6f5a4b3c2d1e"]},"doc_url":{"type":"string"}}}}},"Export":{"type":"object","properties":{"id":{"type":"string","example":"exp_Q2hsYXVkZUV4cG9ydA"},"dataset":{"type":"string","enum":["listings","listing_changes","registered_transactions","registered_rents","aggregate_layers"]},"format":{"type":"string","enum":["ndjson","csv"]},"compression":{"type":"string","enum":["gzip","none"]},"status":{"type":"string","enum":["queued","running","completed","failed","expired"],"description":"`queued` → `running` → `completed`, or `failed`. `expired` once the files are deleted."},"filters":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}],"description":"As requested. Null once complete if your organization has turned off storing request details."},"price_source":{"type":"string","enum":["asking","registered"],"description":"Where the prices come from: `asking` = advertised asking prices from listings; `registered` = registered transactions or rent contracts. Asking prices typically sit above what is finally agreed.","example":"asking"},"rows_estimated":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Rows counted before a listing export ran, which `units` is priced on."},"row_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Rows written, once complete."},"units":{"type":"integer","description":"Units charged. 0 for open data, and refunded if the export fails."},"progress":{"type":"object","properties":{"rows_written":{"type":"integer"},"parts_written":{"type":"integer"}},"required":["rows_written","parts_written"],"additionalProperties":false},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string","description":"`export_too_large`, `monthly_quota_exceeded`, `spend_cap_reached`, `project_cap_exceeded` or `internal_error`."},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]},"attribution":{"anyOf":[{"type":"object","properties":{"notice":{"type":"string"},"license_url":{"type":"string"}},"required":["notice","license_url"],"additionalProperties":false},{"type":"null"}],"description":"Open-data exports: the licence notice, also in ATTRIBUTION.txt. Keep it with the data."},"files":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","example":"part-00001.ndjson.gz"},"kind":{"type":"string","enum":["data","manifest","attribution"]},"rows":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Rows in a data part; null otherwise."},"bytes":{"type":"integer"},"url":{"type":"string","description":"Signed download link."},"url_expires_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","example":"2026-09-21T10:00:00.000Z"}},"required":["name","kind","rows","bytes","url","url_expires_at"],"additionalProperties":false},"description":"Download links, on GET /exports/{export_id} of a completed export only."},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","example":"2026-09-21T10:00:00.000Z"},"started_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","example":"2026-09-21T10:00:00.000Z"},{"type":"null"}]},"completed_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","example":"2026-09-21T10:00:00.000Z"},{"type":"null"}]},"expires_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","example":"2026-09-21T10:00:00.000Z"},{"type":"null"}],"description":"When the files are deleted."}},"required":["id","dataset","format","compression","status","filters","price_source","rows_estimated","row_count","units","progress","error","attribution","files","created_at","started_at","completed_at","expires_at"],"additionalProperties":false},"ExportRequest":{"oneOf":[{"type":"object","properties":{"dataset":{"type":"string","const":"listings"},"filters":{"$ref":"#/components/schemas/ListingExportFilters"},"format":{"default":"ndjson","description":"`ndjson` (one JSON object per line) or `csv`.","type":"string","enum":["ndjson","csv"]},"compression":{"default":"gzip","description":"`gzip` (default) compresses each part file.","type":"string","enum":["gzip","none"]}},"required":["dataset"],"additionalProperties":false},{"type":"object","properties":{"dataset":{"type":"string","const":"listing_changes"},"filters":{"$ref":"#/components/schemas/ListingChangeExportFilters"},"format":{"default":"ndjson","description":"`ndjson` (one JSON object per line) or `csv`.","type":"string","enum":["ndjson","csv"]},"compression":{"default":"gzip","description":"`gzip` (default) compresses each part file.","type":"string","enum":["gzip","none"]}},"required":["dataset","filters"],"additionalProperties":false},{"type":"object","properties":{"dataset":{"type":"string","const":"registered_transactions"},"filters":{"$ref":"#/components/schemas/TransactionExportFilters"},"format":{"default":"ndjson","description":"`ndjson` (one JSON object per line) or `csv`.","type":"string","enum":["ndjson","csv"]},"compression":{"default":"gzip","description":"`gzip` (default) compresses each part file.","type":"string","enum":["gzip","none"]}},"required":["dataset"],"additionalProperties":false},{"type":"object","properties":{"dataset":{"type":"string","const":"registered_rents"},"filters":{"$ref":"#/components/schemas/RentExportFilters"},"format":{"default":"ndjson","description":"`ndjson` (one JSON object per line) or `csv`.","type":"string","enum":["ndjson","csv"]},"compression":{"default":"gzip","description":"`gzip` (default) compresses each part file.","type":"string","enum":["gzip","none"]}},"required":["dataset"],"additionalProperties":false},{"type":"object","properties":{"dataset":{"type":"string","const":"aggregate_layers"},"filters":{"$ref":"#/components/schemas/AggregateLayerExportFilters"}},"required":["dataset"],"additionalProperties":false}]},"Listing":{"type":"object","properties":{"id":{"type":"integer","example":128647},"url":{"type":"string","description":"The listing's page on kite.sa.","example":"https://kite.sa/en/listing/128647"},"title":{"description":"The advertiser's title, as posted. Null for sources that don't have titles (for example Aqar); use `headline` for display.","example":"شقة للإيجار في حي الملقا","type":["string","null"]},"headline":{"type":"string","description":"A short English description built from the listing's fields. Always present.","example":"3-bedroom apartment for rent in Al Malqa, Riyadh"},"description":{"description":"As posted (usually Arabic).","example":"شقة ثلاث غرف وصالة ومطبخ راكب، الدور الثاني، قريبة من الخدمات.","type":["string","null"]},"description_en":{"description":"English translation, where available.","example":"Three-bedroom apartment with a living room and fitted kitchen, second floor, close to services.","type":["string","null"]},"listing_type":{"type":"string","example":"rent"},"listing_category":{"example":"residential","type":["string","null"]},"property_type":{"type":"string","example":"apartment"},"price":{"type":"object","properties":{"yearly_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Price in SAR per year for rentals (monthly/daily postings are normalized to yearly); total price for sales. Use this for comparisons.","example":60000},"as_posted":{"type":"object","properties":{"amount":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"The price as the advertiser posted it.","example":5000},"frequency":{"description":"Rent period of `amount` (yearly, monthly, weekly, daily). Null for sales.","example":"monthly","type":["string","null"]}},"required":["amount","frequency"],"additionalProperties":false},"previous_yearly_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Price before the last change, if any.","example":66000},"changed_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","example":"2026-09-21T10:00:00.000Z"},{"type":"null"}],"description":"When the price last changed."},"price_basis":{"type":"string","enum":["yearly_rent","sale_price"],"description":"What the `*_sar` price fields mean: `yearly_rent` (SAR per year) for rentals, `sale_price` (total SAR) for sales."},"price_source":{"type":"string","enum":["asking","registered"],"description":"Where the prices come from: `asking` = advertised asking prices from listings; `registered` = registered transactions or rent contracts. Asking prices typically sit above what is finally agreed.","example":"asking"}},"required":["yearly_sar","as_posted","previous_yearly_sar","changed_at","price_basis","price_source"],"additionalProperties":false},"financing":{"type":"object","properties":{"rent_now_pay_later_monthly_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Monthly price under the rent-now-pay-later financing option the source offers on this listing, as the source reports it. Rentals only; currently Aqar only.","example":5450},"accepts_bank_financing":{"description":"Seller accepts a bank mortgage. Null when not stated. Currently Aqar only.","type":["boolean","null"]},"landlord_payment_plans":{"type":"object","properties":{"monthly":{"type":["boolean","null"]},"quarterly":{"type":["boolean","null"]},"semiannually":{"type":["boolean","null"]}},"required":["monthly","quarterly","semiannually"],"additionalProperties":false,"description":"Installment schedules the landlord accepts directly."}},"required":["rent_now_pay_later_monthly_sar","accepts_bank_financing","landlord_payment_plans"],"additionalProperties":false},"bedrooms":{"anyOf":[{"type":"integer"},{"type":"null"}],"example":3},"bathrooms":{"anyOf":[{"type":"integer"},{"type":"null"}],"example":2},"livings":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Living rooms.","example":1},"area_sqm":{"example":140,"type":["number","null"]},"floor":{"example":"2","type":["string","null"]},"age_years":{"anyOf":[{"type":"integer"},{"type":"null"}],"example":4},"furnished":{"example":false,"type":["boolean","null"]},"amenities":{"type":"array","items":{"type":"string"},"example":["ac","kitchen","parking"]},"photo_features":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"feature":{"type":"string","enum":["real_photos","kitchen_installed","ac_split","pool","roof_terrace","balcony","large_windows"]},"image_index":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Index into `images` of a photo that shows the feature. Null when the photos changed after they were analysed.","example":2}},"required":["feature","image_index"],"additionalProperties":false}},{"type":"null"}],"description":"What a vision model saw in the listing's photos, using the values of the `photo_features` filter. Precision-first: a feature is listed only when it is clearly visible, so a missing feature means not seen, not absent. `real_photos` means at least one image is a real photograph (not a render, plan, map or graphic). Null when the photos have not been analysed yet; new listings are analysed within about six hours, residential homes only.","example":[{"feature":"real_photos","image_index":0},{"feature":"kitchen_installed","image_index":3}]},"location":{"type":"object","properties":{"city":{"description":"City slug (see GET /cities).","example":"riyadh","type":["string","null"]},"city_name_en":{"example":"Riyadh","type":["string","null"]},"neighborhood_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"See GET /cities/{city}/neighborhoods.","example":12},"neighborhood_name_ar":{"example":"الملقا","type":["string","null"]},"neighborhood_name_en":{"example":"Al Malqa","type":["string","null"]},"lat":{"example":24.7869,"type":["number","null"]},"lng":{"example":46.6215,"type":["number","null"]},"street_width_m":{"example":20,"type":["number","null"]}},"required":["city","city_name_en","neighborhood_id","neighborhood_name_ar","neighborhood_name_en","lat","lng","street_width_m"],"additionalProperties":false},"plot":{"anyOf":[{"$ref":"#/components/schemas/ListingPlot"},{"type":"null"}]},"compound_name":{"example":"Sedra","type":["string","null"]},"project_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Off-plan project this unit belongs to, if linked."},"images":{"type":"array","items":{"type":"string"},"description":"Image URLs on Kite's CDN.","example":["https://images.darak.app/listings/128647/1.webp"]},"image_count":{"type":"integer","example":8},"advertiser":{"type":"object","properties":{"type":{"description":"Advertiser category as the source reports it, verbatim — `agency`, `company_broker`, `developer`, `individual_broker`, `individual_owner` and similar. These are not the values the `advertiser_type` filter takes: that filter offers `company` and `individual`, which group these, so a response value cannot be passed straight back as a filter.","example":"agency","type":["string","null"]},"name":{"description":"The advertiser's name as the source shows it. Null unless the ad is licensed.","example":"مكتب الملقا للعقار","type":["string","null"]},"name_en":{"description":"English name, where the source has one. Null unless the ad is licensed.","example":"Al Malqa Real Estate","type":["string","null"]},"company":{"description":"Brokerage or company name. Null unless the ad is licensed.","example":"Al Malqa Real Estate Company","type":["string","null"]},"logo":{"description":"Logo URL. Null unless the ad is licensed.","example":"https://images.example.com/advertisers/al-malqa.png","type":["string","null"]},"fal_number":{"description":"REGA FAL (brokerage) licence number. Null when the ad has no FAL licence, including owner-posted ads.","example":"1100012345","type":["string","null"]},"cr":{"description":"Commercial registration number. Null unless the ad is licensed.","example":"1010012345","type":["string","null"]},"ad_license":{"description":"REGA advertising licence number for this ad (10 digits).","example":"7100232271","type":["string","null"]},"contact_available":{"type":"boolean","description":"Whether GET /listings/{id}/contact returns the advertiser's phone number: the ad is licensed, Kite holds a number, and no takedown or removal request covers it.","example":true}},"required":["type","name","name_en","company","logo","fal_number","cr","ad_license","contact_available"],"additionalProperties":false,"description":"Who posted the ad. The identity fields are filled only when the ad carries a REGA licence (an advertising licence or a FAL brokerage licence) and no takedown or removal request covers the listing; otherwise they are null. No listing response carries a phone number: it comes from GET /listings/{id}/contact, one listing at a time, with the `listings:contact` scope."},"verified_by_source":{"description":"The source marks this ad as verified.","type":["boolean","null"]},"source":{"type":"object","properties":{"name":{"type":"string","description":"Source platform (see GET /enums).","example":"aqar"},"listing_id":{"description":"The source's own id for the ad. Null on the Sandbox plan.","example":"7788123","type":["string","null"]},"url":{"description":"A kite.sa link that forwards to the original ad. Null on the Sandbox plan, or when the source has no ad page. Where you show a listing, link `url` and credit `name` (see the terms).","example":"https://kite.sa/r/128647","type":["string","null"]}},"required":["name","listing_id","url"],"additionalProperties":false},"also_listed_on":{"type":"array","items":{"type":"string"},"description":"Other sources carrying the same property. Kite shows one listing per property.","example":["bayut"]},"first_seen_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","example":"2026-09-21T10:00:00.000Z"},{"type":"null"}],"description":"When Kite first saw the listing."},"updated_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","example":"2026-09-21T10:00:00.000Z"},{"type":"null"}],"description":"Last update at the source, or the last time Kite saw the listing if the source doesn't publish update times. Drives `updated_since` and the `updated_*` sorts."},"last_seen_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","example":"2026-09-21T10:00:00.000Z"},{"type":"null"}],"description":"Last time Kite confirmed the listing is live."},"days_on_market":{"anyOf":[{"type":"integer"},{"type":"null"}],"example":12}},"required":["id","url","title","headline","description","description_en","listing_type","listing_category","property_type","price","financing","bedrooms","bathrooms","livings","area_sqm","floor","age_years","furnished","amenities","photo_features","location","plot","compound_name","project_id","images","image_count","advertiser","verified_by_source","source","also_listed_on","first_seen_at","updated_at","last_seen_at","days_on_market"],"additionalProperties":false},"ListingChangeExportFilters":{"type":"object","properties":{"city":{"description":"City slugs from GET /cities. Default: every city.","minItems":1,"maxItems":113,"type":"array","items":{"description":"City slug from GET /cities. A town inside a covered region is accepted and resolved to its city (`dammam`, `khobar`, `dhahran`, `jubail` and `qatif` to `eastern_province`; `buraydah` and `unaizah` to `qassim`; `hofuf` to `al_ahsa`), as are Arabic city names. The response's `filters.city` and the `X-Resolved-City` header show the slug used.","example":"riyadh","type":"string","pattern":"^[a-z_]+$"}},"listing_type":{"description":"Default: both.","minItems":1,"maxItems":2,"type":"array","items":{"type":"string","enum":["rent","sale"]}},"listing_category":{"description":"Omit for both.","type":"string","enum":["residential","commercial"]},"property_type":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"string","enum":["apartment","villa","floor","duplex","office","shop","warehouse","land","building"]}},"neighborhood_id":{"description":"Neighborhood ids from GET /cities/{city}/neighborhoods.","minItems":1,"maxItems":500,"type":"array","items":{"type":"integer","minimum":1}},"beds_min":{"type":"integer","minimum":0,"maximum":20},"beds_max":{"type":"integer","minimum":0,"maximum":20},"price_min":{"description":"SAR. Yearly for rentals.","type":"integer","minimum":0,"maximum":2000000000},"price_max":{"description":"SAR. Yearly for rentals.","type":"integer","minimum":0,"maximum":2000000000},"area_min":{"description":"m².","type":"number","minimum":0,"maximum":10000000},"area_max":{"description":"m².","type":"number","minimum":0,"maximum":10000000},"source":{"description":"Source platforms, see GET /enums.","minItems":1,"maxItems":20,"type":"array","items":{"type":"string","pattern":"^[a-z_]+$"}},"furnished":{"type":"boolean"},"from":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"Start of the range (inclusive). Listing history begins 2026-03-09; nothing earlier exists.","example":"2026-09-01T00:00:00Z"},"to":{"description":"End of the range (exclusive). Default: now. At most 366 days after `from`.","type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"event_type":{"description":"Default: all three.","minItems":1,"maxItems":3,"type":"array","items":{"type":"string","enum":["created","price_changed","delisted"]}}},"required":["from"],"additionalProperties":false},"ListingExportFilters":{"type":"object","properties":{"city":{"description":"City slugs from GET /cities. Default: every city.","minItems":1,"maxItems":113,"type":"array","items":{"description":"City slug from GET /cities. A town inside a covered region is accepted and resolved to its city (`dammam`, `khobar`, `dhahran`, `jubail` and `qatif` to `eastern_province`; `buraydah` and `unaizah` to `qassim`; `hofuf` to `al_ahsa`), as are Arabic city names. The response's `filters.city` and the `X-Resolved-City` header show the slug used.","example":"riyadh","type":"string","pattern":"^[a-z_]+$"}},"listing_type":{"description":"Default: both.","minItems":1,"maxItems":2,"type":"array","items":{"type":"string","enum":["rent","sale"]}},"listing_category":{"description":"Omit for both.","type":"string","enum":["residential","commercial"]},"property_type":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"string","enum":["apartment","villa","floor","duplex","office","shop","warehouse","land","building"]}},"neighborhood_id":{"description":"Neighborhood ids from GET /cities/{city}/neighborhoods.","minItems":1,"maxItems":500,"type":"array","items":{"type":"integer","minimum":1}},"beds_min":{"type":"integer","minimum":0,"maximum":20},"beds_max":{"type":"integer","minimum":0,"maximum":20},"price_min":{"description":"SAR. Yearly for rentals.","type":"integer","minimum":0,"maximum":2000000000},"price_max":{"description":"SAR. Yearly for rentals.","type":"integer","minimum":0,"maximum":2000000000},"area_min":{"description":"m².","type":"number","minimum":0,"maximum":10000000},"area_max":{"description":"m².","type":"number","minimum":0,"maximum":10000000},"source":{"description":"Source platforms, see GET /enums.","minItems":1,"maxItems":20,"type":"array","items":{"type":"string","pattern":"^[a-z_]+$"}},"furnished":{"type":"boolean"},"updated_since":{"description":"Only listings whose `updated_at` is at or after this time: an incremental snapshot.","example":"2026-09-01T00:00:00Z","type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"additionalProperties":false,"description":"The filters of GET /listings, as JSON. `city` and `listing_type` take several values here, and default to all of them."},"ListingPlot":{"type":"object","properties":{"zoning":{"anyOf":[{"type":"string","enum":["residential","commercial","mixed","industrial","agricultural","public","other"]},{"type":"null"}],"description":"Zoning class of the parcel in the municipal plan. Null when the parcel record carries none.","example":"residential"},"is_corner":{"description":"The plot is on a corner: it fronts streets on two adjacent sides.","example":false,"type":["boolean","null"]},"frontage_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Sides that face a street (0 to 4).","example":1},"facing":{"type":"array","items":{"type":"string","enum":["north","east","south","west"]},"description":"The sides that face a street. Empty when unknown.","example":["north"]},"street_width_m":{"description":"Width of the widest street the plot fronts, metres.","example":25,"type":["number","null"]},"street_width_source":{"anyOf":[{"type":"string","enum":["official","measured"]},{"type":"null"}],"description":"`official`: the municipality's street records; `measured`: measured by Kite as the gap between the plots on either side of the street. Null without a width.","example":"official"},"plot_area_sqm":{"description":"Area of the official parcel, m². Can differ from the listing's `area_sqm`, which is what the ad states.","example":449.1,"type":["number","null"]},"buildable_area_sqm":{"description":"Floor area the parcel's building regulations allow, m². Null where the regulations aren't known.","example":747,"type":["number","null"]},"buildable_far":{"description":"Floor-area ratio the regulations allow: `buildable_area_sqm` ÷ the plot area.","example":1.66,"type":["number","null"]},"price_per_buildable_sqm_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Sale listings only: the asking price ÷ `buildable_area_sqm`, SAR per m² of floor area that may be built. Compares plots under different regulations. Null for rentals and without a buildable area.","example":2410},"urban_growth_phase":{"description":"The earliest phase of the urban growth boundary the plot is inside: `1440`, `1445` or `1450` (the Hijri year of the phase), or `protection` (the development protection boundary, beyond the phased area). Earlier phases have been open to development for longer. Null outside the boundary or where it isn't loaded.","example":"1440","type":["string","null"]},"urban_growth_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Hijri year of `urban_growth_phase`; null for `protection`.","example":1440},"white_land_fee":{"anyOf":[{"type":"object","properties":{"band":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Band number, 1 (highest rate) to 5.","example":3},"rate_pct":{"description":"Yearly fee in the band, percent of the land's value.","example":5,"type":["number","null"]},"as_of":{"description":"Date of the band map, `YYYY-MM-DD`.","example":"2025-08-26","type":["string","null"]}},"required":["band","rate_pct","as_of"],"additionalProperties":false},{"type":"null"}],"description":"The white-land fee band the plot is in. The fee is levied on vacant land in a band, so a built plot in one doesn't pay it. Bands are mapped for Riyadh only: null outside every band and in every other city."},"last_registered_sale":{"anyOf":[{"type":"object","properties":{"month":{"type":"string","description":"Month the sale was registered.","example":"2026-08"},"price_sar":{"type":"integer","description":"Registered sale price, SAR.","example":1850000},"price_per_sqm_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Registered price per m² of the deed's area, SAR.","example":4111},"area_sqm":{"description":"Area on the deed, m².","example":450,"type":["number","null"]},"registry":{"type":"string","enum":["MOJ","Real Estate Registry"],"description":"Where the sale was registered: `MOJ` for a deed registered through a notary of the Ministry of Justice, `Real Estate Registry` for one registered with the Real Estate Registry.","example":"Real Estate Registry"},"areas_agree":{"description":"The listing's stated `area_sqm` is within 5% of the deed's area. Villa ads often state the built-up area rather than the plot's, so compare a price with this sale only when this is true. Null when the listing states no area.","example":true,"type":["boolean","null"]},"ask_to_last_sale_ratio":{"description":"Sale listings whose area agrees with the deed's only: the asking price ÷ `price_sar`, to 3 decimals. Null for rentals and when the areas don't agree.","example":0.973,"type":["number","null"]},"months_since":{"type":"integer","description":"Calendar months from `month` to the current month (0 in the same month).","example":3}},"required":["month","price_sar","price_per_sqm_sar","area_sqm","registry","areas_agree","ask_to_last_sale_ratio","months_since"],"additionalProperties":false,"description":"The parcel's most recent registered sale of the same kind of property as the listing: a land sale for land, and for villas and buildings a sale of the plot with what stands on it (the Real Estate Registry files villas and residential buildings alike, so the two can't be told apart there). Always null for flats, floors and duplexes, whose plot holds other units too. Deeds covering several plots, or several properties at one price, are left out because none states one plot's price. Null when no such sale is on record. A registered price, unlike the listing's asking price."},{"type":"null"}]},"registered_sale_while_listed":{"anyOf":[{"type":"object","properties":{"month":{"type":"string","description":"Month the sale was registered. Deal dates are given to the month only.","example":"2026-10"},"price_sar":{"type":"integer","description":"Registered sale price, SAR.","example":1800000},"registry":{"type":"string","enum":["MOJ","Real Estate Registry"],"description":"Where the sale was registered: `MOJ` for a deed registered through a notary of the Ministry of Justice, `Real Estate Registry` for one registered with the Real Estate Registry.","example":"Real Estate Registry"},"ask_at_sale_sar":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"The ad's asking price in effect when the sale was registered, from Kite's price history of the ad. An asking price, not a registered one; it can differ from the listing's `price` today.","example":1950000},"areas_agree":{"type":"boolean","description":"The ad's stated area is within 5% of the deed's area: the ad and the deed describe the same plot, so `deal_to_ask_ratio` compares like with like.","example":true},"deal_to_ask_ratio":{"description":"`price_sar` ÷ `ask_at_sale_sar`, to 3 decimals: the registered price as a share of the asking price. 0.92 means the sale registered 8% below the ask. Null when the areas don't agree.","example":0.923,"type":["number","null"]},"weeks_to_sell":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Whole weeks from when Kite first saw the ad to the sale. Null when the sale was registered before Kite first saw the ad, or when the ad's true posting date is unknown: Kite first saw it while importing a source's back catalogue.","example":7}},"required":["month","price_sar","registry","ask_at_sale_sar","areas_agree","deal_to_ask_ratio","weeks_to_sell"],"additionalProperties":false,"description":"The plot registered a sale of the same kind (see `last_registered_sale`) while this ad was up: from a week before Kite first saw the ad (a slow first crawl) to 90 days after it was taken down. On a listing still on the market this means the plot has most likely already been sold. Land, villas and buildings for sale only; null otherwise and when no such sale is on record. Not given for a plot whose plan and parcel numbers more than 5 separate ads share, which is usually a compound's master deed rather than one plot."},{"type":"null"}]},"registered_sales_count":{"type":"integer","description":"Registered sales of the same kind (see `last_registered_sale`) on record for the parcel. Always 0 for flats, floors and duplexes.","example":1},"match":{"type":"object","properties":{"method":{"type":"string","enum":["plan_parcel_and_pin","plan_parcel_and_district"],"description":"`plan_parcel_and_pin`: the plan and parcel numbers in the ad, with the listing's map pin near the parcel. `plan_parcel_and_district`: the same numbers, with the pin farther off but in a neighborhood where the parcel's registered sales are.","example":"plan_parcel_and_pin"},"confidence":{"type":"number","description":"Kite's confidence in the match, 0 to 1.","example":0.9}},"required":["method","confidence"],"additionalProperties":false,"description":"How Kite placed the listing on the parcel."}},"required":["zoning","is_corner","frontage_count","facing","street_width_m","street_width_source","plot_area_sqm","buildable_area_sqm","buildable_far","price_per_buildable_sqm_sar","urban_growth_phase","urban_growth_year","white_land_fee","last_registered_sale","registered_sale_while_listed","registered_sales_count","match"],"additionalProperties":false,"description":"The plot the property stands on, from official parcel records, and the parcel's last registered sale. Kite places a listing on a parcel from the plan and parcel numbers in the ad, checked against its map pin or neighborhood (see `match`). Null when the listing couldn't be placed: most ads give no plan and parcel numbers, and parcel maps are loaded for the main cities only. Recomputed after every scrape. A flat's plot is its building's."},"NeighborhoodTown":{"anyOf":[{"type":"object","properties":{"name_en":{"type":"string","example":"Khobar"},"name_ar":{"type":"string","example":"الخبر"}},"required":["name_en","name_ar"],"additionalProperties":false},{"type":"null"}],"description":"The town the neighborhood is in, for a city made of several towns (Eastern Province: Dammam, Khobar, Dhahran, Jubail, Qatif, Khafji, Nairiyah, Abqaiq, Ras Tanura; Qassim: Buraidah, Unaizah, Ar Rass and the region's other towns; Al Ahsa: Hofuf, Mubarraz, Al Jafr, Al Uyun, Al Omran, Jawatha, Al Uqair, Yabrin), where two towns can have a neighborhood of the same name. Null in every other city, and for the few neighborhoods in those cities whose town Kite has not established."},"Pagination":{"type":"object","properties":{"limit":{"type":"integer","example":25},"next_cursor":{"description":"Pass as `cursor` for the next page.","example":"eyJvIjoyNSwiZiI6IksweTFfU1F3d1BXSiJ9.pkFEfJUOpRbZRS279EDC4v","type":["string","null"]},"has_more":{"type":"boolean","example":true},"result_window_reached":{"type":"boolean","example":false,"description":"True when more results exist but your plan's paging depth is reached. Narrow the filters, or for syncs continue with `updated_since` set to the last `updated_at` you received."}},"required":["limit","next_cursor","has_more","result_window_reached"],"additionalProperties":false},"RentExportFilters":{"type":"object","properties":{"city":{"description":"Default: every city.","minItems":1,"maxItems":113,"type":"array","items":{"description":"City slug from GET /cities. A town inside a covered region is accepted and resolved to its city (`dammam`, `khobar`, `dhahran`, `jubail` and `qatif` to `eastern_province`; `buraydah` and `unaizah` to `qassim`; `hofuf` to `al_ahsa`), as are Arabic city names. The response's `filters.city` and the `X-Resolved-City` header show the slug used.","example":"riyadh","type":"string","pattern":"^[a-z_]+$"}},"property_type":{"minItems":1,"maxItems":5,"type":"array","items":{"type":"string","enum":["apartment","studio","floor","villa","duplex"]}},"period_from":{"description":"First quarter, `YYYY-Qn`.","example":"2025-Q1","type":"string","pattern":"^\\d{4}-Q[1-4]$"},"period_to":{"description":"Last quarter, `YYYY-Qn`.","type":"string","pattern":"^\\d{4}-Q[1-4]$"}},"additionalProperties":false},"Transaction":{"type":"object","properties":{"id":{"type":"string","description":"Opaque, stable id for the deal: a keyed hash, not MOJ's reference number, which is not served.","example":"txn_4f1c9a0b7e2d5c8a1b3e"},"month":{"type":"string","description":"Month the deal was registered.","example":"2026-03"},"source":{"$ref":"#/components/schemas/DealSource"},"source_quarter":{"description":"The MOJ quarterly file the deal was published in; see `attribution.datasets`. Null for deals not from the open data (`source` other than `moj_open_data`).","example":"2026-Q1","type":["string","null"]},"city":{"type":"string","example":"riyadh"},"city_name_ar":{"description":"City as MOJ writes it. Tells towns apart where a Kite city covers a region (eastern_province, qassim).","example":"الرياض","type":["string","null"]},"district_name_ar":{"description":"District as MOJ writes it, whether or not Kite could map it.","example":"النرجس","type":["string","null"]},"neighborhood":{"anyOf":[{"$ref":"#/components/schemas/TransactionNeighborhood"},{"type":"null"}],"description":"The Kite neighborhood the district maps to; null when it doesn't map."},"land_use":{"type":"string","enum":["residential","commercial","agricultural","industrial","mixed_use","other"],"description":"Land-use class: `residential` (سكني), `commercial` (تجاري), `agricultural` (زراعي), `industrial` (صناعي), `mixed_use` (سكني تجاري), `other` (أخرى). `other` also covers unclassified deals. MOJ's deed class on open-data deals; the parcel's zoning on deals from the registers (see `land_use_basis`).","example":"residential"},"land_use_ar":{"description":"MOJ's class as published, on open-data deals; null on the others.","example":"سكني","type":["string","null"]},"land_use_basis":{"type":"string","enum":["moj_class","zoning"],"description":"What `land_use` reads. `moj_class`: MOJ's class of the deal (open data). `zoning`: the parcel's zoning (deals from the registers). They disagree on most commercial deals, so don't pool them by class.","example":"moj_class"},"property_type":{"anyOf":[{"type":"string","enum":["vacant_land","agricultural_land","apartment","floor","villa","house","residential_building","mixed_use_building","commercial","other"]},{"type":"null"}],"description":"What changed hands, as the register records it: vacant land, a flat, a floor, a villa, a building, … Null on open-data deals, whose files don't say (their `land_use` is a class, not a property type).","example":"vacant_land"},"area_sqm":{"description":"Total area of the deal in m².","example":400,"type":["number","null"]},"price_sar":{"type":"number","description":"Total registered price in SAR.","example":1150000},"price_per_sqm_sar":{"description":"`price_sar` / `area_sqm`, rounded to 2 decimals; null without an area.","example":2875,"type":["number","null"]},"property_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Properties conveyed in the deal. Above 1, price and area are totals for all of them.","example":1},"token_price":{"type":"boolean","description":"True when the registered price is no market price: zero, under 10,000 SAR, or under 10 SAR per m² of `area_sqm` (a gift, inheritance or grant rather than a sale). The statistics endpoints leave these deals out unless `include_token_prices=true`, and `market_sales_only=true` drops them.","example":false}},"required":["id","month","source","source_quarter","city","city_name_ar","district_name_ar","neighborhood","land_use","land_use_ar","land_use_basis","property_type","area_sqm","price_sar","price_per_sqm_sar","property_count","token_price"],"additionalProperties":false},"TransactionAttribution":{"type":"object","properties":{"notice":{"type":"string","description":"Show this, or an equivalent that names and links the datasets, wherever you display or pass on this data."},"license":{"type":"object","properties":{"name":{"type":"string","example":"Saudi Open Data License v2.0 (an adaptation of the Open Data Commons Attribution License)"},"url":{"type":"string","example":"https://open.data.gov.sa/en/pages/policies/license"},"base_license":{"type":"string","example":"Open Data Commons Attribution License v1.0 (ODC-By)"},"base_license_url":{"type":"string","example":"https://opendatacommons.org/licenses/by/1-0/"}},"required":["name","url","base_license","base_license_url"],"additionalProperties":false},"datasets":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string","enum":["rega_rent_index","moj_transactions"]},"title":{"type":"string","description":"The dataset's title on the portal (Arabic)."},"title_en":{"type":"string"},"publisher":{"type":"string"},"urls":{"type":"array","items":{"type":"string"},"description":"The open.data.gov.sa datasets this response draws on, one per quarter."}},"required":["source","title","title_en","publisher","urls"],"additionalProperties":false}},"quarters":{"type":"array","items":{"type":"object","properties":{"quarter":{"type":"string","example":"2026-Q1"},"url":{"type":"string","description":"That quarter's dataset on open.data.gov.sa."}},"required":["quarter","url"],"additionalProperties":false},"description":"Which dataset each `source_quarter` came from."},"modifications":{"type":"string","description":"What Kite changed from the source files."},"other_sources":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string","enum":["moj_notary","real_estate_registry"]},"publisher":{"type":"string","example":"Real Estate Registry (السجل العقاري)"},"title_en":{"type":"string","example":"Sale deals registered with the Real Estate Registry"},"note":{"type":"string","example":"Not from the open-data files, so the open-data licence notice does not cover these rows."}},"required":["source","publisher","title_en","note"],"additionalProperties":false},"description":"Registers behind the deals in this response that are not open data (`source` other than `moj_open_data`). Empty when every deal is from the open data."}},"required":["notice","license","datasets","quarters","modifications","other_sources"],"additionalProperties":false,"description":"Licence notice for the Ministry of Justice open data in this response. Those rows and figures are government open data under the Saudi Open Data License (an adaptation of ODC-By), not Kite Data: you may reuse and redistribute them, including commercially, provided this attribution travels with them. Deals from the registers themselves are listed in `other_sources` and are not covered by that licence."},"TransactionCoverage":{"type":"object","properties":{"city":{"type":"string","example":"riyadh"},"first_deal_date":{"example":"2020-01-01","type":["string","null"]},"last_deal_date":{"description":"Latest deal date in the archive for this city (a city-wide figure).","example":"2026-06-30","type":["string","null"]},"latest_quarter":{"example":"2026-Q2","type":["string","null"]},"complete_through_quarter":{"description":"Last quarter whose figures are complete. Earlier than `latest_quarter` when the city's deals moved out of the source (Riyadh: 2026-Q1); figures after it are marked `complete: false` and `coverage_flag: \"incomplete\"`.","example":"2026-Q1","type":["string","null"]},"notary_only_from_quarter":{"description":"First quarter whose open-data figures cover notary-registered deals only, because the Real Estate Registry had begun registering part of the city's sales, which the open data does not carry. Figures from it on are flagged `coverage_flag: \"notary_only\"`. Null when the whole archive is full coverage. Riyadh: `2024-Q1`; Eastern Province: `2025-Q1`; Hail: `2026-Q1`.","example":"2024-Q1","type":["string","null"]},"registry_sample_from_quarter":{"description":"First quarter whose figures are built on Real Estate Registry deals, after the city's sales moved to the Registry; flagged `coverage_flag: \"registry_sample\"`. Null for cities that have not moved, and until Registry deals for the city are available. Riyadh: `2026-Q3`.","example":"2026-Q3","type":["string","null"]},"excluded_quarters":{"type":"array","items":{"type":"object","properties":{"quarter":{"type":"string"},"reason":{"type":"string"}},"required":["quarter","reason"],"additionalProperties":false},"description":"Quarters left out of every response, and why."},"notes":{"type":"array","items":{"type":"string"},"description":"Known gaps in the source for this city, in plain English."}},"required":["city","first_deal_date","last_deal_date","latest_quarter","complete_through_quarter","notary_only_from_quarter","registry_sample_from_quarter","excluded_quarters","notes"],"additionalProperties":false},"TransactionCoverageFlag":{"type":"string","enum":["full","notary_only","incomplete","registry_sample"],"description":"How much of the market a registered-deal figure covers. `full`: every deal the open data carries for the city. `notary_only`: notary deals only, while the Real Estate Registry was taking part of the city's sales, which the open data does not carry (Riyadh from 2024-Q1, Eastern Province from 2025-Q1, Hail from 2026-Q1). `incomplete`: a period past `coverage.complete_through_quarter`, built on part of the usual deals (the quarter a city moved to the Registry, or a quarter not yet published). `registry_sample`: built on deals from a partial feed of the registers, a sample of the market, not all of it: after a city moved, its Real Estate Registry deals (residential-zoned only); on a `property_type` cell, the notary and Registry deals that record that type.","example":"full"},"TransactionExportFilters":{"type":"object","properties":{"city":{"description":"Default: every city.","minItems":1,"maxItems":113,"type":"array","items":{"description":"City slug from GET /cities. A town inside a covered region is accepted and resolved to its city (`dammam`, `khobar`, `dhahran`, `jubail` and `qatif` to `eastern_province`; `buraydah` and `unaizah` to `qassim`; `hofuf` to `al_ahsa`), as are Arabic city names. The response's `filters.city` and the `X-Resolved-City` header show the slug used.","example":"riyadh","type":"string","pattern":"^[a-z_]+$"}},"land_use":{"minItems":1,"maxItems":6,"type":"array","items":{"type":"string","enum":["residential","commercial","agricultural","industrial","mixed_use","other"]}},"month_from":{"description":"First month, `YYYY-MM`.","example":"2024-01","type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"},"month_to":{"description":"Last month, `YYYY-MM`.","example":"2026-06","type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"}},"additionalProperties":false},"TransactionNeighborhood":{"type":"object","properties":{"id":{"type":"integer","example":25},"name_ar":{"type":"string","example":"النرجس"},"name_en":{"type":"string","example":"Al Narjis"},"town":{"$ref":"#/components/schemas/NeighborhoodTown"}},"required":["id","name_ar","name_en","town"],"additionalProperties":false}}}}