UnitSwapper

API Documentation

Real-time forex rates, historical exchange data, and unit conversions - one API key, one endpoint structure. Free tier available, no credit card required.

Get Free API KeyQuick StartOpenAPI Spec

Quick Start

Get your API key from your dashboard and make your first request in under a minute.

Get live forex rates

curl "https://unitswapper.net/api/v1/latest?base=USD&symbols=EUR,CHF,GBP" \
  -H "Authorization: Bearer YOUR_API_KEY"
{
  "base": "USD",
  "date": "2026-04-06",
  "timestamp": 1744000200,
  "rates": {
    "EUR": 0.9187,
    "CHF": 0.9042,
    "GBP": 0.7831
  }
}

Convert units

curl "https://unitswapper.net/api/v1/convert?from=kilometer&to=mile&value=100" \
  -H "Authorization: Bearer YOUR_API_KEY"
{
  "result": 62.13711922,
  "from": "kilometer",
  "to": "mile",
  "value": 100,
  "formula": "multiply by 0.621371192",
  "precision": 8
}

Replace YOUR_API_KEY with the key from your dashboard. Base URL: https://unitswapper.net.

Authentication

Authenticated endpoints require a Bearer token in the Authorization HTTP header.

Authorization: Bearer YOUR_API_KEY
  • Where to get a key - Sign in at unitswapper.net/login and generate an API key from your dashboard. No credit card required.
  • Keep it secret - Do not expose your key in client-side code or public repositories.
  • Public endpoints - /api/v1/fx/currencies, /api/v1/units, /api/v1/categories, and /api/v1/status do not require authentication.

Endpoints

All endpoints are versioned under /api/v1/ and return JSON.

GET

/api/v1/latest

Requires API key

Returns the latest exchange rates for a given base currency. Rates are updated every 30 seconds on Pro/Business plans, hourly on Starter, and daily on Free.

Query Parameters

ParameterTypeDescription
basestringBase currency code (e.g. USD, EUR). Defaults to EUR.
symbolsstringComma-separated list of target currency codes. Returns all currencies if omitted.

Example request

curl "https://unitswapper.net/api/v1/latest?base=USD&symbols=EUR,CHF,GBP" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "base": "USD",
  "date": "2026-04-06",
  "timestamp": 1744000200,
  "rates": {
    "EUR": 0.9187,
    "CHF": 0.9042,
    "GBP": 0.7831
  }
}
GET

/api/v1/historical

Requires API key - all plans

Returns exchange rates for a specific date in the past. Historical data is available from 1999-01-01 on all plans including Free.

Query Parameters

ParameterTypeDescription
daterequiredstringDate in YYYY-MM-DD format. Must be 1999-01-01 or later.
basestringBase currency code. Defaults to EUR.
symbolsstringComma-separated list of target currency codes. Returns all if omitted.

Example request

curl "https://unitswapper.net/api/v1/historical?date=2025-01-01&base=EUR" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "base": "EUR",
  "date": "2025-01-01",
  "historical": true,
  "rates": {
    "USD": 1.0352,
    "GBP": 0.8318,
    "CHF": 0.9431
  }
}
GET

/api/v1/timeseries

Starter+

Returns daily exchange rates for a date range. Maximum range is 365 days on Starter, unlimited on Pro and Business.

Query Parameters

ParameterTypeDescription
start_daterequiredstringStart of range in YYYY-MM-DD format.
end_daterequiredstringEnd of range in YYYY-MM-DD format.
basestringBase currency code. Defaults to EUR.
symbolsstringComma-separated list of target currency codes.

Example request

curl "https://unitswapper.net/api/v1/timeseries?start_date=2025-01-01&end_date=2025-01-31&base=USD&symbols=EUR" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "base": "USD",
  "start_date": "2025-01-01",
  "end_date": "2025-01-03",
  "rates": {
    "2025-01-01": { "EUR": 0.9621 },
    "2025-01-02": { "EUR": 0.9608 },
    "2025-01-03": { "EUR": 0.9599 }
  }
}
GET

/api/v1/fluctuation

Starter+

Returns the absolute and percentage change for exchange rates between two dates. Useful for charting rate movements and building alerts.

Query Parameters

ParameterTypeDescription
start_daterequiredstringStart date in YYYY-MM-DD format.
end_daterequiredstringEnd date in YYYY-MM-DD format.
basestringBase currency code. Defaults to EUR.
symbolsstringComma-separated list of target currency codes.

Example request

