Dubai cost of living: REST API v2 & MCP v2

REST API v2

Base URL: https://prices.brainy.ae/api/v2. Start with service metadata and the OpenAPI 3.1 description. The JSON schema documents each route, input, response and source condition. CORS is enabled.

Read the envelope before using a figure

Successful data responses contain meta, data and links. meta.dataset identifies the dataset and its dates, reference period, sources[] and availability:

• ok: the requested dataset is available.
• partial: some components or sources are paused or unavailable; inspect row-level status and preserve the notice.
• paused: deliberately withheld; HTTP 200, empty data, no retry instruction. Never use a previous copy of excluded prices.
• not_published: not published yet; HTTP 200 with empty data. A temporary fetch/service failure is instead an HTTP 503 problem.

historical describes the source's reference period, such as KHDA tuition for 2024–2025. stale describes our cache: a previous admitted copy served after a failed refresh. They are independent. Observation, publication and compilation dates have their stated precision; an unknown date or amount is null, never invented.

Rows carry provenance. Resolve each source_id and license_id in meta.dataset.sources to retain the publisher, URL, dates, licence, conditions and required attribution. Preserve links.open_in_browser and row links where present.

Pagination and selective queries

For paginated lists, page_size defaults to 20 and must be 1–50. meta.page contains returned, total (matches for this query), result_window (200), has_more, next_cursor, snapshot_id and cursor_ttl_s. Pass the opaque cursor unchanged as cursor, with the same filters, sorting, language and page size. Stop when next_cursor is null.

MCP: call the matching tool for a direct question; use start_here only if unsure which tool to use. schools {} returns the first 20 rows by tuition; refine with q (school name), near (zone), grade, curriculum or max_fee_aed. housing_rents accepts q as a zone alias (e.g. JVC) when zone and zone_id are absent; zone takes precedence. grocery_products needs query (product name) or product_id.

The window is at most 200 rows across all pages, even when total is higher. At the window boundary has_more is false; refine the question instead of splitting queries to enumerate a dataset. HTTP 400 filter_required means a substantive documented filter is missing: this applies to product and zone searches, housing rents/sales, reference prices, buyer reports and commute routes. These routes cannot be used to list the entire inventory.

Errors, validators and privacy

Errors use application/problem+json (RFC 9457), with type, title, HTTP status, stable code, detail, request_id, invalid_params and retry information. Check the code, not message text. Invalid filters return 400; unavailable resources return 404; unsupported methods return 405; oversized bodies return 413; quota limits return 429 and transient failures 503. Respect Retry-After.

An invalid/mismatched cursor returns 400 cursor_invalid. An expired cursor or changed snapshot returns 409 cursor_expired or snapshot_changed: start again without a cursor. GET data responses include an ETag; send If-None-Match to receive HTTP 304 when the representation is unchanged. Conditional requests still count toward quota. GET data uses private caching; POST calculations and MCP responses use Cache-Control: no-store.

Relocation, gratuity, overtime, annual leave, final settlement, job offer and DEWA calculations require POST JSON. Salaries, amounts, employment dates, household and consumption inputs are not persisted by the service. Never put them in URL parameters.

curl examples

# Current monthly fuel
curl -s 'https://prices.brainy.ae/api/v2/transport/fuel-prices'

# Select products and a school shortlist
curl -s 'https://prices.brainy.ae/api/v2/grocery/products?q=milk&page_size=20'
curl -s 'https://prices.brainy.ae/api/v2/schools?near=Jumeirah%20Park&grade=YEAR%207&radius_km=10&page_size=50'

# Registered 1-bedroom apartment rents in Dubai Marina; discover zone ids separately
curl -s 'https://prices.brainy.ae/api/v2/housing/rents?zone_id=dubai-marina&property_type=apartment&bedrooms=1&page_size=20'
curl -s 'https://prices.brainy.ae/api/v2/housing/zones?q=Dubai%20Marina'

