PQAI: API Usage Guide

[TOC]

Introduction

PQAI API enables you to use the data and functionality of PQAI in a programmatic way.

You can use it to obtain patent data (only US patents as of now), run similarity searches, predict CPCs given some technical text, etc. This guide shows all you can do with it.

Getting started

To get started the first thing you will need is an API access token.

The token is a unique ID that verifies real API users. It looks like this: 392cd21128f44cc496331c4c9c772b62. You can request one for free by filling this form on our website.

Make sure you include your email address, because that's where we are going to send your token.

Typically it will take us about a day to send you your token. In some instances (such as holidays) it may take us up to 2 days. If you haven't received your token after 2 days, feel free to email sam@projectpq.ai.

Once you get your token, you can begin using with the API.

Some programming experience is needed to make use of this API, although, its functionality can pretty much be tried out without writing any code by sending request via a web browser.

How to use the API?

How to formulate requests?

Every request has to go to one of the API routes.

The endpoints are listed in the next section. Each route specifies some parameters. They can be of two types:

Path parameters
Query string parameters

Path parameters are part of the URL. In this guide, they are preceded by a colon in the route URL. For example, the route below is one for getting a patent drawing:

/patents/:pn/drawings/:n

It contains two parameters, pn and n. To make a request, we have to replace them (along with the preceding colons) with their values.

To get drawing #4 of patent no. US7654321B2, the route will become: /patents/US7654321B2/drawings/4.

By adding this route to the PQAI endpoint, which is http://api.projectpq.ai, you get the final URL:

https://api.projectpq.ai/patents/US7654321B2/drawings/4

(if you open the above route in your browser, you should see the drawing returned by the API - try changing the patent and drawing number to get a hang of it)

Query string parameters come after the URL and are separated from it with a ? symbol.

Let's demonstrate with an example. There is another route in PQAI API similar to the one above. It returns thumbnails of drawings:

https://api.projectpq.ai/patents/US7654321B2/thumbnails/4

This route also accepts query string parameters. They are w and h, which specify the width and height of the thumbnail to be returned.

Let's try sending the w parameter with this route.

https://api.projectpq.ai/patents/US7654321B2/thumbnails/4?w=300

Note that query string parameters are sent by specifying their symbol, followed by = sign, and then followed by their value, which in this case, was 300.

To send multiple query string parameters, separate them with the & symbol, like so:

https://api.projectpq.ai/patents/US7654321B2/thumbnails/4?w=300&h=300

How to send requests?

Most endpoints accept HTTP GET requests, which you can make by using an appropriate HTTP client in any programming language (e.g., Python, Javascript, etc.).

Since these are GET requests, they can also be made by typing in a URL in your browser. Example:

https://api.projectpq.ai/patents/US10112730B2/thumbnails/2?w=400

How to use access token?

All requests (except a few, see note below) need to be authenticated with a token parameter, like so:

https://api.projectpq.ai/patents/US11154408B2?token=392cd21128f44cc496331c4c9c772b62

