# Alterlab Uspto

> Access USPTO APIs for patent and trademark searches, examination history (PEDS), assignments, citations, office actions, and trademark status (TSDR). Use when searching patents or trademarks, conducting prior art searches, retrieving patent examination or assignment records, or doing intellectual property (IP) analysis. Part of the AlterLab Academic Skills suite.

- Skill: `alterlab-ieu/alterlab-uspto` (Agent Skill, multi-file: 10 files)
- Install (CLI): `npx skillmds@latest add alterlab-ieu/alterlab-uspto`
- Raw SKILL.md: https://api.skillmd.com/api/skills/alterlab-ieu/alterlab-uspto/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: AlterLab-IEU (https://skillmd.com/u/alterlab-ieu)
- Updated: 2026-08-19
- Page: https://skillmd.com/skills/alterlab-ieu/alterlab-uspto

---


# USPTO Database

## Overview

USPTO provides specialized APIs for patent and trademark data. Search patents by keywords/inventors/assignees, retrieve examination history via PEDS, track assignments, analyze citations and office actions, access TSDR for trademarks, for IP analysis and prior art searches.

## When to Use This Skill

This skill should be used when:

- **Patent Search**: Finding patents by keywords, inventors, assignees, classifications, or dates
- **Patent Details**: Retrieving full patent data including claims, abstracts, citations
- **Trademark Search**: Looking up trademarks by serial or registration number
- **Trademark Status**: Checking trademark status, ownership, and prosecution history
- **Examination History**: Accessing patent prosecution data from PEDS (Patent Examination Data System)
- **Office Actions**: Retrieving office action text, citations, and rejections
- **Assignments**: Tracking patent/trademark ownership transfers
- **Citations**: Analyzing patent citations (forward and backward)
- **Litigation**: Accessing patent litigation records
- **Portfolio Analysis**: Analyzing patent/trademark portfolios for companies or inventors

## USPTO API Ecosystem

The USPTO provides multiple specialized APIs for different data needs:

### Core APIs

1. **PatentSearch API** - Modern ElasticSearch-based patent search (replaced legacy PatentsView in May 2025)
   - Search patents by keywords, inventors, assignees, classifications, dates
   - Access to patent data through June 30, 2025
   - 45 requests/minute rate limit
   - **Base URL**: `https://search.patentsview.org/api/v1/`

2. **PEDS (Patent Examination Data System)** - Patent examination history
   - Application status and transaction history from 1981-present
   - Office action dates and examination events
   - Use `uspto-opendata-python` Python library
   - **Replaced**: PAIR Bulk Data (PBD) - decommissioned

3. **TSDR (Trademark Status & Document Retrieval)** - Trademark data
   - Trademark status, ownership, prosecution history
   - Search by serial or registration number
   - **Base URL**: `https://tsdrapi.uspto.gov/ts/cd/`

### Additional APIs

4. **Patent Assignment Search** - Ownership records and transfers
5. **Trademark Assignment Search** - Trademark ownership changes
6. **Enriched Citation API** - Patent citation analysis
7. **Office Action Text Retrieval** - Full text of office actions
8. **Office Action Citations** - Citations from office actions
9. **Office Action Rejection** - Rejection reasons and types
10. **PTAB API** - Patent Trial and Appeal Board proceedings
11. **Patent Litigation Cases** - Federal district court litigation data
12. **Cancer Moonshot Data Set** - Cancer-related patents

## Quick Start

### API Key Registration

USPTO APIs require an API key. Register at:
**https://account.uspto.gov/api-manager/**

API key for **PatentSearch API** is provided by PatentsView. Register at:
**https://patentsview.org/api-v01-information-page**

Set the API key as an environment variable:
```bash
export USPTO_API_KEY="your_api_key_here"
export PATENTSVIEW_API_KEY="your_api_key_here"
```

### Helper Scripts

This skill includes Python scripts for common operations:

- **`scripts/patent_search.py`** - PatentSearch API client for searching patents
- **`scripts/peds_client.py`** - PEDS client for examination history
- **`scripts/trademark_client.py`** - TSDR client for trademark data

## Task 1: Searching Patents

### Using the PatentSearch API

The PatentSearch API uses a JSON query language with various operators
(`_text_all`/`_text_any`/`_text_phrase`, comparison `_gte`/`_lte`, logical
`_and`/`_or`/`_not`). **Best practice**: use `_text_*` operators for text fields
(more performant than `_contains`/`_begins`).

The `scripts/patent_search.py` `PatentSearchClient` wraps the common cases:
search by keywords, inventor, assignee, date range, or CPC classification, plus
`advanced_search(...)` to combine criteria. For full control, POST a JSON query
to `https://search.patentsview.org/api/v1/patent` with an `X-Api-Key` header.

**Available patent endpoints**: `/patent` (granted), `/publication` (pregrant),
`/inventor`, `/assignee`, `/cpc_subclass`, `/cpc_at_issue`, `/uspc`, `/ipc`, and
text endpoints `/claims`, `/brief_summary_text`, `/detail_description_text`
(beta).

See `references/usage_examples.md` (Task 1) for worked client and direct-API
code, and `references/patentsearch_api.md` for the complete endpoint/field
reference, query syntax, response formats, rate limits, and best practices.

## Task 2: Retrieving Patent Examination Data

### Using PEDS (Patent Examination Data System)

PEDS provides comprehensive prosecution history: transaction events, status
changes, and examination timeline. Install the library with
`uv pip install uspto-opendata-python`.

The `scripts/peds_client.py` `PEDSHelper` covers application/patent lookup,
transaction history, office actions, status summary, and `analyze_prosecution`.

