# Patent Search API: PatSnap Patents, Legal Status and Families (`nabeelbaghoor/patent-search-legal-status-api`) Actor

Patent search API over 210M+ patents in 170+ jurisdictions: query, assignee, applicant and semantic prior art search, plus patent bibliography, abstracts, CPC and IPC classes, legal status and patent families, through the PatSnap Open Platform API. Bring your own key.

- **URL**: https://apify.com/nabeelbaghoor/patent-search-legal-status-api.md
- **Developed by:** [Nabeel Hassan](https://apify.com/nabeelbaghoor) (community)
- **Categories:** Business, Developer tools, Integrations
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $5.00 / 1,000 patent search results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Patent Search API: PatSnap Patents, Legal Status and Families

Search 210M+ patents from 170+ patent offices by keyword query, company or technical text, and pull bibliographic data, legal status and patent families from PatSnap with your own API key, as clean rows you can export to CSV, Excel or JSON.

PatSnap is a patent and R\&D intelligence company whose database covers USPTO, EPO, WIPO, CNIPA, JPO and every other major patent authority with a daily refresh. This actor wraps the read endpoints of the PatSnap Open Platform API (the self serve developer platform at open.patsnap.com): Analytics query search, current assignee and original applicant search, semantic similar patent search, simple bibliography, simple legal status and patent family. Use it for prior art and novelty searches, freedom to operate screening, competitor patent portfolio tracking, technology landscaping, IP due diligence, patent family mapping and BI pipelines. Bring your own API key.

BYOK, not live tested: every route, parameter and response field comes from PatSnap's own OpenAPI document (open.patsnap.com/openapi.json) and the Open Platform reference pages, and the routes were probed on 2026-11-02 with an invalid key. The actor has not been run against a live key.

### What it does

- **Patent search by query**: full PatSnap Analytics query syntax (such as `TACD: (solid state battery)` or `ANCS: (Apple, Inc.) AND TACD: (wireless charging)`), with stemming, family collapse and sorting by relevance, publication, application or issue date.
- **Patents by current assignee**: every patent currently owned by one or up to 100 standardized company names.
- **Patents by original applicant**: every patent originally filed by those companies.
- **Semantic prior art search**: paste an abstract or invention disclosure and get the most similar patents with a relevancy score, filtered by authority and kind code, publication and filing dates, minimum relevancy and legal status.
- **Patent bibliography**: title, abstract, patent type, kind code, application, publication and issue dates, current assignees, applicants, inventors, priority claims, CPC, IPC and Locarno classes, cited patents, cited non patent literature and PCT data.
- **Simple legal status**: active, pending, inactive, undetermined or PCT designated stage for each patent.
- **Patent family**: simple (DOCDB), INPADOC and PatSnap extended family ids, member publication numbers and member counts.
- **Batch lookups**: up to 100 patents per request and 5,000 per run, by publication number or PatSnap patent id.
- **Read only and pay only for results**: empty answers and refused lookups become a free row that says why.

### How to get your own key

1. Sign up at open.patsnap.com. PatSnap gives new developers free trial credits; after that the Open Platform bills per call.
2. Create an API key on the API Keys page of the dashboard.
3. Paste it into the **PatSnap Open Platform API key** field, or set the DATA_API_KEY environment secret. The actor sends it in the documented `Authorization: Bearer` header.
4. Make sure the API packages you need (patent search, basic patent data) are enabled on your account.

### Input

| Field | Modes | Notes |
| --- | --- | --- |
| `mode` | all | `querySearch`, `assigneeSearch`, `applicantSearch`, `semanticSearch`, `bibliography`, `legalStatus`, `family` |
| `apiKey` | all | your API key; falls back to the DATA_API_KEY secret |
| `query` | querySearch | PatSnap Analytics query, up to 3,000 characters |
| `stemming` | querySearch | match plural and tense variants of English keywords |
| `companies` | assigneeSearch, applicantSearch | standardized company names, one per line, up to 100 (joined with OR) |
| `collapseType` | the three list searches | `ALL`, `APNO`, `DOCDB`, `INPADOC`, `EXTEND` |
| `collapseBy`, `collapseOrder` | the three list searches, when collapsing | `PBD`, `APD`, `AUTHORITY`, `SCORE`; `LATEST` or `OLDEST` |
| `sortBy`, `sortOrder` | the three list searches | `SCORE`, `PBDT_YEARMONTHDAY`, `APD_YEARMONTHDAY`, `ISD`; `desc` or `asc` |
| `semanticText` | semanticSearch | a technical text; more than 200 words works best |
| `authorities` | semanticSearch | authority plus kind code, such as `USB`, `EPB`, `CNA` |
| `publishedFrom`, `publishedTo`, `filedFrom`, `filedTo` | semanticSearch | YYYY-MM-DD or YYYYMMDD |
| `minRelevancy` | semanticSearch | 1 to 100 percent |
| `legalStatuses` | semanticSearch | active, pending, inactive, PCT stages, undetermined |
| `patents` | bibliography, legalStatus, family | publication numbers such as `US11205304B2`, or PatSnap patent ids |
| `maxResults` | all | stop after this many rows (default 100, at most 20,000; semantic search returns at most 1,000) |

### Output

A search row:

```json
{
    "mode": "querySearch",
    "recordType": "patent",
    "query": "TACD: virtual reality",
    "found": true,
    "patentNumber": "US11205304B2",
    "patentId": "718ead9c-4f3c-4674-8f5a-24e126827269",
    "title": "Techniques for using multiple symbols to provide feedback for a sidelink transmission",
    "authority": "US",
    "applicationNumber": "US17/521392",
    "applicationDate": "2021-11-08",
    "publicationDate": "2023-08-15",
    "currentAssignee": "QUALCOMM INCORPORATED",
    "originalAssignee": "QUALCOMM INCORPORATED",
    "inventors": ["ELSHAFIE, AHMED", "YANG, WEI", "HOSSEINI, SEYEDKIANOUSH"],
    "relevancy": null,
    "totalResults": 1000
}
```

A bibliography row (shortened):

```json
{
    "mode": "bibliography",
    "recordType": "bibliography",
    "query": "US11205304B2",
    "found": true,
    "patentNumber": "US11205304B2",
    "patentType": "PATENT",
    "title": "Systems and methods for rendering user interfaces for augmented or virtual reality",
    "abstract": "An augmented reality display system comprises a passable world model data...",
    "authority": "US",
    "kindCode": "B2",
    "currentAssignees": ["MAGIC LEAP, INC."],
    "cpcMain": "G06Q40/025",
    "ipcMain": "G06Q40/025",
    "citedPatents": ["CN203027992U"]
}
```

Legal status rows carry `legalStatus` and `legalStatuses`; family rows carry `simpleFamilyId`, `inpadocFamilyId`, `patsnapFamilyId`, the member publication numbers and their counts. The values above are taken from PatSnap's documentation examples and are illustrative.

### Pricing

Pay per event, only for rows with data:

| Event | Price |
| --- | --- |
| Patent search result (query, assignee, applicant or semantic search) | $0.005 |
| Patent bibliography record | $0.015 |
| Patent legal status | $0.005 |
| Patent family record | $0.01 |
| Empty and refused lookups | free |

Your PatSnap Open Platform usage is billed separately by PatSnap in credits. Each search page and each patent in a batch lookup is billed by PatSnap; a small `maxResults` keeps both costs down.

### FAQ

#### What is the PatSnap Open Platform API?

The PatSnap Open Platform is PatSnap's self serve developer platform. Its REST API at connect.patsnap.com exposes PatSnap's patent database (210M+ patents across 174 jurisdictions) for patent search, patent data, legal data, valuation and AI workflows, with usage based pricing.

#### Do I need my own PatSnap API key?

Yes. This actor is bring your own key: your API key, your PatSnap credits and your plan. A run without a key ends cleanly with a message and makes no API call.

#### How do I write a PatSnap Analytics query?

Use field codes such as `TACD:` (title, abstract, claims, description), `ANCS:` (standardized current assignee) and `ANS:` (standardized original applicant), combined with AND, OR and NOT. PatSnap documents the full syntax at analytics.patsnap.com/search_helper.

#### What is the difference between the assignee and applicant searches?

The current assignee search finds patents a company owns today, including ones it acquired. The original applicant search finds patents the company filed itself, including ones it has since sold.

#### Can I do prior art or novelty searches?

Yes. The semantic search mode compares your technical text to the patent database and returns the most similar patents with a relevancy percentage, up to 1,000 per search. It is a search aid, not a legal opinion.

#### Which legal status values come back?

PatSnap's simple legal status: Active, Pending, Inactive, Undetermined, PCT designated period and PCT designated expiration.

#### Why did my run stop with "not on your plan"?

The Open Platform enables APIs by package. If your account does not include the search or patent data API a mode calls, PatSnap refuses it and the run ends cleanly, naming the API.

#### What do I pay?

$0.005 per search result or legal status, $0.01 per family record and $0.015 per bibliography record. Empty and refused lookups are free.

### Keyword map

patent search API, patent data API, prior art search, semantic patent search, patent legal status, patent family, INPADOC family, patent bibliography, CPC and IPC classification, assignee patent portfolio, PatSnap, PatSnap Open Platform, Eureka, freedom to operate, patent landscape, USPTO EPO WIPO CNIPA patents.

### Routes and verification

| Mode | Route | Probe with invalid key (twice) |
| --- | --- | --- |
| Patent search by query | POST /search/patent/query-search-patent/v2 | HTTP 200 JSON status false, 67200202 apikey auth error |
| Current assignee search | POST /search/patent/current-search-patent/v2 | from the OpenAPI document |
| Original applicant search | POST /search/patent/company-search-patent/v2 | from the OpenAPI document |
| Semantic search | POST /search/patent/semantic-search-patent/v2 | from the OpenAPI document |
| Bibliography | GET /basic-patent-data/simple-bibliography | HTTP 200 JSON status false, 67200202 apikey auth error |
| Legal status | GET /basic-patent-data/simple-legal-status | from the OpenAPI document |
| Patent family | GET /basic-patent-data/patent-family | from the OpenAPI document |
| Invented control routes | GET /basic-patent-data/simple-bibliography-invented-xyz; GET /nonexistent-root-xyz | 67200202 inside a real service prefix; HTTP 404 67200101 Path Not Found at the root |

The gateway checks the key before it routes inside a service prefix, so an invalid key cannot tell a real leaf path from an invented one; every leaf path here is copied from the OpenAPI document. The key goes in the documented `Authorization: Bearer` header, never in a URL or a log line.

### Licensing and data use

This actor works only with your own PatSnap Open Platform API key, and your agreement with PatSnap applies. For self serve Open Platform accounts that is the Patsnap Eureka Terms of Service (eureka.patsnap.com/terms-of-service), which the Open Platform links as its terms; enterprise customers are governed by their own contract with PatSnap. Those terms license API responses and other outputs for your internal or personal purposes only. You must not resell, sublicense, redistribute, republish, publish at scale, create derivative datasets from or otherwise commercially exploit the data without PatSnap's written permission, and you must keep your API key confidential and within your plan's limits. The terms say that sending outputs to a third party application or integration, such as this actor and its dataset, is at your own risk. Keep the rows for your own research and decisions and do not resell or republish them. This actor is not affiliated with or endorsed by PatSnap.

# Actor input Schema

## `mode` (type: `string`):

Each mode calls one documented read endpoint of the PatSnap Open Platform API. The four searches return patent lists; the three patent data modes read patents you list by number or PatSnap patent id.

## `apiKey` (type: `string`):

Your own API key from the API Keys page of the PatSnap Open Platform dashboard (open.patsnap.com). Sent in the Authorization Bearer header, never in a URL. Leave empty to use the DATA_API_KEY secret.

## `query` (type: `string`):

Patent search by query. A PatSnap Analytics query of up to 3,000 characters, such as TACD: (solid state battery) for title, abstract, claims and description, or ANCS: (Apple, Inc.) AND TACD: (wireless charging). The syntax is described at analytics.patsnap.com/search_helper.

## `stemming` (type: `boolean`):

Patent search by query. Also match singular, plural and tense variants of English keywords (stemming 1). Off matches exact keywords only.

## `companies` (type: `array`):

Current assignee and original applicant searches. One standardized company name per line, such as Apple, Inc. or Huawei Technologies Co., Ltd. Up to 100 names; they are searched together with OR.

## `collapseType` (type: `string`):

Query, assignee and applicant searches. Keep one publication per application or family instead of every publication.

## `collapseBy` (type: `string`):

Query, assignee and applicant searches, when collapsing. The field that picks the one publication kept for each application or family.

## `collapseOrder` (type: `string`):

Query, assignee and applicant searches, when collapsing by publication or application date.

## `sortBy` (type: `string`):

Query, assignee and applicant searches. The order of the results; relevance is the default.

## `sortOrder` (type: `string`):

Query, assignee and applicant searches.

## `semanticText` (type: `string`):

Semantic search. A technical description, abstract or invention disclosure; PatSnap recommends more than 200 words. Results come back most similar first, at most 1,000.

## `authorities` (type: `array`):

Semantic search. Limit results to authority plus kind code values such as USB (US granted), USA (US applications), EPB, CNA or JPU. Kind codes are A application, B granted, U utility model, D design. Leave empty for all.

## `publishedFrom` (type: `string`):

Semantic search. Earliest publication date as YYYY-MM-DD or YYYYMMDD.

## `publishedTo` (type: `string`):

Semantic search. Latest publication date as YYYY-MM-DD or YYYYMMDD.

## `filedFrom` (type: `string`):

Semantic search. Earliest application date as YYYY-MM-DD or YYYYMMDD.

## `filedTo` (type: `string`):

Semantic search. Latest application date as YYYY-MM-DD or YYYYMMDD.

## `minRelevancy` (type: `integer`):

Semantic search. Only return patents at least this similar to your text, such as 50 for 50%.

## `legalStatuses` (type: `array`):

Semantic search. Only return patents with these simple legal statuses. Leave empty for all.

## `patents` (type: `array`):

Bibliography, legal status and family modes. One publication number (such as US11205304B2 or EP3456789A1) or PatSnap patent id per line. Read in batches of 100; up to 5,000 per run. Search rows carry both values.

## `maxResults` (type: `integer`):

The run stops after this many rows. Searches can page up to 20,000 results (semantic search 1,000).

## Actor input object example

```json
{
  "mode": "querySearch",
  "query": "TACD: (solid state battery)",
  "stemming": false,
  "collapseType": "ALL",
  "collapseBy": "PBD",
  "collapseOrder": "LATEST",
  "sortBy": "SCORE",
  "sortOrder": "desc",
  "patents": [
    "US11205304B2"
  ],
  "maxResults": 100
}
```

# Actor output Schema

## `records` (type: `string`):

One row per search hit, bibliography, legal status or patent family record the chosen mode read.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "query": "TACD: (solid state battery)",
    "patents": [
        "US11205304B2"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("nabeelbaghoor/patent-search-legal-status-api").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "query": "TACD: (solid state battery)",
    "patents": ["US11205304B2"],
}

# Run the Actor and wait for it to finish
run = client.actor("nabeelbaghoor/patent-search-legal-status-api").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "query": "TACD: (solid state battery)",
  "patents": [
    "US11205304B2"
  ]
}' |
apify call nabeelbaghoor/patent-search-legal-status-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,nabeelbaghoor/patent-search-legal-status-api"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/ef1ckdvzOtMaH8zsJ/builds/SfBGAUH3ZAf0bwfrS/openapi.json