# Supplied grocery list (POST only)
curl -s 'https://prices.brainy.ae/api/v2/grocery/comparisons' \
  -H 'Content-Type: application/json' \
  -d '{"items":["milk","eggs"],"area":"JLT"}'

# Monthly DEWA estimate; water_m3 and water_gallons are alternatives
curl -s 'https://prices.brainy.ae/api/v2/utilities/dewa/bill-estimates' \
  -H 'Content-Type: application/json' \
  -d '{"kwh":1000,"water_m3":15}'

# Supplied example, not personal data: estimate, not tax advice
curl -s 'https://prices.brainy.ae/api/v2/relocation/estimates' \
  -H 'Content-Type: application/json' \
  -d '{"country":"GB","gross_annual":80000,"currency":"GBP","household":{"status":"single","children":0},"area":"Dubai Marina","bedrooms":1}'

# Supplied example: end-of-service gratuity estimate, not legal advice
curl -s 'https://prices.brainy.ae/api/v2/employment/gratuity-estimates' \
  -H 'Content-Type: application/json' \
  -d '{"basic_monthly_aed":15000,"start_date":"2018-10-13","end_date":"2026-10-13","unpaid_days":0,"work_pattern":"full-time"}'

# Supplied example: Overtime estimate, not legal advice
curl -s 'https://prices.brainy.ae/api/v2/employment/overtime-estimates' \
  -H 'Content-Type: application/json' \
  -d '{"basic_monthly_aed":6000,"total_monthly_wage_aed":9000,"normal_hours_per_day":8,"hourly_basic_aed":null,"shift_worker":false,"work_pattern":"full-time","category":"private","day_hours":8,"night_hours":4,"rest_days":0,"holidays":0}'

# Supplied example: Annual leave on leaving; employment_ends defaults to true in REST
curl -s 'https://prices.brainy.ae/api/v2/employment/annual-leave-estimates' \
  -H 'Content-Type: application/json' \
  -d '{"start_date":"2023-01-01","end_date":"2025-12-31","leave_taken_days":60,"basic_monthly_aed":6000,"total_monthly_wage_aed":9000,"employment_ends":true,"notice_days":30,"notice_worked_days":30,"ended_by":"employer","work_pattern":"full-time","category":"private"}'

# Supplied example: Final settlement estimate, not legal advice
curl -s 'https://prices.brainy.ae/api/v2/employment/final-settlement-estimates' \
  -H 'Content-Type: application/json' \
  -d '{"start_date":"2023-01-01","end_date":"2025-12-31","basic_monthly_aed":6000,"total_monthly_wage_aed":9000,"unpaid_days":0,"leave_taken_days":60,"unused_leave_days":null,"notice_days":30,"notice_worked_days":20,"notice_cut_by":"employer","wages_owed_aed":0,"category":"private","work_pattern":"full-time"}'

# Supplied example: Job offer estimate, not financial advice; no verdict on the offer
curl -s 'https://prices.brainy.ae/api/v2/employment/job-offer-estimates' \
  -H 'Content-Type: application/json' \
  -d '{"basic_monthly_aed":6000,"housing_aed":36000,"housing_period":"year","transport_monthly_aed":500,"other_monthly_aed":250,"zone_id":"dubai-marina","home_type":"apartment","bedrooms":1,"household":"couple","car":"none"}'

To paginate, reuse a response's actual meta.page.next_cursor, retaining the original query. To validate a cached result, use that response's actual ETag in If-None-Match. Do not fabricate cursors or validators.

Use Brainy Prices in your AI assistant

Connect to our Brainy Prices MCP server: free, with no API key, authentication or Brainy Prices account required. Results include their source and date. Your assistant account must support custom MCP connectors.

Server URL (Streamable HTTP): https://prices.brainy.ae/mcp/v2

MCP v2

Remote endpoint: https://prices.brainy.ae/mcp/v2, Streamable HTTP, stateless JSON responses, no authentication. Supported protocol versions: 2025-11-25, 2025-06-18 and 2025-03-26. Application version 2.0.0 is separate from the MCP protocol version.

