Reporting

Reporting provides a set of services to create, process, and retrieve either CSV extracts or XML extracts from CLAIMS Direct. Reports are available for six months after they are created. Please download any reports older than six months that you wish to keep. Reports can be downloaded through the API using https://cdws21.ificlaims.com/reports/<report-id>/<report-name>.

In brief, you can use the interface to do the following:

  1. /report/create: create a report – defining the data selection criteria
  2. /report/queue: queue the report – defining the processing and packaging requirements for the report delivery
  3. /report/status: check the status of the report progress – from queued to complete
  4. /report/list: get a list of current reports
  5. /report/detail: get a list of the details related to a particular report
  6. /report/delete: delete a report
  7. /report/columns: get a list of the columns supported by CSV reporting

Note that whereas CSV reporting does allow you to select the columns or fields that you want included in the report, the XML output assumes you want the complete XML record. Also note that while the XML output allows for batching of the output into multiple files in order to keep file sizes manageable, the CSV report assumes you want everything in one file.

The details of the service calls are below.

/report/create

Method(s)GET | POST

Path

/report/create

Parameter
ValuesDescription

@nameString: ex. test-report-01Report name. Special Unix/Linux characters may not be used in report names. Valid characters include alphas, numerics, dashes, and underscores.

@typeString: ex. csvReport type, one of 'csv' or 'xml' (default=xml)

@sourceString: ex. searchReport source, one of 'search', 'list' or 'table' (default=list)

@criteriaString: ex. pnctry:us AND solar

Report criteria. Depending on @source, this will be either a valid Solr search query, a space, comma or new-line-separated list of ucids or an existing schema-qualified DWH table name containing the required column ucid.

For long ucid lists and complicated queries, the POST method should be used.


@solrparamsunused, set internally



@solrurlunused, set internally

The following options pertain to @type = csv

@csv.colsString: ex. c1,c2

Comma-separated list of columns to include. Columns will be output in order given.
Currently available columns:

Note

Columns containing multiple values will be separated by the '|' character, e.g. US | EP | WO

ColumnDescription
document-ucidDocument identifier (ucid)
document-countryCountry of publication
document-numberPatent/publication number
document-kindPublication kind code
document-dateDate of publication (YYYYMMDD)
document-yearYear of publication (YYYY)
application-ucidApplication filing identifier (ucid)
application-countryFiling country
application-numberFiling number
application-kindFiling kind code
application-dateDate of filing (YYYYMMDD)
application-yearYear of filing (YYYY)
priority-numberPriority numbers (ucids)
priority-countryPriority countries
priority-datePriority filing dates (YYYYMMDD)
priority-yearPriority filing years (YYYY)
us-class-primaryPrimary US classification
us-classAll US classifications
cpcCPC
cpc-first-inventiveFirst inventive CPC
ipcrIPCR
ipcIPC
eclaECLA
f-termsF-terms
patent-citationsPatent citations
non-patent-citationsNon-patent citations
forward-citationsForward citations
related-applicationsRelated applications
assignee-applicantAssignees/applicants
epo-assignee-applicantDOCDB standardized assignees/applicants
inventorInventors
agentAgents
correspondentCorrespondent
examinerExaminer
pct-application-numberPCT filing number (ucid)
designated-statesEP and PCT designated states
abstractEnglish abstract or, if no English abstract exists, the abstract in the language of publication
first-claimFirst claim
english-claimsClaims in English
original-claimsClaims in language of publication
espacenet-linkURL to espacenet
simple-familyList of ucids sharing the same family ID, as assigned by DOCDB
inpadoc-familyExtended family
legal-statusLegal status
titleEnglish language title or, if not present, title in publication language
ifi-expirationIFI anticipated patent expiration date
ifi-statusIFI patent status
ifi-publication-typeIFI publication type
ifi-adj-expirationIFI adjusted patent expiration date
ifi-assigneeIFI assignee
ifi-assignee-originalOriginal, as published, assignee
ifi-assignee-currentCurrent IFI assignee
ifi-assignee-probableProbable IFI assignee
family-idDOCDB-assigned simple family integer identifier
load-idmodified-load-id
date-producedDate on which CLAIMS Direct XML was produced

@csv.headerBool: ex. 1[ 0 | 1 ] Include column headers

@csv.nonlBool: ex. 1[ 0 | 1 ] Replace new lines (nl) with spaces

@csv.maxcolsizeInteger: ex. 32The maximum number of bytes allowed per column (overflow will be truncated). This value is assumed to be Kilobytes.

@csv.datefmt

String. Available Options:

yyyy-mm-dd
dd/mm/yyyy
mm/dd/yyyy
yyyymmdd

