← Back to blog

Free Unit Conversion API for AI Agents (curl & Python)

Unit conversion is one of those chores that shows up in every automation at the worst possible time. Your ingestion script gets shipping weights in pounds but the carrier API wants kilograms. Your dashboard renders temperatures in Celsius but the customer is in the US. Your agent reads a recipe, a spec sheet, or a dataset and needs to reason in a different measurement system before it can do anything useful.

You can hard-code conversion factors into every project, maintain a growing pile of constants, and silently drift out of sync across codebases — or you can call one public endpoint that handles the math for you. Agent Media Tools ships a free unit conversion API covering length, weight, temperature, volume, and speed. It takes a single GET or POST, requires no signup and no API key for plain HTTP calls, and is also exposed as an MCP tool (unit_convert) so AI agents can call it by name. This guide shows the real endpoint, the exact request and response shapes, and copy-paste examples in curl and Python.

Why use an API for unit conversion?

Writing the conversion inline is tempting — it is a few lines of arithmetic, after all. But real automation hits the failure modes fast:

• Factor drift. A mile is 1,609.344 meters, a pound is 0.45359237 kg, a US gallon is 3.785411784 liters. Most people round these, and rounding in the middle of a pipeline compounds.
• Temperature is not linear in the same way. Celsius, Fahrenheit, and Kelvin need offset math, which is exactly where quick inline implementations forget a +32 or a 273.15.
• Mixed unit systems. A single payload can mix imperial and metric, and each unit needs its own factor against a shared base.

An API gives every caller one consistent conversion table. Your scripts and agents send value, from, to, and category — and get a deterministic result back.

The endpoint

The unit converter lives at /api/units and accepts both GET (query parameters) and POST (JSON body). The parameters are identical:

Parameter	Type	Description
value	number	Numeric value to convert (required)
from	string	Source unit code, e.g. mi, kg, c (required)
to	string	Target unit code, e.g. km, lb, f (required)
category	string	One of length, weight, temperature, volume, speed. Defaults to length.

Here are the supported unit codes per category, exactly as implemented:

Category	Unit codes
length	mm, cm, m, km, in, ft, yd, mi
weight	mg, g, kg, oz, lb, ton
temperature	c, f, k
volume	ml, l, gal, qt, pt, cup, floz
speed	mps, kmh, mph, knot

Every category converts against a fixed base (meters, kilograms, liters, meters-per-second, or Celsius), so results are consistent regardless of which direction you convert. One nuance worth knowing: in the weight category, ton is the short (US) ton at 907.185 kg, not the metric tonne.

Convert with curl

The simplest call is a GET. Convert 5 miles to kilometers:

curl "https://agentmediatools.com/api/units?value=5&from=mi&to=km&category=length"

Response:

{"success":true,"value":5,"from":"mi","to":"km","result":8.0467,"category":"length"}

Temperature conversions handle the offset math for you — no +32 bookkeeping in your code:

curl "https://agentmediatools.com/api/units?value=100&from=c&to=f&category=temperature"
# {"success":true,"value":100,"from":"c","to":"f","result":212,"category":"temperature"}

If you prefer a JSON body, use POST. The handler merges the JSON fields with the same query-parameter names:

curl -X POST https://agentmediatools.com/api/units \
  -H "Content-Type: application/json" \
  -d '{"value":10,"from":"lb","to":"kg","category":"weight"}'
# {"success":true,"value":10,"from":"lb","to":"kg","result":4.5359,"category":"weight"}

Volume and speed work the same way — a gallon to liters, or 60 mph to km/h:

curl "https://agentmediatools.com/api/units?value=1&from=gal&to=l&category=volume"
# {"success":true,"value":1,"from":"gal","to":"l","result":3.7854,"category":"volume"}

curl "https://agentmediatools.com/api/units?value=60&from=mph&to=kmh&category=speed"
# {"success":true,"value":60,"from":"mph","to":"kmh","result":96.5606,"category":"speed"}

Convert with Python (requests)

The same endpoint is trivial to call from Python. A tiny wrapper keeps your pipeline code clean:

import requests

def convert(value, from_unit, to_unit, category="length"):
    resp = requests.get(
        "https://agentmediatools.com/api/units",
        params={
            "value": value,
            "from": from_unit,
            "to": to_unit,
            "category": category,
        },
        timeout=10,
    )
    resp.raise_for_status()
    return resp.json()

# Convert 5 miles to kilometers
print(convert(5, "mi", "km"))
# {'success': True, 'value': 5, 'from': 'mi', 'to': 'km', 'result': 8.0467, 'category': 'length'}

# Convert 212 degrees Fahrenheit to Celsius
print(convert(212, "f", "c", "temperature"))
# {'success': True, 'value': 212, 'from': 'f', 'to': 'c', 'result': 100.0, 'category': 'temperature'}

# Convert 2 liters to US cups
print(convert(2, "l", "cup", "volume"))
# {'success': True, 'value': 2, 'from': 'l', 'to': 'cup', 'result': 8.4535, 'category': 'volume'}

Because the response is plain JSON, you can drop this into a CSV normalization job, an ETL step, or a data-cleaning notebook without adding a dependency beyond requests. For a modest batch, loop over rows, call with a timeout, and let raise_for_status() surface bad input early. For large datasets, convert locally rather than turning every row into a network request.

Understanding the response and errors

Successful responses always include success: true, the input value/from/to, the computed result, and the category. Non-temperature results are rounded to four decimal places; temperature results are rounded to two. That rounding is deterministic, so the same input always returns the same output — which matters when you cache results or diff pipeline runs.

Invalid requests return HTTP 400 with a JSON error body. For example, a non-numeric value:

curl "https://agentmediatools.com/api/units?value=abc&from=mi&to=km"
# HTTP 400
# {"success":false,"error":"Invalid value"}

Unknown categories and unknown unit codes behave the same way (Unknown category: foo or Unknown unit). Validate from/to against the table above before calling, and your scripts will rarely see a 400.

Using it from an AI agent

The same converter is registered in the hosted MCP server as the unit_convert tool, with inputs value, from, to, and category. That means a Claude, Hermes, or any MCP-capable agent can normalize units natively — for example, when a web search returns "top speed 130 mph" and the agent needs to compare it against a km/h spec, or when an international order form arrives in mixed units. MCP access goes through your agent API key, while the raw HTTP endpoint stays free and keyless for scripts.

Prefer a visual check? The same tool is the Unit Converter panel in the browser toolbox, which is handy for spot-checking a conversion before you wire it into code.

Where this fits in your stack

The unit converter is a sibling of the other small deterministic utilities in the Agent Media Tools toolbox — the timezone conversion API for instants and the developer utility APIs for hashing, encoding, IDs, and text chores. None of them need a big SDK; they are one-call endpoints designed to be embedded in scripts and agents. Because the unit-conversion REST route carries no authentication, you can use it in shell one-liners, cron jobs, and CI steps with zero setup, subject to the platform's normal request limits.

Keep a copy of the unit table in your notes, point your wrapper at /api/units, and never hand-roll a Fahrenheit offset again.