Versions Compared
Key
- This line was added.
- This line was removed.
- Formatting was changed.
Table of Contents
Table of Contents |
---|
IPscreener API Specification
Version 2.1
General
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.
API updates / change log
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.
Service Management and Support
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.
- Support is available Monday-Friday 8:30-17:00 CEST
- The taget uptime for the IPscreener service is 99%, excluding scheduled service break points (normally 4 occasions per year scheduled on weekends).
- A ticket response will normally be provided within 2 hours during office hours, where we address the following topics:
- Notification that the support team has received your request.
- Possible request from the support team for further information.
- Information about how the issue is going to be handled.
- Solutions and assistance will be provided in-line with timescales dependent on the priority of the support request:
- Within 8 hours (during business hours) for issues classified as High priority.
- Within 48 hours for issues classified as Medium priority.
- Within 10 working days for issues classified as Low priority.
Terms of Use
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.
Disclaimer
- The sample method calls, success response and error response in API details are provided for general information purposes only.
- The terminology used in this document may differ from other specifications of API's for fetching of data.
Introduction to IPscreener
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.
System Security Frame Work
The API is hosted in a protected and secure environment including the protection of the user information and data.
- We have our own dedicated self-hosted servers for hosting the API, located in a 24/7 guarded vault in Stockholm, Sweden.
- A security surveillance system protects and prevents unauthorized traffic from accessing the network. It also ensures the implementation and compliance of the organization's regulatory policy.
- A hardware based firewall is implemented to secure the network traffic.
- When the clients access the API, no client information is stored/cached in the system except for the session ticket and case reference number. This data is used to track the number of performed searches.
- The API server has an EV SSL certificate implemented which provides an assured encryption level.
API Authentication Procedure
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.
API Pricing Model
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 IPscreener Search Procedure
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.
- An API authorization key is needed for performing any access request.
- The request is initiated by the user specifying the search query text and how many records to be fetched in the result set. Optionally the user may also manually select what indexes to search with the query text. A maximum of three indexes may be searched in parallel. Index values is received by using the Index API.
- As a response to a query a session ticket is received. This ticket is used to fetch result data when ready for delivery. Thus, note that polling from the requesting part needed.
- The response is a result list with a number of hits representing the top most relevant documents corresponding to the content of the search query text. The hits are sorted in order of relevance. The result list includes for each hit the patent number, the associated relevance score and the additional requested document information.
- To fetch a PDF document for hit provided in the search response, insert each patent number a URL parameter request in the PDF API. The PDF document is encoded in base64 format.
- The maximum number of requests allowed are limited to 10 fetches per minute.
Fig. 3 IPscreener search procedure and identification steps.
IPscreener optimization and index selection structure
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.
Boost mode (beta)
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.
API Endpoints
The index API
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
|
The IPscreener search API
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.
Request result
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 | Headerclient-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. Bodyquery: 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 responsex-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. |
Receive result
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 | Headerauthorization: An API authorization key must be sent with all requests. You need to contact the IPscreener support team to get the API authorization key. Bodyticket: 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 for document retrieval
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. |