epo_ops

package module
v1.1.3 Latest Latest
Warning

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

 Go to latest Published: Mar 12, 2026 License: MIT Imports: 22 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 with INPADOC legal event data
  • EPO Register access (biblio, events, procedural steps, unitary patent)
  • Patent number format conversion and validation
  • 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 (returns *BiblioData)
    biblio, err := client.GetBiblio(ctx, "publication", "docdb", "EP.1000000.B1")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Title: %v\n", biblio.Titles)

    // Search patents (returns *SearchResultData)
    results, err := client.Search(ctx, "ti=plastic", "1-5")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Total results: %d\n", results.TotalCount)

    // Get patent family (returns *FamilyData)
    family, err := client.GetFamily(ctx, "publication", "docdb", "EP.1000000.B1")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Family members: %d\n", len(family.Members))

    // 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))
}

Parsed vs Raw API

This library provides two ways to access API data:

By default, methods return parsed Go structs for type-safe access:

// Returns *BiblioData struct
biblio, err := client.GetBiblio(ctx, "publication", "docdb", "EP.1000000.B1")
fmt.Printf("Title: %s\n", biblio.Titles["en"])
fmt.Printf("Country: %s, Doc: %s, Kind: %s\n", biblio.Country, biblio.DocNumber, biblio.Kind)
fmt.Printf("Applicants: %d\n", len(biblio.Applicants))

// Returns *FamilyData struct
family, err := client.GetFamily(ctx, "publication", "docdb", "EP.1000000.B1")
fmt.Printf("Family ID: %s\n", family.FamilyID)
fmt.Printf("Members: %d\n", len(family.Members))

// Returns *SearchResultData struct
results, err := client.Search(ctx, "ti=battery", "1-5")
fmt.Printf("Total: %d\n", results.TotalCount)
for _, r := range results.Results {
    fmt.Printf("  %s%s\n", r.Country, r.DocNumber)
}

// Returns *LegalData struct
legal, err := client.GetLegal(ctx, "publication", "docdb", "EP.1000000.B1")
for _, event := range legal.LegalEvents {
    fmt.Printf("%s: %s\n", event.Date, event.Code)
}
Raw API (XML Access)

For special cases (e.g., saving raw XML, custom parsing), use *Raw() methods:

// Returns raw XML string
xmlData, err := client.GetBiblioRaw(ctx, "publication", "docdb", "EP.1000000.B1")
os.WriteFile("biblio.xml", []byte(xmlData), 0644)

// All endpoints have Raw variants
familyXML, err := client.GetFamilyRaw(ctx, "publication", "docdb", "EP.1000000.B1")
searchXML, err := client.SearchRaw(ctx, "ti=battery", "1-5")
legalXML, err := client.GetLegalRaw(ctx, "publication", "docdb", "EP.1000000.B1")

Architecture Note: Parsed methods internally call the corresponding *Raw() method and parse the result. This ensures consistent data access and eliminates code duplication.

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", "EP.1000000.B1")

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

All methods return parsed Go structs by default. Use *Raw() variants for XML access.

// Retrieve bibliographic data → *BiblioData
biblio, err := client.GetBiblio(ctx, "publication", "docdb", "EP.1000000.B1")
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Title: %s\n", biblio.Titles["en"])
fmt.Printf("Publication Date: %s\n", biblio.PublicationDate)
fmt.Printf("IPC: %v\n", biblio.IPCClasses)
for _, applicant := range biblio.Applicants {
    fmt.Printf("Applicant: %s (%s)\n", applicant.Name, applicant.Country)
}

// Retrieve claims → *ClaimsData
claims, err := client.GetClaims(ctx, "publication", "docdb", "EP.1000000.B1")
fmt.Printf("Claims count: %d\n", len(claims.Claims))
for _, claim := range claims.Claims {
    fmt.Printf("Claim %s: %s\n", claim.Number, claim.Text)
}

// Retrieve description → *DescriptionData
description, err := client.GetDescription(ctx, "publication", "docdb", "EP.1000000.B1")
fmt.Printf("Paragraphs: %d\n", len(description.Paragraphs))

// Retrieve abstract → *AbstractData
abstract, err := client.GetAbstract(ctx, "publication", "docdb", "EP.1000000.B1")
fmt.Printf("Abstract: %s\n", abstract.Text)

