Clients

clients.bulk_data - Client for USPTO bulk data API

This module provides a client for interacting with the USPTO Open Data Portal (ODP) Bulk Data API. It allows you to search for and download bulk data products.

class pyUSPTO.clients.bulk_data.BulkDataClient(api_key=None, base_url=None, config=None)[source]

Bases: BaseUSPTOClient[BulkDataResponse]

Client for interacting with the USPTO bulk data API.

ENDPOINTS = {'download_file': '{file_download_uri}', 'product_by_id': 'products/{product_id}', 'products_search': 'products/search'}

__init__(api_key=None, base_url=None, config=None)[source]

Initialize the BulkDataClient.

Parameters:

api_key (Optional[str]) – Optional API key for authentication
base_url (Optional[str]) – The base URL of the API, defaults to config.bulk_data_base_url or “https://api.uspto.gov/api/v1/datasets”
config (Optional[USPTOConfig]) – Optional USPTOConfig instance

download_file(file_data, destination)[source]

Download a file from the API.

Parameters:

file_data (FileData) – FileData object containing file information
destination (str) – Directory where the file should be saved

Return type:

str

Returns:

Path to the downloaded file

get_product_by_id(product_id, file_data_from_date=None, file_data_to_date=None, offset=None, limit=None, include_files=None, latest=None)[source]

Get a specific bulk data product by ID.

Parameters:

product_id (str) – The product identifier
file_data_from_date (Optional[str]) – Filter files by data from date (YYYY-MM-DD)
file_data_to_date (Optional[str]) – Filter files by data to date (YYYY-MM-DD)
offset (Optional[int]) – Number of product file records to skip
limit (Optional[int]) – Number of product file records to collect
include_files (Optional[bool]) – Whether to include product files in the response
latest (Optional[bool]) – Whether to return only the latest product file

Return type:

BulkDataProduct

Returns:

BulkDataProduct object containing the product data

get_products(params=None)[source]

Get a list of bulk data products.

This method is deprecated. Use search_products instead.

Parameters:: params (Optional[Dict[str, Any]]) – Optional query parameters
Return type:: BulkDataResponse
Returns:: BulkDataResponse object containing the API response

paginate_products(**kwargs)[source]

Paginate through all products matching the search criteria.

Parameters:: **kwargs (Any) – Keyword arguments to pass to search_products
Yields:: BulkDataProduct objects
Return type:: Iterator[BulkDataProduct]

search_products(query=None, product_title=None, product_description=None, product_short_name=None, from_date=None, to_date=None, categories=None, labels=None, datasets=None, file_types=None, offset=None, limit=None, include_files=None, latest=None, facets=None)[source]

Search for products with various filters.

Parameters:

query (Optional[str]) – Search text
product_title (Optional[str]) – Filter by product title
product_description (Optional[str]) – Filter by product description
product_short_name (Optional[str]) – Filter by product identifier (short name)
from_date (Optional[str]) – Filter products with data from this date (YYYY-MM-DD)
to_date (Optional[str]) – Filter products with data until this date (YYYY-MM-DD)
categories (Optional[List[str]]) – Filter by dataset categories
labels (Optional[List[str]]) – Filter by product labels
datasets (Optional[List[str]]) – Filter by datasets
file_types (Optional[List[str]]) – Filter by file types
offset (Optional[int]) – Number of product records to skip
limit (Optional[int]) – Number of product records to collect
include_files (Optional[bool]) – Whether to include product files in the response
latest (Optional[bool]) – Whether to return only the latest product file for each product
facets (Optional[bool]) – Whether to enable facets in the response

Return type:

BulkDataResponse

Returns:

BulkDataResponse object containing matching products

clients.patent_data - Client for USPTO patent data API

This module provides a client for interacting with the USPTO Patent Data API. It allows you to search for and retrieve patent application data.

class pyUSPTO.clients.patent_data.PatentDataClient(api_key=None, base_url=None, config=None)[source]

Bases: BaseUSPTOClient[PatentDataResponse]

Client for interacting with the USPTO Patent Data API.

