epo_ops

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 24, 2025 License: MIT Imports: 20 Imported by: 0

README

EPO OPS Go Client

A Go client library for the European Patent Office's Open Patent Services (OPS) API v3.2.

Overview

This library provides an idiomatic Go interface to interact with the EPO's Open Patent Services, allowing you to:

  • Retrieve patent bibliographic data, claims, descriptions, and abstracts
  • Search for patents using various criteria
  • Get patent family information (INPADOC)
  • Access CPC/ECLA classification data (schema, statistics, mapping, media)
  • Download patent images and convert TIFF to PNG
  • Access legal status and register data
  • Track API quota usage

Features

  • OAuth2 authentication with automatic token management
  • Patent text retrieval (biblio, claims, description, abstract, fulltext)
  • Patent search using CQL (Contextual Query Language)
  • INPADOC family retrieval
  • CPC/ECLA classification services (schema, statistics, mapping, media)
  • Patent image retrieval with TIFF to PNG conversion
  • Legal status retrieval
  • EPO Register access (biblio, events, procedural steps, unitary patent)
  • Patent number format conversion
  • Comprehensive error handling with custom error types
  • Automatic retry logic with exponential backoff
  • Quota tracking and fair use monitoring
  • Unit and integration tests

Installation

go get github.com/patent-dev/epo-ops

Quick Start

package main

import (
    "context"
    "fmt"
    "log"

    ops "github.com/patent-dev/epo-ops"
)

func main() {
    config := &ops.Config{
        ConsumerKey:    "your-consumer-key",
        ConsumerSecret: "your-consumer-secret",
    }

    client, err := ops.NewClient(config)
    if err != nil {
        log.Fatal(err)
    }

    ctx := context.Background()

    // Retrieve bibliographic data
    biblio, err := client.GetBiblio(ctx, "publication", "docdb", "EP1000000")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println("Biblio:", biblio)

    // Search patents
    results, err := client.Search(ctx, "ti=plastic", "1-5")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println("Search results:", results)

    // Get patent family
    family, err := client.GetFamily(ctx, "publication", "docdb", "EP1000000B1")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println("Family:", family)

    // Get patent image (first page of drawings)
    imageData, err := client.GetImage(ctx, "EP", "1000000", "B1", "Drawing", 1)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Retrieved image: %d bytes\n", len(imageData))
}

Getting Credentials

To use the EPO OPS API, you need to register for API credentials:

  1. Visit https://developers.epo.org/
  2. Create an account or sign in
  3. Register a new application to get your consumer key and secret

Fair Use Policy & Quota Tracking

The EPO OPS API has usage limits:

  • Non-paying users: 4 GB/week (free)
  • Paying users: >4 GB/week (€2,800/year)

See: https://www.epo.org/en/service-support/ordering/fair-use

This client automatically tracks quota usage from API responses:

// Make API calls
client.GetBiblio(ctx, "publication", "docdb", "EP1000000")

// Check quota status
quota := client.GetLastQuota()
if quota != nil {
    fmt.Printf("Status: %s\n", quota.Status) // "green", "yellow", "red", or "black"
    fmt.Printf("Individual: %d/%d (%.2f%%)\n",
        quota.Individual.Used,
        quota.Individual.Limit,
        quota.Individual.UsagePercent())
}

Image Retrieval & TIFF Conversion

Patent images from EPO are typically in TIFF format. This library includes utilities to convert TIFF to PNG:

import (
    ops "github.com/patent-dev/epo-ops"
    "github.com/patent-dev/epo-ops/tiffutil"
)

// Retrieve patent image (TIFF format)
imageData, err := client.GetImage(ctx, "EP", "1000000", "B1", "Drawing", 1)
if err != nil {
    log.Fatal(err)
}

// Convert TIFF to PNG (with automatic rotation for landscape images)
pngData, err := tiffutil.TIFFToPNG(imageData)
if err != nil {
    log.Fatal(err)
}

// Save PNG file
os.WriteFile("patent_drawing.png", pngData, 0644)

// Or convert without rotation
pngData, err := tiffutil.TIFFToPNGNoRotate(imageData)

// Or batch convert multiple pages
pngImages, err := tiffutil.BatchTIFFToPNG([][]byte{imageData1, imageData2, imageData3})

The TIFF utilities support:

  • CCITT Group 3/4 compression (common in patent drawings)
  • LZW compression
  • CMYK color model
  • Automatic landscape-to-portrait rotation

API Reference

Client Creation
// Create client with default configuration
config := &ops.Config{
    ConsumerKey:    "your-key",
    ConsumerSecret: "your-secret",
}
client, err := ops.NewClient(config)

// Create client with custom configuration
config := &ops.Config{
    ConsumerKey:    "your-key",
    ConsumerSecret: "your-secret",
    BaseURL:        "https://ops.epo.org/3.2/rest-services",  // Default
    MaxRetries:     3,                                          // Default
    RetryDelay:     time.Second,                                // Default
    Timeout:        30 * time.Second,                           // Default
}
client, err := ops.NewClient(config)
Published Data Retrieval
// Retrieve bibliographic data
biblio, err := client.GetBiblio(ctx, "publication", "docdb", "EP1000000B1")

// Retrieve claims
claims, err := client.GetClaims(ctx, "publication", "docdb", "EP1000000B1")

// Retrieve description
description, err := client.GetDescription(ctx, "publication", "docdb", "EP1000000B1")

// Retrieve abstract
abstract, err := client.GetAbstract(ctx, "publication", "docdb", "EP1000000B1")

// Retrieve full text (biblio + abstract + description + claims)
fulltext, err := client.GetFulltext(ctx, "publication", "docdb", "EP1000000B1")

Parameters:

  • refType: Reference type - "publication", "application", or "priority"
  • format: Number format - "docdb" or "epodoc"
  • number: Patent number (e.g., "EP1000000B1")
// Basic search
results, err := client.Search(ctx, "ti=plastic", "1-25")

// Search with specific constituent
results, err := client.SearchWithConstituent(ctx, "biblio", "pa=Siemens", "1-10")

CQL Query Examples:

  • ti=plastic - Title contains "plastic"
  • pa=Siemens - Applicant is Siemens
  • ti=plastic and pa=Siemens - Combined search
  • de - Country code DE

Range Format: "1-25" (default), "1-100", etc.

Family Retrieval
// Basic INPADOC family
family, err := client.GetFamily(ctx, "publication", "docdb", "EP1000000B1")

// Family with bibliographic data
family, err := client.GetFamilyWithBiblio(ctx, "publication", "docdb", "EP1000000B1")

// Family with legal status
family, err := client.GetFamilyWithLegal(ctx, "publication", "docdb", "EP1000000B1")
Images
// Retrieve patent image (typically TIFF format)
imageData, err := client.GetImage(ctx, "EP", "1000000", "B1", "Drawing", 1)

// Image types: "FullDocument", "Drawing", "FirstPageClipping"
// Page: 1-based page number

// Legal status data
legal, err := client.GetLegal(ctx, "publication", "docdb", "EP1000000B1")

// EPO Register bibliographic data
registerBiblio, err := client.GetRegisterBiblio(ctx, "publication", "docdb", "EP1000000B1")

// EPO Register procedural events
events, err := client.GetRegisterEvents(ctx, "publication", "docdb", "EP1000000B1")
Number Conversion
// Convert patent number formats
converted, err := client.ConvertPatentNumber(ctx, "publication", "docdb", "EP1000000B1", "epodoc")

Formats:

  • original: US.(05/948,554).19781004
  • epodoc: US19780948554
  • docdb: US 19780948554
Quota Monitoring
// Get last quota information
quota := client.GetLastQuota()
if quota != nil {
    fmt.Printf("Status: %s\n", quota.Status)
    fmt.Printf("Usage: %.2f%%\n", quota.Individual.UsagePercent())
}

Configuration Options

