◈ Real Estate Data API

عقارساس API

Programmatic access to Saudi Arabia's real estate market. Query historical transactions, aggregated market statistics, top deals by price or area, full property lookups with their deal history, and rental contract records. Data is sourced from the Ministry of Justice (MOJ) and the Real Estate Registry (RER); responses are JSON with Arabic labels by default. accounts with spatial data access additionally receive geographic coordinates.

HTTPS Only POST JSON Arabic Results
01 — Authentication

API Key

Every request must include your API key. Keys are issued by our support team — contact us to request one.

⚠
API access is available through the API Integration plan. Spatial access (Lng, Lat, Elevation, Coords) and Ejar API (rental data) are available as optional add-ons. Contact our support team for access.
🔑
Include your key field in every JSON request body. Requests without a valid key will return an error response immediately.
JSON · Request skeleton
{
  "key": "YOUR_API_KEY_HERE",
  // ... additional parameters
}
02 — Errors

Error Codes

All responses include an Error_code and Error_msg field.

0
No error. Request processed successfully. Results are in the response body.
1
Error occurred. Check Error_msg for a detailed explanation.
03 — Reference

Regions & States

Use the integer ID when filtering by state.

0Riyadh — الرياض
1Makkah — مكة
2Medina — المدينة
3Al-Qasim — القصيم
4Eastern — الشرقية
5Asir — عسير
6Tabuk — تبوك
7Ha'il — حائل
8N. Borders — الحدود الشمالية
9Jizan — جازان
10Najran — نجران
11Al-Bahah — الباحة
12Al-Jawf — الجوف
Endpoint 01

Get Real Estate Transactions

Search and filter transaction records with up to 5,000 results per request.

