twingly-analytics 1.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: e31d1b593419817798bfa388cdb2b2d3c74d2708
+  data.tar.gz: 3498b2b18671060c8119017bf9bd6ab07c18f8d4
+SHA512:
+  metadata.gz: e85e466d13661942b9f6b54b83dac6b9bb7537cc481525783d8863f3750133ed7e0cd68c71569e6c39d45b8c1d00ef588442415a815dbd7f81bb0276d5d76c00
+  data.tar.gz: 580b72a3b84a9398c57401731f644515e07d4b996bd7d59186543a2a2c865d46e74c59e6b56a3504ea8cb2fb6e38b60c66115439b3f5ab400958c392afa56f8f

data/.gitignore

@@ -0,0 +1,4 @@
+.env
+Gemfile.lock
+.ruby-version
+*.gem

data/.travis.yml

@@ -0,0 +1,17 @@
+language: ruby
+cache: bundler
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - 2.1
+  - 2.2
+deploy:
+  provider: rubygems
+  api_key:
+    secure: "QxMWXTQ3/T+0IQZl3pk3hmdoX8FcXTXEhH7Jn7Ub1A1D5faa8VNnfYsWAPjP6+VRgVfKEjAsHNMyZQNTvudpPPC/2kAwwzPvStyS+y7KnRkjZ9acC7sYVVel6cZ2lcl+t8iHY+19NRBFBWpq/P0eCAcR/Ew0XXaLZnig5h/1mQo="
+  gem: twingly-analytics
+  gemspec: twingly-analytics-api-ruby.gemspec
+  on:
+    tags: true
+    rvm: 2.2
+    repo: twingly/twingly-analytics-api-ruby

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org/'
+
+gemspec

