From 3905c25c331b82412dff713c62ecdb8a25b4ec5d Mon Sep 17 00:00:00 2001 From: Dan Romano <1087791+krautrocker@users.noreply.github.com> Date: Thu, 9 Oct 2025 11:30:45 -0400 Subject: [PATCH 1/2] - Initial release --- .../US PTO/apiDefinition.swagger.json | 3696 +++++++++++++++++ .../US PTO/apiProperties.json | 20 + .../US PTO/readme.md | 123 + 3 files changed, 3839 insertions(+) create mode 100644 independent-publisher-connectors/US PTO/apiDefinition.swagger.json create mode 100644 independent-publisher-connectors/US PTO/apiProperties.json create mode 100644 independent-publisher-connectors/US PTO/readme.md diff --git a/independent-publisher-connectors/US PTO/apiDefinition.swagger.json b/independent-publisher-connectors/US PTO/apiDefinition.swagger.json new file mode 100644 index 0000000000..e59915d2e6 --- /dev/null +++ b/independent-publisher-connectors/US PTO/apiDefinition.swagger.json @@ -0,0 +1,3696 @@ +{ + "swagger": "2.0", + "info": { + "title": "US Patent & Trademark Office", + "description": "Search and retrieve bibliographic data for patent applications.", + "version": "1.0", + "contact": { + "name": "United States Patent and Trademark Office", + "email": "uspto@uspto.gov", + "url": "https://developer.uspto.gov" + } + }, + "x-ms-connector-metadata": [ + { + "propertyName": "Website", + "propertyValue": "https://developer.uspto.gov" + }, + { + "propertyName": "Privacy policy", + "propertyValue": "https://www.uspto.gov/privacy-policy" + }, + { + "propertyName": "Categories", + "propertyValue": "IT Operations" + } + ], + "host": "api.uspto.gov", + "basePath": "/api/v1", + "schemes": [ + "https" + ], + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "securityDefinitions": { + "api_key": { + "type": "apiKey", + "in": "header", + "name": "x-api-key" + } + }, + "security": [ + { + "api_key": [] + } + ], + "paths": { + "/patent/applications/search": { + "get": { + "tags": [ + "Patent Search" + ], + "operationId": "Search_Patent_Applications_GET", + "summary": "Search patent applications using query parameters", + "description": "Returns up to 25 patent applications matching optional filters, fields, sort, and facets.", + "x-ms-summary": "Search patent applications via query parameters", + "x-ms-visibility": "important", + "parameters": [ + { + "name": "q", + "in": "query", + "type": "string", + "x-ms-summary": "Search query", + "x-ms-visibility": "important", + "description": "Search text string supporting Boolean, range, and wildcard syntax." + }, + { + "name": "sort", + "in": "query", + "type": "string", + "x-ms-summary": "Sort order", + "x-ms-visibility": "important", + "description": "Field and sort order (e.g., filingDate asc)." + }, + { + "name": "offset", + "in": "query", + "type": "integer", + "x-ms-summary": "Offset", + "x-ms-visibility": "important", + "description": "Record offset position.", + "default": 0 + }, + { + "name": "limit", + "in": "query", + "type": "integer", + "x-ms-summary": "Limit", + "x-ms-visibility": "important", + "description": "Number of records to return.", + "default": 25 + }, + { + "name": "facets", + "in": "query", + "type": "string", + "x-ms-summary": "Facets", + "x-ms-visibility": "important", + "description": "Comma-separated fields to facet upon." + }, + { + "name": "fields", + "in": "query", + "type": "string", + "x-ms-summary": "Fields", + "description": "Comma-separated list of fields to include in results." + }, + { + "name": "filters", + "in": "query", + "type": "string", + "x-ms-summary": "Filters", + "x-ms-visibility": "important", + "description": "Filter records by field name and value." + }, + { + "name": "rangeFilters", + "in": "query", + "type": "string", + "x-ms-summary": "Range filters", + "description": "Range filters for numeric or date fields." + } + ], + "responses": { + "200": { + "description": "Successful response", + "schema": { + "$ref": "#/definitions/PatentDataResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "403": { + "description": "Forbidden", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "413": { + "description": "Payload Too Large", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "default": { + "description": "Unexpected error" + } + } + }, + "post": { + "tags": [ + "Patent Search" + ], + "operationId": "Search_Patent_Applications_POST", + "summary": "Search patent applications (advanced JSON)", + "description": "Retrieve patent application data using structured JSON payload.", + "x-ms-summary": "Search patent applications using JSON payload", + "x-ms-visibility": "important", + "parameters": [ + { + "name": "body", + "in": "body", + "required": true, + "x-ms-summary": "Request body", + "description": "JSON payload defining search criteria, filters, sort order, and pagination.", + "schema": { + "type": "object", + "properties": { + "q": { + "type": "string", + "description": "Search query string supporting boolean operators and wildcards.", + "example": "applicationMetaData.applicationTypeLabelName:Utility" + }, + "filters": { + "type": "array", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "example": "applicationMetaData.applicationStatusDescriptionText" + }, + "value": { + "type": "array", + "items": { + "type": "string", + "example": "Patented Case" + } + } + } + } + }, + "rangeFilters": { + "type": "array", + "items": { + "type": "object", + "properties": { + "field": { + "type": "string", + "example": "applicationMetaData.grantDate" + }, + "valueFrom": { + "type": "string", + "example": "2010-08-04T00:00:00.000Z" + }, + "valueTo": { + "type": "string", + "example": "2022-08-04T00:00:00.000Z" + } + } + } + }, + "sort": { + "type": "array", + "items": { + "type": "object", + "properties": { + "field": { + "type": "string", + "example": "applicationMetaData.filingDate" + }, + "order": { + "type": "string", + "example": "desc" + } + } + } + }, + "fields": { + "type": "array", + "items": { + "type": "string" + }, + "example": [ + "applicationNumberText", + "correspondenceAddressBag", + "applicationMetaData.filingDate" + ] + }, + "pagination": { + "type": "object", + "properties": { + "offset": { + "type": "integer", + "example": 0 + }, + "limit": { + "type": "integer", + "example": 25 + } + } + }, + "facets": { + "type": "array", + "items": { + "type": "string" + }, + "example": [ + "applicationMetaData.applicationTypeLabelName", + "applicationMetaData.applicationStatusCode" + ] + } + } + } + } + ], + "responses": { + "200": { + "description": "Successful response", + "schema": { + "$ref": "#/definitions/PatentDataResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "403": { + "description": "Forbidden", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "413": { + "description": "Payload Too Large", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "default": { + "description": "Unexpected error" + } + } + } + }, + "/patent/applications/search/download": { + "get": { + "tags": [ + "Patent Search" + ], + "operationId": "Download_Patent_Search_Results_GET", + "summary": "Download patent data by query", + "description": "Download patent data using query parameters. Defaults to JSON format.", + "x-ms-summary": "Download patent data using query parameters", + "x-ms-visibility": "internal", + "parameters": [ + { + "name": "q", + "in": "query", + "type": "string", + "x-ms-summary": "Search query", + "x-ms-visibility": "important", + "description": "A search query string supporting boolean operators (AND, OR, NOT), wildcards (*), and exact phrases (\"\")." + }, + { + "name": "sort", + "in": "query", + "type": "string", + "x-ms-summary": "Sort order", + "x-ms-visibility": "important", + "description": "Field to sort by followed by sort direction." + }, + { + "name": "offset", + "in": "query", + "type": "integer", + "minimum": 0, + "x-ms-summary": "Offset", + "x-ms-visibility": "important", + "description": "Record offset to begin from.", + "default": 0 + }, + { + "name": "limit", + "in": "query", + "type": "integer", + "minimum": 1, + "x-ms-summary": "Limit", + "x-ms-visibility": "important", + "description": "Maximum number of results to return.", + "default": 25 + }, + { + "name": "fields", + "in": "query", + "type": "string", + "x-ms-summary": "Fields", + "x-ms-visibility": "important", + "description": "Comma-separated list of fields to include in the response." + }, + { + "name": "filters", + "in": "query", + "type": "string", + "x-ms-summary": "Filters", + "x-ms-visibility": "important", + "description": "Filter data by providing field name and value." + }, + { + "name": "rangeFilters", + "in": "query", + "type": "string", + "x-ms-summary": "Range filters", + "x-ms-visibility": "important", + "description": "Filter data by numeric or date range." + }, + { + "name": "format", + "in": "query", + "type": "string", + "x-ms-summary": "Format", + "x-ms-visibility": "important", + "description": "Output format of download (json or csv).", + "enum": [ + "json", + "csv" + ], + "default": "json" + } + ], + "responses": { + "200": { + "description": "Download successful", + "schema": { + "$ref": "#/definitions/PatentDataResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "403": { + "description": "Forbidden", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + } + } + }, + "post": { + "tags": [ + "Patent Search" + ], + "operationId": "Download_Patent_Search_Results", + "summary": "Download patent data", + "description": "Download patent application data by supplying JSON search payload.", + "x-ms-summary": "Download patent data using JSON payload", + "x-ms-visibility": "important", + "parameters": [ + { + "name": "body", + "in": "body", + "required": true, + "x-ms-summary": "Request body", + "x-ms-visibility": "important", + "description": "JSON payload defining search criteria, filters, sort order, and download format.", + "schema": { + "type": "object", + "properties": { + "q": { + "type": "string", + "description": "Search query string.", + "example": "applicationMetaData.applicationTypeLabelName:Utility" + }, + "filters": { + "type": "array", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "example": "applicationMetaData.applicationStatusDescriptionText" + }, + "value": { + "type": "array", + "items": { + "type": "string" + }, + "example": [ + "Patented Case" + ] + } + } + } + }, + "rangeFilters": { + "type": "array", + "items": { + "type": "object", + "properties": { + "field": { + "type": "string", + "example": "applicationMetaData.grantDate" + }, + "valueFrom": { + "type": "string", + "example": "2010-08-04T00:00:00.000Z" + }, + "valueTo": { + "type": "string", + "example": "2022-08-04T00:00:00.000Z" + } + } + } + }, + "sort": { + "type": "array", + "items": { + "type": "object", + "properties": { + "field": { + "type": "string", + "example": "applicationMetaData.filingDate" + }, + "order": { + "type": "string", + "enum": [ + "asc", + "desc" + ], + "example": "desc" + } + } + } + }, + "fields": { + "type": "array", + "items": { + "type": "string" + }, + "example": [ + "applicationNumberText", + "correspondenceAddressBag", + "applicationMetaData.filingDate" + ] + }, + "pagination": { + "type": "object", + "properties": { + "offset": { + "type": "integer", + "example": 0 + }, + "limit": { + "type": "integer", + "example": 25 + } + } + }, + "format": { + "type": "string", + "enum": [ + "json", + "csv" + ], + "example": "json" + } + } + } + } + ], + "responses": { + "200": { + "description": "Download successful", + "schema": { + "$ref": "#/definitions/PatentDataResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "403": { + "description": "Forbidden", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + } + } + } + }, + "/patent/applications/{applicationNumberText}": { + "get": { + "tags": [ + "Patent Application Details" + ], + "operationId": "Get_Patent_Application_By_Number", + "summary": "Get patent application by number", + "description": "Retrieve detailed bibliographic data for a specified patent application number. Application numbers containing special characters (e.g. `PCT/BR00/000001`) must be UTF-8 encoded.", + "x-ms-summary": "Retrieve a patent application by number", + "x-ms-visibility": "important", + "parameters": [ + { + "name": "applicationNumberText", + "in": "path", + "required": true, + "type": "string", + "x-ms-summary": "Application number", + "x-ms-visibility": "important", + "description": "Patent application number (UTF-8 encoded if special characters present).", + "default": "14412875" + } + ], + "responses": { + "200": { + "description": "Successful response", + "schema": { + "$ref": "#/definitions/PatentDataResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "403": { + "description": "Forbidden", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "default": { + "description": "Unexpected error" + } + } + } + }, + "/patent/applications/{applicationNumberText}/meta-data": { + "get": { + "tags": [ + "Patent Application Details" + ], + "operationId": "Get_Patent_Application_MetaData", + "summary": "Get patent application metadata", + "description": "Retrieve metadata details for a specified patent application number, including bibliographic and file wrapper data.", + "x-ms-summary": "Retrieve metadata for a patent application", + "x-ms-visibility": "important", + "parameters": [ + { + "name": "applicationNumberText", + "in": "path", + "required": true, + "type": "string", + "x-ms-summary": "Application number", + "x-ms-visibility": "important", + "description": "Patent application number for which metadata is requested.", + "default": "16330077" + } + ], + "responses": { + "200": { + "description": "Successful response containing metadata details", + "schema": { + "$ref": "#/definitions/ApplicationMetaDataResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "403": { + "description": "Forbidden", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "default": { + "description": "Unexpected error" + } + } + } + }, + "/patent/applications/{applicationNumberText}/adjustment": { + "get": { + "tags": [ + "Patent Application Details" + ], + "operationId": "Get_Patent_Application_Adjustment", + "summary": "Get patent term adjustment data", + "description": "Retrieve patent term adjustment details for a specific application number, including extensions and delay information.", + "x-ms-summary": "Retrieve patent term adjustment details", + "x-ms-visibility": "important", + "parameters": [ + { + "name": "applicationNumberText", + "in": "path", + "required": true, + "type": "string", + "x-ms-summary": "Application number", + "x-ms-visibility": "important", + "description": "Patent application number for which term adjustment information is requested.", + "default": "14104993" + } + ], + "responses": { + "200": { + "description": "Successful response with adjustment data", + "schema": { + "$ref": "#/definitions/PatentAdjustmentResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "403": { + "description": "Forbidden", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "default": { + "description": "Unexpected error" + } + } + } + }, + "/patent/applications/{applicationNumberText}/assignment": { + "get": { + "tags": [ + "Patent Application Details" + ], + "operationId": "Get_Patent_Application_Assignment", + "summary": "Get patent assignment data", + "description": "Retrieve assignment and ownership transfer information for a specific patent application number.", + "x-ms-summary": "Retrieve assignment details for a patent application", + "x-ms-visibility": "important", + "parameters": [ + { + "name": "applicationNumberText", + "in": "path", + "required": true, + "type": "string", + "x-ms-summary": "Application number", + "x-ms-visibility": "important", + "description": "Patent application number for which assignment information is requested.", + "default": "14104993" + } + ], + "responses": { + "200": { + "description": "Successful response with assignment data", + "schema": { + "$ref": "#/definitions/PatentAssignmentResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "403": { + "description": "Forbidden", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "default": { + "description": "Unexpected error" + } + } + } + }, + "/patent/applications/{applicationNumberText}/attorney": { + "get": { + "tags": [ + "Patent Application Details" + ], + "operationId": "Get_Patent_Application_Attorney", + "summary": "Get attorney or agent data", + "description": "Retrieve attorney or agent representation details for a specific patent application number.", + "x-ms-summary": "Retrieve attorney or agent information", + "x-ms-visibility": "important", + "parameters": [ + { + "name": "applicationNumberText", + "in": "path", + "required": true, + "type": "string", + "x-ms-summary": "Application number", + "x-ms-visibility": "important", + "description": "Patent application number for which attorney or agent information is requested.", + "default": "14104993" + } + ], + "responses": { + "200": { + "description": "Successful response with attorney or agent data", + "schema": { + "$ref": "#/definitions/PatentAttorneyResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "403": { + "description": "Forbidden", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "default": { + "description": "Unexpected error" + } + } + } + }, + "/patent/applications/{applicationNumberText}/continuity": { + "get": { + "tags": [ + "Patent Application Details" + ], + "operationId": "Get_Patent_Application_Continuity", + "summary": "Get patent continuity data", + "description": "Retrieve parent and child continuity relationships for a specified patent application number, including continuations, divisionals, and continuations-in-part.", + "x-ms-summary": "Retrieve parent and child continuity data", + "x-ms-visibility": "important", + "parameters": [ + { + "name": "applicationNumberText", + "in": "path", + "required": true, + "type": "string", + "x-ms-summary": "Application number", + "x-ms-visibility": "important", + "description": "Patent application number for which continuity data is requested.", + "default": "14104993" + } + ], + "responses": { + "200": { + "description": "Successful response with continuity data", + "schema": { + "$ref": "#/definitions/PatentContinuityResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "403": { + "description": "Forbidden", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "default": { + "description": "Unexpected error" + } + } + } + }, + "/patent/applications/{applicationNumberText}/foreign-priority": { + "get": { + "tags": [ + "Patent Application Details" + ], + "operationId": "Get_Patent_Application_ForeignPriority", + "summary": "Get foreign priority data", + "description": "Retrieve foreign priority details for a specific patent application, including foreign filing numbers, countries, and filing dates.", + "x-ms-summary": "Retrieve foreign priority data for a patent application", + "x-ms-visibility": "important", + "parameters": [ + { + "name": "applicationNumberText", + "in": "path", + "required": true, + "type": "string", + "x-ms-summary": "Application number", + "x-ms-visibility": "important", + "description": "Patent application number for which foreign priority data is requested.", + "default": "14104993" + } + ], + "responses": { + "200": { + "description": "Successful response with foreign priority data", + "schema": { + "$ref": "#/definitions/PatentForeignPriorityResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "403": { + "description": "Forbidden", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "default": { + "description": "Unexpected error" + } + } + } + }, + "/patent/applications/{applicationNumberText}/transactions": { + "get": { + "tags": [ + "Patent Application Details" + ], + "operationId": "Get_Patent_Application_Transactions", + "summary": "Get patent transaction history", + "description": "Retrieve a chronological list of prosecution events and transactions for a specific patent application number.", + "x-ms-summary": "Retrieve transaction history for a patent application", + "x-ms-visibility": "important", + "parameters": [ + { + "name": "applicationNumberText", + "in": "path", + "required": true, + "type": "string", + "x-ms-summary": "Application number", + "x-ms-visibility": "important", + "description": "Patent application number for which transaction history is requested.", + "default": "14104993" + } + ], + "responses": { + "200": { + "description": "Successful response with transaction data", + "schema": { + "$ref": "#/definitions/PatentTransactionResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "403": { + "description": "Forbidden", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "default": { + "description": "Unexpected error" + } + } + } + }, + "/patent/applications/{applicationNumberText}/documents": { + "get": { + "tags": [ + "Patent Application Details" + ], + "operationId": "Get_Patent_Application_Documents", + "summary": "Get document metadata for a patent application", + "description": "Retrieve details of documents filed or issued for a specific patent application number, including office actions, responses, and fee worksheets.", + "x-ms-summary": "Retrieve document list for a patent application", + "x-ms-visibility": "important", + "parameters": [ + { + "name": "applicationNumberText", + "in": "path", + "required": true, + "type": "string", + "x-ms-summary": "Application number", + "x-ms-visibility": "important", + "description": "Patent application number for which document details are requested.", + "default": "16330077" + }, + { + "name": "documentCodes", + "in": "query", + "type": "string", + "x-ms-summary": "Document codes", + "x-ms-visibility": "important", + "description": "Comma-separated list of document codes to filter results.", + "default": "WFEE" + }, + { + "name": "officialDateFrom", + "in": "query", + "type": "string", + "format": "date", + "x-ms-summary": "From date", + "x-ms-visibility": "important", + "description": "Start of date range for document official date (yyyy-MM-dd)." + }, + { + "name": "officialDateTo", + "in": "query", + "type": "string", + "format": "date", + "x-ms-summary": "To date", + "x-ms-visibility": "important", + "description": "End of date range for document official date (yyyy-MM-dd)." + } + ], + "responses": { + "200": { + "description": "Successful response with document metadata", + "schema": { + "$ref": "#/definitions/PatentDocumentResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "403": { + "description": "Forbidden", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "default": { + "description": "Unexpected error" + } + } + } + }, + "/patent/applications/{applicationNumberText}/associated-documents": { + "get": { + "tags": [ + "Patent Application Details" + ], + "operationId": "Get_Patent_Application_AssociatedDocuments", + "summary": "Get associated publication and grant document metadata", + "description": "Retrieve metadata for associated publication (PGPub) and grant documents linked to a specific patent application number.", + "x-ms-summary": "Retrieve associated publication and grant metadata", + "x-ms-visibility": "important", + "parameters": [ + { + "name": "applicationNumberText", + "in": "path", + "required": true, + "type": "string", + "x-ms-summary": "Application number", + "x-ms-visibility": "important", + "description": "Patent application number for which associated publication and grant documents are requested.", + "default": "16330077" + } + ], + "responses": { + "200": { + "description": "Successful response with associated document metadata", + "schema": { + "$ref": "#/definitions/PatentAssociatedDocumentsResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "403": { + "description": "Forbidden", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "default": { + "description": "Unexpected error" + } + } + } + }, + "/patent/status-codes": { + "get": { + "tags": [ + "Patent Reference Data" + ], + "summary": "Retrieve patent application status codes", + "description": "Search and filter patent application status codes and descriptions using query parameters. All parameters are optional. Returns top 25 results by default.\n", + "operationId": "Get_Patent_Status_Codes", + "x-ms-summary": "Search patent application status codes (GET)", + "x-ms-visibility": "important", + "parameters": [ + { + "name": "q", + "in": "query", + "type": "string", + "x-ms-summary": "Search query", + "x-ms-visibility": "important", + "description": "A search string supporting boolean operators (AND, OR, NOT), wildcards (*), and exact phrases (\"\").\n", + "required": false + }, + { + "name": "offset", + "in": "query", + "type": "integer", + "x-ms-summary": "Result offset", + "x-ms-visibility": "important", + "description": "Position in the dataset of a particular record.", + "required": false, + "default": 0 + }, + { + "name": "limit", + "in": "query", + "type": "integer", + "x-ms-summary": "Result limit", + "x-ms-visibility": "important", + "description": "Limit the number of results returned.", + "required": false, + "default": 25 + } + ], + "responses": { + "200": { + "description": "Successful response", + "schema": { + "$ref": "#/definitions/StatusCodeSearchResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "403": { + "description": "Forbidden", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "default": { + "description": "Unexpected error" + } + } + }, + "post": { + "tags": [ + "Patent Reference Data" + ], + "summary": "Search patent application status codes via JSON payload", + "description": "Perform advanced search for patent application status codes using a structured JSON payload. All fields in the request are optional.\n", + "operationId": "Search_Patent_Status_Codes_POST", + "x-ms-summary": "Search patent status codes (POST)", + "x-ms-visibility": "important", + "parameters": [ + { + "name": "body", + "in": "body", + "required": false, + "x-ms-summary": "Request body", + "x-ms-visibility": "important", + "description": "JSON payload defining search filters and pagination.", + "schema": { + "$ref": "#/definitions/StatusCodeSearchRequest" + } + } + ], + "responses": { + "200": { + "description": "Successful response", + "schema": { + "$ref": "#/definitions/StatusCodeSearchResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "403": { + "description": "Forbidden", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "default": { + "description": "Unexpected error" + } + } + } + }, + "/datasets/products/search": { + "get": { + "operationId": "Search_Bulk_DataSets", + "summary": "Search bulk dataset products", + "description": "Retrieve available USPTO bulk datasets with optional filters and search parameters.", + "x-ms-summary": "Search USPTO bulk datasets", + "x-ms-visibility": "important", + "tags": [ + "Bulk DataSets" + ], + "parameters": [ + { + "name": "q", + "in": "query", + "type": "string", + "x-ms-summary": "Search query", + "x-ms-visibility": "important", + "description": "A search query string supporting boolean operators (AND, OR, NOT), wildcards (*), and exact phrases (\"\"). Example: `decisionTypeCodeDescriptionText:Denied OR finalDecidingOfficeName:OFFICE`\n", + "required": false + }, + { + "name": "sort", + "in": "query", + "type": "string", + "x-ms-summary": "Sort field", + "x-ms-visibility": "important", + "description": "Field to sort results by (e.g., `petitionMailDate asc`)." + }, + { + "name": "offset", + "in": "query", + "type": "integer", + "x-ms-summary": "Record offset", + "x-ms-visibility": "important", + "description": "Position in the dataset of the first record to return.", + "default": 0 + }, + { + "name": "limit", + "in": "query", + "type": "integer", + "x-ms-summary": "Result limit", + "x-ms-visibility": "important", + "description": "Maximum number of results to return.", + "default": 25 + }, + { + "name": "facets", + "in": "query", + "type": "string", + "x-ms-summary": "Facets", + "x-ms-visibility": "important", + "description": "Comma-separated list of fields to group (facet) results by." + }, + { + "name": "fields", + "in": "query", + "type": "string", + "x-ms-summary": "Fields", + "x-ms-visibility": "important", + "description": "Comma-separated list of fields to include in the response." + }, + { + "name": "filters", + "in": "query", + "type": "string", + "x-ms-summary": "Filters", + "x-ms-visibility": "important", + "description": "Field-value filters separated by space. Example: `technologyCenter 3600` or `businessEntityStatusCategory 'Small'`.\n" + }, + { + "name": "rangeFilters", + "in": "query", + "type": "string", + "x-ms-summary": "Range filters", + "x-ms-visibility": "important", + "description": "Specify numeric or date range filters using `:` separator. Example: `petitionMailDate 2021-01-01:2025-01-01`\n" + } + ], + "responses": { + "200": { + "description": "Successful response", + "schema": { + "$ref": "#/definitions/BdssResponseBag" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "403": { + "description": "Forbidden", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + } + } + } + }, + "/datasets/products/{productIdentifier}": { + "get": { + "operationId": "Get_Bulk_DataSet_Product", + "summary": "Get bulk dataset product by identifier", + "description": "Retrieve details for a specific USPTO bulk dataset product by its short name (productIdentifier). Optional parameters allow filtering by date range and inclusion of product files.\n", + "x-ms-summary": "Get bulk dataset product by identifier", + "x-ms-visibility": "important", + "tags": [ + "Bulk DataSets" + ], + "parameters": [ + { + "name": "productIdentifier", + "in": "path", + "required": true, + "type": "string", + "x-ms-summary": "Product identifier", + "x-ms-visibility": "important", + "description": "Short name of the bulk dataset product (e.g. BDSS_PETITIONS_2024)." + }, + { + "name": "fileDataFromDate", + "in": "query", + "type": "string", + "format": "date", + "x-ms-summary": "File data start date", + "x-ms-visibility": "important", + "description": "Start date (inclusive) to filter dataset files by date.\n" + }, + { + "name": "fileDataToDate", + "in": "query", + "type": "string", + "format": "date", + "x-ms-summary": "File data end date", + "x-ms-visibility": "important", + "description": "End date (inclusive) to filter dataset files by date.\n" + }, + { + "name": "offset", + "in": "query", + "type": "integer", + "x-ms-summary": "Offset", + "x-ms-visibility": "important", + "description": "Number of product file records to skip.", + "default": 0 + }, + { + "name": "limit", + "in": "query", + "type": "integer", + "x-ms-summary": "Limit", + "x-ms-visibility": "important", + "description": "Number of product file records to return.", + "default": 25 + }, + { + "name": "includeFiles", + "in": "query", + "type": "boolean", + "x-ms-summary": "Include files", + "x-ms-visibility": "important", + "description": "Set to true to include detailed file records in the response; false to omit them.\n", + "default": false + }, + { + "name": "latest", + "in": "query", + "type": "boolean", + "x-ms-summary": "Latest only", + "x-ms-visibility": "important", + "description": "Set to true to return only the latest product file for this dataset.\n", + "default": false + } + ], + "responses": { + "200": { + "description": "Successful response", + "schema": { + "$ref": "#/definitions/BdssResponseProductBag" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "403": { + "description": "Forbidden", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + } + } + } + }, + "/petition/decisions/search": { + "get": { + "operationId": "Search_Petition_Decisions_GET", + "summary": "Search petition decisions (query parameters)", + "description": "Retrieve petition decision data by providing query parameters. Query parameters are optional—if none are supplied, the top 25 records are returned.\n", + "x-ms-summary": "Search petition decisions using query parameters", + "x-ms-visibility": "important", + "tags": [ + "Petition Decision Search" + ], + "parameters": [ + { + "name": "q", + "in": "query", + "type": "string", + "x-ms-summary": "Search query", + "x-ms-visibility": "important", + "description": "Query string supporting Boolean operators (AND, OR, NOT), wildcards (*), and exact phrases (\"\").\n" + }, + { + "name": "sort", + "in": "query", + "type": "string", + "x-ms-summary": "Sort order", + "x-ms-visibility": "important", + "description": "Field name followed by sort direction (asc or desc)." + }, + { + "name": "offset", + "in": "query", + "type": "integer", + "x-ms-summary": "Offset", + "x-ms-visibility": "important", + "description": "Position in the dataset of the first record to return.", + "default": 0 + }, + { + "name": "limit", + "in": "query", + "type": "integer", + "x-ms-summary": "Limit", + "x-ms-visibility": "important", + "description": "Maximum number of records to return.", + "default": 25 + }, + { + "name": "facets", + "in": "query", + "type": "string", + "x-ms-summary": "Facet fields", + "x-ms-visibility": "important", + "description": "Comma-separated list of fields to facet upon.\n" + }, + { + "name": "fields", + "in": "query", + "type": "string", + "x-ms-summary": "Selected fields", + "x-ms-visibility": "important", + "description": "Comma-separated list of fields to include in the response.\n" + }, + { + "name": "filters", + "in": "query", + "type": "string", + "x-ms-summary": "Filters", + "x-ms-visibility": "important", + "description": "Filter results by supplying a field name and value.\n" + }, + { + "name": "rangeFilters", + "in": "query", + "type": "string", + "x-ms-summary": "Range filters", + "x-ms-visibility": "important", + "description": "Filter results by providing numeric or date ranges.\n" + } + ], + "responses": { + "200": { + "description": "Successful response", + "schema": { + "$ref": "#/definitions/PetitionDecisionResponseBag" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "403": { + "description": "Forbidden", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + } + } + }, + "post": { + "operationId": "Search_Petition_Decisions_POST", + "summary": "Search petition decisions (advanced JSON)", + "description": "Retrieve petition decision data using a structured JSON payload. Supports Boolean search, filters, range filters, sorting, field selection, and pagination.\n", + "x-ms-summary": "Search petition decisions using JSON payload", + "x-ms-visibility": "important", + "tags": [ + "Petition Decision Search" + ], + "parameters": [ + { + "name": "body", + "in": "body", + "required": true, + "description": "Petition decision search criteria in JSON format.", + "schema": { + "$ref": "#/definitions/PetitionDecisionSearchRequest" + } + } + ], + "responses": { + "200": { + "description": "Successful response", + "schema": { + "$ref": "#/definitions/PetitionDecisionResponseBag" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "403": { + "description": "Forbidden", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + } + } + } + }, + "/petition/decisions/search/download": { + "get": { + "operationId": "Download_Petition_Decisions_GET", + "summary": "Download petition decision data (query parameters)", + "description": "Retrieve petition decision data by supplying query parameters. Supports optional query parameters and returns the top 25 results by default.\n", + "x-ms-summary": "Download petition decision data using query parameters", + "x-ms-visibility": "important", + "tags": [ + "Petition Decision Search" + ], + "parameters": [ + { + "name": "q", + "in": "query", + "type": "string", + "x-ms-summary": "Search query", + "x-ms-visibility": "important", + "description": "A search query string that accepts Boolean operators (AND, OR, NOT), wildcards (*), and exact phrases (\"\").\n" + }, + { + "name": "sort", + "in": "query", + "type": "string", + "x-ms-summary": "Sort order", + "x-ms-visibility": "important", + "description": "Field name followed by sort order (asc or desc)." + }, + { + "name": "offset", + "in": "query", + "type": "integer", + "x-ms-summary": "Offset", + "x-ms-visibility": "important", + "description": "Dataset position to begin the response from.", + "default": 0 + }, + { + "name": "limit", + "in": "query", + "type": "integer", + "x-ms-summary": "Limit", + "x-ms-visibility": "important", + "description": "Maximum number of records to return.", + "default": 25 + }, + { + "name": "fields", + "in": "query", + "type": "string", + "x-ms-summary": "Selected fields", + "x-ms-visibility": "important", + "description": "Comma-separated list of fields to include in the result." + }, + { + "name": "filters", + "in": "query", + "type": "string", + "x-ms-summary": "Filters", + "x-ms-visibility": "important", + "description": "Filter the results by field name and value. Example: `decisionTypeCodeDescriptionText DENIED`\n" + }, + { + "name": "rangeFilters", + "in": "query", + "type": "string", + "x-ms-summary": "Range filters", + "x-ms-visibility": "important", + "description": "Filter by numeric or date ranges. Example: `petitionMailDate 2021-01-01:2025-01-01`\n" + }, + { + "name": "format", + "in": "query", + "type": "string", + "x-ms-summary": "Download format", + "x-ms-visibility": "important", + "description": "Format of the returned dataset (json or csv).", + "enum": [ + "json", + "csv" + ], + "default": "json" + } + ], + "responses": { + "200": { + "description": "Successful response", + "schema": { + "$ref": "#/definitions/PetitionDecisionResponseBag" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "403": { + "description": "Forbidden", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + } + } + }, + "post": { + "operationId": "Download_Petition_Decisions_POST", + "summary": "Download petition decision data (advanced JSON)", + "description": "Download petition decision data by supplying a structured JSON payload. The response supports JSON or CSV format, based on the `format` parameter.\n", + "x-ms-summary": "Download petition decision data using JSON payload", + "x-ms-visibility": "important", + "tags": [ + "Petition Decision Search" + ], + "parameters": [ + { + "name": "body", + "in": "body", + "required": true, + "x-ms-summary": "Download request body", + "x-ms-visibility": "important", + "description": "JSON payload defining filters, ranges, and format options for petition decision data.", + "schema": { + "$ref": "#/definitions/PetitionDecisionDownloadRequest" + } + } + ], + "responses": { + "200": { + "description": "Successful response", + "schema": { + "$ref": "#/definitions/PetitionDecisionResponseBag" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "403": { + "description": "Forbidden", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + } + } + } + }, + "/petition/decisions/{petitionDecisionRecordIdentifier}": { + "get": { + "operationId": "Get_Petition_Decision_By_Id", + "summary": "Get petition decision by identifier", + "description": "Retrieve detailed petition decision information by its unique petition decision record identifier. Optionally include decision documents in the response using the `includeDocuments` query parameter.\n", + "x-ms-summary": "Get petition decision details by identifier", + "x-ms-visibility": "important", + "tags": [ + "Petition Decision Search" + ], + "parameters": [ + { + "name": "petitionDecisionRecordIdentifier", + "in": "path", + "required": true, + "type": "string", + "x-ms-summary": "Petition Decision Identifier", + "x-ms-visibility": "important", + "description": "Unique petition decision record identifier." + }, + { + "name": "includeDocuments", + "in": "query", + "type": "boolean", + "x-ms-summary": "Include decision documents", + "x-ms-visibility": "important", + "description": "Set to `true` to include petition decision documents in the response, or `false` to omit them.\n", + "default": false + } + ], + "responses": { + "200": { + "description": "Successful response", + "schema": { + "$ref": "#/definitions/PetitionDecisionIdentifierResponseBag" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "403": { + "description": "Forbidden", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + } + } + } + }, + "/patent/applications/text-to-search": { + "post": { + "operationId": "Patent_Text_To_Search", + "summary": "Convert text into structured patent search query", + "description": "Extracts key searchable fields, keywords, and metadata from raw text to create a structured query compatible with `/api/v1/patent/applications/search`. Useful for transforming plain text from abstracts, claims, or invention descriptions into field-aware searches.\n", + "x-ms-summary": "Convert text into structured patent search query", + "x-ms-visibility": "internal", + "x-ip-domain": "Patent", + "x-service-type": [ + "Search", + "Dissemination" + ], + "x-content-type": "Bibliographic data", + "tags": [ + "Patent Search" + ], + "parameters": [ + { + "name": "body", + "in": "body", + "required": true, + "x-ms-summary": "Raw text input", + "x-ms-visibility": "important", + "description": "Text input for conversion into a structured USPTO search query.\n", + "schema": { + "$ref": "#/definitions/TextToSearchRequest" + } + } + ], + "responses": { + "200": { + "description": "Successful conversion", + "schema": { + "$ref": "#/definitions/TextToSearchResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "403": { + "description": "Forbidden", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "404": { + "description": "Not Found", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "$ref": "#/definitions/ErrorResponse" + } + } + } + } + } + }, + "definitions": { + "PatentDataResponse": { + "type": "object", + "properties": { + "totalCount": { + "type": "integer", + "format": "int32", + "example": 25 + }, + "response": { + "type": "array", + "items": { + "type": "object", + "properties": { + "applicationNumberText": { + "type": "string", + "example": "14412875" + }, + "filingDate": { + "type": "string", + "format": "date", + "example": "2023-05-01" + }, + "publicationNumber": { + "type": "string", + "example": "US20230012345A1" + }, + "inventorName": { + "type": "string", + "example": "John Doe" + }, + "assigneeName": { + "type": "string", + "example": "ABC Corporation" + }, + "applicationType": { + "type": "string", + "example": "Utility" + } + } + } + } + } + }, + "ApplicationMetaDataResponse": { + "type": "object", + "properties": { + "count": { + "type": "integer", + "format": "int32", + "example": 1 + }, + "patentFileWrapperDataBag": { + "type": "array", + "items": { + "type": "object", + "properties": { + "applicationNumberText": { + "type": "string", + "example": "14104993", + "description": "Free format of the application number" + }, + "applicationMetaData": { + "$ref": "#/definitions/ApplicationMetaData" + } + } + } + }, + "requestIdentifier": { + "type": "string", + "example": "0ff4c603-a290-4659-8092-f68b408150c4" + } + } + }, + "ApplicationMetaData": { + "type": "object", + "properties": { + "filingDate": { + "type": "string", + "example": "2023-05-01" + }, + "applicationTypeCode": { + "type": "string", + "example": "UTL" + }, + "applicationStatusCode": { + "type": "integer", + "format": "int32", + "example": 150 + }, + "firstApplicantName": { + "type": "string", + "example": "Rockwell Automation" + }, + "firstInventorToFileIndicator": { + "type": "string", + "example": "Y" + }, + "entityStatus": { + "type": "string", + "example": "Small Entity" + }, + "groupArtUnitNumber": { + "type": "string", + "example": "1785" + }, + "docketNumber": { + "type": "string", + "example": "2023-0042" + }, + "publicationCategoryBag": { + "type": "array", + "items": { + "type": "string" + }, + "example": [ + "Pre-Grant Publication" + ] + }, + "examinerName": { + "type": "string", + "example": "Jane Smith" + }, + "patentNumber": { + "type": "string", + "example": "US20230012345A1" + } + } + }, + "PatentAdjustmentResponse": { + "type": "object", + "properties": { + "count": { + "type": "integer", + "format": "int32", + "example": 1 + }, + "patentFileWrapperDataBag": { + "type": "array", + "items": { + "type": "object", + "properties": { + "applicationNumberText": { + "type": "string", + "example": "14104993", + "description": "Free format of application number" + }, + "patentTermAdjustmentData": { + "$ref": "#/definitions/PatentTermAdjustment" + } + } + } + }, + "requestIdentifier": { + "type": "string", + "example": "0ff4c603-a290-4659-8092-f68b408150c4" + } + } + }, + "PatentTermAdjustment": { + "type": "object", + "properties": { + "applicationNumberText": { + "type": "string", + "example": "14104993" + }, + "totalDays": { + "type": "integer", + "example": 115, + "description": "Total patent term adjustment days granted" + }, + "aDelayDays": { + "type": "integer", + "example": 40, + "description": "Number of days delayed under USPTO A delay category" + }, + "bDelayDays": { + "type": "integer", + "example": 65, + "description": "Number of days delayed under USPTO B delay category" + }, + "cDelayDays": { + "type": "integer", + "example": 10, + "description": "Number of days delayed under USPTO C delay category" + }, + "overlapDays": { + "type": "integer", + "example": 5, + "description": "Days overlapping between categories, subtracted from total" + }, + "issueDate": { + "type": "string", + "format": "date", + "example": "2023-09-15" + }, + "publicationDate": { + "type": "string", + "format": "date", + "example": "2023-05-10" + }, + "calculationDate": { + "type": "string", + "format": "date", + "example": "2023-10-02" + }, + "status": { + "type": "string", + "example": "Final", + "description": "Current status of patent term adjustment calculation" + } + } + }, + "PatentAssignmentResponse": { + "type": "object", + "properties": { + "count": { + "type": "integer", + "format": "int32", + "example": 1 + }, + "patentFileWrapperDataBag": { + "type": "array", + "items": { + "type": "object", + "properties": { + "applicationNumberText": { + "type": "string", + "example": "14104993", + "description": "Free format of application number" + }, + "assignmentBag": { + "type": "array", + "items": { + "$ref": "#/definitions/Assignment" + } + } + } + } + }, + "requestIdentifier": { + "type": "string", + "example": "0ff4c603-a290-4659-8092-f68b408150c4" + } + } + }, + "Assignment": { + "type": "object", + "properties": { + "reelNumber": { + "type": "integer", + "format": "int32", + "example": "035678", + "description": "Reel number identifying the recorded assignment" + }, + "frameNumber": { + "type": "integer", + "format": "int32", + "example": 123, + "description": "Frame number within the reel" + }, + "recordedDate": { + "type": "string", + "format": "date", + "example": "2023-04-15", + "description": "Date assignment was recorded" + }, + "executionDate": { + "type": "string", + "format": "date", + "example": "2023-04-01", + "description": "Date assignment was executed" + }, + "conveyanceText": { + "type": "string", + "example": "Assignment of assignor's interest", + "description": "Type of conveyance or assignment" + }, + "assignorName": { + "type": "string", + "example": "John Doe", + "description": "Name of assignor" + }, + "assigneeName": { + "type": "string", + "example": "XYZ Innovations LLC", + "description": "Name of assignee" + }, + "correspondenceAddress": { + "type": "string", + "example": "123 Innovation Drive, Boston, MA 02108", + "description": "Correspondence address associated with assignment" + }, + "documentIdentifier": { + "type": "string", + "example": "REEL035678FRAME0123", + "description": "Concatenated reel and frame identifier" + }, + "publicationDate": { + "type": "string", + "format": "date", + "example": "2023-04-22", + "description": "Date assignment data was published" + } + } + }, + "PatentAttorneyResponse": { + "type": "object", + "properties": { + "count": { + "type": "integer", + "format": "int32", + "example": 1 + }, + "patentFileWrapperDataBag": { + "type": "array", + "items": { + "type": "object", + "properties": { + "applicationNumberText": { + "type": "string", + "example": "14104993", + "description": "Free format of application number" + }, + "recordAttorney": { + "$ref": "#/definitions/RecordAttorney" + } + } + } + }, + "requestIdentifier": { + "type": "string", + "example": "0ff4c603-a290-4659-8092-f68b408150c4" + } + } + }, + "RecordAttorney": { + "type": "object", + "properties": { + "attorneyDocketNumber": { + "type": "string", + "example": "A2023-045", + "description": "Attorney docket number associated with the application" + }, + "attorneyName": { + "type": "string", + "example": "Jane Q. Patent", + "description": "Name of the attorney of record" + }, + "registrationNumber": { + "type": "string", + "example": "57,123", + "description": "USPTO registration number for the attorney or agent" + }, + "lawFirmName": { + "type": "string", + "example": "Patent Pros LLP", + "description": "Law firm or organization representing the applicant" + }, + "correspondenceAddress": { + "type": "string", + "example": "456 Legal Way, Arlington, VA 22203", + "description": "Correspondence address on record" + }, + "phoneNumber": { + "type": "string", + "example": "(703) 555-1234", + "description": "Phone number for correspondence" + }, + "emailAddress": { + "type": "string", + "example": "jane.patent@patentpros.com", + "description": "Contact email for attorney or agent" + }, + "effectiveDate": { + "type": "string", + "format": "date", + "example": "2023-05-12", + "description": "Effective date for attorney of record entry" + }, + "status": { + "type": "string", + "example": "Active", + "description": "Current status of attorney or agent record" + } + } + }, + "PatentContinuityResponse": { + "type": "object", + "properties": { + "count": { + "type": "integer", + "format": "int32", + "example": 1 + }, + "patentFileWrapperDataBag": { + "type": "array", + "items": { + "type": "object", + "properties": { + "applicationNumberText": { + "type": "string", + "example": "14104993", + "description": "Free format of application number" + }, + "parentContinuityBag": { + "type": "array", + "items": { + "$ref": "#/definitions/ParentContinuityData" + } + }, + "childContinuityBag": { + "type": "array", + "items": { + "$ref": "#/definitions/ChildContinuityData" + } + } + } + } + }, + "requestIdentifier": { + "type": "string", + "example": "07c5c24d-bf8e-458c-9427-a038500d6e98" + } + } + }, + "ParentContinuityData": { + "type": "object", + "properties": { + "parentApplicationNumberText": { + "type": "string", + "example": "12543210", + "description": "Parent application number" + }, + "relationType": { + "type": "string", + "example": "Continuation", + "description": "Type of parent relationship" + }, + "filingDate": { + "type": "string", + "format": "date", + "example": "2018-09-12" + }, + "patentNumber": { + "type": "string", + "example": "US10012345B2" + }, + "publicationNumber": { + "type": "string", + "example": "US20190234567A1" + }, + "issueDate": { + "type": "string", + "format": "date", + "example": "2021-03-15" + } + } + }, + "ChildContinuityData": { + "type": "object", + "properties": { + "childApplicationNumberText": { + "type": "string", + "example": "15567891", + "description": "Child application number" + }, + "relationType": { + "type": "string", + "example": "Divisional", + "description": "Type of child relationship" + }, + "filingDate": { + "type": "string", + "format": "date", + "example": "2022-01-04" + }, + "patentNumber": { + "type": "string", + "example": "US11234567B2" + }, + "publicationNumber": { + "type": "string", + "example": "US20220123456A1" + }, + "issueDate": { + "type": "string", + "format": "date", + "example": "2024-05-19" + } + } + }, + "PatentForeignPriorityResponse": { + "type": "object", + "properties": { + "count": { + "type": "integer", + "format": "int32", + "example": 1 + }, + "patentFileWrapperDataBag": { + "type": "array", + "items": { + "type": "object", + "properties": { + "applicationNumberText": { + "type": "string", + "example": "14104993", + "description": "Free format of application number" + }, + "foreignPriorityBag": { + "type": "array", + "items": { + "$ref": "#/definitions/ForeignPriority" + } + } + } + } + }, + "requestIdentifier": { + "type": "string", + "example": "07c5c24d-bf8e-458c-9427-a038500d6e98" + } + } + }, + "ForeignPriority": { + "type": "object", + "properties": { + "foreignApplicationNumberText": { + "type": "string", + "example": "GB2018001234", + "description": "Foreign priority application number" + }, + "foreignFilingDate": { + "type": "string", + "format": "date", + "example": "2018-04-12", + "description": "Date of foreign priority filing" + }, + "foreignCountryCode": { + "type": "string", + "example": "GB", + "description": "Two-letter ISO country code for foreign filing" + }, + "foreignCountryName": { + "type": "string", + "example": "United Kingdom", + "description": "Name of the foreign country" + }, + "foreignPatentOffice": { + "type": "string", + "example": "UKIPO", + "description": "Foreign patent office identifier" + }, + "kindCode": { + "type": "string", + "example": "A", + "description": "Kind code for foreign publication" + }, + "relationType": { + "type": "string", + "example": "Priority", + "description": "Relationship type (e.g., Priority, Parent)" + }, + "internationalFilingIndicator": { + "type": "string", + "example": "N", + "description": "Indicates if the filing was international (PCT)" + }, + "translationRequired": { + "type": "boolean", + "example": false, + "description": "Indicates whether a translation is required" + } + } + }, + "PatentTransactionResponse": { + "type": "object", + "properties": { + "count": { + "type": "integer", + "format": "int32", + "example": 1 + }, + "patentFileWrapperDataBag": { + "type": "array", + "items": { + "type": "object", + "properties": { + "applicationNumberText": { + "type": "string", + "example": "14104993", + "description": "Free format of application number" + }, + "eventDataBag": { + "type": "array", + "items": { + "$ref": "#/definitions/EventData" + } + } + } + } + }, + "requestIdentifier": { + "type": "string", + "example": "07c5c24d-bf8e-458c-9427-a038500d6e98" + } + } + }, + "EventData": { + "type": "object", + "properties": { + "eventCode": { + "type": "string", + "example": "PG-Pub Issue Notification", + "description": "Code or label for the prosecution event" + }, + "eventDescription": { + "type": "string", + "example": "Publication of patent application", + "description": "Text description of the event" + }, + "eventDate": { + "type": "string", + "example": "2023-04-10", + "description": "Date when the event occurred" + }, + "eventCategory": { + "type": "string", + "example": "Publication", + "description": "Category of event" + }, + "documentCode": { + "type": "string", + "example": "PUB", + "description": "Code identifying related document" + }, + "documentName": { + "type": "string", + "example": "Patent Application Publication", + "description": "Name of the related document" + }, + "correspondentName": { + "type": "string", + "example": "USPTO Examiner John Smith", + "description": "Correspondent associated with event" + }, + "transactionId": { + "type": "string", + "example": "TXN-123456789", + "description": "Unique identifier for transaction" + }, + "fileSize": { + "type": "integer", + "example": 24567, + "description": "File size in bytes of associated document, if any" + }, + "downloadUrl": { + "type": "string", + "example": "https://developer.uspto.gov/data/patent/transaction/TXN-123456789", + "description": "URL to download associated document" + } + } + }, + "PatentDocumentResponse": { + "type": "object", + "properties": { + "count": { + "type": "integer", + "format": "int32", + "example": 5 + }, + "documents": { + "type": "array", + "items": { + "$ref": "#/definitions/DocumentBag" + } + }, + "requestIdentifier": { + "type": "string", + "example": "07c5c24d-bf8e-458c-9427-a038500d6e98" + } + } + }, + "DocumentBag": { + "type": "object", + "properties": { + "documentCode": { + "type": "string", + "example": "WFEE", + "description": "Code identifying the type of document" + }, + "documentDescription": { + "type": "string", + "example": "Fee Worksheet", + "description": "Description of the document type" + }, + "documentCategory": { + "type": "string", + "example": "Outgoing", + "description": "Category of document (Incoming/Outgoing)" + }, + "officialDate": { + "type": "string", + "format": "date", + "example": "2023-07-12", + "description": "Official date associated with the document" + }, + "createDate": { + "type": "string", + "format": "date", + "example": "2023-07-10", + "description": "Date document was created in system" + }, + "fileSize": { + "type": "integer", + "example": 28573, + "description": "File size of the document in bytes" + }, + "documentUrl": { + "type": "string", + "example": "https://developer.uspto.gov/patent/document/WFEE_16330077.pdf", + "description": "URL for retrieving or downloading the document" + }, + "documentPageCount": { + "type": "integer", + "format": "int32", + "example": 3, + "description": "Number of pages in the document" + }, + "submitterName": { + "type": "string", + "example": "Applicant", + "description": "Name of the submitting party" + }, + "examinerName": { + "type": "string", + "example": "John Doe", + "description": "Examiner associated with the document" + }, + "artUnit": { + "type": "string", + "example": "1785", + "description": "Art unit responsible for the document" + } + } + }, + "PatentAssociatedDocumentsResponse": { + "type": "object", + "properties": { + "count": { + "type": "integer", + "format": "int32", + "example": 1 + }, + "patentFileWrapperDataBag": { + "type": "array", + "items": { + "type": "object", + "properties": { + "applicationNumberText": { + "type": "string", + "example": "14104993", + "description": "Free format of application number" + }, + "pgpubDocumentMetaData": { + "$ref": "#/definitions/PGPubFileMetaData" + }, + "grantDocumentMetaData": { + "$ref": "#/definitions/GrantFileMetaData" + } + } + } + }, + "requestIdentifier": { + "type": "string", + "example": "07c5c24d-bf8e-458c-9427-a038500d6e98" + } + } + }, + "PGPubFileMetaData": { + "type": "object", + "properties": { + "publicationNumber": { + "type": "string", + "example": "US20230123456A1", + "description": "Publication number for the pre-grant publication" + }, + "publicationDate": { + "type": "string", + "format": "date", + "example": "2023-04-20", + "description": "Date of the pre-grant publication" + }, + "kindCode": { + "type": "string", + "example": "A1", + "description": "Kind code for publication" + }, + "title": { + "type": "string", + "example": "Method for Optimizing Widget Production", + "description": "Title of the publication" + }, + "applicantName": { + "type": "string", + "example": "Innovatech LLC", + "description": "Applicant or assignee listed on publication" + }, + "documentUrl": { + "type": "string", + "example": "https://developer.uspto.gov/patent/document/US20230123456A1.pdf", + "description": "URL to retrieve publication document" + } + } + }, + "GrantFileMetaData": { + "type": "object", + "properties": { + "patentNumber": { + "type": "string", + "example": "US11234567B2", + "description": "Granted patent number" + }, + "grantDate": { + "type": "string", + "format": "date", + "example": "2024-01-10", + "description": "Date the patent was granted" + }, + "kindCode": { + "type": "string", + "example": "B2", + "description": "Kind code for granted patent" + }, + "title": { + "type": "string", + "example": "Method for Optimizing Widget Production", + "description": "Title of the granted patent" + }, + "assigneeName": { + "type": "string", + "example": "Innovatech LLC", + "description": "Assignee listed on grant" + }, + "issueClassification": { + "type": "string", + "example": "G06F17/30", + "description": "Primary classification of granted patent" + }, + "documentUrl": { + "type": "string", + "example": "https://developer.uspto.gov/patent/document/US11234567B2.pdf", + "description": "URL to retrieve the granted patent document" + } + } + }, + "StatusCodeSearchResponse": { + "type": "object", + "description": "Response structure for patent status code search results.", + "properties": { + "count": { + "type": "integer", + "format": "int32", + "description": "Number of status codes returned.", + "example": 25 + }, + "patentFileWrapperDataBag": { + "type": "array", + "description": "Array of patent status code records.", + "items": { + "type": "object", + "properties": { + "applicationStatusCode": { + "type": "integer", + "format": "int32", + "description": "Unique numeric or alphanumeric status code.", + "example": 150 + }, + "applicationStatusDescriptionText": { + "type": "string", + "description": "Description of the application status.", + "example": "Patented Case" + }, + "statusCategoryName": { + "type": "string", + "description": "Status category grouping, if available.", + "example": "Final Disposition" + }, + "statusEffectiveDate": { + "type": "string", + "format": "date", + "description": "Effective date of this status code.", + "example": "2022-03-15" + }, + "statusTerminationIndicator": { + "type": "boolean", + "description": "Indicates whether the status represents termination of prosecution.", + "example": false + }, + "requestIdentifier": { + "type": "string", + "description": "Unique request identifier for tracing API calls.", + "example": "07c5c24d-bf8e-458c-9427-a038500d6e98" + } + } + } + }, + "requestIdentifier": { + "type": "string", + "description": "Unique ID for the entire API call.", + "example": "07c5c24d-bf8e-458c-9427-a038500d6e98" + } + } + }, + "StatusCodeSearchRequest": { + "type": "object", + "description": "JSON payload used to search patent application status codes and their descriptions.", + "properties": { + "q": { + "type": "string", + "description": "Search query supporting boolean operators (AND, OR, NOT), wildcards (*), and exact phrases (\"\"). Matches across status code and description fields.\n", + "example": "applicationStatusDescriptionText:Preexam OR applicationStatusCode:50" + }, + "filters": { + "type": "array", + "description": "Optional filters to narrow results by field values.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Field name to filter by.", + "example": "applicationStatusDescriptionText" + }, + "value": { + "type": "array", + "description": "List of filter values for the specified field.", + "items": { + "type": "string", + "example": "Preexam" + } + } + } + } + }, + "rangeFilters": { + "type": "array", + "description": "Optional range filters for numeric or date fields.", + "items": { + "type": "object", + "properties": { + "field": { + "type": "string", + "description": "Field name for the range filter.", + "example": "applicationStatusCode" + }, + "valueFrom": { + "type": "string", + "description": "Starting value of the range (inclusive).", + "example": "100" + }, + "valueTo": { + "type": "string", + "description": "Ending value of the range (inclusive).", + "example": "200" + } + } + } + }, + "sort": { + "type": "array", + "description": "Sorting criteria for the returned results.", + "items": { + "type": "object", + "properties": { + "field": { + "type": "string", + "description": "Field name to sort by.", + "example": "applicationStatusCode" + }, + "order": { + "type": "string", + "description": "Sort order (asc or desc).", + "enum": [ + "asc", + "desc" + ], + "example": "asc" + } + } + } + }, + "pagination": { + "type": "object", + "description": "Pagination settings to control result offset and limit.", + "properties": { + "offset": { + "type": "integer", + "description": "Offset of the first record to return.", + "example": 0 + }, + "limit": { + "type": "integer", + "description": "Maximum number of records to return.", + "example": 25 + } + } + } + } + }, + "BdssResponseProductBag": { + "type": "object", + "description": "Detailed response for a specific USPTO bulk dataset product.", + "properties": { + "count": { + "type": "integer", + "format": "int32", + "description": "Number of product file records returned.", + "example": 5 + }, + "patentFileWrapperDataBag": { + "type": "array", + "description": "Array containing product metadata and optional file details.", + "items": { + "type": "object", + "properties": { + "productIdentifier": { + "type": "string", + "description": "Unique identifier for the dataset product (short name).", + "example": "BDSS_PETITIONS_2024" + }, + "productName": { + "type": "string", + "description": "Human-readable name of the product.", + "example": "USPTO Petitions Data" + }, + "productDescription": { + "type": "string", + "description": "Description of dataset contents.", + "example": "Petitions data including application numbers, petition types, and outcomes." + }, + "productVersion": { + "type": "string", + "description": "Dataset version.", + "example": "v1.3" + }, + "publicationDate": { + "type": "string", + "format": "date", + "description": "Date of dataset publication.", + "example": "2024-08-14" + }, + "productType": { + "type": "string", + "description": "Dataset file type (e.g., XML, JSON, CSV).", + "example": "JSON" + }, + "recordCount": { + "type": "integer", + "format": "int32", + "description": "Number of records in the dataset.", + "example": 2350 + }, + "downloadUrl": { + "type": "string", + "description": "Direct link to download the dataset.", + "example": "https://developer.uspto.gov/ibd-api/downloads/petitions/bdss_petitions_2024.zip" + }, + "checksum": { + "type": "string", + "description": "File checksum for integrity verification.", + "example": "a1b2c3d4e5f6..." + }, + "includeFiles": { + "type": "boolean", + "description": "Whether product files were included in the response.", + "example": true + }, + "productFiles": { + "type": "array", + "description": "List of associated dataset files (if included).", + "items": { + "type": "object", + "properties": { + "fileName": { + "type": "string", + "description": "Dataset file name.", + "example": "petitions_data_2024_01.json" + }, + "fileSize": { + "type": "integer", + "description": "File size in bytes.", + "example": 2456789 + }, + "fileDataDate": { + "type": "string", + "format": "date", + "description": "Date associated with the file’s dataset content.", + "example": "2024-01-01" + }, + "fileUrl": { + "type": "string", + "description": "Direct link to download the file.", + "example": "https://developer.uspto.gov/ibd-api/downloads/petitions/petitions_data_2024_01.json" + }, + "checksum": { + "type": "string", + "description": "File checksum for verification.", + "example": "b7e2c5d99f7c..." + } + } + } + }, + "requestIdentifier": { + "type": "string", + "description": "Unique request identifier for tracing.", + "example": "07c5c24d-bf8e-458c-9427-a038500d6e98" + } + } + } + } + } + }, + "BdssResponseBag": { + "type": "object", + "description": "Response structure for USPTO Bulk DataSet Search results.", + "properties": { + "count": { + "type": "integer", + "format": "int32", + "description": "Number of dataset products returned.", + "example": 25 + }, + "patentFileWrapperDataBag": { + "type": "array", + "description": "Array of dataset metadata objects.", + "items": { + "type": "object", + "properties": { + "productCode": { + "type": "string", + "description": "Unique product or dataset identifier.", + "example": "BDSS_PETITIONS_2024" + }, + "productName": { + "type": "string", + "description": "Human-readable name of the dataset product.", + "example": "USPTO Petitions Data" + }, + "productDescription": { + "type": "string", + "description": "Description of the dataset content.", + "example": "Petitions data including application numbers and outcomes." + }, + "productVersion": { + "type": "string", + "description": "Dataset version number.", + "example": "v1.3" + }, + "productType": { + "type": "string", + "description": "Type of dataset (e.g., XML, JSON, CSV).", + "example": "JSON" + }, + "publicationDate": { + "type": "string", + "format": "date", + "description": "Date of dataset publication.", + "example": "2024-08-14" + }, + "recordCount": { + "type": "integer", + "format": "int32", + "description": "Number of records available in the dataset.", + "example": 2350 + }, + "downloadUrl": { + "type": "string", + "description": "Direct URL for dataset download.", + "example": "https://developer.uspto.gov/ibd-api/downloads/petitions/bdss_petitions_2024.zip" + }, + "checksum": { + "type": "string", + "description": "SHA or MD5 checksum for dataset file verification.", + "example": "a1b2c3d4e5f6..." + }, + "requestIdentifier": { + "type": "string", + "description": "Unique request ID for traceability.", + "example": "07c5c24d-bf8e-458c-9427-a038500d6e98" + } + } + } + }, + "requestIdentifier": { + "type": "string", + "description": "Unique request identifier for the API call.", + "example": "07c5c24d-bf8e-458c-9427-a038500d6e98" + } + } + }, + "PetitionDecisionSearchRequest": { + "type": "object", + "description": "JSON payload for searching petition decisions.", + "properties": { + "q": { + "type": "string", + "description": "Search text with Boolean operators or field-based queries.", + "example": "decisionTypeCodeDescriptionText:Denied" + }, + "filters": { + "type": "array", + "description": "Array of field-value filters.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "example": "businessEntityStatusCategory" + }, + "value": { + "type": "array", + "items": { + "type": "string", + "example": "Small" + } + } + } + } + }, + "rangeFilters": { + "type": "array", + "description": "Array of date or numeric range filters.", + "items": { + "type": "object", + "properties": { + "field": { + "type": "string", + "example": "petitionMailDate" + }, + "valueFrom": { + "type": "string", + "example": "2021-01-01T00:00:00.000Z" + }, + "valueTo": { + "type": "string", + "example": "2025-01-01T00:00:00.000Z" + } + } + } + }, + "sort": { + "type": "array", + "description": "Sorting order definition.", + "items": { + "type": "object", + "properties": { + "field": { + "type": "string", + "example": "petitionMailDate" + }, + "order": { + "type": "string", + "example": "desc" + } + } + } + }, + "fields": { + "type": "array", + "description": "List of fields to include in the response.", + "items": { + "type": "string" + }, + "example": [ + "petitionDecisionRecordIdentifier", + "petitionMailDate", + "decisionTypeCodeDescriptionText" + ] + }, + "pagination": { + "type": "object", + "properties": { + "offset": { + "type": "integer", + "example": 0 + }, + "limit": { + "type": "integer", + "example": 25 + } + } + }, + "facets": { + "type": "array", + "description": "List of field names to generate facets for.", + "items": { + "type": "string" + }, + "example": [ + "decisionTypeCodeDescriptionText", + "businessEntityStatusCategory" + ] + } + } + }, + "PetitionDecisionResponseBag": { + "type": "object", + "description": "Petition decision search response.", + "properties": { + "count": { + "type": "integer", + "format": "int32", + "description": "Number of matching records.", + "example": 25 + }, + "petitionDecisionDataBag": { + "type": "array", + "description": "Array of petition decision records.", + "items": { + "type": "object", + "properties": { + "petitionDecisionRecordIdentifier": { + "type": "string", + "description": "Unique identifier for the petition decision record.", + "example": "PD-2024-00567" + }, + "patentNumber": { + "type": "string", + "description": "Patent number associated with the petition.", + "example": "11223344" + }, + "firstApplicantName": { + "type": "string", + "description": "Name of the first applicant.", + "example": "John Doe" + }, + "petitionMailDate": { + "type": "string", + "description": "Petition mail date.", + "example": "2024-01-15" + }, + "decisionTypeCodeDescriptionText": { + "type": "string", + "description": "Decision outcome.", + "example": "Denied" + }, + "decisionMailDate": { + "type": "string", + "description": "Decision mail date.", + "example": "2024-02-01" + }, + "finalDecidingOfficeName": { + "type": "string", + "description": "Name of the final deciding office.", + "example": "Office of Petitions" + }, + "decisionDate": { + "type": "string", + "description": "Decision date.", + "example": "2024-02-01" + }, + "technologyCenter": { + "type": "string", + "description": "Technology center associated with the petition.", + "example": "3600" + } + } + } + }, + "facets": { + "type": "object", + "description": "Faceted field counts." + }, + "requestIdentifier": { + "type": "string", + "description": "Unique identifier for the API request.", + "example": "07c5c24d-bf8e-458c-9427-a038500d6e98" + } + } + }, + "PetitionDecisionDownloadRequest": { + "type": "object", + "description": "JSON payload for downloading petition decision data. Similar to the search request but allows specifying the output format.\n", + "properties": { + "q": { + "type": "string", + "description": "Query string with Boolean or field-based search.", + "example": "decisionTypeCodeDescriptionText:Denied" + }, + "filters": { + "type": "array", + "description": "List of field-value filters.", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "example": "decisionTypeCodeDescriptionText" + }, + "value": { + "type": "array", + "items": { + "type": "string", + "example": "DENIED" + } + } + } + } + }, + "rangeFilters": { + "type": "array", + "description": "List of date or numeric range filters.", + "items": { + "type": "object", + "properties": { + "field": { + "type": "string", + "example": "petitionMailDate" + }, + "valueFrom": { + "type": "string", + "example": "2021-01-01T00:00:00.000Z" + }, + "valueTo": { + "type": "string", + "example": "2025-01-01T00:00:00.000Z" + } + } + } + }, + "sort": { + "type": "array", + "description": "Sort order configuration.", + "items": { + "type": "object", + "properties": { + "field": { + "type": "string", + "example": "petitionMailDate" + }, + "order": { + "type": "string", + "example": "desc" + } + } + } + }, + "fields": { + "type": "array", + "description": "Fields to include in the output.", + "items": { + "type": "string" + }, + "example": [ + "petitionDecisionRecordIdentifier", + "petitionMailDate", + "decisionTypeCodeDescriptionText" + ] + }, + "pagination": { + "type": "object", + "properties": { + "offset": { + "type": "integer", + "example": 0 + }, + "limit": { + "type": "integer", + "example": 25 + } + } + }, + "facets": { + "type": "array", + "description": "Optional facets to compute aggregations.", + "items": { + "type": "string" + }, + "example": [ + "decisionTypeCodeDescriptionText", + "businessEntityStatusCategory" + ] + }, + "format": { + "type": "string", + "description": "Format of the returned data.", + "enum": [ + "json", + "csv" + ], + "example": "csv" + } + } + }, + "PetitionDecisionIdentifierResponseBag": { + "type": "object", + "description": "Response object containing petition decision details for a specific identifier.", + "properties": { + "petitionDecisionRecordIdentifier": { + "type": "string", + "description": "Unique identifier for the petition decision record.", + "example": "6779f1be-0f3b-5775-b9d3-dcfdb83171c3" + }, + "patentNumber": { + "type": "string", + "description": "Patent number associated with the petition decision.", + "example": "11445522" + }, + "firstApplicantName": { + "type": "string", + "description": "Name of the first applicant.", + "example": "John Doe" + }, + "petitionMailDate": { + "type": "string", + "description": "Petition mail date.", + "example": "2024-01-05" + }, + "decisionDate": { + "type": "string", + "description": "Date of the decision.", + "example": "2024-02-15" + }, + "decisionMailDate": { + "type": "string", + "description": "Date the decision was mailed.", + "example": "2024-02-16" + }, + "decisionTypeCodeDescriptionText": { + "type": "string", + "description": "Description of the decision type.", + "example": "Denied" + }, + "finalDecidingOfficeName": { + "type": "string", + "description": "Name of the office or division that made the final decision.", + "example": "Office of Petitions" + }, + "petitionDecisionDocuments": { + "type": "array", + "description": "List of decision document metadata (included if `includeDocuments=true`).", + "items": { + "type": "object", + "properties": { + "documentName": { + "type": "string", + "example": "Decision_Letter.pdf" + }, + "documentType": { + "type": "string", + "example": "PDF" + }, + "documentSize": { + "type": "string", + "example": "85KB" + }, + "documentUrl": { + "type": "string", + "example": "https://bulkdata.uspto.gov/petitions/documents/6779f1be-0f3b-5775.pdf" + } + } + } + }, + "requestIdentifier": { + "type": "string", + "description": "Unique identifier for the API request.", + "example": "07c5c24d-bf8e-458c-9427-a038500d6e98" + } + } + }, + "TextToSearchRequest": { + "type": "object", + "description": "Request payload for text-to-search endpoint.", + "properties": { + "text": { + "type": "string", + "description": "The input text to be analyzed for extraction of searchable patent fields and keywords.\n", + "example": "An apparatus for desalinating seawater using graphene-based membranes and low-pressure systems.\n" + } + } + }, + "TextToSearchResponse": { + "type": "object", + "description": "Response containing extracted keywords, inferred fields, and a formatted query.", + "properties": { + "originalText": { + "type": "string", + "description": "Original input text submitted by the user.", + "example": "An apparatus for desalinating seawater using graphene-based membranes." + }, + "extractedKeywords": { + "type": "array", + "description": "List of identified key terms from the input text.", + "items": { + "type": "string" + }, + "example": [ + "desalination", + "graphene", + "membrane", + "seawater" + ] + }, + "inferredFields": { + "type": "array", + "description": "List of inferred patent search fields and their possible values.", + "items": { + "type": "object", + "properties": { + "field": { + "type": "string", + "example": "inventionTitle" + }, + "value": { + "type": "string", + "example": "graphene-based desalination system" + } + } + } + }, + "formattedQuery": { + "type": "string", + "description": "A USPTO-compatible search string formatted for use in `/api/v1/patent/applications/search`.\n", + "example": "inventionTitle:graphene AND abstract:desalination AND claims:membrane" + }, + "requestIdentifier": { + "type": "string", + "description": "Unique request tracking identifier.", + "example": "07c5c24d-bf8e-458c-9427-a038500d6e98" + } + } + }, + "ErrorResponse": { + "type": "object", + "properties": { + "code": { + "type": "integer", + "format": "int32" + }, + "error": { + "type": "string" + }, + "errorDetails": { + "type": "string" + }, + "requestIdentifier": { + "type": "string" + } + } + } + } +} \ No newline at end of file diff --git a/independent-publisher-connectors/US PTO/apiProperties.json b/independent-publisher-connectors/US PTO/apiProperties.json new file mode 100644 index 0000000000..86a0180951 --- /dev/null +++ b/independent-publisher-connectors/US PTO/apiProperties.json @@ -0,0 +1,20 @@ +{ + "properties": { + "connectionParameters": { + "api_key": { + "type": "securestring", + "uiDefinition": { + "displayName": "API Key", + "description": "API key provided by the U.S. Patent and Trademark Office (USPTO). You can request one from developer.uspto.gov.", + "tooltip": "Provide your USPTO API key.", + "constraints": { + "required": "true" + } + } + } + }, + "iconBrandColor": "#da3b01", + "publisher": "Dan Romano", + "stackOwner": "U.S. Patent and Trademark Office (USPTO)" + } +} diff --git a/independent-publisher-connectors/US PTO/readme.md b/independent-publisher-connectors/US PTO/readme.md new file mode 100644 index 0000000000..0ea5294fb4 --- /dev/null +++ b/independent-publisher-connectors/US PTO/readme.md @@ -0,0 +1,123 @@ +# U.S. Patent and Trademark Office (Independent Publisher) + +## Publisher: Dan Romano (swolcat) + +## Prerequisites + +You must have a registered developer account with the [U.S. Patent and Trademark Office](https://developer.uspto.gov) to obtain an API key. + +You can sign up and retrieve your key from the **USPTO API Developer Hub**. + +## Supported Operations + +The connector provides access to USPTO’s patent bibliographic and file wrapper data services. +It supports both **query parameter (GET)** and **structured JSON payload (POST)** searches for flexible, high-volume patent data retrieval. + +### Patent Search + +- `GET /applications/search` - Search for patent applications using query parameters (`q`, `filters`, `rangeFilters`, `sort`, etc.). + Returns the top 25 records by default when no parameters are specified. + +- `POST /applications/search`- Perform an advanced search using a structured JSON payload with filters, range filters, pagination, and field selection. + Example: + +- `GET /applications/search/download` - Retrieve search results in download format using query parameters. + +- `POST /applications/search/download` - Download the search results in json or csv format using a similar payload as the search POST endpoint. + +### Patent Application Details + +Each of the following endpoints retrieves specific data associated with a given patent application number ({applicationNumberText}): + +- `GET /{applicationNumberText}` - Get patent by application number + +- `GET /{applicationNumberText}/meta-data` – Bibliographic metadata for a patent application. + +- `GET /{applicationNumberText}/adjustment` – Term adjustment information. + +- `GET /{applicationNumberText}/assignment` – Assignment and ownership data. + +- `GET /{applicationNumberText}/attorney` – Attorney and correspondence details. + +- `GET /{applicationNumberText}/continuity` – Continuity data (parent and child applications). + +- `GET /{applicationNumberText}/foreign-priority` – Foreign priority claim details. + +- `GET /{applicationNumberText}/transactions` – Application transaction history. + +- `GET /{applicationNumberText}/documents` – Published file wrapper documents. + +- `GET /{applicationNumberText}/associated-documents` – Related publication (PGPub or grant) metadata. + +### Patent Reference Data + +- `GET /patent/status-codes` – Retrieve status codes and their definitions used in USPTO records. + +- `POST /patent/status-codes` – Search patent application status codes via JSON payload. + +### Dataset Search + +- `GET /datasets/products/search` – Search for USPTO product datasets. + +- `GET /datasets/products/{productIdentifier}` – Retrieve metadata for a specific dataset. + +### Petition Decision Data + +- `GET /petition/decisions/search` – Search petition decision records (query parameters). + +- `POST /petition/decisions/search` – Search petition decision records (JSON). + +- `GET /petition/decisions/search/download` – Download petition decisions (query parameters). + +- `POST /petition/decisions/search/download` – Download petition decisions (JSON). + +- `GET /petition/decisions/{petitionDecisionRecordIdentifier}` – Retrieve a specific petition decision record. + +### Text-to-Search + +- `POST /patent/applications/text-to-search` – Accept text input and return matching patent application results. + +## Obtaining Credentials + +- Official USPTO API Reference can be found [here](https://developer.uspto.gov/api-catalog). + +## Getting Started + +[Official site](https://data.uspto.gov/home) + +[Official USPTO API Reference](https://data.uspto.gov/swagger/index.html) + +- Navigate to the USPTO Developer Hub. +- Register or log in to your developer account. +- Request an API key for the Patent Data APIs.Note: API Key is required. Obtain an API key [here](https://data.uspto.gov/myodp). +- Copy your API key and store it securely. You will use it to authenticate requests. + +When creating the connection in Power Platform, enter your USPTO API Key. The connector automatically sends this key in the request header as `x-api-key: {your-api-key}` + +## Known Issues and Limitations + +1.) Request limitations + +The USPTO may rate-limit API usage depending on request volume. + +- The /search/download GET endpoint may not be available in sandbox mode; use the POST variant instead. + +- Query timeouts may occur when using complex filters or large date ranges. + +- Data freshness depends on USPTO’s internal publication schedule. + +2.) Transitioning + +- From the website: "As of March 14, 2025, Patent Examination Data System (PEDS) is no longer available. To access publicly available records of USPTO patent applications or patent filing status, users can access Open Data Portal’s Patent File Wrapper feature." + +- [Read more here[(https://data.uspto.gov/apis/transition-guide/bdss). + +3.) Text-to-Search endpoint + +The Text-to-Search endpoint can be found in the Swagger doc, but it is not listed in the public site. That endpoint is not included in this connector. + +Consider using `/api/v1/patent/applications/search` as an alternative. + +4.) Product identifier codes + +For bulk data endpoints, a product identifier is required. Examples can be found [here](https://data.uspto.gov/bulkdata/datasets). \ No newline at end of file From cfd4212a5bb3b3af36f52bb399e0920acef5cb8d Mon Sep 17 00:00:00 2001 From: Dan Romano <1087791+krautrocker@users.noreply.github.com> Date: Thu, 9 Oct 2025 11:44:55 -0400 Subject: [PATCH 2/2] - Uploading connector certification package - paconn validated, no errors --- .../US PTO/ConnectorPackage.zip | Bin 0 -> 34297 bytes 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 independent-publisher-connectors/US PTO/ConnectorPackage.zip diff --git a/independent-publisher-connectors/US PTO/ConnectorPackage.zip b/independent-publisher-connectors/US PTO/ConnectorPackage.zip new file mode 100644 index 0000000000000000000000000000000000000000..358bfb9dd985d6e0284f33b2624f911ae43bea49 GIT binary patch literal 34297 zcmV)4K+3;RO9KQH00;mG09;y0TL1t6000000000001E&h0B~VrYhh<)E_!Kjb$AN^ z0R#X5000C400010R1E+JVAAJkYSQOuVAAJkgu7FaFwnAQS+;H4wr$(CZQHhO+f{$r zwr!hz?(L44xg8TRnYngG#okHT z-p19%(%z2F%hKWhE5Bv_%;NYz9Q}vXZsP>HohI7vme`dx+pYi1t=@mHYTIu0t+qSw z+c)z&=er&9K1D|Aq9P+RwUg9Z8&8S9Bb?KbYbvmPX%=G*XkdO{Jl~<5q-rC#UeiwZDf>81#4(nc2 z8=reC=cSR=<=$RHej|If{<&F0$L9HH8JJGyj4rf|oM*WK1bH^y%H=H792nK1o2um3 zCTRm1GTrXmT0!XOEFVjlkOf=gDyB2y5YZ~KvK+|Zw4)dFKM0|=GPPqiQ%#@+;FHL^ zs5T9>fDBK=1$i3caTxar<_&jwuJHPR{toB}K<3}*6b5`aAN6N~TMFjm(~9Y+YR%>h zr@BORrbyGn0xg-zpyD74OjDAmN$k0&p*2yqc0r(`6bJZc5bxkN*(rglTIrpjrAqzG z(4+k6i7iW!z?PV38%`zH+k2K1?Un?Iy}%v5)>7Q;FWuti)l`XtWTOI4OIzM_l`=lRp6$-P>oDb8;gY0RsVO5CH)+{F&r6_r_lNlkWVbIICZ5y+*@C z{B%RszlZMF+M{$?rmz-dAR#TQRM@kauWs_0h*~Q9+hkDc2oWQOEZsq-n@|+R1v>ssy@75-=+zf7Nf>} z>XG4B;mb<9zP$y73m8cfsf-U{LcFD~(S_-C~`Thn>s z?`JxTyLmV;O#kfsg3(}MCWVW&?4`c4z6tZFutt>OH@#Y30dp)7(&nVP`@^NuWnH%& z`!IG=OKP;-_nbzjy}m5#y(L8i8SS#`)R&n1gM8;&uGTb^eZ6Jftv=dp3o^3M9ply2 zHV1x7$gJWFR^koV!I?`P=YKkGTDFp7P&*2N6#Io1fhq=dkP2jTM86PLokOojbmf;b zegJS)xaBe9=fH!8;`+I|J6gSJ^;XN{CG$M@7VaV8;zhep#`NT*M`EHM3%6QvDaP6~ z^qUG@d>w#|i%NeSk6>(nyWZKg(;eHIcR|;+8Zs-=1)aAlmB7I~YPdME2hH%$2hNxl zJkncAV0>H@B6Fw7?)?SR0L38i2ua~fL>ei6Yga0u6&Fu=^0EI8Nu#T|u(Z9xf1Nk= z)2G-K88w^!_Bvr9?bIt3Po5pH*((sbomLGD@U)9JYAVLuv5uncT5Q!Ck)Je2*K}-G zjk)JddgF1)UV4Lnb+!+ZX8L04Ju`oux#|bD4F)W=EE{q?b%X4bfrB<}hsF=rT|16P z$b?(OM{_5~(0-7Gt^Z9Fxl3mO@7HIsXUmB75JZ&n!W3^|d&3X8jIcgVg{Gl}3xR+{ zJXNDDHF7J;$6QJ@%parV()y*0JDcgLT` zdS`Do+bEJ>WinTF(_U!=DRIW*^0H1(j~2G2C{%K5DVHPyBk>^UR{-dU3AqYCWX%&_ z4?oE*mmE+41_Xc)Sx&erg_WdP>1i=}rK7poUfZf(jE5)MZSB-_YE`XW4VNDVd%Iq3 zxen~X)$_Mj#QIW6Kl83Y{9ppe_)kjGYrvuNeJwi(oa&^2ou|=jqNXDB}OA?VB+hWEsbH(>i!)V9VCUO*^kL@Z3DtvR4 z#Q1jf>>>N2E+PpVjEJBv-LH6>>Cv~XNeC^XnR_<2Z$$8*UyMunOAq{3I@|Wp z*=1NAnvZ5RGqYe7tUL~19}hnnKfCj-tPzSC3NA%k6(N8vdF*sn=E()?-rjh1_YQZa zR#C)eb*qY)Eq(q5MkLvC?_Yn-V&AnMR+%s3YGmhh-+f;gHQV05&IQvyf|m1JA4e=( zzwaU!3fJy#!nP!Iv$>f}`V5;9PUgi6{EJ@%Mto|UATFT?RCfHUnlmXk6r3+IZEh#H z&r8rERs=R$Yxt^~$s=r-QIvRBh_&2_%fqIAH0-U8-hhan;d!xy^G|AqC%S#X2Cw!4 ziaz|SvrE03%MYjRSc93kDV;1~Ew;-6meIp!P)Ghu9IP1)TzYA1Fu}`TTk}ES_BQ}j zz$S;VkHFHM0c;Og8{<<;r%Tp$*gwF>kf(29K+k}wVj>>R$qed$z{yCrM?%p$jcf`b zJAh4GBHgDfQPXJtESvcJdTMia&xhF!m>(aHE6th!pVV#mzB%eB=NX+{IjPfF-+3EyTB&04mM#WfcF}5Sy5Rv%=6}T`9 zn2pft%8XRyM7k^|JXYr19mtfYUY8^B(G6xGWHM@J{1BYP*m`1wRmy5*99+~)y*tSG z&Uklms{T00d>!Bv7`deR(B_ryVewS*P$T+8sisrM_WX#(HEM`Zee2trR2|=qnPgU~ z3NRxHV;_%Nj}m|ge_(U+8}G~rxg;0yL&2!x4plB4Btv}wM3cE=#d zaTp7w&l=d~&CG*h&+EG(2;@=QipM`=lTL4A(Wx^0PG$PNiJ~CtnYHe1hp%1-wxSJ= zpQT5~dI0Q^ajNUcfP4FnNXPrTO&MUkn4Zf1=~(Mw=|nR4h+;=mlCBg;E=%JwVY<^x z&&lZjK{ic>X$iK){kCmJ=}_NHeD~I_hxF<0$l)u4UZ8Dad@*t)bp2$R zu7cI1Q~Z^_sMW2349BMU>i=>QlgLF%k@&Bhx_G;|!!}}^xF9n0Cq%f%;Yq+P>_f|4 zpnMqAKPaq4=@^n&8nUsnJ&p_@(~?p%;U|Gm)zojO@Qg6;SS0y1^GI=>BJ0`yAX?!i zbg`Fsw(%>N-FWw9g7m)%4p&qeLqE!T!Jc0nCf!AOI=Dl>BS|bDRNkX_D+tF%B-wxl zG00%~UkG-(*S%f$I>o}Mc`Y7N#+rfc5lIL%ci;*_C1HvY@x6?@U~1K2$^)8;F4eXd z{VCxIFBK4F0$D4g0FPeFZWO6vtH~y4td#jmU*FVet~`3Lc@p|HU2SV}x$|cfTx)}K zB^sp=rp;>JlBuwj8T{w~t1dBk$?7?cm_+qJLJMax?5K@uJZb(D^v$Q>%nBk>7RdPn zXSo&0lKEKc@D9w*8&67{t>2XG;wwt>8S$!#Be185^9q~l$(T?3@M>lH z7nY42&(NOJe{@JGTB}*kG&7NV;jHX-lSMgOanwvYKd419tv8|{*@@`BD!Yi9#9XiU z0cfbiFbzg*#pWEWMz=~0{LiAdfV~-(%AblJgk9X;Y-cpB{DAi-?MEv~PE>~P{RLOr z2&&03d6ZJ701)5(yLJy&{%lzn(YiHMO~FFWpBFqK_9lOZpE)e4wYh3BzfCk|M@%e5 z+B8f3H6um_fg%Y%z<&2Y*Aq}QFXSol?*1k=z`X|bK(I- zvhY*uWF)o$J@(#((Cjsrdq)Y9gDww*8oi3>v}GGpHo7Cq)f9eIbDm|N{X#@>P1tb$ z>CE`y8Ja^rY*nAu@H}=gw!s5@tDW{utR$dl+kn_yD4NR)=*Hv0ILCY4hb7Z3II5c-5p+@WZAR{Oz%9 zWNfS|Qv?@)feS}bC07wAUDg~+TG>dJg&Pee{VD6T^M%VD1)g-bY%K4E*s+pLN`W)h z)UF5Rg@!jYHe5ozeT?4t2q~q-9V969nc=O#(|_~NOBQY$_P9CL%{s}1$|kD~yQ0Ip zM~0rXe-;UpiwmL`>S${~=T|AM{elgTQNZExX=DB5roqN>sW0{KU2G%;y=Rgi<(JY0 zWq<)7)VwvNF-T2YUnpNbemY#WG~n8ZN}T{z`98L>NJ$&DH^E*t4rzy~;aeCEyXK)# zj`Kph)punQ_F;kf=j;otL*)h`yslppJ!$)O)p(GVUmCPxk)L`o%q`=F7Gz#=Hq{@L zGwQgsVjCY01!{^R?wgU|kkDNxK?EftA=*D4pk&})Z1+;zWT+bz?>qD6x>3sEwWU~n zWpQmx&}mhI57N!VZ&oqgY6AQJ7g743@~Hfm5ToI#jUNBQaRpn@D}sxn;=-cT32GGghf}t_H|tw13s#>>DmNzeQ;IqhQSA!mV-ob zHgH}96$KDCpS-F9relfhnI{v7TWRfOIz~PWL_qDUIzk-{IRnP6Z^B1iLrn>qNMGpSB`vG!2W;}$ywn&ldk}lT*3{ks%7J(utsh&h*QfLWU); z+jXtPuMNxPf#IbP0`GkY07kNh(q@bZM@KEcj}2O5@_ujK;x%a#nV(vXxkrLJC*{Nm zUg63&lYPk)uAR%bg_Pw3jF46xN`4sSNGGn!SfGWH6J)s(YAaD<-p{WibE^z2C{33v zFn<`U)kubFC81th4#R~E09*{DT0iJfZD`q-x}?|G;0oy1 z9gm-tHW_~s9PJ#NRb_2bHn5UfM$u4!qT4_=BEk}Z2!Kv4S=9m@&Mgp8-Uj`8-ksA? zsvTOi-CGjdG>@zW$fXmn((XNLqN$_kzAMwLd0sU(JUMbLYf}hwGBEJIBeHTW0YMzd zn7$@|fQpnt`rZ7OHL5G46_U86=Tf}oT>gnbEV^3By_K1|1eg0h=D|e85-7z^yQnrv z*6<-PEpj=EoY4S#Al-1$H$c>cu(l@MMKJQ#KP6mb1y?VRYyh62WpRL~jE^0CDLm+k z@*Lcn9eJb)tT=}5g9AyDV+7fhqlkiW^@tZUGg%C>r*{Ql=aLiyQvsl}68myyT&C_ZK&wQBLi1 z0;gDO)0iOF3T%WFV#~W@qEq0D`4!6y)@?7m8{j#(-CSs2n}vmq-PwOz;`J0kbk@98 z*K)}%L~A7!Kxp59sLpG9#xla7!X2vW5hNm{J-%^9zg~>s>LrGZux6g?+M64-%nPdJ zqv9Fv{<09-QQH{8i_HmkctlZ`-v2)0457%M^p5AW1MZILy4xJ%0*k)6H4v*MF*hkM zn#Sr*yyPzj(H-O(D|n8M%uMK>mG$je@qau|&5k;g-Dx{MKlC1K+4-w*{R#AetMuHF z-F;IawdSLTES+|zT}i>7W~`6hJ;&gC)T%jVZX{fe(WZ$)d`-u?3$q#Cb6&b6s&In< zd00j8n*x8j4x4;jb2r#(v6K6TXAza7RcjK(U?Vwv3-uABEs4c&_VV*Cr)T6evC4=c z%lBsqL26Gb${kW2-GDBFNQa6GNQVOOpe-Zbt7D@%Yo30UdXt_yTCAx_oNPm(mwECG zaJvK$jalD8;-Z_Y%gdwh#Qrk-?9AQ6AMR`1fv`X~u@c;je>u-p2XAN}&=SnPtj&XV zxy@JmaA_jU1$C#$7_yTn9~+oHS^OSwg1EpzZQlM_yy$A(q9Bh(vy@yUb_n_MCDjvC z%AVM(zQZI}SB1{<_oBI2{5_g05PndSsa4BJ@t-e-Oi5SRN9++q(=>tiv`8 zg6$edM;*DWy5`-xe#Q<9R_yXyk+k#PiO)$zgX{iwcr)STm^TpsQaEZObsB&#bRI@Y z1mu0Rr0N)jJ~q~Ys*juys%zEc<~+-aYqkR!RoM5?ipHTI=> z+PW=psvR%$H1eyIaz6DgyM_VVwD>npTAt10I04Fy5Qa^G(vuAOUC2%f*R zcS=2d7O^L2ikekD*5p#JG5f0#nNZ>BJ&n)U zW+SMr)K>h_ATQS}e`wW|$zT!+xMY1F>ETTGK`k#r3T}wY;xFHYMsfA}1*M}c6sBUj zQtcR#3Mxz2YR%>VfOF|t>r;V4HBiy2<@0&G<%JK-zB!OcSD&w{y2!Y96_n{PK*4J2 zF-J(`Z?FWYsWu{bjiN;=Az*XR%N~hX)rRMva(>@WEc1hfcxHTKvN;)K-2M49Mln1W z;|HC}MZGk~RNg;c!dypgzb)?h`I!fgJjT~GXA()0MU2G^QvB3nMT?vGISKP~d)MZ7 zl-D2$(X(pv5`AXApBbASRQ~vgQJtI;ShI||7u7h5O`vB#b4fe$H+79U3p<;IYq_db zb+tcWBI{P|+qu3-WQL^PFsD5HTtgY=A5-B)V1wXA8GD=&+J|pjV?tURCq1w_!3g5E z^QG5rF2f*2`0Jx3#|IX=A#=2ncpH_xG@C0>4!qhXm%wuWDWTHY3?V3=R4$daKBO0w zYrs@=9UCx_SX>5{lDu>UxE{#gFhWRj>O zgjdY79{a$oQ{SibRy-Axm#ZO+8XYijehHWMYcJH*$Fgr_HUaxHH#|ibv>c(8u5k;J z900{7m;=KPz(**kL%gQ0L2U4)ae|@C?;dp@KCINcd|dd=EMq)kr3nvN6CAp{0?z!1mRUxTs|nAwXeX|NP<~^WXqCsaIO1*H ze(V~WJF-mqhw!x*IJ_$8*`CHQ=Ul?oW-b`T`zXWOnvC{48Y&CT2=S?ID-~b#X4ZOJ z6^?o6+6cBDCb#K8nr}&Ts3CUzaf98w(BS8$@%Md)anIlv+SYk*O#XB>kG(S$jH5NC z=cT=q&lq%gLLs1j3JhoGY>tkMNotXCfI$FmNGo@CpIXl(xn(J(xMW?FMNxg&itWjp zR~x2%r3F&X`v2wq6A(6J;GU2!v1KlfD^-~YZZpl`l+G`@D4bk&>I!Ww+UP@tAsn6d z$?1p%-FxwAEMj+wTZ(G!-DGAV@=)xLSeObwD1vn?W%slVx3c~sWBEr<=Ox63^8OaE z>u~O^Toyg7B*6aMbMne8lQ??q^n8AtQj?dj?wID`k_cQ}Md_hUp5zHVsGqV6E(D}@ z`7!QCw{;12FigLS2RT^}m-HIF1-cQ^u>Ri7Ca7tcKjtTir!9*|01 z(cyNtuG!2_)hZU3W+nyJRMAJb*LWsC%-Y%u7 zU-`U>Vzb7Q(W!F3VnIGxRdxI;yMpnM-Aw9Vv|M+xQGE*v=$7hA2`S-`kimZuY9j53 z)+c*|$g6pb7On=OqIsc*O%=e2un!;{IzTFwG$4cwIS)zzU0tDWwM|l}7Q<~jRd{dd zRh?m2VNf;<8y%fQKZF%1GaL!a~B5{$#_*8ij;}| zJ;4D#S>!v|pA8mT64E!?Im|WKJdDGSECByND*t7WC9BQxv z{X3K4Ijwn!W|l@r@^iO+KkaNfxIrD>%bq`t!BL-JsmI=x%gb&)|bkT-!bB-BBn66+AdRC z{-@T|8JNm6#)rVN;8+A`t+pq<# zZ;uOm$9Y{X&BpTjfaRp0P@z$I-T<=&D6-edys2$0`fc>h9nxqps8+=cenR#P0R6HADk0UHpmkY-fwrySj zm)6xnEr6V5aD&_Oi$3 zr{;GSq7%4G%NFkU7_L|z9&??60t=+a5qw8}&KcAyoKe$)$*J>?hBHXBeyXQhPV(BS ze#@m=5lHqkBYStu_PN)u;8}OY z5en&wQFdkMtPqB0BQdaYN+aY(VUN4-qmxkOisR=-&+&-09}n+{h+9saCT`tmSXYF^ zLgdqguz@3sC&{xUy^gZqGA@J8xEV21C@8R?dI7M_hkdf`+CSbcQfCd~ioOW%>XpRx zwmmL5Pa5F|Fl;+HYvchAO3B7KPpW)qSMEk->Z9S1pj8Euo-@oPp^9@p#e>FaXb`Lv zEy;BdY#od-=*a&xxh$x0a2q^e0voAUXngfKky+K%1Pb+V<7S7HHQ478=7e@&io~b9 z&$*4H;+xY?GRPl=B*IDu+bXLHr(W#wT!by>x#ZzfLGc`OZO#rR(@w@6ee1#(uJXz8 z4_pu;80NU3_&ZI;JB0-YV)4NK9Zjl3r4djsdqEJ=4AGf}gtd(!IC}w{@3CaMmZR7O ziD307wxRs)%8S&8Be#tMOQxSn22X*|1H877N{h@l-rIVNJR`D|(CVXKgdPEF)wO}N z$UJf~q;{2n-w26n2B$;4Qdv&(-VB8W()o2l+nFLtT+-@7gvek#qyRTXOpfEiWOnL5 zEwpoMbEp#@n6DcG` z8b^h~Rgu(x%8`8I+LB%N4lu6P^C=3URKBTUxOfYwu7RKz{G>VT)?M@t5 zF-g{6T*~E*k}Ko(<$+n@a>YVlN?;v#jA`yb{yO6=_q$2Ez&iAB6>Gdm!_%IBlCa7% zBjw=5S)*$DC38|g3TlECI?p;qR1*?YBMSsQ77Sd?=#!pk+HI5MHg;jIp-Q($p#h>H z!|V%V@m0X89a-UnU_1aw!LO@-muodG_pDUuKOrXAhRzvdSd#)>D=>{7H$(=y$J1Z} zR*Rs^>{y|w;|bM35=DXg(%6kbj1q1V6S_Rc()4(w;JO z-KHwMaMOB+_083yrc05uVx=E`MeE4TAgHl(Kx9RasLY1_lP%Bdm$mB2>a96P-OEfq zsVT};OU07)dhUtY*OR9JUFj_DOU<#5H%HWdSR$M;&26q=?B!??{t$06s?66lDpPBz zpDgC6z@$qwscorYgeUBs9A;>_hyzEhcp_O#(&{ZjdPqV687o;T+l?<5s%>jWIa2yD z2Xs$S$eA6+1frbg~oq*H%knj?q{YT`d`gM@TKa0@k|dC}6{3IMfXsRy-oGF7OW`>tir zWFhv#8yhuxrBx^2pvI8eH73s~_qkvLxuLMJ%@agoSW)hyTue}(Yn^a7dne`<*rNjf zN-U-z|BP^s6~gbfMBsHdDV#C$d#2V_OS5x&MRP3)iZFsVh3{zOO@$LCd^LG z#Z|2=JQpR!SOBQeSYC#y0+7Vwp={;26wf5EQlJSkRdT7uv9u2quBw1taXXnJn=AvA zRASB`l9`w{x+ZzWTH39Lr(?5ce2Dc2xaIX4!OGrC@9JgJ$LOC$nZI9Z%P`kqh6@)h zE3Na0OB4u)@OR)d%_RJNp zKGXN@;I>pe+cPxHpbOy{Oq~26;8g_XTM}*~&a`ZhZg;75&&hJG&{cEE1VU2!OvEx9 z`FoxrrwW*p=jj1?aK@>X+tX=)tc|JOW&3P*OUp4OiSmit&QLA>l6FSK)p=FNP+s5+ z8a*@JB%*LruUhRoud6UpaW3}8lV%jYef{Yeinf63!i5er+fN^!Ka{036KJI6jWI}* z)DeR&HWR+;kHpRGpC8hd7N*@ABplv%G;Ms@bN8uZI)Bzw`Giyda<`vAh8iQ41MCpi zVbG)9O`Str(b1%+q!ogxjLr_uefO=8OwtjkW%Cj^+=-47l0RZz=a6Kc#qJ@+Rv(XD z)DEKBt7W%a4qDIaXv2y@}E!`Y=D;&4f@WA&E^mnl9fmAv?!ILZ2F!Uzm3Qw(Y@!m-X z&mBaV+kB=Lm^E9J4FEfbHD0l-RS`J5xZ_*JLAupkc*=mUFnB9ev>rfTpOa}Hh>J`i zv#k&+i_fi~*^d6r!Z{bl9O@c*z;8oH{@Sn+{d3)noW0L@D$4Dk*XBa4?;g`yfxcSo z<_K)%b}SS~J@at#?dYm38ih%%K9tMc5O+dRZY7cTQFmpJ*+_WehPmNTtrHZo`q-x` zQ{Bxn_FG-k?q|Ynk5?SFJ95Uw(EL^Lf{X#7i^)oNKs-RYwkL1f-zP|`8a4LYzi-9F zqID!?w&&2X5w&3C7}A=r{J9&J^G8RR#ut&TG$MBk>L}B)b4VC{3cq-LzKr#+72uj| zD|Y!lN}~SNR!Pg`Gx<^^8JW69c4srU=gq3y=0z#e3uArx<0 zBYDwo?c*b|E}=p4r1Yuf+*+AzpnoSH_Q3yEDT9qw{`B6oAUD@3Kw*2&Reg1ie2SoP z0zH$_5xsf9H6@(VU$F@fSLHNfO5IeqnsaB#gw(kRAU8~5_*IF)kYhTlR6LZgQNKATaJqlFFO9FO7Kc+M2(8M^3mDSnqy@T|NN57@ z7P1_NrXz?#PaPwNMF%2J&mF!w#`7R*YTNL4Vl^kW~AcA z$+$>X5lY`ADNqdcm`J??I4U2VOIXD;mycf#&84{@5zw;8N?w8yCrW^UiYgjBm>(&~ z9Zdkqm_7ChH<)i^l7l(PJp_c3Xq8{rVsbkXL=oDLROcrSI<5&FNIg1=u1@F@6Uo`1 zDCzND%B_>;>!0fhGOZkd0td0{N)mDx2VIybDX8adoY$V^5} z&5I~zJLR@iw)!!hurm!*Uk}0(Q#QW(5f$ZRWijFbfUseGnO_nkkoFSC+I(eIg2nR@ z4|HjD^e9lspN{qpWiJS2U1duSY)v1xFqZFjHW~U(XNvo?zT@hh zd*S4afkqi{4AUqXAf8HnJ%wh_5EeOG)@;syDq}{y23 zQH#ST{feR~CIgSr0|v}0`K)q7scwlb{8I`F?i+FoPxXsJD3`Y zlz-CvgZ9~U(DSzeso7@414fA)tPCV6@0K-k~gSp^)09W(?0`0z*j z@OQKRkbjP~xsE+Yxt{(@&PHk_b~W*E;qhaX1FZBTDADkNQ(%x1Eca7T_Q#}*(cqG* z0BMXlG=bbYHdJ7Yw162}cZ3optTD2bnvU9Cv#-dG@6AQdL+(qDOV%;}rG+(~zoyPn z#{n2HXsjRo07HAj&iN2{;#Ak;LAUtYZx5~=Nc`J_l_8+BmZ2s9s5a?innEc1(5=70 z1{>HvOZ!Qgv$l6LPJ8_x3Syw|SMP>=_JckgprJhp@I!I^GklX2sxdP0rq`jl+5u9U z!!IG_(2*9RVx@EE*;~`aR#5)^4zEcAstbtJ9uz_SC<~SZlCU~MW5fHJG_ma zLC2FvFK(?>DS2S?{dNLZIQQ7Y?jtPB!6iN!6!kMRFkSKaRxRC-mD8i=B>zL*XwyG8 z72N$*U@G|>EmE6nxK1;i45A@T_$Q_n#rIPE{#*n8QgBEv4&cof)XvH{bqD2D1d6>; z-n6}-j$jH#G=!-AM?JdKt;y@sk_NHWP7=&VbXs}LKRM-$N#MTc$5|K6>0^SSkO7ZN z4xTTmhP_mxovu5zWneEq{zcvYGSf2UdnxpQ(491R;IOgM_g=;w42`1RSLF+;Egx3b zTfQ{6TPB_BV}OV8>^jyc>~M)@&`wqf7*fIHVz|^?=cf2>DCGd&FFrIo!}iy8!{Xdv zXY++t>q_rbK%cRUg|UZ`F$|A{>Fu`W$^i=f8#j6B|4r14!UeAtVIaGZoma6bQhW;h zv=jLeQ5s510Tls)3z4k1fWUC0+I<^+hT5K2Ad|nx7xe76>CPxRmB@JHGfU?P&7|~ z<*OvZuV+@2o2i|)dsK0{Ra_n6Q`gwcyFufBRSBKN_I>SL^+33Y@y|alQA;83;n3%I z{Juz`3h5t8njl|bl`3k%yCbHe8SK8?sBsn~#hswV4t?Ls*A=%bsAF;JrkSTfJQ@-I z5dtr$OQvEl%L0z&7REMTuosU5f*9&?UvUZB=mFWKjDAYis_Tn81n=o#Y~>aZ)B`S# zWGp+a#b-frT=S-)M{jW(XsYFc-*$ew zu^RJ7IZt*NRn0UV5XC#MldXFWlO#LWjZYgju4bJk85dk&{+B)Uj>*s6wA}E!*9I@y zj4ABky>HS^%?SSf94vp^ER>3DM#;KiBge)2!So=I%{%d`l0#|K;C!5`t%8g$*fC2Y z+z5U?UwQ9SH#Z)Sd@2uqqsr;!YR~L-h}_yE;eZu`yXE}g9LW@jK8^76#I`;w9$Iu+ zQkYZ;QTCC?A3MeM5vp59QTDkqCCjpR#rV!#o`jp@+EcHb@M4u$KX1luk zNQ?wRr=!7A4ag5I*i3UYVpWs){+JR$vyMck`>3Fz3l~47OW$%(_>OFazj7HT`mw4osy2Yz|_$ zt@v+Z!tvdtE3VTbR+}T#q~-Li8M-59(#JrvQc0%ly>6?MBgdx|hMYjn2epkcT82mt z0cw44EgkUDP|NQWE~O~c=JSNmrml`&H(FV>2MG9f;TOMiXw8rul_qhAKqRu`)z9&h zB4fl>4d-BOh`!Kvg?Ok=XAn)@)_@&`A-OP zg)VQ7Y*30QMNma;FNrCWDe2~q>IKudzDGG?IYTMmBVzi2-Zw4?G|>Yrjj;8JHMHxw zUFg2IY?`+9De<{=59ABwwH4#q(BBkA2SlshUMtV!4&ofIz0D~M9_H*x1dhkowSNB7 zylE#>x4m~DJ(!`s*xbr}0TE#`JYG6yn3MbFbx5<-lwKHdLycVKZ85PsSU5|d!S$tT z^$^(;0V!ct1@f>xm)3RuIjSP)8#)tTNkl|I!P$~*hUDaUt;hmXMNvA?Cb_s#)T*;% z^zx$vf^!G)?dhOJJz%DaW71ax*i2DgDhk=F-x$IEI2Iec40fHP^2oyR1!ukxi{3Sm z3&u>)6AmFATTnaWvtC}!r=_zfX^V(Q7A!?{QP)Bvh-KZ>DBRC5jk`<<*axzl*@TZ2 z{x_mqYabKK$ML4YN^>sreWskGZa_^TN+0_lW=k2yA|Z3O9_l9mk1U1Rw_X35Pk&F8 zuKwllDHjxLmUQFhgDOI8`nI^mIg}VGcJt;E)jK_xy(^=_9yuA79Z>rkb!2sd+NV2# zNM&Up%y$RK@i%@E`Kh{*j{PoFy|G=UV~EIQVFGE~YYpt>qd3;pQ4|f_v~3B$vJB~; zMhQ`*@~knT^1o8!0K;7ltC*??L`8~4SIuwo8x9Q#B&J@{*|6ojmu~K%ZRhBrQpb(kuAQw&&j#zl1wFS>N1}EcuG6tG zkxC+;c?^qYwonyN(s?$4zm9blq#zTISJ7GWxNnu)OLFhIEwe6~rRcbvGY4$|qrLU3 zdn_n@h{}r{>#VFsbhoxKO91NBEW`ZoiH1>2ZQgPddVb++k`#ZKAm`1;a zH^y9Ohb(3Kq5v~}3>|wq%!}{%o?+&tA`APH8o)8G)&f~gvyxcY`m&_GOi{G8_>^Oh zIPHI8Om+PIWXXPrEL>7l>L+r*;l;}*H)WL(c|@0V=iACf&!wY|8t#14*;o)n4U{k4 z@tD%65UtS=$bTVQ_uvYrEwBd3MHCV7Qw&m{#`0}oXZMeBvhSqxnr{ z8^NbCD>J+Yx%W-;JOsa>=W!pdY6>PM5RG#u!eO*!_NBObR}8|_u&YJ_L54R;EJ~w3 zx)v7Ws>gqInTfU+F1fhI?n>}E+Ry?1)8i^+Duw??+W)s|=Iqm0pz^bX9Sr~oF#gxF zvHADBL09HR_eqrpS2o-Am&{R5lK0h5A!C7?RNl)3R+K5GWzCJj?|K zp2Q^x$r`gj{@Z@%v175MW<$-zZ4>O=C5Ggw0}(6 zowROrz*NkQM`{TjljUqA7^J6`nhT_xf@lfTxbDZo*)fTj$9hK$+v9jN(FNUu_$5tA zx;`pS?_9<1@TdJqEfM^)mJdYm+qwSBsV;H* z=k=+tAPo+|4TDo>%>@9U!V3WK|ER4||Cic|`+uvgVm9{f|9@8N^8c|~|BH|=;}|-* z`M!^s+4cWzwf<*ba~gd||FhTkZvDL2v)}eEK9_S<&g527yOWg?zyL)70e}er2=kIQ z+ZN}KB?|xqh+qH$Kn4IYy1Ba7x3s)4yEHbpIF~%vHxW<_0Vtpp0RH@|)pk~YgJ4g> z=N{ANDflrw1q+0!5`j*1ZnX-Qd#%&0mTUF913i|UnBGj+eh4Wv3l2x-tvqd4oyj)Y z>HNN~lNdaM#=uAV;q@<`82~T8G~OGn4akq6w9a2&-Og76j4XahUKI`#^`|kYJsFlk~XAH^-<DKTUY`hu)s0jn&<5wrasN9kMR_khZUs8xH0YXcA92+k?9ly4Y~wAU3M7|DvN zP{LZ=lx6UpsY1xjepM(YS9x8}R8gJca-MoOjA9+tygIXA5h}%~)Z%xq(9Rf*T<4A0 zv>@h<>qJ1&BFxn^^;y)LtQTYs_pwQKHfdVeoA}}o0hfR6#sh+hLzyCiZ-(SrQ}T(6 z`ckOZSx|FJwWL_1TR8>JQnFlA5KM_P<)66>}&v zxm7sbb>dL?(n+Lp^6!~24$8KOlV*d05oQx>*mn(Ez85_+u1*9Ho0lbW5FmzAO^Hll zl|NS;v>ptHGu-q`ZK8rn@)E9c-HN=($Ov_f(nXuB?{@*qb3QR(25Cq*-{A@vz3#}| zw(AX>x?Bo{ln(+>h8>Jxii`VxV?K$xDUTiHA(N1st(g_{{2JcS+4-2X-zj6&)U6Ws z+{1}1TyHg%)k5Wbvb*`GC9j`sqj<>@=C2hYf5hp*Qn`&vO-0!}q2j|^toS6yVS?*2 z+%N(16UH~YZAQnp0rT$b{|@yAecr6TE92Y=TSe>D!Yn_KW@(*`u3p{V6OOt=moQ6| zD5-5yh9fW^+%(NRf}+!)Qp;<(0KZU0z2WBNVx~L;LUx=s!SC0&&t)$G*W}a|K0}%U zUwV%fZ6|JX=+3EN0Bt~$zu>yP2pvZcj}b~I*7|#QnbJ#<-sV=FH8G{>_F`2?jrW6K z&GrJs_T>(n*k@ZAYT4Qm&++zS{Vh~~&wqZ3JB5=50R-Se2mrwFw=lD@JNohmw)Gcj zy@vVuI)Vf7)BTv+4v2TGznqkc^uH>*rx;QCbzSt0(Y9^dc8|73+qP}nwr$(CZQHhc z&+*N*)}A{j=VYH$@=sM=yie+;lK1BKkgR8w*(+CtCvPuxr>AlgQ}L6rMv!c0wRr0Z z#)6vH$UKLWAgkRh;2N{uG75CWh)ccPP=0?eOsCP=$)wR$#oYN#r|L_TasyMS?%?qivfIVucrhiv>Ys&U?n!ldQXFqHoX!c zKQqSQay#0w2}JRnV45|1Z*c7&@XL@w2+UFvL!tStg!_AgXab(4`L0R1*t&hpqt_Gj zf)Yh7^~q_-Vlcw|7|McRkmlnswrNIJd(DySRXFn~$%lU)TrriPEEdec z%qc0tXe8pyB+-d64O6*fNQHGeh{zs?U~QT;_v?yPm~MU^Eidj)M)dI!h&<$XOSh~n zkLbLG`SFvsp>)9@Bc_SR*p}@ZFO*p8p2pz;Wf3%+YF+YDArn#Hy;&JwZ&tv4pA0@% zxho8N8IVSS{M0Zr5L+|M%L?wDh4i6MNND1WAy=j$?z;wObTaPEcHuK1pmBoNBYuT` z29R-Zo?>LJf8DwxlTk&ny7D}Vf2b-YpM1GSr;{(=YC=B9yHvTbxr^PeS09xspRh+D z%k#3^cB!C5)*2-2phDMQ3(o*YquK~tG_bi#l=V(=MG|;ARtPQW!xnuEZYEa5SJzLR zppN82N|kkoD2W1ib74^CWkJox?*ZI4|JSAqDu37ufZ0r#gMX?<56I|aW*k7M-O1S{ z0!XG7)0OSJK;>qWc`gxik!kH8d~wu3G(NtrA0zQ8khaf5C3Z(T^3K-h(V?=LR98QR z61C#}T8Qz+_H`&hc2Sqe!3MWQ0b*Oc3d+21o@msxcLh6~{gf7kLPqBSX3l}9!PK+L%&V(!6+%Pn4V(He(O;)zKB3mQSb!6!MUO|###^R}Y6T<$ z&p?o~m0xQ0)+Sz!F_I1l^|i+wa_dV_MTae$tSxZl^VsuIlRTlsAqibAs%afOJOxkArr4+MN` z+L)D|D;{(;G1hpYG4B+YAt;jin0kTA)tPjqUnzZ6wXvUJcz%~Qv)X1R8egvsvZp>w z&CL<|b)Hn=1VQlIA=HroX>QQR7%G=^`66^OIBTYwVBFg2WrJuzyxelmRlLN|a}hPfV59k5!gNn?%wxXmrn(v{^10 z+&KHyV9~%?fXYT%jz(`dJdS>dii{H2pps!Y+j7zWV)q zd@q*do-Q$BqcHkGJe3a0N+H~h5Ovr~qf+xas96PjHj5??nE2B}2gUReGF5I!g0a3m z4uXY7SPB;{4m*-Lz??V;A_S5MzQkX6to<=-!*0<3A7NoU1VxB8z zjrbUZ{2FCqfmeN7Bpj82@%5|O)8?lb7P4`Ysx&yeagtb^M!c}ZVZYd8@?_>a=sQPB zk=Zfv4+$_p`J5j>Nlb|4psb?9-L2`f z2!%#sJNuegpf@xe9vT1Y zHcf{;ESdvX0+W7^2A-9Mf4j)%1rlyQP{{`Y!*Ql@DXH>U8!FQUQ5oQfoD zw|2i}>>Q;9vS^ZJt(jy)=xdXP=~CN5D=EffYtOjaw7qcrHa&cxeRm}twsryq>aYip zpM~e>-i1~wqR(d;1W{f-9|g8wci6umGI*w|cRY*^EYK7_LtJw=VaSM+8IoBGe2lca zXOxvkf%Ke5+U9DA*@5f|nW}EAcJnINNC{L#J)3S9^s~|+?5%9i56_;?D2~d~JbW-K z$Qy2D+mt|XO__`=uQ!=>PUyb1F4so_3ffr0L#Ny|qz{h~+q3*kA+JOSTa?~gwk~$e z_#&P3X&Y=hZ}!HgV!*8(*L-ei+PQWzMKW?i6Jd?4Us?v0@B1&^+8%-us@P9NIKPOt zatMzNgr#Fg$i4TE4YFV~DWd%i_zW#Zru%lf_!~j{i;u4Ql$PE+0|-+0?O+kwnbx#4 zpV{;cuv}7hN{a!XHl9yjmt3S`@9 zdsE=U+PNtPl1-pL7`o;v5P52u#!;<+hSzcND~Fh_WQxSCAx4XSAPrAotww2oA+i;8 z|2zxd4jVM~^o5j1uH^Jy1C3aG^$N^?gYq`Ia^6KZLk30A z|HzHcJhKCD*?`+OF{dQ)+qRdXc!PEH%L|qjVi`0X889H97-+t@z0E)ick<$60_)AFWMgKP;arPPT4kGI0rm zPAB(Gby3A#197WC@zL!MB?6u)pG5wBTao&ldabU{Fn*@5>rH@=qsbGinct_9Sx<4_ zr+tuDjnbA+KA(?mZh1K2XQD2lY{*Ltp@`1cQ1&Yvt$oh$%h)XudeWq`J=kE;6W<9B z{2>z{x3WD3hzY{`YG71OX$19fBT{{~VThy$}lnyCsp_Y;;HYE$-@d7C>v#-|MVgH)72BtW z$2r1vat9l2w)$qe7wJOgd>R9r(MomNc_b&V1|&*;Q2(XUeO4lxo6Q!n76r${u@XEw zEy$E5eZDaho9U5$7bAV-GL$>lhsu%8Qqk`5=~d;%>OFI2$xpqHLw3*8$;|_ZlggpGRvZd(`a<>zKz-d;#GA^oY`C+t)9^!cXx+wWsC}B$ z!#Hn390a#;eZd&I1m;SBLHV$7h`)Fn3U@P`oRID7qgP~&o-o&t225e^$iHX((f zPDN)c!gD@CHtp-ApF@cTCg8|XgYJ@`(_v;ZSAiLWN?7&f9y?Sz=q70v`MEnfvwNQ> zcD6Uc$=U3C1_^VQTrdKvjcmvKQejWFWfvl19O7cQYFEncFg3l_okyagQM|m;b6gC) zfDGtx#F`LK{b7}7ev5GC957;Z?Zu>10Z!coGGmq29~-;MT48OgW~{;+We+hr8+Sp$ z%yjWb0)T=61mPu&A-grl;yP-UX`u!K0XvQ!vuuqT2hlsReJ}S*VLr$d^8)0g1=Zta zNx7MMg;m#3M<V+;ZPba;$Z|<`-FhQ4p0rmO=9P zlze-iU$W@X1MK%FzM&zT;(Cm7@SeEez}&Gw16*zuI&}~?%0i zcwl30L~q2ab#EY|UiDc6N5|k-haScx<#!V;D!n8lZg{y4QIyK^uV~4;vQgf(HK2)MB@t(n&cy04P??`^Wn+JeM%*IfR@~(`$lce`;6l%3& zp=%s)b%YEsu9-a^wT;f<7(z5M9gyTx$QPNh@J0o45&O5Ye9cWuTENEumf}nA3702lv(iR{&pi_9b2Xb{%$yt@~T!WmgIO#U|AR)x-9N^)l z@r1Pp7m6rJfG+ES*<_NsqUXhaX?JU}0Hf!+D0}PrKnVn$gvx3;^cxFyB-`4|A}IH% z;w4nI3%DQp)kB6lT)qA&dQM82{bzBWYy=1y2x+%1O3dmd0-LsQnm5%xhcZJa3BQ7O z5!bD1U*=wm4VF4_#$3gB&u2WvzN~>Kj>sEs5K{!x4#slgv^AhjbZtu0)RYIBCZTvu zflGKOgiKHN?eg(p^ipHJh+EmBXu_$B>`6-=AhLWP-oW|ssw<=+;$J!87jr*7g_0Th zD8>Ux=fbu4Hhrt6KV z9_CI*M#>}w9&;6dbfxyi&6p7PVw=B1>(l~e{A1oJ8&*o!1J&xX_XM<$4h>VlUX>pz zKI3RzR_E>xD2j$0Y|YvjJu!0O!1Be%NHQsv7RQO*pF>Kf8tqw-Yg1WaK2?`b zQ4ExedLZgi0>@5(YIUXP-)YcqXqdM`i!g9PR#Gl2B7hfv0|>#N=^Xl0Oe|jUzI`q> zOMMgLsApR(%4-z0gcMfJ4hj1eT>82Y;TH?s@~?7AD;D6WZi4*cW)e!x&Vl?dL1LbD z(o>q;^&FB%emnGk1PQe43ypsZ5`zv2zyB>r=;B8Ui4I=s@MDscPW)LNhzf5^wVZJh`!t9j2m^7lLV^`jy3X8+mK^xCT^s{gF?DC@nvhmmH=*Nye}n!jI-D=M6A) zSXadz^EelFWmlFBQA$dbFAV_eea;l?Hu>ot6F&lU&*1`Q@e(0apG>rA?dpmM!J&wB zM9j#34&&LCriPS0#!WEUi%r2Igb_Q+akg?M6{5`4nkel@hZr0ejw&)ujR1iXNn{t^ zOpVDdJW&*_q7P}hEbEt=u1yl!VM5v@z6;Gw;#KYk;HkFA^kVg6H)p^FRa?MWZ+~GNcic0J9B_(RQ@AK zENU$OBS_Q?i>ChA{svbF-b9z2Z-~{yr3^oJnRxTlgQR+p!|v4x{kI_D=a+wplOMWN z2z`|3xn!_n-$3_t3f7vds+fJ}#Keg9Ze?1V9`nZO(r~vq)`Ot=^RRXy~lFj(|!V`U7?V9>`ct*45f$A-`#w$H7kwnIp(cF zyaYQ0kd2uSx7F*dVW-yJJ!YP<95tn?e-c_XKshH?63n04y;u`D(1<`Jb2=mDaBN&c z4Yd*%sAPKr?>}$9sL(pi%@<_bhqxySvR6F@J-Z+V~(d*j(EU$f6maj^~=rLM6D z#PSDUHH1=eP!)zF=xG1){OoMMW63A4W@l|nkDK!*%U95^9<*>L-3P{9$^JvE6RdcH z@LFp2<8XStB>?1sy3}Ir*O4rvFpkntCJD8+ufj>b@0B-ZmABYLmY$$TTrevSf=c;} z=$#XBNyVj-=p=nxx%%nnNmFh=W-^}aW1giIMXhqh&;ZMY->KI37@mRHA0)JauUsgR z0ZU()?<1bNQtmNbt&=d-k{vP3z{{@^5&M+~yU+Ya*HskX4!VIpH(DsfP{baRI521Q z1hVSTU#Dq*bjFC3OVKaXZIv`}?Td!i$8g}Fyo^6mXo09!*8{cRO^b}uqoNX>-7BEp zre9VQ2|ufTK8kK=@0N7Fjj54riwt3Tv6eAhEVJpRar&f_sEhiUCZ6D+j0xpNQcaZ% z5HCE^R*ccI41{H-kUkWY(i?guwM^J&MX=(ujy1cEFL2OBThh<>VL_!#H~m(kTa`xy zVKi%crj*iG;J)b6lpLdBPaa-A44Idz6y)z=7tHIx^0iQAoC|>zOtv(Gvfm;Q2^7X| z(?zwlHv((Rt&Ij$+H#GPreE}7jLyLU{TB}TUgF`Om2#71Y{z-c-*>&~6c^8)6gnSA zVXG=nna)tDAksO_mmrUYRA=uvKNvY=eU;S0-XHfuX1Lj%{X&S;+>KhQ^9_O*NLY^i z@$0eEQ?Z9Ol1Eo`lWn7Pk>=TEAvZrO(Baz3IG{Xi=?%fW8=oXozZ+< zUPgJ(ch^ghcP&~@g`TR+_spaPojgZilr3%yT+V6sgxwEgknmZ~XIKsel&0g(z)Yp# zm@lc7rEd?TNjaAFe=IE-7$GV**U%5gJXpK}$6x%yw}xjIi{8r``NXlWF(R&v5+80U zWpH)c4CZdeRA2(f{{~i*;sp(Em)>oh&kT!OuE`cC;@^0Yj%U5}r&3zIh4?L%bRv_o zEFvWQr%qjwT}~}f@PS291ms9d0keRO1xFN7zuqGVC$0MG(H=s(AuWO_lQ{4v||04Q3i;chllU3yvU%oXZ|JouyW}2nC!&95Dtn`b2y-3ag2y{G=B%wF**4Pb{W~#M--Kn??IM^k zGkX*407pg}1VVgZ!(>&!VH5uX5-EQH2|mPj#M`ABr?)eB6LT0h7%Kc-W_a87ce+~0 zLF`x`RC_ghXiM;no0gxwh>^()!v;GkPqvhHFR39!yP`PtTexPDQj=!1o3k#8TC+?Lylj>R-Z)Jq-#UbT|THj-Wc(e5Vu%&sXD`ip^0dPK$jO7a=Y0beV z4{yg+HSC#tyn-1T@=QME#Z-<1=#sYIX2#8{L_5p;7-@Gln(K-34Y7Zc8W+vqEssyL z)lM0<6IEraUW@5e`qo(ytCc`;Tu1V|ve0rD?#UE4?MuLVTc(`oG}?L`pV4(dP&Wu4 z=NAxvim{;C{s86=;D)&>%&)h;vWriEi~!`}f1FXiuz6Ok&C4i+$ICEnDb5vb8$W(I zHe(vQ-K3@Nf5PFlK{F$RHY9Wkt+O(nt4b(wn`#8BH9VH375Tfiga zG59xM2BQ{nGElo78jXw2UO2O{O2J5pi6P8qXL!S4K?FAXk~F~vr`)8*Enxm*_bwv6 zJl)8%1BY_UZOOOYvsmo+6MW-K=SejB7mSkING+%4Cux!=IT;fPt<-cVB>_#7w1%5NPj29(BcQ6A zf4Bu)bXF5sfxN|`=~=NMe#H63JH>)3lGI z;4i==D!0nS*T~C$R6)X+SWoDpm(ijw71#MQ!U%qK4R8PeOfV!xC0+lpmi#M)fzPNi z-;{%%<*U9~*6g}_WrQb-ru|vMeM)~TPMi*;2Z2q-0Z4_2T>F)TUBRKtK2f|ih*j># z-+zi;is3to`znk2Z$!A{l$A(c@XCk9Y^Ia_!x%e~(Q4jRTvL^niwyDi1oXcTRpM!e z)LL1a$R3g7xUkg`WQ~fztVa2d@qK}rQMgmc#R;LLk@?YlsVnofi|jHY)j6&kX+ru- z&I-29Af-92`toZ_%|uPMt&RMN-ExCn&+UO$4xU|lO<$w#W$P(+S) z-YWEaNg?jx^*_x>5BsnRU6pW^NKKX!D!*3`0#LkoL)uh zf^qc=&<{lvK!efD0O9kl!PEgqI1DTYRXkE1qm=rD4fukzS{Dg*DV=Ff!Z^jl%2+C1 zY?iX;Da`jQMJ}+UwT>IQv2SrNJ&(EeE<3PSp^sh5aMH)Ez${?1kZ%h*;6Apf*pIP* zE^GmcG^u$RUJ0yh=;4)@pSS#%AK{YZ!O+&gjh)4^`rm#;)=AEP`4NtTJAeHM>M}dB zSLdO?+%%*`skdu;qkG3;GdA3e7&MK zn*!#|V1~i}@*`IFd4c}NkFfpzZ$H9GO#iPRF@}8*@ozuE%y}6-zxG(2TKxEoG11=9 z;#ZaAbzAMomAiiH%HUyx&2m&MEi_Eu>V(twGl$A$uNHuY37lBU!TJ-5$JBVV?pJ-n z_CEY*tI(=PI8OEVD*?L3!2S_T0fhp$7eays{$jTI3*ic55`z1Z3xZ;Wwx3JL%PdrE z3QEewbN!V!%MSaBK$FUfF?-ceP0BYa*j7>!ipMad7|t3lF{Af70dj;gc%4cg>33MA zSXi79dI;l%zGD?YbkN1}=3BOXXI53#kU@+LsI!Q?Pl^bpGZ_eXXGMO!L^D^N*Ww-X z?-(^lp-`B;DhtQkq!GJ!+ZO=(*BfSHU(L>+i-AjdePtKEcILbZ^)ruZ{LdvVh0uU$ z!qry(;DGj<$r%oc&fHF2AKc$`3NE5_^5>ChB1F0al?#ItHq#KlGHDqU9${V@22}I5 zl~iG)EA^w143bTq|D>2r@OUYG>8!ZYR1vaGI30h?g=})6Zl8r-Gw+R)x1p3QI z1fnNR!$g`C^hYLZR97aNjBov zT5iN)u9JG&tF3cI^J0n4U!f~ zhWp5uI-k)VPTKf7=ic)kJr>2f>fHCe4Oultv4qS69rt#_H?KajE^RwvV!air6-F_60_SjnmFALAX9O>#l2034UvfLm4Ya zIp;t<%*0WTx*0stazE8PFMx8aq8kasXI_389fl z3wLB)2hTOS+89}orV{BJ&F`(Tg;&S&ftdyVs^2Ac0yyFU*e}E#TnxI?0ho3ziYovk z6-?<$J(r{Y)qmt4sF~)@?h0k%hB7AA;^5{P(X$+qe`~^EsHFh_C4zy-*nD$x?ARZ$ zzGW^=wRQ`&D>b6mrkVnvy}u-^>#}rT%lRU}Ct$$ z*sxMKT(LG0uKkw4qSi;bZl+W;S139&@j7yWQB+H6vse@U@O8#*Po>A%*w*QQ%F>J$ z;#|6`s!V-VAvw7i{w(c=492oR5?+~<%<|08sFH@B&N^^ci|CYnC?a2>qDUwZ@4p-9 zxW0IDCRMuh9IdZe{=#?BNA@=&pHZQ&&8s}1I#B{4E$*BOI-^JwiHLvJB9 zU;7{!FXQ4b<3M}j+nTNq4&+0;FOrye{;5D4ClxO4G{?XiqF?vZN|r87czi3rPINTO zTu@3`hBd^vrAf)vh*BIK$bvcNDoZ<410E!a@z6}|2Lf1DTWJ35$coSlOJH(+Nnhxn zG^}t}&=@24&abKSemg3SQ#?Sw8Oou?2|V5`OLw>zl7J>%k2{gryJXfZ_!&k*5^VLV zSr;BCnyI1*>0XRUkw=m0j>9womhmEMHbib2(eWgqm72vmqqYVWjp?ce%oF4$ljTv9 zB@qDV9a~9ETV9_Lk3o?!S&n9}s;oyd4rS~UNtL$^j=Gq72Eh}SmhOk;kQGs= z86w1C=T67WNCJZ$Hd4V>Tt?>@TQ4u3F!BeZ5WmscK{uP>Gn|)uf0pD0q+vEl)KB)NTD^E;R zyK9zoAnPFJ9>A*x^HMarIP;WfnhDb5yjb9NGcJfR<87(NP<*1FUGgyR>6u&Ds=R%0 zf7u559GWi6k?c1s85du*^6$9_8RmRI)wA${h1M z0l|uLKg+91)EVR%prn#hy5aOi{9$zos}@opojmQUog<{o-@vUer%9%k-)FDD)u8^3zW-!Kuxq+8^F#t^* z*1??c7-mLwQ9ZnC5dKW2lqx-Fs`Qz49l8rZF;-VR$S9B8W5lIBoh~mgUQWO^_1!4= z9YJMysnV!$dQBQpK=9-Xr4=OOpx3)rnX%hMhSgZGq2F(B6e}2kS_#Z3cj2@-^Nd-4cuGkn$0cNdBaw|CKzFk`mFG-Zj+OdOb zahJC-BQ4KqIEM5AZC7obY$yB;zVNKxr2n!ABN^^(W;tWR;N3ZpO{QWBxHOjQK(YDw z+p?B+)$l#;GDI;+t;;zZz|zqn(YXZ+vb@@ z{UYgg3KndUlnb=dUqe7mezSZ9c|yrqt(ja5qA)zXG6U#yIz2+lr5(@8<+U$6O+xm7 zc92Guc^q*}7hR7tdQiNMV{nw&1VyZjM#Y_BeKhY$0d?YSs)r*(?a)fg8XGho1`^{T zb9+WY-{zBz>7cnY?W)F!s^P%P=7JkA)WOXF2Dxy2=P7?tTOb5G$=BJ>qmEYP_y$zJ zT`bUH3Y{L!tOIRb}x=Cav zzdf+A8^6eK?-*S`HUA*-MOlw z4Ii=qWpSTN_tK3JleEY#r0ZLRczkmx&nARMZJJwar;D9aG{rc2Z6~ozAmaGuvSyd_uqY4vT zl$qhzqYX&*bu-6{dtYtp53`k;|X}r-dbMyt4Boqqen>oqetW$ zSpl9V;Y3saTaTEh7wi8-mT2X-Q#eQ^H;;TcDNWC>NrwI}J)%d1P!1Y0Jim9JZdfmK zI3Xx?^3Y3Em#&^^2Kq2_-w$f6QHDc<$@!2U`8RL)N)J)MLA7wd(&0gPWkQFDP$uuV zQK$Q27QJM5=&5!eBMU+huz!ozSRPk_KZc=v>`FGrzx9Zizj}mdHIp{OUp+!rXzs5b zVdnJBh|=;`k09_7l|Q)r5*FfMVKLwVxV2<{rdu4rmvA4!H_N-5 zeAu$(1-vjvxEIvpR>OjWyb*yqtG*%iyJ1RL7|wJ@8xMx5JHh>8@wvY1Up~;|p_ThZ z)N2ywAI_k%u0uOy2!W6}vA-C+oHHPoSV@Iv{A*vlM45Tsa#c{O|7@D^NtMGr_K~h3 zEFGKu8oYNKyH4stXAuj`=%TcM@@s7BkzOYm6jU)}o(7R3Q$7l_j2=i?2PHR~Jb z%jbBfluMfl0HF8Wr|-UJrU&DvM>P4_88%oZxVf0NSZ4ZX1c8076}MFYG!@=!KBQ{2 zXL5E{1avrUny4*hgmAru!m5w-xsv1(3HI@p-Af_-uU0p5Q6KYjjKyyd)$ zus(}8LOLJ+Xr#+G88{iT|8G8m{eSp~1po|+NOn$%QK7oYcw~r;#J_w5I&^>QKYRqD znZ)Gyb_?F<#>`iiLbgKpO7sHvzxjwvi%hnE^AXE$sGu(=a1VLMlG&ZExUOR#YfPozgkAn}Eoy+b_{JV&otoqYxjOSzghVeRntfzj&Wa9l zC*A*XbE8E%{2t+3abie`fd)o=s5^MPrCKvLNO!y_w{XL{{K9zC9n#p5>gaFbg@((c zI)bC7?O12qaWoOj+aGs{%F(?zn~j=r9De(7OiQ49Bns%hW_Ko+`2w0;CT8)4R|=-} zbYEVg#pKh3c%Jnj{_MAOn6WBJ3ve>nsBx|Ghy(WOE1d3qUG62;iyd8U=;$7x5Sr!U z?D#p$n3O*ybR~#qQL=H*cSnj!hnut^duED8Ev{v!hjhf(^v008ugphC!|^lCI8(8WBw%OXqNv7Gm`2Y z@Q%BzeM!p+n-h$8Mbfgdn`sOxCEo!&6NqDyS_JbPw$TRqJa2$Iqb<4&%H{voBQle> zox0cpaXsFq7p(xpZtuXvqu6*{-)jr98;1Yt5uH`%qkr`X#o}GTzk0-bB3k=jJ)#+L zikFo|2WZ7-t+`qyAade^>^s!4;u6gh*bypK%MNPu?r;sqIuyqjc>%s5eFbn#3H@$7 z!hvDub@sNTJ!EgCyeO7!>aQL#Zb%OLA9}>Ok~}@IJ5bR}+CO@P9)}?}59!vw^$23K zfEv~{v6K4e8UJ|HCrlR8CQ$-;*-x73_HosKIVBN2^^ZuhS~&9*AT*^^fdChPzk0;D zj4&Isl3TMTvD}UO(#I{kP`$PE+qw9m3@MR4!zB=9k%`PLB4=2J__0 zQj6JnZ%~7@D&uig93QYLlZ?Z4o>n`?ey_=FV^){AsY&xirgIsFnbQ>m7Kf>|w?r**43PKRHSGZ4iL8`#J3229)|B z`d`wxRU6Q%53p+Ijd_`ITrzgA5ayUFrxQ1TbX6#KX|jqv6!cDWkQlSQm~_=IrXal=4P@;)lm2NWMVO%Jm0rs^_$7I#TDO zS=iV`d|U3(Fy|uZ%d03OA5;B6S3Pt{%&6abvV4<-xASuuL-f3?8V=A7EEY?^-z%K7m295ExqGb-E3Xqld13`Du`GKa=6OuW?~9**{2ZL;7hq*%y>oS%C`S- z{i4qN07Cdw0Nodtsb5abJ35GZkgOE@+6PH#A`j$2U9t?Ap_v+Qw} z3hN#X(D`Kvf5ajd;jXO?wmmDic+lVecwD0TnSeiW?PoW^;+?MQ?#h!x6uXTieT$o* z1|Dn>xTRbw;=J6j!9wR$e7hK}Dq4Wx#1V&6n|zy+=lK#Ls_Z-yzNk{fsp(VBEe2WL z?i*FY>87=E83Isl?Ylq@Jus7QKt|~l2|S}Ua(8iW!SOt!-1Q>&Q>be{Un$$`zXJ5#R~YIbZNva#-Ll17UxM(>sKV@- zb{Ldg_8R6hhi+?2R!ms{ByS0=?pUq!;N@PqpgqP^lOZUzfEJ%e0 zMaZ3z@Z`K%U792JU7QlDTm>?CwbX8ExOy%xo|GmbqJ*xrpsqyyixe`S z4Pi(~$^c1=je|DAy8te4&9;;HKnjias>1Np`1WWjNqNnUX%e2M<89&qhEAi?C-O*& zk1%ukvH%^PB88MLAfWsFnv2f1G86rr%FhAZ&N?a9pgOP5;-bK=a!16@2!(5lJQ??fm&eqj4J&}bui9myR>&wzX-P5~r7WU%!W$!oe+^_DeZ?rN4 zJw!KSzqfTA)q^Ya`pD`yM?vHykhM0e3+SK@SV1+nXiuFl9O8HWl~QNzM8F01MO9PE zsW&@DG80@`4p&>5277ivyXLP;(DMsB*2!iE<3j$#ij9vu)x1W=vB>E^_}0;8ZAPBG6uUxPSRIq=j6M2iAbHty&U|l$v&^@dsSuwVt>;-5c-dX#7bR^fvO7<-%n&=M z=j!?KPl-g}u|1sD5xM-U2*?ED3__W+93;`ybw7QsK05=0z1(Fc0=&tz%S0`VH9lDo)L<;JI_Mec!GSZ@ z=6ao-#m%+FJ;jU!%dv69pQoC= zd&GLcZ<&aw#!Q|tE4My^rOIx!)!)2aaszbV5-;x>w~ldNTocS5H`?%?+mqaW{4|Ep ziGO=BO0R73zG2Ensbpfi3zLcaU40PtM6*qzvxw)Gxn%P8w(vlu;mbypKnq-LKsgI| zoQHDyF309i6yU+H5Z4k^a3Qp15f0sKPcLh6LeXASn$Z^9C$0@T-{P!?9y6~Z!m$0T z=8oNC`jj>I`FC8On?fh+?nP3*hX4A75U91WD~-T)Kt5J@`bcb_x+th62W@W#%ArE; zzc#5Qsb00JN!y#H=p|4+1n@IU4?`-%M@^Zu_p*#DLDw}bsZbN&(-|M^Wg|3?lH7r_5d5aVAF zi~mG`fc|{}{I3fO5CFi^>+jS50#Hi_2&^9-ao~Ia0G)mS08mQ<1QY-W00;nSRY_X_ z00000000000000803ZNqZgg^QE^TCWcnbgl1ONa400aO40031~4FCrR%I9bY%I9bY z%I9dMSlx~rH59%_;vJ6YO%mmY7PwiimTp^?LN{y{A+$n@Gvg$tGvlf4Nj9n~@eW+^ zdOQi=u{|@HY|;jC)9%>E=l}1^6Z&O58`D%cSvV3!N_R%2G8g78-7J?Xk<_~`Qdvs; z1Bz+2$dp}6)BpUl&p&(eq&>KxD^bv`&PAcAXSX^_glnjbH1b`gta8%w*>Ad{yt0ng zVk1eAkt<~#h*C=BMrOK{hD4I+3PQKat;ww=-G55i-+OE4N_#PxG+f4&Eu9{(^rlZv zlU_KX3OuIE={3ETyD?F%P=ZsdRs~h1=We7k3Vdj%E5o$3G&=X13fm1YA6SZ~g?BO9b!T4*?LFnCuU)LcU6WhNh>k{r@nt=6NB&Z=D2 z%6e_0=R_8r@uUvg%=6*H5zV0jO<+T&lHi_65HqJyB=q7U<9$M^tSVM?V3eia{M~#= zbGU~;`A;K?m3-NLTQ~*(OP7rM-d9Ao5|)D}$JObQo_z!T6KzsBZ-;bTiYh}Au4O?; z?LBG2NV26&)KbYb<`K+dpB=YrL{n*CQqK7&(v2t*csyK2lMu-hvG7$8EgO=ztNkp+ zN)=w%FeZr1m~)0K!(p`a#e>MpOkRA#|C3a23zo@&xUGvIs%fN!J1n7yYBG*eF5HQr zj6da;j<~CuCr9J4$Um$u2sx41O;;-XrgD`D)A&o+eI8yqnpmk-;SRI%vQ-Mzj0TbU zN_`>lP%k~3rOq`p$o5B*N4P7tx%UP;$)=Pf+XA7&6r%vyb_WyXgbD^q& zu=m-?0>y^Boke2dU#gdPdF?#$z4EiH(X#fUl~et$aV^~)ul{#)%7J2`WBp!>w`8j9 zUXkTf2{1Z1`~fozA+Iep-AXDUt65+c&RWW@Rp$ z^stxj#{E-gt|y;NTJ&u1OKp#*c}*(%G5b$`Jp8Rdd-@F@i)Z0G?uM&OIe5hCp_a9m z30tM^`ggPbb^V#juRp8P$R;#o;j2itqZe);auam--<~~hitzC#6VF`|+!MIS*hh-{ zrh<0=*{3FVZg84S5n)~_d#<`@rzFc(WznnWkI6s(YWJ`7Y_#fm|IZH(6teR!znpk* zb??LyEwgtlzg7PiN-XhcoNEvOTw%Iw(X3UGOjYf|YwHE({69Tk`SRM2lXbqQseaB| z_Eh=Zf9JRVl^*L{y?;Huv?Fit)8)zg#oqDg#!bHRG{Z}Gld|vhbKbFkBthVoMZ?ACTLiv%W zrR+7YCU1Mv)=6oL48-J*WlvB4oA60`W1#kr9!1{#fW}OAo!*)6%$)4=j%?_#R*b7S z@s)$?82gEw*WV20ycg6_Hp_X(P?LTuhJ0A1A)XI)9$) zcY5FT2Rrr39S{G~ROdNw=gD=$TP@*ZY5!t-mY zpj*f@77!LPeIL?!Vw3C??Vx)- z54pqU?A@CuvT!TQ0<%5V=jGkzq%YXH;JeO}e}4@6HNWq2NMDehz1red-4V8TQ44;T z+{sUxS_(`bH7AbpMI1Xharp_$0@gLZVz!naQL0eugDtnKghm&=oqPMq>#wnmW=-zmYrZ=zQQ@4O-^R{w0Z zFpK4aLk$i>XK%b(cr3+kZfl}<%@WD=SA#D;e=c-4Io9AA|FS5vEl2-#EskCw@jYCO zn`d5FE*T1i@&?({HrhmOj+Tt-k#J?O}nkw;m@_c9i{c@K!>(8$>Uen#` zn0TbmapO(CWzQq}<6_SKiZOQBJG1TAvad=-KG*FdSy(4Vt?hq(k!@w6twqzr=nVep z8`%$^GJ4W*p#F~N;uh&2>MzV#Ys6=k2Za1rUEjU`SZQJBBgdD$`#IL_*zd|Am^wvu z`nSI;FS(`N-tep{yf193*VB}Vw=9hJC;68@^O>AnYBqnzyKmnjayDNus@y4iiRm$0 z=li>7N|Wa1a5Sga{(iQI?MChox2jN;$f?)#r{tc#r_DDfQB=Id)lC~)E6LZL z8f*TSDt&(WoFT?``TB=VnRh;h81Fb-b@KZGNdwht=?^~56We=4S^eLD_m3WWY#^L{Hk1H)+%P*Z@BNrYL1fddF*qCBIKn+e