Option Type Default Description
ConsumerKey string required OAuth2 consumer key
ConsumerSecret string required OAuth2 consumer secret
BaseURL string https://ops.epo.org/3.2/rest-services API base URL
MaxRetries int 3 Maximum retry attempts
RetryDelay time.Duration 1s Base delay between retries
Timeout time.Duration 30s HTTP client timeout (increase for bulk classification endpoints)

Error Handling

The library provides custom error types for different failure scenarios:

biblio, err := client.GetBiblio(ctx, "publication", "docdb", "EP1000000B1")
if err != nil {
    switch e := err.(type) {
    case *ops.AuthError:
        // Authentication failed
        log.Printf("Auth error: %v", e)
    case *ops.NotFoundError:
        // Patent not found (404)
        log.Printf("Patent not found: %v", e)
    case *ops.QuotaExceededError:
        // Fair use limit exceeded
        log.Printf("Quota exceeded: %v", e)
    case *ops.ServiceUnavailableError:
        // Temporary service outage
        log.Printf("Service unavailable: %v", e)
    default:
        // Other errors
        log.Printf("Error: %v", err)
    }
}

Available Error Types:

  • AuthError - Authentication failures
  • NotFoundError - Resource not found (404)
  • QuotaExceededError - Fair use quota exceeded (429, 403)
  • ServiceUnavailableError - Temporary service outage (503)
  • AmbiguousPatentError - Multiple kind codes available
  • ConfigError - Configuration issues

Retry Logic

The client automatically retries failed requests with exponential backoff:

  • Retryable: 5xx errors, 408, timeouts, network errors
  • Non-retryable: 404, 400, authentication errors, quota exceeded
  • Token refresh: Automatic on 401 errors
  • Backoff: Exponential with base delay × (attempt + 1)

Example with custom retry configuration:

config := &ops.Config{
    ConsumerKey:    "your-key",
    ConsumerSecret: "your-secret",
    MaxRetries:     5,                   // Try up to 5 times
    RetryDelay:     2 * time.Second,     // Start with 2s delay
}
client, err := ops.NewClient(config)

Testing

Run unit tests:

go test -v

Run integration tests (requires credentials):

export EPO_OPS_CONSUMER_KEY="your-key"
export EPO_OPS_CONSUMER_SECRET="your-secret"
go test -tags=integration -v

Demo Application

See the demo/ directory for a complete example application demonstrating all features.

API Specification

This library uses an OpenAPI 3.0 specification that was:

  • Converted from the official EPO OPS Swagger 2.0 specification
  • Extended to include the Data Usage Statistics endpoint (missing from official spec)
  • Enhanced with proper type definitions for generated code

The specification is maintained in openapi.yaml and used to generate strongly-typed client code.

Similar Projects

  • epo-bdds - EPO Bulk Data Download Service client
  • uspto-odp - USPTO Open Data Portal client

License

MIT License - see LICENSE file for details.

Credits

Developed by:

Documentation

Overview

Package epo_ops provides a Go client for the European Patent Office's Open Patent Services (OPS) API v3.2.

This library provides an idiomatic Go interface to interact with the EPO's Open Patent Services, allowing you to retrieve patent bibliographic data, claims, descriptions, search for patents, get patent family information, download images, and more.

Example usage: 

config := &ops.Config{
    ConsumerKey:    "your-consumer-key",
    ConsumerSecret: "your-consumer-secret",
}

client, err := ops.NewClient(config)
if err != nil {
    log.Fatal(err)
}

ctx := context.Background()
biblio, err := client.GetBiblio(ctx, "publication", "docdb", "EP1000000")
if err != nil {
    log.Fatal(err)
}

Index

Constants

View Source 
const (
	RefTypePublication = "publication"
	RefTypeApplication = "application"
	RefTypePriority    = "priority"
)

Reference types for API requests

View Source 
const (
	FormatDocDB    = "docdb"
	FormatEPODOC   = "epodoc"
	FormatOriginal = "original"
)

Number formats for API requests

View Source 
const (
	ImageTypeThumbnail = "thumbnail" // Drawings only
	ImageTypeFullImage = "fullimage" // Full document with all sections
	ImageTypeFirstPage = "firstpage" // First page clipping (requires kind="PA")
)

Image types for GetImage (lowercase per EPO OPS specification)

View Source 
const (
	ConstituentBiblio    = "biblio"
	ConstituentAbstract  = "abstract"
	ConstituentFullCycle = "full-cycle"
)

Search constituents

View Source 
const (
	EndpointBiblio      = "biblio"
	EndpointFulltext    = "fulltext"
	EndpointClaims      = "claims"
	EndpointDescription = "description"
	EndpointAbstract    = "abstract"
	EndpointFamily      = "family"
	EndpointLegal       = "legal"
	EndpointRegister    = "register"
	EndpointSearch      = "search"
	EndpointImages      = "images"
)

Endpoint types for Accept header selection

Variables

This section is empty.

Functions

func GetEmbeddedXSD 

func GetEmbeddedXSD(name string) (string, bool)

GetEmbeddedXSD returns the embedded XSD schema content by name. This allows users to access schemas for custom validation if needed.

Available schemas: "exchange-documents", "fulltext-documents", "ops_legal", "ops", "cpc"

func ValidateDate 

func ValidateDate(date string) error

ValidateDate validates a date string in YYYYMMDD format.

Examples of valid dates:

  • 20231015 (October 15, 2023)
  • 19990101 (January 1, 1999)

Note: This only validates the format, not whether the date is valid (e.g., it accepts 20231399 which is not a real date). Empty string is accepted (date is optional in many API calls).

func ValidateDocdbFormat 

func ValidateDocdbFormat(number string) error

ValidateDocdbFormat validates the docdb format: CC.number.KC

Examples of valid docdb format:

  • EP.1000000.B1
  • US.5551212.A
  • WO.2023123456.A1

Format rules:

  • Two-letter country code in uppercase
  • Dot separator
  • Numeric document number
  • Dot separator
  • Kind code: letter + optional digit

func ValidateEpodocFormat 

func ValidateEpodocFormat(number string) error

ValidateEpodocFormat validates the epodoc format: CCnumber[KC]

Examples of valid epodoc format:

  • EP1000000B1
  • EP1000000 (kind code optional)
  • US5551212A
  • WO2023123456A1

Format rules:

  • Two-letter country code in uppercase
  • Numeric document number
  • Optional kind code: letter + optional digit

func ValidateFormat 

func ValidateFormat(format, number string) error

ValidateFormat validates a patent number based on the specified format.

Parameters:

  • format: One of "docdb", "epodoc", or "original" (from constants)
  • number: The patent number to validate

Returns a ValidationError if the format is invalid or the number doesn't match the format rules.

func ValidateOriginalFormat 

func ValidateOriginalFormat(number string) error

ValidateOriginalFormat validates the original format (flexible).

The "original" format is the format as provided by the patent authority, which can vary significantly. This validation is permissive and only checks that the number is non-empty and within reasonable length limits.

Examples of valid original format:

  • EP 1000000 B1 (with spaces)
  • US5,551,212 (with commas)
  • WO/2023/123456
  • Any format used by patent authorities

func ValidatePatentNumber 

func ValidatePatentNumber(number string) error

ValidatePatentNumber performs basic validation on a patent number string. Returns an error if the patent number is invalid.

Validation rules:

  • Must not be empty
  • Length must be between 4 and 50 characters
  • Must contain only ASCII letters, digits, and basic punctuation

Note: This is a permissive validation. Invalid patent numbers will be rejected by the EPO API with appropriate error messages.

func ValidateRefType 

func ValidateRefType(refType string) error

ValidateRefType validates a reference type parameter.

Valid reference types:

  • "publication" - Published patent documents
  • "application" - Patent applications
  • "priority" - Priority documents

func ValidateTimeRange 

func ValidateTimeRange(timeRange string) error

ValidateTimeRange validates a time range string for the Usage Statistics API.

Valid formats:

  • Single date: "dd/mm/yyyy" (e.g., "01/01/2024")
  • Date range: "dd/mm/yyyy~dd/mm/yyyy" (e.g., "01/01/2024~07/01/2024")

Returns an error if the format is invalid.

Types

type AbstractData 

