Guides

Metadata APIs

This section covers all API-level metadata endpoints that return dynamic dictionaries used for filters, search parameters, and geographic metadata. They return only values currently present in the platform’s dataset, ensuring that client applications always work with relevant, up-to-date data. These endpoints do not return static lists — all values are generated dynamically based on actual projects, developers, regions, and locations stored in the system.

Purpose of Metadata Endpoints

Metadata endpoints help clients:

  • build dynamic filter panels (country, region, status, location),
  • synchronize UI with actual project data,
  • avoid hardcoded lists in applications,
  • improve accuracy and relevancy of search/filtering,
  • build map interfaces (markers use the same filtering parameters),
  • power autocomplete and dropdown lists.

All endpoints in this section:

  • use GET only,
  • do not require pagination,
  • return dynamic values reflected from actual project data,
  • are safe to cache (recommended).

The following endpoints belong to the Metadata section:

  1. /countries – available countries
  2. /regions – available regions
  3. /districts – available districts
  4. /projects/sale-statuses – project sale statuses
  5. /projects/statuses – project development statuses
  6. /projects/languages – supported project languages
  7. /units/types – available unit types

Attributes like construction_status, project_amenities, etc. are data fields in the Project model, not standalone metadata endpoints. They will be documented later in the Data Models and Filtering sections.

Countries — List Available Countries

Request

GET /api/v2/clients/countries

Description

Returns a dynamic list of country names available in the catalog. When the language parameter is provided, country names are returned in the requested language.

Typical Use Cases

  • Populating a “Country” filter in a search form or catalog page.
  • Restricting project search to a single country (e.g., only UAE).
  • Building a country selector to refine both list and map results.

Translatable fields:

  • The entire response array (country names)

Supported languages

Available language codes: GET /api/v2/clients/projects/languages

Confirmed languages with translated content: en-us (default), ar, de, fr, he, hi, it, pl, ru, tr, zh.

Meta

Field nameTypeRequiredDefaultNotes
languagestringnoen-usISO language code. Controls the language of country names in the response.

Request and Response Examples

Request:

GET /api/v2/clients/countries?language=fr

Response:

json

[  "United Arab Emirates",  "Cyprus",  "Indonesia",  "Oman",  "Thailand"]

Request:

GET /api/v2/clients/countries?language=fr

Response:

json

[    "Émirats arabes unis",    "Chypre",    "Géorgie",    "Indonésie",    "Maldives"]

Common Usage

GET /api/v2/clients/projects?country=CyprusGET /api/v2/clients/projects/markers?country=United Arab Emirates

Notes

  • The list is dynamic — if all projects from a country are removed, that country will disappear from the response.
  • If a translation is not available for a specific country, the English name is returned.
  • Country values are returned as names (strings), not IDs.

Regions — List Available Regions

Request

GET /api/v2/clients/regions

Description

Returns a dynamic list of regions where projects are located (e.g., “Dubai”, “Abu Dhabi”).

Each region includes approximate bounding box coordinates, which are useful for map-based filtering.

When the language parameter is provided, region names are returned in the requested language.

Typical Use Cases

  • Building region-based filters (e.g., “Region: Dubai”).
  • Restricting project lists or markers to one region.
  • Using bounding boxes for map viewport initialization.

Translatable fields:

  • name

Not translated:

  • id, sw_latitude, sw_longitude, ne_latitude, ne_longitude

Supported languages

Available language codes: GET /api/v2/clients/projects/languages

Confirmed languages with translated content: en-us (default), ar, de, fr, he, hi, it, pl, ru, tr, zh.

Meta

Field nameTypeRequiredDefaultNotes
languagestringnoen-usISO language code. Controls the language of the name field.

Request and Response Examples

Request:

GET /api/v2/clients/regions?language=fr

Response:

json

[    {        "id": 2,        "name": "Dubaï",        "sw_latitude": 24.620369,        "sw_longitude": 54.782523,        "ne_latitude": 25.446058,        "ne_longitude": 56.205636    },    {        "id": 5,        "name": "Abou Dabi",        "sw_latitude": 22.631514,        "sw_longitude": 51.421236,        "ne_latitude": 25.249089,        "ne_longitude": 56.018126    }]

Request:

GET /api/v2/clients/regions

Response:

json