curl "https://unitswapper.net/api/v1/fluctuation?start_date=2025-01-01&end_date=2025-12-31&base=USD&symbols=EUR,GBP" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "base": "USD",
  "start_date": "2025-01-01",
  "end_date": "2025-12-31",
  "fluctuation": true,
  "rates": {
    "EUR": {
      "start_rate": 0.9621,
      "end_rate": 0.9187,
      "change": -0.0434,
      "change_pct": -4.51
    },
    "GBP": {
      "start_rate": 0.7920,
      "end_rate": 0.7831,
      "change": -0.0089,
      "change_pct": -1.12
    }
  }
}
GET

/api/v1/fx/currencies

Public - no auth required

Returns the full list of supported currency codes and their display names. No parameters required.

Example request

curl "https://unitswapper.net/api/v1/fx/currencies"

Response (truncated)

{
  "currencies": {
    "USD": "US Dollar",
    "EUR": "Euro",
    "GBP": "British Pound",
    "CHF": "Swiss Franc",
    "JPY": "Japanese Yen"
  }
}
GET

/api/v1/convert

Requires API key

Convert a numeric value between any two supported units (length, weight, temperature, area, volume, speed, data, time). Currency conversion is handled by the /api/v1/latest endpoint.

Query Parameters

ParameterTypeDescription
fromrequiredstringSource unit ID (e.g. kilometer, pound, celsius)
torequiredstringTarget unit ID (e.g. mile, kilogram, fahrenheit)
valuerequirednumberNumeric value to convert. Finite number, any sign.

Example request

curl "https://unitswapper.net/api/v1/convert?from=kilometer&to=mile&value=100" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "result": 62.13711922,
  "from": "kilometer",
  "to": "mile",
  "value": 100,
  "formula": "multiply by 0.621371192",
  "precision": 8
}
GET

/api/v1/units

Public - no auth required

List all supported units. Pass an optional category query parameter to filter by category. Use unit IDs returned here as the from and to values in the convert endpoint.

Query Parameters

ParameterTypeDescription
categorystringOptional. Filter by category ID (e.g. length, weight, temperature)

Example request

curl "https://unitswapper.net/api/v1/units?category=length"

Response

{
  "category": "length",
  "units": [
    { "id": "meter",      "name": "Meter",      "plural": "Meters",      "symbol": "m",  "category": "length" },
    { "id": "kilometer",  "name": "Kilometer",  "plural": "Kilometers",  "symbol": "km", "category": "length" },
    { "id": "mile",       "name": "Mile",        "plural": "Miles",       "symbol": "mi", "category": "length" },
    { "id": "foot",       "name": "Foot",        "plural": "Feet",        "symbol": "ft", "category": "length" }
  ]
}
GET

/api/v1/categories

Public - no auth required

Returns all available unit categories with their IDs, names, descriptions, and unit counts. No parameters required.

Example request

curl "https://unitswapper.net/api/v1/categories"

Response

{
  "categories": [
    { "id": "length",      "name": "Length",      "description": "Distance and length",  "unitCount": 12 },
    { "id": "weight",      "name": "Weight",      "description": "Mass and weight",       "unitCount": 10 },
    { "id": "temperature", "name": "Temperature", "description": "Temperature scales",    "unitCount": 4  },
    { "id": "area",        "name": "Area",        "description": "Surface area",          "unitCount": 9  },
    { "id": "volume",      "name": "Volume",      "description": "Capacity and volume",   "unitCount": 11 },
    { "id": "speed",       "name": "Speed",       "description": "Velocity and speed",    "unitCount": 6  },
    { "id": "data",        "name": "Data",        "description": "Digital storage",       "unitCount": 10 },
    { "id": "time",        "name": "Time",        "description": "Duration and time",     "unitCount": 9  }
  ]
}
GET

/api/v1/status

Public - no auth required

Health check endpoint. Returns the current API status and version. Useful for monitoring integrations.

Example request

curl "https://unitswapper.net/api/v1/status"

Response

{
  "status": "ok",
  "version": "1.0",
  "uptime": 99.99
}
GET

/api/v1/me

Requires API key

Returns information about the account associated with the API key: current plan, monthly usage and limit, number of active API keys, and account creation date.

Example request

curl "https://unitswapper.net/api/v1/me" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "plan": "free",
  "usage_this_month": 42,
  "limit_month": 5000,
  "keys_count": 1,
  "member_since": "2026-01-15T10:23:00.000Z"
}

Response Format

All responses use Content-Type: application/json. Every authenticated response also includes rate limit headers:

