1. Basic search
Search is one GET request. Typos are handled — “gogle” still finds Google's marks:
curl "https://api.markbase.co/search?q=gogle"In JavaScript:
const res = await fetch("https://api.markbase.co/search?q=gogle");
const { hits, total_hits, processing_time_ms } = await res.json();And Python:
import requests
data = requests.get(
"https://api.markbase.co/search",
params={"q": "gogle"},
).json()
for mark in data["hits"]:
print(mark["serial_number"], mark["word_mark"], mark["status_code"])2. Filter by status and class
Filter by a specific USPTO status code and international class. Code 800 is one registered status; it does not include every live mark. Consider pending applications and other relevant statuses when screening a name:
curl "https://api.markbase.co/search?q=acme&status_code=800&international_code=9"Class 9 is software and electronics; GET /classes lists all 45 with descriptions if you need a picker in your UI. Date ranges (filing_date_from), owner country and state, sorting, facet counts, and CSV export are all query params on the same endpoint.
3. Autocomplete
/suggest is tuned for as-you-type latency — wire it straight to a search box:
curl "https://api.markbase.co/suggest?q=nik"4. Full records, timelines, and batches
Once you have a serial number, pull the complete record:
curl "https://api.markbase.co/trademark/72414177"Its prosecution history as events:
curl "https://api.markbase.co/trademark/72414177/timeline"On the Scale plan, fetch up to 50 records in one request using your API key:
curl -X POST "https://api.markbase.co/trademark/batch" \
-H "Content-Type: application/json" \
-H "X-API-Key: $MARKBASE_API_KEY" \
-d '{"serial_numbers": ["72414177", "73302505"]}'5. Owner portfolios and aggregates
Every mark an owner holds:
curl "https://api.markbase.co/owner?name=Nike"/aggregate returns distributions across status codes, classes, and owner countries for any query — useful for dashboards and market analysis without paginating through everything.
6. Node SDK
There's an official Node client, so you don't have to hand-roll query strings or status-code parsing:
npm i @radsoft/markbaseimport { Markbase, statusOf } from "@radsoft/markbase";
const mb = new Markbase({ apiKey: process.env.MARKBASE_API_KEY });
const { highest_risk, matches } = await mb.clearance("Acme", {
trademarkClass: 9,
});
for (const m of matches) {
console.log(m.word_mark, statusOf(m.status_code), m.similarity);
}It's fully typed, retries rate limits for you, and exposes your remaining quota on mb.rateLimit. There's also an MCP server if you want an AI assistant screening names against the register directly.
7. Python SDK
Install Markbase for Python 3.11 or newer. This command installs the versioned wheel and verifies its SHA-256 checksum.
python -m pip install \
"https://cdn.aws.radsoft.tech/markbase/python/2026.11.1/radsoft_markbase-2026.11.1-py3-none-any.whl#sha256=7359fceec86b264550c9c99cb03bf1e7ba209b1e37ce8573ba87bd5ed34da3a1"Set MARKBASE_API_KEY in your server environment or use the keyless tier. The client reads the key from the environment.
from markbase import Markbase
with Markbase() as client:
for mark in client.paginate("Acme", trademark_class=9, max_pages=2):
print(mark["serial_number"], mark["word_mark"])
result = client.clearance("Acme", trademark_class=9)
print(result["highest_risk"])Catch MarkbaseError for API or connection failures. Read the latest plan and quota from client.rate_limit.
On Launch or Scale, client.clearance_batch(marks) screens up to 25 proposed names in input order. Each admitted name counts toward quota, including duplicates. The SDK sends a batch once, even when its response is lost. Check usage before resubmitting.
8. Watch your limits
Every response tells you where you stand:
X-RateLimit-Remaining: 29
X-Quota-Limit: 1000
X-Quota-Remaining: 993
X-Quota-Reset: 2026-08-01T00:00:00.000Z
X-Plan: openKeyless is 1,000 requests/month with 10 results per search; a free account gets 5,000 and 25 results; Launch and Scale raise that to 50k/1M requests and 100/1,000 results. Rate-limit responses come back as HTTP 429 — back off and retry after the window resets.
That's the whole integration
One base URL, JSON in and out, and an OpenAPI spec if you'd rather generate a typed client.
curl "https://api.markbase.co/search?q=your-brand"Frequently asked questions
Do I need an API key to follow this tutorial?
The search, lookup, autocomplete, and aggregate requests work without a key, within the open tier limits. A free account provides 5,000 monthly requests. Batch lookups require a Scale API key.
How current is the trademark data?
Imports run daily using USPTO bulk files. Source publication delays or import failures can delay some records; check the status page for freshness and known source-file delays.
Is there an OpenAPI spec?
Yes — api.markbase.co/openapi.json, with interactive docs at api.markbase.co/docs. You can generate a typed client for any language from the spec.