type AbstractData struct {
	XMLName      xml.Name `xml:"world-patent-data"`
	PatentNumber string
	Country      string
	DocNumber    string
	Kind         string
	Language     string
	Text         string
}

AbstractData represents parsed patent abstract

func ParseAbstract 

func ParseAbstract(xmlData string) (*AbstractData, error)

ParseAbstract parses abstract XML into structured data

type AmbiguousPatentError 

type AmbiguousPatentError struct {
	Country   string
	Number    string
	KindCodes []string
	Message   string
}

AmbiguousPatentError represents a situation where a patent number has multiple kind codes available (A1, B1, etc.) and the user must choose a specific one.

func (*AmbiguousPatentError) Error 

func (e *AmbiguousPatentError) Error() string

type AuthError 

type AuthError struct {
	StatusCode int
	Message    string
}

AuthError represents an authentication error.

func (*AuthError) Error 

func (e *AuthError) Error() string

type Authenticator 

type Authenticator struct {
	// contains filtered or unexported fields
}

Authenticator handles OAuth2 authentication for the EPO OPS API.

func NewAuthenticator 

func NewAuthenticator(consumerKey, consumerSecret string, httpClient *http.Client) *Authenticator

NewAuthenticator creates a new Authenticator.

func (*Authenticator) ClearToken 

func (a *Authenticator) ClearToken()

ClearToken clears the cached token, forcing a refresh on next request.

func (*Authenticator) GetToken 

func (a *Authenticator) GetToken(ctx context.Context) (string, error)

GetToken returns a valid access token, refreshing it if necessary.

type BiblioData 

type BiblioData struct {
	XMLName         xml.Name `xml:"world-patent-data"`
	PatentNumber    string
	Country         string
	DocNumber       string
	Kind            string
	PublicationDate string
	FamilyID        string
	Titles          map[string]string // lang -> title
	Applicants      []Party
	Inventors       []Party
	IPCClasses      []string
	CPCClasses      []CPCClass
}

BiblioData represents parsed bibliographic data

func ParseBiblio 

func ParseBiblio(xmlData string) (*BiblioData, error)

ParseBiblio parses bibliographic XML into structured data

type BulkOptions 

type BulkOptions struct {
	// MaxConcurrent is the maximum number of concurrent requests.
	// Default: 1 (sequential processing)
	// Note: Concurrent processing not yet implemented
	MaxConcurrent int

	// OnProgress is called after each batch completes.
	// Parameters: current batch number, total batches
	// Optional: set to nil to disable progress callbacks
	OnProgress func(current, total int)
}

BulkOptions holds configuration options for bulk retrieval operations.

type CPCClass 

type CPCClass struct {
	Section   string
	Class     string
	Subclass  string
	MainGroup string
	Subgroup  string
	Full      string // Combined representation (e.g., "H04W 84/20")
}

CPCClass represents a Cooperative Patent Classification

type Claim 

type Claim struct {
	Number int
	Text   string
}

Claim represents a single patent claim

type ClaimsData 

type ClaimsData struct {
	XMLName      xml.Name `xml:"world-patent-data"`
	PatentNumber string
	Country      string
	DocNumber    string
	Kind         string
	Language     string
	Claims       []Claim
}

ClaimsData represents parsed patent claims

func ParseClaims 

func ParseClaims(xmlData string) (*ClaimsData, error)

ParseClaims parses claims XML into structured data

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is the main EPO OPS API client.

func NewClient 

func NewClient(config *Config) (*Client, error)

NewClient creates a new EPO OPS API client.

func (*Client) ConvertPatentNumber 

func (c *Client) ConvertPatentNumber(ctx context.Context, refType, inputFormat, number, outputFormat string) (string, error)

ConvertPatentNumber converts a patent number from one format to another.

Parameters:

  • refType: Reference type (e.g., "publication", "application", "priority")
  • inputFormat: Input format ("original", "epodoc", "docdb")
  • number: Patent number in input format
  • outputFormat: Output format ("original", "epodoc", "docdb")

Returns the patent number in the requested output format as XML.

Format examples:

  • original: US.(05/948,554).19781004
  • epodoc: US19780948554
  • docdb: US 19780948554

func (*Client) ConvertPatentNumberMultiple 

func (c *Client) ConvertPatentNumberMultiple(ctx context.Context, refType, inputFormat string, numbers []string, outputFormat string) (string, error)

ConvertPatentNumberMultiple converts multiple patent numbers from one format to another. Uses POST endpoint for efficient batch conversion of up to 100 patents in one request.

Parameters:

  • refType: Reference type (e.g., RefTypePublication, RefTypeApplication, RefTypePriority)
  • inputFormat: Input format ("original", "epodoc", "docdb")
  • numbers: Slice of patent numbers in input format (max 100)
  • outputFormat: Output format ("original", "epodoc", "docdb")

Returns XML containing converted patent numbers for all requested patents.

func (*Client) GetAbstract 

func (c *Client) GetAbstract(ctx context.Context, refType, format, number string) (*AbstractData, error)

GetAbstract retrieves and parses the abstract for a patent.

Parameters:

  • refType: Reference type (e.g., RefTypePublication, RefTypeApplication, RefTypePriority)
  • format: Number format (e.g., FormatDocDB, FormatEPODOC)
  • number: Patent number (e.g., "EP1000000B1")

Returns parsed abstract data. For raw XML, use GetAbstractRaw().

func (*Client) GetAbstractMultiple 

func (c *Client) GetAbstractMultiple(ctx context.Context, refType, format string, numbers []string) (string, error)

GetAbstractMultiple retrieves abstracts for multiple patents (bulk operation). Uses POST endpoint for efficient batch retrieval of up to 100 patents in one request.

Parameters:

  • refType: Reference type (e.g., RefTypePublication, RefTypeApplication, RefTypePriority)
  • format: Number format (e.g., FormatDocDB, FormatEPODOC)
  • numbers: Slice of patent numbers (max 100)

Returns XML containing abstracts for all requested patents.

func (*Client) GetAbstractRaw 

func (c *Client) GetAbstractRaw(ctx context.Context, refType, format, number string) (string, error)

GetAbstractRaw retrieves the abstract for a patent as raw XML.

Parameters:

  • refType: Reference type (e.g., RefTypePublication, RefTypeApplication, RefTypePriority)
  • format: Number format (e.g., FormatDocDB, FormatEPODOC)
  • number: Patent number (e.g., "EP1000000B1")

Returns the abstract as an XML string.

func (*Client) GetAbstractsBulk 

func (c *Client) GetAbstractsBulk(ctx context.Context, refType, format string, numbers []string, opts *BulkOptions) ([]string, error)

GetAbstractsBulk retrieves abstracts for multiple publications with auto-batching. Automatically splits requests into batches of 100 (EPO limit) and processes them sequentially.

func (*Client) GetBiblio 

func (c *Client) GetBiblio(ctx context.Context, refType, format, number string) (*BiblioData, error)

GetBiblio retrieves and parses bibliographic data for a patent.

Parameters:

  • refType: Reference type (e.g., RefTypePublication, RefTypeApplication, RefTypePriority)
  • format: Number format (e.g., FormatDocDB, FormatEPODOC)
  • number: Patent number (e.g., "EP1000000B1")

Returns parsed bibliographic data. For raw XML, use GetBiblioRaw().

func (*Client) GetBiblioMultiple 

func (c *Client) GetBiblioMultiple(ctx context.Context, refType, format string, numbers []string) (string, error)

GetBiblioMultiple retrieves bibliographic data for multiple patents (bulk operation). Uses POST endpoint for efficient batch retrieval of up to 100 patents in one request.

Parameters:

  • refType: Reference type (e.g., RefTypePublication, RefTypeApplication, RefTypePriority)
  • format: Number format (e.g., FormatDocDB, FormatEPODOC)
  • numbers: Slice of patent numbers (max 100)

Returns XML containing bibliographic data for all requested patents.

Example: 

numbers := []string{"EP.1000000.B1", "EP.1000001.A1", "US.5551212.A"}
xml, err := client.GetBiblioMultiple(ctx, ops.RefTypePublication, ops.FormatDocDB, numbers)