// Retrieve full text → *FulltextData (biblio + abstract + description + claims)
fulltext, err := client.GetFulltext(ctx, "publication", "docdb", "EP.1000000.B1")
fmt.Printf("Title: %s\n", fulltext.Biblio.Titles["en"])
fmt.Printf("Abstract: %s\n", fulltext.Abstract.Text)
fmt.Printf("Description paragraphs: %d\n", len(fulltext.Description.Paragraphs))
fmt.Printf("Claims: %d\n", len(fulltext.Claims.Claims))

// Get published equivalents (simple family) → *EquivalentsData
equivalents, err := client.GetPublishedEquivalents(ctx, "publication", "docdb", "EP.1000000.B1")
fmt.Printf("Equivalents: %d\n", len(equivalents.Equivalents))
for _, eq := range equivalents.Equivalents {
    fmt.Printf("  %s (Date: %s, Kind: %s)\n", eq.DocNumber, eq.Date, eq.Kind)
}

// Raw XML access (if needed)
xmlData, err := client.GetBiblioRaw(ctx, "publication", "docdb", "EP.1000000.B1")
os.WriteFile("biblio.xml", []byte(xmlData), 0644)

Parameters:

  • refType: Reference type - "publication", "application", or "priority"
  • format: Number format - "docdb" or "epodoc"
  • number: Patent number - docdb format: "EP.1000000.B1", epodoc format: "EP1000000"

Returns *SearchResultData with parsed results.

// Basic search → *SearchResultData
results, err := client.Search(ctx, "ti=battery", "1-25")
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Total results: %d\n", results.TotalCount)
fmt.Printf("Range: %d-%d\n", results.RangeBegin, results.RangeEnd)
fmt.Printf("Returned: %d results\n", len(results.Results))

for _, r := range results.Results {
    fmt.Printf("  %s%s%s - %s\n", r.Country, r.DocNumber, r.Kind, r.Title)
}

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

// Raw XML access
xmlData, err := client.SearchRaw(ctx, "ti=battery", "1-25")

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

Returns *FamilyData with parsed family information.

// Basic INPADOC family → *FamilyData
family, err := client.GetFamily(ctx, "publication", "docdb", "EP.1000000.B1")
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Family ID: %s\n", family.FamilyID)
fmt.Printf("Patent Number: %s\n", family.PatentNumber)
fmt.Printf("Total Members: %d\n", family.TotalCount)
fmt.Printf("Has Legal Data: %v\n", family.Legal)

for _, member := range family.Members {
    fmt.Printf("Member: %s %s %s (Date: %s)\n",
        member.Country, member.DocNumber, member.Kind, member.Date)

    if member.ApplicationRef.DocNumber != "" {
        fmt.Printf("  Application: %s %s (Date: %s)\n",
            member.ApplicationRef.Country,
            member.ApplicationRef.DocNumber,
            member.ApplicationRef.Date)
    }

    for _, priority := range member.PriorityClaims {
        fmt.Printf("  Priority: %s %s (Date: %s)\n",
            priority.Country, priority.DocNumber, priority.Date)
    }
}

// Family with bibliographic data → *FamilyData
family, err := client.GetFamilyWithBiblio(ctx, "publication", "docdb", "EP.1000000.B1")

// Family with legal status → *FamilyData
family, err := client.GetFamilyWithLegal(ctx, "publication", "docdb", "EP.1000000.B1")

// Raw XML access
xmlData, err := client.GetFamilyRaw(ctx, "publication", "docdb", "EP.1000000.B1")
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 → *LegalData
legal, err := client.GetLegal(ctx, "publication", "docdb", "EP.1000000.B1")
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Patent: %s\n", legal.PatentNumber)
fmt.Printf("Legal Events: %d\n", len(legal.LegalEvents))

for _, event := range legal.LegalEvents {
    fmt.Printf("Event: %s (Code: %s, Country: %s)\n", event.Date, event.EventCode, event.Country)
    if event.Description != "" {
        fmt.Printf("  Description: %s\n", event.Description)
    }
}

// Raw XML access
xmlData, err := client.GetLegalRaw(ctx, "publication", "docdb", "EP.1000000.B1")

// Register events → *RegisterEventsData
regEvents, err := client.GetRegisterEvents(ctx, "publication", "epodoc", "EP1000000")
for _, event := range regEvents.Events {
    fmt.Printf("%s: %s (%s)\n", event.Date, event.Description, event.Category)
}

// EPO Register bibliographic data (returns raw XML)
registerBiblio, err := client.GetRegisterBiblioRaw(ctx, "publication", "epodoc", "EP1000000")
Number Conversion
// Convert patent number formats
converted, err := client.ConvertPatentNumber(ctx, "publication", "docdb", "EP.1000000.B1", "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", "EP.1000000.B1")
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.

