Petition Decisions Client
clients.petition_decisions - Client for USPTO Final Petition Decisions API.
This module provides a client for interacting with the USPTO Final Petition Decisions API. It allows you to search for and retrieve final agency petition decisions in publicly available patent applications and patents filed in 2001 or later.
- class pyUSPTO.clients.petition_decisions.FinalPetitionDecisionsClient(config=None, base_url=None)[source]
Bases:
BaseUSPTOClient[PetitionDecisionResponse]Client for interacting with the USPTO Final Petition Decisions API.
This client provides methods to search for petition decisions, retrieve specific decisions by ID, download decision data, and download associated documents.
Final petition decisions data are incrementally added to the USPTO Open Data Portal on a monthly basis starting with data from 2022 and later.
- ENDPOINTS = {'download_decisions': 'api/v1/petition/decisions/search/download', 'get_decision_by_id': 'api/v1/petition/decisions/{petitionDecisionRecordIdentifier}', 'search_decisions': 'api/v1/petition/decisions/search'}
- __init__(config=None, base_url=None)[source]
Initialize the FinalPetitionDecisionsClient.
- 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 Final Petition Decisions API. If not provided, uses config.petition_decisions_base_url or default.
- download_decisions(format='json', query=None, sort=None, offset=None, limit=None, fields=None, filters=None, range_filters=None, application_number_q=None, patent_number_q=None, inventor_name_q=None, applicant_name_q=None, decision_date_from_q=None, decision_date_to_q=None, additional_query_params=None, file_name=None, destination=None, overwrite=False)[source]
Download petition decisions data in the specified format.
This endpoint is designed for bulk downloads of petition decisions data. It supports JSON and CSV formats.
- Parameters:
format (
str) – Download format, either “json” or “csv”. Defaults to “json”.query (
Optional[str]) – Direct query string in USPTO search syntax.offset (
Optional[int]) – Number of records to skip (pagination).limit (
Optional[int]) – Maximum number of records to return.range_filters (
Optional[str]) – Range filter configuration string.application_number_q (
Optional[str]) – Filter by application number.applicant_name_q (
Optional[str]) – Filter by applicant name.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).additional_query_params (
Optional[dict[str,Any]]) – Additional custom query parameters.file_name (
Optional[str]) – Optional filename for CSV downloads. Defaults to “petition_decisions.csv”.destination (
Optional[str]) – Optional directory path to save CSV file. If None, returns Response.overwrite (
bool) – Whether to overwrite existing files. Default False.
- Returns:
If format=”json”: Returns PetitionDecisionDownloadResponse
If format=”csv” and destination is None: Returns streaming Response
If format=”csv” and destination is set: Returns str path to saved file
- Return type:
Union[PetitionDecisionDownloadResponse, requests.Response, str]
- Raises:
FileExistsError – If CSV file exists and overwrite=False
Examples
# Download as JSON >>> download = client.download_decisions( … format=”json”, … technology_center_q=”1700”, … limit=1000 … ) >>> for decision in download.petition_decision_data: … print(decision.application_number_text)
# Download CSV and save to file >>> file_path = client.download_decisions( … format=”csv”, … decision_date_from_q=”2023-01-01”, … destination=”./downloads” … ) >>> print(f”Saved to: {file_path}”)
# Download CSV as streaming response (advanced usage) >>> response = client.download_decisions(format=”csv”) >>> with open(“decisions.csv”, “wb”) as f: … for chunk in response.iter_content(chunk_size=8192): … f.write(chunk)
- download_petition_document(download_option, destination=None, file_name=None, overwrite=False)[source]
Download petition document (auto-extracts if in archive).
- Parameters:
download_option (
DocumentDownloadOption) – DocumentDownloadOption object containing the download URL and metadata.destination (
Optional[str]) – Optional directory path where the file should be saved. If not provided, saves to the current directory.file_name (
Optional[str]) – Optional filename for the downloaded file. If not provided, it will be extracted from Content-Disposition header or URL.overwrite (
bool) – Whether to overwrite an existing file. Defaults to False.
- Returns:
The absolute path to the downloaded file (extracted if was in archive).
- Return type:
- Raises:
ValueError – If download_option has no download URL.
FileExistsError – If the file exists and overwrite=False.
Examples
# Download first document from a decision >>> decision = client.get_decision_by_id( … “34044333-4b40-515f-a684-2515325c57c5”, … include_documents=True … ) >>> if decision.document_bag: … doc = decision.document_bag[0] … if doc.download_option_bag: … # Download PDF version … pdf_option = next( … opt for opt in doc.download_option_bag … if opt.mime_type_identifier == “PDF” … ) … path = client.download_petition_document( … pdf_option, … destination=”./downloads” … ) … print(f”Downloaded to: {path}”)
- get_decision_by_id(petition_decision_record_identifier, include_documents=None)[source]
Retrieve a specific petition decision by its record identifier.
- Parameters:
- Returns:
The petition decision if found, None otherwise.
- Return type:
Optional[PetitionDecision]
Examples
# Get decision without documents >>> decision = client.get_decision_by_id( … “9f1a4a2b-eee1-58ec-a3aa-167c4075aed4” … )
# Get decision with documents >>> decision = client.get_decision_by_id( … “34044333-4b40-515f-a684-2515325c57c5”, … include_documents=True … )
- paginate_decisions(post_body=None, **kwargs)[source]
Provide an iterator to paginate through petition decision search results.
This method simplifies fetching all petition decisions matching a search query by automatically handling pagination. Supports both GET and POST requests.
The offset and limit parameters are managed by the pagination logic; setting them directly in kwargs or post_body might lead to unexpected behavior.
- Parameters:
- Returns:
- An iterator yielding PetitionDecision objects,
allowing iteration over all matching petition decisions across multiple pages of results.
- Return type:
Iterator[PetitionDecision]
Examples
# GET pagination through all decisions for a technology center >>> for decision in client.paginate_decisions(technology_center_q=”1700”): … print(f”{decision.application_number_text}: {decision.decision_type_code}”)
# POST pagination with date range >>> for decision in client.paginate_decisions( … post_body={ … “decision_date_from_q”: “2023-01-01”, … “decision_date_to_q”: “2023-12-31” … } … ): … 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, application_number_q=None, patent_number_q=None, inventor_name_q=None, applicant_name_q=None, invention_title_q=None, decision_type_code_q=None, decision_date_from_q=None, decision_date_to_q=None, petition_mail_date_from_q=None, petition_mail_date_to_q=None, technology_center_q=None, final_deciding_office_name_q=None, additional_query_params=None)[source]
Return final petition decisions matching the given criteria.
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_q (
Optional[str]) – Filter by application number.applicant_name_q (
Optional[str]) – Filter by applicant name.invention_title_q (
Optional[str]) – Filter by invention title.decision_type_code_q (
Optional[str]) – Filter by decision type code.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).petition_mail_date_from_q (
Optional[str]) – Filter petition mail dates from (YYYY-MM-DD).petition_mail_date_to_q (
Optional[str]) – Filter petition mail dates to (YYYY-MM-DD).technology_center_q (
Optional[str]) – Filter by technology center.final_deciding_office_name_q (
Optional[str]) – Filter by deciding office name.additional_query_params (
Optional[dict[str,Any]]) – Additional custom query parameters.
- Returns:
Response containing matching petition decisions.
- Return type:
Examples
# Search with direct query >>> response = client.search_decisions(query=”applicationNumberText:17765301”)
# Search with convenience parameters >>> response = client.search_decisions( … applicant_name_q=”ACME Corp”, … decision_date_from_q=”2022-01-01”, … limit=50 … )
# Search with POST body >>> response = client.search_decisions( … post_body={“q”: “technologyCenter:1700”, “limit”: 100} … )