Twingly Search API Ruby

A Ruby gem for Twingly's Blog Search API (previously known as Analytics API) and Blog LiveFeed API. Twingly is a blog search service that provides a searchable API known as Twingly Blog Search API and a blog data firehose called Twingly Blog LiveFeed API.

Installation

Install via RubyGems

gem install twingly-search

Or add to your application's Gemfile and then run bundle

gem "twingly-search"

Usage

The twingly-search gem talks to a commercial API and requires an API key. Best practice is to set the TWINGLY_SEARCH_KEY environment variable to the obtained key. Twingly::Search::Client and Twingly::LiveFeed::Client can be passed a key at initialization if your setup does not allow environment variables.

To learn more about the features of this gem, read the gem documentation or check out the example code that can be found in examples/.

To learn more about the capabilities of Twingly's APIs, please read the Blog Search API documentation and Blog LiveFeed API documentation.

Blog Search API

require "twingly/search"

client = Twingly::Search::Client.new do |client|
  client.user_agent = "MyCompany/1.0"
end

query = client.query do |query|
  query.search_query  = "github page-size:10"
  query.language      = "sv"
end

result = query.execute
=> #<Twingly::Search::Result:0x3fca8ad3aa60 posts, number_of_matches_returned=10, number_of_matches_total=281, incomplete_result=false, seconds_elapsed=0.239, all_results_returned?=false, incomplete?=false>
result.posts # will include all returned posts

Blog LiveFeed API

require "twingly/livefeed"

client = Twingly::LiveFeed::Client.new do |client|
  client.user_agent = "MyCompany/1.0"
  # Start getting posts indexed by Twingly at this timestamp
  client.timestamp = Time.now - 3600 # 1 hour ago
  client.max_posts = 1000            # Maximum number of posts returned per call
end

# get the next chunk of posts
result = client.next_result
=> #<Twingly::LiveFeed::Result:0x3fca8ad4e81c posts, ts=2019-03-27 12:52:54 UTC, from=2019-03-27 11:52:53 UTC, number_of_posts=709, max_number_of_posts=1000, first_post=2019-03-27 11:53:02 UTC, last_post=2019-03-27 12:52:42 UTC, next_timestamp=2019-03-27 12:52:42 UTC>

result.posts # will include all returned posts

Requirements

API key, sign up via twingly.com to get one
Ruby
- Ruby >= 2.5
- JRuby >= 9.2

Development

Tests

Make sure you have all the dependencies

bundle

Run the tests

bundle exec rake

Profiling

It's possible to profile memory and object allocation:

bundle exec ruby profiler/profile_livefeed.rb
bundle exec ruby profiler/profile_search.rb

Currently using memory_profiler for reports and VCR for saving requests (to make runs comparable).

Release

Make a commit bumping the version in lib/twingly/search/version.rb, follow Semantic Versioning 2.0.0. No need to push as this will be taken care of automatically in the next step.
Ensure you are signed in to RubyGems.org as twingly with gem signin.
Build and the release gem with bundle exec rake release. This will create a git tag for the version and push the .gem file to RubyGems.org.
Generate a changelog with github_changelog_generator (gem install github_changelog_generator if you don't have it). Set CHANGELOG_GITHUB_TOKEN to a personal access token to increase the API rate limit. (The changelog uses GitHub Changelog Generator)
Update release information on the releases page. This is done manually.

Documentation

This gem is documented using YARD. To start a local YARD server run:

bundle exec rake yard:server

The YARD server reloads the documentation automatically so there is no need to restart it when making changes.

twingly / twingly-search-api-ruby

readme