ENDPOINTS = {'download_application_document': 'api/v1/download/applications/{application_number}/{document_id}', 'get_application_adjustment': 'api/v1/patent/applications/{application_number}/adjustment', 'get_application_assignment': 'api/v1/patent/applications/{application_number}/assignment', 'get_application_associated_documents': 'api/v1/patent/applications/{application_number}/associated-documents', 'get_application_attorney': 'api/v1/patent/applications/{application_number}/attorney', 'get_application_by_number': 'api/v1/patent/applications/{application_number}', 'get_application_continuity': 'api/v1/patent/applications/{application_number}/continuity', 'get_application_documents': 'api/v1/patent/applications/{application_number}/documents', 'get_application_foreign_priority': 'api/v1/patent/applications/{application_number}/foreign-priority', 'get_application_metadata': 'api/v1/patent/applications/{application_number}/meta-data', 'get_application_transactions': 'api/v1/patent/applications/{application_number}/transactions', 'get_search_results': 'api/v1/patent/applications/search/download', 'search_applications': 'api/v1/patent/applications/search', 'status_codes': 'api/v1/patent/status-codes'}

download_archive(printed_metadata, file_name=None, destination_path=None, overwrite=False)[source]

Downloads Printed Metadata (XML data). These are XML files of the patent as printed.

Note

See also download_publication() for a clearer method name with identical functionality.

Parameters:

printed_metadata (PrintedMetaData) – ArchiveMetaData object containing download URL and metadata
file_name (Optional[str]) – Optional filename. If not provided, uses xml_file_name from metadata
destination_path (Optional[str]) – Optional directory path to save the file
overwrite (bool) – Whether to overwrite existing files. Default False

Returns:

Path to the downloaded file

Return type:

str

Raises:

ValueError – If printed_metadata has no download URL
FileExistsError – If file exists and overwrite=False

download_document(document_format, file_name=None, destination_path=None, overwrite=False, stream=True)[source]

Downloads a document in the specified format.

Parameters:

document_format (DocumentFormat) – DocumentFormat object containing download URL and metadata
file_name (Optional[str]) – Optional filename. If not provided, extracted from URL
destination_path (Optional[str]) – Optional path - can be a directory OR a complete file path
overwrite (bool) – Whether to overwrite existing files. Default False
stream (bool) – Whether to stream the download. Default True for large files

Returns:

Path to the downloaded file

Return type:

str

Raises:

ValueError – If document_format has no download URL
FileExistsError – If file exists and overwrite=False

download_publication(printed_metadata, file_name=None, destination_path=None, overwrite=False)[source]

Download a publication XML file (grant or pre-grant publication).

This method downloads publication XML files from PrintedMetaData objects, such as grant documents or pre-grant publications (pgpub). The filename is automatically extracted from the metadata if not provided.

Parameters:

printed_metadata (PrintedMetaData) – PrintedMetaData object containing the publication download URL and filename information. Typically obtained from get_application_associated_documents() or from PatentFileWrapper’s grant_document_meta_data or pg_publication_document_meta_data.
file_name (Optional[str]) – Optional custom filename. If not provided, uses the xml_file_name from the metadata (e.g., “18915708_12307527.xml”).
destination_path (Optional[str]) – Optional directory path where the file should be saved. If not provided, saves to the current directory. The directory will be created if it doesn’t exist.
overwrite (bool) – Whether to overwrite an existing file at the destination. Default is False, which raises FileExistsError if file exists.

Returns:

Absolute path to the downloaded publication file.

Return type:

str

Raises:

ValueError – If printed_metadata has no file_location_uri (download URL).
FileExistsError – If the file already exists and overwrite=False.

Examples

Download grant XML to a specific directory (auto-filename):

>>> response = client.get_application_by_number("18/915,708")
>>> ifw = response
>>> grant_metadata = ifw.grant_document_meta_data
>>> path = client.download_publication(grant_metadata, destination_path="./downloads")
>>> print(path)
'./downloads/18915708_12307527.xml'

Download pgpub XML with custom filename:

>>> pgpub_metadata = ifw.pg_publication_document_meta_data
>>> path = client.download_publication(
...     pgpub_metadata,
...     file_name="my_publication.xml",
...     destination_path="./downloads"
... )
>>> print(path)
'./downloads/my_publication.xml'

Download to current directory:

>>> path = client.download_publication(grant_metadata)
>>> print(path)
'./18915708_12307527.xml'

get_IFW_metadata(application_number=None, publication_number=None, patent_number=None, PCT_app_number=None, PCT_pub_number=None)[source]

Retrieves complete patent file wrapper data using common identifiers.

