epo-ops 0.1.5

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 7fdce426fc2fbb64f5f6c91f76f9892a0d9bcd59
+  data.tar.gz: ccc3a3ddd81354d151da39a4b37d01916fede709
+SHA512:
+  metadata.gz: ef5f5150ab3eea7bb22675946a1f7c21c4fed46dcba1be39b187f633fe77a756aa261d4bc37a03e59b627005106a00450471da97b7eec5769c0435ed1ca13251
+  data.tar.gz: fb9e7f249f6330083d95ab565b2bb2824ea45f220b257fb52741ee76a0dc0165d493388ef2bfb29142e0c1aa4b0e45b76a59d726d96b1120cef49e8b29b6aceb

data/.gitignore

@@ -0,0 +1,37 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/test/epo_credentials.yml
+/tmp/
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalization:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+Gemfile.lock
+# .ruby-version
+# .ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc

data/.travis.yml

@@ -0,0 +1,5 @@
+language: ruby
+rvm:
+  - "2.0.0"
+  - "2.1.0"
+  - "2.2.0"

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in epo-ops.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 FHG-IMW
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,34 @@
+[![Build Status](https://travis-ci.org/FHG-IMW/epo-ops.svg?branch=master)](https://travis-ci.org/FHG-IMW/epo-ops)
+[![Code Climate](https://codeclimate.com/github/FHG-IMW/epo-ops/badges/gpa.svg)](https://codeclimate.com/github/FHG-IMW/epo-ops)
+
+# epo-ops
+Ruby interface to the EPO Open Patent Services (OPS).
+
+You can play around with the API [here](https://developers.epo.org/).
+Documentation of it can be found [here](https://www.epo.org/searching-for-patents/technical/espacenet/ops.html) under `Downloads`.
+
+# Usage
+
+## Authentification
+In order to use this gem you need to register at the EPO for OAuth
+[here](https://developers.epo.org/user/register).
+Use your credentials by configuring
+```ruby
+Epo::Ops.configure do |conf|
+  conf.consumer_key = "YOUR_KEY"
+  conf.consumer_secret = "YOUR_SECRET"
+end
+```
+
+## What works up to now
+* Search the EPO OPS register with `Epo::Ops::Register.search(query)`; use `Epo::Ops::SearchQueryBuilder` to build an appropriate request.
+* Get bibliographic info from the register, both for application and publication references (which you may retrieve with the search).
+* Bulk searching for all patents on a given date wih `Epo::Ops::Register::Bulk.all_queries(date)`. Note that patents are usually published on Wednesdays, if you find some on another weekday, please let us know.
+   This method currently returns all queries necessary to find all patents with `Epo::Ops::Register.search`
+
+### #search
+Use the `SearchQueryBuilder` to set up the queries. By default structs are returned that should make it easier to work with the results, but with the `raw`-flag set to true you may also retrieve the resulting hash and parse it yourself.
+The results have the method `#epodoc_reference` which perfectly fits into `#biblio`
+
+### #biblio
+With `Epo::Ops::Register.biblio(reference_id)` you can retrieve the bibliographic entry for the given patent (see OPS documentation). By default it searches the `/application/` endpoint, but you may set `publication` as the second parameter. Make sure the `reference_id` matches the given type. The last optional parameter allows you to set another format the id, but the default `epodoc` is strongly advised. This format is also provided from search results with `#epodoc_reference`.

data/Rakefile

@@ -0,0 +1,10 @@
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+task default: :test

data/epo-ops.gemspec

@@ -0,0 +1,29 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'epo/ops/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'epo-ops'
+  spec.version       = Epo::Ops::VERSION
+  spec.authors       = ['Max Kießling', 'Robert Terbach', 'Michael Prilop']
+
+  spec.summary       = 'Ruby interface to the European Patent Office API (OPS)'
+  spec.description   = 'This gem allows simple access to the European Patent'\
+    ' Offices (EPO) Open Patent Services (OPS) using their XML-API'
+  spec.homepage      = 'https://github.com/FHG-IMW/epo-ops'
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'bundler', '~> 1.3'
+  spec.add_development_dependency 'rake', '~> 10.5'
+  spec.add_development_dependency 'minitest', '~> 5.8'
+  spec.add_development_dependency 'vcr', '~> 2.9'
+  spec.add_development_dependency 'webmock', '~> 1.22'
+  spec.add_development_dependency 'simplecov'
+
+  spec.add_dependency 'oauth2', '~> 1.1'
+end

data/lib/epo/ops.rb

@@ -0,0 +1,41 @@
+require 'epo/ops/version'
+require 'epo/ops/token_store'
+require 'epo/ops/register'
+require 'epo/ops/search_query_builder'
+
+module Epo
+  module Ops
+    # Configure your OAuth credentials to use with this gem.
+    # @example
+    #   Epo:Ops.configure do |conf|
+    #     conf.consumer_key = "foo"
+    #     conf.consumer_secret = "bar"
+    #   end
+    # Optional parameter:
+    # conf.token_store (defaults to {Epo::Ops::TokenStore})
+    # @yieldparam [Configuration] configuration that is yielded.
+    def self.configure
+      yield(config)
+    end
+
+    # The {Configuration} used. You may want to call {Epo::Ops#configure} first.
+    # @return [Configuration] the configuration used.
+    def self.config
+      @configuration ||= Configuration.new
+    end
+
+    class Configuration
+      attr_accessor :consumer_key, :consumer_secret, :token_store
+
+      def initialize
+        @consumer_key = ''
+        @consumer_secret = ''
+        @token_store = Epo::Ops::TokenStore.new
+
+        OAuth2::Response.register_parser(:xml, ['application/xml']) do |body|
+          MultiXml.parse(body)
+        end
+      end
+    end
+  end
+end

data/lib/epo/ops/address.rb

@@ -0,0 +1,60 @@
+module Epo
+  module Ops
+    # Used to represent persons or companies (or both) in patents. Used for
+    # both, agents and applicants. Most of the time, when `name` is a person
+    # name, `address1` is a company name. Be aware that the addresses are in
+    # their respective local format.
+    #
+    # Current patents usually at least use the fields address1-3, so they should
+    # nearly always have values. Nevertheless, older ones often only use 1-2.
+    # Note also that EPOs schema documents fields like `street` or `city`, but
+    # by now they have not been used yet.
+    #
+    # @attr [String] name the name of an entity (one or more persons or
+    #   companies)
+    # @attr [String] address1 first address line. May also be a company name
+    # @attr [String] address2 second address line
+    # @attr [String] address3 third address line, may be empty
+    # @attr [String] address4 fourth address line, may be empty
+    # @attr [String] address5 fifth address line, may be empty
+    # @attr [String] country_code two letter country code of the address
+    # @attr [Date] occurred_on the date an address occurred on, usually matching
+    #   the entries change_gazette_num
+    # @attr [String] cdsid some kind of id the EPO provides, not sure yet if
+    #   usable as reference.
+    class Address
+      attr_reader :name, :address1,
+                  :address2,
+                  :address3,
+                  :address4,
+                  :address5,
+                  :country_code,
+                  :occurred_on,
+                  :cdsid
+      def initialize(name, address1, address2, address3, address4,
+                     address5, country_code, occurred_on,
+                     cdsid)
+        @address1 = address1
+        @address2 = address2
+        @address3 = address3 || ''
+        @address4 = address4 || ''
+        @address5 = address5 || ''
+        @name = name
+        @country_code = country_code || ''
+        @occurred_on = occurred_on || ''
+        @cdsid = cdsid || ''
+      end
+
+      # Compare addresses by the name and address fields.
+      # @return [Boolean]
+      def equal_name_and_address?(other)
+        name == other.name &&
+          address1 == other.address1 &&
+          address2 == other.address2 &&
+          address3 == other.address3 &&
+          address4 == other.address4 &&
+          address5 == other.address5
+      end
+    end
+  end
+end

data/lib/epo/ops/bibliographic_document.rb

@@ -0,0 +1,196 @@
+require 'epo/ops/address'
+
+module Epo
+  module Ops
+    # Parses and simplifies the elements the EPO OPS returns for bibliographic
+    # documents. Parsing is done lazily.
+    # Some elements are not yet fully parsed but hashes returned instead.
+    # Not all information available is parsed (e.g. inventors), if you need
+    # more fields, add them here.
+    class BibliographicDocument
+      # @return [Hash] a nested Hash, which is a parsed XML response of the
+      #   `/biblio` endpoint of the EPO APIs.
+      # @see Client
+      attr_reader :raw
+
+      def initialize(raw)
+        @raw = raw
+      end
+
+      # A number by which a patent is uniquely identifiable and querieable.
+      # The first two letters are the country code of the processing patent
+      # office, for european patents this is EP.
+      # @return [String] application number.
+      def application_nr
+        @application_nr ||= parse_application_nr
+      end
+
+      # @return [String] The URL at which you can query the original document.
+      def url
+        @url ||= "https://ops.epo.org/3.1/rest-services/register/application/epodoc/#{application_nr}"
+      end
+
+      # @return [String] the english title of the patent @note Titles are
+      #   usually available at least in english, french and german.
+      #   Other languages are also possible.
+      def title
+        @title ||= parse_title
+      end
+
+      # @return [Array] a list of the IPC-Classifications, as strings.
+      #   Format is set by EPO, should be similar to: E06B7/23
+      def classifications
+        @classifications ||= parse_classification raw
+      end
+
+      # Agents and applicants are subject to change at EPO, often
+      # their names or addresses are updated, sometimes other
+      # people/companies appear or disappear.
+      #
+      # @return [Array] Array of {Address}
+      def agents
+        @agents ||= parse_agents raw
+      end
+
+      # (see #agents)
+      def applicants
+        @applicants ||= parse_applicants raw
+      end
+
+      # @return [String] the string representation of the current patent status as
+      #   described by the EPO
+      def status
+        @status ||= parse_status raw
+      end
+
+      # Many fields of the XML the EPO provides have a field
+      # `change_gazette_num`.  It is a commercial date (year + week)
+      # that describes in which week the element has been
+      # changed. This method parses them and returns the most recent
+      # date found.
+      # @return [Date] the latest date found in the document.
+      def latest_update
+        @latest ||= parse_latest_update raw
+      end
+
+      # The priority date describes the first document that was filed at any
+      # patent office in the world regarding this patent.
+      # @return [Hash] a hash which descibes the filed priority with the fields:
+      #   `country` `doc_number`, `date`, `kind`, and `sequence`
+      def priority_date
+        @priority_date ||= parse_priority_date raw
+      end
+
+      # @return [Array] List of hashes containing information about publications
+      #   made, entries exist for multiple types of publications, e.g. A1, B1.
+      def publication_references
+        @publication_dates ||= parse_publication_references raw
+      end
+
+      def effective_date
+        @effective_date ||= parse_effective_date raw
+      end
+
+      private
+
+      def parse_title
+        titles = Util.find_in_data(raw,
+                                   path_to_bibliographic_data +
+                                   ['invention_title'])
+        titles.each do |the_title|
+          return the_title['__content__'] if the_title['lang'] == 'en'
+        end
+        # no english title found
+        titles.first['__content__']
+      end
+
+      def parse_application_nr
+        path = %w(world_patent_data register_search query __content__)
+        Util.find_in_data(raw, path).first.partition('=').last
+      end
+
+      def parse_priority_date(raw)
+        priority_claims = Util.find_in_data(raw,
+                                            path_to_bibliographic_data +
+                                            %w(priority_claims))
+                          .first
+        if priority_claims.nil?
+          priority_date = nil
+        else
+          priority_date = priority_claims['priority_claim'].is_a?(Hash) ? priority_claims['priority_claim'] : priority_claims['priority_claim'].first
+        end
+        priority_date
+      end
+
+      def parse_publication_references(raw)
+        Util.parse_hash_flat(
+          Util.find_in_data(raw,
+                            path_to_bibliographic_data +
+                            %w(publication_reference)), 'document_id')
+      end
+
+      def parse_effective_date(raw)
+        effective_date =
+          Util.find_in_data(raw,
+                            path_to_bibliographic_data +
+                            %w(dates_rights_effective request_for_examination))
+        effective_date.first.nil? ? nil : effective_date.first['date']
+      end
+
+      def parse_latest_update(raw)
+        gazette_nums = Util.parse_hash_flat(raw, 'change_gazette_num')
+        nums = gazette_nums.map { |num| Util.parse_change_gazette_num(num) }.keep_if { |match| !match.nil? }
+        nums.max
+      end
+
+      def parse_status(raw)
+        Util.find_in_data(raw,
+                          path_to_bibliographic_data + ['status'])
+          .first
+      end
+
+      def parse_classification(raw)
+        Util.find_in_data(raw,
+                          path_to_bibliographic_data +
+                          %w(classifications_ipcr classification_ipcr text))
+          .first.split(',').map(&:strip)
+      end
+
+      def parse_agents(raw)
+        entries = Util.find_in_data(raw,
+                                    path_to_bibliographic_data +
+                                    %w(parties agents))
+        parse_address(entries, 'agent')
+      end
+
+      def parse_applicants(raw)
+        entries = Util.find_in_data(raw,
+                                    path_to_bibliographic_data +
+                                    %w(parties applicants))
+        parse_address(entries, 'applicant')
+      end
+
+      def parse_address(party_group_entries, group)
+        party_group_entries.flat_map do |entry|
+          change_date = Util.parse_change_gazette_num(
+            entry.fetch('change_gazette_num', '')) || latest_update
+          Util.find_in_data(entry, [group, 'addressbook']).map do |address|
+            Address.new(address['name'],
+                        address['address']['address_1'],
+                        address['address']['address_2'],
+                        address['address']['address_3'],
+                        address['address']['address_4'],
+                        address['address']['address_5'],
+                        address['address']['country'],
+                        change_date,
+                        address['cdsid'])
+          end
+        end
+      end
+
+      def path_to_bibliographic_data
+        %w(world_patent_data register_search register_documents register_document bibliographic_data)
+      end
+    end
+  end
+end

data/lib/epo/ops/client.rb

@@ -0,0 +1,16 @@
+require 'epo/ops/token_store'
+require 'epo/ops/error'
+
+module Epo
+  module Ops
+    class Client
+      # @return [OAuth2::Response]
+      def self.request(verb, url, options = {})
+        token = Epo::Ops.config.token_store.token
+        response = token.request(verb, URI.encode(url), options)
+        fail Error.from_response(response) unless response.status == 200
+        response
+      end
+    end
+  end
+end

data/lib/epo/ops/error.rb

@@ -0,0 +1,85 @@
+require 'epo/ops/rate_limit'
+
+module Epo
+  module Ops
+    class Error < StandardError
+      # @return [Integer]
+      attr_reader :code, :rate_limit
+
+      # Raised when EPO returns a 4xx HTTP status code
+      ClientError = Class.new(self)
+      # Raised when EPO returns the HTTP status code 400
+      BadRequest = Class.new(ClientError)
+      # Raised when EPO returns the HTTP status code 401
+      Unauthorized = Class.new(ClientError)
+      # Raised when EPO returns the HTTP status code 403
+      Forbidden = Class.new(ClientError)
+      # Raised when EPO returns the HTTP status code 404
+      NotFound = Class.new(ClientError)
+      # Raised when EPO returns the HTTP status code 406
+      NotAcceptable = Class.new(ClientError)
+      # Raised when EPO returns the HTTP status code 422
+      UnprocessableEntity = Class.new(ClientError)
+      # Raised when EPO returns the HTTP status code 429
+      TooManyRequests = Class.new(ClientError)
+      # Raised when EPO returns a 5xx HTTP status code
+      ServerError = Class.new(self)
+      # Raised when EPO returns the HTTP status code 500
+      InternalServerError = Class.new(ServerError)
+      # Raised when EPO returns the HTTP status code 502
+      BadGateway = Class.new(ServerError)
+      # Raised when EPO returns the HTTP status code 503
+      ServiceUnavailable = Class.new(ServerError)
+      # Raised when EPO returns the HTTP status code 504
+      GatewayTimeout = Class.new(ServerError)
+
+      ERRORS = {
+        400 => Epo::Ops::Error::BadRequest,
+        401 => Epo::Ops::Error::Unauthorized,
+        403 => Epo::Ops::Error::Forbidden,
+        404 => Epo::Ops::Error::NotFound,
+        406 => Epo::Ops::Error::NotAcceptable,
+        422 => Epo::Ops::Error::UnprocessableEntity,
+        429 => Epo::Ops::Error::TooManyRequests,
+        500 => Epo::Ops::Error::InternalServerError,
+        502 => Epo::Ops::Error::BadGateway,
+        503 => Epo::Ops::Error::ServiceUnavailable,
+        504 => Epo::Ops::Error::GatewayTimeout
+      }.freeze
+      FORBIDDEN_MESSAGES = {
+        'This request has been rejected due to the violation of Fair Use policy' => Epo::Ops::Error::TooManyRequests
+      }.freeze
+
+      class << self
+        # Parses an error from the given response
+        # @return [Error]
+        def from_response(response)
+          code = response.status
+          message = parse_error(response.parsed)
+
+          if code == 403 && FORBIDDEN_MESSAGES[message]
+            FORBIDDEN_MESSAGES[message].new(message, response.headers, code)
+          else
+            ERRORS[code].new(message, response.headers, code)
+          end
+        end
+
+        private
+
+        def parse_error(body)
+          if body.nil? || body.empty?
+            nil
+          elsif body['error'] && body['error']['message']
+            body['error']['message']
+          end
+        end
+      end
+
+      def initialize(message = '', rate_limit = {}, code = nil)
+        super(message)
+        @code = code
+        @rate_limit = RateLimit.new(rate_limit)
+      end
+    end
+  end
+end

data/lib/epo/ops/limits.rb

@@ -0,0 +1,22 @@
+module Epo
+  module Ops
+    # The register search is limited by some parameters. With one
+    # query one may only request as many as
+    # {Epo::Ops::Limits::MAX_QUERY_INTERVAL} references at once.
+    # Considering this, you have to split your requests by this
+    # interval.  Nevertheless, the maximum value you may use is
+    # {Epo::Ops::Limits::MAX_QUERY_RANGE}. If you want to retrieve more
+    # references you must split by other parameters.
+    # @see Register
+    class Limits
+      # @return [Integer] The range in which you can search is limited, say you
+      #   cannot request all patents of a given class at once, you probably must
+      #   split your requests by additional conditions.
+      MAX_QUERY_RANGE = 2000
+
+      # @return [Integer] The maximum number of elements you may search with one
+      #   query. Ignoring this will result in errors.
+      MAX_QUERY_INTERVAL = 100
+    end
+  end
+end

data/lib/epo/ops/logger.rb

@@ -0,0 +1,11 @@
+module Epo
+  module Ops
+    # Simple logger writing some notifications to standard output.
+    class Logger
+      # Just hands the parameter to puts.
+      def self.log(output)
+        puts output
+      end
+    end
+  end
+end

data/lib/epo/ops/rate_limit.rb

@@ -0,0 +1,49 @@
+module Epo
+  module Ops
+    class RateLimit
+      WEEKLY_QUOTA_RESET_TIME = 604_800
+      HOURLY_QUOTA_RESET_TIME = 600
+      BASE_RESET_TIME = 60
+
+      attr_reader :attr
+
+      def initialize(http_header)
+        fail "Rate Limit data should be a Hash but is #{http_header.inspect} (#{http_header.class.name})" unless http_header.is_a?(Hash)
+        @attr = http_header
+      end
+
+      def limit_reached?
+        @attr.key?('x-rejection-reason')
+      end
+
+      def rejection_reason
+        return nil unless @attr['x-rejection-reason']
+        case @attr['x-rejection-reason']
+        when 'RegisteredQuotaPerWeek' then :weekly_quota
+        when 'IndividualQuotaPerHour' then :hourly_quota
+        else :unknown_reason
+        end
+      end
+
+      def hourly_quota
+        quota = @attr['x-individualquotaperhour-used']
+        quota.to_i if quota
+      end
+
+      def weekly_quota
+        quota = @attr['x-registeredquotaperweek-used']
+        quota.to_i if quota
+      end
+
+      def reset_at
+        return unless limit_reached?
+
+        case rejection_reason
+        when :weekly_quota then Time.now.to_i + WEEKLY_QUOTA_RESET_TIME
+        when :hourly_quota then Time.now.to_i + HOURLY_QUOTA_RESET_TIME
+        else Time.now.to_i + BASE_RESET_TIME
+        end
+      end
+    end
+  end
+end

data/lib/epo/ops/register.rb

@@ -0,0 +1,177 @@
+require 'epo/ops'
+require 'epo/ops/client'
+require 'epo/ops/util'
+require 'epo/ops/bibliographic_document'
+require 'epo/ops/logger'
+
+module Epo
+  module Ops
+    # Access to the {http://ops.epo.org/3.1/rest-services/register register}
+    # endpoint of the EPO OPS API.
+    #
+    # By now you can search and retrieve patents by using the type `application`
+    # in the `epodoc` format.
+    #
+    # Search queries are limited by size, not following these limits
+    # will result in errors.
+    #
+    # @see Limits
+    # @see SearchQueryBuilder
+    class Register
+      # Helper class that assists in building the queries necessary to search
+      # for more patents than possible with one query respecting the given
+      # limits.
+      #
+      # @see Limits
+      class Bulk
+        # Helper method returning all unique register references on a given
+        # date. This is the same as executing all queries from {.all_queries}
+        # and making the results unique.
+        #
+        # @note Patents may have more than one IPC class, they would appear
+        #   more than once, this method filters these by `doc_number`
+        def self.all_register_references(date)
+          begin
+            queries = Bulk.all_queries(date)
+            search_entries = queries.flat_map do |query|
+              Register.search(query)
+            end
+          rescue ::Epo::Ops::Error::NotFound
+            return []
+          end
+          search_entries.map(&:application_reference)
+            .uniq(&:doc_number)
+        end
+
+        # Build the queries to search for all patents on a given date.
+        #
+        # The offset of EPOs register search may at max be 2000, if more patents
+        # are published on one day the queries must be split; here across the
+        # first level of ipc classification.
+        # At time of this writing they are mostly below 1000, there should be
+        # plenty of space for now.
+        #
+        # In case the limits change, they can be found in {Epo::Ops::Limits}
+        # Should there be more than 2000 patents in one class, a message will
+        # be logged, please file an Issue if that happens.
+        #
+        # @return [Array] containing all queries to put into {Register.search}.
+        # @note The queries are split by IPC-classes if necessary; Patents may
+        #   have more than one, you might get multiple references to the same
+        #   patent.
+        # @see .all_register_references
+        def self.all_queries(date)
+          overall_count = published_patents_count(date)
+          if overall_count > Limits::MAX_QUERY_RANGE
+            patent_count_by_ipc_classes(date).flat_map do |ipc_class, count|
+              builder = SearchQueryBuilder.new
+                        .publication_date(date.year, date.month, date.day)
+                        .and
+                        .ipc_class(ipc_class)
+              split_by_size_limits(builder, count)
+            end
+          else
+            builder = SearchQueryBuilder.new
+                      .publication_date(date.year, date.month, date.day)
+            split_by_size_limits(builder, overall_count)
+          end
+        end
+
+        # @return [Hash] For all top level IPC classes (A-H) => count
+        def self.patent_count_by_ipc_classes(date)
+          ipc_classes = %w(A B C D E F G H)
+          ipc_classes.inject({}) do |mem, ipcc|
+            mem[ipcc] = published_patents_count(date, ipcc)
+            if mem[ipcc] > Limits::MAX_QUERY_RANGE
+              Logger.log("IPC class #{ipcc} has more than #{Epo::Ops::Limits::MAX_QUERY_RANGE} on #{date}. They can not all be retrieved. Please file this as an issue!")
+            end
+            mem
+          end
+        end
+
+        # Splits the queries build by `query_builder` by the allowed intervals.
+        #
+        # @param query_builder [SearchQueryBuilder] with all settings made, but
+        #   not built yet.
+        # @param patent_count [Integer] number of overall results expected.
+        #   See {.published_patents_count}
+        #
+        # @return [Array] of Strings, each a query to put into {Register.search}
+        def self.split_by_size_limits(query_builder, patent_count)
+          max_interval = Limits::MAX_QUERY_INTERVAL
+          (1..patent_count).step(max_interval).map do |start|
+            query_builder.build(start, [start + max_interval - 1, patent_count].min)
+          end
+        end
+
+        # makes a minimum request to find out how many patents are published on
+        # that date
+        #
+        # @return [Integer] number of patents on that date.
+        def self.published_patents_count(date, ipc_class = nil)
+          query = SearchQueryBuilder.new
+          query.publication_date(date.year, date.month, date.day)
+          query.and.ipc_class(ipc_class) if ipc_class
+          query = query.build(1, 2)
+          minimum_result_set = Register.search(query, true)
+          return 0 if minimum_result_set.empty?
+          minimum_result_set['world_patent_data']['register_search']['total_result_count'].to_i
+        end
+      end
+
+      # @param query A query built with {Epo::Ops::SearchQueryBuilder}
+      # @param raw if `true` the result will be the raw response as a nested hash.
+      # if false(default) the result will be parsed further, returning a list of [SearchEntry]
+      # @return [Array] containing {SearchEntry}
+      def self.search(query, raw = false)
+        hash = Client.request(:get, register_api_string + query).parsed
+        return parse_search_results(hash) unless raw
+        hash
+      end
+
+      # @param format epodoc is a format defined by the EPO for a
+      #   document id. see their documentation.
+      # @param type may be `application` or `publication` make sure that the
+      #   `reference_id` is matching
+      # @param raw flag if the result should be returned as a raw Hash or
+      #   parsed as {BibliographicDocument}
+      # @return [BibliographicDocument, Hash]
+      def self.biblio(reference_id, type = 'application', format = 'epodoc', raw = false)
+        request = "#{register_api_string}#{type}/#{format}/#{reference_id}/biblio"
+        result = Client.request(:get, request).parsed
+        raw ? result : BibliographicDocument.new(result)
+      end
+
+      Reference = Struct.new(:country, :doc_number, :date) do
+        def epodoc_reference
+          country + doc_number
+        end
+      end
+
+      SearchEntry = Struct.new(:publication_reference, :application_reference, :ipc_classes)
+
+      private
+
+      def self.parse_search_results(result)
+        path = %w(world_patent_data register_search register_documents register_document bibliographic_data)
+
+        list = Util.find_in_data(result, path)
+        list.map do |entry|
+          publication_reference = Reference.new(
+            entry['publication_reference']['document_id']['country'],
+            entry['publication_reference']['document_id']['doc_number'],
+            entry['publication_reference']['document_id']['date'])
+          application_reference = Reference.new(
+            entry['application_reference']['document_id']['country'],
+            entry['application_reference']['document_id']['doc_number'])
+          ipc_classes = entry['classifications_ipcr']['classification_ipcr']['text'].split(';;').map(&:strip)
+          SearchEntry.new(publication_reference, application_reference, ipc_classes)
+        end
+      end
+
+      def self.register_api_string
+        '/3.1/rest-services/register/'
+      end
+    end
+  end
+end

data/lib/epo/ops/search_query_builder.rb

@@ -0,0 +1,70 @@
+require 'epo/ops/limits'
+require 'epo/ops/logger'
+
+module Epo
+  module Ops
+    # This Builder helps creating a search query using
+    # {https://www.loc.gov/standards/sru/cql/ CQL} (Common Query Language or
+    # Contextual Query Language) with the identifies specified by the EPO in
+    # the OPS Documentation chapter 4.2 ( {https://www.epo.org/searching-for-patents/technical/espacenet/ops.html Link}
+    # - use tab Downloads and see file 'OPS version 3.1 documentation').
+    # Dont use a builder twice ;)
+    class SearchQueryBuilder
+      def initialize
+        @query = 'search?q='
+      end
+
+      def publication_date(year, month, day)
+        @query << "pd=#{('%04d' % year) << ('%02d' % month) << ('%02d' % day)}"
+        self
+      end
+
+      def and
+        @query << ' and '
+        self
+      end
+
+      def ipc_class(ipc_class)
+        @query << "ic=#{ipc_class}"
+        # TODO: ipc_class richtig formatieren
+        self
+      end
+
+      # builds the search query ready to put into the register API. The
+      # parameters are validated with {#validate_range}.
+      # This does not change the query, several calls will allow you to
+      # create the same queries for different ranges.
+      def build(range_start = 1, range_end = nil)
+        range_end ||= range_start + Limits::MAX_QUERY_INTERVAL - 1
+        validated_range = validate_range range_start, range_end
+        @query + "&Range=#{validated_range[0]}-#{validated_range[1]}"
+      end
+
+      # Fixes the range given so that they meed the EPO APIs rules. The range
+      #  may only be 100 elements long, the maximum allowed value is 2000.
+      # If the given window is out of range, it will be moved preserving the
+      # distance covered.
+      # @see Epo::Ops::Limits
+      # @return array with two elements: [range_start, range_end]
+      def validate_range(range_start, range_end)
+        if range_start > range_end
+          range_start, range_end = range_end, range_start
+          Logger.log('range_start was bigger than range_end, swapped values')
+        elsif range_start == range_end || range_end - range_start > Limits::MAX_QUERY_INTERVAL - 1
+          range_end = range_start + Limits::MAX_QUERY_INTERVAL - 1
+          Logger.log("range invalid, set to: #{[range_start, range_end]}")
+        end
+        if range_start < 1
+          range_end = range_end - range_start + 1
+          range_start = 1
+          Logger.log("range_start must be > 0, set to: #{[range_start, range_end]}")
+        elsif range_end > Limits::MAX_QUERY_RANGE
+          range_start = Limits::MAX_QUERY_RANGE - (range_end - range_start)
+          range_end = Limits::MAX_QUERY_RANGE
+          Logger.log("range_end was too big, set to: #{[range_start, range_end]}")
+        end
+        [range_start, range_end]
+      end
+    end
+  end
+end

data/lib/epo/ops/token_store.rb

@@ -0,0 +1,29 @@
+require 'oauth2'
+require 'epo/ops'
+
+module Epo
+  module Ops
+    # This class saves the token in memory, you may want to subclass this and
+    # overwrite #token if you want to store it somewhere else.
+    #
+    class TokenStore
+      def token
+        return generate_token if !@token || @token.expired?
+        @token
+      end
+
+      protected
+
+      def generate_token
+        client = OAuth2::Client.new(
+          Epo::Ops.config.consumer_key,
+          Epo::Ops.config.consumer_secret,
+          site: 'https://ops.epo.org/',
+          token_url: '/3.1/auth/accesstoken',
+          raise_errors: false
+        )
+        @token = client.client_credentials.get_token
+      end
+    end
+  end
+end

data/lib/epo/ops/token_store/redis.rb

@@ -0,0 +1,35 @@
+require 'redis'
+require 'connection_pool'
+
+module Epo
+  module Ops
+    class TokenStore
+      class Redis < TokenStore
+        def initialize(redis_host)
+          fail "Please install gems 'redis' and 'connection_pool' to use this feature" unless defined?(::Redis) && defined?(ConnectionPool)
+
+          @redis = ConnectionPool.new(size: 5, timeout: 5) { ::Redis.new(host: redis_host) }
+        end
+
+        def token
+          token = nil
+          @redis.conn do |conn|
+            token = conn.get("epo_token_#{id}")
+          end
+
+          token.present? ? OAuth2::AccessToken.new(client, token) : generate_token
+        end
+
+        private
+
+        def generate_token
+          super
+          Sidekiq.redis do |conn|
+            conn.set("epo_token_#{id}", token.token, ex: token.expires_in, nx: true)
+          end
+          token
+        end
+      end
+    end
+  end
+end

data/lib/epo/ops/util.rb

@@ -0,0 +1,32 @@
+module Epo
+  module Ops
+    class Util
+      # the path should be an array of strings indicating the path you want to go in the hash
+      def self.find_in_data(epo_hash, path)
+        path.reduce(epo_hash) { |res, c| parse_hash_flat(res, c) }
+      end
+
+      def self.parse_hash_flat(hash_layer, target)
+        result = []
+        if hash_layer.nil?
+          return []
+        elsif hash_layer.class == String
+          return []
+        elsif hash_layer.class == Array
+          result.concat(hash_layer.map { |x| parse_hash_flat(x, target) })
+        elsif hash_layer[target]
+          result << hash_layer[target]
+        elsif hash_layer.class == Hash || hash_layer.respond_to?(:to_h)
+          result.concat(hash_layer.to_h.map { |_x, y| parse_hash_flat(y, target) })
+        end
+        result.flatten
+      end
+
+      def self.parse_change_gazette_num(num)
+        res = /^(?<year>\d{4})\/(?<week>\d{2})$/.match(num)
+        return nil if res.nil?
+        Date.commercial(Integer(res[:year], 10), week = Integer(res[:week], 10))
+      end
+    end
+  end
+end

data/lib/epo/ops/version.rb

@@ -0,0 +1,5 @@
+module Epo
+  module Ops
+    VERSION = '0.1.5'.freeze
+  end
+end

metadata

@@ -0,0 +1,164 @@
+--- !ruby/object:Gem::Specification
+name: epo-ops
+version: !ruby/object:Gem::Version
+  version: 0.1.5
+platform: ruby
+authors:
+- Max Kießling
+- Robert Terbach
+- Michael Prilop
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2016-03-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '10.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '10.5'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '5.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '5.8'
+- !ruby/object:Gem::Dependency
+  name: vcr
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.9'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.22'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: oauth2
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.1'
+description: This gem allows simple access to the European Patent Offices (EPO) Open
+  Patent Services (OPS) using their XML-API
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .travis.yml
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- epo-ops.gemspec
+- lib/epo/ops.rb
+- lib/epo/ops/address.rb
+- lib/epo/ops/bibliographic_document.rb
+- lib/epo/ops/client.rb
+- lib/epo/ops/error.rb
+- lib/epo/ops/limits.rb
+- lib/epo/ops/logger.rb
+- lib/epo/ops/rate_limit.rb
+- lib/epo/ops/register.rb
+- lib/epo/ops/search_query_builder.rb
+- lib/epo/ops/token_store.rb
+- lib/epo/ops/token_store/redis.rb
+- lib/epo/ops/util.rb
+- lib/epo/ops/version.rb
+homepage: https://github.com/FHG-IMW/epo-ops
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.6
+signing_key: 
+specification_version: 4
+summary: Ruby interface to the European Patent Office API (OPS)
+test_files: []