PTAB Appeals Client
clients.ptab_appeals - Client for USPTO PTAB Appeals API.
This module provides a client for interacting with the USPTO PTAB (Patent Trial and Appeal Board) Appeals API. It allows you to search for ex parte appeal decisions.
- class pyUSPTO.clients.ptab_appeals.PTABAppealsClient(config=None, base_url=None)[source]
Bases:
BaseUSPTOClient[PTABAppealResponse]Client for interacting with the USPTO PTAB Appeals API.
This client provides methods to search for ex parte appeal decisions from the Patent Trial and Appeal Board.
Appeals data includes decisions on patent application appeals from the examiner to the PTAB.
- ENDPOINTS = {'search_decisions': 'api/v1/patent/appeals/decisions/search'}
- __init__(config=None, base_url=None)[source]
Initialize the PTABAppealsClient.
- Parameters:
config (
Optional[USPTOConfig]) – USPTOConfig instance containing API key and settings. If not provided, creates config from environment variables (requires USPTO_API_KEY).base_url (
Optional[str]) – Optional base URL override for the USPTO PTAB API. If not provided, uses config.ptab_base_url or default.
- download_appeal_archive(appeal_meta_data, destination=None, file_name=None, overwrite=False)[source]
Download appeal archive (ZIP/TAR) without extraction.
- Parameters:
- Return type:
- Returns:
Path to downloaded archive file
- Raises:
ValueError – If appeal_meta_data has no file_download_uri
- download_appeal_document(document_data, destination=None, file_name=None, overwrite=False)[source]
Download individual appeal document (auto-extracts if needed).
- Parameters:
- Return type:
- Returns:
Path to downloaded file
- Raises:
ValueError – If document_data has no file_download_uri
- download_appeal_documents(appeal_meta_data, destination=None, overwrite=False)[source]
Download and extract all appeal documents.
- Parameters:
appeal_meta_data (
AppealMetaData) – AppealMetaData with file_download_urioverwrite (
bool) – Overwrite existing files
- Return type:
- Returns:
Path to extraction directory
- Raises:
ValueError – If appeal_meta_data has no file_download_uri
- paginate_decisions(post_body=None, **kwargs)[source]
Provide an iterator to paginate through appeal decision search results.
This method simplifies fetching all appeal decisions matching a search query by automatically handling pagination. It internally calls the search_decisions method, batching results and yielding them one by one.
Supports both GET and POST requests. For POST requests, provide the search criteria in post_body. For GET requests, use keyword arguments.
The offset parameter is managed by the pagination logic and should not be provided by the user. The limit parameter can be customized.
- Parameters:
- Returns:
- An iterator yielding PTABAppealDecision objects,
allowing iteration over all matching decisions across multiple pages of results.
- Return type:
Iterator[PTABAppealDecision]
Examples
# GET-based pagination with convenience parameters >>> for decision in client.paginate_decisions(technology_center_number_q=”3600”): … print(f”{decision.appeal_meta_data.appeal_number}: ” … f”{decision.decision_data.decision_type_category}”)
# GET-based pagination with date range and custom limit >>> for decision in client.paginate_decisions( … decision_date_from_q=”2023-01-01”, … decision_date_to_q=”2023-12-31”, … limit=50 … ): … process_decision(decision)
# POST-based pagination >>> for decision in client.paginate_decisions( … post_body={“q”: “decisionTypeCategory:Affirmed”, “limit”: 100} … ): … process_decision(decision)
- search_decisions(query=None, sort=None, offset=0, limit=25, facets=None, fields=None, filters=None, range_filters=None, post_body=None, appeal_number_q=None, application_number_text_q=None, appellant_name_q=None, requestor_name_q=None, decision_type_category_q=None, decision_date_from_q=None, decision_date_to_q=None, technology_center_number_q=None, additional_query_params=None)[source]
Search for PTAB appeal decisions.
This method can perform either a GET request using query parameters or a POST request if post_body is specified. When using GET, you can provide either a direct query string or use convenience parameters that will be automatically combined into a query.
- Parameters:
query (
Optional[str]) – Direct query string in USPTO search syntax.offset (
int|None) – Number of records to skip (pagination).range_filters (
Optional[str]) – Range filter configuration string.post_body (
Optional[dict[str,Any]]) – Optional POST body for complex queries.application_number_text_q (
Optional[str]) – Filter by application number.appellant_name_q (
Optional[str]) – Filter by appellant name.requestor_name_q (
Optional[str]) – Filter by requestor name.decision_type_category_q (
Optional[str]) – Filter by decision type category.decision_date_from_q (
Optional[str]) – Filter decisions from this date (YYYY-MM-DD).decision_date_to_q (
Optional[str]) – Filter decisions to this date (YYYY-MM-DD).technology_center_number_q (
Optional[str]) – Filter by technology center number.additional_query_params (
Optional[dict[str,Any]]) – Additional custom query parameters.
- Returns:
Response containing matching appeal decisions.
- Return type:
Examples
# Search with direct query >>> response = client.search_decisions(query=”appealNumber:2023-001234”)
# Search with convenience parameters >>> response = client.search_decisions( … technology_center_number_q=”3600”, … decision_date_from_q=”2023-01-01”, … limit=50 … )
# Search with POST body >>> response = client.search_decisions( … post_body={“q”: “decisionTypeCategory:Affirmed”, “limit”: 100} … )