func (*Client) GetBiblioRaw 

func (c *Client) GetBiblioRaw(ctx context.Context, refType, format, number string) (string, error)

GetBiblioRaw retrieves bibliographic data for a patent as raw XML.

Parameters:

  • refType: Reference type (e.g., RefTypePublication, RefTypeApplication, RefTypePriority)
  • format: Number format (e.g., FormatDocDB, FormatEPODOC)
  • number: Patent number (e.g., "EP1000000B1")

Returns the bibliographic data as an XML string.

func (*Client) GetBibliosBulk 

func (c *Client) GetBibliosBulk(ctx context.Context, refType, format string, numbers []string, opts *BulkOptions) ([]string, error)

GetBibliosBulk retrieves bibliographic data for multiple publications with auto-batching. Automatically splits requests into batches of 100 (EPO limit) and processes them sequentially.

func (*Client) GetClaims 

func (c *Client) GetClaims(ctx context.Context, refType, format, number string) (*ClaimsData, error)

GetClaims retrieves and parses claims for a patent.

Parameters:

  • refType: Reference type (e.g., RefTypePublication, RefTypeApplication, RefTypePriority)
  • format: Number format (e.g., FormatDocDB, FormatEPODOC)
  • number: Patent number (e.g., "EP1000000B1")

Returns parsed claims data. For raw XML, use GetClaimsRaw().

func (*Client) GetClaimsBulk 

func (c *Client) GetClaimsBulk(ctx context.Context, refType, format string, numbers []string, opts *BulkOptions) ([]string, error)

GetClaimsBulk retrieves claims for multiple publications with auto-batching. Automatically splits requests into batches of 100 (EPO limit) and processes them sequentially.

func (*Client) GetClaimsMultiple 

func (c *Client) GetClaimsMultiple(ctx context.Context, refType, format string, numbers []string) (string, error)

GetClaimsMultiple retrieves claims for multiple patents (bulk operation). Uses POST endpoint for efficient batch retrieval of up to 100 patents in one request.

Parameters:

  • refType: Reference type (e.g., RefTypePublication, RefTypeApplication, RefTypePriority)
  • format: Number format (e.g., FormatDocDB, FormatEPODOC)
  • numbers: Slice of patent numbers (max 100)

Returns XML containing claims for all requested patents.

func (*Client) GetClaimsRaw 

func (c *Client) GetClaimsRaw(ctx context.Context, refType, format, number string) (string, error)

GetClaimsRaw retrieves claims for a patent as raw XML.

Parameters:

  • refType: Reference type (e.g., RefTypePublication, RefTypeApplication, RefTypePriority)
  • format: Number format (e.g., FormatDocDB, FormatEPODOC)
  • number: Patent number (e.g., "EP1000000B1")

Returns the claims as an XML string.

func (*Client) GetClassificationMapping 

func (c *Client) GetClassificationMapping(ctx context.Context, inputFormat, class, subclass, outputFormat string, additional bool) (string, error)

GetClassificationMapping converts between CPC and ECLA classification formats.

This method maps classification codes between the Cooperative Patent Classification (CPC) and European Classification (ECLA) systems. This is useful when working with patents that use different classification systems.

Parameters:

  • inputFormat: Format of the input classification ("cpc" or "ecla")
  • class: Classification class code (e.g., "A01D2085")
  • subclass: Classification subclass code (e.g., "8")
  • outputFormat: Desired output format ("cpc" or "ecla")
  • additional: If true, include additional/invention information

Returns XML containing:

  • Mapped classification codes
  • Mapping relationships
  • Classification descriptions

Example: 

// Convert ECLA to CPC
mapping, err := client.GetClassificationMapping(ctx, "ecla", "A01D2085", "8", "cpc", false)
if err != nil {
    log.Fatal(err)
}

// Convert CPC to ECLA with additional information
mapping, err := client.GetClassificationMapping(ctx, "cpc", "H04W84", "18", "ecla", true)

func (*Client) GetClassificationMedia 

func (c *Client) GetClassificationMedia(ctx context.Context, mediaName string, asAttachment bool) ([]byte, error)

GetClassificationMedia retrieves media files (images/diagrams) for CPC classifications.

The CPC classification system includes illustrative diagrams and images to help understand classification concepts. This method downloads these media files.

Parameters:

  • mediaName: Name of the media resource (e.g., "1000.gif", "5000.png")
  • Media names are referenced in classification schema XML
  • Common formats: GIF, PNG, JPG
  • asAttachment: If true, sets Content-Disposition to attachment (forces download)
  • false (default): inline display
  • true: download as attachment

Returns binary image data that can be saved to a file or displayed.

Example: 

// Download a classification diagram
imageData, err := client.GetClassificationMedia(ctx, "1000.gif", false)
if err != nil {
    log.Fatal(err)
}

// Save to file
err = os.WriteFile("classification-1000.gif", imageData, 0644)

func (*Client) GetClassificationSchema 

func (c *Client) GetClassificationSchema(ctx context.Context, class string, ancestors, navigation bool) (string, error)

GetClassificationSchema retrieves CPC classification schema hierarchy.

This method retrieves the Cooperative Patent Classification (CPC) hierarchy for a given classification symbol. The CPC is a patent classification system jointly developed by the EPO and USPTO.

Parameters:

  • class: CPC classification symbol (e.g., "A01B", "H04W84/18")
  • Section + Class format: "A01" retrieves all subclasses
  • Class + Subclass format: "A01B" retrieves class hierarchy
  • Full symbol: "H04W84/18" retrieves specific classification
  • ancestors: If true, include ancestor classifications in the hierarchy
  • navigation: If true, include navigation links to related classifications

Returns XML containing:

  • Classification hierarchy structure
  • Class titles and descriptions
  • Parent/child relationships
  • Related classification links (if navigation=true)

Example: 

// Get full hierarchy for class A01B
schema, err := client.GetClassificationSchema(ctx, "A01B", false, false)

// Get with ancestors and navigation
schema, err := client.GetClassificationSchema(ctx, "H04W84/18", true, true)

func (*Client) GetClassificationSchemaMultiple 

func (c *Client) GetClassificationSchemaMultiple(ctx context.Context, classes []string) (string, error)

GetClassificationSchemaMultiple retrieves CPC classification schemas for multiple classifications.

This method uses the POST endpoint to retrieve classification data for multiple classification symbols in a single request.

Parameters:

  • classes: Slice of CPC classification symbols (max 100)
  • Each can be in any supported format: "A01", "A01B", "H04W84/18"

Returns XML containing classification hierarchies for all requested symbols.

Example: 

classes := []string{"A01B", "H04W", "G06F17/30"}
schemas, err := client.GetClassificationSchemaMultiple(ctx, classes)

func (*Client) GetClassificationSchemaSubclass 

func (c *Client) GetClassificationSchemaSubclass(ctx context.Context, class, subclass string, ancestors, navigation bool) (string, error)

GetClassificationSchemaSubclass retrieves CPC classification schema for a specific subclass.

This is a more specific version of GetClassificationSchema that retrieves classification hierarchy for a specific class/subclass combination.

Parameters:

  • class: CPC class identifier (e.g., "A01B1")
  • subclass: CPC subclass identifier (e.g., "00")
  • ancestors: If true, include ancestor classifications in the hierarchy
  • navigation: If true, include navigation links to related classifications

Returns XML containing the subclass classification hierarchy.

Example: 

// Get specific subclass hierarchy
schema, err := client.GetClassificationSchemaSubclass(ctx, "A01B1", "00", false, false)

func (*Client) GetClassificationStatistics 

func (c *Client) GetClassificationStatistics(ctx context.Context, query string) (string, error)

GetClassificationStatistics searches for CPC classification statistics.

This method retrieves statistical information about patent counts across CPC classification codes. It allows searching for classification codes and returns the number of patents in each classification.

Parameters:

  • query: Search query for classification codes
  • Can be a keyword (e.g., "plastic", "wireless")
  • Can be a classification code (e.g., "H04W", "A01B")
  • Can use wildcard patterns

