List advertisers by matching listings
GET/advertisers
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.
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.
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.
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.
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.
Prices are asking prices of active listings, in SAR; rents are yearly.
- Authentication
- Send a data key (dk_live_… or dk_test_…) as a Bearer token.
- Scope
analytics- Cost
- 50 units per call
Parameters
| Name | Description |
|---|---|
cityrequiredType: string · query | City slug from GET /cities. A town inside a covered region is accepted and resolved to its city ( |
listing_typerequiredType: string · query | One of: |
listing_categoryType: string · query | Omit for both. One of: |
property_typeType: string[] · query | One or more, comma-separated. One of: |
neighborhood_idType: integer[] · query | Neighborhood ids from GET /cities/{city}/neighborhoods. |
bedsType: integer · query | 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_minType: integer · query | Minimum number of bedrooms. |
beds_maxType: integer · query | Maximum number of bedrooms. |
bathrooms_minType: integer · query | Minimum number of bathrooms. |
price_minType: integer · query | SAR. Yearly for rentals (see |
price_maxType: integer · query | SAR. Yearly for rentals (see |
area_minType: number · query | Square meters. |
area_maxType: number · query | Square meters. |
furnishedType: string · query |
One of: |
sourceType: string[] · query | Source platforms, see GET /enums. Values aren't checked against the list, so a misspelled source narrows to nothing rather than erroring. |
bboxType: string · query | Bounding box |
updated_sinceType: string (date-time) · query | Only listings whose |
bathroomsType: integer · query | Exact number of bathrooms. |
bathrooms_maxType: integer · query | Maximum number of bathrooms. |
livings_minType: integer · query | Minimum number of living rooms. |
neighborhood_id_excludeType: integer[] · query | Exclude these neighborhoods. Ids from GET /cities/{city}/neighborhoods. Listings Kite could not place in a neighborhood are kept — unlike |
qType: string · query | Free-text match on the advertiser's title and description, as posted — not on |
amenitiesType: string[] · query | Only listings that have all of these. See GET /enums. One of: |
amenities_excludeType: string[] · query | Exclude listings that have any of these. One of: |
photo_featuresType: string[] · query | Only listings whose photos show all of these: One of: |
floorType: string · query |
One of: |
source_excludeType: string[] · query | Exclude these source platforms, see GET /enums. |
max_ageType: integer · query | 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. |
verifiedType: string · query |
One of: |
advertiser_typeType: string · query | Who posted the ad, where the source says. One of: |
compoundType: string · query | Compound name, partial match. |
in_compoundType: string · query | Only listings that belong to a compound, whichever one. One of: |
rent_frequencyType: string · query | How the rent is advertised. One of: |
days_on_market_minType: integer · query | Days since Kite first saw the listing. |
days_on_market_maxType: integer · query | Days since Kite first saw the listing. |
zoningType: string[] · query | Only listings whose plot is zoned any of these ( One of: |
cornerType: string · query |
One of: |
street_width_minType: number · query | Minimum width in metres of the widest street the plot fronts ( |
white_land_feeType: string · query |
One of: |
last_sale_within_monthsType: integer · query | Only listings whose parcel's last registered sale ( |
ask_to_last_sale_maxType: number · query | 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_soldType: string · query |
One of: |
above_median_pctType: number · query | Count only listings priced more than this percentage above the median of comparable listings (same neighborhood, property type and bedrooms, at least 5 listings). |
min_listingsType: integer · query | Only advertisers with at least this many matching listings. |
sortType: string · query |
One of: |
limitType: integer · query | |
cursorType: string · query |
Response
The data field is an object with these fields.
| Name | Description |
|---|---|
price_basisrequiredType: string | What the One of: |
price_sourcerequiredType: string | Where the prices come from: One of: |
totalsrequiredType: object | Across every page: advertisers with at least |
advertisersrequiredType: object[] |
Related endpoints
- Get comparable listings
GET /listings/{id}/comparables - Get a listing's market position
GET /listings/{id}/market-position - Get a listing's nearby asking-price band
GET /listings/{id}/price-band - Find below-market listings
GET /market/below-market - Find below-market listings (old path)
GET /market/deals - Get gross rental yield
GET /market/rental-yield - Get price trends
GET /market/trends - Compare neighborhoods
GET /market/neighborhoods/compare - Check the asking price for any home
GET /valuations/asking-range