CORE APIS

Filters API

Turn a natural-language search into standard property filters and sorting, in English and Arabic.

Overview

POST/api/v1/parse

AuthenticationUse a key with filters and sort permission: Authorization: Bearer <key>.

Manage API keys

Request

Parse a search query

Send a sentence; get back filters, sorting and what was not understood.

QueryPlaces, budgets, bedrooms, property types, amenities and more, in English or Arabic.

curl -X POST https://nabdaq.dev/api/v1/parse \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "2 bed apartment in Dubai Marina under 2m",
  "locale": "en"
}'

Parameters

Name	Type	Required	Description
`query`	string	Yes	The search as people write it, up to 2,000 characters.
`locale`	"en" or "ar"	No	The language of the page it came from (default "en"). Mixed English and Arabic is read either way.

Response

Example response

{
  "request_id": "req_01J…",
  "query": "2 bed apartment in Dubai Marina under 2m",
  "mode": "local",
  "schema_version": "nabdaq-uae-v1@sha256:dcf734d1649bbca5",
  "status": "resolved",
  "filters": [
    {
      "field": "location",
      "operator": "eq",
      "value": "dubai_marina",
      "confidence": 1,
      "source": "exact",
      "evidence": [
        {
          "start": 19,
          "end": 31
        }
      ]
    },
    {
      "field": "property_type",
      "operator": "eq",
      "value": "apartment",
      "confidence": 1,
      "source": "exact",
      "evidence": [
        {
          "start": 6,
          "end": 15
        }
      ]
    },
    {
      "field": "bedrooms",
      "operator": "eq",
      "value": 2,
      "confidence": 1,
      "source": "exact",
      "evidence": [
        {
          "start": 0,
          "end": 5
        }
      ]
    },
    {
      "field": "price",
      "operator": "lt",
      "value": 2000000,
      "confidence": 1,
      "source": "exact",
      "evidence": [
        {
          "start": 32,
          "end": 40
        }
      ]
    }
  ],
  "sort": [],
  "unresolved": [],
  "offset_unit": "unicode_code_point",
  "refinement": {
    "status": "not_needed"
  }
}

Field	Meaning
`status`	`resolved`: everything understood; `partially_resolved`: some words are in `unresolved`; `unresolved`: nothing could be used.
`filters[]`	`field`, `operator` (`eq neq gt gte lt lte between in not_in exists`) and `value`, with `source` (exact, lexicon, fuzzy for a corrected typo, classifier) and `confidence`.
`sort[]`	Ordering the words asked for, in order: `{ field, direction }`. See Sorting.
`unresolved[]`	Words that were not turned into a filter, each with a `code` and a message; nothing is dropped silently.
`evidence`	The words behind each filter, as `{ start, end }` offsets in Unicode code points of `query` (`offset_unit`).
`schema_version`	The version of the published fields the answer uses.
`refinement`	When words are left, an AI refinement may follow: `GET /api/v1/parse/{request_id}` returns it once ready. Local answers never wait for it.

Examples

Arabic

JSON

{
  "request_id": "req_01J…",
  "query": "شقة غرفتين للإيجار في دبي مارينا مفروشة",
  "mode": "local",
  "schema_version": "nabdaq-uae-v1@sha256:dcf734d1649bbca5",
  "status": "resolved",
  "filters": [
    {
      "field": "location",
      "operator": "eq",
      "value": "dubai_marina",
      "confidence": 1,
      "source": "exact",
      "evidence": [
        {
          "start": 22,
          "end": 32
        }
      ]
    },
    {
      "field": "purpose",
      "operator": "eq",
      "value": "rent",
      "confidence": 1,
      "source": "exact",
      "evidence": [
        {
          "start": 11,
          "end": 18
        }
      ]
    },
    {
      "field": "furnishing",
      "operator": "eq",
      "value": "furnished",
      "confidence": 1,
      "source": "exact",
      "evidence": [
        {
          "start": 33,
          "end": 39
        }
      ]
    },
    {
      "field": "property_type",
      "operator": "eq",
      "value": "apartment",
      "confidence": 1,
      "source": "exact",
      "evidence": [
        {
          "start": 0,
          "end": 3
        }
      ]
    },
    {
      "field": "bedrooms",
      "operator": "eq",
      "value": 2,
      "confidence": 1,
      "source": "lexicon",
      "evidence": [
        {
          "start": 4,
          "end": 10
        }
      ]
    }
  ],
  "sort": [],
  "unresolved": [],
  "offset_unit": "unicode_code_point",
  "refinement": {
    "status": "not_needed"
  }
}

A community and a sort

JBR resolves to its registry id; "cheapest" becomes a sort, not a filter.

JSON

