# Property Finder API (UAE, Saudi Arabia, Qatar, Bahrain, Egypt) — propertyfinder.ae / .sa / .qa / .bh / .eg listings for sale and rent (residential and commercial) with every site filter and sort, real paging with totals, the full listing (price, size, permit, photos, amenities, agent and agency with phone / WhatsApp / e-mail), price trends, Dubai Land Department sold and rented transactions, area guides with resident reviews, new projects and developers, agents and agencies with their listings — no API key, no account

> Look up places by name on one Property Finder portal and get the location ids every other action accepts: cities, communities, sub-communities and buildings, with coordinates, review score and the area-guide link.
> ReefAPI engine `propertyfinder` · 18 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/propertyfinder/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed calls are free.
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http). Clients that add connectors by URL, such as ChatGPT and the Claude app, connect with OAuth 2.1 (the user pastes their key once on a ReefAPI page; discovery at `/.well-known/oauth-protected-resource/mcp`). Config files send the key as `Authorization: Bearer <key>`. `?key=<key>` in the URL also works as a last-resort fallback.

## Endpoints

### POST https://api.reefapi.com/propertyfinder/v1/locations — 1 credit
Look up places by name on one Property Finder portal and get the location ids every other action accepts: cities, communities, sub-communities and buildings, with coordinates, review score and the area-guide link.

**Parameters:**
- `query` (string, required) — Place or building name.
- `country` (enum, optional, default "ae") — Which Property Finder portal: ae (propertyfinder.ae, default), sa, qa, bh, eg. [one of: ae, sa, qa, bh, eg]
- `language` (enum, optional, default "en") — Language of the texts the site returns. [one of: en, ar]
- `page` (integer, optional, default 1) — Result page (1-based).
- `page_size` (integer, optional, default 10) — Rows per page, 1-50.

**Returns:** results[]{id, name, type, path, path_name, level, slug, city_slug, latitude, longitude, children_count, review_count, review_score, insights_url, images[], polygon} + total + page + total_pages

**Example request body:**
```json
{
  "query": "Dubai Marina"
}
```

### POST https://api.reefapi.com/propertyfinder/v1/search — 1 credit
Search Property Finder listings (for sale / for rent, residential / commercial) on one portal with every filter and sort the site's own search takes, paged with the site's total. `results` are the ranked listings that `total` counts; `spotlight` holds the paid listings the site pins on top of every page, `projects` the new-project cards it mixes in.

