npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@radsoft/markbase

v2026.11.3

Published

Official Node client for the Markbase USPTO trademark API — search, screen, and look up 14M+ US trademarks.

Readme

@radsoft/markbase

Node client for the Markbase USPTO trademark API — search, screen, and look up 14M+ US trademarks. Fully typed, zero dependencies.

npm i @radsoft/markbase

Covers the USPTO only. If you need EUIPO, WIPO, or UKIPO, a multi-office platform is a better fit — we'd rather say so than waste your time.


30 seconds

No key needed to try it. The keyless tier allows 1,000 requests a month; a free account raises that to 5,000.

import { Markbase } from "@radsoft/markbase";

const mb = new Markbase(); // reads MARKBASE_API_KEY if set

const { highest_risk, matches } = await mb.clearance("nikee", {
  trademarkClass: 25, // clothing
});

console.log(highest_risk);        // "high"
console.log(matches[0].word_mark); // "NIKE"
console.log(matches[0].owner_name);// "Nike, Inc."
console.log(matches[0].similarity);// 0.85

The one thing to get right: classes

Trademark rights are scoped to goods and services, not to names. DELTA coexists as an airline, a faucet maker, and dental insurance — same word, three owners, no conflict.

So screening without a class gives you noise:

await mb.clearance("Delta");                      // ~everything, mostly irrelevant
await mb.clearance("Delta", { trademarkClass: 9 }); // only what could block you

There are 45 classes. Fetch them to build a picker:

const classes = await mb.classes();
// [{ code: "009", title: "Computers & electronics" }, ...]

Common ones: 9 software · 25 clothing · 35 advertising & business · 41 education & entertainment · 42 science & technology services (where most SaaS sits).


Recipes

Screen names from a generator

The usual shape: generate candidates, drop the ones that are obviously taken.

import { Markbase } from "@radsoft/markbase";

const mb = new Markbase();

async function viable(names: string[], trademarkClass: number) {
  const checks = await Promise.all(
    names.map(async (name) => {
      const { highest_risk } = await mb.clearance(name, { trademarkClass });
      return { name, risk: highest_risk };
    })
  );
  return checks.filter((c) => c.risk === "low" || c.risk === "none");
}

await viable(["Zeplo", "Nikee", "Flowmint"], 25);
// [{ name: "Zeplo", risk: "low" }, { name: "Flowmint", risk: "low" }]
// "Nikee" is dropped — high risk against NIKE in class 25

Flag conflicts at checkout

For a registrar or a "claim your brand" flow — warn before they pay.

const { highest_risk, matches } = await mb.clearance(brand, {
  trademarkClass: 42,
  limit: 3,
});

if (highest_risk === "high") {
  return {
    warn: `“${matches[0].word_mark}” is already registered by ${matches[0].owner_name}.`,
    conflicts: matches,
  };
}

Watch a competitor's portfolio

const { hits } = await mb.byOwner("Nike, Inc.", { limit: 50 });

const live = hits.filter((m) => statusOf(m.status_code) === "registered");
console.log(`${live.length} live in this page`);

// note: total_hits saturates at 1000 for large portfolios — page through with
// the `page` option, or use aggregate() if you need a true count

Analyse a whole class

total_hits caps at 1,000, so use aggregate() when you want real numbers.

const { buckets } = await mb.aggregate("class");
// [{ key: "009", count: 1839467 }, { key: "035", count: 1437003 }, ...]

const byCountry = await mb.aggregate("country");
const byYear = await mb.aggregate("year");

Walk a large result set

paginate() handles the page arithmetic and stops when results run out.

for await (const mark of mb.paginate({ q: "coffee", limit: 100 }, 5)) {
  console.log(mark.serial_number, mark.word_mark);
}

In a Next.js route handler

// app/api/check/route.ts
import { Markbase } from "@radsoft/markbase";

const mb = new Markbase({ apiKey: process.env.MARKBASE_API_KEY });

export async function POST(req: Request) {
  const { name, trademarkClass } = await req.json();
  const result = await mb.clearance(name, { trademarkClass });
  return Response.json(result);
}

Keep the key server-side. It's a secret; don't ship it to the browser.


Opt-in phonetic clearance

Starting with SDK 2026.11.2, pass phonetic: true in clearance or clearanceBatch options to add whole-name ASCII phonetic matching. Omit it or use false for spelling-only behavior. One name still uses one monthly request; batches require Launch or Scale.

Read matching.phonetic_status and each match's signals.phonetic separately from similarity and risk, which retain their spelling-based meaning. Names with digits, non-ASCII characters, more than 12 tokens, or no token of at least four letters return not_evaluated and retain spelling results. A changed token must have at least four letters; short tokens must match literally in the same position. matching.truncated reports a phonetic retrieval cap or hydration budget being reached; false does not establish exhaustive coverage.

An unavailable opt-in request returns 503 without silently switching modes. Admission failures do not consume monthly quota. Accepted batches count even if a search fails and are never retried automatically. See the phonetic contract for response evidence, ranking, and limits. Phonetic evidence does not establish legal availability.

Reference