This utility fetches the PatentFileWrapper, which contains comprehensive IFW metadata, application details, and more. Provide only one identifier if possible. If multiple are given, they are processed in the order listed in the arguments, and the first successful match is returned.

Parameters:

application_number (Optional[str], optional) – USPTO application number (e.g., “16123456”). Checked first (direct lookup).
patent_number (Optional[str], optional) – USPTO patent number (e.g., “11000000”). Checked second (uses search).
publication_number (Optional[str], optional) – USPTO pre-grant publication number (e.g., “20230123456”). Checked third (uses search).
PCT_app_number (Optional[str], optional) – PCT application number. Checked fourth (direct lookup, treated as USPTO app#).
PCT_pub_number (Optional[str], optional) – PCT publication number (e.g., “2023012345”). Checked fifth (uses search).

Returns:

A PatentFileWrapper object with: comprehensive data if found using one of the identifiers, otherwise None.

Return type:

Optional[PatentFileWrapper]

get_application_adjustment(application_number)[source]

Retrieves patent term adjustment (PTA) data for a specific application.

This method fetches the PatentTermAdjustmentData component from the full patent file wrapper. This data includes details on various delay quantities (e.g., A, B, C delays, applicant delays), the total calculated adjustment, and a history of PTA events that influenced the term.

Parameters:

application_number (str) – The USPTO application number for which PTA data is being requested (e.g., “16123456”).

Returns:

A PatentTermAdjustmentData: object containing the PTA details if the application is found and has such data. Returns None if the application cannot be found or if PTA data is not available in the response.

Return type:

Optional[PatentTermAdjustmentData]

get_application_assignment(application_number)[source]

Retrieves a list of patent assignments for a specific application.

This method fetches the assignment_bag from the patent file wrapper, which contains a list of Assignment objects. Each Assignment object details an assignment including information such as reel and frame numbers, recording dates, conveyance text, and details about the assignors and assignees.

Parameters:

application_number (str) – The USPTO application number for which assignment data is being requested (e.g., “16123456”).

Returns:

A list of Assignment objects, each: representing a recorded assignment for the application. Returns None if the application cannot be found, or if no assignment data is available in the response. An empty list may be returned if the application is found but has no recorded assignments.

Return type:

Optional[List[Assignment]]

get_application_associated_documents(application_number)[source]

Retrieves metadata for Pre-Grant Publication and Grant documents.

This method fetches metadata specifically for published documents associated with the patent application, such as Pre-Grant Publications (PGPUBs) and granted patent documents. It does not retrieve the prosecution history documents (see get_application_documents for that). The result is a PrintedPublication object, which holds PrintedMetaData including file URIs and names. Download with download_archive.

Parameters:

application_number (str) – The USPTO application number for which associated PGPUB/Grant document metadata is being requested (e.g., “16123456”).

Returns:

A PrintedPublication object: containing PrintedMetaData for the Pre-Grant Publication and/or the Grant document, if available. Returns None if the application cannot be found or if no such associated document metadata is available. The fields within the returned object (pgpub_document_meta_data, grant_document_meta_data) may themselves be None if a particular type of document (e.g., PGPUB) does not exist for the application.

Return type:

Optional[PrintedPublication]

get_application_attorney(application_number)[source]

Retrieves data for the attorney(s) of record for a specific application.

This method fetches the RecordAttorney object associated with the patent application. This object contains details about the attorney(s) of record, including customer number correspondence data, power of attorney information, and a list of listed attorneys.

Parameters:

application_number (str) – The USPTO application number for which attorney data is being requested (e.g., “16123456”).

Returns:

A RecordAttorney object with details: about the attorney(s) of record if the application is found and such data exists. Returns None if the application cannot be found or if no attorney data is available in the response.

Return type:

Optional[RecordAttorney]

get_application_by_number(application_number)[source]

Retrieves the full details for a specific patent application by its number.

This method fetches comprehensive information for a single patent application identified by its unique application number.

Parameters:

application_number (str) – The USPTO application number for the patent application (e.g., “16123456” or “18/915,708”). The application number will be automatically sanitized to remove commas and spaces.

Returns:

A PatentFileWrapper object representing: the complete file wrapper for the application if found. This object contains all data sections related to the application, such as metadata, addresses, assignments, attorney/agent data, continuity data, PTA/PTE data, transactions, and associated documents. Returns None if the application cannot be found or if the response does not contain the expected data.

Return type:

Optional[PatentFileWrapper]

get_application_continuity(application_number)[source]

Retrieves continuity data (parent/child applications) for a specific application.

This method fetches the lineage of the specified application, returning an ApplicationContinuityData object. This object consolidates lists of ParentContinuity (applications to which the current one claims priority) and ChildContinuity (applications claiming priority to the current one) objects, each detailing the related application’s key identifiers and status.

Parameters:

application_number (str) – The USPTO application number for which continuity data is being requested (e.g., “16123456”).

Returns:

An ApplicationContinuityData: object containing lists of parent and child continuity relationships. Returns None if the application cannot be found or if the underlying data to construct continuity is not available. The lists within the returned object may be empty if no parent or child continuity links exist.

Return type:

Optional[ApplicationContinuityData]

get_application_documents(application_number, document_codes=None, official_date_from=None, official_date_to=None)[source]

Retrieves metadata for documents associated with a specific application.

This method fetches a collection of document metadata related to the given patent application. The result is a DocumentBag object, which is an iterable collection of Document instances. Each Document object contains metadata such as its identifier, official date, document code and description, direction (incoming/outgoing), and available download formats.

Parameters:

application_number (str) – The USPTO application number for which document metadata is being requested (e.g., “16123456”).
document_codes (Optional[List[str]]) – Filter by specific document type codes. If provided, only documents with these codes will be returned. Examples: [‘ABST’, ‘CLM’, ‘SPEC’, ‘DRWD’].
official_date_from (Optional[str]) – Filter documents from this date (inclusive). Date format: YYYY-MM-DD (e.g., “2020-01-15”).
official_date_to (Optional[str]) – Filter documents to this date (inclusive). Date format: YYYY-MM-DD (e.g., “2023-12-31”).

Returns:

A DocumentBag object containing metadata for all: publicly available documents associated with the application that match the provided filters. The bag will be empty if no documents are found or if the API response indicates no documents. It does not return None for “not found” cases; an empty collection is returned instead.

Return type:

DocumentBag

get_application_foreign_priority(application_number)[source]

Retrieves a list of foreign priority claims for a specific application.

This method fetches the foreign_priority_bag from the patent file wrapper. This bag contains a list of ForeignPriority objects, each representing a claim to a foreign patent application’s priority date. Details include the IP office name, filing date, and application number of the foreign priority application.

Parameters:

application_number (str) – The USPTO application number for which foreign priority data is being requested (e.g., “16123456”).

Returns:

A list of ForeignPriority objects,: each detailing a claimed foreign priority. Returns None if the application cannot be found or if no foreign priority data is available. An empty list may be returned if the application is found but has no foreign priority claims.

Return type:

Optional[List[ForeignPriority]]

get_application_metadata(application_number)[source]

Retrieves key metadata for a specific patent application.

This method fetches the ApplicationMetaData component from the full patent file wrapper. The metadata includes a wide range of information such as application status, important dates (filing, grant, publication), applicant and inventor details, classification data, and other core identifying information for the application.

Parameters:

application_number (str) – The USPTO application number for which metadata is being requested (e.g., “16123456” or “18/915,708”). The application number will be automatically sanitized.

Returns:

An ApplicationMetaData object: containing the core details of the patent application if found. Returns None if the application cannot be found or if metadata is not available in the response.

Return type:

Optional[ApplicationMetaData]

get_application_transactions(application_number)[source]

Retrieves the transaction history (events) for a specific application.

This method fetches the event_data_bag from the patent file wrapper. This bag contains a list of EventData objects, each representing a single recorded event in the prosecution history of the patent application. Events include details like an event code, a textual description, and the date the event was recorded.

Parameters:

application_number (str) – The USPTO application number for which transaction history is being requested (e.g., “16123456”).

Returns:

A list of EventData objects, each: detailing a transaction or event in the application’s history. Returns None if the application cannot be found or if no transaction data is available. An empty list may be returned if the application is found but has no recorded transaction events.

Return type:

Optional[List[EventData]]

get_search_results(query=None, sort=None, offset=0, limit=25, fields_param=None, filters_param=None, range_filters_param=None, post_body=None, application_number_q=None, patent_number_q=None, inventor_name_q=None, applicant_name_q=None, assignee_name_q=None, filing_date_from_q=None, filing_date_to_q=None, grant_date_from_q=None, grant_date_to_q=None, classification_q=None, additional_query_params=None)[source]

Fetches a dataset of patent applications based on search criteria, always requesting JSON format. For GET, parameters align with OpenAPI for /api/v1/patent/applications/search/download. For POST, post_body should conform to PatentDownloadRequest schema.

Return type:: PatentDataResponse

get_status_codes(params=None)[source]

Retrieves USPTO patent application status codes and their descriptions.

This method fetches a list of defined USPTO patent application status codes (e.g., codes for “Pending,” “Abandoned,” “Issued”) using a GET request. The request can be customized with query parameters to filter or paginate the results if supported by the API endpoint.

Parameters:

params (Optional[Dict[str, Any]], optional) – A dictionary of query parameters to be sent with the GET request. These parameters can be used to filter or control the output of the status codes list. Defaults to None, which typically retrieves all available status codes or the API’s default set.

Returns:

An object containing a count of matching: status codes, a StatusCodeCollection of the StatusCode objects (code and description), and a request identifier.

Return type:

StatusCodeSearchResponse

paginate_applications(**kwargs)[source]

Provides an iterator to easily paginate through patent application search results.

This method simplifies the process of fetching all patent applications that match a given search query by automatically handling pagination. It internally calls the search_applications method for GET requests, batching results and yielding them one by one.

All keyword arguments provided to this method (**kwargs) are passed directly to the search_applications method to define the search criteria. See the search_applications method for more details on available parameters. The offset and limit parameters are managed by the pagination logic; setting them directly in kwargs might lead to unexpected behavior.

Parameters:

**kwargs (Any) – Keyword arguments to be passed to the search_applications method for constructing the search query. These define the criteria for the patent applications to be retrieved. Do not include post_body.

Returns:

An iterator that yields PatentFileWrapper: objects, allowing iteration over all matching patent applications across multiple pages of results.

Return type:

Iterator[PatentFileWrapper]

Raises:

ValueError – If post_body is included in kwargs, as this method only supports GET request parameters for pagination.

sanitize_application_number(input_number)[source]

Sanitize and validate a USPTO application number.

Application numbers are either: - 8 digits (e.g., “16123456”) - Series code format: 2 digits + “/” + 6 digits (e.g., “08/123456”) - PCT format: “PCT/US2024/012345” → “PCTUS2412345”

This method removes common separators (commas, spaces) while preserving the “/” in series code format.

Parameters:: input_number (str) – Raw application number input. May include commas, spaces, or other formatting.
Returns:: Sanitized application number (either “NNNNNNNN” or “NN/NNNNNN”).
Return type:: str
Raises:: ValueError – If the format is invalid.

Examples

>>> client.sanitize_application_number("16123456")
"16123456"
>>> client.sanitize_application_number("16,123,456")
"16123456"
>>> client.sanitize_application_number("08/123456")
"08/123456"
>>> client.sanitize_application_number("08/123,456")
"08/123456"

search_applications(query=None, sort=None, offset=0, limit=25, facets=None, fields=None, filters=None, range_filters=None, post_body=None, application_number_q=None, patent_number_q=None, inventor_name_q=None, applicant_name_q=None, assignee_name_q=None, filing_date_from_q=None, filing_date_to_q=None, grant_date_from_q=None, grant_date_to_q=None, classification_q=None, earliestPublicationNumber_q=None, pctPublicationNumber_q=None, additional_query_params=None)[source]

Searches for patent applications. Can perform a GET request based on OpenAPI query parameters or a POST request if post_body is specified.

Return type:: PatentDataResponse

search_status_codes(search_request)[source]

Searches USPTO patent application status codes using POST criteria.

Performs targeted searches for USPTO patent application status codes (e.g., for “Pending,” “Abandoned,” “Issued”) by sending a POST request with a JSON body containing the search_request criteria. This method is suited for more complex queries than the GET-based get_status_codes.

Parameters:

search_request (Dict[str, Any]) – A dictionary with search criteria, sent as the JSON POST body. The structure must conform to USPTO API requirements for this endpoint (e.g., for searching by code or description keywords).

Returns:

An object containing a count of matching: status codes, a StatusCodeCollection of the StatusCode objects (code and description), and a request identifier.

Return type:

StatusCodeSearchResponse