Endpoints

Every search you can run inside Patalyze is also a request you can send. The Global Patents REST API has four endpoints under the base URL https://search.patalyze.com. Authenticate every request as described in the API overview. Patents and classifications each have a search endpoint (POST with a JSON body) and a fetch endpoint (GET by id).

Search patents#

Runs boolean and semantic search over the patent corpus. Send a JSON body describing a list of filters, plus optional paging, sorting and family de-duplication.

POST/patents

{
  "filters": [
    { "field": "Claims", "operator": "similar to", "value": "lithium-ion battery" },
    { "field": "Territory", "operator": "is any of", "value": ["US", "EP"] },
    { "field": "Priority date", "operator": "after", "value": "2018-01-01" },
    { "field": "Status", "operator": "is", "value": "In-force" }
  ],
  "sort": [{ "field": "publication_date", "order": "desc" }],
  "deduplication": "family",
  "limit": 20
}

Example code#

const res = await fetch("https://search.patalyze.com/patents", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PATALYZE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    filters: [
      { field: "Claims", operator: "similar to", value: "lithium-ion battery" },
      { field: "Territory", operator: "is any of", value: ["US", "EP"] },
      { field: "Priority date", operator: "after", value: "2018-01-01" },
      { field: "Status", operator: "is", value: "In-force" },
    ],
    sort: [{ field: "publication_date", order: "desc" }],
    deduplication: "family",
    limit: 20,
  }),
});

const data = await res.json();
console.log(data.total);

import os import requests res = requests.post( "https://search.patalyze.com/patents", headers={"Authorization": f"Bearer {os.environ['PATALYZE_API_KEY']}"}, json={ "filters": [ {"field": "Claims", "operator": "similar to", "value": "lithium-ion battery"}, {"field": "Territory", "operator": "is any of", "value": ["US", "EP"]}, {"field": "Priority date", "operator": "after", "value": "2018-01-01"}, {"field": "Status", "operator": "is", "value": "In-force"}, ], "sort": [{"field": "publication_date", "order": "desc"}], "deduplication": "family", "limit": 20, }, ) data = res.json() print(data["total"])

use serde_json::json; #[tokio::main] async fn main() -> Result<(), Box<dyn std::error::Error>> { let api_key = std::env::var("PATALYZE_API_KEY")?; let res = reqwest::Client::new() .post("https://search.patalyze.com/patents") .bearer_auth(api_key) .json(&json!({ "filters": [ { "field": "Claims", "operator": "similar to", "value": "lithium-ion battery" }, { "field": "Territory", "operator": "is any of", "value": ["US", "EP"] }, { "field": "Priority date", "operator": "after", "value": "2018-01-01" } ], "sort": [{ "field": "publication_date", "order": "desc" }], "deduplication": "family", "limit": 20 })) .send() .await?; let data: serde_json::Value = res.json().await?; println!("{}", data["total"]); Ok(()) }

Example response#

Results come back as an array of patents with the total match count and the paging window you requested.

{
  "results": [
    {
      "publication_number": "US11735790B2",
      "country": "US",
      "kind": "B2",
      "publication_date": "2023-08-22",
      "status": "In-force",
      "title": "Solid-state electrolyte for lithium batteries",
      "assignees": ["SolidPower Inc."],
      "inventors": ["Jane Doe"],
      "cpc": ["H01M10/0562", "H01M10/052"],
      "earliest_priority_date": "2022-01-15",
      "family": [
        { "publication_number": "EP4123456A1", "country": "EP", "kind": "A1", "status": "Filed" }
      ]
    }
  ],
  "total": 1542,
  "offset": 0,
  "limit": 20
}

Body parameters#

filtersFilter[]required

The filters to apply. An empty array matches the whole corpus (subject to the territory default below).

limitnumber

Results per page, 1 to 100. Defaults to 10.

offsetnumber

Number of results to skip, 0 to 10000. Defaults to 0.

sort{ field, order }[]

Sort order, for example publication_date with desc. Omit to sort by relevance.

deduplicationstring

Set to family to return one representative result per patent family. Omit to return every publication.

Filter object#

combination"And" | "Or"

How this filter joins the others. Optional; defaults to And. See Combining filters below.

fieldstringrequired

One of Text, Claims, Territory, Classifications, Assignees, Inventors, Priority date, Status, Number or Kind code.

operatorstringrequired

The comparison to apply. Valid operators depend on the field, see below. Operator strings must match exactly.

valuestring | string[] | number[]

The value(s) to compare against. Single-value operators (is, after, before, contains, ...) take a bare string; multi-value operators (is any of, contains all of, ...) take an array. Use YYYY-MM-DD for dates; for between pass two dates [from, to].

Filter fields and operators#

Operator strings are matched exactly. Note the singular forms on the text-style fields.

Texttitle + abstract

contains, does not contain, contains any of, contains all of, does not contain any of, does not contain all of, similar to.

Claimsclaim text

contain, do not contain, contain any of, contain all of, do not contain any of, do not contain all of, similar to.

ClassificationsCPC/IPC codes

