Query Language

To access prior or specific versions of the api, insert /vN after api in the URL. For example,

GET /api/v1/patents/query?q{,f,o,s}

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 (see “Field List” for a list of fields and their value data types). For example, this query string will return the patent with the patent number of 7861317:

q={"patent_number":"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 January 4, 2007:

q={"_and":[{"inventor_last_name":"Whitney"},{"patent_date":"2007-01-04"}]}

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:

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"} .

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:

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:

q={"inventor_last_name":["Whitney","Hopper"]}

Note that this is functionally equivalent to: q={"_or":[{"inventor_last_name":"Whitney"},{"inventor_last_name":"Hopper"}]}

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:

q={"_and":[{"_gte":{"patent_date":"2007-01-04"}},{"_lte":{"patent_date":"2007-12-31"}}]}

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

q={"_and":[{"inventor_last_name":["Whitney","Hopper"]},{"_not":{"patent_type":"design"}},{"_gte":{"patent_date":"2007-01-04"}},{"_lte":{"patent_date":"2007-12-31"}}]}

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

q={"_or":[{"inventor_last_name":["Whitney","Hopper"]},{"_text_any":{"patent_title":"COBOL cotton gin"}}]}

Patents with an inventor with the last name of “Whitney” and with “cotton gin” in the title, or with an inventor with the last name of “Hopper” and with “COBOL” in the title:

q={"_or":[{"_and":[{"inventor_last_name":"Whitney"},{"_text_phrase":{"patent_title":"cotton gin"}}]},{"_and":[{"inventor_last_name":"Hopper"},{"_text_all":{"patent_title":"COBOL"}}]}]}

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. See “Field List” for the fields available for the results. 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"]

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 may 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 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}

Matched Subentities Only

The matched_subentities_only option is provided to indicate whether only those subentities that match their subentity-specific criteria should be included in the results. By default, only those subentities that match their respective query criteria will be included for each parent entity.

Consider this example. Assume the database only has the following content:

Patents:

PATENT_NUMBER NUMBER PATENT_DATE
PAT1 7861317 1/21/2007

Inventors:

INVENTOR_IDPATENT_NUMBERNAME_FIRSTNAME_LAST
INV1pat1GraceHopper
INV2pat1EliWhitney
INV3pat1WillisCarrier

This query:

q={"_and":[{"_gte":{"patent_date":"2007-01-04"}},{"inventor_last_name":"Whitney"}]}&f=["patent_number","patent_date","inventor_last_name"]

Produces results that include only patents that have a grant date on or after January 4, 2007 and an inventor with the last name "Whitney":

{"patents":[{"patent_number":"pat1","patent_date":"2007-01-27","inventors":[{"inventor_last_name":"Whitney"}]}],"count":1,"total_patent_count":1}

However, if the query includes {"matched_subentities_only": false}, the results will include all patents granted on or after January 4, 2007 whether the inventor's last name is "Whitney" or not:

q={"_and":[{"_gte":{"patent_date":"2007-01-04"}},{"inventor_last_name":"Whitney"}]}&f=["patent_number","patent_date","inventor_last_name"]&o={"matched_subentities_only":false}

the results would include subentity (i.e. inventor) data:

{"patents":[{"patent_number":"pat1","patent_date":"2007-01-27","inventors":[{"inventor_last_name":"Hopper"},{"inventor_last_name":"Whitney"},{"inventor_last_name":"Carrier"}]}],"count":1,"total_patent_count":1}

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 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:

q={"_and":[{"_gte":{"patent_date":"2007-01-04"}},{"inventor_last_name":"Whitney"}]}&f=["patent_number","patent_date","inventor_last_name","assignee_last_name"]

In addition to the matching patents, he result will include the total number of patents matching the query.

{"patents":[{"patent_number":"pat1","patent_date":"2007-02-20","inventors":[{"inventor_last_name":"Whitney"}],"assignees":[{"assignee_last_name":null}]},...], "count":25,"total_patent_count":314}

If we set the include_subentity_total_counts to "true":

q={"_and":[{"_gte":{"patent_date":"2007-01-04"}},{"inventor_last_name":"Whitney"}]}&f=["patent_number","patent_date","inventor_last_name","assignee_last_name"]&o={"include_subentity_total_counts":"true"}

then the output will also include the total numbers of inventors and assignees associated to matching patents.

{"patents":[{"patent_number":"pat1","patent_date":"2007-02-20","inventors":[{"inventor_last_name":"Whitney"}],"assignees":[{"assignee_last_name":null}]},...], "count":25,"total_patent_count":314,"total_inventor_count":696,"total_assignee_count":102}

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").

For example:

  • 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.

Results Format

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.