PatentSearch API Reference

Introduction

The PatentsView PatentSearch API is intended to inspire the exploration and enhanced understanding of US intellectual property (IP) and innovation systems. The database driving the API is regularly updated and integrates the best available tools for inventor disambiguation and data quality control. We hope researchers and developers alike will explore the API to discover people and companies and to visualize trends and patterns across the US innovation landscape.

tip

Throughout this document, whenever the {} syntax is used, users are expected to replace it with valid values.

Authentication

API Keys

The PatentSearch API uses API Keys to authenticate requests but there are no specific authorization enforced. i.e. if you have an API Key you can access all publicly available endpoints.

• All API requests must include the header X-Api-Key: {your_key}

  info

  Currently, the API Keys do not expire but this may change in the future. If this changes, we will update the documentation here as well as communicate changes with the users via the patentsview website and the mailing list.

  tip

  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.

Usage Limits

Each API Key is allowed 45 requests/minute. If you exceed this limit, your API requests will fail. See HTTP Response Code for more details

Request an API Key

You can obtain an API key by submitting a request via the PatentsView Help Center. Each user is allowed only one API Key. If you lose your API key, please request a new one with same email address and name.

warning

Please do not request/use multiple keys at the same time. If you do, your access may be revoked.

API Request

Structure of Request

An API request is made of 4 components:

1. API Key (Discussed above)
2. The requested endpoint (See Endpoints Dictionary)
3. Request method
4. Request parameters

Request Method

All PatentSearch API endpoints support two methods: GET and POST. Both GET and POST use/require the same set of parameters.

info

The PatentsView PatentSearch API endpoints don't allow users to submit data to our databases. The POST method is another mechanism for posting query parameters, not for adding new records.

Request Parameters

There are 4 parameters that can be provided in a request. Each of the components is fully specified in the API Query Language section. Briefly:

1. Query String(q) - used to filter data
2. Field list (f) - used to specify fields to return
3. Sorting (s) - used to specify ordering
4. Options (o) - used to specify additional options and pagination

Defaults

Each API endpoint is configured with appropriate defaults for the f, s and o parameters. When a user does not include one or more these parameters, the defaults will be used. The q parameter is without defaults and is mandatory.

• By default, the API will return 100 records. This can be increased up to 1,000. See Options (o) section.
• The default for the s parameter the "ID" field of that particular endpoint in ascending order. E.g. patent_id is the default sort field for /patent endpoint. The full list of default sort fields can be found in the Endpoints Dictionary below.

API Response

HTTP Response Codes

Response Code	Description	Potential Resolution
200	Request Successfully Completed
400	Request Invalid	Review X-Status-Reason and X-Status-Reason-Code response headers for more details
403	Forbidden	Verify that your API key is correctly entered and provided in your request headers with the key X-Api-Key
404	Resource not found	Verify the endpoint URL is correct. If using "GET" resource locator, verify the supplied ID is valid
429	Too many requests	Your application has exceeded the usage limits. Use Retry-After response header to identify wait duration before making the next request
500	Server Error	This is typically an error on our servers. Check the Service Status page and/or submit a support request

Response Structure

Every API response will have the following structure:

• error: a boolean flag indicating if the request succeeded or failed
• count: total number of records returned in this response
• total_hits: total number of records that matched the current query
• ...: The final and the main data component on the response will be based on the endpoint used. (See individual Endpoints for their respective response keys)

{
  "error": "boolean",
  "count": "integer",
  "total_hits": "integer",
  ...
}

API Query Language

Query String (q)

Query String Format

The query string is always a single JSON object: {}, with properties and contained objects that determine the criteria for the query.

tip

Note: To aid in understanding the structure of the queries below and while creating your own, it is helpful to use JSON validators and visual parsers, like http://www.jsoneditoronline.org/ and http://jsonlint.com/.

Syntax

q={criterion}
criterion
    pair
    "_eq" : {simple_pair}
    "_neq" : {simple_pair}
    "_gt" : {simple_pair}
    "_gte" : {simple_pair}
    "_lt" : {simple_pair}
    "_lte" : {simple_pair}
    "_begins" : {simple_pair}
    "_contains" : {simple_pair}
    "_text_all" : {simple_pair}
    "_text_any" : {simple_pair}
    "_text_phrase" : {simple_pair}
    "_not" : {criterion}
    "_and" : [{criterion}, ...]
    "_or" : [{criterion}, ...]