https://prices.brainy.ae/mcp/v2/apps offers 20 read-only tools, a reduced tool set for app directories such as ChatGPT, limited to government and open-data sources; same limits as /mcp/v2.

27 read-only tools, grouped below from the service catalogue. Input and output schemas are returned by tools/list. List tools support page_size up to 50 where their selected operation is paginated; the REST window and shared quota apply.

official_shop_prices still responds as a hidden alias of ministry_shop_prices on /mcp/v2; it is not advertised by tools/list and is unavailable on /mcp/v2/apps.

Start here

• start_here — Tool selection help: examples and citations. Also GET https://prices.brainy.ae/api/v2/start-here.

Groceries

• grocery_products — Dubai supermarket prices: per-store pack/unit offers, dates, history. Give query (product name), e.g. milk, or product_id. Not MOET.
• grocery_compare_list — Cheapest store for a list: subtotals, delivery fees, minimums. items: ["milk"]. Observed + labelled estimates.
• grocery_stores — Grocery stores: delivery fees, free-delivery thresholds, minimum orders.
• ministry_shop_prices — MOET-published Dubai shop prices. category: bread or chain_id/product_id. Not online offers.
• shopper_price_reports — Community price reports by product/store, with date and promos.

Schools

• schools — Dubai school fees: KHDA tuition by grade/year, bus fees, distance. q: school name; near: zone (JVC). Year ≠ Grade; uniforms paused.

Housing and household costs

• housing_rents — Registered Dubai rent: annual/monthly medians, contract counts. zone or q: JVC. Not listings.
• housing_sales — Sale prices by Dubai area: ready/off-plan registered medians. Not listings.
• costs_by_area — Dubai areas ranked by monthly cost: rent, fees, bills (+school). Not full budgets.
• fixed_monthly_costs — Monthly fixed costs for a household profile, with assumptions. Not a full budget.
• costs_by_emirate — Compare emirates: rent, utilities, schools. Non-Dubai rent unknown.
• tax_savings_by_country — Tax saved by moving to Dubai, per country, typical pay. Not tax advice.

Transport and utilities

• fuel_prices — UAE petrol/diesel prices this month and last, change, 50/70 L tank cost, history.
• transport_fares — Taxi fare estimate, or metro/bus fares, parking and toll tariffs. Not app quotes.
• commute_cost — Monthly/annual car commute cost (fuel+Salik). Area commute routes: paused while we confirm the official source. No parking.
• dewa — Consumption charge under the tariff published in the resolution, before VAT; not a bill. Bill total: not available. Paused while we confirm the official source. 5% VAT applies.
• mobile_internet_plans — UAE mobile and home internet plans: VAT-inclusive price, data, contract.

Health and relocation

• health_insurance — Dubai health insurance rules: who pays, basic plan band/benefits, fines. Not quotes.
• residence_visas — UAE residence visas by route: payer, requirements, fees, medical/insurance bands.
• free_zone_companies — Free zone company setup: package prices, annual/monthly cost, visas.
• move_to_dubai — Move to Dubai? Home vs Dubai net pay, taxes, FX, costs, savings. No country: models. Owner: household=business_owner + profit. Not tax advice.
• end_of_service_gratuity — UAE private-sector end-of-service gratuity estimate (Decree-Law 33/2021 art. 51): basic wage + dates → amount or range; not legal advice.
• labour_calculator — UAE labour law estimates (Decree-Law 33/2021): overtime pay, annual leave, final settlement. Not legal advice.
• fx_rates — Dated CBUAE AED exchange rates. Not bank quotes.

Highlights and sources

• today — Paused since 21 October 2026 and not listed in tools/list while paused: a direct call answers with status "paused" and no figures. Shop prices published by the Ministry of Economy and Tourism remain available via ministry_shop_prices.
• data_sources — Where each number comes from: publishers, licences, dates, paused sources.

