List published projects (paginated, filterable)

GET

/projects

const url = 'https://agent-dev.azizdubai.com/projects?developer_ids=3%2C4&unit_types=1%2C2&development_status=1%2C2&bedrooms=0%2C1%2C2&statuses=3%2C4&handover_from=2027-01-01&handover_to=2029-12-31&preference_ids=1%2C7&unit_preference_ids=1%2C3&limit=20&offset=0';
const options = {method: 'GET', headers: {'X-API-Key': '<X-API-Key>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://agent-dev.azizdubai.com/projects?developer_ids=3%2C4&unit_types=1%2C2&development_status=1%2C2&bedrooms=0%2C1%2C2&statuses=3%2C4&handover_from=2027-01-01&handover_to=2029-12-31&preference_ids=1%2C7&unit_preference_ids=1%2C3&limit=20&offset=0' \
  --header 'X-API-Key: <X-API-Key>'

Returns published projects only (is_draft = false).

Price bounds must be expressed in the prices the client sees, that is, with the key’s price vector already applied. The service converts them back to base prices before querying the database, so that filtering and the displayed prices are always consistent.

CSV parameters accept a comma-separated list, for example statuses=3,4.

Authorizations

apiKeyHeader
bearerKey

Parameters

Query Parameters

search

string

Case-insensitive substring of the project name or its developer’s name.

developer_ids

string

CSV of developer company IDs.

unit_types

string

CSV of Project.type values (positive integers).

development_status

string

CSV of construction stages, values 1–3.

bedrooms

string

CSV of bedroom counts; 0 denotes a studio. The value 5 is interpreted as “5+” and matches five or more bedrooms.

statuses

string

CSV of unit statuses, values 1–5.

price_min

number format: double

Minimum unit price, in the key’s prices.

price_max

number format: double

Maximum unit price, in the key’s prices.

price_per_ft2_min

number format: double

Minimum price per ft², in the key’s prices. Calculated as price divided by area.

price_per_ft2_max

number format: double

price_per_m2_min

number format: double

Minimum price per m², in the key’s prices.

price_per_m2_max

number format: double

size_min

number format: double

Minimum unit area in m² (the storage unit of Unit.unit_area).

size_max

number format: double

parking_min

integer

Minimum number of parking spaces for the unit.

is_branded

boolean

Branded project.

is_resale

boolean

is_escrow

boolean

The project has an escrow account.

handover_from

string

Lower bound of the handover date. RFC3339 or YYYY-MM-DD.

handover_to

string

Upper bound of the handover date. RFC3339 or YYYY-MM-DD.

payment_max_pre_handover

number format: double

<= 100

Maximum percentage of payments due before handover (0–100).

payment_min_after_handover

number format: double

<= 100

Minimum percentage of payments due after handover (0–100).

payment_only_post_handover

boolean

Only projects with post-handover payments.

lat

number format: double

>= -90 <= 90

Latitude of the search centre. Must be used together with lng and radius_km.

lng

number format: double

>= -180 <= 180

Longitude of the search centre. Must be used together with lat and radius_km.

radius_km

number format: double

> 0

Search radius in kilometres; must be greater than zero.

near_airport

boolean

The project has a nearby facility in the “airports and ports” category. The proximity threshold is configured on the server (AMENITIEST_RADIUS) and cannot be set per request. The other seven categories use flags of the same form.

near_education

boolean

near_employment

boolean

near_healthcare

boolean

near_lifestyle

boolean

near_retail

boolean

near_transport

boolean

near_tourism

boolean

preference_ids

string

CSV of project feature/amenity IDs. AND semantics: the project must have all of the listed items.

unit_preference_ids

string

CSV of unit tag IDs. AND semantics, applied to a single unit: the project must have one unit that carries all of the listed tags and also satisfies every other unit-level filter.

limit

integer

default: 20 >= 1 <= 100

Page size. Values above 100 are capped at 100.

offset

integer

Responses

200

A page of projects.

application/json

object

status

required

string

Allowed value: success

data

required

The shape depends on the operation.

data

required

object

total

Total number of projects matching the filters

integer format: int64

items

Array<object>

object

integer

name

string

status

Free-form integer with no defined meaning.

integer

development_status

integer

Allowed values: 0 1 2 3

is_branded

boolean

is_resale

boolean

is_escrow

boolean

handover_date

string | null format: date-time

price_from

Lowest unit price in the project, in the key’s prices. null if the project has no priced units.

number | null format: double

size_from

Smallest unit area

number | null format: double

currency

string

logo

string | null

company

object

integer

name

string

logo

Ready-to-use logo link, built from STATIC_BASE_URL.

string | null

payment_plans

Array<object>

object

type

1 — down payment, 2 — during construction, 3 — on completion.

integer

Allowed values: 1 2 3

percent

number format: double

preferences

object

features

Array<object>

object

integer

name

string

type

1 — feature, 2 — amenity.

integer

Allowed values: 1 2

amenities

Array<object>

object

integer

name

string

type

1 — feature, 2 — amenity.

integer

Allowed values: 1 2

Example

{
  "status": "success",
  "data": {
    "items": [
      {
        "development_status": 0,
        "currency": "AED",
        "payment_plans": [
          {
            "type": 1
          }
        ],
        "preferences": {
          "features": [
            {
              "name": "Infinity Pool",
              "type": 1
            }
          ],
          "amenities": [
            {
              "name": "Infinity Pool",
              "type": 1
            }
          ]
        }
      }
    ]
  }
}

400

A parameter or the request body failed validation.

application/json

object

status

required

string

Allowed value: error

message

required

Human-readable message.

string

Examples

badID

{
  "status": "error",
  "message": "id must be a positive integer"
}

401

The key is missing (missing api key) or invalid (invalid api key). The latter covers unknown, revoked and deleted keys. Every operation requires a key, so any request without one receives this response.

application/json

object

status

required

string

Allowed value: error

message

required

Human-readable message.

string

Examples

invalid

{
  "status": "error",
  "message": "invalid api key"
}

403

The key is valid, but it is restricted to a list of domains and the request’s Origin (or Referer) does not match any of them; or the key’s agency has no approved licence.

application/json

object

status

required

string

Allowed value: error

message

required

Human-readable message.

string

Examples

{
  "status": "error",
  "message": "origin is not allowed for this api key"
}

{
  "status": "error",
  "message": "agency license is required: upload a company license and wait for its approval"
}

500

An unexpected error. The cause is logged; a generic message is returned.

application/json

object

status

required

string

Allowed value: error

message

required

Human-readable message.

string

Examples

generic

{
  "status": "error",
  "message": "internal server error"
}