🔌 Свободен калиброващ API

Преглед

API работи точно по същата математика, която използва уебсайта. Изпрати стойностите на полето на калкулатора като параметри на запитване или JSON и получи изчислените резултати обратно като JSON — включително всички амортизация график или графики, които калкулаторът произвежда.

• 198+ калиброве, всеки със своя крайна точка
• Без API ключ — анонимен достъп, ограничен с IP
• CORS — Access-Control-Allow-Origin: * (Употреба на клиента)
• Ограничение на скоростта: 60 искания/час на IP (HTTP 429, когато е превишено)
• Грешката е свободна — Само успешен (2xx) отговор използва едно обаждане от месечната квота. На всеки 400, 401, 404, 429 и 500 ви струва нищо.

Основен URL

https://calculator.free/api/v1/

Индекс — списък на всеки калкулатор

GET https://calculator.free/api/v1/

Връща машинно четен списък на всички калкулатори с полетата на всеки един (ключ, етикет, тип, по подразбиране, единица) и ключове за резултат — достатъчно, за да се изгради клиент динамично. Всяко поле също така носи изисквано знаме — вярно за няколко полета, които нямат по подразбиране (по-вече дати). Изпрати тези: няколко калкулатора могат да изчислят един, останалата отговор 400 без него.

Изчисляване — изпълняване на един калкулатор

GET  https://calculator.free/api/v1/<slug>/?field=value&field=value
POST https://calculator.free/api/v1/<slug>/     (JSON or form body)

Форма на отговора:

{
  "ok": true,
  "slug": "mortgage",
  "country": "us",
  "inputs":   { ... the values actually computed with ... },
  "results":  { ... computed result keys ... },
  "schedule": { "columns": [...], "rows": [...] } | null,
  "chart":    { "type": "pie", "slices": [...] } | null,
  "defaults_applied": ["tax", "insurance"]
}

Калиброве на страните (морт, заем, данък върху доходите, данъка върху продажбите...) приемат ?country=us|uk|ca|au|in|ie|nz|za. Неизвестен полз връща 404; неподдържана страна или лош вход връща 400 с полезно съобщение и поле спецификация.

Параметри, по подразбиране и грешки

Изпращане само на полетата, за които се интересувате. Всичко, което изоставяте, е изпълнено с публикуваното поле по подразбиране – същата стойност, която калибровата страница предварително изпълва, така че API и уебсайта винаги връщане на същите числа за същите входове. Всяко отговор показва това, което тя попълва в defaults_applied.

Всичко, което API не може да реши честно, е грешка, никога не е нула: погрешно объркан параметр, стойност на грешния тип, неизвестна падаща опция или липсващо поле, което няма по подразбиране (полята за дата — дата не може да се отгатне). Всяко 400 имена на обиждащия параметър и отразява пълния специфичен параметр на полето, така че клиентът може да се поправи.

$ curl "https://calculator.free/api/v1/mortgage/?price=350000&rate=6.5&term=30"
{
  "ok": false,
  "error": "unknown_parameter",
  "message": "Unknown parameter 'term' for calculator 'mortgage'. Did you mean 'years'? ...",
  "unknown_parameters": ["term"],
  "did_you_mean": { "term": "years" },
  "valid_parameters": ["down", "extra", "extra_onetime", "extra_yearly", "hoa",
                       "insurance", "other", "pmi", "price", "rate", "tax", "years"],
  "fields": [ ... ]
}

The /api/v1/ индекс публикува ключа на всяко поле, тип, единица, по подразбиране и дали е необходимо — достатъчно, за да се изгради клиент, който никога не предполага.

Планове за автентичност

Можете да се обадите на API без ключ изобщо — анонимните искания са ограничени с ставка от IP. За по-висока, предсказуема месечна квота (и търговски употреба), създавайте ключ на вашата страница на сметката и я изпращайте един от три начина:

GET  https://calculator.free/api/v1/mortgage/?price=350000&key=YOUR_KEY
curl -H "Authorization: Bearer YOUR_KEY" "https://calculator.free/api/v1/bmi/?units=metric&height=180&weight=80"
curl -H "X-Api-Key: YOUR_KEY"           "https://calculator.free/api/v1/bmi/?units=metric&height=180&weight=80"

• Безплатен — анонимна (ограничена ставка на КИП) или свободен ключ с малка месечна квота.
• Разработчик — $9/mo — 10 000 обаждания месечно, търговска употреба.
• Бизнес — $49/mo — 100 000 обаждания на месец, приоритетен пропуск.

Какво е важно за квотата ти?

Само успешен отговор прави. Едно 2xx = едно обаждане. Всяка грешка е безплатна: 400 за погрешно оформен параметр, лоша стойност или липсващо поле, 404 за неизвестен куршум, 409 за лош ключ, 429 и всичко, което се обърка от наша страна. Разгледайте договора и поправете искането си толкова пъти, колкото ви трябва - сте наплатени за отговори, а не за корекции.

Защото грешките са безплатни, те са ограничени с лимит вместо: ако един ключ провокира повече от 200 Отхвърлени отговори за час, получава HTTP 429 "too_mnogy_ OPAT_ Заявки" докато часът се превърне. Успешните обаждания никога не се броят към това, така че работната интеграция никога няма да го види – тя само хваща клиент заседнат в повторното повторяване.

Когато се използва месечна квота на ключ, API връща HTTP 429 с грешка "quota_ превишена"; неизвестен или неактивен ключ връща HTTP 401. Вижте пълни планове и се регистрирайте на Цена страница.

Примери

curl

curl "https://calculator.free/api/v1/mortgage/?price=350000&down=70000&rate=6.9&years=30"

JavaScript fetch()

const r = await fetch(
  "https://calculator.free/api/v1/bmi/?" + new URLSearchParams({
    units: "metric", height: "180", weight: "80"
  }));
const { results } = await r.json();
console.log(results.bmi, results.category);

Python

import requests

r = requests.get("https://calculator.free/api/v1/mortgage/",
                 params={"price": 350000, "down": 70000,
                         "rate": 6.9, "years": 30},
                 headers={"Authorization": "Bearer YOUR_KEY"})
print(r.json()["results"])

POST JSON

curl -X POST "https://calculator.free/api/v1/income-tax/?country=uk" \
  -H "Content-Type: application/json" \
  -d '{"income": 60000}'

Всички крайни точки

Един крайна точка на калкулатор. Полеви ключове и резултатни ключове за всеки от тях са в /api/v1/ индекс.