Skip to content

Add Enriched Citations API Endpoint #130

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
dpieski merged 5 commits into from
Mar 27, 2026
Merged

Add Enriched Citations API Endpoint #130

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
4fedf9f
feat: init enriched citations
dpieski Mar 27, 2026
59fcdbf
fix: improve tests, add form_urlencoded to requests for citations
dpieski Mar 27, 2026
92de568
fix: paginate results for solr endpoints
dpieski Mar 27, 2026
c808946
docs: update docs with new endpoint.
dpieski Mar 27, 2026
b245a59
chore: add examples
dpieski Mar 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions docs/source/api/clients/enriched_citations.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
Enriched Citations Client
=========================

.. automodule:: pyUSPTO.clients.enriched_citations
:members:
:undoc-members:
:show-inheritance:
1 change: 1 addition & 0 deletions docs/source/api/clients/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ Clients
:maxdepth: 2

bulk_data
enriched_citations
patent_data
petition_decisions
ptab_appeals
Expand Down
7 changes: 7 additions & 0 deletions docs/source/api/models/enriched_citations.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
Enriched Citations
==================

.. automodule:: pyUSPTO.models.enriched_citations
:members:
:undoc-members:
:show-inheritance:
1 change: 1 addition & 0 deletions docs/source/api/models/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ Models

base
bulk_data
enriched_citations
patent_data
petition_decisions
ptab
Expand Down
6 changes: 6 additions & 0 deletions docs/source/examples/enriched_citations.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
Enriched Citations Example
==========================

.. literalinclude:: ../../../examples/enriched_citations_example.py
:language: python
:linenos:
1 change: 1 addition & 0 deletions docs/source/examples/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ Examples
:maxdepth: 2

bulk_data
enriched_citations
patent_data
ifw_example
petition_decisions
Expand Down
132 changes: 132 additions & 0 deletions examples/enriched_citations_example.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,132 @@
"""Example usage of pyUSPTO for Enriched Cited Reference Metadata.

Demonstrates the EnrichedCitationsClient for searching citation data
extracted from patent office actions, filtering by various criteria,
and paginating through results.
"""

import os

from pyUSPTO import EnrichedCitationsClient, USPTOConfig

# --- Client Initialization ---
api_key = os.environ.get("USPTO_API_KEY", "YOUR_API_KEY_HERE")
if api_key == "YOUR_API_KEY_HERE":
raise ValueError(
"API key is not set. Set the USPTO_API_KEY environment variable."
)
config = USPTOConfig(api_key=api_key)
client = EnrichedCitationsClient(config=config)

print("-" * 40)
print("Example 1: Search by application number")
print("-" * 40)

response = client.search_citations(patent_application_number_q="15061308")
print(f"Found {response.num_found} citations for application 15061308.")
for citation in response.docs[:5]:
print(f"\n Cited Document: {citation.cited_document_identifier}")
print(f" Category Code: {citation.citation_category_code}")
print(f" Office Action Date: {citation.office_action_date}")
print(f" Office Action Type: {citation.office_action_category}")
if citation.examiner_cited_reference_indicator:
print(" Cited by: Examiner")
if citation.passage_location_text:
print(f" Passages: {citation.passage_location_text}")

print("-" * 40)
print("Example 2: Search by tech center and citation category")
print("-" * 40)

response = client.search_citations(
tech_center_q="2800",
citation_category_code_q="X",
rows=5,
)
print(f"Found {response.num_found} 'X' citations in tech center 2800.")
for citation in response.docs:
print(
f" App {citation.patent_application_number}: "
f"{citation.cited_document_identifier} "
f"(claims: {citation.related_claim_number_text})"
)

print("-" * 40)
print("Example 3: Search by date range")
print("-" * 40)

response = client.search_citations(
office_action_date_from_q="2019-01-01",
office_action_date_to_q="2019-12-31",
rows=5,
)
print(f"Found {response.num_found} citations from 2019.")

print("-" * 40)
print("Example 4: Combined filters")
print("-" * 40)

response = client.search_citations(
tech_center_q="2800",
citation_category_code_q="Y",
examiner_cited_q=True,
rows=5,
)
print(
f"Found {response.num_found} examiner-cited 'Y' citations in tech center 2800."
)
for citation in response.docs:
print(
f" App {citation.patent_application_number}: "
f"{citation.cited_document_identifier} "
f"(art unit: {citation.group_art_unit_number})"
)

print("-" * 40)
print("Example 5: Search with sort")
print("-" * 40)

response = client.search_citations(
tech_center_q="2800",
sort="officeActionDate desc",
rows=5,
)
print(f"Found {response.num_found} citations, sorted by date descending.")
for citation in response.docs:
print(f" {citation.office_action_date}: {citation.cited_document_identifier}")