**Parameters:**
- `country` (enum, optional, default "ae") — Which Property Finder portal: ae (propertyfinder.ae, default), sa, qa, bh, eg. [one of: ae, sa, qa, bh, eg]
- `language` (enum, optional, default "en") — Language of the texts the site returns. [one of: en, ar]
- `category` (enum, optional, default "buy") — What to search: buy (default), rent, commercial_buy, commercial_rent. [one of: buy, rent, commercial_buy, commercial_rent]
- `location` (string, optional) — Place name (city, community, sub-community or building). The engine resolves it with the site's own location search and uses the best match; the match is echoed in `location`.
- `location_ids` (array, optional) — One or more Property Finder location ids (from `locations`), comma-separated.
- `property_type` (array, optional) — One or more property types (names below or numeric type ids), comma-separated. [one of: apartment, villa, townhouse, penthouse, compound, duplex, full_floor, half_floor, whole_building, land, bulk_sale_unit, bungalow, hotel_apartment, bulk_rent_unit, office, retail, warehouse, shop, showroom, factory, labor_camp, staff_accommodation, business_centre, coworking, farm]
- `bedrooms` (array, optional) — Bedroom counts, comma-separated: studio, 1-7, 7+ (any of them matches).
- `bathrooms` (array, optional) — Bathroom counts, comma-separated: 1-7, 7+.
- `min_price` (integer, optional) — Minimum price (local currency).
- `max_price` (integer, optional) — Maximum price (local currency).
- `min_area` (integer, optional) — Minimum size in the portal's area unit (sqft on .ae/.qa/.bh, sqm on .sa/.eg).
- `max_area` (integer, optional) — Maximum size in the portal's area unit.
- `min_plot_size` (integer, optional) — Minimum plot size.
- `max_plot_size` (integer, optional) — Maximum plot size.
- `min_price_per_area` (integer, optional) — Minimum price per area unit.
- `max_price_per_area` (integer, optional) — Maximum price per area unit.
- `furnished` (enum, optional) — Furnishing. [one of: furnished, unfurnished, partly_furnished]
- `completion_status` (enum, optional) — Ready or off-plan. [one of: ready, off_plan]
- `price_period` (enum, optional) — Rent: only listings priced per this period. [one of: yearly, monthly, weekly, daily]
- `keywords` (string, optional) — Keyword the listing must mention (the site's keyword box).
- `text` (string, optional) — Free-text search across the listing (the site's full-text query).
- `listed_within` (enum, optional) — Only listings added in the last 1d / 7d / 15d / 30d / 90d (or the day count). [one of: 1d, 7d, 15d, 30d, 90d]
- `amenities` (array, optional) — Amenities, comma-separated, all must match: two-letter codes (AC, BA, PP, PA, …) or their names (private pool, pets allowed, …). [one of: AC, MR, BA, SP, SS, SY, CS, CP, VW, BL, PA, ST, PG, PP, PY, PJ, BW, WC, BK, MS, PR, CO, BR]
- `mortgage_cashback` (boolean, optional) — Only listings with a mortgage cashback offer.
- `virtual_viewings` (array, optional) — Only listings with this kind of virtual viewing. [one of: floor_plan, 360_tours, video, live]
- `deal_badges` (array, optional) — Only listings carrying this badge. [one of: great_value, high_demand, price_drop]
- `delivery_date_from` (string, optional) — Off-plan handover on/after this date (YYYY-MM-DD).
- `delivery_date_to` (string, optional) — Off-plan handover on/before this date (YYYY-MM-DD).
- `post_handover_payment_plan` (boolean, optional) — Only off-plan listings with a post-handover payment plan.
- `upgraded` (boolean, optional) — Only listings marked upgraded.
- `extended` (boolean, optional) — Only listings marked extended.
- `landscaped` (boolean, optional) — Only listings marked landscaped.
- `min_cheques` (integer, optional) — Rent: minimum number of cheques accepted.
- `max_cheques` (integer, optional) — Rent: maximum number of cheques accepted.
- `latitude` (number, optional) — Search around a point: latitude (with longitude + radius_km).
- `longitude` (number, optional) — Search around a point: longitude.
- `radius_km` (number, optional) — Search around a point: radius in km (default 2).
- `sort` (enum, optional, default "featured") — Sort order. featured re-ranks between calls; newest shifts by the listings added between two page calls; price / bedrooms sorts page without gaps (0 overlaps over 3 pages, measured). [one of: featured, newest, price_asc, price_desc, bedrooms_asc, bedrooms_desc, delivery_date_asc, delivery_date_desc, price_per_area_asc, price_per_area_desc]
- `page` (integer, optional, default 1) — Result page, 1-50: the site's search serves its first 50 pages of any query (up to 3000 listings at page_size 60); narrow the filters to reach more.
- `page_size` (integer, optional, default 25) — Listings per page, 1-60 (the site's own maximum).

**Returns:** results[]{id, listing_ref, url, title, description, category, property_type, price, currency, price_period, price_per_area, bedrooms, bathrooms, size, size_unit, plot_size, furnished, completion_status, listed_at, location{…}, images[], amenities[], agent{…}, agency{…, phone, email}, contact{phone, whatsapp, email}, permit{…}, flags{…}} + spotlight[] + projects[] + total + page + page_size + total_pages + has_next + price_range + location

**Example request body:**
```json
{
  "location_ids": "1",
  "category": "buy",
  "sort": "newest"
}
```

### POST https://api.reefapi.com/propertyfinder/v1/property — 1 credit
Everything one listing page shows: price, price per area, size, rooms, furnishing, completion, the full description, every photo (and the community / building photos), amenities, the permit / RERA number and validation link, the agent and the agency with phone, WhatsApp and e-mail as published, the property and regulatory detail tables, local price trends (1 / 2 / 5 years), the price comparison against the area, similar sold / rented transactions and mortgage rates.

**Parameters:**
- `property_id` (string, required) — Listing id (e.g. 170616251) or any Property Finder listing link (its domain picks the country).
- `country` (enum, optional, default "ae") — Which Property Finder portal: ae (propertyfinder.ae, default), sa, qa, bh, eg. [one of: ae, sa, qa, bh, eg]
- `language` (enum, optional, default "en") — Language of the texts the site returns. [one of: en, ar]

**Returns:** property{…every search field…, available_from, property_details[], regulatory_details[], licenses[], community_images[], building_images[], price_trends{unit, series{1Y,2Y,5Y}}, price_comparison{…}, similar_transactions{sold[], rented[]}, mortgage{…}, breadcrumbs[]}

**Example request body:**
```json
{
  "property_id": "170616251"
}
```

### POST https://api.reefapi.com/propertyfinder/v1/price_trends — 1 credit
Price trend of a community or building for one property type and bedroom count: monthly price per area (sale) or yearly rent, community line and building line, over 1, 2 and 5 years.

**Parameters:**
- `location_id` (string, required) — Community / sub-community / building location id (from `locations` or a listing's location.id).
- `country` (enum, optional, default "ae") — Which Property Finder portal: ae (propertyfinder.ae, default), sa, qa, bh, eg. [one of: ae, sa, qa, bh, eg]
- `language` (enum, optional, default "en") — Language of the texts the site returns. [one of: en, ar]
- `category` (enum, optional, default "buy") — Sale prices or rents. [one of: buy, rent]
- `property_type` (string, optional, default "apartment") — Property type (name or id). [one of: apartment, villa, townhouse, penthouse, compound, duplex, full_floor, half_floor, whole_building, land, bulk_sale_unit, bungalow, hotel_apartment, bulk_rent_unit, office, retail, warehouse, shop, showroom, factory, labor_camp, staff_accommodation, business_centre, coworking, farm]
- `bedrooms` (string, optional, default "1") — Bedrooms: studio, 1-7.

**Returns:** unit + community + building + series{1Y[], 2Y[], 5Y[]}{date, period, community_price, building_price}

**Example request body:**
```json
{
  "location_id": "1"
}
```

### POST https://api.reefapi.com/propertyfinder/v1/transactions — 1 credit
UAE (Dubai Land Department data as Property Finder publishes it): sold or rented transactions in a city, community or building with the market summary (average and median price, price per sqft, volume, yield, monthly trend). Filters: property type, bedrooms, price, size, period, seller (developer / individual), completion, new or renewed rent contracts, unit number.

**Parameters:**
- `location_id` (string, required) — Location id (Dubai = 1, Dubai Marina = 50; any id from `locations`).
- `category` (enum, optional, default "sold") — Sales or rent contracts. [one of: sold, rented]
- `property_type` (string, optional) — Property type (name or id). [one of: apartment, villa, townhouse, penthouse, compound, duplex, full_floor, half_floor, whole_building, land, bulk_sale_unit, bungalow, hotel_apartment, bulk_rent_unit, office, retail, warehouse, shop, showroom, factory, labor_camp, staff_accommodation, business_centre, coworking, farm]
- `bedrooms` (string, optional) — Bedrooms: studio or 1-7.
- `min_price` (integer, optional) — Minimum price (AED).
- `max_price` (integer, optional) — Maximum price (AED).
- `min_area` (integer, optional) — Minimum size (sqft).
- `max_area` (integer, optional) — Maximum size (sqft).
- `period` (enum, optional, default "1y") — Time window (default 1y, the site's default). [one of: 1m, 3m, 6m, 1y, 3y]
- `sold_by` (enum, optional) — Sales only: who sold. [one of: developer, individual]
- `completion_status` (enum, optional) — Ready or off-plan. [one of: ready, off_plan]
- `contract_status` (enum, optional) — Rent contracts only: new or renewed. [one of: new, renewed]
- `unit_number` (string, optional) — Unit number as registered (e.g. M1-413).
- `page` (integer, optional, default 1) — Result page (1-based).
- `page_size` (integer, optional, default 20) — Rows per page, 1-50. The source serves the first 500 rows of any query (page × page_size ≤ 500).
- `language` (enum, optional, default "en") — Language of the texts the site returns. [one of: en, ar]
- `country` (enum, optional, default "ae") — Which Property Finder portal: ae (propertyfinder.ae, default), sa, qa, bh, eg. [one of: ae, sa, qa, bh, eg]

**Returns:** results[]{id, date, price, price_per_sqft, property_type, bedrooms, size_sqft, unit_number, status, completion_status, sold_by, developer, contract_start_date, contract_end_date, previous_price, price_change_pct, location{…}} + summary{…} + total + page + total_pages + has_next

**Example request body:**
```json
{
  "location_id": "1"
}
```

### POST https://api.reefapi.com/propertyfinder/v1/area — 3 credits
The site's area guide for a city, community or building: description, key facts, FAQs, getting around, schools, nearby places (counts and named places), demographics of renters, market insights (average sale price, price per sqft, yield, transaction volume), median prices per property type and bedroom count, price histogram, review summary with the latest reviews, popular buildings, similar communities and photos.

**Parameters:**
- `area` (string, required) — Area-guide path '<city>/<slug>' (e.g. dubai/dubai-marina), a city slug (dubai), or an area-insights link.
- `country` (enum, optional, default "ae") — Which Property Finder portal: ae (propertyfinder.ae, default), sa, qa, bh, eg. [one of: ae, sa, qa, bh, eg]
- `language` (enum, optional, default "en") — Language of the texts the site returns. [one of: en, ar]

**Returns:** area{id, name, type, city, latitude, longitude, description, key_facts[], faqs[], getting_around{…}, schools, house_prices[], market_insights{…}, price_histogram[], reviews{score, count, aggregate{…}, latest[]}, nearby{…}, demographics{…}, market{…}, popular_buildings{…}, similar_communities[], images[]}

**Example request body:**
```json
{
  "area": "dubai/dubai-marina"
}
```

### POST https://api.reefapi.com/propertyfinder/v1/area_reviews — 1 credit
Resident reviews of a community or building (the area guide's reviews), paged and sortable, with the score per category (traffic, quiet, parks, family, maintenance, parking, amenities).

**Parameters:**
- `location_id` (string, required) — Community or building location id (from `locations`).
- `country` (enum, optional, default "ae") — Which Property Finder portal: ae (propertyfinder.ae, default), sa, qa, bh, eg. [one of: ae, sa, qa, bh, eg]
- `language` (enum, optional, default "en") — Language of the texts the site returns. [one of: en, ar]
- `sort` (enum, optional, default "newest") — Order. [one of: newest, oldest, rating_highest, rating_lowest]
- `page` (integer, optional, default 1) — Result page (1-based).
- `page_size` (integer, optional, default 20) — Reviews per page, 1-50.

**Returns:** results[]{id, date, author, persona, text, text_translated, language, scores{…}, like_count, location{id, name}} + aggregate{…} + total + page + total_pages + has_next

**Example request body:**
```json
{
  "location_id": "1"
}
```

### POST https://api.reefapi.com/propertyfinder/v1/projects — 1 credit
New (off-plan) projects on one portal, paged as the site's new-projects search shows them: name, developer, location, starting price and price range, bedrooms, property types, handover date, construction and sales phase, payment plans, down payment, amenities. Filters: location, developer, property type, bedrooms, price, handover date, ready / off-plan, post-handover payment plan.

**Parameters:**
- `country` (enum, optional, default "ae") — Which Property Finder portal: ae (propertyfinder.ae, default), sa, qa, bh, eg. [one of: ae, sa, qa, bh, eg]
- `language` (enum, optional, default "en") — Language of the texts the site returns. [one of: en, ar]
- `location_id` (array, optional) — Location id(s) from `locations`.
- `developer_id` (array, optional) — Developer id(s) (uuid, from `developers` or a project's developer.id).
- `property_type` (array, optional) — Property type(s). [one of: apartment, villa, townhouse, penthouse, compound, duplex, full_floor, half_floor, whole_building, land, bulk_sale_unit, bungalow, hotel_apartment, bulk_rent_unit, office, retail, warehouse, shop, showroom, factory, labor_camp, staff_accommodation, business_centre, coworking, farm]
- `bedrooms` (array, optional) — Bedrooms: studio, 1-7, 7+.
- `min_price` (integer, optional) — Minimum starting price.
- `max_price` (integer, optional) — Maximum starting price.
- `completion_status` (enum, optional) — Ready or off-plan. [one of: ready, off_plan]
- `delivery_date_from` (string, optional) — Handover on/after this date (YYYY-MM-DD).
- `post_handover_payment_plan` (boolean, optional) — Only projects with a post-handover payment plan.
- `sort` (enum, optional, default "featured") — Order. [one of: featured, price_asc, price_desc, delivery_date_asc, delivery_date_desc, newest]
- `page` (integer, optional, default 1) — Result page (1-based).

**Returns:** results[]{id, title, slug, url, developer{…}, location{…}, starting_price, price_range{min, max}, bedrooms[], property_types[], delivery_date, construction_phase, sales_phase, payment_plans[], down_payment_percentage, amenities[], images[], contact{…}} + total + total_from_developers + total_resale + page + total_pages + has_next

**Example request body:**
```json
{
  "country": "ae"
}
```

### POST https://api.reefapi.com/propertyfinder/v1/project — 1 credit
One new project: description, developer, master plan, location with coordinates, starting price and price range, unit types with sizes and prices, payment plans, handover and construction timeline, amenities, images, brochure, FAQs, agents marketing it, recent sales in the building and similar projects.

**Parameters:**
- `project` (string, required) — Project path '<developer-slug>/<project-slug>' (a project's `slug`) or its new-projects link.
- `country` (enum, optional, default "ae") — Which Property Finder portal: ae (propertyfinder.ae, default), sa, qa, bh, eg. [one of: ae, sa, qa, bh, eg]
- `language` (enum, optional, default "en") — Language of the texts the site returns. [one of: en, ar]

**Returns:** project{id, title, slug, url, description, developer{…}, location{…}, starting_price, units[], payment_plans[], timeline_phases[], amenities[], images[], faqs[], agents[], historical_transactions{…}, listings_count, similar_projects[]}

**Example request body:**
```json
{
  "project": "nakheel/podium-villas"
}
```

### POST https://api.reefapi.com/propertyfinder/v1/developers — 1 credit
Find property developers (and their projects) by name with the site's new-projects autocomplete.

**Parameters:**
- `query` (string, required) — Developer or project name (2+ characters).
- `country` (enum, optional, default "ae") — Which Property Finder portal: ae (propertyfinder.ae, default), sa, qa, bh, eg. [one of: ae, sa, qa, bh, eg]
- `language` (enum, optional, default "en") — Language of the texts the site returns. [one of: en, ar]
- `page_size` (integer, optional, default 10) — Matches per group (developers, projects), 1-15 — the site's own maximum (16 answers 'max bucket size 15').

**Returns:** developers[]{id, name, slug, logo, url} + projects[]{id, title, slug, url, location, hotness_level}

**Example request body:**
```json
{
  "query": "Dubai Marina"
}
```

### POST https://api.reefapi.com/propertyfinder/v1/developer — 1 credit
A developer's page: profile (description, established since, projects online, logo), the developer's projects (first page, paged with `page`) and the per-city project counts.

**Parameters:**
- `developer` (string, required) — Developer slug (e.g. emaar-properties) or its new-projects/dev link.
- `country` (enum, optional, default "ae") — Which Property Finder portal: ae (propertyfinder.ae, default), sa, qa, bh, eg. [one of: ae, sa, qa, bh, eg]
- `language` (enum, optional, default "en") — Language of the texts the site returns. [one of: en, ar]
- `page` (integer, optional, default 1) — Result page (1-based).

**Returns:** developer{id, name, slug, url, description, established_since, projects_online, logo, city_counts[]} + projects[] + total + page + total_pages + has_next

**Example request body:**
```json
{
  "developer": "emaar-properties"
}
```

### POST https://api.reefapi.com/propertyfinder/v1/agents — 1 credit
Search the portal's agent directory: by name, area, language, nationality, service (sale / rent, residential / commercial), property type, SuperAgent; paged with the site's total.

**Parameters:**
- `country` (enum, optional, default "ae") — Which Property Finder portal: ae (propertyfinder.ae, default), sa, qa, bh, eg. [one of: ae, sa, qa, bh, eg]
- `language` (enum, optional, default "en") — Language of the texts the site returns. [one of: en, ar]
- `name` (string, optional) — Agent name (or part of it).
- `location_id` (string, optional) — Location id the agent works in (from `locations`).
- `spoken_language` (array, optional) — Spoken language id(s) as the site numbers them: 1 English, 2 Arabic, 3 French, 5 German, 6 Russian, 7 Hindi, 8 Urdu, 21 Mandarin …
- `nationality` (string, optional) — Nationality ISO code (e.g. GB, IN, EG).
- `service` (enum, optional) — Service the agent offers. [one of: buy, rent, commercial_buy, commercial_rent]
- `property_type` (string, optional) — Property type the agent lists. [one of: apartment, villa, townhouse, penthouse, compound, duplex, full_floor, half_floor, whole_building, land, bulk_sale_unit, bungalow, hotel_apartment, bulk_rent_unit, office, retail, warehouse, shop, showroom, factory, labor_camp, staff_accommodation, business_centre, coworking, farm]
- `super_agent` (boolean, optional) — Only SuperAgents.
- `agency_id` (string, optional) — Only agents of this agency.
- `sort` (enum, optional, default "featured") — Order. [one of: featured, most_for_sale, most_for_rent]
- `page` (integer, optional, default 1) — Result page (1-based).
- `page_size` (integer, optional, default 20) — Agents per page, 1-100.

**Returns:** results[]{id, name, profile_url, position, phone, whatsapp, email, image, is_super_agent, is_verified, nationality, languages[], experience_since, listings{…}, rating, review_count, agency{…}} + total + page + total_pages + has_next

**Example request body:**
```json
{
  "country": "ae"
}
```

### POST https://api.reefapi.com/propertyfinder/v1/agent — 1 credit
One agent's public profile: bio, position, nationality, languages, experience, licence, listing counts by type, rating and review count with the distribution, WhatsApp response time, top locations, claimed transactions and the agency.

**Parameters:**
- `agent_id` (string, required) — Agent id (e.g. 303271) or an agent profile link.
- `country` (enum, optional, default "ae") — Which Property Finder portal: ae (propertyfinder.ae, default), sa, qa, bh, eg. [one of: ae, sa, qa, bh, eg]
- `language` (enum, optional, default "en") — Language of the texts the site returns. [one of: en, ar]

**Returns:** agent{…every agents field…, bio, license_number, top_locations[], claimed_transactions{…}, rating_distribution{…}, compliances[]}

**Example request body:**
```json
{
  "agent_id": "303271"
}
```

### POST https://api.reefapi.com/propertyfinder/v1/agent_listings — 1 credit
Every live listing of one agent, paged, with the same filters and sorting as `search`.

**Parameters:**
- `agent_id` (string, required) — Agent id.
- `country` (enum, optional, default "ae") — Which Property Finder portal: ae (propertyfinder.ae, default), sa, qa, bh, eg. [one of: ae, sa, qa, bh, eg]
- `language` (enum, optional, default "en") — Language of the texts the site returns. [one of: en, ar]
- `category` (enum, optional, default "buy") — What to search: buy (default), rent, commercial_buy, commercial_rent. [one of: buy, rent, commercial_buy, commercial_rent]
- `location` (string, optional) — Place name (city, community, sub-community or building). The engine resolves it with the site's own location search and uses the best match; the match is echoed in `location`.
- `location_ids` (array, optional) — One or more Property Finder location ids (from `locations`), comma-separated.
- `property_type` (array, optional) — One or more property types (names below or numeric type ids), comma-separated. [one of: apartment, villa, townhouse, penthouse, compound, duplex, full_floor, half_floor, whole_building, land, bulk_sale_unit, bungalow, hotel_apartment, bulk_rent_unit, office, retail, warehouse, shop, showroom, factory, labor_camp, staff_accommodation, business_centre, coworking, farm]
- `bedrooms` (array, optional) — Bedroom counts, comma-separated: studio, 1-7, 7+ (any of them matches).
- `bathrooms` (array, optional) — Bathroom counts, comma-separated: 1-7, 7+.
- `min_price` (integer, optional) — Minimum price (local currency).
- `max_price` (integer, optional) — Maximum price (local currency).
- `min_area` (integer, optional) — Minimum size in the portal's area unit (sqft on .ae/.qa/.bh, sqm on .sa/.eg).
- `max_area` (integer, optional) — Maximum size in the portal's area unit.
- `min_plot_size` (integer, optional) — Minimum plot size.
- `max_plot_size` (integer, optional) — Maximum plot size.
- `min_price_per_area` (integer, optional) — Minimum price per area unit.
- `max_price_per_area` (integer, optional) — Maximum price per area unit.
- `furnished` (enum, optional) — Furnishing. [one of: furnished, unfurnished, partly_furnished]
- `completion_status` (enum, optional) — Ready or off-plan. [one of: ready, off_plan]
- `price_period` (enum, optional) — Rent: only listings priced per this period. [one of: yearly, monthly, weekly, daily]
- `keywords` (string, optional) — Keyword the listing must mention (the site's keyword box).
- `text` (string, optional) — Free-text search across the listing (the site's full-text query).
- `listed_within` (enum, optional) — Only listings added in the last 1d / 7d / 15d / 30d / 90d (or the day count). [one of: 1d, 7d, 15d, 30d, 90d]
- `amenities` (array, optional) — Amenities, comma-separated, all must match: two-letter codes (AC, BA, PP, PA, …) or their names (private pool, pets allowed, …). [one of: AC, MR, BA, SP, SS, SY, CS, CP, VW, BL, PA, ST, PG, PP, PY, PJ, BW, WC, BK, MS, PR, CO, BR]
- `mortgage_cashback` (boolean, optional) — Only listings with a mortgage cashback offer.
- `virtual_viewings` (array, optional) — Only listings with this kind of virtual viewing. [one of: floor_plan, 360_tours, video, live]
- `deal_badges` (array, optional) — Only listings carrying this badge. [one of: great_value, high_demand, price_drop]
- `delivery_date_from` (string, optional) — Off-plan handover on/after this date (YYYY-MM-DD).
- `delivery_date_to` (string, optional) — Off-plan handover on/before this date (YYYY-MM-DD).
- `post_handover_payment_plan` (boolean, optional) — Only off-plan listings with a post-handover payment plan.
- `upgraded` (boolean, optional) — Only listings marked upgraded.
- `extended` (boolean, optional) — Only listings marked extended.
- `landscaped` (boolean, optional) — Only listings marked landscaped.
- `min_cheques` (integer, optional) — Rent: minimum number of cheques accepted.
- `max_cheques` (integer, optional) — Rent: maximum number of cheques accepted.
- `latitude` (number, optional) — Search around a point: latitude (with longitude + radius_km).
- `longitude` (number, optional) — Search around a point: longitude.
- `radius_km` (number, optional) — Search around a point: radius in km (default 2).
- `sort` (enum, optional, default "featured") — Sort order. featured re-ranks between calls; newest shifts by the listings added between two page calls; price / bedrooms sorts page without gaps (0 overlaps over 3 pages, measured). [one of: featured, newest, price_asc, price_desc, bedrooms_asc, bedrooms_desc, delivery_date_asc, delivery_date_desc, price_per_area_asc, price_per_area_desc]
- `page` (integer, optional, default 1) — Result page, 1-50: the site's search serves its first 50 pages of any query (up to 3000 listings at page_size 60); narrow the filters to reach more.
- `page_size` (integer, optional, default 25) — Listings per page, 1-60 (the site's own maximum).

**Returns:** results[] (search rows) + total + page + total_pages + has_next

**Example request body:**
```json
{
  "agent_id": "303271"
}
```

### POST https://api.reefapi.com/propertyfinder/v1/agencies — 1 credit
Search the portal's agency (real-estate company) directory by name, area and service; paged with the site's total.

**Parameters:**
- `country` (enum, optional, default "ae") — Which Property Finder portal: ae (propertyfinder.ae, default), sa, qa, bh, eg. [one of: ae, sa, qa, bh, eg]
- `language` (enum, optional, default "en") — Language of the texts the site returns. [one of: en, ar]
- `name` (string, optional) — Agency name (or part of it).
- `location_id` (string, optional) — Location id (from `locations`).
- `service` (enum, optional) — Service offered. [one of: buy, rent, commercial_buy, commercial_rent]
- `sort` (enum, optional, default "featured") — Order. [one of: featured, name]
- `page` (integer, optional, default 1) — Result page (1-based).
- `page_size` (integer, optional, default 20) — Agencies per page, 1-100.

**Returns:** results[]{id, name, profile_url, phone, email, address, location, license_number, logo, listings{…}, total_agents, total_super_agents, description} + total + page + total_pages + has_next

**Example request body:**
```json
{
  "page_size": 5
}
```

### POST https://api.reefapi.com/propertyfinder/v1/agency — 1 credit
One agency's profile: name, licence, phone, e-mail, address, description, logo, listing counts by type, number of agents and SuperAgents, awards, branches.

**Parameters:**
- `agency_id` (string, required) — Agency id (e.g. 10438) or a broker profile link.
- `country` (enum, optional, default "ae") — Which Property Finder portal: ae (propertyfinder.ae, default), sa, qa, bh, eg. [one of: ae, sa, qa, bh, eg]
- `language` (enum, optional, default "en") — Language of the texts the site returns. [one of: en, ar]

**Returns:** agency{…every agencies field…, awards[], is_main_branch, total_branches}

**Example request body:**
```json
{
  "agency_id": "10438"
}
```

### POST https://api.reefapi.com/propertyfinder/v1/agency_agents — 1 credit
Every agent of one agency, paged with the site's total.

**Parameters:**
- `agency_id` (string, required) — Agency id.
- `country` (enum, optional, default "ae") — Which Property Finder portal: ae (propertyfinder.ae, default), sa, qa, bh, eg. [one of: ae, sa, qa, bh, eg]
- `language` (enum, optional, default "en") — Language of the texts the site returns. [one of: en, ar]
- `sort` (enum, optional, default "featured") — Order. [one of: featured, most_for_sale, most_for_rent]
- `page` (integer, optional, default 1) — Result page (1-based).
- `page_size` (integer, optional, default 20) — Agents per page, 1-100.

**Returns:** results[] (agents rows) + total + page + total_pages + has_next

**Example request body:**
```json
{
  "agency_id": "10438"
}
```

### POST https://api.reefapi.com/propertyfinder/v1/agency_listings — 1 credit
Every live listing of one agency, paged, with the same filters and sorting as `search`.

**Parameters:**
- `agency_id` (string, required) — Agency id.
- `country` (enum, optional, default "ae") — Which Property Finder portal: ae (propertyfinder.ae, default), sa, qa, bh, eg. [one of: ae, sa, qa, bh, eg]
- `language` (enum, optional, default "en") — Language of the texts the site returns. [one of: en, ar]
- `category` (enum, optional, default "buy") — What to search: buy (default), rent, commercial_buy, commercial_rent. [one of: buy, rent, commercial_buy, commercial_rent]
- `location` (string, optional) — Place name (city, community, sub-community or building). The engine resolves it with the site's own location search and uses the best match; the match is echoed in `location`.
- `location_ids` (array, optional) — One or more Property Finder location ids (from `locations`), comma-separated.
- `property_type` (array, optional) — One or more property types (names below or numeric type ids), comma-separated. [one of: apartment, villa, townhouse, penthouse, compound, duplex, full_floor, half_floor, whole_building, land, bulk_sale_unit, bungalow, hotel_apartment, bulk_rent_unit, office, retail, warehouse, shop, showroom, factory, labor_camp, staff_accommodation, business_centre, coworking, farm]
- `bedrooms` (array, optional) — Bedroom counts, comma-separated: studio, 1-7, 7+ (any of them matches).
- `bathrooms` (array, optional) — Bathroom counts, comma-separated: 1-7, 7+.
- `min_price` (integer, optional) — Minimum price (local currency).
- `max_price` (integer, optional) — Maximum price (local currency).
- `min_area` (integer, optional) — Minimum size in the portal's area unit (sqft on .ae/.qa/.bh, sqm on .sa/.eg).
- `max_area` (integer, optional) — Maximum size in the portal's area unit.
- `min_plot_size` (integer, optional) — Minimum plot size.
- `max_plot_size` (integer, optional) — Maximum plot size.
- `min_price_per_area` (integer, optional) — Minimum price per area unit.
- `max_price_per_area` (integer, optional) — Maximum price per area unit.
- `furnished` (enum, optional) — Furnishing. [one of: furnished, unfurnished, partly_furnished]
- `completion_status` (enum, optional) — Ready or off-plan. [one of: ready, off_plan]
- `price_period` (enum, optional) — Rent: only listings priced per this period. [one of: yearly, monthly, weekly, daily]
- `keywords` (string, optional) — Keyword the listing must mention (the site's keyword box).
- `text` (string, optional) — Free-text search across the listing (the site's full-text query).
- `listed_within` (enum, optional) — Only listings added in the last 1d / 7d / 15d / 30d / 90d (or the day count). [one of: 1d, 7d, 15d, 30d, 90d]
- `amenities` (array, optional) — Amenities, comma-separated, all must match: two-letter codes (AC, BA, PP, PA, …) or their names (private pool, pets allowed, …). [one of: AC, MR, BA, SP, SS, SY, CS, CP, VW, BL, PA, ST, PG, PP, PY, PJ, BW, WC, BK, MS, PR, CO, BR]
- `mortgage_cashback` (boolean, optional) — Only listings with a mortgage cashback offer.
- `virtual_viewings` (array, optional) — Only listings with this kind of virtual viewing. [one of: floor_plan, 360_tours, video, live]
- `deal_badges` (array, optional) — Only listings carrying this badge. [one of: great_value, high_demand, price_drop]
- `delivery_date_from` (string, optional) — Off-plan handover on/after this date (YYYY-MM-DD).
- `delivery_date_to` (string, optional) — Off-plan handover on/before this date (YYYY-MM-DD).
- `post_handover_payment_plan` (boolean, optional) — Only off-plan listings with a post-handover payment plan.
- `upgraded` (boolean, optional) — Only listings marked upgraded.
- `extended` (boolean, optional) — Only listings marked extended.
- `landscaped` (boolean, optional) — Only listings marked landscaped.
- `min_cheques` (integer, optional) — Rent: minimum number of cheques accepted.
- `max_cheques` (integer, optional) — Rent: maximum number of cheques accepted.
- `latitude` (number, optional) — Search around a point: latitude (with longitude + radius_km).
- `longitude` (number, optional) — Search around a point: longitude.
- `radius_km` (number, optional) — Search around a point: radius in km (default 2).
- `sort` (enum, optional, default "featured") — Sort order. featured re-ranks between calls; newest shifts by the listings added between two page calls; price / bedrooms sorts page without gaps (0 overlaps over 3 pages, measured). [one of: featured, newest, price_asc, price_desc, bedrooms_asc, bedrooms_desc, delivery_date_asc, delivery_date_desc, price_per_area_asc, price_per_area_desc]
- `page` (integer, optional, default 1) — Result page, 1-50: the site's search serves its first 50 pages of any query (up to 3000 listings at page_size 60); narrow the filters to reach more.
- `page_size` (integer, optional, default 25) — Listings per page, 1-60 (the site's own maximum).

**Returns:** results[] (search rows) + total + page + total_pages + has_next

**Example request body:**
```json
{
  "agency_id": "10438"
}
```

## At scale
- **Volume:** 5M+ requests a day, measured at 60 requests a second across the fleet with no
  central bottleneck. Per-key limits are raised for high-volume accounts; volume pricing on request.
- **Missing a source:** tell us a site we do not cover and it becomes an engine. A customer asked
  for bestprice.gr on 21 Sep 2026 and it was in the catalog on 22 Sep.
- **Support:** 2 minute median time from a question in the live chat to the first answer. Setup
  help included, no support tier to buy.
- **One key, one credit pool** across every API. No per-site plans, no separate subscriptions.

## More
- Try it live, no code: https://reefapi.com/playground?engine=propertyfinder
- Human docs page: https://reefapi.com/docs/propertyfinder
- Overview page: https://reefapi.com/propertyfinder-api
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt
