IPscreener API Specification
Version 2.1
This is a technical documentation that describes the IPscreener API's interaction with the AutoMatch search engine. The specification is intended for those who are experienced in programming software applications and intend to implement the IPscreener API service. This documentation is subject to continuous change, however normally backward compatibility is maintained.
This document will be updated with the latest information regarding the API structure and functionality. Notifications of changes will be sent to registered users via email.
The support is managed by the IPscreener team and contact is encouraged for any inquiries, as well for technical matters as for user specific questions. For any questions, please contact our support team by sending an email to support@ipscreener.com.
The terms of use for the APIs are regulated by agreements and the general terms for web services. We apply a strict fair usage principle and in endeavoring to make the IPscreener API stable for everyone to use, we place restrictions on the number of requests you can make to the service. If you exceed the limits set out we may throttle, suspend or terminate your access. The set limit may be adjusted by us when updating the IPscreener API. For more information please refer to the general terms, which sent upon request from support@ipscreener.com.
IPscreener is a decision support tool based on semantic technology used for automatic prior art retrieval. When feeding a raw text to the IPscreener API, the AutoMatch search engine converts this text to a fingerprint representation. This representation is used to fetch the most similar documents reflecting the context of the query text. This is done from a specially tailored global reference database of patent documents. Thus, relevant prior art is identified and presented to a user in a client platform without any manual interaction needed. Therefore, each review of an idea along the innovation process is given a support for faster decisions, better priority of resources and at a higher quality.
The IPscreener API is implemented as a standalone-module that is easily integrated with any existing commercial or internal patent administration system. The API service is built using REST principles which ensures predictable URLs that supports easy connectivity and communication. For a descriptive overview of the data flow see Fig. 1. The IPscreener REST API follows standard HTTP rules, enabling a wide range of HTTP clients to be able to interact with the service.
The IPscreener API system architecture
Fig. 1 The IPscreener API data flow architecture showing data traffic over Internet for a query and response.
The API is hosted in a protected and secure environment including the protection of the user information and data.
The API authentication is implemented as token authentication over the secure HTTPS protocol. By default there is no restriction on the IP-address from which the requests can be sent or from witch domain the request must come from (CORS). If the client requires additional security they can contact the support team to have a IP-address restriction and CORS enabled for their API authorization key. The client will then have to provide a list of IP numbers or an IP range that will be white listed, i.e. requests to API service is only possible form the specified IP addresses. Likewise, the same principle applies for registering whitelisted domains. You may retrieve API credentials and register associated IP restrictions by contacting the IPscreener support team, support@ipscreener.com.
There are two levels of user identification employed by the IPscreener API service. If the user is an end customer, e.g. direct end user, only the authorization key is needed when accessing the service, where said key also includes the client identification. When the client is a platform provider which in turn have their respective clients being the platform provider's end users, also the respective end user client-id has to be submitted in the header in the API request. In order for a platform provider to register and obtain a client-id for a new platform client, contact the IPscreener support team, support@ipscreener.com. A description of the hierarchy is revealed in Fig. 2.
Fig. 2 The access level hierarchy used to identify search requests for platform providers and end users.
The IPscreener API uses normally a transaction-fee based pricing model. Hence, you will need to purchase credits (the number of searches to be performed) in advance to use the API service. For more information contact the IPscreener team at support@ipscreener.com. A notification e-mail will be sent when there are few credits remaining or when the contract period is about to expire.
The procedure for performing a search request via the API services is done according to the following steps. A general overview and introduction to this procedure of these steps is presented in Fig. 3 below.
Fig. 3 IPscreener search procedure and identification steps.
The AutoMatch search engine comprises advanced logic to optimize the search query according to the input text. In the default setup it automatically select the most appropriate settings for best recall and precision. This includes the possibility to also retrieve the paragraph considered by the algorithm to be most relevant for a specific retrieved document. The user may also manually select specific technically optimized domain indexes to be used during the query process. This includes the selection of customer specific indexes such as e.g. the archive of internal invention disclosures or adapted customizations. A summary overview of the index setup is shown in Fig. 4. For more information on special indexes and how to order and create them, contact the IPscreener support team, support@ipscreener.com.
Fig 4. Showing the layout structure for technical optimizations versus the IPscreener master collection.
The next generation of IPscreener has an improved algorithm and extra layers of semantic analysis. This means that the engine identifies the technical domain that is optimized for the search query as such and tunes the settings accordingly. Currently the pilot running with the new analytic features is in a separate option named Boost. For trying out this new feature, use the switch "boost" with the optional index parameter. This feature is still in beta mode until further notice.
The Index API is used to retrieve the indexes accessible by a customer by the end client, whereby both the technical description of an index as well as the access number is provided. If no index is specified in the search request, the master index will be used as default. A maximum of three parallel indexes may be accessed in one single IPscreener query this includes customer specific indexes as well. If you are a platform provider, by adding the client-id header you will also see the technical index list available for your respective clients in your platform.
URL | |||||||
Method | GET | ||||||
Headers | Required: authorization=[UTF-8 encoded max 100 char] Optional: client-id=[positive integer] | ||||||
Success Response | Body content format: JSON HTTP Status Code: 200 OK
| ||||||
Error Response | HTTP Status Code: 401 Unauthorized (No API authorization key found)
HTTP Status Code: 403 Forbidden (Using wrong API authorization key)
HTTP Status Code: 403 Forbidden (When the IP restriction is activated and source IP is not whitelisted)
HTTP Status Code: 429 Too many requests (API rate limit exceeded)
HTTP Status Code: 422 Unprocessable entity (When using invalid client-id)
Sample Call
Notes
|
This API receives a text query input and then uses the AutoMatch semantic search engine to retrieve similar results from the worldwide patent database collection. The search procedure includes a first response to a query by returning a session ticket, which then is used to retrieve the results when ready for retrieval. Processing an IPscreeener query typically takes 15-30 seconds, and the patent data is delivered in a JSON format. The number of records delivered depends on the figure specified by the requested-hits parameter and are presented in order of ranked relevance. If the requested-hits parameter is null or absent, 25 records are returned by default. The request procedure is optimized for returning up to 100 records.
If no switches are provided IPscreener will select the most appropriate general settings for carrying out the semantic matching procedure, and returns a single result list. If the query specifies several indexes to be queried in the request, the number of results set by the requested-hits parameter applies to all. Thus, this is the number retrieved for each and one of the queried indexes, where the results for each index are presented sequentially according to the request order in the query string.
To note; we have a pilot running on a new feature where IPscreener performs an extra layer of analysis. For trying this new feature out use the switch "boost" as the optional index parameter. This feature is still in beta mode until further notice.
URL | ||||||||||||||
Method | POST | |||||||||||||
Headers | Required: reference-number=[UTF-8 encoded max 100 char] Optional: client-id=[positive integer] | |||||||||||||
Body | Required: query=[UTF-8 encoded] Optional: requested-hits=[positive integer] view=[bibliographic, claim, description, image, pdf, passage] index=[positive integer(s) with comma separator or value 'boost' (beta) ] | |||||||||||||
Success Response | Body content format: JSON The below response will be returned while the request is still being processed. HTTP Status Code: 200 OK
Do note; the response below is an example where we have truncated the data for several fields to make the view more condensed and comprehensive. | |||||||||||||
Error Response | HTTP Status Code: 401 Unauthorized (No API authorization key found)
HTTP Status Code: 403 Forbidden (Using wrong API authorization key)
HTTP Status Code: 403 Forbidden (When the IP restriction is activated and source IP is not whitelisted)
HTTP Status Code: 422 Unprocessable entity (When using invalid client-id)
HTTP Status Code: 422 Unprocessable entity (When null value passed in query parameter)
HTTP Status Code: 422 Unprocessable entity (When null value passed in reference-number parameter)
HTTP Status Code: 422 Unprocessable entity (When wrong value passed in requested-hits parameter)
HTTP Status Code: 422 Unprocessable entity (When greater than 100 value passed in requested-hits parameter)
HTTP Status Code: 422 Unprocessable entity (When wrong value passed in view parameter)
HTTP Status Code: 429 Too many requests (API rate limit exceeded)
HTTP Status Code: 422 Unprocessable entity (When wrong value passed into index parameter)
HTTP Status Code: 422 Unprocessable entity (When null value passed into index parameter)
HTTP Status Code: 408 Request Timeout (When one or many indexes are offline or having other troubles)
| |||||||||||||
Sample Call |
| |||||||||||||
Notes | Header client-id: This value relates to the identification of an end client for a platform provider. To retrieve a client-id for a new or existing client, contact the IPscreener support team. authorization: An API authorization key must be sent with all requests. You need to contact the IPscreener support team to get the API authorization key.reference-number: This number is used for tracking the API calls for each client. The same number which is sent as input is returned in the header without any modifications. Body query: The text on which the search is performed. requested-hits: This is the number of relevant hit records which you want to fetch in the result list. If this parameter is not used in the search request, by default 25 records are returned. view: This input parameter is used to specify the data fields that are required to be returned for each hit in the response. You can specify a combination of fields using comma to separate the values. If this parameter is not used is all data fields except the description field are fetched. The available field parameters are: bibliographic (includes Applicant, Inventor, Class, Title and Abstract fields, all sections can return multiple data) claim (Covers all the patent claims) description (This is the full description, tables and charts are excluded) image (Presented in base64 format) pdf (An URL link to the PDF API is provided) passage (The paragraph within a document that the AutoMatch engine considers to be most relevant) Header response x-ratelimit-limit-minute: The figure shows how many request of the API endpoint that is possible to do per minute. Accessing the API service at a higher rate will result in a block access until following subsequent one minute period has begun. x-ratelimit-remaining-minute: This indicates how many requests for the current minute that are left within the current minute period. data: the session ticket value associated with a search request used to GET the search results. |
URL | |||||
Method | GET | ||||
Header | Required: authorization=[UTF-8 encoded max 100 char] | ||||
Body | Required: ticket=[ticket value, string] | ||||
Success Response | Body content format: JSON The below response will be returned while the request is still being processed. HTTP Status Code: 202 Accepted
When checking if data is ready for retrieval you only use the parameter ticket value. The response below will be returned once the search request has been processed and is ready for delivery. Do note; the response below is an example where we have truncated the data for several fields to make the view more condensed and comprehensive.
| ||||
Error Response | HTTP Status Code: 204 No Content (When no result could be found)
HTTP Status Code: 404 Not Found (When wrong value passed into ticket parameter)
HTTP Status Code: 404 Not Found (When empty value passed into ticket parameter)
HTTP Status Code: 429 Too many requests (API rate limit exceeded)
| ||||
Sample Call |
| ||||
Notes | Header authorization: An API authorization key must be sent with all requests. You need to contact the IPscreener support team to get the API authorization key. Body ticket: The ticket value used to retrieve the results is the ticket session identification data string received by the POST search request.
index value: After the parameter automatch-result there is an integer value, e.g. index-1. This value indicates the specific index and associated settings used for performing the matching procedure. If several indexes are targeted with a search (maximum three in parallel), each result list will be presented separately, one after the other. score: The score is the AutoMatch engine indication of the estimated relevance of a document. position: The position refers to the record number of the hit in the search results, where the search results are sorted on the relevance score value in descending order. country: This returns a two-letter country code describing the origin of the patent publication. number: It is the publication number for the application or the granted patent retrieved. kind-code: The kind codes are used to identify the type of patent publication. More information on this syntax is available at: www.wipo.org. Some of the most common kind codes are:
family-number: Patent family is a set of interrelated patent applications filed in one or more countries to protect the same invention by inventor(s). Each patent family has a unique number and this value returns that number. Family numbers are provided by EPO according to the Inpadoc specification. publication-date: The publication date is the date on which a patent application/grant is first published. It is the date on which the document is made available to the public. bibliographic: The bibliographic data section includes reference data on who is behind the patent application as well as summary data on the content and the technical field. applicant (array): This field provides information about the patent owner(s) or applicant(s).
inventor (array): This field provides information about the inventor(s).
class (array): The classification scheme is a system of codes that groups inventions according to technical area, where IPC and CPC is the most common. The class information is divided into the follwoing hierarchy, including four sections:
title (array): This section includes the full title of the patent.
abstract (array): This is the summary describing the essence of the scope of a patent.
claim (array): A claim defines exactly what is claimed by the invention and therefore what is sought to be protected. It clearly lays down what the patent does and does not cover.
description (array): The detailed description describes in detail what the invention is and how it is made and used. It reflects the complete picture of the invention.
image: It contains the first image of the patent document.
pdf: It provides a PDF API link. This link enables access to download the full PDF document. passage: Shows the paragraph within a document that the AutoMatch engine considered to be most relevant to the query.
|
The PDF API is used to retrieve the original patent document(s) corresponding to a search query. From the requested patent number input via an URL query, the API request returns a PDF file in base64 format.
URL | |||||||
Method | GET | ||||||
Headers | Required: authorization=[UTF-8 encoded] | ||||||
URL Parameters | Required: | ||||||
Success Response | HTTP Status Code: 200 OK
| ||||||
Error Response | HTTP Status Code: 401 Unauthorized (No API authorization key found)
HTTP Status Code: 403 Forbidden (Using wrong API authorization key)
HTTP Status Code: 403 Forbidden (When the IP restriction is activated and source IP is not whitelisted)
HTTP Status Code: 404 Not found (PDF is not available)
HTTP Status Code: 422 Unprocessable entity (When null value passed in patent-number parameter)
HTTP Status Code: 429 Too many requests (API rate limit exceeded)
| ||||||
Sample Call |
| ||||||
Notes | authorization: An API authorization key must be sent with all requests. You need to contact the IPscreener support team to get the API authorization key. patent-number: This descriptor represents uniquely a patent publications. The full patent number is based on a country code, a number and a kind code, separated with hyphens, e.g. US-2006258329-A1. The format of the patent number must be DocDB. data: Retrieval of a complete PDF document encoded in Base64 format. |