| Method | Returns | |---|---| | search(opts \| string) | SearchResult — typo-tolerant full-text search | | clearance(mark, opts?) | ClearanceResult — ranked conflicts with a risk level | | clearanceBatch(marks, opts?) | ClearanceBatchResult — 1–25 names in input order (Launch or Scale) | | suggest(q, limit?) | Suggestion[] — autocomplete, tuned for as-you-type | | getTrademark(serial) | Trademark — one full record | | getTimeline(serial) | prosecution history | | byOwner(name, opts?) | OwnerResult — an owner's portfolio | | getBatch(serials) | BatchResult — up to 50 at once (Scale plan) | | aggregate(field) | AggregateResult — counts by class/status/country/drawing/year | | classes() | NiceClass[] — all 45 | | info() | IndexInfo — index size and freshness | | paginate(opts, maxPages?) | AsyncGenerator<Trademark> |

Search options

await mb.search({
  q: "acme",                  // typo-tolerant: "gogle" finds Google
  trademarkClass: 9,          // 9, "009", or [9, 42] all work
  statusCode: "800",          // 800 = registered
  ownerCountry: "US",
  ownerState: "CA",
  filingDateFrom: "20200101", // YYYYMMDD
  filingDateTo: "20251231",
  sort: "filing_date:desc",
  page: 1,
  limit: 50,
  facets: true,               // include distribution counts
});

Helpers

USPTO records are raw. These make them presentable:

import { statusOf, parseDate, padClass } from "@radsoft/markbase";

statusOf("800");        // "registered"
statusOf("630");        // "pending" — a new application, not a dead one
statusOf("601");        // "dead"
statusOf("710");        // "cancelled"
parseDate("19720131");  // Date(1972-01-31) — the register stores YYYYMMDD
padClass(9);            // "009"

Errors

Typed, so you can branch on what actually went wrong rather than parsing strings.

import {
  MarkbaseError, AuthError, PlanError, RateLimitError, NotFoundError,
} from "@radsoft/markbase";

try {
  await mb.getBatch(serials);
} catch (err) {
  if (err instanceof PlanError) {
    // endpoint isn't on this plan — batch is Scale-only
  } else if (err instanceof RateLimitError && err.kind === "quota") {
    // month's allowance is gone; err.resetsAt says when it returns
  } else if (err instanceof AuthError) {
    // bad or missing key
  } else if (err instanceof NotFoundError) {
    // no such serial number
  }
}

| Error | When | |---|---| | AuthError | 401 — key missing or invalid | | PlanError | 403 — endpoint not on your plan | | NotFoundError | 404 — no such record | | RateLimitError | 429 — kind is "rate" or "quota" | | MarkbaseError | anything else, including network failures (status: 0) |


Rate limits and quota

Per-minute limits and 5xx are retried automatically with backoff (maxRetries, default 2), except for clearanceBatch().

Bulk clearance accepts 1–25 names, each up to 200 characters, with an optional shared trademarkClass and limit of 1–50 matches per name (default 20). Every submitted name counts toward monthly and per-minute limits, including duplicates. A batch that exceeds the remaining monthly quota is rejected in full. Accepted batches consume their full name count even if a search fails. The SDK never automatically retries bulk requests because that could charge the names again.

Monthly quota exhaustion is not retried — waiting a few seconds can't fix a month-long window, so it throws immediately with resetsAt rather than burning your retries on a call that can't succeed.

Live limits sit on the client after any call:

await mb.search({ q: "nike" });

mb.rateLimit;
// {
//   plan: "launch",
//   rateLimit: 120, rateRemaining: 119,
//   quotaLimit: 50000, quotaRemaining: 49873,
//   quotaResetsAt: Date
// }

Useful for backing off before you hit the wall:

if (mb.rateLimit && mb.rateLimit.quotaRemaining !== null && mb.rateLimit.quotaRemaining < 100) {
  console.warn("Nearly out of quota this month");
}

Options

new Markbase({
  apiKey: process.env.MARKBASE_API_KEY, // null forces the keyless tier
  baseUrl: "https://api.markbase.co",
  timeout: 30_000,                       // ms before abort
  maxRetries: 2,                         // rate limits and 5xx
  fetch: customFetch,                    // inject your own
});

new Markbase("mb_your_key"); // shorthand

apiKey falls back to MARKBASE_API_KEY. Pass null to force keyless even when that variable is set.


TypeScript

Ships with declarations — no @types package needed.

import type {
  Trademark, SearchResult, ClearanceResult, ClearanceMatch,
  MarkStatus, RiskLevel, NiceClass, RateLimitInfo,
} from "@radsoft/markbase";

function render(m: ClearanceMatch): string {
  return `${m.word_mark} — ${m.risk} risk (${m.similarity})`;
}

Not legal advice

Clearance returns a first-pass screening signal over the federal register. It does not cover state trademarks, common-law rights, or the legal analysis of likelihood of confusion — no API does.

Treat a clean result as worth pursuing, not cleared, and put a trademark attorney at the end of the funnel for any name you actually intend to adopt.


Also available

License

MIT — a product of Rad Soft.