Returns XML or JSON containing:

  • Classification codes matching the query
  • Patent counts for each classification
  • Classification titles and descriptions

The response format depends on the Accept header sent by the client. By default, XML is returned.

Example: 

// Search for statistics on "wireless" classifications
stats, err := client.GetClassificationStatistics(ctx, "wireless")
if err != nil {
    log.Fatal(err)
}

// Search for specific classification
stats, err := client.GetClassificationStatistics(ctx, "H04W")

func (*Client) GetDescription 

func (c *Client) GetDescription(ctx context.Context, refType, format, number string) (string, error)

GetDescription retrieves the description for a patent.

Parameters:

  • refType: Reference type (e.g., "publication", "application", "priority")
  • format: Number format (e.g., "docdb", "epodoc")
  • number: Patent number (e.g., "EP1000000")

Returns the description as an XML string.

func (*Client) GetDescriptionMultiple 

func (c *Client) GetDescriptionMultiple(ctx context.Context, refType, format string, numbers []string) (string, error)

GetDescriptionMultiple retrieves descriptions for multiple patents (bulk operation). Uses POST endpoint for efficient batch retrieval of up to 100 patents in one request.

Parameters:

  • refType: Reference type (e.g., RefTypePublication, RefTypeApplication, RefTypePriority)
  • format: Number format (e.g., FormatDocDB, FormatEPODOC)
  • numbers: Slice of patent numbers (max 100)

Returns XML containing descriptions for all requested patents.

func (*Client) GetDescriptionsBulk 

func (c *Client) GetDescriptionsBulk(ctx context.Context, refType, format string, numbers []string, opts *BulkOptions) ([]string, error)

GetDescriptionsBulk retrieves descriptions for multiple publications with auto-batching. Automatically splits requests into batches of 100 (EPO limit) and processes them sequentially.

func (*Client) GetFamily 

func (c *Client) GetFamily(ctx context.Context, refType, format, number string) (string, error)

GetFamily retrieves the INPADOC patent family for a given patent.

Parameters:

  • refType: Reference type (e.g., "publication", "application", "priority")
  • format: Number format (e.g., "docdb", "epodoc")
  • number: Patent number (e.g., "EP1000000")

Returns the family data as XML containing all family members.

INPADOC (International Patent Documentation) family includes all patents related through priority claims.

func (*Client) GetFamilyWithBiblio 

func (c *Client) GetFamilyWithBiblio(ctx context.Context, refType, format, number string) (string, error)

GetFamilyWithBiblio retrieves the INPADOC patent family with bibliographic data.

Parameters:

  • refType: Reference type (e.g., "publication", "application", "priority")
  • format: Number format (e.g., "docdb", "epodoc")
  • number: Patent number (e.g., "EP1000000")

Returns the family data with biblio as XML.

func (*Client) GetFamilyWithBiblioMultiple 

func (c *Client) GetFamilyWithBiblioMultiple(ctx context.Context, refType, format string, numbers []string) (string, error)

GetFamilyWithBiblioMultiple retrieves INPADOC patent family with bibliographic data for multiple patents.

This method uses the POST endpoint to retrieve family data with bibliographic information for multiple patent numbers in a single request.

Parameters:

  • refType: Reference type (e.g., RefTypePublication, RefTypeApplication, RefTypePriority)
  • format: Number format (e.g., FormatDocDB, FormatEPODOC)
  • numbers: Slice of patent numbers (max 100)

Returns XML containing family data with biblio for all requested patents.

func (*Client) GetFamilyWithLegal 

func (c *Client) GetFamilyWithLegal(ctx context.Context, refType, format, number string) (string, error)

GetFamilyWithLegal retrieves the INPADOC patent family with legal status data.

Parameters:

  • refType: Reference type (e.g., "publication", "application", "priority")
  • format: Number format (e.g., "docdb", "epodoc")
  • number: Patent number (e.g., "EP1000000")

Returns the family data with legal status as XML.

func (*Client) GetFamilyWithLegalMultiple 

func (c *Client) GetFamilyWithLegalMultiple(ctx context.Context, refType, format string, numbers []string) (string, error)

GetFamilyWithLegalMultiple retrieves INPADOC patent family with legal status data for multiple patents.

This method uses the POST endpoint to retrieve family data with legal status for multiple patent numbers in a single request.

Parameters:

  • refType: Reference type (e.g., RefTypePublication, RefTypeApplication, RefTypePriority)
  • format: Number format (e.g., FormatDocDB, FormatEPODOC)
  • numbers: Slice of patent numbers (max 100)

Returns XML containing family data with legal status for all requested patents.

func (*Client) GetFullCycleMultiple 

func (c *Client) GetFullCycleMultiple(ctx context.Context, refType, format string, numbers []string) (string, error)

GetFullCycleMultiple retrieves full cycle data for multiple patents (bulk operation). Uses POST endpoint for efficient batch retrieval of up to 100 patents in one request.

Full cycle data includes the complete publication history and bibliographic evolution of a patent across different publication stages (e.g., A1, A2, B1, B2).

Parameters:

  • refType: Reference type (e.g., RefTypePublication, RefTypeApplication, RefTypePriority)
  • format: Number format (e.g., FormatDocDB, FormatEPODOC)
  • numbers: Slice of patent numbers (max 100)

Returns XML containing full cycle data for all requested patents.

func (*Client) GetFulltext 

func (c *Client) GetFulltext(ctx context.Context, refType, format, number string) (string, error)

GetFulltext retrieves the full text (biblio, abstract, description, claims) for a patent.

Parameters:

  • refType: Reference type (e.g., "publication", "application", "priority")
  • format: Number format (e.g., "docdb", "epodoc")
  • number: Patent number (e.g., "EP1000000")

Returns the full text as an XML string.

func (*Client) GetFulltextMultiple 

func (c *Client) GetFulltextMultiple(ctx context.Context, refType, format string, numbers []string) (string, error)

GetFulltextMultiple retrieves full text for multiple patents (bulk operation). Uses POST endpoint for efficient batch retrieval of up to 100 patents in one request.

Parameters:

  • refType: Reference type (e.g., RefTypePublication, RefTypeApplication, RefTypePriority)
  • format: Number format (e.g., FormatDocDB, FormatEPODOC)
  • numbers: Slice of patent numbers (max 100)

Returns XML containing full text (biblio, abstract, description, claims) for all requested patents.

func (*Client) GetFulltextsBulk 

func (c *Client) GetFulltextsBulk(ctx context.Context, refType, format string, numbers []string, opts *BulkOptions) ([]string, error)

GetFulltextsBulk retrieves fulltext for multiple publications with auto-batching. Automatically splits requests into batches of 100 (EPO limit) and processes them sequentially.

func (*Client) GetImage 

func (c *Client) GetImage(ctx context.Context, country, number, kind, imageType string, page int) ([]byte, error)

GetImage retrieves a patent image (drawing page).

Parameters:

  • country: Two-letter country code (e.g., "EP", "US", "WO")
  • number: Patent number without country code (e.g., "2400812")
  • kind: Kind code (e.g., "A1", "B1")
  • imageType: Image type - use ImageTypeFullImage constant
  • page: Page number (1-based, e.g., 1)

Returns the image data as bytes (typically TIFF format).

Example: 

imageData, err := client.GetImage(ctx, "EP", "2400812", "A1", ops.ImageTypeFullImage, 1)

Note: EPO typically returns images in TIFF format. Use tiffutil.TIFFToPNG() to convert to PNG format.

func (*Client) GetImageInquiry 

func (c *Client) GetImageInquiry(ctx context.Context, refType, format, number string) (*ImageInquiry, error)

GetImageInquiry retrieves metadata about available images for a patent.

This method queries what images are available without downloading them. Use this to discover:

  • How many pages of drawings exist
  • What document types are available (drawings, full document, etc.)
  • What formats are available (PDF, TIFF, etc.)

