FreePatentsOnline APIfreepatentsonline.com ↗
Search US patents and applications by attorney, agent, or law firm. Retrieve front-page bibliographic data, abstracts, and full claims by document number.
What is the FreePatentsOnline API?
The FreePatentsOnline API exposes 2 endpoints for querying US patent documents. Use search_by_attorney to find all patents and published applications associated with a given attorney, agent, or law firm name, then call get_document_by_attorney_lookup with any returned document number to retrieve title, abstract, full claims text, inventors, assignees, filing date, and patent classifications in a single structured response.
curl -X GET 'https://api.parse.bot/scraper/e1a14cc5-4483-40ec-b2e1-9551f7f48b05/search_by_attorney?attorney_name=Emily+Shu' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace freepatentsonline-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: FreePatentsOnline SDK — search patents by attorney, inspect details."""
from parse_apis.freepatentsonline_com_api import FreePatentsOnline, DocumentNotFound
client = FreePatentsOnline()
# Search patents filed by a specific attorney; limit caps total items fetched.
for doc in client.documents.search(attorney_name="Emily Shu", limit=5):
print(doc.title, doc.document_type, doc.publication_date)
# Drill down: take one result, then refresh to confirm full detail access.
result = client.documents.search(attorney_name="Emily Shu", limit=1).first()
if result is not None:
refreshed = result.refresh()
print(refreshed.full_document_id, refreshed.attorney_agent_or_firm)
for cls in refreshed.classifications:
print(cls.scheme, cls.codes)
# Point lookup by a document number discovered from the search above.
if result is not None:
detail = client.documents.get(document_number=result.document_number)
print(detail.title, "Filed:", detail.filing_date)
print("Assignee:", detail.assignee)
# Error handling: unknown document number raises DocumentNotFound.
try:
client.documents.get(document_number="99999999")
except DocumentNotFound:
print("Document not found")
print("exercised: documents.search / Document.refresh / documents.get / DocumentNotFound")
Searches US patents and published US patent applications whose 'Attorney, Agent or Firm' front-page field matches the given attorney, agent or law firm name, using the site's field-restricted expert search. One result row per document: the site's result list is paged and every returned hit is enriched by opening its document page, so each call costs one or two result-page requests plus one request per returned document (limit is capped at 20). Results are in the site's relevance order. total is the site's total match count; start/limit tile the full result set as a true offset and has_more tells whether more hits exist beyond start+returned. By default the name is matched as an exact phrase; with exact_phrase=false every word must appear in the attorney field (broader, surname-only search). Documents whose page could not be opened are listed in failed_documents rather than silently dropped. The site does not print inventors, attorney registration numbers, examiner names on most documents or legal status, so inventors is usually an empty array, primary_examiner is usually null, kind_code is only printed for published applications (A1) and document_type distinguishes granted patents from published applications. attorney_agent_or_firm is the single line the site prints (an individual attorney or a firm) and is not split into person and firm. A search with no matches returns total 0 and an empty results array.
| Param | Type | Description |
|---|---|---|
| limit | integer | Number of documents to return and enrich, 1-20 (values above 20 are clamped to 20). |
| start | integer | Zero-based offset into the site's full match list. |
| exact_phrase | boolean | true matches the whole name as a phrase in the attorney/agent field; false requires every word of the name to appear anywhere in that field (e.g. a surname alone). |
| attorney_namerequired | string | Attorney, agent or law firm name as printed on the document front page (e.g. a full name such as 'Emily Shu', or a firm name). Double quotes are stripped. |
{
"type": "object",
"fields": {
"limit": "integer, effective page size after clamping",
"query": "the field-restricted search expression sent to the site",
"start": "integer, echoed offset",
"total": "integer, site's total number of matching documents",
"results": "array of document records (same shape as get_document_by_attorney_lookup): document_number, full_document_id, document_type (granted_patent|published_application), kind_code (A1 for applications, null for patents), title, application_number, filing_date and publication_date (YYYY-MM-DD), assignee (array of names), inventors (array, empty when the site prints none), attorney_agent_or_firm (string as printed), attorney_agent_block (array of printed lines), primary_examiner (string or null), classifications (array of {scheme, codes}: International Classes = IPC/CPC, Primary Class/Other Classes = US classes), abstract, claims (full text, null on old documents without text), url",
"has_more": "boolean, more matches exist beyond this page",
"returned": "integer, number of documents in results",
"failed_documents": "array of {listing_id, url, reason} for hits whose document page could not be opened"
},
"sample": {
"data": {
"limit": 10,
"query": "AGT/\"Emily Shu\"",
"start": 0,
"total": 5,
"results": [
{
"url": "https://www.freepatentsonline.com/y2025/0106963.html",
"title": "PWM SIGNAL CONVERSION CIRCUIT AND METHOD, AND LED DIMMING SYSTEM",
"claims": "1. A PWM signal conversion circuit, comprising at least: ...",
"abstract": "A PWM signal conversion circuit and method, and an LED dimming system. ...",
"assignee": [
"CRM ICBG (WUXI) CO., LTD."
],
"inventors": [],
"kind_code": "A1",
"filing_date": "2022-07-29",
"document_type": "published_application",
"classifications": [
{
"codes": [
"H05B45/325",
"H05B45/10"
],
"scheme": "International Classes"
}
],
"document_number": "20250106963",
"full_document_id": "US20250106963",
"primary_examiner": null,
"publication_date": "2025-03-27",
"application_number": "18/294551",
"attorney_agent_block": [
"Emily Shu"
],
"attorney_agent_or_firm": "Emily Shu"
}
],
"has_more": false,
"returned": 5,
"failed_documents": []
},
"status": "success"
}
}About the FreePatentsOnline API
Search by Attorney, Agent, or Firm
The search_by_attorney endpoint accepts an attorney_name string and runs a field-restricted query against the attorney/agent/firm front-page field on FreePatentsOnline. The exact_phrase boolean controls whether the name is matched as a complete phrase or as individual words, which matters for common names or firm variants. Results are paginated via start (zero-based offset) and limit (1–20, clamped). Each call returns total (the full match count), returned (documents in this page), has_more to indicate remaining pages, and a results array of document records. Any document page that could not be resolved is reported in failed_documents with the reason.
Document Detail Retrieval
The get_document_by_attorney_lookup endpoint accepts either a US patent number (up to 8 digits) or an 11-digit US publication number and returns the complete front-page record. Response fields include title, abstract, claims (full text or null), inventors, assignee, filing_date (YYYY-MM-DD), kind_code, document_type (granted_patent or published_application), and classifications as an array of {scheme, codes} objects. The attorney_agent_block lines and the joined attorney_agent_or_firm string are returned exactly as printed on the document, making it straightforward to verify firm attribution or compare name variants.
Coverage and Document Types
Both endpoints cover US grants and published US patent applications indexed on FreePatentsOnline. The document_type field in every result distinguishes between the two. Document numbers follow standard USPTO formatting: up to 8 digits for grants, 11 digits (YYYYXXXXXXX) for publications. The search endpoint's query field echoes the exact expression used, so results are auditable against the site's own search syntax.
The FreePatentsOnline API is a managed, monitored endpoint for freepatentsonline.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when freepatentsonline.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official freepatentsonline.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Audit all patent filings represented by a specific law firm using
attorney_nameandtotalto enumerate the full docket. - Retrieve full claims text for a set of competitor patents identified by their document numbers.
- Track published applications associated with an individual patent attorney over time using
filing_datefrom document records. - Cross-reference assignee and attorney fields to map which firms represent which companies in a technology space.
- Extract CPC or IPC classifications from
classificationsto categorize a firm's patent portfolio by technology area. - Compare
attorney_agent_blockline variants across documents to normalize law firm name spelling in a dataset. - Build a prior-art lookup tool that searches by attorney and returns abstracts for a quick relevance scan.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does FreePatentsOnline have an official developer API?+
What does `search_by_attorney` return beyond a list of document numbers?+
results array is a full document record with the same shape as get_document_by_attorney_lookup: title, abstract, claims, inventors, assignees, filing date, kind code, document type, classifications, and the attorney/agent block. You do not need a separate call for each document when using the search endpoint.How does pagination work and are there limits on result size?+
start (zero-based) and limit (1–20, values above 20 are clamped to 20) to page through results. The total field gives the full match count and has_more confirms whether additional pages exist. To retrieve more than 20 documents in one logical query, make successive calls incrementing start by the effective limit.Does the API cover international patents or PCT applications?+
Can I search by inventor name, assignee, or keyword rather than attorney?+
get_document_by_attorney_lookup endpoint does return inventor and assignee data once you have a document number. You can fork this API on Parse and revise it to add endpoints for inventor-name or assignee-based search.