[  {    "id": 5,    "name": "Dubai",    "sw_latitude": 24.620369,    "sw_longitude": 54.782523,    "ne_latitude": 25.446058,    "ne_longitude": 56.205636  },  {    "id": 3,    "name": "Abu Dhabi",    "sw_latitude": 22.631514,    "sw_longitude": 51.421236,    "ne_latitude": 25.249089,    "ne_longitude": 56.018126  }]

Common Usage

GET /api/v2/clients/projects?region=DubaiGET /api/v2/clients/projects/markers?region=Abu Dhabi

Notes

  • Regions are higher-level geographic areas that may contain multiple locations/districts.
  • Only regions with at least one active project are returned.
  • If a translation is not available for a specific region, the English name is returned.

Districts — List Available Districts

Request

GET /api/v2/clients/districts

Description

Returns a dynamic list of districts (neighbourhood-level areas) where projects exist, for example: “Business Bay”, “Palm Jumeirah”, “Dubai Marina”.

When the language parameter is provided, district descriptions are returned in the requested language.

Typical Use Cases

  • Building district filters in search forms (e.g. “District: Business Bay”).
  • Creating autocomplete suggestions for location-based search.
  • Refining map or list results to a specific local area.

Translatable fields:

  • description

Not translated:

  • id, name

Supported languages

Available language codes: GET /api/v2/clients/projects/languages

Confirmed languages with translated content: en-us (default), ar, de, fr, he, hi, it, pl, ru, tr, zh.

Meta

Field nameTypeRequiredDefaultNotes
languagestringnoen-usISO language code. Controls the language of the description field.

Request and Response Examples

Request:

GET /api/v2/clients/districts?language=fr

Response:

json

[    {        "id": 269,        "name": "JVC (Jumeirah Village Circle)",        "description": "Jumeirah Village Circle JVC est un quartier confortable et dynamique au cœur de Dubaï, alliant la tranquillité des banlieues et la commodité de la métropole..."    },    {        "id": 318,        "name": "Reem",        "description": "Reem est la premiere commune fermee a Dubai et constitue une oasis moderne..."    }]

Request:

GET /api/v2/clients/districts

Response:

[  { "id": 2, "name": "Abu Al Habel Island" },  { "id": 5, "name": "Academic City" },  { "id": 17, "name": "Al Barsha" },  { "id": 187, "name": "Business Bay" },  { "id": 308, "name": "Palm Jumeirah" }]

Common Usage

GET /api/v2/clients/projects?district_ids=187GET /api/v2/clients/projects/markers?district_ids=187,308

Notes

  • IDs can be used as stable keys for filters and UI components.
  • Only districts that are actually used by current projects are included.
  • District name is not translated — only description.
  • If a translation is not available for a specific district description, the English text is returned.

Project Sale Statuses

Request

GET /api/v2/clients/projects/sale-statuses

Description

Returns a dynamic list of project sale statuses, such as “On Sale” or “Out of Stock”.

These statuses describe the commercial availability of a project.

When the language parameter is provided, status names are returned in the requested language.

Typical Use Cases

  • Building “Sale Status” filters on catalog and search pages.
  • Displaying readable status chips/tags (e.g. labels on project cards).
  • Aligning list and map filters by sale status.

Translatable fields:

  • The entire response array (sale status names)

Supported languages

Available language codes: GET /api/v2/clients/projects/languages

Confirmed languages with translated content: en-us (default), ar, de, fr, he, hi, it, pl, ru, tr, zh.

Meta

Field nameTypeRequiredDefaultNotes
languagestringnoen-usISO language code. Controls the language of sale status names in the response.

Request and Response Examples

Request:

GET /api/v2/clients/projects/sale-statuses?language=fr

Response:

json

[    "Annoncé",    "En vente",    "Épuisé",    "Prévente (EOI)",    "Début des ventes"]

Request:

GET /api/v2/clients/projects/sale-statuses

Response:

[  "Announced",  "On Sale",  "Out of Stock",  "Presale (EOI)",  "Start of Sales"]

Common Usage

GET /api/v2/clients/projects?sale_status=On%20SaleGET /api/v2/clients/projects/markers?sale_status=Presale%20(EOI)

