API Design Changes and API Keys
The improved version of the API requires that the user register their software application before querying the API. Once registered, you will be provided an API key. You will need this API key to query the API.
Each application is allowed to make 45 requests/minute. If your application exceeds this limit, you will receive a “429 Too many Requests” response to your API query. See Swagger Documentation for details.
Obtaining the API key
- Email the PatentsView team with the following information:
- Requestor Name
- Requestor Contact Email address
- Application Name
- Short description of the application
- You will receive your API key via email.
Using the API Key
- Each request to the API should include a X-Api-Key header.
- The value of the X-Api-Key header should be the API key.
- The API keys do not expire.
Note on workflow:
If users previously used a browser to run API queries, due to the API key enforcement users will not be able use the same workflow. Alternatively either a standalone applications (such as Postman) or browser extension (such as RESTED in Firefox/Chrome) can be used to send one-off queries.
API Design Changes
While the API query language remains unchanged in most cases, there are some differences:
Linked Fields: In case of data field that link two different entities ("foreign keys" in RDMBS vernacular), new API will carry the API lookup URL for the linked entity. For example, when querying the API for cpc_group A01B , the response will include a link for the cpc_subsection A01 :
In addition to the regular q parameter, applications can now perform "ID lookups" for each entity by specifically querying single ID values. See Swagger Documentation for details.
Classification Endpoints (CPC, USPC and NBER) will return lookup data exclusively. That is, when looking up any of the above classifications, only id, title and, in some cases, aggregate statistics will be returned. Fields to fetch related patent, assignee, inventor, etc. will not be supported.
API Query Language Changes
- page and per_page option parameters have been replaced by size and offset parameters. The default values are also changed.
- Owing to de-normalized and split API design, sub-entity information is not available directly via each endpoint. As a consequence, "matched_subentity" option parameters are not valid.
See the API v0.1 Query Language for full documentation.
Please refer to the 200 "Response" section for each endpoint for full list of fields available. All the available fields are "queryable."
The current API endpoint and field counterparts (citations and classification endpoints and fields) will continue to be available until such a time when the new API is considered stable. These are expected to be turned off early in 2022. Please note that for each data element available in the current API,
- We plan to implement endpoints in new API iteratively.
- There will always be a period of overlap when both the current and new API will carry each data element.