Parameters:

  • refType: Reference type ("publication", "application", "priority")
  • format: Number format ("docdb", "epodoc", "original")
  • number: Patent number (e.g., "EP.1000000.B1" for docdb format)

Returns an ImageInquiry containing:

  • DocumentInstances: List of available document types
  • Each instance includes: Description, NumberOfPages, Formats, Link

Example workflow: 

// First, check what's available
inquiry, err := client.GetImageInquiry(ctx, "publication", "docdb", "EP.1000000.B1")
if err != nil {
    log.Fatal(err)
}

// Then download the actual images
for _, instance := range inquiry.DocumentInstances {
    fmt.Printf("Found %s with %d pages\n", instance.Description, instance.NumberOfPages)
    for page := 1; page <= instance.NumberOfPages; page++ {
        img, _ := client.GetImage(ctx, "EP", "1000000", "B1", "fullimage", page)
        // Process image...
    }
}

func (*Client) GetImagePOST 

func (c *Client) GetImagePOST(ctx context.Context, page int, identifier string) ([]byte, error)

GetImagePOST retrieves a patent image using POST method (keeps document identifier encrypted in body). This is identical to GetImage but uses POST instead of GET, keeping the document identifier in the encrypted request body rather than the URL. Both methods return one page at a time.

Parameters:

  • page: Page number to retrieve (1-based, e.g., 1)
  • identifier: Document identifier in format "CC/NNNNNNNN/KC/TYPE" (e.g., "EP/1000000/A1/fullimage", "EP/2400812/A1/drawing")

Returns the binary image data (TIFF, PDF, or PNG format) for the specified page.

Note: Despite the POST method, this does NOT retrieve multiple pages at once. Use the page parameter to iterate through pages one at a time.

Example: 

// Get first page of full document
data, err := client.GetImagePOST(ctx, 1, "EP/1000000/A1/fullimage")

func (*Client) GetLastQuota 

func (c *Client) GetLastQuota() *QuotaInfo

GetLastQuota returns the last quota information from API responses. Returns nil if no API calls have been made yet.

Quota tracking helps monitor fair use limits (4GB/week for non-paying users). The returned QuotaInfo includes:

  • Status: "green" (<50%), "yellow" (50-75%), "red" (>75%), "black" (blocked)
  • Individual: Quota for individual users
  • Registered: Quota for registered/paying users
  • Images: Separate quota for image downloads

func (*Client) GetLegal 

func (c *Client) GetLegal(ctx context.Context, refType, format, number string) (string, error)

GetLegal retrieves legal status data for a patent.

Parameters:

  • refType: Reference type (e.g., "publication", "application", "priority")
  • format: Number format (e.g., "docdb", "epodoc")
  • number: Patent number (e.g., "EP1000000")

Returns legal status data as XML, including:

  • Legal events (grants, oppositions, revocations, etc.)
  • Status in different jurisdictions
  • Procedural information

func (*Client) GetLegalMultiple 

func (c *Client) GetLegalMultiple(ctx context.Context, refType, format string, numbers []string) (string, error)

GetLegalMultiple retrieves legal status data for multiple patents (bulk operation). Uses POST endpoint for efficient batch retrieval of up to 100 patents in one request.

Parameters:

  • refType: Reference type (e.g., RefTypePublication, RefTypeApplication, RefTypePriority)
  • format: Number format (e.g., FormatDocDB, FormatEPODOC)
  • numbers: Slice of patent numbers (max 100)

Returns XML containing legal status data for all requested patents.

func (*Client) GetPublishedEquivalents 

func (c *Client) GetPublishedEquivalents(ctx context.Context, refType, format, number string) (string, error)

GetPublishedEquivalents retrieves equivalent publications for a patent (simple family).

This returns the "simple family" - equivalent publications of the same invention (same priority claim). This is different from the INPADOC family which includes extended family members.

Parameters:

  • refType: Reference type (RefTypePublication, RefTypeApplication, or RefTypePriority)
  • format: Number format ("epodoc" or "docdb")
  • number: Patent number in specified format

Returns XML or JSON with equivalent publications.

Example: 

equivalents, err := client.GetPublishedEquivalents(ctx, epo_ops.RefTypePublication, "epodoc", "EP1000000")

func (*Client) GetPublishedEquivalentsMultiple 

func (c *Client) GetPublishedEquivalentsMultiple(ctx context.Context, refType, format string, numbers []string) (string, error)

GetPublishedEquivalentsMultiple retrieves equivalent publications for multiple patents.

This method uses the POST endpoint to retrieve simple family data for multiple patent numbers in a single request.

Parameters:

  • refType: Reference type (RefTypePublication, RefTypeApplication, or RefTypePriority)
  • format: Number format ("epodoc" or "docdb")
  • numbers: Slice of patent numbers (max 100)

Returns XML or JSON with equivalent publications for all requested patents.

Example: 

numbers := []string{"EP1000000", "EP1000001"}
equivalents, err := client.GetPublishedEquivalentsMultiple(ctx, epo_ops.RefTypePublication, "epodoc", numbers)

func (*Client) GetRegisterBiblio 

func (c *Client) GetRegisterBiblio(ctx context.Context, refType, format, number string) (string, error)

GetRegisterBiblio retrieves bibliographic data from the EPO Register.

Parameters:

  • refType: Reference type (e.g., "publication", "application", "priority")
  • format: Number format (e.g., "docdb", "epodoc")
  • number: Patent number (e.g., "EP1000000")

Returns EPO Register bibliographic data as XML.

Note: The EPO Register contains more detailed and up-to-date information than the standard bibliographic service.

func (*Client) GetRegisterBiblioMultiple 

func (c *Client) GetRegisterBiblioMultiple(ctx context.Context, refType, format string, numbers []string) (string, error)

GetRegisterBiblioMultiple retrieves bibliographic data from the EPO Register for multiple patents. Uses POST endpoint for efficient batch retrieval of up to 100 patents in one request.

Parameters:

  • refType: Reference type (e.g., RefTypePublication, RefTypeApplication, RefTypePriority)
  • format: Number format (e.g., FormatDocDB, FormatEPODOC)
  • numbers: Slice of patent numbers (max 100)

Returns XML containing EPO Register bibliographic data for all requested patents.

func (*Client) GetRegisterEvents 

func (c *Client) GetRegisterEvents(ctx context.Context, refType, format, number string) (string, error)

GetRegisterEvents retrieves procedural events from the EPO Register.

Parameters:

  • refType: Reference type (e.g., "publication", "application", "priority")
  • format: Number format (e.g., "docdb", "epodoc")
  • number: Patent number (e.g., "EP1000000")

Returns EPO Register events as XML, including:

  • Filing events
  • Publication events
  • Examination events
  • Grant/refusal events

func (*Client) GetRegisterEventsMultiple 

func (c *Client) GetRegisterEventsMultiple(ctx context.Context, refType, format string, numbers []string) (string, error)

GetRegisterEventsMultiple retrieves procedural events from the EPO Register for multiple patents. Uses POST endpoint for efficient batch retrieval of up to 100 patents in one request.

Parameters:

  • refType: Reference type (e.g., RefTypePublication, RefTypeApplication, RefTypePriority)
  • format: Number format (e.g., FormatDocDB, FormatEPODOC)
  • numbers: Slice of patent numbers (max 100)

Returns XML containing EPO Register events for all requested patents.

func (*Client) GetRegisterProceduralSteps 

func (c *Client) GetRegisterProceduralSteps(ctx context.Context, refType, format, number string) (string, error)

GetRegisterProceduralSteps retrieves procedural steps from the EPO Register.

Procedural steps provide detailed information about the procedural history of a patent application, including milestones, deadlines, and administrative actions.

Parameters:

  • refType: Reference type ("publication" or "application")
  • format: Number format ("epodoc" only)
  • number: Patent number (e.g., "EP1000000")

Returns XML containing:

  • Procedural step history
  • Step dates and descriptions
  • Administrative actions
  • Milestone information

Example: 

// Get procedural steps for a publication
steps, err := client.GetRegisterProceduralSteps(ctx, "publication", "epodoc", "EP1000000")
if err != nil {
    log.Fatal(err)
}

