Legacy API Query Language
Query String Format
The query string is always a single JSON object: {}, with properties and contained objects that determine the criteria for the query.
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/. Clicking on the icons below display the JSON in JSON Editor Online.
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
Single Criterion
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).
For example, this query string will return the patent with the patent number of 7861317:
https://api.patentsview.org/patents/query?q={"patent_id":"7861317"}
Joining Criteria
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 “]”). The following has multiple criteria, and will return patents that have “Whitney” as an inventor and a grant date of October 6, 1981:
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. For example, this query string will return all patents that have a grant date on or after January 4, 2007:
https://api.patentsview.org/patents/query?q={"_gte":{"patent_date":"2007-01-04"}}
Note that q={"_eq":{"patent_date":"2007-01-04"}} is functionally equivalent to q={"patent_date":"2007-01-04"} .
Note that q={"_eq":{"citation_date":"2007-01-04"}} is functionally equivalent to q={"citation_date":"2007-01-04"}.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. For example, this query string will return all patents that are not design patents:
https://api.patentsview.org/patents/query?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. For example, this query will return all patents that have “Whitney” or “Hopper” as an inventor:
https://api.patentsview.org/patents/query?q={"inventor_last_name":["Whitney","Hopper"]}
Note that this is functionally equivalent to: q={"_or":[{"inventor_last_name":"Whitney"},{"inventor_last_name":"Hopper"}]}
Note that this is functionally equivalent to: q={"_or":[{"citation_category":"cited_by_applicant"},{"citation_category":"cited_by_examiner"}]}Complex Combinations
These elements, criteria, arrays, and operators can be combined to define robust queries. Here are a few examples.
Patents with a grant date in 2007:
Patents with an inventor with the last name of “Whitney” or “Hopper” and not a design patent and with a grant date in 2007:
Patents with an inventor with the last name of “Whitney” or “Hopper” or with a title that contains “cotton” or “gin” or “COBOL”:
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:
Complex combinations in the ElasticSearch API utilize the same query language as used for the MySQL API.
Formats
Dates are expected to be in ISO 8601 date format: YYYY-MM-DD.
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. The following example would return the patent numbers, inventor names, and date patent was granted that meet the query criteria:
f=["patent_number","inventor_last_name","patent_date"]
For the default field list for each endpoint, please navigate to the specific endpoint's page from the endpoints' homepage.
Options Parameter
The options parameter is a JSON formatted object of options to modify the query or results. Available options are:
- page and per_page — customize how many patents to return per page and which page.
- matched_subentities_only — whether a query should return all related subentities or just those that match query criteria. Defaults to "false".
- include_subentity_total_counts — whether the query results should include the total counts of unique subentities. Defaults to "false".
Pagination
By default the MySQL API will return the first 25 results. The page and per_page options can be used to customize the set of results that is returned.
- The page option is 1-based and omitting the page option will return the first page of results.
- The per_page option specifies the number of results per page; it defaults to 25 and has a maximum of 10,000.
- An example for specifying pagination in the options parameter is: o={"page":2,"per_page":50}
- The API can return a maximum of 100,000 results per query.
Matched Subentities Only
The matched_subentities_only option is provided to indicate whether only those subentities that match all query criteria should be included in the results. By default, this option is set to false and any query returns all subentity data associated with the primary entity for this query regardless of the query parameters.
Consider this example. Assume the database only has the following content:
Patents:
| PATENT_ID | NUMBER | PATENT_DATE |
|---|---|---|
| PAT1 | 7202770 | 4/10/2007 |
Inventors:
| INVENTOR_ID | PATENT_NUMBER | NAME_FIRST | NAME_LAST |
|---|---|---|---|
| INV1 | pat1 | Stephen J. | Whitney |
| INV2 | pat1 | Scott | Davidson |
| INV3 | pat1 | David | Perry |
| INV4 | pat1 | Edwin James | Harris |
This query:
produces results that include all patents that have a grant date on or after April 10, 2007 and all associated inventor last names, be it "Whitney" or not:
{"patents":[{"patent_number":"7202770","patent_date":"2007-04-10","inventors":[{"inventor_first_name":"Stephen J.","inventor_last_name":"Whitney"},{"inventor_first_name":"Scott","inventor_last_name":"Davidson"},{"inventor_first_name":"David","inventor_last_name":"Perry"},{"inventor_first_name":"Edwin James","inventor_last_name":"Harris"}]}...
However, if the query includes {"matched_subentities_only": true}, the results will include all patents granted on or after April 10, 2007 and associated inventor data only if the inventor's last name is "Whitney":
the results would include subentity (i.e. inventor) data:
{"patents":[{"patent_number":"7202770","patent_date":"2007-04-10","inventors":[{"inventor_last_name":"Whitney"}]}...
Include Subentity Total Counts
The include_subentity_total_counts option is provided to indicate whether the query results should include the total counts of unique subentities. By default, these counts are not returned. If this option is set to true, then there will be a count of unique subentities for those subentities that have at least one field included in the result fields. These will be named, e.g., total_inventor_count, total_assignee_count, etc.
For example, suppose the following patent query is submitted:
In addition to the matching patents, the result will only include the total number of patents matching the query.
{"patents":[{"patent_number":"7202770","patent_date":"2007-04-10","inventors":[{"inventor_last_name":"Whitney"},{"inventor_last_name":"Davidson"},{"inventor_last_name":"Perry"},{"inventor_last_name":"Harris"}],"assignees":[{"assignee_organization":"Littlelfuse, Inc."}]},..., "count":25,"total_patent_count":324}
If we set the include_subentity_total_counts to "true":
then the output will also include the total numbers of inventors and assignees associated to matching patents.
{"patents":[{"patent_number":"7202770","patent_date":"2007-04-10","inventors":[{"inventor_last_name":"Whitney"},{"inventor_last_name":"Davidson"},{"inventor_last_name":"Perry"},{"inventor_last_name":"Harris"}],"assignees":[{"assignee_organization":"Littlelfuse, Inc."}]},..., "count":25,"total_patent_count":324,"total_inventor_count":111,"total_assignee_count":101}
Sort Parameter
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 patent number.
Each object in the array should be a pair, with the pair's key being one of the patent fields, and the value is either “asc” or “desc”, to indicate ascending or descending sort, respectively.
All sort fields should be also necessarily included into the field list parameter ("f"). For example, if a user wants to sort all assignee organizations from assignee entity by their associated inventors' last names from inventor subentity, they should make sure that "inventor_last_name" is present in both the field list ("f") and the sort parameter ("s").
Examples:
- s=[{"patent_num_claims":"desc"}
Primary sort is by patent_num_claims in ascending order, so that patents with the most claims will be first, and those with least claims will be last. - s=[{"patent_date":"desc"},{"patent_number":"asc"}]
Primary sort is by patent_date in descending order, secondarily by patent_number 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_number":"asc"}]
Primary sort is by citation_date in descending order, secondarily by patent_number in ascending order.
Results Format
JSON
Syntax
{“error”:error, “count”:count, “total_hits”:total_hits, entity_name:[{[key_value_pair[,…]}]}
Error
boolean
Entity_name
{patent_citations | application_citations | cpc_subsections | cpc_groups | cpc_subgroups | uspc_mainclasses | uspc_subclasses | nber_categories | nber_subcategories}
Key_value_pair
“field_name”:value
Where field_name is from the fields available in the endpoint
Example
{'error': False, 'count': 3, 'total_hits': 3, 'patent_citations': [{'patent_number': '10876664', 'cited_patent_number': '8529273', 'citation_date': '2013-09-01'}, {'patent_number': '10876664', 'cited_patent_number': '5658159', 'citation_date': '1997-08-01'}, {'patent_number': '10876664', 'cited_patent_number': '696529', 'citation_date': '1902-04-01'}]}
See the endpoints page for specific information on the endpoint of interest.
JSON
Syntax
{"patents":[patent[,...]], "count":count, "total_patent_count":total_patent_count}
patent
{[key_value_pair[,...]][,related_group[,...]]}
related_group
"entity_name":[related_entity[,...]]
related_entity
{key_value_pair[,...]}
entity_name
{ inventors | assignees | applications | application_citations | cited_patents | citedby_patents | ipcs | uspc_mainclasses | cpc_subsections }
key_value_pair
"field_name":value
Where field_name is from the table of fields below.
Example
{"patents":[{"patent_number":"pat1","date":"2007-01-27","inventors":[{"inventor_last_name":"Hopper"},{"inventor_last_name":"Whitney"},{"inventor_last_name":"Carrier"}]}],"count":1,"total_patent_count":1}
XML
Syntax
Example
<root>
<patents>
<patent>
<patent_number>pat1</patent_number>
<inventors>
<inventor>
<inventor_last_name>Hopper</inventor_last_name>
</inventor>
<inventor>
<inventor_last_name>Carrier</inventor_last_name>
</inventor>
</inventors>
</patent>
</patents>
<count>1</count>
<total_patent_count>1</total_patent_count>
</root>
Response Status codes
When the query parameters are all valid, the API will return results formatted per “Results Format” with an HTTP status code of 200. The results will be in the body of the response.
An HTTP status code of 400 will be returned when the query parameters are not valid, typically either because they are not in valid JSON format, or a specified field or value is not valid. The “status reason” in the header will contain the error message.
An HTTP status code of 500 will be returned when there is an internal error with the processing of the query. The “status reason” in the header will contain the error message.