{
  "request_id": "req_01J…",
  "query": "cheapest villa in JBR with a pool",
  "mode": "local",
  "schema_version": "nabdaq-uae-v1@sha256:dcf734d1649bbca5",
  "status": "resolved",
  "filters": [
    {
      "field": "property_type",
      "operator": "eq",
      "value": "villa",
      "confidence": 1,
      "source": "exact",
      "evidence": [
        {
          "start": 9,
          "end": 14
        }
      ]
    },
    {
      "field": "pool",
      "operator": "eq",
      "value": true,
      "confidence": 1,
      "source": "exact",
      "evidence": [
        {
          "start": 29,
          "end": 33
        }
      ]
    },
    {
      "field": "location",
      "operator": "eq",
      "value": "wikidata:Q1466585",
      "confidence": 1,
      "source": "exact",
      "evidence": [
        {
          "start": 18,
          "end": 21
        }
      ]
    }
  ],
  "sort": [
    {
      "field": "price",
      "direction": "asc",
      "source": "lexicon",
      "confidence": 1,
      "evidence": [
        {
          "start": 0,
          "end": 8
        }
      ]
    }
  ],
  "unresolved": [],
  "offset_unit": "unicode_code_point",
  "refinement": {
    "status": "not_needed"
  }
}

Words it could not use

"near a good school" stays unresolved rather than guessed; the rest still works.

JSON

{
  "request_id": "req_01J…",
  "query": "villa near a good school in Arabian Ranches under 5m",
  "mode": "local",
  "schema_version": "nabdaq-uae-v1@sha256:dcf734d1649bbca5",
  "status": "partially_resolved",
  "filters": [
    {
      "field": "location",
      "operator": "eq",
      "value": "arabian_ranches",
      "confidence": 1,
      "source": "exact",
      "evidence": [
        {
          "start": 28,
          "end": 43
        }
      ]
    },
    {
      "field": "property_type",
      "operator": "eq",
      "value": "villa",
      "confidence": 1,
      "source": "exact",
      "evidence": [
        {
          "start": 0,
          "end": 5
        }
      ]
    },
    {
      "field": "price",
      "operator": "lt",
      "value": 5000000,
      "confidence": 1,
      "source": "exact",
      "evidence": [
        {
          "start": 44,
          "end": 52
        }
      ]
    }
  ],
  "sort": [],
  "unresolved": [
    {
      "text": "near",
      "code": "VETO_CUE_UNRESOLVED",
      "message": "\"near\" needs refinement.",
      "evidence": [
        {
          "start": 6,
          "end": 10
        }
      ]
    },
    {
      "text": "good school",
      "code": "UNKNOWN_PHRASE",
      "message": "This phrase could not be mapped safely to the published schema.",
      "evidence": [
        {
          "start": 13,
          "end": 24
        }
      ]
    }
  ],
  "offset_unit": "unicode_code_point",
  "refinement": {
    "status": "pending"
  }
}

Field reference

Filter fields

84 live fields. Parse returns them; listings and index search use the same ones.

