Enriched Citations Client

clients.enriched_citations - Client for USPTO Enriched Citations API.

This module provides a client for interacting with the USPTO Enriched Cited Reference Metadata API (v3). It allows users to search for enriched citation data extracted from patent office actions using AI/NLP algorithms.

class pyUSPTO.clients.enriched_citations.EnrichedCitationsClient(config=None, base_url=None)[source]

Bases: BaseUSPTOClient[EnrichedCitationResponse]

Client for interacting with the USPTO Enriched Citations API.

This client provides methods to search for enriched citation data from office actions mailed from October 1, 2017 to 30 days prior to the current date. The data is extracted using AI/NLP algorithms and includes bibliographic information, rejected claims, and passage locations from cited prior art.

ENDPOINTS = {'get_fields': 'api/v1/patent/oa/enriched_cited_reference_metadata/v3/fields', 'search_citations': 'api/v1/patent/oa/enriched_cited_reference_metadata/v3/records'}
__init__(config=None, base_url=None)[source]

Initialize the EnrichedCitationsClient.

Parameters:

  • config (USPTOConfig | None) – USPTOConfig instance containing API key and settings. If not provided, creates config from environment variables (requires USPTO_API_KEY).

  • base_url (str | None) – Optional base URL override for the USPTO Enriched Citations API. If not provided, uses config.enriched_citations_base_url or default.

get_fields()[source]

Retrieve available fields and API metadata for the Enriched Citations API.

Returns:

API metadata including available field

names and last data update timestamp.

Return type:

EnrichedCitationFieldsResponse

Examples

>>> fields_response = client.get_fields()
>>> print(fields_response.fields)
['officeActionDate', 'relatedClaimNumberText', ...]
>>> print(fields_response.last_data_updated_date)
'2024-07-11 11:33:41.0'
paginate_citations(post_body=None, **kwargs)[source]

Provide an iterator to paginate through enriched citation search results.

This method simplifies fetching all enriched citations matching a search query by automatically handling pagination.

The start parameter is managed by the pagination logic; setting it directly in kwargs or post_body will raise a ValueError.

Parameters:

  • post_body (dict[str, Any] | None) – Optional POST body for complex search queries.

  • **kwargs (Any) – Keyword arguments passed to search_citations.

Returns:

An iterator yielding EnrichedCitation objects.

Return type:

Iterator[EnrichedCitation]

Examples

# Paginate through all citations for a tech center >>> for citation in client.paginate_citations(tech_center_q=”2800”): … print(f”{citation.patent_application_number}: {citation.citation_category_code}”)

# Paginate with POST body >>> for citation in client.paginate_citations( … post_body={“q”: “techCenter:2800”, “rows”: 50} … ): … process_citation(citation)

search_citations(query=None, sort=None, start=0, rows=25, post_body=None, patent_application_number_q=None, cited_document_identifier_q=None, office_action_category_q=None, citation_category_code_q=None, tech_center_q=None, group_art_unit_number_q=None, examiner_cited_q=None, office_action_date_from_q=None, office_action_date_to_q=None, additional_query_params=None)[source]

Return enriched citations matching the given criteria.

This method performs a POST request to search for enriched citation records. You can provide either a direct post_body, a query string, or use convenience parameters that will be automatically combined into a query.

Parameters:

  • query (str | None) – Direct query string in USPTO search syntax.

  • sort (str | None) – Sort order for results.

  • start (int | None) – Starting index for pagination.

  • rows (int | None) – Maximum number of records to return.

  • post_body (dict[str, Any] | None) – Optional POST body for complex queries. When provided, all other parameters are ignored.

  • patent_application_number_q (str | None) – Filter by patent application number.

  • cited_document_identifier_q (str | None) – Filter by cited document identifier.

  • office_action_category_q (str | None) – Filter by office action category (e.g., “CTNF”).

  • citation_category_code_q (str | None) – Filter by citation category code (e.g., “X”, “Y”).

  • tech_center_q (str | None) – Filter by technology center code.

  • group_art_unit_number_q (str | None) – Filter by group art unit number.

  • examiner_cited_q (bool | None) – Filter by whether the examiner cited the reference.

  • office_action_date_from_q (str | None) – Filter from this date (YYYY-MM-DD).

  • office_action_date_to_q (str | None) – Filter to this date (YYYY-MM-DD).

  • additional_query_params (dict[str, Any] | None) – Additional custom query parameters.

Returns:

Response containing matching enriched citations.

Return type:

EnrichedCitationResponse

Examples

# Search with direct query >>> response = client.search_citations( … query=”patentApplicationNumber:15739603” … )

# Search with convenience parameters >>> response = client.search_citations( … tech_center_q=”2800”, … citation_category_code_q=”X”, … rows=50, … )

# Search with POST body >>> response = client.search_citations( … post_body={“q”: “techCenter:2800”, “rows”: 100} … )