HeaderDescription
X-RateLimit-LimitMaximum requests allowed in the current window
X-RateLimit-RemainingRequests remaining in the current window
X-RateLimit-ResetUnix timestamp when the limit resets (UTC)

Error Codes

Errors return a JSON body with an error string and the appropriate HTTP status code.

400

Bad Request

Missing or invalid parameters. The response includes a details object with per-field validation messages.

{ "error": "Invalid parameters", "details": { "value": ["Expected number, received string"] } }
401

Unauthorized

No API key provided or the key is invalid. Check the Authorization header format.

{
  "error": "Missing API key. Provide Authorization: Bearer <api_key>"
}
404

Not Found

The requested category, unit, or date does not exist.

{ "error": "Unknown category" }
429

Too Many Requests

You have exceeded your plan's rate limit. Wait for the reset window or upgrade your plan.

{
  "error": "Rate limit exceeded. Upgrade your plan for more requests."
}

Rate Limiting

Rate limits are applied per API key on a rolling monthly window (UTC calendar month reset). When you exceed your limit you will receive a 429 response.

  • -Authenticated endpoints - limits are tied to your account and shared across all your API keys.
  • -Public endpoints -/api/v1/fx/currencies, /api/v1/units, /api/v1/categories, and /api/v1/status have a separate IP-based limit and do not count against your plan quota.
  • -Headers - every authenticated response includes X-RateLimit-Remaining and X-RateLimit-Reset so you can track usage programmatically.
  • -Best practice - check X-RateLimit-Remaining before making bulk requests and back off exponentially if you receive a 429.

Pricing

Start for free. Scale as you grow. Full pricing details at unitswapper.net/pricing.

Free

$0

forever

  • ✓5,000 req/month
  • ✓33 currencies
  • ✓Daily updates
  • ✓History since 1999
  • ✓Unlimited unit conversions
Get started

Starter

$9

/month

  • ✓50,000 req/month
  • ✓170+ currencies
  • ✓Hourly updates
  • ✓Timeseries & fluctuation
  • ✓Email support
Start trial

Pro

Popular

$29

/month

  • ✓500,000 req/month
  • ✓170+ currencies
  • ✓30-second updates
  • ✓Webhooks
  • ✓SLA 99.9%
Start trial

Business

$99

/month

  • ✓5M req/month
  • ✓All currencies
  • ✓WebSocket streaming
  • ✓SLA 99.95%
  • ✓Dedicated support
Contact sales

Code Examples

Examples in four languages. Swap YOUR_API_KEY for your key from the dashboard.

Live exchange rates

Fetch latest USD rates for EUR, CHF, GBP.

cURL

curl "https://unitswapper.net/api/v1/latest?base=USD&symbols=EUR,CHF,GBP" \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript

const response = await fetch(
  "https://unitswapper.net/api/v1/latest?base=USD&symbols=EUR,CHF,GBP",
  { headers: { Authorization: "Bearer YOUR_API_KEY" } }
);
const data = await response.json();
// data.rates.EUR => 0.9187

Python (httpx)

import httpx

response = httpx.get(
    "https://unitswapper.net/api/v1/latest",
    params={"base": "USD", "symbols": "EUR,CHF,GBP"},
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
data = response.json()
print(data["rates"])  # {"EUR": 0.9187, "CHF": 0.9042, "GBP": 0.7831}

PHP

<?php
$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => 'https://unitswapper.net/api/v1/latest'
        . '?base=USD&symbols=EUR,CHF,GBP',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer YOUR_API_KEY'],
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
print_r($data['rates']);
?>

Unit conversion

Convert 100 kilometers to miles.

cURL

curl "https://unitswapper.net/api/v1/convert?from=kilometer&to=mile&value=100" \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript

const response = await fetch(
  "https://unitswapper.net/api/v1/convert?from=kilometer&to=mile&value=100",
  { headers: { Authorization: "Bearer YOUR_API_KEY" } }
);
const data = await response.json();
console.log(data.result); // 62.1371...

Python (httpx)

import httpx

response = httpx.get(
    "https://unitswapper.net/api/v1/convert",
    params={"from": "kilometer", "to": "mile", "value": 100},
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
data = response.json()
print(data["result"])  # 62.1371...

PHP

<?php
$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => 'https://unitswapper.net/api/v1/convert'
        . '?from=kilometer&to=mile&value=100',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer YOUR_API_KEY'],
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);
echo $response['result']; // 62.1371...
?>

Ready to build?

Create a free account, generate your API key, and make your first request in under 5 minutes. No credit card required.

Get Free API Key