Stories
Show me this endpoint for

About

The stories endpoint is used to return stories based on parameters you set in your query. The News API crawler gathers articles in near real-time and stores information about them, or metadata. Below you can see all of the query parameters, which you can use to narrow down your query.

Parameters

Name Type Description Notes
id Array<Integer> This parameter is used for finding stories by story id. [optional]
not_id Array<Integer> This parameter is used for excluding stories by story id. [optional]
title String This parameter is used for finding stories whose title contains a specfic keyword. It supports boolean operators. [optional]
body String This parameter is used for finding stories whose body contains a specfic keyword. It supports boolean operators. [optional]
text String This parameter is used for finding stories whose title or body contains a specfic keyword. It supports boolean operators. [optional]
language Array<String> This parameter is used for finding stories whose language is the specified value. It supports ISO 639-1 language codes. [optional] [enum: en, de, fr, it, es, pt]
not_language Array<String> This parameter is used for excluding stories whose language is the specified value. It supports ISO 639-1 language codes. [optional] [enum: en, de, fr, it, es, pt]
published_at_start String This parameter is used for finding stories whose published at time is greater than the specified value. Here you can find more information about how to work with dates. [optional]
published_at_end String This parameter is used for finding stories whose published at time is less than the specified value. Here you can find more information about how to work with dates. [optional]
categories_taxonomy String This parameter is used for defining the type of the taxonomy for the rest of the categories queries. You can read more about working with categories here. [optional] [enum: iab-qag, iptc-subjectcode]
categories_confident BOOLEAN This parameter is used for finding stories whose categories are confident. You can read more about working with categories here. [optional] [default to true]
categories_id Array<String> This parameter is used for finding stories by categories id. You can read more about working with categories here. [optional]
not_categories_id Array<String> This parameter is used for excluding stories by categories id. You can read more about working with categories here. [optional]
categories_level Array<Integer> This parameter is used for finding stories by categories level. You can read more about working with categories here. [optional]
not_categories_level Array<Integer> This parameter is used for excluding stories by categories level. You can read more about working with categories here. [optional]
entities_title_text Array<String> This parameter is used to find stories based on the specified entities `text` in story titles. You can read more about working with entities here. [optional]
not_entities_title_text Array<String> This parameter is used to exclude stories based on the specified entities `text` in story titles. You can read more about working with entities here. [optional]
entities_title_type Array<String> This parameter is used to find stories based on the specified entities `type` in story titles. You can read more about working with entities here. [optional]
not_entities_title_type Array<String> This parameter is used to exclude stories based on the specified entities `type` in story titles. You can read more about working with entities here. [optional]
entities_title_links_dbpedia Array<String> This parameter is used to find stories based on the specified entities dbpedia URL in story titles. You can read more about working with entities here. [optional]
not_entities_title_links_dbpedia Array<String> This parameter is used to exclude stories based on the specified entities dbpedia URL in story titles. You can read more about working with entities here. [optional]
entities_body_text Array<String> This parameter is used to find stories based on the specified entities `text` in the body of stories. You can read more about working with entities here. [optional]
not_entities_body_text Array<String> This parameter is used to exclude stories based on the specified entities `text` in the body of stories. You can read more about working with entities here. [optional]
entities_body_type Array<String> This parameter is used to find stories based on the specified entities `type` in the body of stories. You can read more about working with entities here. [optional]
not_entities_body_type Array<String> This parameter is used to exclude stories based on the specified entities `type` in the body of stories. You can read more about working with entities here. [optional]
entities_body_links_dbpedia Array<String> This parameter is used to find stories based on the specified entities dbpedia URL in the body of stories. You can read more about working with entities here. [optional]
not_entities_body_links_dbpedia Array<String> This parameter is used to exclude stories based on the specified entities dbpedia URL in the body of stories. You can read more about working with entities here. [optional]
sentiment_title_polarity String This parameter is used for finding stories whose title sentiment is the specified value. [optional] [enum: positive, neutral, negative]
not_sentiment_title_polarity String This parameter is used for excluding stories whose title sentiment is the specified value. [optional] [enum: positive, neutral, negative]
sentiment_body_polarity String This parameter is used for finding stories whose body sentiment is the specified value. [optional] [enum: positive, neutral, negative]
not_sentiment_body_polarity String This parameter is used for excluding stories whose body sentiment is the specified value. [optional] [enum: positive, neutral, negative]
media_images_count_min Integer This parameter is used for finding stories whose number of images is greater than or equal to the specified value. [optional]
media_images_count_max Integer This parameter is used for finding stories whose number of images is less than or equal to the specified value. [optional]
media_images_width_min Integer This parameter is used for finding stories whose width of images are greater than or equal to the specified value. [optional]
media_images_width_max Integer This parameter is used for finding stories whose width of images are less than or equal to the specified value. [optional]
media_images_height_min Integer This parameter is used for finding stories whose height of images are greater than or equal to the specified value. [optional]
media_images_height_max Integer This parameter is used for finding stories whose height of images are less than or equal to the specified value. [optional]
media_images_content_length_min Integer This parameter is used for finding stories whose images content length are greater than or equal to the specified value. [optional]
media_images_content_length_max Integer This parameter is used for finding stories whose images content length are less than or equal to the specified value. [optional]
media_images_format Array<String> This parameter is used for finding stories whose images format are the specified value. [optional] [enum: BMP, GIF, JPEG, PNG, TIFF, PSD, ICO, CUR, WEBP, SVG]
not_media_images_format Array<String> This parameter is used for excluding stories whose images format are the specified value. [optional] [enum: BMP, GIF, JPEG, PNG, TIFF, PSD, ICO, CUR, WEBP, SVG]
media_videos_count_min Integer This parameter is used for finding stories whose number of videos is greater than or equal to the specified value. [optional]
media_videos_count_max Integer This parameter is used for finding stories whose number of videos is less than or equal to the specified value. [optional]
author_id Array<Integer> This parameter is used for finding stories whose author id is the specified value. [optional]
not_author_id Array<Integer> This parameter is used for excluding stories whose author id is the specified value. [optional]
author_name String This parameter is used for finding stories whose author full name contains the specified value. [optional]
not_author_name String This parameter is used for excluding stories whose author full name contains the specified value. [optional]
source_id Array<Integer> This parameter is used for finding stories whose source id is the specified value. [optional]
not_source_id Array<Integer> This parameter is used for excluding stories whose source id is the specified value. [optional]
source_name Array<String> This parameter is used for finding stories whose source name contains the specified value. [optional]
not_source_name Array<String> This parameter is used for excluding stories whose source name contains the specified value. [optional]
source_domain Array<String> This parameter is used for finding stories whose source domain is the specified value. [optional]
not_source_domain Array<String> This parameter is used for excluding stories whose source domain is the specified value. [optional]
source_locations_country Array<String> This parameter is used for finding stories whose source country is the specified value. It supports ISO 3166-1 alpha-2 country codes. Here you can find more information about how to work with locations. [optional]
not_source_locations_country Array<String> This parameter is used for excluding stories whose source country is the specified value. It supports ISO 3166-1 alpha-2 country codes. Here you can find more information about how to work with locations. [optional]
source_locations_state Array<String> This parameter is used for finding stories whose source state/province is the specified value. Here you can find more information about how to work with locations. [optional]
not_source_locations_state Array<String> This parameter is used for excluding stories whose source state/province is the specified value. Here you can find more information about how to work with locations. [optional]
source_locations_city Array<String> This parameter is used for finding stories whose source city is the specified value. Here you can find more information about how to work with locations. [optional]
not_source_locations_city Array<String> This parameter is used for excluding stories whose source city is the specified value. Here you can find more information about how to work with locations. [optional]
source_scopes_country Array<String> This parameter is used for finding stories whose source scopes is the specified country value. It supports ISO 3166-1 alpha-2 country codes. Here you can find more information about how to work with locations. [optional]
not_source_scopes_country Array<String> This parameter is used for excluding stories whose source scopes is the specified country value. It supports ISO 3166-1 alpha-2 country codes. Here you can find more information about how to work with locations. [optional]
source_scopes_state Array<String> This parameter is used for finding stories whose source scopes is the specified state/province value. Here you can find more information about how to work with locations. [optional]
not_source_scopes_state Array<String> This parameter is used for excluding stories whose source scopes is the specified state/province value. Here you can find more information about how to work with locations. [optional]
source_scopes_city Array<String> This parameter is used for finding stories whose source scopes is the specified city value. Here you can find more information about how to work with locations. [optional]
not_source_scopes_city Array<String> This parameter is used for excluding stories whose source scopes is the specified city value. Here you can find more information about how to work with locations. [optional]
source_scopes_level Array<String> This parameter is used for finding stories whose source scopes is the specified level value. Here you can find more information about how to work with locations. [optional] [enum: international, national, local]
not_source_scopes_level Array<String> This parameter is used for excluding stories whose source scopes is the specified level value. Here you can find more information about how to work with locations. [optional] [enum: international, national, local]
source_links_in_count_min Integer This parameter is used for finding stories from sources whose Links in count is greater than or equal to the specified value. You can read more about working with Links in count here. [optional]
source_links_in_count_max Integer This parameter is used for finding stories from sources whose Links in count is less than or equal to the specified value. You can read more about working with Links in count here. [optional]
source_rankings_alexa_rank_min Integer This parameter is used for finding stories from sources whose Alexa rank is greater than or equal to the specified value. You can read more about working with Alexa ranks here. [optional]
source_rankings_alexa_rank_max Integer This parameter is used for finding stories from sources whose Alexa rank is less than or equal to the specified value. You can read more about working with Alexa ranks here. [optional]
source_rankings_alexa_country Array<String> This parameter is used for finding stories from sources whose Alexa rank is in the specified country value. It supports ISO 3166-1 alpha-2 country codes. You can read more about working with Alexa ranks here. [optional]
social_shares_count_facebook_min Integer This parameter is used for finding stories whose Facebook social shares count is greater than or equal to the specified value. [optional]
social_shares_count_facebook_max Integer This parameter is used for finding stories whose Facebook social shares count is less than or equal to the specified value. [optional]
social_shares_count_google_plus_min Integer This parameter is used for finding stories whose Google+ social shares count is greater than or equal to the specified value. [optional]
social_shares_count_google_plus_max Integer This parameter is used for finding stories whose Google+ social shares count is less than or equal to the specified value. [optional]
social_shares_count_linkedin_min Integer This parameter is used for finding stories whose LinkedIn social shares count is greater than or equal to the specified value. [optional]
social_shares_count_linkedin_max Integer This parameter is used for finding stories whose LinkedIn social shares count is less than or equal to the specified value. [optional]
social_shares_count_reddit_min Integer This parameter is used for finding stories whose Reddit social shares count is greater than or equal to the specified value. [optional]
social_shares_count_reddit_max Integer This parameter is used for finding stories whose Reddit social shares count is less than or equal to the specified value. [optional]
cluster BOOLEAN This parameter enables clustering for the returned stories. You can read more about working with clustering here. [optional] [default to false]
cluster_algorithm String This parameter is used for specifying the clustering algorithm you wish to use. It supprts STC, Lingo and k-means algorithms. You can read more about working with clustering here. [optional] [default to lingo] [enum: stc, lingo, kmeans]
_return Array<String> This parameter is used for specifying return fields. [optional] [enum: id, title, body, summary, source, author, entities, keywords, hashtags, characters_count, words_count, sentences_count, paragraphs_count, categories, social_shares_count, media, sentiment, language, published_at, links]
sort_by String This parameter is used for changing the order column of the results. [optional] [default to published_at] [enum: relevance, recency, hotness, published_at, social_shares_count, social_shares_count.facebook, social_shares_count.linkedin, social_shares_count.google_plus, social_shares_count.reddit, media.images.count, media.videos.count, source.links_in_count, source.rankings.alexa.rank, source.rankings.alexa.rank.COUNTRYCODE]
sort_direction String This parameter is used for changing the order direction of the result. [optional] [default to desc] [enum: asc, desc]
cursor String This parameter is used for finding a specific page. You can read more about pagination of results here. [optional] [default to *]
per_page Integer This parameter is used for specifying number of items in each page You can read more about pagination of results here [optional] [default to 10]

