Pinakel · Trademark Analytics API · v1

Integrator Guide

Aggregate trademark analytics — filing trends, Nice-class distribution, owner and representative leaderboards — computed over our worldwide corpus and served as JSON, so you can build your own dashboards without running a warehouse. Base URL:

https://api.pinakelai.com/analytics

Interactive OpenAPI reference: https://api.pinakelai.com/analytics/docs · machine-readable spec: /openapi.json

Also on this host: /data — per-record trademark search, lookup and change tracking, sold and keyed separately.

Authentication

Every request carries your API key in the X-API-Key header (or as a Bearer token). Keys are scoped per product: a key sold for analytics returns 403 product_not_enabled on the record API, and vice versa. That is a provisioning state, not a bad credential — do not rotate the key; ask us to enable the product.

curl -H "X-API-Key: pk_live_…" \
  "https://api.pinakelai.com/analytics/v1/kpis?jurisdiction=US"

Coverage: read this before you render a number

The corpus is being loaded register by register. Every response carries a coverage block describing exactly what the figures in it were computed over:

{
  "kpis": { … },
  "coverage": {
    "jurisdiction": "US",
    "rows_loaded": 200000,
    "backfill_status": "in_progress",
    "is_sample": true,
    "last_ingested_date": "2026-09-14"
  }
}

Live from the warehouse — 119 registers, 4,514,223 records, 119 still sampling. This table is generated per-request and never overstates.

Pagination

List endpoints return {"items": […], "next_cursor": "…"|null, "has_more": true|false}. Pass next_cursor back as cursor for the next page; null means you have reached the end. Cursors are bound to the exact query that produced them, so changing a filter mid-pagination is refused rather than silently mixing result sets — start a new scan instead.

There is deliberately no total-row count. Use has_more to drive "next page", and /v1/search/facets when you need counts: it reports exact totals per status, jurisdiction, year, class and owner for the same filters.

Aggregate endpoints

These take an optional jurisdiction (a 2–4 letter register code, e.g. US); omit it for every register combined. Leaderboards take limit (1–500). Responses are an envelope: {"items": […], "coverage": {…}}.

GET/v1/jurisdictions

Every register we hold analytics for, with counts and year range. The machine-readable coverage table — poll it to discover what is available as the corpus loads.

GET/v1/kpis

Headline totals for a register or the whole corpus: records, live vs dead, distinct owners, registration rate.

GET/v1/filings-by-year

Filing volume per year, split live vs dead. Optional year_from / year_to (1800–2100).

GET/v1/nice-classes

Distribution of filings across the 45 Nice classes.

GET/v1/top-owners

Largest filers by volume, with their live ratio. limit defaults to 50.

GET/v1/law-firms

Representative leaderboard: volume, success rate, median days to registration, distinct clients. limit defaults to 100.

GET/v1/squatting

Owners matching the squatting heuristic — high volume, low registration rate, filings scattered across unrelated classes. A signal to investigate, not a determination.

GET/v1/collateral

Owners with security interests recorded against their marks.

GET/v1/search

Structured search across the corpus. q plus search_in (name, owner, rep, keyword, all), include_translations, and filters for owner_key, nice_class, status, jurisdiction, year_from/year_to. Keyset pagination via cursor.

GET/v1/search/facets

Breakdowns over the same filters as /v1/search: status, jurisdiction, year, Nice class and top owners.

GET/v1/renewals

Upcoming renewal deadlines, soonest first. months_ahead (1–120), owner_key, nice_class, jurisdiction. Served from a pre-built aggregate, so it is far cheaper than the equivalent search.

GET/v1/dead-marks

Marks the register no longer treats as live. Same grammar as /v1/search, filtered to dead.

GET/v1/owners/{owner_key}

One owner's portfolio. ?include=filings_by_year,jurisdictions,status adds breakdowns.

GET/v1/brands/{brand_key}

One brand name across registers and owners. ?include=owners adds the owner list.

GET/v1/usage

Your key's own month-to-date call count, quota and rate limit, broken down per product, so you can watch consumption without asking us.

Errors & limits

Every non-2xx response carries one envelope: {"error": {"code": "…", "message": "…", "param": "…"}} — code is the machine-readable contract, param names the offending parameter when one exists.

A rate-limit 429 carries Retry-After and X-RateLimit-Limit / X-RateLimit-Remaining; a quota 429 carries X-Quota-Limit / X-Quota-Used (resets at month end). Requests refused with 429 are never counted against your usage.

Support

Integration questions: support@pinakelai.com · commercial: hello@pinakelai.com