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)

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)

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)

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)

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)

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)

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)

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)

Bases: BaseUSPTOClient[PatentDataResponse]

Client for interacting with the USPTO Patent Data API.

ENDPOINTS = {'application_adjustment': 'applications/{application_number}/adjustment', 'application_assignment': 'applications/{application_number}/assignment', 'application_associated_documents': 'applications/{application_number}/associated-documents', 'application_attorney': 'applications/{application_number}/attorney', 'application_by_number': 'applications/{application_number}', 'application_continuity': 'applications/{application_number}/continuity', 'application_documents': 'applications/{application_number}/documents', 'application_foreign_priority': 'applications/{application_number}/foreign-priority', 'application_metadata': 'applications/{application_number}/meta-data', 'application_transactions': 'applications/{application_number}/transactions', 'applications_search': 'applications/search', 'applications_search_download': 'applications/search/download', 'download_document': 'download/applications/{application_number}/{document_id}', 'status_codes': 'status-codes'}

__init__(api_key=None, base_url=None, config=None)

Initialize the PatentDataClient.

Parameters:

• api_key (Optional[str]) – Optional API key for authentication

• base_url (Optional[str]) – The base URL of the API, defaults to config.patent_data_base_url or “https://api.uspto.gov/api/v1/patent”

• config (Optional[USPTOConfig]) – Optional USPTOConfig instance

download_application_document(application_number, document_id, destination)

Download a document for a patent application.

Parameters:

• application_number (str) – The application number

• document_id (str) – The document identifier

• destination (str) – Directory where the file should be saved

Return type:

str

Returns:

Path to the downloaded file

download_patent_applications(params=None, format='json')

Download patent data with specified format.

Parameters:

• params (Optional[Dict[str, Any]]) – Optional query parameters

• format (str) – Download format (json or csv)

Return type:

PatentDataResponse

Returns:

PatentDataResponse object containing the API response

download_patent_applications_post(download_request)

Download patent data using POST method with JSON payload.

Parameters:

download_request (Dict[str, Any]) – JSON payload with download parameters including format

Return type:

PatentDataResponse

Returns:

PatentDataResponse object containing the API response

get_application_adjustment(application_number)

Get patent term adjustment data for an application.

Parameters:

application_number (str) – The application number

Return type:

PatentDataResponse

Returns:

PatentDataResponse object containing the adjustment data

get_application_assignment(application_number)

Get assignment data for an application.

Parameters:

application_number (str) – The application number

Return type:

PatentDataResponse

Returns:

PatentDataResponse object containing the assignment data

get_application_associated_documents(application_number)

Get associated documents metadata for an application.

Parameters:

application_number (str) – The application number

Return type:

PatentDataResponse

Returns:

PatentDataResponse object containing the associated documents metadata

get_application_attorney(application_number)

Get attorney/agent data for an application.

Parameters:

application_number (str) – The application number

Return type:

PatentDataResponse

Returns:

PatentDataResponse object containing the attorney data

get_application_continuity(application_number)

Get continuity data for an application.

Parameters:

application_number (str) – The application number

Return type:

PatentDataResponse

Returns:

PatentDataResponse object containing the continuity data

get_application_documents(application_number)

Get document details for an application.

Parameters:

application_number (str) – The application number

Return type:

PatentDataResponse

Returns:

PatentDataResponse object containing document details

get_application_foreign_priority(application_number)

Get foreign priority data for an application.

Parameters:

application_number (str) – The application number

Return type:

PatentDataResponse

Returns:

PatentDataResponse object containing the foreign priority data

get_application_metadata(application_number)

Get metadata for a specific patent application.

Parameters:

application_number (str) – The application number

Return type:

PatentDataResponse

Returns:

PatentDataResponse object containing the application metadata

get_application_transactions(application_number)

Get transaction data for an application.

Parameters:

application_number (str) – The application number

Return type:

PatentDataResponse

Returns:

PatentDataResponse object containing the transaction data

get_patent_applications(params=None)

Get a list of patent applications using the search endpoint.

Parameters:

params (Optional[Dict[str, Any]]) – Optional query parameters including: - q: Search query string - sort: Field to sort by followed by sort order - offset: Position in dataset to start from - limit: Number of results to return - facets: List of fields to facet upon - fields: Fields to include in response - filters: Field filters - rangeFilters: Range filters

Return type:

PatentDataResponse

Returns:

PatentDataResponse object containing the API response

get_patent_by_application_number(application_number)

Get a specific patent by application number.

Parameters:

application_number (str) – The application number

Return type:

PatentFileWrapper

Returns:

PatentFileWrapper object containing the patent data

get_patent_status_codes(params=None)

Get patent application status codes and descriptions.

Parameters:

params (Optional[Dict[str, Any]]) – Optional query parameters including: - q: Search query string - offset: Position in dataset to start from - limit: Number of results to return

Return type:

Dict[str, Any]

Returns:

Dictionary containing status codes and descriptions

paginate_patents(**kwargs)

Paginate through all patents matching the search criteria.

Parameters:

**kwargs (Any) – Keyword arguments to pass to search_patents

Yields:

PatentFileWrapper objects

Return type:

Iterator[PatentFileWrapper]

search_patent_applications_post(search_request)

Search patent applications using POST method with JSON payload.

Parameters:

search_request (Dict[str, Any]) – JSON payload with search parameters including: - q: Search query string - filters: Array of filter objects - rangeFilters: Array of range filter objects - sort: Array of sort objects - fields: Array of field names to include - pagination: Pagination object - facets: Array of facet field names

Return type:

PatentDataResponse

Returns:

PatentDataResponse object containing the API response

search_patent_status_codes_post(search_request)

Search patent status codes using POST method with JSON payload.

Parameters:

search_request (Dict[str, Any]) – JSON payload with search parameters

Return type:

Dict[str, Any]

Returns:

Dictionary containing status codes and descriptions

search_patents(query=None, application_number=None, patent_number=None, inventor_name=None, applicant_name=None, assignee_name=None, filing_date_from=None, filing_date_to=None, grant_date_from=None, grant_date_to=None, classification=None, limit=25, offset=0)

Search for patents with various filters.

Parameters:

• query (Optional[str]) – Search text in all fields

• application_number (Optional[str]) – Filter by application number

• patent_number (Optional[str]) – Filter by patent number

• inventor_name (Optional[str]) – Filter by inventor name

• applicant_name (Optional[str]) – Filter by applicant name

• assignee_name (Optional[str]) – Filter by assignee name

• filing_date_from (Optional[str]) – Filter by filing date from (YYYY-MM-DD)

• filing_date_to (Optional[str]) – Filter by filing date to (YYYY-MM-DD)

• grant_date_from (Optional[str]) – Filter by grant date from (YYYY-MM-DD)

• grant_date_to (Optional[str]) – Filter by grant date to (YYYY-MM-DD)

• classification (Optional[str]) – Filter by CPC classification

• limit (Optional[int]) – Number of results to return (default 25)

• offset (Optional[int]) – Position in dataset to start from (default 0)

Return type:

PatentDataResponse

Returns:

PatentDataResponse object containing matching patents