pair
    simple_pair
    "field" : [value, ...]
simple_pair
    "field" : value

tip

When working with text data fields, wherever possible, we recommend using _text* operators over the _contains and _begins operator. The text operators treat these fields as full text data and hence are more performant. The "full text" fields are identified in the API Endpoint specification with the value "text" for the data type.

Single Criterion (Equals operator)

The basic criterion, which checks for equality, has the format: {<field>:<value>}, where <field> is the name of a database field and <value> is the value the field will be compared to for equality (Each API Endpoint section contains a list of the data fields that can be selected for inclusion in output datasets)

info

For example, this query string will return the patent with the patent number of 7861317:

https://search.patentsview.org/api/v1/patent/?q={"patent_id":"7861317"}

Comparison Operators

Comparison operators can be used to compare a field to a value using comparators other than equality. The available comparison operators are:

• Integer, float, date, and string:
  • _eq — equal to
  • _neq — not equal to
  • _gt — greater than
  • _gte — greater than or equal to
  • _lt — less than
  • _lte — less than or equal to
• String:
  • _begins — the string begins with the value string
  • _contains — the string contains the value string
• Full text:
  • _text_all — the text contains all the words in the value string
  • _text_any — the text contains any of the words in the value string
  • _text_phrase — the text contains the exact phrase of the value string

To specify a comparison operator for a criterion, nest the element containing the criterion inside an element that uses the comparison operator.

info

For example, this query string will return all patents that have a grant date on or after January 9, 2007:

https://search.patentsview.org/api/v1/patent/?q={"_gte":{"patent_date":"2007-01-09"}}

tip

The query string q={"_eq":{"patent_date":"2007-01-09"}} is functionally equivalent to q={"patent_date":"2007-01-09"}

Negation

Negation does the opposite of the specified comparison. To specify the negation operator for a criterion, nest the element containing the criterion inside an element that uses the negation operator: _not.

info

For example, this query string will return all patents that are not design patents:

https://search.patentsview.org/api/v1/patent/?q={"_not":{"patent_type":"design"}}

Value Arrays

If the value of a criterion is an array, then the query will accept a match of any one of the array values.

info

For example, this query will return all patents that have "Whitney" or "Hopper" as an inventor:

https://search.patentsview.org/api/v1/patent/?q={"inventors.inventor_name_last":["Whitney","Hopper"]}

Join (Conjunction) Operators

Multiple criteria can be added to a query using a join operator (_and, _or) and putting the criteria in an array using square brackets ("[" and "]").

info

The following has multiple criteria, and will return patents that have "Whitney" as an inventor and a grant date of October 6, 1981:

https://search.patentsview.org/api/v1/patent/?q={"_and":[{"inventors.inventor_name_last":"Whitney"},{"patent_date":"1981-10-06"}]}

Complex Combinations

These elements, criteria, arrays, and operators can be combined to define robust queries. A few examples:

info

Patents with a grant date in 2007:

https://search.patentsview.org/api/v1/patent/?q={"_and":[{"_gte":{"patent_date":"2007-01-01"}},{"_lte":{"patent_date":"2007-12-31"}}]}

info

Patents with an inventor with the last name of "Whitney" or "Hopper" and not a design patent and with a grant date in 2007:

https://search.patentsview.org/api/v1/patent/?q={"_and":[{"inventors.inventor_name_last":["Whitney","Hopper"]},{"_not":{"patent_type":"design"}},{"_gte":{"patent_date":"2007-01-01"}},{"_lte":{"patent_date":"2007-12-31"}}]}

info

Patents with an inventor with the last name of "Whitney" or "Hopper" or with a title that contains "cotton" or "gin" or "COBOL":

https://search.patentsview.org/api/v1/patent/?q={"_or":[{"inventors.inventor_name_last":["Whitney","Hopper"]},{"_text_any":{"patent_title":"COBOL cotton gin"}}]}

info

Patents with an inventor with the last name of "Whitener" and with "cotton gin" in the title, or with an inventor with the last name of "Heath" and with "COBOL" in the title:

https://search.patentsview.org/api/v1/patent/?q={"_or":[{"_and":[{"inventors.inventor_name_last":"Whitener"},{"_text_phrase":{"patent_title":"cotton gin"}}]},{"_and":[{"inventors.inventor_name_last":"Heath"},{"_text_all":{"patent_title":"COBOL"}}]}]}