Ex. csv.datefmt=mm/dd/yyyy

(v3.9.1) The format of date output for the CSV columns: Publication Date, Application Date, Priority Date, Date Produced, IFI Expiration and IFI Adjusted Expiration dates.


Example:

wget -O- -q \
  --header 'x-user:x' \
  --header 'x-password:y' \
'https://cdws21.ificlaims.com/report/create?name=a-csv-report&type=csv&source=list&criteria=US-20140255094-A1,ES-2478140-A8,ES-2486245-T3' 


Response JSON

{
   "status" : "success"
   "time" : "0.015465",
   "report" : {
      "id" : "63cfdeb1-0162-444f-9ffa-a1ddd18de7d1"
   },
}


Response Object
Member
Value

@statussuccess | error

@timeInternal request time in seconds

@report.idUnique identifier of the report

@messageIn case of error, this may optionally contain the reason for failure


/report/queue

MethodGET

Path

/report/queue

Parameter
ValuesDescription

@idString: ex. e16eebc9-6965...Report identifier

@nthreadsInteger: ex. 4Maximum number of backend processes used to generate report (2, 4 or 8, default=4)

@batchsizeInteger: ex. 100Number of documents to process per thread (default=200)

@batchprefixString: ex. my-prefix

Output file name(s) prefix. For example, running an xml report with @package_type=batched, output tar file will contain:

<report-name>.tar:
my-prefix.00000001.xml
my-prefix.00000002.xml
my-prefix.00000003.xml
my-prefix.00000004.xml 

Default=batch


@package_typeString: ex. archived

Report package type. Valid types include:

    • single: output single file. For report type csv, this is the only available package_type, for report type xml, the output file will contain multiple XML documents
    • archived: (xml only) output tar archive with predictable path to individual documents
    • archived_attachments: (xml only) archived package including associated attachments
    • batched: (xml only) output tar archive containing raw batches

@package_suffixUnused: generated internally based on package_type and package_compression

The following table shows the generated suffix:

Type
No compression
Gzip
Zip
single<report-name>.csv | .xml<report-name>.gz<report-name>.zip
archived<report-name>.tar<report-name>.tar.gz<report-name>.tar.zip
batched<report-name>.tar<report-name>.tar.gz.<report-name>.tar.zip

@package_compressionString: ex. gzipValid values are one of: __none__ (default), gzip or zip

@priorityInteger: ex. 1Setting a priority > 0 will prioritize processing of report higher. Default behavior is to process each report in order of en-queue.


Example:

wget -O- -q \
  --header 'x-user:x' \
  --header 'x-password:y' \
'https://cdws21.ificlaims.com/report/queue?id=99a479b9-4a73-4f27-b8b1-44b052844e23'


Response JSON

{
   "status" : "success",
   "time" : "0.064897"
   "queue" : {
      "id" : 257
   },
}
Response Object
Member
Value

@statussuccess | error

@queue.idReport queue identifier (currently unused in other requests)

@messageIn case of error, this may optionally contain the reason for failure


/report/status

MethodGET

Path

/report/status

Parameter
ValuesDescription

@idString: ex. e16eebc9-6965-41a4-9337-8f76d8953a89Report identifier


Example:

wget -O- \
  --header 'x-user:x' \
  --header 'x-password:y' \
'https://cdws21.ificlaims.com/report/status?id=99a479b9-4a73-4f27-b8b1-44b052844e23'


Response JSON

{
   "time" : " 0.041137",
   "status" : "success",
   "report" : {
      "percent_complete" : "0.000",
      "completed_status" : null,
      "completed_stamp" : null,
      "ndocs" : 0,
      "completed_error" : null,
      "ndocs_processed" : 0,
      "running_status" : "queued",
      "entered_stamp" : "2014-09-28 14:52:57",
      "completed_url" : null
   },
}
Response Object
Member
Value

@statussuccess | error

@messageIn case of error, this may optionally contain the reason for failure

@report.entered_stampTime stamp when report was queued for processing

@report.running_status

Stage of processing:

    • queued
    • preparing
    • extracting
    • packaging
    • complete 

@report.completed_urlWhen complete, the url of package

@report.completed_statussuccess | error

@report.completed_errorIf @completed_status == 'error', this may contain an optional error message pertaining to processing

@report.completed_stampTime stamp report processing completed

@report.ndocsTotal number of documents in report. Note: This value will be 0 until @running_status completes the preparation (preparing) stage.

@report.ndocs_processedTotal number of documents already processed

@report.percent_completeConvenience value of @ndocs_processed / @ndocs as a floating point, e.g., 0.000


/report/list

MethodGET

