عقارساس 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.
API Key
Every request must include your API key. Keys are issued by our support team — contact us to request one.
key field in every JSON request body. Requests without a valid key will return an error response immediately.{
"key": "YOUR_API_KEY_HERE",
// ... additional parameters
}
Error Codes
All responses include an Error_code and Error_msg field.
Error_msg for a detailed explanation.Regions & States
Use the integer ID when filtering by state.
Get Real Estate Transactions
Search and filter transaction records with up to 5,000 results per request.
| Parameter | Type | Default | Description |
|---|---|---|---|
| keyrequired | string | — | Your API key. |
| calendar | string | gregorian | hijri or gregorian |
| start_date | string | none | Format: yyyy-mm-dd |
| end_date | string | none | Format: yyyy-mm-dd |
| category | enum | none | One of:
سكني
تجاري
زراعي
|
| dtype | enum | none | Property type — one of 46 values.
Show all values
قطعة أرضشقةفيلامعرض/محلبيتوحدة عقاريةوحدة سكنيةعمارةمرفقوحدة تجاريةإستراحةمركز تجاريمحل تجاريقصرمكتبمعرضصالة تجاريةشاليهسوق تجاريسطحمطعمأرض فضاءأخرىبرجحديقةدورزائدة تنظيميةشقة سكنيفندقمبنىمبنى تجاريمبنى سكنيمبنى سكني/تجاريمجمع تجاريمجمع سكنيمجمع سكني/ تجاريمحطة وقودمحلمرفق تعليميمرفق خدمةمرفق صحيمرفق صناعيمزرعةمستودعمواقفأرض زراعية
|
| state | integer | none | Region ID (0–12). See Regions table above. |
| city | string | none | Exact city name match. |
| min_meter_price | integer | 0 | Minimum price per m². |
| max_meter_price | integer | none | Maximum price per m². |
| min_deal_price | integer | 0 | Minimum total deal value (SAR). |
| max_deal_price | integer | none | Maximum total deal value (SAR). |
| min_area | integer | 0 | Minimum area in m². |
| max_area | integer | none | Maximum area in m². |
| hai | string | none | Neighborhood (حي) name. |
| hai_exact_match | integer | 0 | 1 = exact, 0 = fuzzy search (recommended). |
| m566 | string | none | Plan number (مخطط). |
| m566_exact_match | integer | 0 | 1 = exact, 0 = fuzzy (recommended). |
| unit | string | none | Unit number (قطعة). |
| unit_exact_match | integer | 0 | 1 = exact, 0 = fuzzy (recommended). |
| Date | string | Transaction date, formatted DD/MM/YYYY (Hijri if calendar=hijri). |
| Category | string | Property category: سكني, تجاري, زراعي, or أخرى. |
| Dtype | string | Property kind (e.g. قطعة أرض, مبنى, شقة). |
| aqarsas_intelligence | object (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_price | integer | Price per square meter, in SAR. |
| Deal_price | integer | Total deal price, in SAR. |
| Area | number | Property area, in m². |
| State | integer | Region code (0–12). See Regions / States for mapping. |
| City | string | City name in Arabic. |
| Hai | string | District (حي) name in Arabic. |
| M566 | string | Plan number (مخطط). |
| Unit | string | Unit/parcel number (قطعة). |
| Abnormality_explanation | string | Flag for non-standard transactions (e.g. mortgage, gift). See the dedicated row below for the full list of values. |
| Deal_src | string | "moj" (Ministry of Justice transactions) or "rer" (Real Estate Registry). |
| Lng | number | Spatial access only. Longitude in decimal degrees (WGS84 / EPSG:4326). 0 indicates coordinates were unavailable. |
| Lat | number | Spatial access only. Latitude in decimal degrees (WGS84 / EPSG:4326). 0 indicates coordinates were unavailable. |
| GAccuracy | integer | Spatial 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). |
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": "وحدة"}}.{
"key": "your_api_key",
"state": 0,
"city": "الرياض",
"hai": "النرجس",
"m566": "2670",
"start_date": "2026-05-01",
"end_date": "2026-05-31"
}
{
"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"
}
]
}
Get Statistics
Aggregate market statistics by deal count, total value, or total area — by region, city, hai, and date range.
| Parameter | Type | Default | Description |
|---|---|---|---|
| keyrequired | string | — | Your API key. |
| stat_type | string | value_of_deals | number_of_deals, value_of_deals, or area_of_deals |
| calendar | string | gregorian | hijri or gregorian |
| start_date | string | none | Format: yyyy-mm-dd |
| end_date | string | none | Format: yyyy-mm-dd |
| state | integer | none | Region ID (0–12). |
| city | string | none | Exact city name match. |
| hai | string | none | District name. If provided, city becomes required. |
{
"key": "your_api_key",
"stat_type": "value_of_deals",
"start_date": "2026-05-01",
"end_date": "2026-05-31",
"city": "الرياض",
"hai": "النرجس"
}
{
"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": "تجاري"}
]
}
Get Top Transactions
Sort and retrieve top-ranked transactions by date, price, meter price, or area.
| Parameter | Type | Default | Description |
|---|---|---|---|
| keyrequired | string | — | Your API key. |
| calendar | string | gregorian | hijri or gregorian |
| start_date | string | none | Format: yyyy-mm-dd |
| end_date | string | none | Format: yyyy-mm-dd |
| state | integer | none | Region ID (0–12). |
| city | string | none | Exact city name. |
| hai | string | none | Neighborhood (حي) name. |
| hai_exact_match | integer | 0 | 0 = fuzzy (recommended), 1 = exact. |
| sort_by | string (enum) | s3r | One 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_ascending | integer | 0 | 0 = descending (highest first), 1 = ascending. |
| results_n | integer | 5000 | Number of results. Range: 1–5000. |
sort_by field. Per-row fields:
| Date | string | Transaction date, formatted DD/MM/YYYY (Hijri if calendar=hijri). |
| Category | string | Property category: سكني, تجاري, زراعي, or أخرى. |
| Dtype | string | Property kind (e.g. قطعة أرض, مبنى, شقة). |
| Meter_price | integer | Price per square meter, in SAR. |
| Deal_price | integer | Total deal price, in SAR. |
| Area | number | Property area, in m². |
| State | integer | Region code (0–12). See Regions / States for mapping. |
| City | string | City name in Arabic. |
| Hai | string | District (حي) name in Arabic. |
| M566 | string | Plan number (مخطط). |
| Unit | string | Unit/parcel number (قطعة). |
| Abnormality_explanation | string | Flag for non-standard transactions (e.g. mortgage, gift). See the dedicated row below for the full list of values. |
| Deal_src | string | "moj" (Ministry of Justice transactions) or "rer" (Real Estate Registry). |
| Lng | number | Spatial access only. Longitude in decimal degrees (WGS84 / EPSG:4326). 0 indicates coordinates were unavailable. |
| Lat | number | Spatial access only. Latitude in decimal degrees (WGS84 / EPSG:4326). 0 indicates coordinates were unavailable. |
| GAccuracy | integer | Spatial 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). |
{
"key": "your_api_key",
"state": 0,
"start_date": "2026-05-01",
"end_date": "2026-05-31",
"sort_by": "s3r",
"results_n": 5
}
{
"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"
}
]
}
Get Property Details
Look up a specific land or property and retrieve its full transaction history.
rer_realestate_number is provided, all other lookup parameters (state, city, m566, unit) are not required.| Parameter | Type | Default | Description |
|---|---|---|---|
| keyrequired | string | — | Your API key. |
| rer_realestate_number | string | none | Real 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. |
| area | number | none | Optional but recommended. Area in m². Returns properties within ±15% range, sorted by closest match. |
| M566 | string | Plan number (مخطط). |
| Unit | string | Unit/parcel number (قطعة). |
| Area | string | Property area in m² (returned as a string). |
| State | integer | Region code (0–12). See Regions / States. |
| City | string | City name in Arabic. |
| ExactMatchDealsCount | integer | Number of transactions on this exact parcel (capped at 100 per record). |
| ExactMatchDeals[] | array | Per-deal sub-fields shown below. |
| Coords | object | Spatial access only. {lng, lat} in decimal degrees (WGS84 / EPSG:4326). |
| Elevation | number | Spatial access only. Ground elevation in meters above sea level. |
| LandUsePrimary | string | Spatial access only. Primary zoning category. |
| LandUseSecondary | string | Spatial access only. Secondary zoning category. |
| LandUseDetailed | string | Spatial access only. Detailed zoning label. |
| RelevantDealsCount | integer | Spatial access only. Number of deals on the same plan/area (capped at 100). |
| RelevantDeals[] | array | Spatial access only. Same per-deal shape as ExactMatchDeals[]. |
ExactMatchDeals[] / RelevantDeals[]:| Kind | string | Property kind (Arabic). |
| Degree | string | Property category: سكني, تجاري, زراعي, or أخرى. |
| S3ralmtr | integer | Price per square meter, in SAR. |
| S3r | integer | Total deal price, in SAR. |
| Msa7h | number | Property area, in m². |
| Hdate | string | Transaction date (Hijri). |
| Mdate | string | Transaction date (Gregorian). |
| Region | string | Region code (as string). |
| City | string | City name in Arabic. |
| District | string | District (حي) name in Arabic. |
| M566 | string | Plan number (مخطط). |
| Qitah | string | Unit/parcel number (قطعة). |
rer_realestate_number, or when querying one of: الرياض, الدرعيه, عرقه, الجبيلة, الدمام, الخبر, الجبيل, القطيف, جده, مكة المكرمة, المدينة المنورة.{
"key": "your_api_key",
"rer_realestate_number": "1234567890000000"
}
{
"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": ""
}
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).
| Parameter | Type | Default | Description |
|---|---|---|---|
| keyrequired | string | — | 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 (قطعة). |
| Deal_id | string | Transaction identifier (RER deals are masked, e.g. **0507). |
| Date | string | Transaction date, DD/MM/YYYY. |
| Degree | string | Property category: سكني, تجاري, زراعي, or أخرى. |
| Kind | string | Property kind (e.g. قطعة أرض, مبنى, شقة). |
| Meter_price | integer | Price per square meter, in SAR. |
| Deal_price | number | Total deal price, in SAR. |
| Area | number | Property area, in m². |
| State | integer | Region code (0–12). See Regions / States. |
| City | string | City name in Arabic. |
| Hai | string | District (حي) name in Arabic. |
| M566 | string | Plan number (مخطط). |
| Qitah | string | Unit/parcel number (قطعة). |
| GeoData | object | Geographic + zoning metadata (see sub-fields below). Empty if no spatial record for this property. |
GeoData sub-fields (all optional, omitted when not available):| Elevation | number | Ground elevation in meters above sea level. |
| LandUsePrimary | string | Primary zoning category. |
| LandUseSecondary | string | Secondary zoning category. |
| LandUseDetailed | string | Detailed zoning label. |
| LandStatus | string | Land status / classification. |
| BuildingCode | string | Applicable building code identifier. |
{
"key": "your_api_key",
"rer_realestate_number": "1234567890000000"
}
{
"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 }
}
]
}
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 AccessTry it Live
Enter your API key, pick an endpoint, fill in parameters, and send a real request.
PDF Reference
The complete API documentation in a printable PDF — same content, formatted for offline reading.