Transactions Search
الاستعلام عن الصفقات
POST https://api.aqarsas.sa/transactions/
Returns transaction records matching your filters. If results exceed 5,000, a random selection of 5,000 is returned. Results are in Arabic.
Request Parameters
ParameterTypeDefaultDescription
keyrequiredstring—Your API key.
calendarstringgregorianhijri or gregorian
start_datestringnoneFormat: yyyy-mm-dd
end_datestringnoneFormat: yyyy-mm-dd
categoryenumnoneOne of:
سكني تجاري زراعي
dtypeenumnoneProperty type — one of 46 values.
Show all values
قطعة أرضشقةفيلامعرض/محلبيتوحدة عقاريةوحدة سكنيةعمارةمرفقوحدة تجاريةإستراحةمركز تجاريمحل تجاريقصرمكتبمعرضصالة تجاريةشاليهسوق تجاريسطحمطعمأرض فضاءأخرىبرجحديقةدورزائدة تنظيميةشقة سكنيفندقمبنىمبنى تجاريمبنى سكنيمبنى سكني/تجاريمجمع تجاريمجمع سكنيمجمع سكني/ تجاريمحطة وقودمحلمرفق تعليميمرفق خدمةمرفق صحيمرفق صناعيمزرعةمستودعمواقفأرض زراعية
stateintegernoneRegion ID (0–12). See Regions table above.
citystringnoneExact city name match.
min_meter_priceinteger0Minimum price per m².
max_meter_priceintegernoneMaximum price per m².
min_deal_priceinteger0Minimum total deal value (SAR).
max_deal_priceintegernoneMaximum total deal value (SAR).
min_areainteger0Minimum area in m².
max_areaintegernoneMaximum area in m².
haistringnoneNeighborhood (حي) name.
hai_exact_matchinteger01 = exact, 0 = fuzzy search (recommended).
m566stringnonePlan number (مخطط).
m566_exact_matchinteger01 = exact, 0 = fuzzy (recommended).
unitstringnoneUnit number (قطعة).
unit_exact_matchinteger01 = exact, 0 = fuzzy (recommended).
Response Fields
Error_code0 = success, 1 = error
Error_msgError message if applicable
Deals_list[]
Array of transaction objects. Per-row fields:
DatestringTransaction date, formatted DD/MM/YYYY (Hijri if calendar=hijri).
CategorystringProperty category: سكني, تجاري, زراعي, or أخرى.
DtypestringProperty kind (e.g. قطعة أرض, مبنى, شقة).
aqarsas_intelligenceobject (optional)Aqarsas Intelligence: our verified real-estate type, returned only when it differs from the registry's record. Shape: {"Dtype": "وحدة"}. The registry's original value always remains in Dtype untouched. See the dedicated row below.
Meter_priceintegerPrice per square meter, in SAR.
Deal_priceintegerTotal deal price, in SAR.
AreanumberProperty area, in m².
StateintegerRegion code (0–12). See Regions / States for mapping.
CitystringCity name in Arabic.
HaistringDistrict (حي) name in Arabic.
M566stringPlan number (مخطط).
UnitstringUnit/parcel number (قطعة).
Abnormality_explanationstringFlag for non-standard transactions (e.g. mortgage, gift). See the dedicated row below for the full list of values.
Deal_srcstring"moj" (Ministry of Justice transactions) or "rer" (Real Estate Registry).
LngnumberSpatial access only. Longitude in decimal degrees (WGS84 / EPSG:4326). 0 indicates coordinates were unavailable.
LatnumberSpatial access only. Latitude in decimal degrees (WGS84 / EPSG:4326). 0 indicates coordinates were unavailable.
GAccuracyintegerSpatial access only. Coordinate precision: 0 = precise parcel centroid; 1–3 = centroid of a less-precise spatial object; 4+ = a random point inside a bounding box (least precise; subsequent calls for the same row may return slightly different coords).
Abnormality_explanationFlags non-standard transactions; empty string means a normal arm's-length deal. Possible values: رهن (Mortgage), فك رهن (Mortgage Release), هبة (Gift), ورث (Inheritance), مشترك أو مشاع (Shared), صفقة بتمويل (Financed Deal), فرز/دمج (Partition or Merge), بيع مرهون (Mortgaged Sale). Suffix (غير مؤكد) means the classification is unconfirmed. Multiple labels are joined by "/".
aqarsas_intelligenceAqarsas Intelligence: our verified real-estate type, returned only when it differs from the registry's record. The registry's original value always remains in Dtype untouched. Present only on corrected rows and absent otherwise — treat it as optional and always fall back to Dtype. The value is the corrected type name in Arabic, in the same format as the existing Dtype field, e.g. {"aqarsas_intelligence": {"Dtype": "وحدة"}}.
Example
JSON · Request
{
  "key": "your_api_key",
  "state": 0,
  "city": "الرياض",
  "hai": "النرجس",
  "m566": "2670",
  "start_date": "2026-05-01",
  "end_date": "2026-05-31"
}
JSON · Response
{
  "Error_code": 0,
  "Error_msg": "",
  "Deals_list": [
    {
      "Date": "07/05/2026", "Category": "سكني", "Dtype": "أرض فضاء",
      "Meter_price": 4850, "Deal_price": 1455000, "Area": 300,
      "State": 0, "City": "الرياض", "Hai": "النرجس",
      "M566": "2670", "Unit": "314",
      "Abnormality_explanation": "",
      "Deal_src": "rer"
    },
    {
      "Date": "20/05/2026", "Category": "سكني", "Dtype": "مبنى سكني",
      "aqarsas_intelligence": { "Dtype": "وحدة" },
      "Meter_price": 0, "Deal_price": 0, "Area": 280,
      "State": 0, "City": "الرياض", "Hai": "النرجس",
      "M566": "2670", "Unit": "108",
      "Abnormality_explanation": "هبة",
      "Deal_src": "rer"
    }
  ]
}
Endpoint 02

Get Statistics

Aggregate market statistics by deal count, total value, or total area — by region, city, hai, and date range.

Market Statistics
إحصائيات عامة عن الصفقات
POST https://api.aqarsas.sa/stats/
Returns aggregated statistics (number, value, or area of deals) broken down by category and property type.
Request Parameters
ParameterTypeDefaultDescription
keyrequiredstring—Your API key.
stat_typestringvalue_of_dealsnumber_of_deals, value_of_deals, or area_of_deals
calendarstringgregorianhijri or gregorian
start_datestringnoneFormat: yyyy-mm-dd
end_datestringnoneFormat: yyyy-mm-dd
stateintegernoneRegion ID (0–12).
citystringnoneExact city name match.
haistringnoneDistrict name. If provided, city becomes required.
Response Fields
Error_code0 = success, 1 = error
Error_msgError message if applicable
Stats_list[]Array of objects: Category, Dtype, Stat (the aggregated value for the given stat_type)
Example
JSON · Request
{
  "key": "your_api_key",
  "stat_type": "value_of_deals",
  "start_date": "2026-05-01",
  "end_date": "2026-05-31",
  "city": "الرياض",
  "hai": "النرجس"
}
JSON · Response
{
  "Error_code": 0,
  "Error_msg": "",
  "Stats_list": [
    {"Stat": 182298361, "Category": "قطعة أرض",   "Dtype": "سكني"},
    {"Stat":  12961423, "Category": "قطعة أرض",   "Dtype": "تجاري"},
    {"Stat":   5605000, "Category": "شقة",        "Dtype": "سكني"},
    {"Stat": 117746420, "Category": "مبنى",       "Dtype": "سكني"},
    {"Stat":  15126351, "Category": "مبنى",       "Dtype": "تجاري"}
  ]
}
Endpoint 03

