epo-ops 0.2.6 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 486c2b78a9d96a95206df411f2414bb58387f873
-  data.tar.gz: f512f54574ac9b6a98905545e24e0917ae59f333
+  metadata.gz: 598720d94ba023a3a3e6b0e2b3f4b018a7f1983e
+  data.tar.gz: d6861675f8ef8abd67a13664c881406a9a8e711a
 SHA512:
-  metadata.gz: ddca9237f9e562cd45901b8bbd4ae4b2c5b4f5fc460e6b3f4de7406415b8791ba0157e978d9b0dfb8b49803540ddd97c4042ae633058897594815570354736b9
-  data.tar.gz: 19cfcb49c74da598b5e6e8e5290e83b09e025ad253fcdbe9425b8a461a2afbfefcabbafb11e1bde971fe67e915185d4c50e7b1ee8af4593876725b3b4d98f6ba
+  metadata.gz: 31e1b55be1850539337a550d831d1b63881b4248e8456dcbc1c6a4af1b32e6e289d92a76833434038f53dc97612bf214a1680388f955d7220bee2046e423b25c
+  data.tar.gz: 50f29328406d721d8515cc0436cad653d1cf2e0fdf6f725f372b950c12401968ddaed942b1d57483ab594778b04c26533d5c3f5a8c47ba7606bd6e7240339dfb

data/.gitignore

@@ -35,3 +35,6 @@ Gemfile.lock
 
 # unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
 .rvmrc
+
+# IDEs
+/.idea/

data/.travis.yml

@@ -0,0 +1,6 @@
+language: ruby
+rvm:
+  - "2.0"
+  - "2.1"
+  - "2.2"
+  - "2.3.0"

data/README.md

@@ -4,68 +4,108 @@
 # epo-ops
 Ruby interface to the EPO Open Patent Services (OPS).
 
