gh-k-dense-ai-claude-scientific-skills-scientific-skills/skills/uspto-database/references/patentsearch_api.md

PatentSearch API Reference

Overview

The PatentSearch API is USPTO's modern ElasticSearch-based patent search system that replaced the legacy PatentsView API in May 2025. It provides access to patent data through June 30, 2025, with regular updates.

Base URL: https://search.patentsview.org/api/v1/

Authentication

All API requests require authentication using an API key in the request header:

X-Api-Key: YOUR_API_KEY

Register for an API key at: https://account.uspto.gov/api-manager/

Rate Limits

• 45 requests per minute per API key
• Exceeding rate limits results in HTTP 429 errors

Available Endpoints

Core Patent & Publication Endpoints

• /patent - General patent data (granted patents)
• /publication - Pregrant publication data
• /publication/rel_app_text - Related application data for publications

Entity Endpoints

• /inventor - Inventor information with location and gender code fields
• /assignee - Assignee details with location identifiers
• /location - Geographic data including latitude/longitude coordinates
• /attorney - Legal representative information

Classification Endpoints

• /cpc_subclass - Cooperative Patent Classification at subclass level
• /cpc_at_issue - CPC classification as of patent issue date
• /uspc - US Patent Classification data
• /wipo - World Intellectual Property Organization classifications
• /ipc - International Patent Classification

Text Data Endpoints (Beta)

• /brief_summary_text - Patent brief summaries (granted and pre-grant)
• /claims - Patent claims text
• /drawing_description_text - Drawing descriptions
• /detail_description_text - Detailed description text

Note: Text endpoints are in beta with data primarily from 2023 onward. Historical backfilling is in progress.

Supporting Endpoints

• /other_reference - Patent reference materials
• /related_document - Cross-references between patents

Query Parameters

All endpoints support four main parameters:

1. Query String (q)

Filters data using JSON query objects. Required parameter.

Query Operators:

• Equality: {"field": "value"} or {"field": {"_eq": "value"}}
• Not equal: {"field": {"_neq": "value"}}
• Comparison: _gt, _gte, _lt, _lte
• String matching:
  • _begins - starts with
  • _contains - substring match
• Full-text search (recommended for text fields):
  • _text_all - all terms must match
  • _text_any - any term matches
  • _text_phrase - exact phrase match
• Logical operators: _and, _or, _not
• Array matching: Use arrays for OR conditions

Examples:

// Simple equality
{"patent_number": "11234567"}

// Date range
{"patent_date": {"_gte": "2020-01-01", "_lte": "2020-12-31"}}

// Text search (preferred for text fields)
{"patent_abstract": {"_text_all": ["machine", "learning"]}}

// Inventor name
{"inventor_name": {"_text_phrase": "John Smith"}}

// Complex query with logical operators
{
  "_and": [
    {"patent_date": {"_gte": "2020-01-01"}},
    {"assignee_organization": {"_text_any": ["Google", "Alphabet"]}}
  ]
}

// Array for OR conditions
{"cpc_subclass_id": ["H04N", "H04L"]}

2. Field List (f)

Specifies which fields to return in the response. Optional - each endpoint has default fields.

Format: JSON array of field names

["patent_number", "patent_title", "patent_date", "inventor_name"]

3. Sorting (s)

Orders results by specified fields. Optional.

Format: JSON array with field name and direction

[{"patent_date": "desc"}]

4. Options (o)

Controls pagination and additional settings. Optional.

Available options:

• page - Page number (default: 1)
• per_page - Records per page (default: 100, max: 1,000)
• pad_patent_id - Pad patent IDs with leading zeros (default: false)
• exclude_withdrawn - Exclude withdrawn patents (default: true)

Format: JSON object

{
  "page": 1,
  "per_page": 500,
  "exclude_withdrawn": false
}

Response Format

All responses follow this structure:

{
  "error": false,
  "count": 100,
  "total_hits": 5432,
  "patents": [...],
  // or "inventors": [...], "assignees": [...], etc.
}

• error - Boolean indicating if an error occurred
• count - Number of records in current response
• total_hits - Total number of matching records
• Endpoint-specific data array (e.g., patents, inventors)

Complete Request Example

Using curl

curl -X POST "https://search.patentsview.org/api/v1/patent" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": {
      "_and": [
        {"patent_date": {"_gte": "2024-01-01"}},
        {"patent_abstract": {"_text_all": ["artificial", "intelligence"]}}
      ]
    },
    "f": ["patent_number", "patent_title", "patent_date", "assignee_organization"],
    "s": [{"patent_date": "desc"}],
    "o": {"per_page": 100}
  }'

Using Python

import requests

url = "https://search.patentsview.org/api/v1/patent"
headers = {
    "X-Api-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {
    "q": {
        "_and": [
            {"patent_date": {"_gte": "2024-01-01"}},
            {"patent_abstract": {"_text_all": ["artificial", "intelligence"]}}
        ]
    },
    "f": ["patent_number", "patent_title", "patent_date", "assignee_organization"],
    "s": [{"patent_date": "desc"}],
    "o": {"per_page": 100}
}

response = requests.post(url, headers=headers, json=data)
results = response.json()

Common Field Names

Patent Endpoint Fields

• patent_number - Patent number
• patent_title - Title of the patent
• patent_date - Grant date
• patent_abstract - Abstract text
• patent_type - Type of patent
• inventor_name - Inventor names (array)
• assignee_organization - Assignee company names (array)
• cpc_subclass_id - CPC classification codes
• uspc_class - US classification codes
• cited_patent_number - Citations to other patents
• citedby_patent_number - Patents citing this patent

Refer to the full field dictionary at: https://search.patentsview.org/docs/

Best Practices

1. Use _text* operators for text fields - More performant than _contains or _begins
2. Request only needed fields - Reduces response size and improves performance
3. Implement pagination - Handle large result sets efficiently
4. Respect rate limits - Implement backoff/retry logic for 429 errors
5. Cache results - Reduce redundant API calls
6. Use date ranges - Narrow searches to improve performance

Error Handling

Common HTTP status codes:

• 200 - Success
• 400 - Bad request (invalid query syntax)
• 401 - Unauthorized (missing or invalid API key)
• 429 - Too many requests (rate limit exceeded)
• 500 - Server error

Recent Updates (February 2025)

• Data updated through December 31, 2024
• New pad_patent_id option for formatting patent IDs
• New exclude_withdrawn option to show withdrawn patents
• Text endpoints continue beta backfilling

Resources

• Official Documentation: https://search.patentsview.org/docs/
• API Key Registration: https://account.uspto.gov/api-manager/
• Legacy API Notice: The old PatentsView API was discontinued May 1, 2025