Get Top Transactions

Sort and retrieve top-ranked transactions by date, price, meter price, or area.

Top Transactions
أعلى وأقل الصفقات
POST https://api.aqarsas.sa/toptransactions/
Returns ranked transactions (ascending or descending) based on your chosen sort field. Up to 5,000 records.
Request Parameters
ParameterTypeDefaultDescription
keyrequiredstring—Your API key.
calendarstringgregorianhijri or gregorian
start_datestringnoneFormat: yyyy-mm-dd
end_datestringnoneFormat: yyyy-mm-dd
stateintegernoneRegion ID (0–12).
citystringnoneExact city name.
haistringnoneNeighborhood (حي) name.
hai_exact_matchinteger00 = fuzzy (recommended), 1 = exact.
sort_bystring (enum)s3rOne of: s3r (total deal price, default), s3ralmtr (price per m²), area. Date sorting is not supported here — use /transactions/ for date-ordered results.
sort_by_ascendinginteger00 = descending (highest first), 1 = ascending.
results_ninteger5000Number of results. Range: 1–5000.
Response Fields
Error_code0 = success, 1 = error
Error_msgError message if applicable
Deals_list[]
Array of transaction objects, sorted by the chosen sort_by field. Per-row fields:
DatestringTransaction date, formatted DD/MM/YYYY (Hijri if calendar=hijri).
CategorystringProperty category: سكني, تجاري, زراعي, or أخرى.
DtypestringProperty kind (e.g. قطعة أرض, مبنى, شقة).
Meter_priceintegerPrice per square meter, in SAR.
Deal_priceintegerTotal deal price, in SAR.
AreanumberProperty area, in m².
StateintegerRegion code (0–12). See Regions / States for mapping.
CitystringCity name in Arabic.
HaistringDistrict (حي) name in Arabic.
M566stringPlan number (مخطط).
UnitstringUnit/parcel number (قطعة).
Abnormality_explanationstringFlag for non-standard transactions (e.g. mortgage, gift). See the dedicated row below for the full list of values.
Deal_srcstring"moj" (Ministry of Justice transactions) or "rer" (Real Estate Registry).
LngnumberSpatial access only. Longitude in decimal degrees (WGS84 / EPSG:4326). 0 indicates coordinates were unavailable.
LatnumberSpatial access only. Latitude in decimal degrees (WGS84 / EPSG:4326). 0 indicates coordinates were unavailable.
GAccuracyintegerSpatial access only. Coordinate precision: 0 = precise parcel centroid; 1–3 = centroid of a less-precise spatial object; 4+ = a random point inside a bounding box (least precise; subsequent calls for the same row may return slightly different coords).
Abnormality_explanationFlags non-standard transactions; empty string means a normal arm's-length deal. Possible values: رهن (Mortgage), فك رهن (Mortgage Release), هبة (Gift), ورث (Inheritance), مشترك أو مشاع (Shared), صفقة بتمويل (Financed Deal), فرز/دمج (Partition or Merge), بيع مرهون (Mortgaged Sale). Suffix (غير مؤكد) means the classification is unconfirmed. Multiple labels are joined by "/".
Example
JSON · Request
{
  "key": "your_api_key",
  "state": 0,
  "start_date": "2026-05-01",
  "end_date": "2026-05-31",
  "sort_by": "s3r",
  "results_n": 5
}
JSON · Response
{
  "Error_code": 0,
  "Error_msg": "",
  "Deals_list": [
    {
      "Date": "20/05/2026", "Category": "سكني", "Dtype": "أرض فضاء",
      "Meter_price": 810, "Deal_price": 699192000, "Area": 863200,
      "State": 0, "City": "الرياض", "Hai": "السلي",
      "M566": "...", "Unit": "...",
      "Abnormality_explanation": "", "Deal_src": "rer"
    },
    {
      "Date": "07/05/2026", "Category": "تجاري", "Dtype": "أرض فضاء",
      "Meter_price": 23366, "Deal_price": 420000000, "Area": 17975,
      "State": 0, "City": "الرياض", "Hai": "النفل",
      "M566": "...", "Unit": "...",
      "Abnormality_explanation": "", "Deal_src": "rer"
    }
  ]
}
Endpoint 04