data/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2013 Twingly AB
+
+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,60 @@
+# Twingly Analytics API Ruby
+
+[![Build Status](https://travis-ci.org/twingly/twingly-analytics-api-ruby.png?branch=master)](https://travis-ci.org/twingly/twingly-analytics-api-ruby)
+[![Code Climate](https://codeclimate.com/github/twingly/twingly-analytics-api-ruby.png)](https://codeclimate.com/github/twingly/twingly-analytics-api-ruby)
+
+A Ruby gem for Twingly's Analytics API. Twingly is a blog search service that provides a searchable API called [Twingly Analytics](https://developer.twingly.com/resources/analytics/).
+
+## Installation
+
+Add to your application's [Gemfile](http://bundler.io/gemfile.html) and then run `bundle`
+
+```Ruby
+gem 'twingly-analytics', github: 'twingly/twingly-analytics-api-ruby'
+```
+
+## Usage
+
+```Ruby
+require 'twingly-analytics'
+
+client = Twingly::Analytics::Client.new
+query = client.query
+query.pattern = 'github page-size:10'
+query.language = 'sv'
+result = query.execute
+=> #<Twingly::Analytics::Result:0x3ff7adcbe3d4 @posts, @number_of_matches_returned=10, @number_of_matches_total=3035221>
+result.posts # will include all returned posts
+```
+
+The `twinlgy-analytics` gem talks to a commercial blog search API and requires an API key. Best practice is to set the `TWINGLY_ANALYTICS_KEY` environment variable to the obtained key. `Twingly::Analytics::Client` can be passed a key at initialization if your setup does not allow environment variables.
+
+Too learn more about the capabilities of this API you should read the [Twingly Analytics API documentation](https://developer.twingly.com/resources/analytics/).
+
+## Requirements
+
+* API key, contact sales@twingly.com to get one
+* Ruby 1.9, 2.0, 2.1, 2.2
+
+## License
+
+The MIT License (MIT)
+
+Copyright (c) 2013 Twingly AB
+
+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/Rakefile

@@ -0,0 +1,17 @@
+require 'rake'
+require 'bundler/gem_tasks'
+
+desc "Run specs"
+task :spec do
+  require 'bundler/setup'
+  require 'rspec/core/rake_task'
+  RSpec::Core::RakeTask.new(:spec) do |t|
+    t.rspec_opts = %w(-fd -c)
+  end
+end
+
+desc "Synonym for spec"
+task :test => :spec
+desc "Synonym for spec"
+task :tests => :spec
+task :default => :spec

data/examples/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gem 'twingly-analytics', path: '../'

data/examples/find_all_posts_mentioning_github.rb

@@ -0,0 +1,29 @@
+require 'set'
+require 'bundler'
+Bundler.require
+
+# Set environment variable TWINGLY_ANALYTICS_KEY
+client = Twingly::Analytics::Client.new
+
+finished   = nil
+start_time = Time.new(2013, 01, 01)
+blogs      = Set.new
+
+until finished
+  query = client.query
+  query.pattern    = "sort-order:asc sort:published github"
+  query.start_time = start_time
+  query.language   = 'sv'
+  result = query.execute
+
+  result.posts.each do |post|
+    blogs.add(post.blog_url)
+  end
+
+  finished = start_time == result.posts.last.published
+  start_time = result.posts.last.published
+end
+
+blogs.each do |url|
+  puts url
+end

data/lib/twingly-analytics/client.rb

@@ -0,0 +1,19 @@
+module Twingly
+  module Analytics
+    class Client
+      attr_accessor :api_key
+
+      def initialize(api_key = nil)
+        @api_key = api_key || env_api_key || fail("Missing API key")
+      end
+
+      def query
+        Query.new(self)
+      end
+    private
+      def env_api_key
+        ENV['TWINGLY_ANALYTICS_KEY']
+      end
+    end
+  end
+end

data/lib/twingly-analytics/parser.rb

@@ -0,0 +1,45 @@
+require 'nokogiri'
+
+module Twingly
+  module Analytics
+    class Parser
+      def parse(document)
+        result = Result.new
+        nokogiri = Nokogiri::XML(document)
+
+        failure = nokogiri.at_xpath('//name:blogstream/name:operationResult[@resultType="failure"]', :name => 'http://www.twingly.com')
+        fail failure.text if failure
+
+        result.number_of_matches_returned = nokogiri.at_xpath('/twinglydata/@numberOfMatchesReturned').value.to_i
+        result.number_of_matches_total = nokogiri.at_xpath('/twinglydata/@numberOfMatchesTotal').value.to_i
+        result.seconds_elapsed = nokogiri.at_xpath('/twinglydata/@secondsElapsed').value.to_f
+
+        nokogiri.xpath('//post').each do |post|
+          result.posts << parse_post(post)
+        end
+
+        result
+      end
+    private
+      def parse_post(element)
+        post_params = {}
+        element.element_children.each do |child|
+          if child.name == 'tags'
+            post_params[child.name] = parse_tags(child) if child.name == 'tags'
+          else
+            post_params[child.name] = child.text
+          end
+        end
+        post = Post.new
+        post.set_values(post_params)
+        post
+      end
+
+      def parse_tags(element)
+        element.element_children.map do |child|
+          child.text
+        end
+      end
+    end
+  end
+end

data/lib/twingly-analytics/post.rb

@@ -0,0 +1,26 @@
+# encoding: utf-8
+
+require 'date'
+
+module Twingly
+  module Analytics
+    class Post
+      attr_reader :url, :title, :summary, :language_code, :indexed,
+        :published, :blog_url, :blog_name, :authority, :blog_rank, :tags
+
+      def set_values(params)
+        @url           = params.fetch('url')
+        @title         = params.fetch('title')
+        @summary       = params.fetch('summary')
+        @language_code = params.fetch('languageCode')
+        @published     = DateTime.parse(params.fetch('published'))
+        @indexed       = DateTime.parse(params.fetch('indexed'))
+        @blog_url      = params.fetch('blogUrl')
+        @blog_name     = params.fetch('blogName')
+        @authority     = params.fetch('authority').to_i
+        @blog_rank     = params.fetch('blogRank').to_i
+        @tags          = params.fetch('tags', [])
+      end
+    end
+  end
+end

data/lib/twingly-analytics/query.rb

@@ -0,0 +1,61 @@
+require 'faraday'
+
+module Twingly
+  module Analytics
+    class Query
+      attr_accessor :pattern, :language, :client
+      attr_reader :start_time, :end_time
+
+      BASE_URL = 'https://api.twingly.com'
+      ANALYTICS_PATH = '/analytics/Analytics.ashx'
+
+      def initialize(client)
+        @client = client
+      end
+
+      def url
+        "#{BASE_URL}#{ANALYTICS_PATH}?#{url_parameters}"
+      end
+
+      def execute
+        Parser.new.parse(get_response.body)
+      end
+
+      def start_time=(time)
+        @start_time = time.strftime("%F %T")
+      end
+
+      def end_time=(time)
+        @end_time = time.strftime("%F %T")
+      end
+
+      def url_parameters
+        Faraday::Utils.build_query(request_parameters)
+      end
+
+      def request_parameters
+        fail("Missing pattern") unless pattern
+
+        {
+          :key => client.api_key,
+          :searchpattern => pattern,
+          :documentlang => language,
+          :ts => start_time,
+          :tsTo => end_time,
+          :xmloutputversion => 2
+        }
+      end
+
+    private
+
+      def get_response
+        connection = Faraday.new(:url => BASE_URL) do |faraday|
+          faraday.request :url_encoded
+          faraday.adapter Faraday.default_adapter
+        end
+        connection.headers[:user_agent] = 'Ruby'
+        connection.get(ANALYTICS_PATH, request_parameters)
+      end
+    end
+  end
+end

data/lib/twingly-analytics/result.rb

@@ -0,0 +1,20 @@
+module Twingly
+  module Analytics
+    class Result
+      attr_accessor :number_of_matches_returned, :number_of_matches_total,
+        :seconds_elapsed
+
+      def posts
+        @posts ||= []
+      end
+
+      def inspect
+        matches = "@posts, "
+        matches << "@number_of_matches_returned=#{self.number_of_matches_returned}, "
+        matches << "@number_of_matches_total=#{self.number_of_matches_total}"
+
+        sprintf("#<%s:0x%x %s>", self.class.name, __id__, matches)
+      end
+    end
+  end
+end

data/lib/twingly-analytics/version.rb

@@ -0,0 +1,5 @@
+module Twingly
+  module Analytics
+    VERSION = '1.0.1'
+  end
+end

data/lib/twingly-analytics.rb

@@ -0,0 +1,6 @@
+require 'twingly-analytics/client'
+require 'twingly-analytics/query'
+require 'twingly-analytics/result'
+require 'twingly-analytics/parser'
+require 'twingly-analytics/post'
+require 'twingly-analytics/version'

data/spec/client_spec.rb

@@ -0,0 +1,27 @@
+require 'spec_helper'
+
+include Twingly::Analytics
+
+describe Client do
+  subject { Client.new('api_key') }
+  context 'with API key as arguments' do
+    it { should be_a Client }
+  end
+
+  context 'with API key from ENV variable' do
+    before { allow_any_instance_of(Client).to receive(:env_api_key).and_return('api_key') }
+    subject { Client.new }
+    it { should be_a Client }
+  end
+
+  context 'without valid API key' do
+    before { allow_any_instance_of(Client).to receive(:env_api_key).and_return(nil) }
+    subject { Client.new }
+    it { expect { subject }.to raise_error(RuntimeError, 'Missing API key') }
+  end
+
+  describe '#query' do
+    subject { Client.new('api_key').query }
+    it { should be_a Query }
+  end
+end

data/spec/fixtures/invalid_result.xml

@@ -0,0 +1,3 @@
+<?xml version="1.0" encoding="UTF-8"?><blogstream xmlns="http://www.twingly.com">
+  <operationResult resultType="failure">The API key does not exist.</operationResult>
+</blogstream>