Tool discovery

Three endpoints help you find the tools in the catalog. All of them require locale (tr or en).

Search

curl "https://api.mirac-ozdemir.com/v1/public/search?locale=tr&q=kdv&pageSize=2"

Parameter	Required	Description
locale	yes	tr or en.
q	no	Search text, at most 100 characters. If empty, all tools are listed.
category	no	Category key. A parent category also covers its subcategories.
page	no	Default 1.
pageSize	no	Default 20, at most 50.

{
  "data": [
    {
      "toolId": "7fbb657f-1877-4d62-a586-c0595b30f5e6",
      "key": "kdvli-fiyat-karsilastirma",
      "locale": "tr",
      "slug": "kdvli-fiyat-karsilastirma",
      "title": "KDV'li Fiyat Karşılaştırma (İki Teklif)",
      "shortDescription": "KDV dahil veya hariç, farklı KDV oranlarıyla verilmiş iki teklifi gerçek maliyetinize göre karşılaştırın.",
      "category": "kdv",
      "availability": "ONLINE",
      "score": 3.149,
      "path": "/tr/araclar/kdvli-fiyat-karsilastirma"
    }
  ],
  "meta": { "page": 1, "pageSize": 2, "total": 33, "totalPages": 17 }
}

• Search tolerates Turkish characters and spelling variations (kdv, k.d.v.).
• score is the relevance score; results come in this order.
• Search endpoints are rate limited (60 per minute); cache the results and send requests with a delay (debounce) while the user types in the search box.

Listing

curl "https://api.mirac-ozdemir.com/v1/public/tools?locale=tr&category=kdv&page=1&pageSize=20"

It returns the same fields as searchTools. The pageSize upper limit is 100. To pull the whole catalog, walk through as many pages as meta.totalPages:

JavaScript

async function listAllTools(locale = 'tr') {
  const items = [];
  for (let page = 1; ; page += 1) {
    const url = `https://api.mirac-ozdemir.com/v1/public/tools?locale=${locale}&page=${page}&pageSize=100`;
    const { data, meta } = await (await fetch(url)).json();
    items.push(...data);
    if (page >= meta.totalPages) return items;
  }
}

Python

import requests

def list_all_tools(locale="tr"):
    items, page = [], 1
    while True:
        r = requests.get(
            "https://api.mirac-ozdemir.com/v1/public/tools",
            params={"locale": locale, "page": page, "pageSize": 100},
            timeout=15,
        ).json()
        items += r["data"]
        if page >= r["meta"]["totalPages"]:
            return items
        page += 1

Tip

A snapshot of the whole catalog is available in searchable form on the Tool catalog page.

Categories

curl "https://api.mirac-ozdemir.com/v1/public/categories?locale=tr"

The response is a tree made up of parent categories and subcategories:

{
  "data": [
    {
      "key": "tax",
      "locale": "tr",
      "slug": "vergi",
      "path": "/tr/kategori/vergi",
      "name": "Vergi",
      "description": "KDV, gelir vergisi, stopaj, harçlar…",
      "toolCount": 116,
      "availability": "ONLINE",
      "alternates": [
        { "locale": "tr", "slug": "vergi", "path": "/tr/kategori/vergi" },
        { "locale": "en", "slug": "tax", "path": "/en/category/tax" }
      ],
      "children": [{ "key": "kdv", "name": "KDV Araçları", "toolCount": 13 }]
    }
  ]
}

You can narrow the list by using a category key in the category parameter (category=tax also covers all subcategories). Tools in a category with availability: "MAINTENANCE" cannot be calculated temporarily.

Resolving a tool from a site address

If you hold the website address (/tr/araclar/kdv-hesaplama), the by-slug endpoint resolves the tool:

curl "https://api.mirac-ozdemir.com/v1/public/tools/by-slug/tr/kdv-hesaplama"

The response is one of two forms: kind: "tool" (the tool definition) or kind: "redirect" (the new address if the slug has changed: locale, slug, path). For integrations, using the permanent key with by-key is safer.