Get Property Details

Look up a specific land or property and retrieve its full transaction history.

Property Details & Deal Archive
تفاصيل العقار وأرشيف صفقاته
POST https://api.aqarsas.sa/propertydetails/
Returns up to 5 matching property records. If multiple match, they are sorted by closest area. Each record includes its full transaction history.
Request Parameters
💡
If rer_realestate_number is provided, all other lookup parameters (state, city, m566, unit) are not required.
ParameterTypeDefaultDescription
keyrequiredstring—Your API key.
rer_realestate_numberstringnoneReal estate registry number. If provided, all other lookup parameters are not required.
staterequired*integer—Region ID (0–12). *Required if rer_realestate_number is not provided.
cityrequired*string—Exact city name. *Required if rer_realestate_number is not provided.
m566required*string—Plan number (مخطط). *Required if rer_realestate_number is not provided.
unitrequired*string—Unit number (قطعة). *Required if rer_realestate_number is not provided.
areanumbernoneOptional but recommended. Area in m². Returns properties within ±15% range, sorted by closest match.
Response Fields
Error_code0 = success, 1 = error
Error_msgError message if applicable
Lands_countNumber of matching property records found
Land_Details[]
Array of matching property records (up to 5 from moj + up to 5 from rer). Per-record fields:
M566stringPlan number (مخطط).
UnitstringUnit/parcel number (قطعة).
AreastringProperty area in m² (returned as a string).
StateintegerRegion code (0–12). See Regions / States.
CitystringCity name in Arabic.
ExactMatchDealsCountintegerNumber of transactions on this exact parcel (capped at 100 per record).
ExactMatchDeals[]arrayPer-deal sub-fields shown below.
CoordsobjectSpatial access only. {lng, lat} in decimal degrees (WGS84 / EPSG:4326).
ElevationnumberSpatial access only. Ground elevation in meters above sea level.
LandUsePrimarystringSpatial access only. Primary zoning category.
LandUseSecondarystringSpatial access only. Secondary zoning category.
LandUseDetailedstringSpatial access only. Detailed zoning label.
RelevantDealsCountintegerSpatial access only. Number of deals on the same plan/area (capped at 100).
RelevantDeals[]arraySpatial access only. Same per-deal shape as ExactMatchDeals[].
Each entry in ExactMatchDeals[] / RelevantDeals[]:
KindstringProperty kind (Arabic).
DegreestringProperty category: سكني, تجاري, زراعي, or أخرى.
S3ralmtrintegerPrice per square meter, in SAR.
S3rintegerTotal deal price, in SAR.
Msa7hnumberProperty area, in m².
HdatestringTransaction date (Hijri).
MdatestringTransaction date (Gregorian).
RegionstringRegion code (as string).
CitystringCity name in Arabic.
DistrictstringDistrict (حي) name in Arabic.
M566stringPlan number (مخطط).
QitahstringUnit/parcel number (قطعة).
Spatial-only fields are returned only for accounts with spatial data access, either when looking up by rer_realestate_number, or when querying one of: الرياض, الدرعيه, عرقه, الجبيلة, الدمام, الخبر, الجبيل, القطيف, جده, مكة المكرمة, المدينة المنورة.
Example
JSON · Request
{
  "key": "your_api_key",
  "rer_realestate_number": "1234567890000000"
}
JSON · Response
{
  "Lands_count": 1,
  "Land_Details": [
    {
      "M566": "2670", "Unit": "47", "Area": "300",
      "State": 0, "City": "الرياض",
      "Elevation": 683.9,
      "LandUsePrimary": "سكنى",
      "LandUseDetailed": "فيلا أسرة واحدة",
      "Coords": { "lng": 46.6544, "lat": 24.88 },
      "ExactMatchDealsCount": 1,
      "ExactMatchDeals": [
        {
          "Kind": "أرض فضاء", "Degree": "سكني",
          "S3ralmtr": 4850, "S3r": 1455000, "Msa7h": 300,
          "Hdate": "1447-11-20", "Mdate": "2026-05-07",
          "City": "الرياض", "District": "النرجس",
          "M566": "2670", "Qitah": "47"
        }
      ],
      "RelevantDeals": []
    }
  ],
  "Error_code": 0,
  "Error_msg": ""
}
Endpoint 05

