🔌 API de calculadora gratuita

Sinopsis

La API ejecuta exactamente las mismas matemáticas que el sitio web utiliza. Envíe los valores de campo de una calculadora como parámetros de consulta o JSON y obtenga los resultados calculados de nuevo como JSON — incluyendo cualquier esquema de amortización o datos gráficos que la calculadora produce.

• 198+ calculadoras, cada una con su propio punto final
• No hay clave API — acceso anónimo, tasa limitada por IP
• CORS — Access-Control-Allow-Origin: * (uso del cliente)
• Límite de la tasa: 60 solicitudes/hora por IP (HTTP 429 cuando se supere)
• Los errores son gratis — sólo una respuesta exitosa (2xx) utiliza una llamada de su cuota mensual. Cada 400, 401, 404, 429 y 500 no le cuesta nada.

URL de la base

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

Índice — lista cada calculadora

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

Devuelve una lista legible por máquina de todas las calculadoras con los campos de cada una (llave, etiqueta, tipo, predeterminado, unidad) y las teclas de resultado — lo suficiente para construir un cliente dinámicamente. Cada campo también lleva una bandera requerida —verdadera para los pocos campos que no tienen por defecto (fechas, en su mayoría). Enviarlos: un par de calculadoras pueden inferir uno, el resto responder 400 sin él.

Computar — ejecutar una calculadora

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

Forma de respuesta:

{
  "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"]
}

Calculadoras de país-aware (hipoteca, préstamo, impuestos sobre la renta, ventas-impuestos...) aceptan ?country=us|uk|ca|au|in|ie|nz|za. Desconocido slug devuelve 404; país no soportado o mala entrada devuelve 400 con un mensaje útil y la especificación de campo.

Parámetros, valores predeterminados y errores

Envíe sólo los campos que le importan. Cualquier cosa que omita se llena con el valor predeterminado publicado de ese campo — el mismo valor que la página de la calculadora se rellena previamente, por lo que la API y el sitio web siempre devuelven los mismos números para las mismas entradas. defaults_applied.

Cualquier cosa que la API no pueda resolver honestamente es un error, nunca un cero: un parámetro mal escrito, un valor del tipo incorrecto, una opción desplegable desconocida, o un campo que no tiene ningún valor predeterminado (los campos de fecha — una fecha de nacimiento no se puede adivinar). Cada 400 nombres del parámetro ofensivo y se hace eco de la especificación de campo completo para que un cliente pueda corregirse.

$ 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": [ ... ]
}

Los /api/v1/ indice publica la clave de cada campo, tipo, unidad, predeterminado y si es necesario — suficiente para construir un cliente que nunca adivina.

Planes de autenticación de &

Puede llamar a la API sin ninguna clave — las solicitudes anónimas están limitadas por IP. Para una cuota mensual más alta y predecible (y uso comercial), cree una clave en su página de cuenta y envíela de tres maneras:

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"

• Libre — anónima (tipo IP limitado) o una llave libre con una pequeña cuota mensual. No comercial.
• Desarrollador — $9/mo — 10.000 llamadas/mes, uso comercial.
• Negocios — $49/mo — 100.000 llamadas/mes, rendimiento prioritario.

Lo que cuenta contra tu cuota

Sólo una respuesta exitosa. Una 2xx = una llamada. Cada error es gratis: un 400 para un parámetro mal escrito, un valor malo o un campo requerido faltante, un 404 para una bala desconocida, un 401 para una mala llave, un 429, y cualquier cosa que salga mal de nuestro lado. Explore el contrato y arregle su solicitud tantas veces como necesite — se le facturan por respuestas, no por correcciones.

Porque los errores son libres, en cambio, están limitados por la tasa: si una clave provoca más que 200 respuestas rechazadas en una hora, obtiene HTTP 429 "too_many_invalid_requests" hasta que la hora se acerca. Las llamadas exitosas nunca cuentan para eso, así que una integración de trabajo nunca lo verá, sólo atrapa a un cliente atrapado en un bucle de reintento.

Cuando se utiliza la cuota mensual de una clave, la API devuelve HTTP 429 con el error "quota_exceeded"; una clave desconocida o inactiva devuelve HTTP 401. Ver planes completos y registrarse en el Precios página.

Ejemplos

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}'

Todos los puntos finales

Un punto final por calculadora. Las teclas de campo y las teclas de resultado para cada uno están en el /api/v1/ índice.