Part of the patent.dev open-source patent data ecosystem:

  • uspto-odp - USPTO Open Data Portal client (search, PTAB, XML full text)
  • epo-bdds - EPO Bulk Data Distribution Service client
  • dpma-connect-plus - DPMA Connect Plus client (patents, designs, trademarks)

The bulk-file-loader uses these libraries for automated patent data downloads.

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 NormalizeToDocdb 

func NormalizeToDocdb(number string) (string, error)

NormalizeToDocdb converts a patent number to DOCDB format (CC.number.KC).

This function accepts patent numbers in various formats and normalizes them to the DOCDB format required by most EPO OPS API endpoints.

Supported input formats:

  • EPODOC format: "EP1000000B1", "US5551212A", "WO2023123456A1"
  • DOCDB format: "EP.1000000.B1" (returns unchanged if valid)
  • With spaces: "EP 1000000 B1" (spaces removed before processing)

Examples:

  • "EP2884620A2" → "EP.2884620.A2"
  • "EP.2884620.A2" → "EP.2884620.A2" (already DOCDB)
  • "US5551212A" → "US.5551212.A"
  • "EP 1000000 B1" → "EP.1000000.B1"

Returns an error if:

  • The input is empty
  • The input cannot be parsed as a valid patent number
  • The input is in DOCDB format but invalid

func ValidateBulkNumbers added in v1.0.0 

func ValidateBulkNumbers(numbers []string, format string) error

ValidateBulkNumbers validates a slice of patent numbers for bulk operations. This helper reduces code duplication across GetXMultiple methods.

Parameters:

  • numbers: Slice of patent numbers to validate
  • format: Number format (e.g., FormatDocDB, FormatEPODOC)

Returns error if:

  • numbers slice is empty
  • numbers slice has more than 100 entries
  • any individual number fails format validation

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 (kind code optional)

Examples of valid docdb format:

  • EP.1000000.B1
  • US.5551212.A
  • WO.2023123456.A1
  • US.7654321. (without kind code)

Format rules:

  • Two-letter country code in uppercase
  • Dot separator
  • Numeric document number
  • Dot separator
  • Optional 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 ApplicationReference added in v1.0.0 

type ApplicationReference struct {
	Country   string
	DocNumber string
	Kind      string
	Date      string
	DocID     string
}

ApplicationReference represents the application reference for a family member

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 ClassificationChild added in v1.0.0 

type ClassificationChild struct {
	Symbol string
	Title  string
	Level  int
}

ClassificationChild represents a child classification item

type ClassificationData added in v1.0.0 

type ClassificationData struct {
	Symbol     string
	Title      string
	Level      int
	SchemeType string
	Children   []ClassificationChild
	Ancestors  []ClassificationChild
}

ClassificationData represents parsed CPC classification schema data

func ParseClassificationSchema added in v1.0.0 

func ParseClassificationSchema(xmlData string) (*ClassificationData, error)

ParseClassificationSchema parses EPO classification schema XML into a ClassificationData struct.

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) (*NumberConversionData, error)

ConvertPatentNumber converts a patent number between formats and returns parsed data.

Parameters:

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

Returns parsed NumberConversionData with Country, DocNumber, Kind, and Date fields.

func (*Client) ConvertPatentNumberMultipleRaw added in v1.0.0 

func (c *Client) ConvertPatentNumberMultipleRaw(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) ConvertPatentNumberRaw added in v1.0.0 

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

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 string containing abstracts for all requested patents.

Note: Returns raw XML. See GetBiblioMultiple() documentation for notes on return type inconsistency.

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) 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 string containing bibliographic data for all requested patents.

Note: This method returns raw XML instead of parsed structs for historical reasons. Some *Multiple() methods return parsed structs (GetDescriptionMultiple, GetFulltextMultiple) while others return XML (GetBiblioMultiple, GetClaimsMultiple, GetAbstractMultiple). This inconsistency is technical debt to be addressed in a future major version. For now, callers can parse the XML using ParseBiblio() if needed.

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

Note: Returns raw XML. See GetBiblioMultiple() documentation for notes on return type inconsistency.

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) GetClassificationMappingRaw added in v1.0.0 

func (c *Client) GetClassificationMappingRaw(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) (*ClassificationData, error)

GetClassificationSchema retrieves and parses CPC classification schema hierarchy.