-[Documentation can be found here](http://www.rubydoc.info/gems/epo-ops/)
+[Full documentation can be found here](http://www.rubydoc.info/gems/epo-ops/)
+
 
-The EPO provides [playground](https://developers.epo.org/), where you can try
-out the methods. As well as [Documentation](https://www.epo.org/searching-for-patents/technical/espacenet/ops.html)
-of the different endpoints and detailed usage (see the 'Downloads' section).
 
 # Usage
 
-## Authentication
-In order to use this gem you need to register at the [EPO for
-OAuth](https://developers.epo.org/user/register).
-Use your credentials by configuring
+## Quickstart
+Simply install this gem and start a ruby console.
+```
+$ gem install epo-ops
+$ irb
+```
+
+and start querying the API
 
 ```ruby
-Epo::Ops.configure do |conf|
+require 'epo_ops'
+
+patent_application = EpoOps::PatentApplication.find("EP14731659")
+patent_application.title  # "DEVICE AND METHOD FOR INTRODUCING FIBRES INTO AN EXTRUDER"
+patent_application.classifications # ["B29C47/10", "B29C47/68", "B29C47/92", "B29C45/00", "B01D46/24"] 
+patent_application.applicants.first.name # "Fraunhofer-Gesellschaft zur Förderung der angewandten Forschung e.V."
+```
+
+## Advanced Usage
+
+### OAuth
+
+EPO offers an anonymous developer access to their API with very little quota. To get extended quotas you can register
+an account at the [EPO for OAuth](https://developers.epo.org/user/register)
+
+After your account has been approved configure your credentials
+
+```ruby
+
+EpoOps.configure do |conf|
+  conf.authentication = :oauth
   conf.consumer_key = "YOUR_KEY"
   conf.consumer_secret = "YOUR_SECRET"
 end
+
 ```
 
-## Quickstart
-### Search for Patents
+The temporary access token is kept in memory for subsequent retrievals. To share this between several processes the
+token storage strategy may be changed as shown in `epo/ops/token_store` for redis.
 
-Get references to all Patents on a given date and IPC-class:
 
-```ruby
-Epo::Ops::Register.search("A", Date.new(2016,2 ,3))
-# or for all ipc classes
-Epo::Ops::Register.search(nil, Date.new(2016,2 ,3))
-```
+### Querying and searching patent applications
 
-You can now retrieve the bibliographic entries of all these:
+Currently this gem focuses mostly around patent applications.
+It is possible to search for specific applications by application number and to search for applications using a
+CQL search query
+
+For example to find all applications in IPC Class _A01_ (and all subclasses) that were updated on 2016-01-01
 
 ```ruby
-references = Epo::Ops::Register.search(nil, Date.new(2016,2 ,3))
-references.map { |ref| Epo::Ops::Register.biblio(ref) }
+query = EpoOps::SearchQueryBuilder.build("A01", Date.parse("2016-01-02"))
+applications = EpoOps::PatentApplication.search(query)
+puts applications.count # 1234
+applications.map {|application| puts application.application_nr } # print all application numbers
+applications.map {|application| application.fetch} # fetch complete bibliographic data for each document
+
 ```
-This will return an object that helps parsing the result. See the documentation
-for more information
 
-Note that both operations take a considerable amount of time. Also you may not
-want to develop and test with many of these requests, as they can quite quickly
-excess the API limits. Also note that this methods use the `application`
-endpoint.
+The Request will return a search result containing the number of all applications matching the search. By default the
+search will return 10 documents (max is 100). You can use `start_rang` and `end_range` of `EpoOps::SearchQueryBuilder.build`
+to page through all results
+
+**Note: EPO will always only return up to 2000 documents even if the search would return more**
 
-## Custom Retrieval
 
-### #raw_search
-This allows you to build your own CQL query, as
-described in the official documentation. With the second parameter set
-to true you can get the raw result as a nested Hash, if you want to
-parse it yourself.
+### Search for all Patents on a given Date
+
+To circumvent the restriction of max 2000 search results this gem
+offers a convenient method to search for all patents updated on a given date and/or a given IPC class
 
 ```ruby
-Epo::Ops::Register.raw_search("q=pd=20160203 and ic=D&Range=1-100", true)
+EpoOps::Register.search("A", Date.new(2016,2 ,3))
+# or for all ipc classes
+EpoOps::Register.search(nil, Date.new(2016,2 ,3))
 ```
 
-### #raw_biblio
-If you do not want to retrieve via the `application` endpoint (say you want
-`publication`) this method gives you more fine-grained control. Make sure the
-`reference_id` you use matches the type.
+You can now retrieve the bibliographic entries of all these:
 
 ```ruby
-Epo::Ops::Register.raw_biblio('EP1000000', 'publication')
+references = EpoOps::Register.search(nil, Date.new(2016,2 ,3))
+references.map { |ref| EpoOps::Register.biblio(ref) }
 ```
+
+**Note: Both operations take a considerable amount of time. Also you may not
+want to develop and test with many of these requests, as they can quite quickly exceed your limits.**
+
+
+# Further Reading
+
+The EPO provides [a developer playground](https://developers.epo.org/), where you can test-drive the OPS-API.
+They also provide extensive [documentation](https://www.epo.org/searching-for-patents/technical/espacenet/ops.html)
+of the different endpoints and how to use them (see the 'Downloads' section).
+
+
+# Development
+
+This gem is still an early version and it is far from covering the whole API.
+If you are interested to include different API endpoints than the register it should be easy to include those and we
+are happy to accept pull requests.

data/epo-ops.gemspec

@@ -1,11 +1,11 @@
 # coding: utf-8
 lib = File.expand_path('../lib', __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require 'epo/ops/version'
+require 'epo_ops/version'
 
 Gem::Specification.new do |spec|
   spec.name          = 'epo-ops'
-  spec.version       = Epo::Ops::VERSION
+  spec.version       = EpoOps::VERSION
   spec.authors       = ['Max Kießling', 'Robert Terbach', 'Michael Prilop']
 
   spec.summary       = 'Ruby interface to the European Patent Office API (OPS)'

data/lib/epo_ops.rb

@@ -0,0 +1,46 @@
+require 'epo_ops/version'
+require 'epo_ops/token_store'
+require 'epo_ops/register'
+require 'epo_ops/search_query_builder'
+require 'epo_ops/ipc_class_hierarchy_loader'
+require 'epo_ops/ipc_class_util'
+require 'epo_ops/patent_application'
+require 'epo_ops/name_and_address'
+require 'epo_ops/factories'
+require 'epo_ops/register_search_result'
+
+module EpoOps
+  # Configure authentication method and credentials
+  # @example
+  #   EpoOps.configure do |conf|
+  #     conf.consumer_key = "foo"
+  #     conf.consumer_secret = "bar"
+  #     conf.token_store = EpoOps::TokenStore::Redis # (defaults to EpoOps::TokenStore)
+  #     conf.authentication :oauth # or :plain (defaults to :plain)
+  #   end
+  # @yieldparam [Configuration] configuration that is yielded.
+  def self.configure
+    yield(config)
+  end
+
+  # The {Configuration} used. You may want to call {EpoOps#configure} first.
+  # @return [Configuration] the configuration used.
+  def self.config
+    @configuration ||= Configuration.new
+  end
+
+  class Configuration
+    attr_accessor :consumer_key, :consumer_secret, :token_store, :authentication
+
+    def initialize
+      @consumer_key = ''
+      @consumer_secret = ''
+      @token_store = EpoOps::TokenStore.new
+      @authentication = :plain
+
+      OAuth2::Response.register_parser(:xml, ['application/xml']) do |body|
+        MultiXml.parse(body)
+      end
+    end
+  end
+end

data/lib/epo_ops/client.rb

@@ -0,0 +1,46 @@
+require 'epo_ops/token_store'
+require 'epo_ops/error'
+
+module EpoOps
+
+  # This is a wrapper for OAuth
+  class Client
+
+
+    # @return [OAuth2::Response]
+    # @option options [Hash] :params query parameter for the request
+    # @option options [Hash, String] :body the body of the request
+    # @option options [Hash] :headers http request headers
+    # @raise [EpoOps::Error] API Error if request was not successful
+    def self.request(verb, url, options = {})
+      response = case EpoOps.config.authentication
+                  when :oauth then do_oauth_request(verb, url, options)
+                  when :plain then do_plain_request(verb,url,options)
+                  else raise('Unknown authentication strategy!')
+                 end
+      fail Error.from_response(response) unless response.status == 200
+      response
+    rescue Error::AccessTokenExpired
+      EpoOps.config.token_store.reset
+      request(verb, url, options)
+    end
+
+    private
+
+    # Make an oauth request to the EPO API
+    # @return [OAuth2::Response]
+    def self.do_oauth_request(verb, url, options = {})
+      token = EpoOps.config.token_store.token
+      token.request(verb, URI.encode(url), options)
+    end
+
+    # Make an anonymous request to the EPO API
+    # @return [OAuth2::Response] OAuth2::Reponse is used for convenience and consistency
+    def self.do_plain_request(verb, url, options = {})
+      conn = Faraday.new("https://ops.epo.org/")
+      url = conn.build_url(url, options[:params]).to_s
+      response = conn.run_request(verb,url,options[:body], options[:header])
+      OAuth2::Response.new(response)
+    end
+  end
+end

data/lib/epo_ops/error.rb

@@ -0,0 +1,87 @@
+require 'epo_ops/rate_limit'
+
+module EpoOps
+  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)
+    # AccessToken has expired
+    AccessTokenExpired = Class.new(ClientError)
+
+    ERRORS = {
+      400 => EpoOps::Error::BadRequest,
+      401 => EpoOps::Error::Unauthorized,
+      403 => EpoOps::Error::Forbidden,
+      404 => EpoOps::Error::NotFound,
+      406 => EpoOps::Error::NotAcceptable,
+      422 => EpoOps::Error::UnprocessableEntity,
+      429 => EpoOps::Error::TooManyRequests,
+      500 => EpoOps::Error::InternalServerError,
+      502 => EpoOps::Error::BadGateway,
+      503 => EpoOps::Error::ServiceUnavailable,
+      504 => EpoOps::Error::GatewayTimeout
+    }.freeze
+    FORBIDDEN_MESSAGES = {
+      'This request has been rejected due to the violation of Fair Use policy' => EpoOps::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)
+        elsif code == 400 && response.headers['www-authenticate'] && response.headers['www-authenticate'].include?('Access Token expired')
+          Error::AccessTokenExpired.new('Access Token expired', 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

data/lib/epo_ops/factories.rb

@@ -0,0 +1,9 @@
+require 'epo_ops/factories/patent_application_factory'
+require 'epo_ops/factories/name_and_address_factory'
+require 'epo_ops/factories/register_search_result_factory'
+
+module EpoOps
+  module Factories
+
+  end
+end

data/lib/epo_ops/factories/name_and_address_factory.rb

@@ -0,0 +1,54 @@
+module EpoOps
+  module Factories
+    # Parses the addressbook data from EPO Ops into an 'NameAndAddress' object
+    class NameAndAddressFactory
+      class << self
+
+        # @param raw_data [Hash] raw addressbook data as retrieved included in Epo Ops biblio data
+        # @return [EpoOps::NameAndAddress] NameAndAddress filled with parsed data
+        def build(raw_data)
+          factory = new(raw_data)
+
+          EpoOps::NameAndAddress.new(
+              factory.name,
+              factory.address_1,
+              factory.address_2,
+              factory.address_3,
+              factory.address_4,
+              factory.address_5,
+              factory.country_code,
+              factory.cdsid
+          )
+        end
+      end
+
+      attr_reader :raw_data,
+                  :name,
+                  :address_1,
+                  :address_2,
+                  :address_3,
+                  :address_4,
+                  :address_5,
+                  :country_code,
+                  :cdsid
+
+
+      def initialize(raw_data)
+        @raw_data = raw_data
+
+        @name         = raw_data['name']
+
+        if raw_data['address'].is_a? Hash
+          @address_1    = raw_data['address']['address_1']
+          @address_2    = raw_data['address']['address_2']
+          @address_3    = raw_data['address']['address_3']
+          @address_4    = raw_data['address']['address_4']
+          @address_5    = raw_data['address']['address_5']
+          @country_code = raw_data['address']['country']
+        end
+
+        @cdsid        = raw_data['cdsid']
+      end
+    end
+  end
+end

data/lib/epo_ops/factories/patent_application_factory.rb

@@ -0,0 +1,116 @@
+module EpoOps
+  module Factories
+    # Parses the patent application data from EPO Ops into an PatentApplication object
+    class PatentApplicationFactory
+      class << self
+
+        # @param raw_data [Hash] raw application data as retrieved from Epo Ops
+        # @return [EpoOps::PatentApplication] PatentApplication filled with parsed data
+        def build(raw_data)
+          factory = new(raw_data)
+
+          EpoOps::PatentApplication.new(
+            factory.application_number,
+
+            raw_data: raw_data,
+            title: factory.title,
+            status: factory.status,
+            agents: factory.agents,
+            applicants: factory.applicants,
+            inventors: factory.inventors,
+            classifications: factory.classifications,
+            priority_claims: factory.priority_claims,
+            publication_references: factory.publication_references,
+            effective_date: factory.effective_date
+          )
+        end
+      end
+
+      attr_reader :raw_data
+
+      def initialize(raw_data)
+        @raw_data = raw_data
+      end
+
+      # @return [String] Application Number
+      # @see EpoOps::PatentApplication#application_nr
+      def application_number
+        document_id = EpoOps::Util.flat_dig raw_data, data_path('application_reference', 'document_id')
+        document_id = document_id.first if document_id.is_a?(Array)
+
+        "#{document_id['country']}#{document_id['doc_number']}"
+      end
+
+      # @return [Hash] List of titles in different languages
+      # @see EpoOps::PatentApplication#title
+      def title
+        titles = EpoOps::Util.flat_dig raw_data, data_path('invention_title')
+        titles.inject({}) do |hash, title|
+          hash[title['lang']] = title['__content__'] if title.is_a? Hash
+          hash
+        end
+      end
+
+      # @return [Array] List of {EpoOps::NameAndAddress}
+      # @see EpoOps::PatentApplication#agents
+      def agents
+        EpoOps::Util.flat_dig(raw_data, data_path('parties', 'agents', 'agent', 'addressbook')).map do |agent|
+          EpoOps::Factories::NameAndAddressFactory.build(agent)
+        end
+      end
+
+      # @return [Array] List of {EpoOps::NameAndAddress}
+      # @see EpoOps::PatentApplication#applicants
+      def applicants
+        EpoOps::Util.flat_dig(raw_data, data_path('parties', 'applicants', 'applicant', 'addressbook')).map do |applicant|
+          EpoOps::Factories::NameAndAddressFactory.build(applicant)
+        end
+      end
+
+      # @return [Array] List of {EpoOps::NameAndAddress}
+      # @see EpoOps::PatentApplication#inventors
+      def inventors
+        EpoOps::Util.flat_dig(raw_data, data_path('parties', 'inventors', 'inventor', 'addressbook')).map do |inventor|
+          EpoOps::Factories::NameAndAddressFactory.build(inventor)
+        end
+      end
+
+      # @return [Array] List of IPC classes
+      # @see EpoOps::PatentApplication#classifications
+      def classifications
+        EpoOps::Util.dig(raw_data, data_path('classifications_ipcr', 'classification_ipcr', 'text')).split(",").map(&:strip)
+      end
+
+      # @return [String] Application status as described by EPO
+      # @see EpoOps::PatentApplication#status
+      def status
+        EpoOps::Util.dig raw_data, data_path('status')
+      end
+
+      # @return [Array] Hashes of priority claims
+      # @see EpoOps::PatentApplication#priority_claims
+      def priority_claims
+        EpoOps::Util.flat_dig raw_data, data_path('priority_claims','priority_claim')
+      end
+
+      # @return [Array]
+      # @see EpoOps::PatentApplication#publication_references
+      def publication_references
+        EpoOps::Util.flat_dig raw_data, data_path('publication_reference', 'document_id')
+      end
+
+      # @return [Date]
+      # @see EpoOps::PatentApplication#effective_date
+      def effective_date
+        dates = EpoOps::Util.flat_dig raw_data, data_path('dates_rights_effective', 'request_for_examination')
+        dates.first.nil? ? nil : dates.first['date']
+      end
+
+      private
+        def data_path(*path)
+          %w(bibliographic_data) + path
+        end
+
+    end
+  end
+end