Formats

Dates are expected to be in ISO 8601 date format: YYYY-MM-DD.
Nested fields follow the format <field>.<nested_field>

Field List (f)

Field List Format

The field list parameter is a JSON array of the names of the fields to be returned by the query. If not provided, the API will return a default set of fields. Each API Endpoint section contains a list of the data fields that can be selected for inclusion in output datasets.

info

The following example would return the patent numbers, inventor names, and date patent was granted that meet the query criteria:

f=["patent_id","inventors.inventor_name_last","patent_date"]

tip

Note that Nested fields have the format {entity}.{field_name}. In the endpoint specification below, these fields are shown in a containers within the parent endpoint.

Sorting (s)

Sort Parameter Format

The sort parameter is a JSON formatted array of objects that specifies the sort order for the returned results. If empty or not provided, the default sort order will be ascending by the endpoint's primary field or fields. These default sort fields are specified in the Endpoints Section below. Each object in the array should be a pair, with the pair's key being one of the endpoint fields, and the value is either asc or desc, to indicate ascending or descending sort, respectively.

info

Examples:

• s=[{"patent_num_times_cited_by_us_patents":"desc"}]: Primary sort is by patent_num_times_cited_by_us_patents in descending order, so that patents with the most citations by other US patents will be first, and those with the fewest citations by other US patents will be last.
• s=[{"patent_date":"desc"},{"patent_id":"asc"}]: Primary sort is by patent_date in descending order, secondarily by patent_id in ascending order.
• s=[{"citation_sequence":"desc"}]: Primary sort is by citation_sequence in ascending order, so that citations are returned in the ordered they were cited.
• s=[{"citation_date":"desc"},{"patent_id":"asc"}]: Primary sort is by citation_date in descending order, secondarily by patent_id in ascending order.

Options (o)

The options parameter is a JSON formatted object of options to modify the query results. All options keywords are optional. Available options are:

Search Options

• exclude_withdrawn: The exclude_withdrawn option is only used by the Patent endpoint and determines whether information for withdrawn patents will be excluded from the results. It defaults to true. If the query includes the condition {"withdrawn": true}, this option will be ignored. This option is ignored by all other endpoints.
• pad_patent_id: The pad_patent_id option is used in endpoints that include patent_id as a valid field. It determines whether the API will pad the patent_id field to a standard length of 8 characters by left-appending 0s to the numeric portion of the ID. It defaults to false. This transformation applies both to how patent_id is presented in the response as well as how it is interpreted by the query, sort order, and pagination options.

info

As an example, with pad_patent_id set to true, the patent_ids "7245826" and "PP3990" will be treated and displayed as "07245826" and "PP003990", respectively.
The padded form used when pad_patent_id is set to true provides a more natural and intuitive sorting and filtering behavior for patents that have different numbers of nonzero digits. For example, with pad_patent_id set to true, a range query or sort based on patent_id will treat patent "D0999999" as before/lower than patent "D1000000" instead of treating patent "D1000000" as before/lower than patent "D999999".
The un-padded form used when pad_patent_id is set to false or omitted matches the patent_id as displayed in other PatentsView data products such as the bulk data download tables.

Pagnation Options

• size: The size option specifies the number of results per page; it defaults to 100 and has a maximum of 1,000. Values greater than 1,000 will be treated as 1,000.
• after: The after option implements Cursor Pagination. If included, the value should be a valid value (or list of values) from the field(s) specified in the sort option. To get continuous pages of results, users will need to supply the value(s) from the last record in the previous query to the subsequent query. The number and order of values provided should match the number and order of fields used in the Sort parameter.

info

As an example, if the Sort parameter is s=[{"patent_id":"asc"}], the Option parameter for your first query might look like o={"size":100}. This would return the first 100 records sorted by patent id in ascending order.
The Option parameter for the second query might look like o={"size":100, "after":"11191202"} where "11191202" is the last patent_id value from the previous query. This would return the next 100 records.
If the Sort parameter were s=[{"patent_id":"asc"},{"claim_sequence":"desc"}], the second query would have an Option parameter that would look like 0={"size":100, "after":["12050006",2]}, where "12050006" is the patent_id from the last record of the previous query, and 2 is the claim_sequence value from the last record of the previous query. This would return the next 100 records; in this case, the next record would be the one where patent_id = "12050006" and claim_sequence = 1.

Swagger

Try out the API with our Swagger Page!