**Common transaction codes**: `CTNF` (non-final rejection), `CTFR` (final
rejection), `NOA` (notice of allowance), `WRIT` (response filed), `ISS.FEE`
(issue fee), `ABND` (abandoned), `AOPF` (office action mailed).

See `references/usage_examples.md` (Task 2) for worked code and
`references/peds_api.md` for the full data-field and transaction-code reference,
library usage, and portfolio-analysis examples.

## Task 3: Searching and Monitoring Trademarks

### Using TSDR (Trademark Status & Document Retrieval)

Access trademark status, ownership, and prosecution history. The
`scripts/trademark_client.py` `TrademarkClient` looks up marks by serial or
registration number, fetches status, runs `check_trademark_health`, and supports
portfolio monitoring.

**Common statuses**: `REGISTERED`, `PENDING`, `PUBLISHED FOR OPPOSITION`,
`ABANDONED`, `CANCELLED`, `SUSPENDED`, `REGISTERED AND RENEWED`.

See `references/usage_examples.md` (Task 3) for worked code and
`references/trademark_api.md` for the TSDR + Trademark Assignment Search
references, status codes, prosecution history, and ownership tracking.

## Task 4: Tracking Assignments and Ownership

Both patents and trademarks have Assignment Search APIs for tracking ownership
changes.

**Patent Assignment API base URL**: `https://assignment-api.uspto.gov/patent/v1.4/`
— search by patent number (returns XML) or by company name (`assigneeName`
criteria). Use an `X-Api-Key` header.

**Common assignment types**: `ASSIGNMENT OF ASSIGNORS INTEREST` (ownership
transfer), `SECURITY AGREEMENT`, `MERGER`, `CHANGE OF NAME`, `ASSIGNMENT OF
PARTIAL INTEREST`.

See `references/usage_examples.md` (Task 4) for worked request/XML-parsing code.

## Task 5: Accessing Additional USPTO Data

### Office Actions, Citations, and Litigation

Multiple specialized APIs provide additional patent data.

#### Office Action Text Retrieval

Retrieve full text of office actions using application number. Integrate with PEDS to identify which office actions exist, then retrieve full text.

#### Enriched Citation API

Analyze patent citations:
- Forward citations (patents citing this patent)
- Backward citations (prior art cited)
- Examiner vs. applicant citations
- Citation context

#### Patent Litigation Cases API

Access federal district court patent litigation records:
- 74,623+ litigation records
- Patents asserted
- Parties and venues
- Case outcomes

#### PTAB API

Patent Trial and Appeal Board proceedings:
- Inter partes review (IPR)
- Post-grant review (PGR)
- Appeal decisions

### Reference Documentation

See `references/additional_apis.md` for comprehensive documentation on:
- Enriched Citation API
- Office Action APIs (Text, Citations, Rejections)
- Patent Litigation Cases API
- PTAB API
- Cancer Moonshot Data Set
- OCE Status/Event Codes

## Complete Analysis Example

For full patent intelligence, combine APIs: use PatentSearch for the patent
record, PEDS (`analyze_prosecution` + `get_status_summary`) for examination
history, and the Patent Assignment API for ownership, then merge for citations
and pendency. A complete `comprehensive_patent_analysis(...)` implementation is
in `references/usage_examples.md` (Complete Analysis Example).

## Best Practices

1. **API Key Management**
   - Store API key in environment variables
   - Never commit keys to version control
   - Use same key across all USPTO APIs

2. **Rate Limiting**
   - PatentSearch: 45 requests/minute
   - Implement exponential backoff for rate limit errors
   - Cache responses when possible

3. **Query Optimization**
   - Use `_text_*` operators for text fields (more performant)
   - Request only needed fields to reduce response size
   - Use date ranges to narrow searches

4. **Data Handling**
   - Not all fields populated for all patents/trademarks
   - Handle missing data gracefully
   - Parse dates consistently

5. **Combining APIs**
   - Use PatentSearch for discovery
   - Use PEDS for prosecution details
   - Use Assignment APIs for ownership tracking
   - Combine data for comprehensive analysis

## Important Notes

- **Legacy API Sunset**: PatentsView legacy API discontinued May 1, 2025 - use PatentSearch API
- **PAIR Bulk Data Decommissioned**: Use PEDS instead
- **Data Coverage**: PatentSearch has data through June 30, 2025; PEDS from 1981-present
- **Text Endpoints**: Claims and description endpoints are in beta with ongoing backfilling
- **Rate Limits**: Respect rate limits to avoid service disruptions

## Resources

### API Documentation
- **PatentSearch API (ODP transition guidance)**: https://data.uspto.gov/support/transition-guidance/patentsview — the legacy `search.patentsview.org/docs/` host is being retired as part of the USPTO Open Data Portal (ODP) consolidation; consult this page for the migration path and current endpoint references.
- **USPTO Developer Portal**: https://developer.uspto.gov/
- **USPTO Open Data Portal**: https://data.uspto.gov/
- **API Key Registration**: https://account.uspto.gov/api-manager/

### Python Libraries
- **uspto-opendata-python**: https://pypi.org/project/uspto-opendata-python/
- **USPTO Docs**: https://docs.ip-tools.org/uspto-opendata-python/

### Reference Files
- `references/usage_examples.md` - Worked Python examples per task (search, PEDS, trademarks, assignments, full analysis)
- `references/patentsearch_api.md` - Complete PatentSearch API reference
- `references/peds_api.md` - PEDS API and library documentation
- `references/trademark_api.md` - Trademark APIs (TSDR and Assignment)
- `references/additional_apis.md` - Citations, Office Actions, Litigation, PTAB

### Scripts
- `scripts/patent_search.py` - PatentSearch API client
- `scripts/peds_client.py` - PEDS examination data client
- `scripts/trademark_client.py` - Trademark search client