func (*Client) GetRegisterProceduralStepsMultiple 

func (c *Client) GetRegisterProceduralStepsMultiple(ctx context.Context, refType, format string, numbers []string) (string, error)

GetRegisterProceduralStepsMultiple retrieves procedural steps for multiple patent numbers.

This method uses the POST endpoint to retrieve procedural step data for multiple patent numbers in a single request.

Parameters:

  • refType: Reference type ("publication" or "application")
  • format: Number format ("epodoc" only)
  • numbers: Slice of patent numbers (max 100)

Returns XML containing procedural steps for all requested patents.

Example: 

numbers := []string{"EP1000000", "EP1000001", "EP1000002"}
steps, err := client.GetRegisterProceduralStepsMultiple(ctx, "publication", "epodoc", numbers)

func (*Client) GetRegisterUNIP 

func (c *Client) GetRegisterUNIP(ctx context.Context, refType, format, number string) (string, error)

GetRegisterUNIP retrieves unitary patent package (UPP) information from the EPO Register.

Parameters:

  • refType: Reference type (RefTypePublication or RefTypeApplication)
  • format: Number format (must be "epodoc")
  • number: Patent number in specified format

Returns XML or JSON with unitary patent information including:

  • Unified Patent Court opt-out status
  • Unitary effect registration
  • Participating member states

Example: 

unip, err := client.GetRegisterUNIP(ctx, epo_ops.RefTypePublication, "epodoc", "EP3000000")

func (*Client) GetRegisterUNIPMultiple 

func (c *Client) GetRegisterUNIPMultiple(ctx context.Context, refType, format string, numbers []string) (string, error)

GetRegisterUNIPMultiple retrieves unitary patent package (UPP) information for multiple patents.

Parameters:

  • refType: Reference type (RefTypePublication or RefTypeApplication)
  • format: Number format (must be "epodoc")
  • numbers: List of patent numbers (max 100)

Returns XML or JSON with unitary patent information for all requested patents.

Example: 

numbers := []string{"EP3000000", "EP3000001"}
unip, err := client.GetRegisterUNIPMultiple(ctx, epo_ops.RefTypePublication, "epodoc", numbers)

func (*Client) GetUsageStats 

func (c *Client) GetUsageStats(ctx context.Context, timeRange string) (*UsageStats, error)

GetUsageStats retrieves usage statistics from the EPO OPS Data Usage API.

The Data Usage API provides historical usage data for quota monitoring and analysis. Usage statistics are updated within 10 minutes of each hour and aligned on midnight UTC/GMT boundaries. This API does not count against quotas.

Parameters:

  • timeRange: Time range in one of two formats:
  • Single date: "dd/mm/yyyy" (e.g., "01/01/2024")
  • Date range: "dd/mm/yyyy~dd/mm/yyyy" (e.g., "01/01/2024~07/01/2024")

Returns:

  • UsageStats containing usage entries with timestamps, response sizes, and message counts
  • error if the time range format is invalid or the request fails

Example: 

// Get usage for a specific date
stats, err := client.GetUsageStats(ctx, "01/01/2024")
if err != nil {
    log.Fatal(err)
}

// Get usage for a date range
stats, err := client.GetUsageStats(ctx, "01/01/2024~07/01/2024")
for _, entry := range stats.Entries {
    fmt.Printf("Time: %d, Size: %d bytes, Messages: %d\n",
        entry.Timestamp, entry.TotalResponseSize, entry.MessageCount)
}

func (*Client) Search 

func (c *Client) Search(ctx context.Context, query string, rangeStr string) (string, error)

Search performs a bibliographic search using CQL (Contextual Query Language).

Parameters:

  • query: CQL query string (e.g., "ti=plastic", "pa=Siemens and de")
  • rangeStr: Optional range in format "1-25" (default: "1-25")

Returns the search results as XML containing matching patents.

Example queries:

  • "ti=plastic" - Title contains "plastic"
  • "pa=Siemens" - Applicant is Siemens
  • "de" - Country code DE
  • "ti=plastic and pa=Siemens" - Combined search

See OPS documentation for full CQL syntax.

func (*Client) SearchRegister 

func (c *Client) SearchRegister(ctx context.Context, query, rangeSpec string) (string, error)

SearchRegister searches the EPO Register for patents matching a query.

Parameters:

  • query: Search query (e.g., "ti=plastic", "applicant=google")
  • rangeSpec: Optional range specification (e.g., "1-25", "26-50"). Empty string uses default (1-25).

The query parameter supports various search fields including:

  • ti (title), ab (abstract), ta (title and abstract)
  • applicant, inventor
  • pn (publication number), an (application number)
  • pd (publication date), ad (application date)
  • cl (classification)

Returns XML or JSON with matching register entries including bibliographic data.

Example: 

results, err := client.SearchRegister(ctx, "ti=battery AND applicant=tesla", "1-100")

func (*Client) SearchRegisterWithConstituent 

func (c *Client) SearchRegisterWithConstituent(ctx context.Context, constituent, query, rangeSpec string) (string, error)

SearchRegisterWithConstituent searches the EPO Register and returns specific constituent data.

Parameters:

  • constituent: The type of data to return ("biblio", "events", "procedural-steps", "upp")
  • query: Search query (e.g., "ti=plastic", "applicant=google")
  • rangeSpec: Optional range specification (e.g., "1-25"). Empty string uses default (1-25).

Constituents:

  • "biblio": Bibliographic data
  • "events": Legal events
  • "procedural-steps": Procedural step information
  • "upp": Unified Patent Package data

Returns XML or JSON with matching register entries for the specified constituent.

Example: 

// Search for patents and get legal events
events, err := client.SearchRegisterWithConstituent(ctx, "events", "applicant=tesla", "1-50")

func (*Client) SearchWithConstituent 

func (c *Client) SearchWithConstituent(ctx context.Context, constituent, query string, rangeStr string) (string, error)

SearchWithConstituent performs a bibliographic search with specific constituent.

Parameters:

  • constituent: The constituent to retrieve (e.g., "biblio", "abstract", "full-cycle")
  • query: CQL query string
  • rangeStr: Optional range in format "1-25"

Returns the search results as XML with the requested constituent data.

type Config 

type Config struct {
	// BaseURL is the base URL for the OPS API.
	// Default: "https://ops.epo.org/3.2/rest-services"
	BaseURL string

	// AuthURL is the OAuth2 token endpoint URL.
	// Default: "https://ops.epo.org/3.2/auth/accesstoken"
	// This field is primarily for testing purposes.
	AuthURL string

	// ConsumerKey is the OAuth2 consumer key (required).
	ConsumerKey string

	// ConsumerSecret is the OAuth2 consumer secret (required).
	ConsumerSecret string

	// MaxRetries is the maximum number of retries for failed requests.
	// Default: 3
	MaxRetries int

	// RetryDelay is the base delay between retries.
	// Default: 1 second
	RetryDelay time.Duration

	// Timeout is the HTTP client timeout.
	// Default: 30 seconds
	Timeout time.Duration
}

Config holds configuration for the EPO OPS client.

func DefaultConfig 

func DefaultConfig() *Config

DefaultConfig returns a Config with default values.

type ConfigError 

type ConfigError struct {
	Message string
}

ConfigError represents a configuration error.

func (*ConfigError) Error 

func (e *ConfigError) Error() string

type DocumentInstance 

type DocumentInstance struct {
	// Description is a human-readable description of the document type
	// Examples: "Drawing", "FullDocument", "FirstPageClipping"
	Description string

	// Link is the URL to retrieve this document instance
	Link string

	// NumberOfPages is the total number of pages in this document instance
	NumberOfPages int

	// Formats lists the available formats for this document instance
	// Examples: ["pdf", "tiff"], ["application/pdf", "image/tiff"]
	Formats []string

	// DocType is the internal document type identifier
	// Examples: "Drawing", "FullDocument"
	DocType string
}

DocumentInstance represents a single document type available for a patent. For example, a patent might have separate instances for drawings and full document.