print("-" * 40)
print("Example 6: Search by cited document identifier")
print("-" * 40)

response = client.search_citations(
cited_document_identifier_q="US 20190165601 A1",
rows=5,
)
print(f"Found {response.num_found} citations of US 20190165601 A1.")

print("-" * 40)
print("Example 7: Paginate through results")
print("-" * 40)

max_items = 30
count = 0
for citation in client.paginate_citations(

Check notice

Code scanning / CodeQL

Unused global variable Note

The global variable 'citation' is not used.

Copilot Autofix

AI 3 days ago

In general, when a loop or global variable is intentionally unused, it should be given a conventional “unused” name (such as _ or a name containing unused) so that both humans and static analysis tools recognize it as deliberate. Otherwise, the unused variable should be removed.

Here, the loop on lines 114–116 iterates over client.paginate_citations(...) but never uses citation. The best fix without changing functionality is to rename the loop variable from citation to _, which signals it is intentionally unused while leaving the logic (incrementing count, enforcing max_items, and breaking) unchanged. No imports or additional definitions are needed, and no other parts of the file reference this particular loop variable, so the change is localized to the for statement in examples/enriched_citations_example.py.

Suggested changeset 1
examples/enriched_citations_example.py

Autofix patch

Autofix patch
Run the following command in your local git repository to apply this patch
cat << 'EOF' | git apply
diff --git a/examples/enriched_citations_example.py b/examples/enriched_citations_example.py
--- a/examples/enriched_citations_example.py
+++ b/examples/enriched_citations_example.py
@@ -111,7 +111,7 @@
 
 max_items = 30
 count = 0
-for citation in client.paginate_citations(
+for _ in client.paginate_citations(
     tech_center_q="2800", rows=10
 ):
     count += 1
EOF
@@ -111,7 +111,7 @@

max_items = 30
count = 0
for citation in client.paginate_citations(
for _ in client.paginate_citations(
tech_center_q="2800", rows=10
):
count += 1
Copilot is powered by AI and may make mistakes. Always verify output.
tech_center_q="2800", rows=10
):
count += 1
if count >= max_items:
print(f" ... (stopping at {max_items} items)")
break

print(f"Retrieved {count} citations via pagination")

print("-" * 40)
print("Example 8: Get available fields")
print("-" * 40)

fields_response = client.get_fields()
print(f"API Status: {fields_response.api_status}")
print(f"Field Count: {fields_response.field_count}")
print(f"Fields: {fields_response.fields}")
print(f"Last Updated: {fields_response.last_data_updated_date}")
17 changes: 15 additions & 2 deletions src/pyUSPTO/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@
pass

from pyUSPTO.clients.bulk_data import BulkDataClient
from pyUSPTO.clients.enriched_citations import EnrichedCitationsClient
from pyUSPTO.clients.patent_data import PatentDataClient
from pyUSPTO.clients.petition_decisions import FinalPetitionDecisionsClient
from pyUSPTO.clients.ptab_appeals import PTABAppealsClient
Expand All @@ -28,14 +29,20 @@
USPTOTimeout,
)
from pyUSPTO.http_config import HTTPConfig

# Import model implementations
from pyUSPTO.models.bulk_data import (
BulkDataProduct,
BulkDataResponse,
FileData,
ProductFileBag,
)

# Import model implementations
from pyUSPTO.models.enriched_citations import (
CitationCategoryCode,
EnrichedCitation,
EnrichedCitationFieldsResponse,
EnrichedCitationResponse,
)
from pyUSPTO.models.patent_data import (
ApplicationContinuityData,
PatentDataResponse,
Expand Down Expand Up @@ -82,6 +89,12 @@
"USPTOTimezoneWarning",
"USPTOEnumParseWarning",
"USPTODataMismatchWarning",
# Enriched Citations API
"EnrichedCitationsClient",
"CitationCategoryCode",
"EnrichedCitation",
"EnrichedCitationResponse",
"EnrichedCitationFieldsResponse",
# Bulk Data API
"BulkDataClient",
"BulkDataResponse",
Expand Down
2 changes: 2 additions & 0 deletions src/pyUSPTO/clients/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@
"""

from pyUSPTO.clients.bulk_data import BulkDataClient
from pyUSPTO.clients.enriched_citations import EnrichedCitationsClient
from pyUSPTO.clients.patent_data import PatentDataClient
from pyUSPTO.clients.petition_decisions import FinalPetitionDecisionsClient
from pyUSPTO.clients.ptab_appeals import PTABAppealsClient
Expand All @@ -12,6 +13,7 @@

__all__ = [
"BulkDataClient",
"EnrichedCitationsClient",
"PatentDataClient",
"FinalPetitionDecisionsClient",
"PTABTrialsClient",
Expand Down
Loading
Loading