contain, do not contain, contain any of, contain all of, do not contain any of, do not contain all of. Codes match by prefix, so H01M10 matches its sub-groups.

Assigneesowner names

contain, do not contain, contain any of, do not contain any of.

Inventorsinventor names

contain, do not contain, contain any of, do not contain any of.

Territorycountry codes

is, is not, is any of, is not any of. Values are two-letter codes such as US or EP.

Priority dateYYYY-MM-DD

before, after, between. Compares the earliest priority date.

Statuslegal status

is, is not, is any of, is not any of. Accepts the groups In-force, Pending and Dead, which expand to their underlying statuses.

Numberpublication / application

is, is not, is any of, is not any of. Digit-only terms match application numbers; terms with letters match publication numbers.

Kind codeA1, B2, ...

is, is not, is any of, is not any of.

Combining filters#

Each filter's combination controls how it joins the others. It is optional and defaults to And, so you only need it to broaden a query with Or:

And makes a positive filter required: every result must match it.
Or makes a positive filter optional: it broadens the result set so a result matching any Or filter is included.
A negative operator (for example does not contain or is not) always excludes matches, regardless of combination.

Territory defaults to US and EP

If you do not include a Territory filter, results are limited to US and EP publications. Add a Territory filter to widen or change the jurisdictions.

Semantic search#

Use the similar to operator on Text or Claims to rank results by meaning rather than exact keywords. Pass a short description as the value:

{ "field": "Claims", "operator": "similar to", "value": "lithium-ion battery" }

The first similar to filter drives the ranking; other filters narrow the candidate set. You can combine it with the boolean filters above.

Response fields#

To fetch the complete stored record for a single patent, see Fetch patent.

Fetch patent#

Returns the complete stored record for one patent, including claims, description, legal events and family members. This is the full document behind the trimmed records returned by search.

GET/patents/US11735790B2

publication_number

Example code#

const res = await fetch(
  "https://search.patalyze.com/patents/US11735790B2",
  { headers: { Authorization: `Bearer ${process.env.PATALYZE_API_KEY}` } },
);
const patent = await res.json();
console.log(patent.title);

Example response#

The response is the patent's full stored record. An unknown publication number returns 404 Not Found.

{
  "publication_number": "US11735790B2",
  "country": "US",
  "kind": "B2",
  "status": "In-force",
  "publication_date": "2023-08-22",
  "title": "Solid-state electrolyte for lithium batteries",
  "abstract": "A solid-state electrolyte composition for lithium-ion cells ...",
  "assignees": ["SolidPower Inc."],
  "inventors": ["Jane Doe"],
  "cpc": ["H01M10/0562", "H01M10/052"],
  "earliest_priority_date": "2022-01-15",
  "family": [
    { "publication_number": "EP4123456A1", "country": "EP", "kind": "A1", "status": "Filed" }
  ]
  // plus claims, application_number, ipc, priorities,
  // citations, legal_events, grant_date and more
}

Response fields#

publication_numberstring

The publication number, for example US11735790B2.

countrystring

Two-letter publication country code.

kindstring

Kind code, for example B2.

statusstring

Current legal status.

publication_dateYYYY-MM-DD

Date the publication was issued.

titlestring

Patent title.

abstractstring

Abstract text.

assigneesstring[]

Current owners.

inventorsstring[]

Named inventors.

cpcstring[]

CPC classification symbols. ipc codes are included the same way.

earliest_priority_dateYYYY-MM-DD

Earliest priority date across the family.

claimsobject

Structured claim text.

familyobject[]

Family members, each with publication_number, country, kind and status.

The full stored record also carries application_number, application_date, grant_date, applicants, priorities, citations, language and legal_events.

Search classifications#

Searches the CPC/IPC scheme by exact symbol, by text, or by meaning.

POST/classifications

{
  "mode": "text",
  "query": "solid electrolyte",
  "limit": 10
}

Example code#

const res = await fetch("https://search.patalyze.com/classifications", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PATALYZE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ mode: "text", query: "solid electrolyte", limit: 10 }),
});

const data = await res.json();
console.log(data.total);

Example response#

The response mirrors patent search: a results array of classifications plus total, offset and limit.

{
  "results": [
    {
      "symbol": "H01M10/0562",
      "title": "Solid materials for use as electrolytes",
      "depth": 0,
      "score": 0.91
    }
  ],
  "total": 12,
  "offset": 0,
  "limit": 10
}

Body parameters#

Response fields#

Fetch classification#

Returns a single classification and its tree of child groups, for example H01M10.

GET/classifications/H01M10

symbol

Example code#

const res = await fetch(
  "https://search.patalyze.com/classifications/H01M10",
  { headers: { Authorization: `Bearer ${process.env.PATALYZE_API_KEY}` } },
);
const classification = await res.json();
console.log(classification);

Example response#

The response is the classification and its nested child groups. An unknown symbol returns 404 Not Found.

{
  "symbol": "H04L",
  "title": "Transmission of digital information",
  "depth": 2,
  "parent": "H04"
  // plus optional notes, statement, glossary, synonyms
  // and a nested tree of child groups
}

Response fields#

The response also nests the classification's child groups, each with the same fields.