/api/v1/patents/yoy-growthPatent YoY Growth
Year-over-year patent growth by CPC code or company (dimension is required). Returns one row per group with oldCount (year_start), newCount (year_end), absolute change and percent change, sorted by growth or percent; percent is a fraction (0.35 = +35%). min_old_count (default 50) hides small groups - narrow with cpc_code / company_id or lower it. Defaults compare 2024 against 2025; pass year_start/year_end for other windows. Company filters accept an exact raw assignee string, 'organizations/<key>', 'ror:<id>' or 'lei:<id>'; unresolved company values and unknown CPC prefixes return HTTP 400 naming the value (never silently dropped). Requires a Pro workspace (returns HTTP 402 otherwise). Use patents.aggregate for plain counts.
When to use it
- which CPC classes are growing fastest
- company patent growth between two years
- emerging vs. declining areas of a portfolio
Getting started
Base URL
https://app.caelrith.com/api/v1/toolsAuthentication
Include your API key in the x-api-key header.
Parameters
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| dimension | string | Yes | Growth dimension (required): 'cpc' groups by CPC code, 'company' groups by company. Allowed values: cpc, company |
| year_start | integer | No | Baseline year (default 2024). oldCount is the patent count in this year. Range: 1900 to 2026 |
| year_end | integer | No | Comparison year (default 2025). newCount is the patent count in this year. Range: 1900 to 2026 |
| cpc_code | string | No | Optional CPC restriction (e.g. 'A61K'). |
| company_id | string | No | Organization to filter on. Accepts an exact raw assignee string (as it appears in a patent's assignees array), 'organizations/<key>', 'ror:<id>', 'lei:<id>', or a bare ROR/LEI id. Takes precedence over company_name. Unresolved values return HTTP 400 (never silently ignored). |
| company_name | string | No | Organization name fallback when company_id is not provided. |
| include_descendants | string | No | When true (default), a cpc_code prefix expands to every code starting with it; set false for exact-code matches only. Allowed values: true, false |
| min_old_count | integer | No | Only include groups with at least this many patents in year_start (default 50). Range: 0 to ∞ |
| limit | integer | No | Maximum number of groups to return (1-100, default 10). Range: 1 to 100 |
| sort | string | No | Sort order (default growth_desc). Allowed values: growth_desc, growth_asc, percent_desc, percent_asc |
Example request
curl -H "x-api-key: YOUR_API_KEY" \ "https://app.caelrith.com/api/v1/patents/yoy-growth?dimension=cpc"
Response envelope
Successful responses wrap the payload in a success flag.
{
"success": true,
"data": { /* payload */ },
"meta": { /* pagination, totals */ }
}Response shape
Payload: data — YoY Growth
Common row fields
| Field | Description |
|---|---|
| cpc_code | CPC |
| company_id | Company |
| oldCount | Old Count |
| newCount | New Count |
| change | Change |
| percent | Percent |
Empty results: No matching rows (HTTP 200)
One row per group: dimension=cpc keys rows on cpc_code, dimension=company keys them on company_id - read whichever id column is present. oldCount/newCount are the patent counts in year_start/year_end; change is the absolute delta; percent is a FRACTION of 1 (0.35 = +35%, negative = decline) - multiply by 100 before presenting as a percentage. The EXACT TOTAL line is the number of growth rows returned, NOT a patent count. min_old_count (default 50) hides small groups. Unresolved company values and unknown CPC prefixes are rejected with HTTP 400 naming the value (never silently dropped); meta.filters.company_id_resolved / company_cluster_size echo the resolved anchor (null / 0 when absent).
Catalog version 0.0.0-generated · generated from the API source