Open Source

Build with CoverageMap, open sourced

We're opening up the tools that power CoverageMap, starting with @coveragemap/speed-test — a free library that gives any app access to our speed testing network and infrastructure.

View on npmView on GitHub
Apache 2.010 Minute SetupFree forever
$npm install @coveragemap/speed-test
TypeScript
import { SpeedTestEngine } from '@coveragemap/speed-test'

const engine = new SpeedTestEngine({
  application: {
    id: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
    name: 'My App',
    version: '1.0.0',
    organization: 'My Org',
    type: 'web',
  },
})

// Runs latency -> download -> upload against the nearest server
const result = await engine.run()
console.log(result.results.measurements)
Why we're doing it

Sharing what we built

CoverageMap runs on real-world, crowdsourced data. Open sourcing our tools lets developers plug into that ecosystem and makes the maps better for everyone.

Real-world data
Open libraries let more developers contribute richer, crowdsourced measurements to the map.
Hard problems solved
Distributed servers, a buffer-resistant protocol, accurate multi-gigabit measurement. We built it.
A symbiotic deal
You get world-class infrastructure for free; we get more data points for more accurate maps.
Free and Apache 2.0
Use it in personal projects, commercial products, and open source tools. No fees, no tiers.
The libraries

What's available today

We're just getting started with one package on npm now, with more CoverageMap libraries planned.

Speed Test Client API

Build your own speed test client that measures latency, jitter, download, and upload throughput using CoverageMap's global server network.

Speed Test ClientTypeScriptnpmBrowser + Node
npmGitHub

More on the way

We plan to open source more of the libraries that power CoverageMap. Watch the GitHub organization for new releases.

How to use it

Up and running in minutes

1

Install from npm

Requires Node.js 20 or newer and works with any modern bundler.

2

Create an engine

Add your application metadata so every result is attributed to your app.

3

Run the test

Latency, download, and upload run against the nearest server automatically.

4

Read the docs

Explore the protocol spec, API reference, and backend integration guides.

$npm install @coveragemap/speed-test
Read the documentation
Use cases

What you can build

From consumer apps to backend monitors, the same engine adapts to wherever you need accurate measurements.

Consumer speed test app

Build a branded speed test at your own domain. Embed the engine in React, Vue, Svelte, or plain HTML with live download, upload, and latency gauges. It runs entirely client-side, so no backend is required.

Consumer speed test web app powered by the CoverageMap library

Mobile coverage app (WebView)

The browser-mode library runs inside WebView environments. Pair it with device location APIs and cell telemetry SDKs to capture geolocated cellular measurements from a hybrid mobile app.

Mobile coverage app running a speed test inside a WebView

Network monitoring dashboard

Use the Node.js backend mode to run scheduled speed tests from your servers or edge nodes. Continuously monitor egress bandwidth from your infrastructure and alert on degradation over time.

Network monitoring dashboard charting speed test results
The symbiotic deal

Where your results go

When a user runs a test through your app, the result does three things. You get free infrastructure; CoverageMap gets richer data.

Step 1
Returned to You
Each run resolves to a typed object with all measurement data including latency, jitter, download, and upload.
Step 2
Uploaded to CoverageMap
Results are tagged with device metadata, location, and app identity, then saved to CoverageMap's servers.
Step 3
Added to the Map
Qualifying tests join the crowdsourced dataset that powers the maps on coveragemap.com.

While all tests are collected, not all are added to the map. Tests must satisfy certain conditions to be mapped.

Fair use
The infrastructure behind the library is shared. To keep it fast for everyone, please follow a few guidelines.
  • Run tests in response to a genuine need — user-triggered measurements, reasonable monitoring, or one-off diagnostics.
  • Automated or scheduled tests must run no more than once per 10 minutes per application.
  • Always provide accurate application id, name, and organization metadata so tests can be attributed.

CoverageMap may rate-limit or block any application ID found to be abusing the infrastructure. For high-volume use cases, reach out before deploying.

FAQ

Frequently asked questions

Everything you need to know before you start building.

How much does it cost?

Nothing. The library is free and open source under the Apache 2.0 license, and it runs against CoverageMap’s shared infrastructure at no charge, subject to the fair use policy.

What are the requirements?

Node.js 20 or newer. It ships in dual ESM/CJS format and works in modern browsers via bundlers like Vite or webpack, as well as in Node.js for backend and CLI usage.

What happens to my test results?

Completed results are returned to your application and also uploaded to CoverageMap, where they are tagged with device metadata, location, app identity, and a timestamp. Qualifying tests contribute to the coverage map.

Are there rate limits?

Yes. Automated or scheduled tests must run no more than once per 10 minutes per application. CoverageMap may rate-limit or block any application ID found to be abusing the shared infrastructure.

Can I use it in a commercial product?

Yes. The Apache 2.0 license permits use in personal projects, commercial products, and open source tools. For high-volume use cases, reach out to discuss your needs.

Will there be more libraries?

Yes. @coveragemap/speed-test is the first of more open source libraries to come. This page will grow as new packages are released.

Start building

Install the package, read the docs, and ship real-world speed testing in your own product. Issues and pull requests are welcome.

Get it on npmStar on GitHub

Want the full story? Read the announcement