hawatel_search_jobs 0.1.0

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 2.2.1
+before_install: gem install bundler -v 1.10.6

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,13 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, or religion.
+
+Examples of unacceptable behavior by participants include the use of sexual language or imagery, derogatory comments or personal attacks, trolling, public or private harassment, insults, or other unprofessional conduct.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct. Project maintainers who do not follow the Code of Conduct may be removed from the project team.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers.
+
+This Code of Conduct is adapted from the [Contributor Covenant](http://contributor-covenant.org), version 1.0.0, available at [http://contributor-covenant.org/version/1/0/0/](http://contributor-covenant.org/version/1/0/0/)

data/CONTRIBUTING.md

@@ -0,0 +1,70 @@
+# Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/Hawatel/hawatel_search_jobs. This project is intended to be a safe, welcoming space for collaboration, and contributors.
+
+1. [Fork](https://help.github.com/articles/fork-a-repo/) the project, clone your fork,
+   and configure the remotes:
+
+   ```sh
+   # Clone your fork of the repo into the current directory
+   git clone https://github.com/<your-username>/hawatel_ps
+   # Navigate to the newly cloned directory
+   cd hawatel_search_jobs
+   # Assign the original repo to a remote called "upstream"
+   git remote add upstream https://github.com/Hawatel/hawatel_search_jobs
+   ```
+
+2. If you cloned a while ago, get the latest changes from upstream:
+
+   ```bash
+   git checkout master
+   git pull upstream master
+   ```
+
+3. Create a new topic branch (off of `master`) to contain your feature, change,
+   or fix.
+
+   **IMPORTANT**: Making changes in `master` is discouraged. You should always
+   keep your local `master` in sync with upstream `master` and make your
+   changes in topic branches.
+
+   ```sh
+   git checkout -b <topic-branch-name>
+   ```
+
+4. Commit your changes in logical chunks. Keep your commit messages organized,
+   with a short description in the first line and more detailed information on
+   the following lines. Feel free to use Git's
+   [interactive rebase](https://help.github.com/articles/about-git-rebase/)
+   feature to tidy up your commits before making them public.
+
+5. Make sure all the tests are still passing.
+
+   ```sh
+   rake
+   ```
+
+6. Push your topic branch up to your fork:
+
+   ```sh
+   git push origin <topic-branch-name>
+   ```
+
+7. [Open a Pull Request](https://help.github.com/articles/using-pull-requests/)
+    with a clear title and description.
+
+8. If you haven't updated your pull request for a while, you should consider
+   rebasing on master and resolving any conflicts.
+
+   **IMPORTANT**: _Never ever_ merge upstream `master` into your branches. You
+   should always `git rebase` on `master` to bring your changes up to date when
+   necessary.
+
+   ```sh
+   git checkout master
+   git pull upstream master
+   git checkout <your-topic-branch>
+   git rebase master
+   ```
+
+Thank you for your contributions!

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Daniel Iwaniuk
+
+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,146 @@
+# Hawatel Search Jobs
+
+Hawatel_job_search, it is gem which provides ease access to API from popular job websites to get current job offers. At this moment, supported backends are indeed.com, careerjet.com,  xing.com, careerbuilder.com and reed.co.uk.
+
+Before you can start using the gem, you need have an accounts/tokens for each portal where is required by API.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'hawatel_search_jobs'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install hawatel_search_jobs
+
+## Usage
+
+#### How to configure access to search engine APIs
+```ruby
+HawatelSearchJobs.configure do |config|
+  config.indeed[:activated] = true
+  config.indeed[:api]       = 'api.indeed.com'
+  config.indeed[:version]   = '2'
+  config.indeed[:publisher] = 'secret-key'
+
+  config.xing[:activated]           = true
+  config.xing[:consumer_key]        = 'secret-key'
+  config.xing[:consumer_secret]     = 'secret-key'
+  config.xing[:oauth_token]         = 'secret-key'
+  config.xing[:oauth_token_secret]  = 'secret-key'
+
+  config.reed[:activated] = true
+  config.reed[:api]       = 'reed.co.uk/api'
+  config.reed[:clientid]  = 'secret-key'
+  config.reed[:version]   = '1.0'
+
+  config.careerbuilder[:activated]  = true
+  config.careerbuilder[:api]        = 'api.careerbuilder.com'
+  config.careerbuilder[:clientid]   = 'secret-key'
+  config.careerbuilder[:version]    = 'v2'
+
+  config.careerjet[:activated]   = true
+  config.careerjet[:api]         = 'public.api.careerjet.net'
+end
+```
+
+#### Where to get a secret-key
+ 1. Indeed: http://www.indeed.com/jsp/apiinfo.jsp
+ 2. Xing: https://dev.xing.com
+ 3. Reed: https://www.reed.co.uk/developers/jobseeker
+ 4. Careerbuilder: http://developer.careerbuilder.com
+ 5. Careerjet: secret-key is no needed (http://www.careerjet.com/partners/api/)
+
+#### Get first page of job offers
+There are two ways to read the returned job offers.
+
+1. Returned job offers by search_jobs method:
+```ruby
+  client = HawatelSearchJobs::Client.new
+  result = client.search_jobs({:keywords => 'ruby'})
+    p result[:indeed]
+    p result[:xing]
+    p result[:reed]
+    p result[:careerbuilder]
+    p result[:careerjet]
+```
+
+2. Access to the instance variable jobs_table.
+Instance variable *jobs_table* always has last returned job offers.
+```ruby
+  client = HawatelSearchJobs::Client.new
+  client.search_jobs({:keywords => 'ruby'})
+  p client.jobs_table
+```
+
+Keep in mind that each API has a limit of returned records. For consistency, each API returns maximum `25` records.
+
+#### Get next page of job offers
+```ruby
+  client = HawatelSearchJobs::Client.new
+  client.search_jobs({:keywords => 'ruby'})
+  p client.next
+```
+
+#### Get all pages of job offers
+```ruby
+  client = HawatelSearchJobs::Client.new
+  client.search_jobs({:keywords => 'ruby'})
+  
+  job_offers = Array.new
+  
+  while(client.next) do
+    job_offers << client.jobs_table
+  end
+```
+Keep in mind if keywords will be too general probably each API will return loads of data and then a daily limit for each API provider can be exceeded.
+Reed about your daily limit for each API on the provider side.
+
+#### How many job offers were found
+```ruby
+  client = HawatelSearchJobs::Client.new
+  client.search_jobs({:keywords => 'ruby'})
+  p client.count # for all APIs
+  p client.count('indeed') # for a particular API
+```
+Keep in mind the `client.count` returns count of total results for each APIs which can be returned to you if you will use `client.next` method.
+
+## Structure of job offers table
+Below is an example for indeed but each of APIs has the same result structure.
+```ruby
+  client = HawatelSearchJobs::Client.new
+  client.search_jobs({:keywords => 'ruby'})
+  result = client.jobs_table
+  
+  result[:indeed][:code]            # HTTP status code (see https://en.wikipedia.org/wiki/List_of_HTTP_status_codes)
+  result[:indeed][:message]         # HTTP message (seee https://en.wikipedia.org/wiki/List_of_HTTP_status_codes)
+  
+  result[:indeed][:totalResults]    # Total results of job offers which matches to your search criteria on API provider
+  result[:indeed][:page]            # Current results page number counted from index 0
+  result[:indeed][:last]            # Last results page number
+  result[:indeed][:key]             # Internal key which usuely keep last URL sent to API or last used keywords
+  
+  result[:indeed][:jobs]            # OpenStruct array which store returned job offers from API provider
+  result[:indeed][:jobs].jobtitle   # Job title
+  result[:indeed][:jobs].location   # Job location
+  result[:indeed][:jobs].company    # Company name which posted the job
+  result[:indeed][:jobs].date       # Date of the posted job (format %d/%m/%y)
+  result[:indeed][:jobs].url        # Source URL to the job offer
+```
+
+## Contributing
+
+See [CONTRIBUTING](CONTRIBUTING.md)
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/hawatel_search_jobs.gemspec

@@ -0,0 +1,30 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'hawatel_search_jobs/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "hawatel_search_jobs"
+  spec.version       = HawatelSearchJobs::VERSION
+  spec.authors       = ['Przemyslaw Mantaj','Daniel Iwaniuk']
+  spec.email         = ['przemyslaw.mantaj@hawatel.com', 'daniel.iwaniuk@hawatel.com']
+
+  spec.summary       = %q{Hawatel_job_search, it is gem which provides ease access to API from popular job websites to get current job offers.}
+  spec.description   = %q{Hawatel_job_search, it is gem which provides ease access to API from popular job websites
+                         to get current job offers.  At this moment, supported backends are indeed.com, careerjet.com,
+                         xing.com, careerbuilder.com and reed.com.}
+  spec.homepage      = "http://github.com/Hawatel/hawatel_search_jobs"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_runtime_dependency 'xing_api'
+  spec.add_runtime_dependency 'activesupport'
+
+  spec.add_development_dependency "bundler", "~> 1.10"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec"
+end

data/lib/hawatel_search_jobs.rb

@@ -0,0 +1,64 @@
+##
+# = Hawatel Search Jobs
+# More details how to use it was described here {HawatelSearchJobs::Client}
+module HawatelSearchJobs
+  require 'hawatel_search_jobs/helpers'
+  require 'hawatel_search_jobs/api'
+  require 'hawatel_search_jobs/client'
+
+  class << self
+    attr_accessor :indeed, :xing, :reed, :careerbuilder, :careerjet
+
+    ##
+    # How to configure APIs go to example {HawatelSearchJobs::Client#search_jobs}
+    def configure
+      @indeed         = default_indeed(Hash.new)
+      @xing           = default_xing(Hash.new)
+      @reed           = default_reed(Hash.new)
+      @careerbuilder  = default_careerbuilder(Hash.new)
+      @careerjet      = default_careerjet(Hash.new)
+      yield self
+      true
+    end
+
+    private
+
+    def default_xing(settings)
+      settings[:activated]          = false
+      settings[:consumer_key]       = ''
+      settings[:consumer_secret]    = ''
+      settings[:oauth_token]        = ''
+      settings[:oauth_token_secret] = ''
+      return settings
+    end
+
+    def default_indeed(settings)
+      settings[:activated]  = false
+      settings[:api]        = 'api.indeed.com'
+      settings[:version]    = '2'
+      settings[:publisher]  = ''
+      return settings
+    end
+
+    def default_careerjet(settings)
+      settings[:activated]  = false
+      settings[:api]        = 'public.api.careerjet.net'
+      return settings
+    end
+
+    def default_reed(settings)
+      settings[:activated]  = false
+      settings[:api]        = 'reed.co.uk/api'
+      settings[:version]    = '1.0'
+      return settings
+    end
+
+    def default_careerbuilder(settings)
+      settings[:activated]  = false
+      settings[:api]        = 'api.careerbuilder.com'
+      settings[:version]    = 'v2'
+      return settings
+    end
+  end
+
+end

data/lib/hawatel_search_jobs/api.rb

@@ -0,0 +1,9 @@
+module HawatelSearchJobs
+  module Api
+    require 'hawatel_search_jobs/api/indeed'
+    require 'hawatel_search_jobs/api/reed'
+    require 'hawatel_search_jobs/api/xing'
+    require 'hawatel_search_jobs/api/careerbuilder'
+    require 'hawatel_search_jobs/api/careerjet'
+  end
+end

data/lib/hawatel_search_jobs/api/careerbuilder.rb

@@ -0,0 +1,170 @@
+require 'ostruct'
+require 'active_support/core_ext/hash'
+
+module HawatelSearchJobs
+  module Api
+    ##
+    # = Carerrbuilder API
+    #
+    # @see 	http://api.careerbuilder.com/Search/jobsearch/jobsearchinfo.aspx
+    module Careerbuilder
+      class << self
+        include HawatelSearchJobs::Helpers::Base
+
+        DEFAULT = {
+            :keywords => '',
+            :location => '',
+            :company  => ''
+        }
+
+        RESULT_LIMIT = 25
+
+        # Search jobs by specific criteria
+        # @param [Hash] args
+        # @option args :settings [Hash] search criteria
+        #   - *:api* (String) - URL API (default: api.careerbuilder.com)
+        #   - *:version* (String) - a version of API (default: v2)
+        #   - *:clientid* (String) - Private Developer Key (see http://developer.careerbuilder.com)
+        # @option args :query [Hash] settings of API
+        #   - *:keywors* (String)
+        #   - *:location* (String)
+        #   - *:company* (String)
+        # @example
+        #   jobs = Careerbuilder.search({:settings => {
+        #                                   :api => 'api.careerbuilder.com',
+        #                                   :version => 'v2',
+        #                                   :clientid => 'secret-code'},
+        #                                :query => {
+        #                                   :keywords => 'ruby',
+        #                                   :location => 'London',
+        #                                   :company => ''}})
+        # @return [Hash] First page of the result (see constant RESULT_LIMIT)
+        def search(args)
+          args[:query] = DEFAULT.merge(args[:query]) if args[:query]
+
+          if args[:query_key].nil?
+            url_request = prepare_conn_string(args) + prepare_query(args)
+          else
+            url_request = args[:query_key]
+          end
+
+          response = send_request(url_request)
+          attributes = build_jobs_table(response, url_request)
+          OpenStruct.new(attributes)
+        end
+
+
+        # Get a specific page result
+        # At the beging you have to run {search} method and get :key from result and pass it to the argument :query_key
+        # @param [Hash] args
+        # @option args :settings [Hash] see {search}
+        # @option args [Integer] :page page number counted from 0
+        # @option args [String] :query_key
+        # @example
+        #   jobs = Careerbuilder.page({:settings => {
+        #                                   :api => 'api.careerbuilder.com',
+        #                                   :version => 'v2',
+        #                                   :clientid => 'secret-code'},
+        #                              :page => 5,
+        #                              :query_key => 'value from :key returned by search method'})
+        # @return [Hash] Job offers from specific page
+        def page(args)
+          page = args[:page].to_i || 0
+          if args[:query_key]
+            url_request = args[:query_key].gsub(/&PageNumber=\d+/, '') << "&PageNumber=#{page+1}"
+            args[:query_key] = url_request
+            search(args)
+          end
+        end
+
+        private
+
+        def build_jobs_table(response, url_request)
+          attributes  = Hash.new
+          attributes[:code] = response.code.to_i
+          attributes[:msg]  = response.message
+
+          attributes[:totalResults] = 0
+          attributes[:page] = nil
+          attributes[:last] = nil
+          attributes[:key]  = url_request
+          attributes[:jobs] = nil
+
+          if response.code.to_i == 200
+            xml_response = Hash.from_xml(response.body.gsub('\n', ''))
+            begin
+              if xml_response['ResponseJobSearch'] && xml_response['ResponseJobSearch']['Results']
+                attributes[:totalResults] = xml_response['ResponseJobSearch']['TotalCount'].to_i || 0
+                attributes[:page] = get_page_number(url_request) - 1
+                attributes[:last] = xml_response['ResponseJobSearch']['TotalPages'].to_i - 1
+                attributes[:key]  = url_request
+                attributes[:jobs] = parse_raw_data(xml_response)
+              end
+            rescue
+              raise "Something wrong with returned data: #{xml_response}"
+            end
+          end
+          attributes
+        end
+
+        def prepare_query(args)
+          "Keywords=#{args[:query][:keywords]}&" \
+          "Location=#{args[:query][:location]}&" \
+          "CompanyName=#{args[:query][:company]}"
+        end
+
+        def prepare_conn_string(args)
+          conn_string = "https://#{args[:settings][:api]}/#{args[:settings][:version]}/jobsearch?" \
+          "PerPage=#{RESULT_LIMIT}&DeveloperKey=#{args[:settings][:clientid]}&"
+
+          conn_string
+        end
+
+        def parse_raw_data(data)
+          jobs = Array.new
+          data['ResponseJobSearch']['Results']['JobSearchResult'].each do |offer|
+            job = Hash.new
+            job[:jobtitle] = offer['JobTitle'] if offer['JobTitle']
+
+            country = get_country_name(offer['State'], data['ResponseJobSearch']['SearchMetaData']['SearchLocations'])
+            location = country
+            location += ", #{offer['City']}" if offer['City'] && country != offer['City']
+            job[:location] = location
+            job[:company]  = offer['Company']
+
+            newdate = offer['PostedDate'].split('/')
+            job[:date]  = "#{newdate[1]}/#{newdate[0]}/#{newdate[2]}"
+
+            job[:date]     = convert_date_to_format(job[:date],'%d/%m/%y')
+            job[:url]      = offer['JobDetailsURL']
+
+            job = convert_empty_to_nil(job)
+
+            jobs << OpenStruct.new(job)
+          end
+          jobs
+        rescue
+          raise "Cannot parse raw data - #{data.inspect}"
+        end
+
+        def get_country_name(code, locations)
+          locations.each do |loc|
+            if loc[1]['StateCode'] && code && code.to_s == loc[1]['StateCode'].to_s
+              return loc[1]['City'] if loc[1]['City']
+            end
+          end
+
+          'United States'
+        rescue
+          raise "Cannot get country name (code=#{code}, locations=#{locations}"
+        end
+
+        def get_page_number(url)
+          result = url.match(/\&PageNumber=(\d+)/)
+          result ? result[1].to_i : 1
+        end
+
+      end
+    end
+  end
+end