Skip to content
💎 Twingly Blog Search API in Ruby
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

Twingly Search API Ruby

Build Status Code Climate

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.


Install via RubyGems

gem install twingly-search

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

gem "twingly-search"


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 = do |client|
  client.user_agent = "MyCompany/1.0"

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

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 = do |client|
  client.user_agent = "MyCompany/1.0"
  # Start getting posts indexed by Twingly at this timestamp
  client.timestamp = - 3600 # 1 hour ago
  client.max_posts = 1000            # Maximum number of posts returned per call

# 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




Make sure you have all the dependencies


Run the tests

bundle exec rake


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).


  1. 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.
  2. Ensure you are signed in to as twingly with gem signin.
  3. 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
  4. 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)
  5. Update release information on the releases page. This is done manually.


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.

You can’t perform that action at this time.