Anvil › Docs › /v1/broadband-need

Broadband speed API: how many Mb/s a household needs, which plan, and does yours cope

Broadband need is the busiest moment, not the average: everything that runs at the same time on a weekday evening, added up, plus headroom because Wi-Fi and peak-time networks never deliver the full figure. A family with a 4K film, an HD stream, a video call, an online game and some browsing uses about 41 Mb/s at once; with x1.5 headroom that's 61.5 Mb/s, so an 80 Mb/s plan is comfortable. This endpoint does that sum, checks your plan in both directions and times big downloads.

Parameters

Example

Request:

GET https://api.oddlathe.com/v1/broadband-need?example=family&plan_down=50&plan_up=10

Response (generated by the real code when these docs were last built; random or time-based values will differ for you):

{
 "mode": "need",
 "use": "k4-1_hd-1_call-1_game-1_web-1",
 "headroom": {
  "key": "mixed",
  "name": "Usual Wi-Fi around the home",
  "x": 1.5
 },
 "busiest": {
  "down_mbps": 41,
  "up_mbps": 5.5
 },
 "with_headroom": {
  "down_mbps": 61.5,
  "up_mbps": 8.3
 },
 "suggested_plan": {
  "down_mbps": 80,
  "up_mbps": 10
 },
 "parts": [
  {
   "key": "k4",
   "name": "4K TV or film stream",
   "count": 1,
   "down_mbps": 25,
   "up_mbps": 0
  },
  {
   "key": "hd",
   "name": "HD (1080p) video stream",
   "count": 1,
   "down_mbps": 5,
   "up_mbps": 0
  },
  {
 …

Code examples

curl 'https://api.oddlathe.com/v1/broadband-need?example=family&plan_down=50&plan_up=10'

const params = new URLSearchParams({
  example: "family",
  plan_down: "50",
  plan_up: "10"
});
const res = await fetch(`https://api.oddlathe.com/v1/broadband-need?${params}`);
if (!res.ok) throw new Error((await res.json()).error.message);
const data = await res.json();
console.log(data);

import json, urllib.parse, urllib.request

params = urllib.parse.urlencode({"example": "family", "plan_down": "50", "plan_up": "10"})
url = "https://api.oddlathe.com/v1/broadband-need?" + params
# Send a User-Agent: the edge network refuses Python's default one.
req = urllib.request.Request(url, headers={"User-Agent": "my-script/1.0"})
with urllib.request.urlopen(req, timeout=10) as r:
    data = json.load(r)
print(data)

When it's useful

• Broadband comparison or moving-home pages: "what speed do you actually need?" from a few counters
• Support tools that tell a customer whether their plan or their Wi-Fi is the likely problem
• Checking upload for working from home, live streaming or cloud cameras, which plans often skimp on
• Teaching why a faster plan helps big downloads but not peak-time congestion

Good to know

• mode=need (default) takes use as activity-count pairs, for example use=k4-1_call-2_game-1 (a bare name counts as 1; words like 4k, zoom, twitch and cctv are accepted as aliases), or example=solo|couple|family|house. Returns busiest, with_headroom, suggested_plan, the parts, a summary and a downloads table.
• headroom is wired (x1.25), mixed (x1.5, default) or weak (x2). Plan tiers are 30, 50, 80, 100, 150, 300, 500, 1000 and 2000 Mb/s; upload tiers 5 to 1000.
• Add plan_down and plan_up for your_plan: Plenty (covers the headroom), Tight at busy times (covers what's in use but not the headroom) or Not enough (with short_mbps).
• mode=download&gb=100&plan_down=100 times a download: 100 GB is 2 h 13 min at 100 Mb/s in theory, 27 min at 500 and about 13 min at 1 Gb/s; the realistic column assumes 70% of the speed arrives.
• Figures are rounded typical values per stream or device, not a measurement. Speeds are megabits per second, as plans are sold (divide by 8 for MB/s).
• Browser UI: Tooltern broadband speed calculator with the same model and coloured download and upload pipes (nothing leaves your device). Background: how much broadband speed do I need and the Wirebook lesson on why the internet slows down in the evening.

How much broadband speed a household needs: adds up rounded typical Mb/s for everything happening at the busiest moment (4K and HD streams, video calls, online games, live streaming, cloud cameras, browsing, music), multiplies by headroom for Wi-Fi and busy evenings, and suggests the smallest common plan tier (30 to 2000 Mb/s) and upload tier that cover it. Pass plan_down / plan_up for a Plenty / Tight at busy times / Not enough verdict per direction. Also times a big download at your plan and 50 to 1000 Mb/s, in theory and at a realistic 70%. mode=download is just the time table; mode=options lists every figure. Same model as the Tooltern broadband speed calculator. Pure maths; nothing is stored.

Errors

Errors are JSON like {"error": {"code": "…", "message": "…"}}. The ones this endpoint can return:

• bad_param (400): a value is the wrong type or out of range (the message says which)
• rate_limited (429): over 60 requests a minute; wait for Retry-After seconds

Questions

Related endpoints

• /v1/stream-dataStreaming data use: GB per hour, monthly allowance planner, film size, hours from GB
• /v1/unitsConvert length, mass, temperature, data-size or data-rate units
• /v1/video-sizeVideo file size: MB for a length, what fits in free space, bitrate and ffmpeg commands for a target size
• /v1/input-lagInput lag: ms from button press to picture, split into six parts, with the biggest fixes ranked

Prefer a page to an API?

• Broadband speed calculator (busiest-moment pipes, plan check) on Tooltern: same job, nothing leaves your browser.

Published 7 November 2026 · OpenAPI 3.1 spec · Limits and privacy