Get Nearby Transactions

Find real estate transactions in the vicinity of a specific property. Identify the property by either its RER number, or by the unique tuple (state, city, m566, unit).

Nearby Transactions
الصفقات المجاورة للعقار
POST https://api.aqarsas.sa/nearbytransactions/
Returns recent deals on properties around a specific reference property. Useful for comparable market analysis. The reference property is identified either by its RER number or by the unique tuple (state, city, m566, unit) — exactly one match is required.
Request Parameters
ParameterTypeDefaultDescription
keyrequiredstring—Your API key.
rer_realestate_numberrequired*string—Numeric RER property number. *Required if the property is identified via RER. If provided, all other identifiers are ignored.
staterequired**integer—Region ID (0–12). **Required (together with city, m566, unit) when rer_realestate_number is not provided.
cityrequired**string—Exact city name.
m566required**string—Plan number (مخطط).
unitrequired**string—Unit/parcel number (قطعة).
Response Fields
Error_code0 = success, 1 = error
Error_msgError message if applicable
NearbyDeals[]
Array of nearby deal objects. Per-row fields:
Deal_idstringTransaction identifier (RER deals are masked, e.g. **0507).
DatestringTransaction date, DD/MM/YYYY.
DegreestringProperty category: سكني, تجاري, زراعي, or أخرى.
KindstringProperty kind (e.g. قطعة أرض, مبنى, شقة).
Meter_priceintegerPrice per square meter, in SAR.
Deal_pricenumberTotal deal price, in SAR.
AreanumberProperty area, in m².
StateintegerRegion code (0–12). See Regions / States.
CitystringCity name in Arabic.
HaistringDistrict (حي) name in Arabic.
M566stringPlan number (مخطط).
QitahstringUnit/parcel number (قطعة).
GeoDataobjectGeographic + zoning metadata (see sub-fields below). Empty if no spatial record for this property.
GeoData sub-fields (all optional, omitted when not available):
ElevationnumberGround elevation in meters above sea level.
LandUsePrimarystringPrimary zoning category.
LandUseSecondarystringSecondary zoning category.
LandUseDetailedstringDetailed zoning label.
LandStatusstringLand status / classification.
BuildingCodestringApplicable building code identifier.
Example
JSON · Request
{
  "key": "your_api_key",
  "rer_realestate_number": "1234567890000000"
}
JSON · Response
{
  "Error_code": 0,
  "Error_msg": "",
  "NearbyDeals": [
    {
      "Deal_id": "**0507", "Date": "07/05/2026",
      "Degree": "سكني", "Kind": "أرض فضاء",
      "Meter_price": 4850, "Deal_price": 1455000, "Area": 300,
      "State": 0, "City": "الرياض", "Hai": "النرجس",
      "M566": "2670", "Qitah": "314",
      "GeoData": { "Elevation": 683.9 }
    }
  ]
}
🏠
Ejar Rental Data — Available via API
بيانات إيجار متاحة عبر الواجهة البرمجية

We offer dedicated API endpoints for Ejar rental market data. Access rental transactions, pricing trends, and property rental history programmatically. Contact us to learn more and get access.

✉ Contact Us for Ejar API Access
Playground

Try it Live

Enter your API key, pick an endpoint, fill in parameters, and send a real request.

API Key
Endpoint
POST /transactions/
POST /stats/
POST /toptransactions/
POST /propertydetails/
POST /nearbytransactions/
Parameters
Waiting for request…
Response will appear here.
Download

PDF Reference

The complete API documentation in a printable PDF — same content, formatted for offline reading.

📄
PDF
عقارساس API Reference
aqarsas-api-reference.pdf · All 5 endpoints · Examples included
↓ Download PDF