AllNewsAPI Ruby SDK

A simple Ruby wrapper for the AllNewsAPI.

Installation

Add this line to your application's Gemfile:

gem 'allnewsapi'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install allnewsapi

Usage

require 'allnewsapi'

# Initialize the client with your API key
api_key = 'your_api_key_here'
client = AllNewsAPI::Client.new(api_key)

# Search for news articles with various options
results = client.search(
  q: 'climate change',
  lang: 'en',
  country: ['us', 'gb'],
  category: 'science',
  max: 10,
  sort_by: 'publishedAt',
  format: 'json'
)

# Get top headlines
headlines = client.headlines(
  country: 'us',
  category: 'technology',
  max: 5,
  format: 'json'
)

# Process the results
results['articles'].each do |article|
  puts "#{article['title']} - #{article['source']['name']}"
  puts article['url']
  puts "-----"
end

# Search with date ranges
require 'date'
results = client.search(
  q: 'elections',
  start_date: Date.new(2023, 1, 1),
  end_date: Date.today,
  max: 20
)

# Get results in CSV format and save to file
csv_data = client.search(
  q: 'technology',
  format: 'csv'
)

File.write('technology_news.csv', csv_data)

Available Options

Both the search and headlines methods accept the following options:

Option	Type	Description
q	String	Keywords to search for
start_date	String, Date	Start date (YYYY-MM-DD or Date object)
end_date	String, Date	End date (YYYY-MM-DD or Date object)
content	Boolean	Whether to include full content
lang	String, Array	Language(s) to filter by
country	String, Array	Country/countries to filter by
region	String, Array	Region(s) to filter by
category	String, Array	Category/categories to filter by
max	Integer	Maximum number of results (1-100)
attributes	String, Array	Attributes to search in (title, description, content)
page	Integer	Page number for pagination
sort_by	String	Sort by 'publishedAt' or 'relevance'
publisher	String, Array	Publisher(s) to filter by
format	String	Response format (json, csv, xlsx)

Headlines vs Search

The SDK provides two main methods for retrieving news:

search: Search for news articles based on keywords and filters
headlines: Get top headlines with the same filtering options

Both methods accept identical parameters and return the same response format.

# Get top headlines for a specific country and category
headlines = client.headlines(
  country: 'us',
  category: 'business',
  max: 10
)

# Search for specific topics
search_results = client.search(
  q: 'artificial intelligence',
  lang: 'en',
  max: 20
)

Error Handling

begin
  results = client.search(q: 'technology')
rescue AllNewsAPI::Error => e
  puts "Error #{e.status_code}: #{e.message}"
end

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/AllNewsAPI/ruby-sdk.

License

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