type ImageInquiry 

type ImageInquiry struct {
	// DocumentInstances contains the list of available document types and their metadata
	DocumentInstances []DocumentInstance
}

ImageInquiry represents the response from an image inquiry request. It contains information about available images for a patent document.

func ParseImageInquiry 

func ParseImageInquiry(xmlData string) (*ImageInquiry, error)

ParseImageInquiry parses image inquiry XML into structured data.

This function processes the XML response from the EPO OPS Published Images Inquiry service and extracts information about available document instances (drawings, full document, etc.), their page counts, available formats, and download links.

Example XML structure: 

<ops:world-patent-data>
  <ops:document-inquiry>
    <ops:inquiry-result>
      <ops:document-instance desc="Drawing" number-of-pages="5" doc-type="Drawing">
        <ops:document-instance-link href="..."/>
        <ops:document-format-options>
          <ops:document-format>application/pdf</ops:document-format>
          <ops:document-format>image/tiff</ops:document-format>
        </ops:document-format-options>
      </ops:document-instance>
    </ops:inquiry-result>
  </ops:document-inquiry>
</ops:world-patent-data>

type NotFoundError 

type NotFoundError struct {
	Resource string
	Message  string
}

NotFoundError represents a 404 error (document doesn't exist).

func (*NotFoundError) Error 

func (e *NotFoundError) Error() string

type NotImplementedError 

type NotImplementedError struct {
	Message string
}

NotImplementedError represents a not-yet-implemented feature.

func (*NotImplementedError) Error 

func (e *NotImplementedError) Error() string

type OPSError 

type OPSError struct {
	HTTPStatus int    // HTTP status code
	Code       string // EPO error code (e.g., "CLIENT.InvalidReference", "SERVER.EntityNotFound")
	Message    string // Human-readable error message
	MoreInfo   string // Optional URL with more information
}

OPSError represents a structured error response from EPO OPS API. The EPO OPS API returns errors in XML format with a code, message, and optional moreInfo URL.

func (*OPSError) Error 

func (e *OPSError) Error() string

type Party 

type Party struct {
	Name    string
	Country string
}

Party represents an applicant or inventor

type PatentNumber 

type PatentNumber struct {
	// Country is the two-letter country code (e.g., "EP", "US", "DE").
	// Empty if the input doesn't contain a valid country code.
	Country string

	// Number is the numeric/alphanumeric portion of the patent number.
	// Empty if no valid number portion is found.
	Number string

	// Kind is the kind code (e.g., "A1", "B1", "C").
	// Empty if the patent number is invalid.
	Kind string
}

PatentNumber represents the parsed components of a patent number.

func ParsePatentNumber 

func ParsePatentNumber(number string) PatentNumber

ParsePatentNumber splits a patent number into its components: country code, number, and kind code.

Patent number format rules:

  • Minimum length: 4 characters (CCnK format)
  • First two characters (A-Z, a-z) are the country code (CC)
  • Followed by the number portion (n) - can start with A-Z, a-z and must contain at least one 0-9
  • Followed by REQUIRED kind code (K) - 1-2 chars, always starts with A-Z, a-z, always at the end

Examples:

  • "EP2400812A1" → {Country: "EP", Number: "2400812", Kind: "A1"}
  • "DE123C" → {Country: "DE", Number: "123", Kind: "C"}
  • "DE123C1" → {Country: "DE", Number: "123", Kind: "C1"}
  • "USD123456S1" → {Country: "US", Number: "D123456", Kind: "S1"}

Invalid examples (return empty PatentNumber):

  • "DE123" → {Country: "", Number: "", Kind: ""} (missing kind code)
  • "123C" → {Country: "", Number: "", Kind: ""} (no country code)
  • "D123C" → {Country: "", Number: "", Kind: ""} (country code too short)
  • "DEC" → {Country: "", Number: "", Kind: ""} (no number portion)

type QuotaExceededError 

type QuotaExceededError struct {
	Message string
}

QuotaExceededError represents a fair use quota limit error.

func (*QuotaExceededError) Error 

func (e *QuotaExceededError) Error() string

type QuotaInfo 

type QuotaInfo struct {
	// Status indicates the overall quota status.
	// Possible values: "green" (<50%), "yellow" (50-75%), "red" (>75%), "black" (blocked)
	Status string

	// Individual quota for individual users (4GB/week for non-paying users)
	Individual QuotaMetric

	// Registered quota for registered users (>4GB/week for paying users)
	Registered QuotaMetric

	// Images quota (separate quota for image downloads)
	Images QuotaMetric

	// Raw header values for debugging
	ThrottlingControl string
	IndividualHeader  string
	RegisteredHeader  string
}

QuotaInfo contains quota information from EPO OPS API responses.

func ParseQuotaHeaders 

func ParseQuotaHeaders(headers http.Header) *QuotaInfo

ParseQuotaHeaders extracts quota information from HTTP response headers.

EPO OPS returns quota information in these headers:

  • X-Throttling-Control: Overall status (e.g., "green", "yellow", "red", "black")
  • X-IndividualQuota: Individual quota in format "used=123,quota=456"
  • X-RegisteredQuota: Registered quota in format "used=123,quota=456"
  • X-ImagesQuota: Images quota in format "used=123,quota=456" (optional)

type QuotaMetric 

type QuotaMetric struct {
	// Used is the amount of quota consumed
	Used int

	// Limit is the maximum quota allowed
	Limit int
}

QuotaMetric represents a quota metric with used and limit values.

func (*QuotaMetric) UsagePercent 

func (q *QuotaMetric) UsagePercent() float64

UsagePercent calculates the usage percentage (0-100).

type ServiceUnavailableError 

type ServiceUnavailableError struct {
	StatusCode int
	Message    string
	RetryAfter string // Optional Retry-After header value
}

ServiceUnavailableError represents a temporary service outage.

func (*ServiceUnavailableError) Error 

func (e *ServiceUnavailableError) Error() string

type UsageEntry 

type UsageEntry struct {
	// Timestamp is the Unix timestamp (seconds since epoch) for this entry
	Timestamp int64

	// TotalResponseSize is the total size of API responses in bytes for this period
	TotalResponseSize int64

	// MessageCount is the number of API requests made during this period
	MessageCount int

	// Service identifies which OPS service was used (optional field)
	Service string
}

UsageEntry represents a single usage data point.

Each entry corresponds to an hour of usage, with data updated within 10 minutes of the hour boundary.

type UsageStats 

type UsageStats struct {
	// TimeRange is the requested time range (dd/mm/yyyy or dd/mm/yyyy~dd/mm/yyyy)
	TimeRange string

	// Entries contains usage data points, typically one per hour
	Entries []UsageEntry
}

UsageStats represents usage statistics from the EPO OPS Data Usage API.

The Data Usage API endpoint (/3.2/developers/me/stats/usage) provides historical usage data for quota monitoring and analysis.

Usage statistics are updated within 10 minutes of each hour and aligned on midnight UTC/GMT boundaries. This API does not count against quotas.

Example usage: 

// Get usage for a specific date
stats, err := client.GetUsageStats(ctx, "01/01/2024")

// Get usage for a date range
stats, err := client.GetUsageStats(ctx, "01/01/2024~07/01/2024")

type ValidationError 

type ValidationError struct {
	Field   string // Field name that failed validation (e.g., "number", "format", "date")
	Format  string // Expected format (e.g., "docdb", "epodoc")
	Value   string // The invalid value provided
	Message string // Human-readable error message
}

ValidationError represents an input validation error. This is returned when user-provided input doesn't match the expected format.

func (*ValidationError) Error 

func (e *ValidationError) Error() string

Source Files

View all Source files

Directories

Path Synopsis
Package generated provides primitives to interact with the openapi HTTP API.
 Package generated provides primitives to interact with the openapi HTTP API.
Package tiffutil provides utilities for TIFF image handling, specifically for converting EPO patent TIFF images to PNG format.
 Package tiffutil provides utilities for TIFF image handling, specifically for converting EPO patent TIFF images to PNG format.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.