Tools

8 read-only tools. Each wraps one REST endpoint and returns its JSON; amounts are SAR.

list_markets

GET /api/v1/markets

Every destination with at least 20 collected listings: slug, listing counts by source, asking-rate quartiles in SAR, and tracked occupancy, ADR and revenue where calendars are tracked. Assistants call it first to find slugs.

No arguments.

get_market

GET /api/v1/markets/{slug}

Full report for one destination: supply, bedroom price bands, property mix, average rating, and tracked occupancy, ADR, RevPAR, revenue per listing, on-the-books share, weekday and monthly breakdowns and lead times.

Argument	Type	Description
`slug`	string	Market slug such as riyadh, dubai or cairo; a city name also works.

get_metrics

GET /api/v1/metrics

Occupancy, ADR, RevPAR, monthly revenue per listing and on-the-books share for a city or rectangle, with weekday, monthly and lead-time breakdowns.

Argument	Type	Description
`city`	string, optional	Market slug or name.
`bounds`	object, optional	north, south, east, west in degrees, up to 5 degrees across. Use instead of city.
`past_days`	integer, optional	Nights to look back, 1–365 (default 30).
`forward_days`	integer, optional	Nights to look ahead, 1–365 (default 60).
`include_series`	boolean, optional	Include the per-night series. Default false, to keep responses small.

list_listings

GET /api/v1/listings

Collected listings with source, title, district, type id, bedrooms, coordinates, last asking rate in SAR, rating out of 10 and URL. The assistant pages with nextCursor.

Argument	Type	Description
`city`	string	Market slug or name.
`limit`	integer, optional	Listings per page, 1–500 (default 100).
`cursor`	string, optional	nextCursor from the previous page.

estimate_revenue

POST /api/v1/estimate

Projected nightly rate, occupancy and monthly and annual revenue from nearby comparables and tracked calendars, or 40%, 55% and 70% scenarios when occupancy is not measured.

Argument	Type	Description
`latitude, longitude`	number	Property location.
`radiusKm`	number, optional	Comparable radius, 0.5–20 km (default 3).
`bedrooms`	integer, optional	Exact bedroom count, or 0 for any (default).
`typeId`	string, optional	1 resort, 2 chalet, 3 rest house, 4 farm, 5 camp, 6 apartment, 7 villa, 8 room, 9 studio, 11 serviced apartment, or all (default).
`comps`	array, optional	3–50 `key` values from a previous estimate's `candidates`, at most 50. The estimate then uses only those listings, with the same rules as `POST /api/v1/estimate`: no wider fallback, `selection.status` `too-few` when fewer than 3 match, and keys no longer among the candidates counted in `selection.ignored`.

get_trends

GET /api/v1/trends

Daily history for one destination and metric from stored snapshots, with changes against 7, 30 and 90 days earlier where history allows.

Argument	Type	Description
`city`	string	Market slug or name.
`metric`	string, optional	occupancy (default), adr, revpar, asking, listings, tracked or on_the_books.
`source`	string, optional	all (default), gathern or airbnb.
`days`	integer, optional	Days of history, 7–1100 (default 365).

get_market_pace

GET /api/v1/pace

On-the-books share for each stay date in the next 30 days, its 7- and 14-day pickup, and the average booking curve by days before arrival. Collecting until a week of snapshots exists.

Argument	Type	Description
`city`	string	Market slug or name.

get_events

GET /api/v1/events

Sourced local holidays and events for the markets covered, with Arabic and English names, dates, certainty and source links, for demand and pricing questions.

Argument	Type	Description
`city`	string, optional	Market slug or name.
`from, to`	string, optional	Date range, YYYY-MM-DD.
`kind`	array, optional	religious, national, school, season, sports, culture or business.

Behaviour

The hosted endpoint and the local server offer the same tools with the same arguments.
All tools are marked read-only.
City arguments accept a slug (al-khobar) or a name (Al Khobar).
get_metrics needs either city or bounds, and replaces the nightly series with its length unless include_series is true.
Errors come back as tool errors with a plain explanation, so the assistant can tell you what to fix.
Investment inputs on estimates (cash flow, cap rate and payback) are available through the REST API only.