Metadata-Version: 2.5
Name: kite-sa
Version: 0.3.0
Summary: Official Python client for the Kite API: Saudi real-estate listings and market data.
Project-URL: Documentation, https://platform.kite.sa/docs
Project-URL: Source, https://github.com/basseko/kite/tree/main/packages/sdk-python
Project-URL: Issues, https://github.com/basseko/kite/issues
Project-URL: Changelog, https://platform.kite.sa/changelog
License-Expression: MIT
License-File: LICENSE
Keywords: api,kite,listings,real-estate,saudi-arabia
Classifier: Programming Language :: Python :: 3
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# kite-sa

The official Python client for the [Kite API](https://platform.kite.sa/docs): every live rental and sale listing in Saudi Arabia, deduplicated across 20+ sources. Standard library only, Python 3.9+.

```bash
pip install kite-sa
```

```python
from kite_sa import Kite, KiteError

kite = Kite()  # reads KITE_API_KEY

page = kite.listings.search(city="riyadh", listing_type="rent", beds=3, limit=25)
print(page["data"][0]["price"]["yearly_sar"])

# Every result, fetching pages as you go (stops at your plan's paging depth).
for listing in kite.listings.search_all(city="jeddah", listing_type="sale"):
    print(listing["id"], listing["location"]["neighborhood_name_en"])

try:
    kite.listings.get(1)
except KiteError as e:
    print(e.status, e.code, e.request_id)
```

Get a key at [platform.kite.sa](https://platform.kite.sa).

- Lists are sent comma-separated: `property_type=["apartment", "villa"]`.
- `429` and `5xx` (and network errors) are retried, honoring `Retry-After`. A monthly-quota `429` isn't waited out; it raises.
- Namespaces, generated from the API's OpenAPI spec so they track it exactly:
  `listings`, `market`, `analytics`, `projects`, `reference`, and
  `organization` (admin keys). `listings.search_all(...)` pages for you by
  following the cursor, and `request(method, path, query, body)` reaches
  anything not yet wrapped.
- `cities.list / neighborhoods / directions` still work; they are the 0.1.0
  names for what is now `reference`.

Tests: `python3 -m unittest discover -s tests`.
