uspto-database

Reference Documentation

See references/patentsearch_api.md for complete PatentSearch API documentation including:

Task 2: Retrieving Patent Examination Data

Using PEDS (Patent Examination Data System)

PEDS provides comprehensive prosecution history including transaction events, status changes, and examination timeline.

Installation

uv pip install uspto-opendata-python

Basic PEDS Usage

Get application data:

from scripts.peds_client import PEDSHelper
helper = PEDSHelper()
By application number

app_data = helper.get_application("16123456")
print(f"Title: {app_data['title']}")
print(f"Status: {app_data['app_status']}")
By patent number

patent_data = helper.get_patent("11234567")

Get transaction history:

transactions = helper.get_transaction_history("16123456")
for trans in transactions:
    print(f"{trans['date']}: {trans['code']} - {trans['description']}")

Get office actions:

office_actions = helper.get_office_actions("16123456")
for oa in office_actions:
    if oa['code'] == 'CTNF':
        print(f"Non-final rejection: {oa['date']}")
    elif oa['code'] == 'CTFR':
        print(f"Final rejection: {oa['date']}")
    elif oa['code'] == 'NOA':
        print(f"Notice of allowance: {oa['date']}")

Get status summary:

summary = helper.get_status_summary("16123456")
print(f"Current status: {summary['current_status']}")
print(f"Filing date: {summary['filing_date']}")
print(f"Pendency: {summary['pendency_days']} days")
if summary['is_patented']:
    print(f"Patent number: {summary['patent_number']}")
    print(f"Issue date: {summary['issue_date']}")

Prosecution Analysis

Analyze prosecution patterns:

analysis = helper.analyze_prosecution("16123456")
print(f"Total office actions: {analysis['total_office_actions']}")
print(f"Non-final rejections: {analysis['non_final_rejections']}")
print(f"Final rejections: {analysis['final_rejections']}")
print(f"Allowed: {analysis['allowance']}")
print(f"Responses filed: {analysis['responses']}")

Common Transaction Codes

Reference Documentation

See references/peds_api.md for complete PEDS documentation including:

Task 3: Searching and Monitoring Trademarks

Using TSDR (Trademark Status & Document Retrieval)

Access trademark status, ownership, and prosecution history.

Basic Trademark Usage

Get trademark by serial number:

from scripts.trademark_client import TrademarkClient
client = TrademarkClient()
By serial number

tm_data = client.get_trademark_by_serial("87654321")
By registration number

tm_data = client.get_trademark_by_registration("5678901")

Get trademark status:

status = client.get_trademark_status("87654321")
print(f"Mark: {status['mark_text']}")
print(f"Status: {status['status']}")
print(f"Filing date: {status['filing_date']}")
if status['is_registered']:
    print(f"Registration #: {status['registration_number']}")
    print(f"Registration date: {status['registration_date']}")

Check trademark health:

health = client.check_trademark_health("87654321")
print(f"Mark: {health['mark']}")
print(f"Status: {health['status']}")
for alert in health['alerts']:
    print(alert)
if health['needs_attention']:
    print("⚠️  This mark needs attention!")

Trademark Portfolio Monitoring

Monitor multiple trademarks:

def monitor_portfolio(serial_numbers, api_key):
    """Monitor trademark portfolio health."""
    client = TrademarkClient(api_key)
    results = {
        'active': [],
        'pending': [],
        'problems': []
    }
    for sn in serial_numbers:
        health = client.check_trademark_health(sn)
        if 'REGISTERED' in health['status']:
            results['active'].append(health)
        elif 'PENDING' in health['status'] or 'PUBLISHED' in health['status']:
            results['pending'].append(health)
        elif health['needs_attention']:
            results['problems'].append(health)
    return results

Common Trademark Statuses

Reference Documentation

See references/trademark_api.md for complete trademark API documentation including:

Task 4: Tracking Assignments and Ownership

Patent and Trademark Assignments

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:

import requests
import xml.etree.ElementTree as ET
def get_patent_assignments(patent_number, api_key):
    url = f"https://assignment-api.uspto.gov/patent/v1.4/assignment/patent/{patent_number}"
    headers = {"X-Api-Key": api_key}
    response = requests.get(url, headers=headers)
    if response.status_code == 200:
        return response.text  # Returns XML
assignments_xml = get_patent_assignments("11234567", api_key)
root = ET.fromstring(assignments_xml)
for assignment in root.findall('.//assignment'):
    recorded_date = assignment.find('recordedDate').text
    assignor = assignment.find('.//assignor/name').text
    assignee = assignment.find('.//assignee/name').text
    conveyance = assignment.find('conveyanceText').text
    print(f"{recorded_date}: {assignor} → {assignee}")
    print(f"  Type: {conveyance}\n")

Search by company name:

def find_company_patents(company_name, api_key):
    url = "https://assignment-api.uspto.gov/patent/v1.4/assignment/search"
    headers = {"X-Api-Key": api_key}
    data = {"criteria": {"assigneeName": company_name}}
    response = requests.post(url, headers=headers, json=data)
    return response.text

Common Assignment Types

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:

Patent Litigation Cases API

Access federal district court patent litigation records:

PTAB API

Patent Trial and Appeal Board proceedings:

Reference Documentation

See references/additional_apis.md for comprehensive documentation on:

Complete Analysis Example

Comprehensive Patent Analysis

Combine multiple APIs for complete patent intelligence:

def comprehensive_patent_analysis(patent_number, api_key):
    """
    Full patent analysis using multiple USPTO APIs.
    """
    from scripts.patent_search import PatentSearchClient
    from scripts.peds_client import PEDSHelper
    results = {}
    # 1. Get patent details
    patent_client = PatentSearchClient(api_key)
    patent_data = patent_client.get_patent(patent_number)
    results['patent'] = patent_data
    # 2. Get examination history
    peds = PEDSHelper()
    results['prosecution'] = peds.analyze_prosecution(patent_number)
    results['status'] = peds.get_status_summary(patent_number)
    # 3. Get assignment history
    import requests
    assign_url = f"https://assignment-api.uspto.gov/patent/v1.4/assignment/patent/{patent_number}"
    assign_resp = requests.get(assign_url, headers={"X-Api-Key": api_key})
    results['assignments'] = assign_resp.text if assign_resp.status_code == 200 else None
    # 4. Analyze results
    print(f"\n=== Patent {patent_number} Analysis ===\n")
    print(f"Title: {patent_data['patent_title']}")
    print(f"Assignee: {', '.join(patent_data.get('assignee_organization', []))}")
    print(f"Issue Date: {patent_data['patent_date']}")
    print(f"\nProsecution:")
    print(f"  Office Actions: {results['prosecution']['total_office_actions']}")
    print(f"  Rejections: {results['prosecution']['non_final_rejections']} non-final, {results['prosecution']['final_rejections']} final")
    print(f"  Pendency: {results['prosecution']['pendency_days']} days")
    # Analyze citations
    if 'cited_patent_number' in patent_data:
        print(f"\nCitations:")
        print(f"  Cites: {len(patent_data['cited_patent_number'])} patents")
    if 'citedby_patent_number' in patent_data:
        print(f"  Cited by: {len(patent_data['citedby_patent_number'])} patents")
    return results

Best Practices