POST /api/v2/relocation/estimates accepts an optional day_one object in its JSON body: {"profile":"founder","rent_cheques":4}. Profile is employee (default) or founder. rent_cheques accepts 1, 2, 4, 6 or 12 with no default. Optional quoted amounts in AED are landlord_deposit_aed, agency_commission_aed, dewa_deposit_aed and free_zone_package_aed (0–10000000000000). Zone and package IDs are strings of 1–80 characters, taken from day_one_cash.free_zones in any estimate response. No zone or package is selected automatically; a quote takes precedence and can be supplied without a zone. A founder without a selected package or quote stays pending. Monthly-only packages stay pending without conversion to an annual payment; paused zones and zones without published packages show no package amount.

REST v2 estimates and MCP move_to_dubai estimates return data.day_one_cash: status (complete, partial or unavailable), profile, known_subtotal_aed ({min,max} or null), items, pending item IDs, not_covered and free_zones. Items include a stable ID, status (known, user, market, pending or info), amount_aed or null, optional min_aed/max_aed, source {name,url,date} or null, text and links. The zone catalog and published packages are alphabetical by name, with dates and source links. Unknown amounts stay null and do not enter the subtotal; the medical range counts once per person. Arrival cash is separate from monthly costs and savings. MCP accepts no day_one input: its estimates use employee with unprovided amounts pending. Employee has no free-zone component. V1 is unchanged.

Every successful tool returns the v2 envelope as structuredContent, with a compact content[].text summary that preserves numbers, units, source, date, warnings and a browser link. A text summary can show fewer rows than structured content: use the declared total and continuation instruction. A deliberate pause is a normal result (isError: false), never an instruction to retry; invalid input is isError: true. An unknown tool name is JSON-RPC error -32602: its message and data.valid_tools list the tools that endpoint accepts; call tools/list for their input schemas.

Resources and prompts

resources/list advertises nine static metadata/method resources; resources/templates/list advertises brainy-prices://datasets/{dataset_id}/metadata for allowlisted dataset IDs. They explain scope, sources, licences, dates and pauses; they do not expose dataset rows or bulk exports.

• brainy-prices://catalog/datasets — Metadata-only catalogue of dataset cards and tools, no rows.
• brainy-prices://methodology/groceries — Observed offers, units, exact/equivalent, cohort, delivery and single-store methodology.
• brainy-prices://methodology/schools — Historical KHDA Year/Grade tuition, OSM straight-line distance, bus/uniform scope and rights.
• brainy-prices://methodology/housing — Registered DLD rents/sales, samples, quartiles, period and license.
• brainy-prices://methodology/costs — Fixed partial costs, component assumptions and missing emirate coverage.
• brainy-prices://methodology/relocation — Dated tax/FX calculations, residency assumptions, exclusions, no personal input storage.
• brainy-prices://policies/sources — Rights metadata and deliberate pauses by source, not the underlying datasets.
• brainy-prices://policies/access — Anonymous/free-key quotas, double opt-in and no bulk access policy.
• brainy-prices://changes/current — Latest20 metadata-only changes, no row diffs.

The current changes resource states when no dated change ledger is available; do not infer a publication history from its name. prompts/list advertises five optional templates. prompts/get prepares messages from supplied arguments; it does not execute tools:

• compare_moving_from — Compare a supplied home-country salary scenario with Dubai, using dated tax, FX and partial costs; ask for missing personal assumptions.
• school_shortlist — Shortlist nearby schools by the exact published Year/Grade label, historical tuition and approximate straight-line distance.
• compare_grocery_list — Compare only the grocery items a user actually supplied; distinguish observed offers, official reference prices and buyer reports.
• compare_areas — Compare fixed cost components for a supplied housing scenario without inventing rental coverage outside Dubai.
• check_sources — Inspect metadata, methods and source permissions for a topic without downloading its dataset.

Connect a client

