Firmenwissen

A ruby gem to conveniently access the Firmenwissen Smart Sign-Up API.

Installation

Add this line to your application's Gemfile:

gem 'firmenwissen'

And then execute:

$ bundle

Or install it yourself as:

$ gem install firmenwissen

Usage

Searching

response = Firmenwissen.search('company xyz')

if response.successful?
  suggestions = response.suggestions
  ...
end

will give you an array of suggestions from Firmenwissen, if any, for the specified query string.

suggestion = suggestions.first

suggestion.crefo_id # => '1234567890'
suggestion.name # => 'COMPEON GmbH'
suggestion.trade_name # => 'Compeon'
suggestion.country # => 'DE'
suggestion.state # => 'Nordrhein-Westfalen'
suggestion.zip_code # => '40211'
suggestion.city # => 'Düsseldorf'
suggestion.address # => 'Louise-Dumon-Straße 5'

suggestion.to_h # => { crefo_id: '1234567890', name: 'COMPEON GmbH', ... }

Basic Auth Configuration

Firmenwissen.configure do |config|
  config.authentication_strategy = 'basic' # This is set to 'basic' by default, eliminating the need for explicit configuration.
  config.user     = 'username'      # Username for Firmenwissen basic auth (required)
  config.password = 'password'      # Password for Firmenwissen basic auth (required)
  config.timeout  = 5               # Request timeout in seconds
  config.persistent_session = false # Whether to store/use session information for subsequent requests

  # Configure the endpoint yourself. %s will be replaced by the actual query
  config.endpoint = 'https://example.com/search?query={query}'
end

Api Key Configuration

Firmenwissen.configure do |config|
  config.authentication_strategy = 'api_key' # Mandatory for all options except 'basic' (required)
  config.api_key  = 'your api key'  # API Key for Firmenwissen API Key authentication (required)
  config.timeout  = 5               # Request timeout in seconds
  config.persistent_session = false # Whether to store/use session information for subsequent requests

  # Configure the endpoint yourself. %s will be replaced by the actual query
  config.endpoint = 'https://example.com/search?query={query}'
end

Mocking results

In a non production-like environment you will not want to perform real requests to the API. Thus you can configure the gem to respond with mocked data.

Firmenwissen.configure do |config|
  config.mock_requests = true

  # respond with a fixed array
  config.mock_data = [{ crefo_id: '1111111111', name: 'Test GmbH', ... }, { ... }, ...]

  # respond when a query matches an exact keyword
  # this will return a result mock when you search for 'compeon' or 'test', otherwise an empty result
  mock_data = {
    'compeon' => [{ crefo_id: '1234567890', name: 'COMPEON GmbH', ... }],
    'test' => [{ crefo_id: '1111111111', ... }]
  }

  config.mock_data = mock_data

  # generate your own dynamic response
  config.mock_data = Proc.new do |query|
    # your code for mock data generation here
  end

  # or

  class DynamicMockData
    def call(query)
      # your code for mock data generation here
    end
  end

  config.mock_data = DynamicMockData.new
end

Note: All configuration options can be overridden on a per-request basis by passing an options hash to the search method.

On sessions

Session information is stored globally and used for all subsequent requests made via the Firmenwissen gem if persistent_session is active.

License

The gem is available as open source under the terms of the MIT License.