Field	Type	Description	Example
`purpose`Purpose	string (value)	Buy or rent property; never infer a transaction type from budget alone.	`buy`
`property_category`Property category	string (value)	Residential, commercial, industrial or land.	`residential`
`property_type`Property type	string (value)	The requested real-estate unit type.	`apartment`
`location`Location	string (value)	Named UAE emirate or community; values are locations, not verified listing inventory.	`dubai`
`bedrooms`Bedrooms	number	Count of bedrooms; studio means zero.	`2`
`bathrooms`Bathrooms	number	Count of bathrooms.	`3`
`parking_spaces`Parking spaces	number	Number of parking spaces.	`2`
`rent_cheques`Rent cheques	number	Number of rent payment cheques.	`4`
`area_floor`Floor area	number · sqft	Requested floor area in square feet.	`1200`
`area_plot`Plot area	number · sqft	Requested plot area in square feet.	`5000`
`floor_level`Floor level	number	Floor number or level when an exact numeric constraint is stated.	`20`
`year_built`Year built	number	Construction year if explicitly requested.	`2018`
`price`Price	number (AED)	Asking price or rent amount in AED; rent period is a separate field.	`150000`
`rent_period`Rent period	string (value)	Period to which a rental price applies.	`year`
`furnishing`Furnishing	string (value)	Furnishing condition.	`furnished`
`completion_status`Completion status	string (value)	Ready, off-plan or under construction.	`ready`
`pool`Swimming pool	boolean	A swimming pool of any kind; private_pool and shared_pool name its access.	`true`
`gym`Gym	boolean	Gym or fitness facility requested.	`true`
`balcony`Balcony	boolean	Balcony requested.	`true`
`garden`Garden	boolean	A garden; private_garden names the unit's own.	`true`
`maid_room`Maid room	boolean	Separate maid room requested.	`true`
`study`Study	boolean	Dedicated study room requested.	`true`
`storage_room`Storage room	boolean	Separate storage room requested.	`true`
`pet_friendly`Pet friendly	boolean	Permission for pets requested.	`true`
`sea_view`Sea view	boolean	Sea view requested; actual visibility is not verified.	`true`
`chiller_free`Chiller free	boolean	Cooling cost included or paid by landlord, subject to listing verification.	`true`
`no_commission`No commission	boolean	No brokerage commission requested.	`true`
`bills_included`Bills included	boolean	Utility bills included, exact services require verification.	`true`
`short_term`Short-term stay	boolean	Short-term rental requested.	`true`
`availability_date`Availability date	date (YYYY-MM-DD)	Desired availability date; relative dates depend on request time.	`2026-11-01`
`tenure`Tenure	string (value)	Ownership tenure where explicitly requested.	`freehold`
`property_condition`Property condition	string (value)	Advertised condition, not a verified inspection.	`new`
`payment_method`Purchase payment method	string (value)	Requested purchase payment method.	`cash`
`view`View	string (value)	Requested advertised view.	`sea`
`price_per_sqft`Price per sqft	number · AED/sqft	Asking price or rent per square foot in AED.	`0`
`down_payment`Down payment	number · %	Down payment as a percentage of the price.	`0`
`handover_date`Handover date	date (YYYY-MM-DD)	Expected handover (completion) date of an off-plan unit.	`2027-03-31`
`completion_percentage`Completion percentage	number · %	Construction progress of an off-plan project, in percent.	`0`
`sale_type`Sale type	string (value)	Initial sale from the developer or resale by an owner.	`initial_sale`
`post_handover_payment_plan`Post-handover payment plan	boolean	Part of the price is paid in instalments after handover.	`true`
`payment_plan_years`Payment plan years	number · year	Length of the instalment payment plan in years.	`1`
`dld_registered`DLD registered	boolean	Listing registered with the Dubai Land Department (permit), as advertised.	`true`
`developer`Developer	string (value)	Developer of the project; values are the major UAE developers.	`emaar`
`central_ac`Central AC	boolean	Central air conditioning.	`true`
`private_pool`Private pool	boolean	A pool for the unit alone.	`true`
`shared_pool`Shared pool	boolean	A pool shared by the building or community.	`true`
`private_gym`Private gym	boolean	A gym for the unit alone.	`true`
`spa`Spa	boolean	Spa facilities, usually shared in the building.	`true`
`private_jacuzzi`Private jacuzzi	boolean	A jacuzzi for the unit alone.	`true`
`private_garden`Private garden	boolean	A garden for the unit alone.	`true`
`concierge`Concierge	boolean	Concierge service in the building.	`true`
`covered_parking`Covered parking	boolean	Covered, shaded or underground parking.	`true`
`water_view`Water view	boolean	A view of water: sea, lake, canal, creek or marina.	`true`
`landmark_view`Landmark view	boolean	A view of a landmark such as Burj Khalifa or Burj Al Arab.	`true`
`built_in_wardrobes`Built-in wardrobes	boolean	Built-in or fitted wardrobes.	`true`
`walk_in_closet`Walk-in closet	boolean	A walk-in closet or dressing room.	`true`
`kitchen_appliances`Kitchen appliances	boolean	Kitchen equipped with appliances.	`true`
`maid_service`Maid service	boolean	Housekeeping or cleaning service.	`true`
`childrens_play_area`Children's play area	boolean	A play area or playground for children.	`true`
`childrens_pool`Children's pool	boolean	A children's pool.	`true`
`bbq_area`Barbecue area	boolean	A barbecue area.	`true`
`security_24h`24-hour security	boolean	Security guards or CCTV, around the clock.	`true`
`lobby`Lobby	boolean	A lobby or reception in the building.	`true`
`service_elevator`Service elevator	boolean	A service or goods elevator.	`true`
`prayer_room`Prayer room	boolean	A prayer room in the building.	`true`
`laundry_room`Laundry room	boolean	A laundry room or area.	`true`
`broadband`Broadband internet	boolean	Broadband or fibre internet in the unit.	`true`
`intercom`Intercom	boolean	An intercom system.	`true`
`double_glazed_windows`Double-glazed windows	boolean	Double-glazed windows.	`true`
`day_care`Day care	boolean	A day care or nursery in the building or community.	`true`
`onsite_business_centre`On-site business centre	boolean	A business centre in the residential building.	`true`
`sauna`Sauna	boolean	A sauna.	`true`
`steam_room`Steam room	boolean	A steam room.	`true`
`verified_listing`Verified listing	boolean	The listing is marked verified by the portal or agency.	`true`
`video_tour`Video tour	boolean	The listing has a video.	`true`
`virtual_tour`Virtual tour	boolean	The listing has a 360 or 3D virtual tour.	`true`
`live_viewing`Live viewing	boolean	The agent offers a live video viewing.	`true`
`floor_plan`Floor plan	boolean	The listing has a floor plan.	`true`
`price_reduced`Price reduced	boolean	The asking price was reduced.	`true`
`listed_at`Listing date	date (YYYY-MM-DD)	When the listing was published; relative periods depend on request time.	`2027-03-31`
`upgraded`Upgraded	boolean	The unit was upgraded (finishes, kitchen, bathrooms), as advertised.	`true`
`extended`Extended	boolean	The unit or villa was extended, as advertised.	`true`
`landscaped`Landscaped	boolean	The garden or plot is landscaped, as advertised.	`true`
`occupancy`Occupancy	string (value)	Whether the unit is vacant or tenanted, as advertised.	`vacant`