Claude Code: add a remote HTTP server in the terminal (connection guide).

claude mcp add --transport http brainy-prices-v2 https://prices.brainy.ae/mcp/v2

Claude Desktop: add a custom remote connector in Connectors with https://prices.brainy.ae/mcp/v2. Availability depends on your plan and administrator settings (connection guide).

Cursor: add this to your project's .cursor/mcp.json (connection guide):

{
  "mcpServers": {
    "brainy-prices-v2": { "url": "https://prices.brainy.ae/mcp/v2" }
  }
}

VS Code: add this to .vscode/mcp.json and start the server from the editor's MCP controls (connection guide):

{
  "servers": {
    "brainy-prices-v2": {
      "type": "http",
      "url": "https://prices.brainy.ae/mcp/v2"
    }
  }
}

Other clients: choose a remote Streamable HTTP server, paste the endpoint and select no authentication. The client must support one of the protocol versions above; MCP discovery supplies the schemas, resources and prompts.

# 1. initialize
curl -s 'https://prices.brainy.ae/mcp/v2' \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'

# 2. acknowledge initialization (HTTP 202, no body)
curl -s 'https://prices.brainy.ae/mcp/v2' \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'

# 3. discover tools
curl -s 'https://prices.brainy.ae/mcp/v2' \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# 4. call a tool
curl -s 'https://prices.brainy.ae/mcp/v2' \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"grocery_compare_list","arguments":{"items":["milk","eggs"],"area":"JLT"}}}'

Limits and fair use

• Anonymous v2 access: 30 requests per minute and 500 per UTC day per verified network identity (IPv6 /64). REST v2 requests and MCP v2 tool calls share the same quota across service instances.
• HTTP 304, validation errors and paused data results still consume data quota. HTTP 429 includes Retry-After; inspect RateLimit and RateLimit-Policy headers.
• Cache responses privately, retain their source/date/status and revalidate using ETag when supported. Different datasets refresh on different schedules; consult their metadata.
• No mass downloads, systematic enumeration or open dataset is offered. Free access and metadata resources do not expand a source licence.

Free API key (optional)

Anonymous access stays as it is (v2: 30 requests per minute and 500 per UTC day; v1 unchanged). For more, get a free key at /api-key.html (terms, privacy; versions 2026-10-12).

• Use: send the key as the X-API-Key header on REST v2 and on /mcp/v2 (MCP clients that support custom headers). Never in a query string, a public cookie or shared frontend code. Without the header the call is anonymous; an invalid, expired or revoked key returns 401 invalid_api_key, with no anonymous fallback.
• Quota: 60 requests per minute and 1,500 per UTC day per account. At most two active keys per account share it across REST and MCP. Keys last 180 days; rotating does not reset the quota or unlock paused sources. 304s, paused answers and validation errors count; respect RateLimit and Retry-After with jitter.
• Endpoints (POST, JSON): /api/v2/access/requests {email, purpose: signup|manage, terms_version, privacy_version, transfer_consent, intended_use?} always returns 202; /api/v2/access/confirm {token} returns 201 once (a key for signup, a 10-minute management token for manage; a third active key gives 409 key_limit_reached); /api/v2/access/keys/rotate and /api/v2/access/keys/revoke {management_token}. A repeated, invalid or expired confirmation returns 400 confirmation_invalid; outdated document versions return 400 terms_version_outdated.
• Email: from prices@brainy.ae, transactional only. The link is valid for 24 hours; opening or previewing it does not confirm, the button does. At most 3 requests per email per UTC day and 3 per network per hour.
• Management: ask for a management email, then rotate (new key, shown once) or revoke the most recent active key with the 10-minute token. The key itself never manages the account; there are no MCP tools for access. A lost key cannot be recovered: rotate it.
• Network protection (not extra quota): access endpoints 30 per minute per network; requests carrying a key, valid or not, 120 per minute per network; MCP control 30 per minute.

Attribution and source licences

