Crate epo 

Async client for the EPO Open Patent Services v3.2 REST API.

Handles OAuth2 token caching, bibliographic / family / citation / search fetching, deeply nested JSON response parsing, and exponential backoff on 403/429. Also exposes a lightweight CQL syntax validator so callers can pre-flight queries before sending them.

Quick start

use epo::{EpoClient, EpoError};

let client = EpoClient::new(
    std::env::var("EPO_CONSUMER_KEY").unwrap(),
    std::env::var("EPO_CONSUMER_SECRET").unwrap(),
    None, // defaults to https://ops.epo.org/3.2
);

let biblio = client.fetch_biblio("EP1000000").await?;
println!("{}: {}", biblio.title, biblio.assignee.as_deref().unwrap_or(""));

CQL pre-flight

use epo::validate_cql;

// Date ranges must use `within`, not `>=`/`<=` — EPO rejects the latter.
let q = r#"pa=Apple AND pd within "20240101,20240107""#;
let v = validate_cql(q).expect("syntactically valid");
assert_eq!(v.fields[0], ("pa".into(), "Apple".into()));

Endpoints

• EpoClient::fetch_biblio — bibliographic data (title, abstract, applicants, classifications, dates).
• EpoClient::fetch_description — full-text description body, paragraph-level. Separate quota; may 404 even when biblio works.
• EpoClient::fetch_claims — full claim set, claim-level. Same separate quota as description.
• EpoClient::fetch_family — INPADOC family members.
• EpoClient::fetch_citations — backward citations from the biblio endpoint.
• EpoClient::fetch_citing — forward citations via CQL search.
• EpoClient::fetch_search — CQL search with pagination.

All four return typed EpoError variants on failure, with retry built in for 403/429. The token endpoint response is cached and refreshed automatically when it nears expiry.

Credentials

You need an EPO OPS consumer key + secret from https://developers.epo.org. The free tier limits weekly traffic by bytes; the client honours the documented 4 req/s pacing internally.

Structs

Citation

One backward or forward citation. Returned in Citations::cited from EpoClient::fetch_citations (with phase = "search" | "examination" | …) and in the result of EpoClient::fetch_citing (with phase = "citing").

Citations

Citation directions for one patent. Returned by EpoClient::fetch_citations.

Claim

One claim from a PatentClaims.

ClientConfig

Tunables for EpoClient. Use ClientConfig::default for sensible defaults that match EPO’s documented per-endpoint ceilings, or EpoClient::with_config to override individual fields.

CqlError

CQL validation errors. position is the 0-based char offset into the input where the problem was first detected.

DescriptionParagraph

One paragraph of a PatentDescription.

EndpointQuota

Per-endpoint slice of ThrottlingState.

EpoClient

FamilyMember

One member of an INPADOC patent family. Returned by EpoClient::fetch_family.

PatentBiblio

Bibliographic metadata for one patent. Returned by EpoClient::fetch_biblio.

PatentClaims

Full claim set for a published patent. Returned by EpoClient::fetch_claims.

PatentDescription

Full-text description for a published patent. Returned by EpoClient::fetch_description.

SearchResultPatent

One result row from EpoClient::fetch_search. Mirrors PatentBiblio but with the patent’s own publication number as the primary key.

SearchResults

Page of results from EpoClient::fetch_search.

ThrottlingState

Snapshot of the EPO throttling + quota state, parsed from the response headers of the most recent successful HTTP call. Returned by EpoClient::throttling_state.

ValidatedCql

Successful validation result. query is the trimmed input; field chips are an extracted list of (code, value) pairs the panel renders next to the CQL — driven off the same parse so the badge can’t drift from the chip list.

Enums

CqlErrorKind

EpoError

Errors returned by every EpoClient method.

ThrottlingColor

Per-endpoint quota color from x-throttling-control.

ThrottlingLoad

Overall server load reported in x-throttling-control.

Constants

FIELD_CODES

Recognised EPO CQL field codes. Source: EPO OPS docs (search field reference). Comparators (=, >=, <=, >, <, within) all attach to these prefixes — we accept any code in this set followed by one of the comparators. within is the EPO-recommended form for date ranges (pd within "20240101,20240107"); EPO returns a CLIENT.FuzzyDateRanges fault on pd>=… AND pd<=…, so the validator surfaces both forms.

Functions

parse_biblio

Extract bibliographic data from EPO JSON response.

parse_citations

Parse citations from EPO biblio response.

parse_claims

Parse a claims response. EPO’s shape:

parse_description

Parse a full-text description response. EPO’s shape:

parse_family

Parse INPADOC family response to extract family members.

parse_search_results

Parse search results from EPO OPS biblio-search response.

validate_cql

Validate a CQL string. Returns the parsed-fields decomposition on success or the first error encountered.