(note that the above request won't work because it uses a fake token)

Some requests, such as those for a patent drawing, do not require a token. In the next section, unless specified explicitly, the endpoint requires a valid token to be passed.

How to process responses?

Most endpoints return JSON responses.

How to make requests programmatically?

Python

Here is an example of making an API request in Python:

:::python
import requests

token = "392cd21128f44cc496331c4c9c772b62" # fake; replace with yours
endpoint = "https://api.projectpq.ai"      # address of the PQAI API
route = "/search/102"                      # search route
url = endpoint + route

query = "a fire fighting drone" # search query (can be paragraph long)
n = 10                          # no. of results to return
result_type = "patent"          # exclude research papers
after = "2016-01-01"            # return patents published post-2016

params = {                      # create parameter object
    "q": query,
    "n": n,
    "type": result_type,
    "after": after,
    "token": token
}
response = requests.get(url, params=params)  # send the request
assert response.status_code == 200           # error check

results = response.json().get("results")     # decode response
print(results)

Javascript

Here is the same example in Javascript:

:::javascript
var request = require('request');

const endpoint = "https://api.projectpq.ai";
const route = "/search/102";
const url = endpoint + route;

const qs = {
    q: "a fire fighting drone", // search query
    n: 10,                      // return 10 results
    type: "patent",             // exclude research papers
    after: "2016-01-01",        // return patents published post-2016
    token: "392cd21128f44cc496331c4c9c772b62" // fake; replace with yours
}

request({ url, qs }, (err, res, body) => {
    if(err) {
        console.log(err);
        return;
    }
    const results = JSON.parse(body).results;
    console.log(results);
});

Browser

The same request can be made by going to the following URL (put together manually):

https://api.projectpq.ai/search/102?q=a%20fire%fighting%20drone&n=10&type=patent&after=2016-01-01&token=392cd21128f44cc496331c4c9c772b62

(note that the above URL as such will give you an Invalid Token error. To get it to work, you'd have to replace the fake token in it with a valid one. The Getting Started section above describes how to get an access token.)

Routes

1. Retrieve prior-art documents with text query

Route: /search/102/

Query string parameters

Parameter	Value	Meaning	Example
`q`	String	Query	`"fire fighting drone"`
`lq`	String	Latent query	`"unmanned"`
`n`	Integer	No. of results	`10`
`offset`	Integer	Pagination offset (0-indexed)	`10` (for skipping first 10 results)
`index`	String	CPC subclass	`"H04W"` (`"auto"` for auto-select)
`after`	String	Cutoff date 1	`"2006-01-01"`
`before`	String	Cutoff date 2	`"2019-12-31"`
`type`	String	Document type	`"patent"` or `"npl"`
`snip`	Boolean	Include snippets	`1` or `0`
`maps`	Boolean	Include element-wise mapping	`1` or `0`

2. Retrieve prior-art combinations with text query

Route: /search/103/

Parameters: [Same as for /search/102/ route]

3. Retrieve prior-art for a patent (documents published before the filing date)

Route: /prior-art/patent/

Query string parameters

Parameter	Value	Meaning	Example
`pn`	String	Publication number	`"US7654321B2"`
`n`	Integer	No. of results	`10`
`offset`	Integer	Pagination offset (0-indexed)	`10` (for skipping first 10 results)
`index`	String	CPC subclass	`"H04W"` (`"auto"` for auto-select)
`type`	String	Document type	`"patent"` or `"npl"`

4. Retrieve similar documents to a patent

Route: /similar/

Parameters: [Same as /prior-art/patent/ route]

5. Retrieve snippet for a query-document pair

Route: /snippets/

Query string parameters:

Parameter	Value	Meaning	Example
`q`	String	Text query	`"drone"`
`pn`	String	Publication number	`"US10112730B2"`

6. Retrieve element-wise mapping for a query-document pair

Route: /mappings/

Parameters: [Same as /snippets/ route]

7. Retrieve a sample from a dataset

Route: /datasets/

Query string parameters

Parameter	Value	Meaning	Example
`n`	Integer	Sample number	`23`
`dataset`	String	Dataset name	`"PoC"`

8. Retrieve a document from PQAI database

Route: /documents/

Query string parameters

Parameter	Value	Meaning	Example
`id`	String	Document ID	`US7654321B2`

9. Get a patent drawing

Route: /patents/:pn/drawings/:n

Response type: PNG image (binary)

NOTE: Authentication token is NOT required for this route.

Path parameters

Parameter	Value	Meaning	Example
`pn`	String	Patent Number	`US7654321B2`
`n`	Integer	Drawing index	`3`

Query string parameters

Parameter	Value	Meaning	Example
`w`	Integer	Width	`300`
`h`	Integer	Height	`300`

We suggest you pass only one of the parameters w and h - if you pass both and their values are not appropriately set, the drawing may appear stretched along the horizontal or vertical direction (example: accurate, distorted).

10. Get list of drawings for a patent (to tell how many drawings are there)

Route: /patents/:pn/drawings

NOTE: Authentication token is NOT required for this route.

Path parameters

Parameter	Value	Meaning	Example
`pn`	String	Patent Number	`US7654321B2`

11. Get list of thumbnails available for a patent

Route: /patents/:pn/thumbnails

NOTE: Authentication token is NOT required for this route.

Path parameters

Parameter	Value	Meaning	Example
`pn`	String	Patent Number	`US7654321B2`

12. Get a thumbnail of a patent's drawing

Route: /patents/:pn/thumbnails/:n

NOTE: Authentication token is NOT required for this route.

Response type: PNG image (binary)

Path parameters

Parameter	Value	Meaning	Example
`pn`	String	Patent Number	`US7654321B2`
`n`	Integer	Thumbnail (drawing) index	`3`
`h`	Integer	Thumbnail height (in pixels, optional)	`300`
`w`	Integer	Thumbnail width (in pixels, optional)	`400`

We suggest you pass only one of the parameters w and h - if you pass both and their values are not appropriately set, the drawing may appear stretched along the horizontal or vertical direction (example: accurate, distorted).

13. Get a patent's data

Route: /patents/:pn

Path parameters

Parameter	Value	Meaning	Example
`pn`	String	Patent Number	`US7654321B2`

14. Get a patent's field (title, abstract, claims, etc.)

Route: /patents/:pn/:field

Path parameters

Parameter	Value	Meaning	Example
`pn`	String	Patent Number	`US7654321B2`
`field`	String	Patent's field	`title`, `abstract`, `claims`, `description`, `citations`

NOTES

The /claims route can also take a suffix path parameter /n that can be used to fetch a particular claim. For example, the first claim can be retrieved with /claims/1.
The /claims route can also take a suffix path parameter /independent to get only independent claims.
The /abstract and /description routes can take a suffix path parameter /concepts that will return the entities identified by an ML model within these text fields.
The /citation route takes suffix path parameters /backward and /forward to return only one cited or citing patents.

15. Get a patent's CPCs

Route: /patents/:pn/classification/cpcs

Path parameters

Parameter	Value	Meaning	Example
`pn`	String	Patent Number	`US7654321B2`

16. Get a patent's vector

Route: /patents/:pn/vectors/:field

Path parameters

Parameter	Value	Meaning	Example
`pn`	String	Patent Number	`US7654321B2`
`field`	String	Field vectorized	`cpcs` or `abstract`

17. Get a word (concept) vector

Route: /concepts/:concept/vector

Path parameters

Parameter	Value	Meaning	Example
`concept`	String	Given word	`vehicle` or `mobile phone`

18. Get contextually similar words to a given word

Route: /concepts/:concept/similar

Path parameters

Parameter	Value	Meaning	Example
`concept`	String	Given word	`vehicle` or `mobile phone`

19. Suggest CPCs for a text excerpt

Route: /suggest/cpcs

Query string parameters

Parameter	Value	Meaning	Example
`text`	String	Text Excerpt	`fire fighting drones`

20. Suggest Group Art Units for a text excerpt

Route: /predict/gaus

Query string parameters

Parameter	Value	Meaning	Example
`text`	String	Text Excerpt	`fire fighting drones`

21. Extract technical concepts from a text excerpt

Route: /extract/concepts

Query string parameters

Parameter	Value	Meaning	Example
`text`	String	Text Excerpt	`fire fighting drones`

22. Get definition of a CPC class

Route: /definitions/cpcs

Query string parameters

Parameter	Value	Meaning	Example
`cpc`	String	A CPC code	`H04W52/02`

23. Get API documentation

Route: /docs

Response type: HTML string

Parameters: None required

Files

README-API.md

Latest commit

History

README-API.md

File metadata and controls

PQAI: API Usage Guide

Introduction

Getting started

How to use the API?

How to formulate requests?

How to send requests?

How to use access token?

How to process responses?

How to make requests programmatically?

Python

Javascript

Browser

Routes

1. Retrieve prior-art documents with text query

2. Retrieve prior-art combinations with text query

3. Retrieve prior-art for a patent (documents published before the filing date)

4. Retrieve similar documents to a patent

5. Retrieve snippet for a query-document pair

6. Retrieve element-wise mapping for a query-document pair

7. Retrieve a sample from a dataset

8. Retrieve a document from PQAI database

9. Get a patent drawing

10. Get list of drawings for a patent (to tell how many drawings are there)

11. Get list of thumbnails available for a patent

12. Get a thumbnail of a patent's drawing

13. Get a patent's data

14. Get a patent's field (title, abstract, claims, etc.)

15. Get a patent's CPCs

16. Get a patent's vector

17. Get a word (concept) vector

18. Get contextually similar words to a given word

19. Suggest CPCs for a text excerpt

20. Suggest Group Art Units for a text excerpt

21. Extract technical concepts from a text excerpt

22. Get definition of a CPC class

23. Get API documentation