When displaying a result, cite the original source and its date or reference period, plus “Source: Brainy Prices, prices.brainy.ae, <date>” and the browser link. Retain source-specific attribution, notices, exclusions and licence conditions. There is no blanket licence over all responses: only our own compilations are CC BY 4.0.

• Brainy Prices compilations, calculations and estimates: CC BY 4.0. Fixed monthly costs, medians, ranges, tax and take-home comparisons we compute: credit «Brainy Prices — prices.brainy.ae» with a link and keep the date. See the data licence. Third-party figures keep their own licence, below and in meta.dataset.sources.
• KHDA: unaltered, not for profit. Tuition data is for non-commercial use and must not be altered. Keep the original published Year/Grade labels and academic year; do not sell, monetise or modify the data.
• Dubai Land Department: Dubai Open Data Licence. Retain the DLD attribution and the reference period; contractual medians are not listings.
• OpenStreetMap: ODbL. Credit © OpenStreetMap contributors for school locations only; school locations are approximate and school distances are straight-line distances.
• Store, operator and other sources have their own permissions and conditions, supplied in meta.dataset.sources. Public accessibility is not permission to collect or redistribute them.
• No bulk downloads or open dataset. The API serves selective queries. Source metadata and free anonymous access are not an export or redistribution licence.
• Excluded sources: never. Their prices must not appear in responses, nested content or cached fallback. Paused sources remain empty until their permission/source review permits publication.

Store offers can change during the day and at checkout. Unknown delivery stays unknown, never free; missing items and assumptions remain explicit. A comparison ranks only the common comparable subset, and a single-store result is not a store ranking.

Usage analytics: we measure use of the API and MCP server per request (route or tool, coded parameters, status, timing, country and network, and a pseudonym that changes every day); never IP addresses, full user agents or free text. Details in the privacy notice.

See methodology, source conditions and privacy. Do not strip their warnings when reusing a figure.

Deprecated: API v1 and the legacy MCP endpoint (/mcp)

API v1 and https://prices.brainy.ae/mcp remain available. No removal date has been set; removal will be announced with notice. Existing v1 integrations continue to work. New integrations should use v2. The table maps the legacy tool names and routes to the v2 design; use v2 input schemas rather than copying old parameter names.

ministry_shop_prices, shopper_price_reports, costs_by_emirate, tax_savings_by_country, fx_rates, end_of_service_gratuity, labour_calculator and data_sources are new tools without a direct legacy equivalent. Online references and electronics have no v2 tool; their paused REST resources and metadata remain available. School uniform status is included in schools.

Parameter changes include q for REST product searches, max_annual_fee_aed for REST tuition filtering, zone_id for REST housing (resolve names with /housing/zones?q=…), profile_id for household costs, and category/max_aed_per_month for telecom. MCP tools retain their own documented inputs, including housing zone names/aliases. Grocery comparisons, DEWA, relocation, gratuity, overtime, annual leave, final settlement and job offer estimates use POST JSON.

Support and contact

Brainy Prices, its API, its MCP server and its ChatGPT app are operated by SOFT DEV FZ LLC, licensed by Fujairah Creative City – Media Free Zone (licence No. 9485/2016), Fujairah – Twin Towers, P.O. Box 4422, Fujairah, United Arab Emirates.

For help with the API, the MCP server or the ChatGPT app, to report a wrong figure, or for privacy requests, write to prices@brainy.ae. Never send an API key or a confirmation token. See also the terms and the privacy notice.

Links

• REST v2 OpenAPI 3.1 and service metadata
• MCP v2 endpoint: https://prices.brainy.ae/mcp/v2 (POST only)
• API catalogue: Linkset discovery for REST and MCP versions
• llms.txt: plain-text documentation for language models
• Deprecated v1 OpenAPI and v1 service metadata
• The website: same admitted data, for people
• Brainy Prices for Retailers: send us your product feed (agent-ready product feeds) · Retailer Feed Terms