Return type

Stories

Example

# load the gem
require 'aylien_news_api'

# setup authorization
AylienNewsApi.configure do |config|
  # Configure API key authorization: app_id
  config.api_key['X-AYLIEN-NewsAPI-Application-ID'] = 'YOUR_APP_ID'

  # Configure API key authorization: app_key
  config.api_key['X-AYLIEN-NewsAPI-Application-Key'] = 'YOUR_APP_KEY'
end

api_instance = AylienNewsApi::DefaultApi.new

opts = { 
  id: [5411],
  not_id: [3625],
  title: "startup AND (raise OR raised OR raising OR raises)",
  body: "startup",
  text: "startup company",
  language: ["en", "fr"],
  not_language: ["es", "it"],
  published_at_start: "NOW-10DAYS",
  published_at_end: "NOW",
  categories_taxonomy: "iptc-subjectcode",
  categories_confident: true,
  categories_id: ["11000000", "02000000"],
  not_categories_id: ["11001000", "10000000"],
  categories_level: [3],
  not_categories_level: [1, 2],
  entities_title_text: ["GNU/Linux", "Microsoft"],
  not_entities_title_text: ["Google", "Windows"],
  entities_title_type: ["Software", "Organization"],
  not_entities_title_type: ["Agent", "Person"],
  entities_title_links_dbpedia: ["http://dbpedia.org/resource/Linux"],
  not_entities_title_links_dbpedia: ["http://dbpedia.org/resource/Windows"],
  entities_body_text: ["Free Software", "Open Source"],
  not_entities_body_text: ["Barack Obama", "Trump"],
  entities_body_type: ["Software", "Organization"],
  not_entities_body_type: ["Agent", "Person"],
  entities_body_links_dbpedia: ["http://dbpedia.org/resource/Linux"],
  not_entities_body_links_dbpedia: ["http://dbpedia.org/resource/Windows"],
  sentiment_title_polarity: "positive",
  not_sentiment_title_polarity: "neutral",
  sentiment_body_polarity: "negative",
  not_sentiment_body_polarity: "positive",
  media_images_count_min: 3,
  media_images_count_max: 3,
  media_images_width_min: 640,
  media_images_width_max: 1024,
  media_images_height_min: 480,
  media_images_height_max: 800,
  media_images_content_length_min: 25411,
  media_images_content_length_max: 369541,
  media_images_format: ["JPEG", "BMP", "GIF"],
  not_media_images_format: ["TIFF", "PNG"],
  media_videos_count_min: 1,
  media_videos_count_max: 2,
  author_id: [4155],
  not_author_id: [2541],
  author_name: "John Doe",
  not_author_name: "Mike Wally",
  source_id: [124],
  not_source_id: [54],
  source_name: ["BBC"],
  not_source_name: ["Fox News"],
  source_domain: ["bbc.co.uk"],
  not_source_domain: ["foxnews.com"],
  source_locations_country: ["US", "IE"],
  not_source_locations_country: ["JP", "GB"],
  source_locations_state: ["California"],
  not_source_locations_state: ["Arizona"],
  source_locations_city: ["Los Angeles"],
  not_source_locations_city: ["Dublin City"],
  source_scopes_country: ["GB", "IE"],
  not_source_scopes_country: ["US", "JP"],
  source_scopes_state: ["Co Dublin"],
  not_source_scopes_state: ["Co Wicklow"],
  source_scopes_city: ["Cork"],
  not_source_scopes_city: ["Galway"],
  source_scopes_level: ["local"],
  not_source_scopes_level: ["national"],
  source_links_in_count_min: 126333,
  source_links_in_count_max: 521000,
  source_rankings_alexa_rank_min: 123,
  source_rankings_alexa_rank_max: 152,
  source_rankings_alexa_country: ["IE"],
  social_shares_count_facebook_min: 3521,
  social_shares_count_facebook_max: 5841,
  social_shares_count_google_plus_min: 2541,
  social_shares_count_google_plus_max: 36541,
  social_shares_count_linkedin_min: 6521,
  social_shares_count_linkedin_max: 32541,
  social_shares_count_reddit_min: 14521,
  social_shares_count_reddit_max: 95841,
  cluster: false,
  cluster_algorithm: "kmeans",
  _return: ["id", "title"],
  sort_by: "published_at",
  sort_direction: "desc",
  cursor: "*",
  per_page: 10
}

begin
  #List Stories
  result = api_instance.list_stories(opts)
  puts result
rescue AylienNewsApi::ApiError => e
  puts "Exception when calling DefaultApi->list_stories: #{e}"
  puts e.response_body
end