Notes

  • Values are case-sensitive strings and should be treated as such.
  • The list is dynamic and based only on statuses actually used by existing projects.
  • These are human-readable labels for display. Project objects in API responses use snake_case values (on_sale, out_of_stock, etc.) which are not translated.
  • If a translation is not available, the English name is returned.

Project (Construction) Statuses

Request

GET /api/v2/clients/projects/statuses

Description

Returns a dynamic list of development statuses that reflect the lifecycle stage of a project.

When the language parameter is provided, status names are returned in the requested language.

Translatable fields:

  • The entire response array (construction status names)

Supported languages

Available language codes: GET /api/v2/clients/projects/languages

Confirmed languages with translated content: en-us (default), ar, de, fr, he, hi, it, pl, ru, tr, zh.

Meta

Field nameTypeRequiredDefaultNotes
languagestringnoen-usISO language code. Controls the language of construction status names in the response.

Request and Response Examples

Request:

GET /api/v2/clients/projects/statuses?language=fr

Response:

json

[    "Achevé",    "Prévente",    "En construction"]

Request:

GET /api/v2/clients/projects/statuses

Response:

[  "Completed",  "Presale",  "Under Construction"]

Typical Use Cases

  • Building a “Project Status” filter (e.g., “Show only completed projects”).
  • Displaying labels on project cards like “Under Construction”.
  • Combining with other filters (country, location, price) for complex search.

Common Usage

GET /api/v2/clients/projects?status=Under%20ConstructionGET /api/v2/clients/projects/markers?status=Completed

Notes

  • This endpoint is dynamic — only statuses that exist in the current project dataset will be returned.
  • These are human-readable labels for display. Project objects in API responses use snake_case values (completed, presale, under_construction) which are not translated.
  • If a translation is not available, the English name is returned.

Project Languages

Request

GET /api/v2/clients/projects/languages

Description

Returns a list of supported languages for project-related content, including which language is the default.

This enables clients to localize project descriptions, names, and marketing content.

Response Example

[  {    "code": "en-us",    "name": "English",    "default": true  },  {    "code": "fr",    "name": "French",    "default": false  },  {    "code": "de",    "name": "German",    "default": false  }]

Available language codes:

Confirmed languages with translated content: en-us (default), ar, de, fr, he, hi, it, pl, ru, tr, zh.

Typical Use Cases

  • Building a language selector for project detail pages.
  • Choosing which language to request or display by default.
  • Validating allowed language codes on the client side.

Notes

  • code can be used as the canonical value for language selection in client apps.
  • Only languages that are configured and enabled for projects are returned.

Unit Types

Request

GET /api/v2/clients/units/types

Description

Returns a dynamic list of unit types available across all projects, such as Apartments, Villas, Townhouses, etc.

Used to filter units and to build type selectors in search UIs.

When the language parameter is provided, unit type names are returned in the requested language.

Supported languages

Available language codes: GET /api/v2/clients/projects/languages

Confirmed languages with translated content: en-us (default), ar, de, fr, he, hi, it, pl, ru, tr, zh.

Meta

Field nameTypeRequiredDefaultNotes
languagestringnoen-usISO language code. Controls the language of unit type names in the response.

Request and Response Examples

Request:

GET /api/v2/clients/units/types?language=fr

Response:

json

[    "Appartements",    "Villa",    "Duplex",    "Maison de ville",    "Penthouse"]

Request:

GET /api/v2/clients/units/types

Response:

[  "Apartments",  "Villa",  "Duplex",  "Townhouse",  "Penthouse"]

Typical Use Cases

  • Filtering unit lists or project units by type (e.g., “Only Villas”).
  • Building dropdowns or chips “Unit Type: Apartment / Townhouse / Villa”.
  • Displaying user-friendly labels for unit type fields
  • If a translation is not available for a specific unit type, the English name is returned.

Common Usage

  • Fetch available unit types once on application start or when building filters:
GET /api/v2/clients/units/types
  • Use the returned values:

    • As options in frontend filters (the actual filtering can be done on the client side after calling GET /api/v2/clients/projects/{id}/units),

      Available only with an “Enterprise” subscription

      or

    • As allowed values when designing future server-side filters for units.

Notes

  • The list is dynamic — only unit types that are actually present in the current dataset are returned.
  • Values are strings and should be treated as an enumeration on the client side.
  • This endpoint does not provide a unit listing by itself; it only describes which unit_type values are valid across the platform.

Updated 21 days ago