# Data Transfer API
> Data-transfer and bandwidth maths as an API, computed locally and deterministically. The time endpoint computes how long a file takes to transfer at a given bandwidth, time = file bits ÷ (rate × (1 − overhead)), accepting sizes in B, KB, MB, GB, TB or the binary KiB/MiB/GiB and rates in bps, Kbps, Mbps, Gbps or bytes-per-second (MB/s), with an optional protocol-overhead allowance, and returns the time in seconds, minutes, hours and a human-readable form. The bandwidth endpoint works backwards: the bandwidth needed to move a file within a target time, in bps, Mbps, Gbps and MB/s. The convert endpoint converts a data size between decimal (1 MB = 1,000,000 bytes) and binary (MiB = 1,048,576) units, or a data rate between bit-rates and byte-rates. Everything is computed locally and deterministically, so it is instant and private. Ideal for networking, cloud, backup and streaming app developers, download-time and capacity-planning tools, and dev dashboards. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is transfer time and bandwidth; for media encoding bitrate use a bitrate API.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/transfer-api/..."
```

## Pricing
- **Free** (Free) — 3,000 calls/Mo, 2 req/s
- **Starter** ($6/Mo) — 40,000 calls/Mo, 5 req/s
- **Pro** ($18/Mo) — 300,000 calls/Mo, 15 req/s
- **Mega** ($59/Mo) — 1,500,000 calls/Mo, 40 req/s

## Endpoints

### Transfer

#### `GET /v1/bandwidth` — Required bandwidth

**Parameters:**
- `file_size` (query, required, string) — File size Example: `1`
- `size_unit` (query, optional, string) — Size unit (default GB) Example: `GB`
- `seconds` (query, required, string) — Target time (seconds) Example: `60`
- `overhead_percent` (query, optional, string) — Protocol overhead % (default 0) Example: `0`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/transfer-api/v1/bandwidth?file_size=1&size_unit=GB&seconds=60&overhead_percent=0"
```

**Response:**
```json
{
    "data": {
        "gbps": 0.133333333,
        "mbps": 133.333333,
        "note": "bandwidth = file bits / time / (1 − overhead). Mbps is megabits per second; MB/s is megabytes per second (×8).",
        "inputs": {
            "seconds": 60,
            "file_size": 1,
            "size_unit": "GB",
            "overhead_percent": 0
        },
        "mb_per_s": 16.666667,
        "bits_per_second": 133333333.3333
    },
    "meta": {
        "timestamp": "2026-06-04T18:38:13.969Z",
        "request_id": "987c81b2-5840-421c-a7fc-7c7f121dcca6"
    },
    "status": "ok",
    "message": "Required bandwidth",
    "success": true
}
```

#### `GET /v1/convert` — Data unit conversion

**Parameters:**
- `value` (query, required, string) — Value to convert Example: `1`
- `from` (query, required, string) — Unit (GB, MiB, Mbps, MB/s …) Example: `GB`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/transfer-api/v1/convert?value=1&from=GB"
```

**Response:**
```json
{
    "data": {
        "GB": 1,
        "KB": 1000000,
        "MB": 1000,
        "TB": 0.001,
        "GiB": 0.931322575,
        "KiB": 976562.5,
        "MiB": 953.674316,
        "bits": 8000000000,
        "mode": "size",
        "note": "Decimal (KB=1000) and binary (KiB=1024) sizes from the input.",
        "bytes": 1000000000,
        "inputs": {
            "from": "GB",
            "value": 1
        }
    },
    "meta": {
        "timestamp": "2026-06-04T18:38:14.093Z",
        "request_id": "a8e9e379-f0fe-48c8-aaad-b1fda5b0b4be"
    },
    "status": "ok",
    "message": "Data unit convert",
    "success": true
}
```

#### `GET /v1/time` — Transfer time

**Parameters:**
- `file_size` (query, required, string) — File size Example: `1`
- `size_unit` (query, optional, string) — B | KB | MB | GB | TB | GiB … (default GB) Example: `GB`
- `bandwidth` (query, required, string) — Bandwidth value Example: `100`
- `bandwidth_unit` (query, optional, string) — bps | Mbps | Gbps | MB/s (default Mbps) Example: `Mbps`
- `overhead_percent` (query, optional, string) — Protocol overhead % (default 0) Example: `0`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/transfer-api/v1/time?file_size=1&size_unit=GB&bandwidth=100&bandwidth_unit=Mbps&overhead_percent=0"
```

**Response:**
```json
{
    "data": {
        "note": "time = file bits / (bandwidth bits-per-second × (1 − overhead)). Bytes are 8 bits; SI units (1 MB = 1,000,000 bytes).",
        "hours": 0.02222222,
        "human": "0h 1m 20s",
        "inputs": {
            "bandwidth": 100,
            "file_size": 1,
            "size_unit": "GB",
            "bandwidth_unit": "Mbps",
            "overhead_percent": 0
        },
        "minutes": 1.333333,
        "seconds": 80
    },
    "meta": {
        "timestamp": "2026-06-04T18:38:14.204Z",
        "request_id": "e2b654f4-a198-4280-81c2-ecee71ad613d"
    },
    "status": "ok",
    "message": "Transfer time",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Spec

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/transfer-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "notes": "Sizes in SI (1 MB = 1,000,000 bytes) or binary (MiB = 1,048,576). Rates in bits/s (Mbps) or bytes/s (MB/s). Real throughput is usually below the line rate — add overhead.",
        "service": "transfer-api",
        "formulae": {
            "bits": "1 byte = 8 bits",
            "time": "time = file_bits / (rate_bits_per_s × (1 − overhead))",
            "bandwidth": "rate = file_bits / time / (1 − overhead)"
        },
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/time": "Transfer time for a file at a bandwidth, with an optional protocol-overhead allowance.",
            "GET /v1/convert": "Convert a data size (B…TiB) or rate (bps…Gbps, MB/s) between units.",
            "GET /v1/bandwidth": "Bandwidth needed to move a file within a target time."
        },
        "description": "Data-transfer and bandwidth calculator: transfer time, required bandwidth, and data size/rate unit conversion."
    },
    "meta": {
        "timestamp": "2026-06-04T18:38:14.292Z",
        "request_id": "dfa02682-8549-4bfd-a9ea-ec56b88fdce7"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/transfer-api
OpenAPI spec: https://www.oanor.com/api/transfer-api/openapi.json