Parameters:

  • class: CPC classification symbol (e.g., "A01B", "H04W84/18")
  • ancestors: If true, include ancestor classifications in the hierarchy
  • navigation: If true, include navigation links to related classifications

Returns parsed ClassificationData with Symbol, Title, Level, SchemeType, and Children.

func (*Client) GetClassificationSchemaMultipleRaw added in v1.0.0 

func (c *Client) GetClassificationSchemaMultipleRaw(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) GetClassificationSchemaRaw added in v1.0.0 

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

GetClassificationSchemaRaw retrieves CPC classification schema hierarchy as raw XML.

Parameters:

  • class: CPC classification symbol (e.g., "A01B", "H04W84/18")
  • ancestors: If true, include ancestor classifications in the hierarchy
  • navigation: If true, include navigation links to related classifications

Returns raw XML response.

func (*Client) GetClassificationSchemaSubclassRaw added in v1.0.0 

func (c *Client) GetClassificationSchemaSubclassRaw(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) GetClassificationStatisticsRaw added in v1.0.0 

func (c *Client) GetClassificationStatisticsRaw(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) (*DescriptionData, 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) (*DescriptionData, error)

GetDescriptionMultiple retrieves descriptions for multiple patents (bulk operation).

Parameters:

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

Returns parsed description data including paragraphs for all requested patents.

func (*Client) GetDescriptionRaw added in v1.0.0 

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

GetDescriptionRaw retrieves patent description as raw XML. For parsed data, use GetDescription() instead.

func (*Client) GetFamily 

