Frequently asked questions

General

Is the API free, and is a key required?

No sign-up or API key is required to use the public API. Per-IP limits apply for fair use: Rate limits. If you plan high-volume or commercial use, contact us.

Are the results official?

No. Results are for information purposes only and do not replace tax, legal or financial advice. The rates we use, together with their legal sources, are in the meta.rates field of the response and in the rates field of the tool definition.

How up to date are the rates?

Every rate is published with an effective range, a source and lastReviewedAt (the last review date). Amounts tied to annual revaluation (income tax brackets, fees, exemptions, etc.) are updated with new periods at the start of each year. For a historical calculation, use asOf: Calculation.

Are the calculation formulas open?

No. The input/output schema, labels, rates and results are published; the calculation definition itself is not.

API

Why are decimals strings?

To avoid floating-point errors in money calculations. Strings such as "1234.56" preserve precision; values sent as JSON numbers are rejected. See Core concepts.

Should I use key or toolId?

key. It is the same in every environment and permanent. toolId is environment-specific.

Can I call it directly from the browser?

Yes. Public endpoints are open to CORS; no proxy is needed. See API overview.

I’m getting 429, what should I do?

Wait for Retry-After and retry. Cache definitions and search results, and use a delay (debounce) on search: Rate limits.

Why does a tool return 503 MAINTENANCE?

The tool has been temporarily put under maintenance. Retry after Retry-After; see Status.

I need a tool that isn’t in the catalog. Can you add it?

You can request a tool through the contact page of our website.

Which tools are there?

All are listed in the tool catalog; or use the /v1/public/tools and /v1/public/search endpoints.

Widget

Does the widget require an API key or sign-up?

No. A single line of HTML and a script are enough: Installation.

Can I remove the disclaimer or the link in the widget?

No. The tool’s disclaimer and the attribution link to the full tool page are part of the widget. You can hide the title (data-header="false").

Can I match the widget’s appearance to my own brand?

To a degree, yes: the theme (light, dark, auto, and inherit, which follows your page), the accent colour (data-accent), the corner radius (data-radius), the density (data-density) and the language can be set: Installation. There is no font customization or full layout change. For a fully custom look, use the Public API.

Can I embed only the calculator?

No. Besides the calculator you can embed a search box (data-mo-search) and a category list (data-mo-category); you can also show the calculator with only its result panel (data-view="result"): Widget kinds.

Can I prefill the form or trigger the calculation from code?

Yes. Use data-input-<field> / data-inputs for prefilled values and data-autorun for automatic calculation; at runtime use MiracOzdemirWidget.setInputs, calculate and reset: JavaScript API.

Is the widget reloaded when I change options?

Presentation options such as theme, accent colour, radius, density, header and view are applied with MiracOzdemirWidget.update without reloading the iframe; changing the language or the tool reloads the iframe: JavaScript API.

The widget pushes the page down (CLS), what should I do?

The loader draws a skeleton placeholder and remembers the last measured height. To prevent the shift on the very first visit too, give the tool’s typical height with data-height: Installation.

Is there an SDK or a React/Vue component, and is it on npm?

A typed SDK package (@mirac-ozdemir/widget: React/Vue components, loadWidget, types) is ready, but it is not published to npm yet; it can be used as a source package. The raw loader and the <mo-calculator> custom elements work without the SDK: Custom elements and SDK.

Can I pin the widget script to a fixed version with an integrity (SRI) check?

Yes: /widget/v1.1.0.js is immutable and is published with its sha384 hash in /widget/manifest.json: Versioning policy.

Is it recorded which sites embed the widget?

Yes, anonymously and in aggregate: the embed page counts the domain of the embedding page (the domain only) per tool and day. Inputs, results, IP addresses, cookies and page paths are not stored: Security and privacy.

Does the widget contribute to my SEO?

Embed pages are noindex; the content value comes from your page’s own text. We recommend adding an explanatory text about the tool.

I use CSP and the widget doesn’t work.

Add the rules script-src https://api.mirac-ozdemir.com; frame-src https://mirac-ozdemir.com: Security and CSP.

Can I use the result on my own page?

Yes: listen to the mo:result event: Events.