Path

/report/list

Parameter
ValuesDescription

@limitInteger: ex. 50Limit number of items to return (reporting has an upper limit of 30K per batch because deep paging can place undue stress on the system)

@offsetInteger: ex. 0Offset into returned list of items

Example:

wget -O- \
  --header 'x-user:x' \
  --header 'x-password:y' \
'https://cdws21.ificlaims.com/report/list?limit=1'


Response JSON

{
   "time" : "0.010817",
   "status" : "success",
   "reports" : [
      {
         "batchprefix" : "batch",
         "source" : "list",
         "name" : "a-csv-report",
         "solrurl" : "https://10.234.1.44:6000/alexandria-v2.1/alexandria",
         "batchsize" : 200,
         "completed_status" : null,
         "package_compression" : "zip",
         "package_sfx" : "csv",
         "completed_stamp" : null,
         "completed_error" : null,
         "running_status" : "queued",
         "solrparams" : null,
         "type" : "csv",
         "entered_stamp" : "2014-09-28 14:52:57.15773",
         "completed_url" : null,
         "id" : "63cfdeb1-0162-444f-9ffa-a1ddd18de7d1",
         "criteria" : "US-20140255094-A1,ES-2478140-A8,ES-2486245-T3",
         "package_type" : "single",
         "report_id" : 276,
         "csvopts" : "csv.nonl=1&csv.cols=__all__&csv.maxcolsize=32768&csv.header=1",
         "nthreads" : 4,
         "user_id" : 4,
         "process_id" : 257,
         "ndocs" : 0,
         "ndocs_processed" : 0
      }
  ]
}


/report/detail

MethodGET

Path

/report/detail

Parameter
ValuesDescription

@idString: ex. e16eebc9-6965-41a4-9337-8f76d8953a89Report identifier


Response JSON

{
   "time" : " 0.012368",
   "status" : "success",
   "report" : {
      "name" : "a-csv-report",
      "batchprefix" : "batch",
      "source" : "list",
      "completed_status" : null,
      "completed_stamp" : null,
      "package_sfx" : "csv",
      "package_compression" : "zip",
      "completed_error" : null,
      "solrurl" : "https://10.234.1.44:6000/alexandria-v2.1/alexandria",
      "batchsize" : 200,
      "completed_url" : null,
      "criteria" : "US-20140255094-A1,ES-2478140-A8,ES-2486245-T3",
      "tracker_id" : "63cfdeb1-0162-444f-9ffa-a1ddd18de7d1",
      "report_id" : 276,
      "package_type" : "single",
      "solrparams" : null,
      "running_status" : "queued",
      "type" : "csv",
      "entered_stamp" : "2014-09-28 14:52:57.15773",
      "nthreads" : 4,
      "user_id" : 4,
      "process_id" : 257,
      "ndocs" : 0,
      "ndocs_processed" : 0,
      "csvopts" : "csv.nonl=1&csv.cols=__all__&csv.maxcolsize=32768&csv.header=1"
   },
}


/report/delete

MethodGET

Path

/report/delete

Parameter
ValuesDescription

@idString: ex. e16eebc9-6965-41a4-9337-8f76d8953a89Report identifier


Response JSON

{
   "status" : "success",
   "time" : " 0.010436",
}


/report/columns

MethodGET

Path

/report/columns


Response JSON

{
   "time" : " 0.008741",
   "status" : "success",
   "columns" : [
      "document-ucid",
      "document-country",
      "document-number",
      "document-kind",
      "document-date",
      "document-year",
      "application-ucid",
      "application-country",
      "application-number",
      "application-kind",
      "application-date",
      "application-year",
      "priority-number",
      "priority-country",
      "priority-date",
      "priority-year",
      "us-class-primary",
      "us-class",
      "cpc",
      "cpc-first-inventive",
      "ipcr",
      "ipc",
      "ecla",
      "f-terms",
      "patent-citations",
      "forward-citations",
      "non-patent-citations",
      "related-applications",
      "assignee-applicant",
      "epo-assignee-applicant",
      "inventor",
      "agent",
      "correspondent",
      "examiner",
      "pct-application-number",
      "designated-states",
      "abstract",
      "first-claim",
      "english-claims",
      "original-claims",
      "espacenet-link",
      "simple-family",
      "inpadoc-family",
      "legal-status",
      "title",
      "ifi-expiration",
      "ifi-status",
      "ifi-publication-type",
      "ifi-adj-expiration",
      "ifi-assignee",
      "ifi-assignee-original",
      "ifi-assignee-current",
      "ifi-assignee-probable",
      "family-id",
      "load-id",
      "date-produced"
   ]
}