func (c *Client) GetFamily(ctx context.Context, refType, format, number string) (*FamilyData, 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 parsed family data containing all family members with their bibliographic details.

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

func (*Client) GetFamilyRaw added in v1.0.0 

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

GetFamilyRaw retrieves the INPADOC patent family as raw XML. For parsed data, use GetFamily() instead.

func (*Client) GetFamilyWithBiblio 

func (c *Client) GetFamilyWithBiblio(ctx context.Context, refType, format, number string) (*FamilyData, 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 parsed family data with bibliographic details for all family members.

func (*Client) GetFamilyWithBiblioMultiple 

func (c *Client) GetFamilyWithBiblioMultiple(ctx context.Context, refType, format string, numbers []string) (*FamilyData, 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 parsed family data with bibliographic details for all requested patents.

func (*Client) GetFamilyWithLegal 

func (c *Client) GetFamilyWithLegal(ctx context.Context, refType, format, number string) (*FamilyData, 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 parsed family data with legal status events for all family members.

func (*Client) GetFamilyWithLegalMultiple 

func (c *Client) GetFamilyWithLegalMultiple(ctx context.Context, refType, format string, numbers []string) (*FamilyData, 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 parsed family data with legal status events 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) (*FulltextData, 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 parsed fulltext data including biblio, abstract, description, and claims.

func (*Client) GetFulltextMultiple 

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

GetFulltextMultiple retrieves fulltext data for multiple patents (bulk operation).

Parameters:

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

Returns parsed fulltext data including biblio, abstract, description, and claims for all requested patents.

func (*Client) GetFulltextRaw added in v1.0.0 

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

GetFulltextRaw retrieves full text as raw XML. For parsed data, use GetFulltext() instead.

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 image formats are available (TIFF, PDF, PNG)
  • Document types (Drawing, FullDocument, FirstPageClipping)

Parameters:

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

Returns an ImageInquiry struct with available image metadata.

Example: 

inquiry, err := client.GetImageInquiry(ctx, ops.RefTypePublication, "docdb", "EP1000000")
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

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

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) (*LegalData, error)

Legal and Register Services - Legal status and EPO Register data.

This file contains methods for retrieving legal status events and EPO Register information.

func (*Client) GetLegalMultiple 

func (c *Client) GetLegalMultiple(ctx context.Context, refType, format string, numbers []string) (*LegalData, 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 parsed legal status data for all requested patents.

func (*Client) GetLegalRaw added in v1.0.0 

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

GetLegalRaw retrieves legal status data as raw XML. For parsed data, use GetLegal() instead.

func (*Client) GetPublishedEquivalents 

func (c *Client) GetPublishedEquivalents(ctx context.Context, refType, format, number string) (*EquivalentsData, 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) (*EquivalentsData, 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 parsed equivalents data for all requested patents.

func (*Client) GetPublishedEquivalentsRaw added in v1.0.0 

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

GetPublishedEquivalentsRaw retrieves equivalent publications as raw XML. For parsed data, use GetPublishedEquivalents() instead.

func (*Client) GetRegisterBiblioMultipleRaw added in v1.0.0 

func (c *Client) GetRegisterBiblioMultipleRaw(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) GetRegisterBiblioRaw added in v1.0.0 

func (c *Client) GetRegisterBiblioRaw(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) GetRegisterEvents 

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

GetRegisterEvents retrieves and parses procedural events from the EPO Register. Returns a parsed RegisterEventsData struct with patent statuses and dossier events.

func (*Client) GetRegisterEventsMultipleRaw added in v1.0.0 

func (c *Client) GetRegisterEventsMultipleRaw(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) GetRegisterEventsRaw added in v1.0.0 

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

GetRegisterEventsRaw retrieves procedural events from the EPO Register as raw XML.

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.

func (*Client) GetRegisterProceduralStepsMultipleRaw added in v1.0.0 

func (c *Client) GetRegisterProceduralStepsMultipleRaw(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) GetRegisterProceduralStepsRaw added in v1.0.0 

func (c *Client) GetRegisterProceduralStepsRaw(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) GetRegisterUNIPMultipleRaw added in v1.0.0 

func (c *Client) GetRegisterUNIPMultipleRaw(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) GetRegisterUNIPRaw added in v1.0.0 

func (c *Client) GetRegisterUNIPRaw(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) 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) (*SearchResultData, 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) SearchRaw added in v1.0.0 

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

SearchRaw performs a bibliographic search and returns raw XML. For parsed data, use Search() instead.

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) (*SearchResultData, 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 parsed search results 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 DataValidationError added in v1.0.0 

type DataValidationError struct {
	Parser       string // e.g., "ParseFamily", "ParseLegal"
	MissingField string // Name of the missing or invalid field
	Message      string // Description of what's wrong
}

DataValidationError represents an error when parsed data is incomplete or invalid. This occurs when XML unmarshaling succeeds but the resulting data structure is missing required fields or contains invalid values.

func (*DataValidationError) Error added in v1.0.0 

func (e *DataValidationError) Error() string

type DescriptionData added in v1.0.0 

type DescriptionData struct {
	XMLName      xml.Name `xml:"world-patent-data"`
	PatentNumber string
	Country      string
	DocNumber    string
	Kind         string
	Language     string
	Paragraphs   []Paragraph
}

DescriptionData represents parsed description data

func ParseDescription added in v1.0.0 

func ParseDescription(xmlData string) (*DescriptionData, error)

ParseDescription parses description XML into structured data

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 EquivalentPatent added in v1.0.0 

type EquivalentPatent struct {
	Country   string
	DocNumber string
	Kind      string
}

EquivalentPatent represents an equivalent patent

type EquivalentsData added in v1.0.0 

type EquivalentsData struct {
	XMLName      xml.Name `xml:"world-patent-data"`
	PatentNumber string
	Equivalents  []EquivalentPatent
}

EquivalentsData represents published equivalents inquiry results

func ParseEquivalents added in v1.0.0 

func ParseEquivalents(xmlData string) (*EquivalentsData, error)

ParseEquivalents parses equivalents inquiry XML into structured data

type FamilyData added in v1.0.0 

type FamilyData struct {
	XMLName      xml.Name `xml:"world-patent-data"`
	PatentNumber string
	FamilyID     string
	TotalCount   int
	Legal        bool
	Countries    []string // Unique country codes from all members, sorted alphabetically
	Members      []FamilyMember
}

FamilyData represents parsed patent family data

func ParseFamily added in v1.0.0 

func ParseFamily(xmlData string) (*FamilyData, error)

ParseFamily parses patent family XML into structured data

type FamilyMember added in v1.0.0 

type FamilyMember struct {
	FamilyID       string
	Country        string
	DocNumber      string
	Kind           string
	Date           string
	Title          string   // Invention title (populated from biblio data, English preferred)
	Applicants     []string // Applicant names (populated from biblio data, epodoc format)
	ApplicationRef ApplicationReference
	PriorityClaims []PriorityClaim
}

FamilyMember represents a single member of a patent family

type FulltextData added in v1.0.0 

type FulltextData struct {
	XMLName     xml.Name `xml:"world-patent-data"`
	Country     string
	DocNumber   string
	Kind        string
	Language    string
	Status      string
	Biblio      *BiblioData
	Abstract    *AbstractData
	Description *DescriptionData
	Claims      *ClaimsData
}

FulltextData represents complete fulltext document data

func ParseFulltext added in v1.0.0 

func ParseFulltext(xmlData string) (*FulltextData, error)

ParseFulltext parses fulltext XML into structured data by reusing existing parsers

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 LegalData added in v1.0.0 

type LegalData struct {
	XMLName      xml.Name `xml:"world-patent-data"`
	PatentNumber string
	FamilyID     string
	LegalEvents  []LegalEvent
}

LegalData represents parsed legal event data

func ParseLegal added in v1.0.0 

func ParseLegal(xmlData string) (*LegalData, error)

ParseLegal parses legal event XML into structured data

type LegalEvent added in v1.0.0 

type LegalEvent struct {
	Code        string
	Description string
	Influence   string
	DateMigr    string
	Country     string            // Country code from L001EP field
	Date        string            // Gazette date from L007EP field
	EventCode   string            // Legal event code from L008EP field
	Fields      map[string]string // All L-code field values
}

LegalEvent represents a single legal event

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 NumberConversionData added in v1.0.0 

type NumberConversionData struct {
	InputFormat  string
	OutputFormat string
	Country      string
	DocNumber    string
	Kind         string
	Date         string
}

NumberConversionData represents parsed patent number conversion data

func ParseNumberConversion added in v1.0.0 

func ParseNumberConversion(xmlData string) (*NumberConversionData, error)

ParseNumberConversion parses EPO number conversion XML into a NumberConversionData struct.

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 Paragraph added in v1.0.0 

type Paragraph struct {
	ID   string
	Num  string
	Text string
}

Paragraph represents a description paragraph

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 PatentStatus added in v1.0.0 

type PatentStatus struct {
	Date        string // Status change date (YYYYMMDD)
	Code        string // Status code (e.g., "7", "8")
	Description string // Human-readable description
}

PatentStatus represents a patent status entry from the EPO Register

type PriorityClaim added in v1.0.0 

type PriorityClaim struct {
	Country   string
	DocNumber string
	Kind      string
	Date      string
	Sequence  string
	Active    string
}

PriorityClaim represents a priority claim for a family member

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 RegisterEvent added in v1.0.0 

type RegisterEvent struct {
	ID          string // Event identifier (e.g., "EVT_434577438")
	Date        string // Event date (YYYYMMDD)
	EventCode   string // Event code (e.g., "0009250", "EPIDOSNIGR1")
	Description string // Human-readable description
	Category    string // Categorized: filing, publication, examination, grant, opposition, appeal, other
	GazetteNum  string // Gazette number (e.g., "2022/32"), empty if not available
	GazetteDate string // Gazette date (YYYYMMDD), empty if not available
}

RegisterEvent represents a single dossier event from the EPO Register

type RegisterEventsData added in v1.0.0 

type RegisterEventsData struct {
	PatentNumber string
	Query        string
	Statuses     []PatentStatus
	Events       []RegisterEvent
}

RegisterEventsData represents parsed register events data

func ParseRegisterEvents added in v1.0.0 

func ParseRegisterEvents(xmlData string) (*RegisterEventsData, error)

ParseRegisterEvents parses EPO Register events XML into a RegisterEventsData struct.

type SearchResult added in v1.0.0 

type SearchResult struct {
	System    string
	FamilyID  string
	Country   string
	DocNumber string
	Kind      string
	Title     string
}

SearchResult represents a single search result

type SearchResultData added in v1.0.0 

type SearchResultData struct {
	XMLName    xml.Name `xml:"world-patent-data"`
	Query      string
	TotalCount int
	RangeBegin int
	RangeEnd   int
	Results    []SearchResult
}

SearchResultData represents search results with pagination

func ParseSearch added in v1.0.0 

func ParseSearch(xmlData string) (*SearchResultData, error)

ParseSearch parses search result XML into structured data. Handles both formats: with constituents (exchange-documents) and without (publication-reference).

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

type XMLParseError added in v1.0.0 

type XMLParseError struct {
	Parser    string // e.g., "ParseFamily", "ParseLegal"
	Element   string // e.g., "family-member", "legal-event"
	XMLSample string // First 200 chars of problematic XML
	Cause     error  // Underlying error from xml.Unmarshal
}

XMLParseError represents an error during XML parsing. This error provides context about what failed during XML unmarshaling including the parser name, problematic element, and a sample of the XML.

func (*XMLParseError) Error added in v1.0.0 

func (e *XMLParseError) Error() string

func (*XMLParseError) Unwrap added in v1.0.0 

func (e *XMLParseError) Unwrap() error

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.