bdds

EPO BDDS Go Client

A Go client for the European Patent Office's Bulk Data Distribution Service (BDDS) REST API - product discovery, delivery listing, and downloading of bulk datasets such as DOCDB, INPADOC, and EP full-text.

Overview

• Product discovery - list products, fetch a product with its deliveries, look up a product by name, get the latest delivery.
• File downloads - stream a delivery file to any io.Writer, with an optional progress callback for large files.
• Automatic auth - OAuth2 password grant; tokens are cached and refreshed before expiry. Credentials are optional: free/public products work without them.
• Robust requests - retry with backoff and automatic re-authentication on expiry; typed errors for the common failure cases.

Installation

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

Getting access

Free/public BDDS products can be listed and downloaded without an account. Paid products require an EPO account with a subscription to the relevant product; the client then authenticates via OAuth2 password grant.

1. Open the BDDS portal to browse the product catalogue, then start sign-in / registration.

2. Sign in with your EPO account, or create one at the EPO login.

3. Subscribe to the products you need (free/public products need no subscription).

4. Export your EPO credentials for the client and demo:

   export EPO_BDDS_USERNAME=...
   export EPO_BDDS_PASSWORD=...
   

Quick start

package main

import (
    "context"
    "fmt"
    "log"

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

func main() {
    // Credentials are optional: free/public products (including ListProducts)
    // work without them. Pass a Config with Username/Password for paid products.
    client, err := bdds.NewClient(nil)
    if err != nil {
        log.Fatal(err)
    }

    products, err := client.ListProducts(context.Background())
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Found %d products\n", len(products))
    for _, p := range products {
        fmt.Printf("- [%d] %s\n", p.ID, p.Name)
    }
}

Usage

Configuration

config := &bdds.Config{
    Username:   "your-username",                          // optional, needed for paid products
    Password:   "your-password",                          // optional, needed for paid products
    BaseURL:    "https://publication-bdds.apps.epo.org",  // default
    UserAgent:  "YourApp/1.0",                            // optional
    MaxRetries: 3,                                        // default: 3
    RetryDelay: time.Second,                              // delay between retries, default: 1s
    Timeout:    30 * time.Second,                         // request timeout, default: 30s
}

client, err := bdds.NewClient(config)

RetryDelay and Timeout are time.Duration values.

Product discovery

// List all available products.
products, err := client.ListProducts(ctx)

// Get a product with its deliveries.
product, err := client.GetProduct(ctx, 3) // EP DocDB front file

// Find a product by name.
product, err := client.GetProductByName(ctx, "EP DocDB front file")

// Get the most recent delivery for a product.
delivery, err := client.GetLatestDelivery(ctx, 3)

GetProduct returns a *ProductWithDeliveries; each delivery lists its files:

for _, d := range product.Deliveries {
    fmt.Printf("%s - %d files\n", d.DeliveryName, len(d.Files))
}

File downloads

If you already have the product, delivery, and file IDs, downloads work without credentials:

f, err := os.Create("download.zip")
if err != nil {
    log.Fatal(err)
}
defer f.Close()

err = client.DownloadFile(ctx, productID, deliveryID, fileID, f)

Use DownloadFileWithProgress for a progress callback on large files:

err = client.DownloadFileWithProgress(ctx, 3, 12345, 67890, f,
    func(bytesWritten, totalBytes int64) {
        fmt.Printf("\rProgress: %.1f%%", float64(bytesWritten)*100/float64(totalBytes))
    })

Common product IDs

Demo

An interactive demo exercises every method. Set credentials and run it:

export EPO_BDDS_USERNAME=your-username
export EPO_BDDS_PASSWORD=your-password
cd demo && go run demo.go

See demo/README.md for details.

Error handling

The library returns typed errors you can match with errors.As:

var authErr *bdds.AuthError
if errors.As(err, &authErr) {
    fmt.Printf("auth failed (status %d): %s\n", authErr.StatusCode, authErr.Message)
}

var notFound *bdds.NotFoundError
if errors.As(err, &notFound) {
    fmt.Printf("%s not found: %s\n", notFound.Resource, notFound.ID)
}

var rateLimit *bdds.RateLimitError
if errors.As(err, &rateLimit) {
    fmt.Printf("rate limited, retry after %d seconds\n", rateLimit.RetryAfter)
}

Testing

make test              # unit tests (mock HTTP server, race)
make test-integration  # integration tests against the real API, needs credentials
make lint

Integration tests require valid EPO BDDS credentials and skip gracefully when they are not set or a product is not accessible for your account:

export EPO_BDDS_USERNAME=your-username
export EPO_BDDS_PASSWORD=your-password

Regenerating from OpenAPI

The typed code under generated/ is produced from the hand-crafted openapi.yaml with oapi-codegen. If you change the spec, regenerate it:

make generate

Related projects

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

• epo-ops - EPO Open Patent Services client (bibliographic, full text, families, legal status, images)
• uspto-odp - USPTO Open Data Portal client (patents, PTAB, TSDR, full text)
• dpma-connect-plus - DPMA Connect Plus client (patents, designs, trademarks)

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

License

MIT - Funktionslust GmbH / patent.dev.