Data API

The Data API is the patent search engine behind Patalyze, exposed as a plain HTTP service. It runs the same boolean and semantic queries over the same normalized global corpus as the search box in the app, so filings from any patent office come back in one consistent shape.

The API is read-only and exposes four endpoints: search and fetch patents, as well as search and fetch CPC/IPC classifications. This page gets you authenticated and through a first search; the endpoints below documents every field, operator, and response shape in full.

Authentication#

Every request authenticates with a bearer token. Create the token in the Patalyze app under Settings → API key. Each organization has a single key, which you can reveal or rotate from that page at any time.

Send it in the Authorization header on every request:

Authorization: Bearer pat_...

Make your first request#

A search is a POST to /patents with a JSON body. The body's filters array describes what to match; optional fields like limit control paging. The example below finds patents whose text contains the phrase solid state electrolyte and prints the total match count.

{
  "filters": [
    { "field": "Text", "operator": "contains", "value": "solid state electrolyte" }
  ],
  "limit": 5
}

const res = await fetch("https://data.patalyze.com/patents", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PATALYZE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    filters: [
      { field: "Text", operator: "contains", value: "solid state electrolyte" },
    ],
    limit: 5,
  }),
});

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

The response is a page of matching patents alongside a total count and the paging window you asked for. To pull the complete record for a single patent, use the fetch endpoint: GET /patents/{publication_number}.

Filter and search syntax#

Every query is a list of filters, and each filter pairs a field (such as Text, Claims or Territory) with an operator and a value. There are two ways to match, and you can mix them in one request.

Boolean search#

Boolean filters match exact terms. Operators like contains, is, and after are precise and predictable, which makes them the right tool for hard constraints: a jurisdiction, a date range, an assignee, a classification code.

{ "field": "Text", "operator": "contains", "value": "solid state electrolyte" }

Semantic search#

The similar to operator on Text or Claims ranks results by meaning rather than exact wording. Pass a short description and the corpus comes back ordered by conceptual closeness, so you catch relevant patents that use different terminology from your query.

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

In practice you combine the two: a similar to filter drives the ranking while boolean filters narrow it to the territories, dates, and statuses you care about.

That is the whole model. For the full set of fields and operators, how filters combine with And/Or, family de-duplication, sorting, and the exact response shape, see Search patents in the Endpoints reference below.

Endpoints#

The Data API has four endpoints, all under the base domain https://data.patalyze.com. Patents and classifications each get a search endpoint (POST a JSON query) and a fetch endpoint (GET by id).

• POST /patents: Search patents by boolean filters and semantic similarity.
• GET /patents/{publication_number}: Fetch one patent's full stored record.
• POST /classifications: Search the CPC/IPC scheme by symbol, text, or meaning.
• GET /classifications/{symbol}: Fetch one classification with its ancestor hierarchy.

Search patents#

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

{
  "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": "application",
  "limit": 20
}

Example code#

const res = await fetch("https://data.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: "application",
    limit: 20,
  }),
});

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

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",
      "abstract": "A solid-state electrolyte for lithium-metal cells that suppresses dendrite growth.",
      "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#

Filter object#

Filter fields and operators#

Text and claim searches take a trailing * wildcard: electrolyte* also matches electrolytes. Classification codes already match by prefix, so they need no wildcard.

Combining filters#

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

• And makes a positive filter required: every result must match it.
• Or makes a positive filter optional: a result that matches any Or filter is included.
• A negative operator (such as does not contain or is not) always excludes its matches, regardless of combination.

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; the rest narrow the candidate set. Mix it freely with the boolean filters above. A request carries at most four similar to filters.

Attachments#

A similar to value does not have to be text. On Text and Claims the array may also carry attachment objects, so you can rank the corpus against a datasheet, a product photo, or a recorded demo instead of describing it in words. Strings and attachments in the same filter are embedded and averaged into one query vector, which lets you steer a document with a sentence of context.

{
  "field": "Claims",
  "operator": "similar to",
  "value": [
    "solid-state electrolyte with a lithium-metal anode",
    {
      "kind": "file",
      "type": "application/pdf",
      "name": "cell-datasheet.pdf",
      "data": "JVBERi0xLjQKJeLjz9MKMy..."
    }
  ]
}

Aggregations#

Aggregations count the matched patents by a facet, so one request can return both a page of results and the shape of the whole match set. Ask for up to five facets, each with an optional limit. The counts cover every match, not just the page you asked for, so set the request limit low when the facets are all you want.

{
  "filters": [
    { "field": "Classifications", "operator": "contain", "value": "H01M10/0562" }
  ],
  "aggregations": [
    { "field": "priority_year" },
    { "field": "assignee", "limit": 10 }
  ],
  "limit": 1
}

The response gains an aggregations object keyed by facet, each holding an array of { value, count } buckets. It is omitted entirely when you ask for no facets.

{
  "results": [ ... ],
  "total": 1542,
  "offset": 0,
  "limit": 1,
  "aggregations": {
    "priority_year": [
      { "value": "2021", "count": 214 },
      { "value": "2022", "count": 389 },
      { "value": "2023", "count": 471 }
    ],
    "assignee": [
      { "value": "SolidPower Inc.", "count": 96 },
      { "value": "Toyota Motor Corporation", "count": 74 }
    ]
  }
}

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.

Example code#

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

Example response#

The example below is abridged. A live response also carries the claims and the other fields described in the tables that follow. 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" }
  ]
}

Response fields#

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. One mode picks how the query is matched: by exact symbol, by text, or by meaning.

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

Example code#

const res = await fetch("https://data.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 the full record for a single classification, such as H01M10, including its ancestor hierarchy up to the top-level section.

Example code#

const res = await fetch(
  "https://data.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 record, with a parents array listing its ancestors from the top-level section down to the immediate parent. An unknown symbol returns 404 Not Found.

{
  "symbol": "H01M10",
  "title": "Secondary cells; Manufacture thereof",
  "depth": 1,
  "parent": "H01M",
  "parents": [
    { "symbol": "H", "title": "Electricity", "depth": 4 },
    { "symbol": "H01", "title": "Basic electric elements", "depth": 3 },
    { "symbol": "H01M", "title": "Processes or means for the direct conversion of chemical energy into electrical energy", "depth": 2 }
  ],
  "notes": "",
  "statement": "",
  "glossary": "",
  "synonyms": "",
  "definition": null,
  "images": []
}

Response fields#

Pricing#

Every request (search or fetch) draws from your organization's data usage. Each request costs 0,075€, whatever it returns.

Rate limits#

Requests are also capped at 100 per minute per organization. We reserve the right to block requests to protect our services for other users.

Errors#

A failed request comes back as JSON with a short error code and a human-readable message:

{ "error": "forbidden", "message": "No remaining AI & Data usage" }

The status codes you may see:

• 400: a filter is invalid, for example an operator the field does not accept or a malformed date. The message says which.
• 401: the bearer token is missing or invalid.
• 403: your organization is out of AI & Data usage.
• 404: no patent or classification exists for that id (the fetch endpoints).
• 422: the request body could not be parsed, for example an unknown filter field or a value of the wrong type.
• 409: the request conflicts with the current state of the resource.
• 429: more than 100 requests in a minute. Slow down and retry.
• 500: an unexpected failure on our side.
• 503: the search or embedding backend is unavailable. The request was well formed, so retry it after a short backoff.