You’re currently viewing the current News API Documentation. If you signed up as a user prior to October 29th you should refer to the Legacy News API documentation.

Endpoints

The News API includes endpoints that provide both retrieval and analysis features that allow you to search, collect, and analyze news content at scale.

Our retrieval endpoints:

Our analysis endpoints:

The OpenAPI 3.0 specification for our endpoints are available on GitHub under the AYLIEN/apis repository.

Clusters

from __future__ import print_function
import time
import aylien_news_api
from aylien_news_api.rest import ApiException
from pprint import pprint
configuration = aylien_news_api.Configuration()

# Configure API key authorization: app_id
configuration.api_key['X-AYLIEN-NewsAPI-Application-ID'] = 'YOUR_API_KEY'
configuration = aylien_news_api.Configuration()

# Configure API key authorization: app_key
configuration.api_key['X-AYLIEN-NewsAPI-Application-Key'] = 'YOUR_API_KEY'
configuration.host = "https://api.aylien.com/news"

# Create an instance of the API class
api_instance = aylien_news_api.DefaultApi(aylien_news_api.ApiClient(configuration))

opts = {
    'id': [123],
    'not_id': [132],
    'story_count_min': 123,
    'story_count_max': 1234,
    'time_start': 'NOW-3DAYS/DAY',
    'time_end': 'NOW-1DAY/DAY',
    'earliest_story_start': 'earliest_story_start_example',
    'earliest_story_end': 'earliest_story_end_example',
    'latest_story_start': 'latest_story_start_example',
    'latest_story_end': 'latest_story_end_example',
    'location_country': ['location_country_example'],
    'not_location_country': ['location_country_example']
    }

try:
    # List Clusters
    api_response = api_instance.list_clusters(**opts)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling DefaultApi->list_clusters: %s\n" % e)

The News API’s clustering feature groups related stories into clusters. These clusters typically correspond to real-world events or topics.

The Clusters endpoint is used to retrieve cluster objects. A cluster object includes a unique cluster ID, some metadata about the cluster, and a story that best represents the cluster. Stories associated with a cluster can be retrieved by calling the Stories endpoint with the cluster ID supplied as the clusters[] parameter.

To learn more about working with clustering, go to the Working With Clusters documentation page.

HTTP Request

GET https://api.aylien.com/news/clusters

Parameters

Name Description
X-AYLIEN-NewsAPI-Application-ID *
string
(header)
x-data-threescale-name: app_ids

Your access API ID

X-AYLIEN-NewsAPI-Application-Key *
string
(header)
x-data-threescale-name: app_keys

Your access API Key

id[]
array [integer]
(query)

This parameter allows you to retrieve specific clusters by their id which is specified with a list of int64 values.

story_count.min
int64
(query)

This parameter allows you to specify the minimum number stories that retrieved clusters should be associated with. Default value is 2.

story_count.max
int64
(query)

This parameter allows you to specify clusters that have a maximum number of stories associated with them.

earliest_story.start
ISO 8601
(query)

This parameter allows you to specify clusters whose earliest story was published after a specified time stamp.

earliest_story.end
ISO 8601
(query)

This parameter allows you to specify clusters whose earliest story was published before a specified time stamp.

latest_story.start
ISO 8601
(query)

This parameter allows you to specify clusters whose latest story was published after a specified time stamp.

latest_story.end
ISO 8601
(query)

This parameter allows you to specify clusters whose latest story was published before a specified time stamp

time.start
ISO 8601
(query)

This parameter allows you to retrieve clusters for which the associated event’s time is after a specified time stamp.

time.end
ISO 8601
(query)

This parameter allows you to retrieve clusters for which the associated event’s time is before a specified time stamp.

sort_by
string
(query)

This parameter allows you to specify the parameter by which your results will be sorted. The accepted values are: - `story_count` - `earliest_story` - `latest_story` - `time`

sort_direction
string
(query)

This parameter allows you to specify the sort direction of your results. The accepted values are `asc` and `desc`.

per_page
int64
(query)

This parameter allows you to specify the maximum number of clusters to be returned by your query. The maximum value is 100, for more than 100 results `cursor` can be used.

cursor
string
(query)

This parameter allows you to chain your requests in calls that return more than 100 clusters by supplying the `next_page_cursor` response to your next call. For more information about using cursor with the News API, take a look at the documentation page.

Stories

from __future__ import print_function
import time
import aylien_news_api
from aylien_news_api.rest import ApiException
from pprint import pprint
configuration = aylien_news_api.Configuration()

# Configure API key authorization: app_id
configuration.api_key['X-AYLIEN-NewsAPI-Application-ID'] = 'YOUR_API_KEY'

# Configure API key authorization: app_key
configuration.api_key['X-AYLIEN-NewsAPI-Application-Key'] = 'YOUR_API_KEY'

# Defining host is optional and default to https://api.aylien.com/news
configuration.host = "https://api.aylien.com/news"
# Create an instance of the API class
api_instance = aylien_news_api.DefaultApi(aylien_news_api.ApiClient(configuration))

opts = {
  'id': [56], 
  'not_id': [56], 
  'title': 'title_example', 
  'body': 'body_example', 
  'text': 'text_example', 
  'translations_en_title': 'translations_en_title_example', 
  'translations_en_body': 'translations_en_body_example', 
  'translations_en_text': 'translations_en_text_example', 
  'language': ['language_example'], 
  'not_language': ['language_example'], 
  'published_at_start': 'published_at_start_example', 
  'published_at_end': 'published_at_end_example', 
  'categories_taxonomy': 'categories_taxonomy_example', 
  'categories_confident': True, 
  'categories_id': ['categories_id_example'], 
  'not_categories_id': ['categories_id_example'], 
  'categories_level': [56], 
  'not_categories_level': [56], 
  'entities_title_text': ['entities_title_text_example'], 
  'not_entities_title_text': ['entities_title_text_example'], 
  'entities_title_type': ['entities_title_type_example'], 
  'not_entities_title_type': ['entities_title_type_example'], 
  'entities_title_links_dbpedia': ['entities_title_links_dbpedia_example'], 
  'not_entities_title_links_dbpedia': ['entities_title_links_dbpedia_example'], 
  'entities_body_text': ['entities_body_text_example'], 
  'not_entities_body_text': ['entities_body_text_example'], 
  'entities_body_type': ['entities_body_type_example'], 
  'not_entities_body_type': ['entities_body_type_example'], 
  'entities_body_links_dbpedia': ['entities_body_links_dbpedia_example'], 
  'not_entities_body_links_dbpedia': ['entities_body_links_dbpedia_example'], 
  'sentiment_title_polarity': 'sentiment_title_polarity_example', 
  'not_sentiment_title_polarity': 'sentiment_title_polarity_example', 
  'sentiment_body_polarity': 'sentiment_body_polarity_example', 
  'not_sentiment_body_polarity': 'sentiment_body_polarity_example', 
  'media_images_count_min': 56, 
  'media_images_count_max': 56, 
  'media_images_width_min': 56, 
  'media_images_width_max': 56, 
  'media_images_height_min': 56, 
  'media_images_height_max': 56, 
  'media_images_content_length_min': 56, 
  'media_images_content_length_max': 56, 
  'media_images_format': ['media_images_format_example'], 
  'not_media_images_format': ['media_images_format_example'], 
  'media_videos_count_min': 56, 
  'media_videos_count_max': 56, 
  'author_id': [56], 
  'not_author_id': [56], 
  'author_name': 'author_name_example', 
  'not_author_name': 'author_name_example', 
  'source_id': [56], 
  'not_source_id': [56], 
  'source_name': ['source_name_example'], 
  'not_source_name': ['source_name_example'], 
  'source_domain': ['source_domain_example'], 
  'not_source_domain': ['source_domain_example'], 
  'source_locations_country': ['source_locations_country_example'], 
  'not_source_locations_country': ['source_locations_country_example'], 
  'source_locations_state': ['source_locations_state_example'], 
  'not_source_locations_state': ['source_locations_state_example'], 
  'source_locations_city': ['source_locations_city_example'], 
  'not_source_locations_city': ['source_locations_city_example'], 
  'source_scopes_country': ['source_scopes_country_example'], 
  'not_source_scopes_country': ['source_scopes_country_example'], 
  'source_scopes_state': ['source_scopes_state_example'], 
  'not_source_scopes_state': ['source_scopes_state_example'], 
  'source_scopes_city': ['source_scopes_city_example'], 
  'not_source_scopes_city': ['source_scopes_city_example'], 
  'source_scopes_level': ['source_scopes_level_example'], 
  'not_source_scopes_level': ['source_scopes_level_example'], 
  'source_links_in_count_min': 56, 
  'source_links_in_count_max': 56, 
  'source_rankings_alexa_rank_min': 56, 
  'source_rankings_alexa_rank_max': 56, 
  'source_rankings_alexa_country': ['source_rankings_alexa_country_example'], 
  'social_shares_count_facebook_min': 56, 
  'social_shares_count_facebook_max': 56, 
  'social_shares_count_google_plus_min': 56, 
  'social_shares_count_google_plus_max': 56, 
  'social_shares_count_linkedin_min': 56, 
  'social_shares_count_linkedin_max': 56, 
  'social_shares_count_reddit_min': 56, 
  'social_shares_count_reddit_max': 56, 
  'clusters': ['clusters_example'], 
  '_return': ['_return_example'], 
  'sort_by': 'published_at', 
  'sort_direction': 'desc', 
  'cursor': '*', 
  'per_page': 10 
}
try:
    # List Stories
    api_response = api_instance.list_stories(**opts)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling DefaultApi->list_stories: %s\n" % e)

Stories allows you to search for news articles based on a specific set of parameters that you set in your query, such as keywords, entities or sources. The News API gathers articles in near real-time, and stores and indexes them along with metadata and enrichments, which you can search over. Below you can see all of the query parameters which you can use to specify and narrow down your query.

HTTP Request

  • GET https://api.aylien.com/news/stories

Parameters

Name Description
X-AYLIEN-NewsAPI-Application-ID *
string
(header)
x-data-threescale-name: app_ids

Your access API ID

X-AYLIEN-NewsAPI-Application-Key *
string
(header)
x-data-threescale-name: app_keys

Your access API Key

global_clustering
integer
(query)

This parameter is used for enabling the clustering functionality. Setting the value to 1 enables clustering, 0 disables the functionality. Defaults to 0. Clustering requires an Advanced or Enterprise license key. Start a free trial or contact sales to upgrade your account.

clusters[]
array [integer]
(query)

This parameter is used for filtering stories associated with a specific cluster (currently accepts one cluster per search). Clustering requires an Advanced or Enterprise license key. Start a free trial or contact sales to upgrade your account.

!clusters[]
array [integer]
(query)

This parameter is used for blocking stories associated with a specific cluster (currently accepts one cluster per search). Clustering requires an Advanced or Enterprise license key. Start a free trial or contact sales to upgrade your account.

translations.title.__
string
(query)

This parameter is used for filtering stories translated from a specified language containing a query term in the title. To specify a language, use the ISO 639-1 standard. Translation requires an Advanced or Enterprise license key. Start a free trial or contact sales to upgrade your account.

translations.body.__
string
(query)

This parameter is used for filtering stories translated from a specified language containing a query term in the body. To specify a language, use the ISO 639-1 standard. Translation requires an Advanced or Enterprise license key. Start a free trial or contact sales to upgrade your account.

id[]
array [integer]
(query)

This parameter is used for finding stories by story id.

!id[]
array [integer]
(query)

This parameter is used for excluding stories by story id.

title
string
(query)

This parameter is used for finding stories whose title contains a specific keyword. It supports boolean operators.

body
string
(query)

This parameter is used for finding stories whose body contains a specific keyword. It supports boolean operators.

text
string
(query)

This parameter is used for finding stories whose title or body contains a specific keyword. It supports boolean operators.

language[]
array [string]
(query)

This parameter is used for finding stories whose language is the specified value. It supports ISO 639-1 language codes.

Available values: en, de, fr, it, es, pt, ru, nl, ar, tr, zh-tw, zh-cn, sv, da.

!language[]
array [string]
(query)

This parameter is used for excluding stories whose language is the specified value. It supports ISO 639-1 language codes.

Available values: en, de, fr, it, es, pt, ru, nl, ar, tr, zh-tw, zh-cn, sv, da.

published_at.start
string
(query)

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.

published_at.end
string
(query)

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.

categories.taxonomy
string
(query)

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.

categories.confident
boolean
(query)

This parameter is used for finding stories whose categories are confident. You can read more about working with categories here.

Default value: true

categories.id[]
array [string]
(query)

This parameter is used for finding stories by categories id. You can read more about working with categories here, and find category ids here.

!categories.id[]
array [string]
(query)

This parameter is used for excluding stories by categories id. You can read more about working with categories here, and find category ids here.

categories.level[]
array [integer]
(query)

This parameter is used for finding stories by categories level. You can read more about working with categories here, and find category ids here.

!categories.level[]
array [integer]
(query)

This parameter is used for excluding stories by categories level. You can read more about working with categories here, and find category ids here.

entities.title.text[]
array [string]
(query)

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.

!entities.title.text[]
array [string]
(query)

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.

entities.title.type[]
array [string]
(query)

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.

!entities.title.type[]
array [string]
(query)

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.

entities.title.links.dbpedia[]
array [string]
(query)

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.

!entities.title.links.dbpedia[]
array [string]
(query)

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.

entities.body.text[]
array [string]
(query)

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.

!entities.body.text[]
array [string]
(query)

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.

entities.body.type[]
array [string]
(query)

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.

!entities.body.type[]
array [string]
(query)

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.

entities.body.links.dbpedia[]
array [string]
(query)

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.

!entities.body.links.dbpedia[]
array [string]
(query)

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.

sentiment.title.polarity
string
(query)

This parameter is used for finding stories whose title sentiment is the specified value.

!sentiment.title.polarity
string
(query)

This parameter is used for excluding stories whose title sentiment is the specified value.

sentiment.body.polarity
string
(query)

This parameter is used for finding stories whose body sentiment is the specified value.

!sentiment.body.polarity
string
(query)

This parameter is used for excluding stories whose body sentiment is the specified value.

media.images.count.min
integer
(query)

This parameter is used for finding stories whose number of images is greater than or equal to the specified value.

media.images.count.max
integer
(query)

This parameter is used for finding stories whose number of images is less than or equal to the specified value.

media.images.width.min
integer
(query)

This parameter is used for finding stories whose width of images are greater than or equal to the specified value.

media.images.width.max
integer
(query)

This parameter is used for finding stories whose width of images are less than or equal to the specified value.

media.images.height.min
integer
(query)

This parameter is used for finding stories whose height of images are greater than or equal to the specified value.

media.images.height.max
integer
(query)

This parameter is used for finding stories whose height of images are less than or equal to the specified value.

media.images.content_length.min
integer
(query)

This parameter is used for finding stories whose images content length are greater than or equal to the specified value.

media.images.content_length.max
integer
(query)

This parameter is used for finding stories whose images content length are less than or equal to the specified value.

media.images.format[]
array [string]
(query)

This parameter is used for finding stories whose images format are the specified value.

Available values: BMP, GIF, JPEG, PNG, TIFF, PSD, ICO, CUR, WEBP, SVG

!media.images.format[]
array [string]
(query)

This parameter is used for excluding stories whose images format are the specified value.

Available values: BMP, GIF, JPEG, PNG, TIFF, PSD, ICO, CUR, WEBP, SVG

media.videos.count.min
integer
(query)

This parameter is used for finding stories whose number of videos is greater than or equal to the specified value.

media.videos.count.max
integer
(query)

This parameter is used for finding stories whose number of videos is less than or equal to the specified value.

author.id[]
array [integer]
(query)

This parameter is used for finding stories whose author id is the specified value.

!author.id[]
array [integer]
(query)

This parameter is used for excluding stories whose author id is the specified value.

author.name
string
(query)

This parameter is used for finding stories whose author full name contains the specified value.

!author.name
string
(query)

This parameter is used for excluding stories whose author full name contains the specified value.

source.id[]
array [integer]
(query)

This parameter is used for finding stories whose source id is the specified value.

!source.id[]
array [integer]
(query)

This parameter is used for excluding stories whose source id is the specified value.

source.name[]
array [string]
(query)

This parameter is used for finding stories whose source name contains the specified value.

!source.name[]
array [string]
(query)

This parameter is used for excluding stories whose source name contains the specified value.

source.domain[]
array [string]
(query)

This parameter is used for finding stories whose source domain is the specified value.

!source.domain[]
array [string]
(query)

This parameter is used for excluding stories whose source domain is the specified value.

source.locations.country[]
array [string]
(query)

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.

!source.locations.country[]
array [string]
(query)

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.

source.locations.state[]
array [string]
(query)

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.

!source.locations.state[]
array [string]
(query)

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.

source.locations.city[]
array [string]
(query)

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.

!source.locations.city[]
array [string]
(query)

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.

source.scopes.country[]
array [string]
(query)

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.

!source.scopes.country[]
array [string]
(query)

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.

source.scopes.state[]
array [string]
(query)

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.

!source.scopes.state[]
array [string]
(query)

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.

source.scopes.city[]
array [string]
(query)

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.

!source.scopes.city[]
array [string]
(query)

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.

source.scopes.level[]
array [string]
(query)

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.

Available values: international, national, local

!source.scopes.level[]
array [string]
(query)

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.

Available values: international, national, local

source.links_in_count.min
integer
(query)

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.

source.links_in_count.max
integer
(query)

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.

source.rankings.alexa.rank.min
integer
(query)

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.

source.rankings.alexa.rank.max
integer
(query)

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.

source.rankings.alexa.country[]
array [string]
(query)

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.

social_shares_count.facebook.min
integer
(query)

This parameter is used for finding stories whose Facebook social shares count is greater than or equal to the specified value.

social_shares_count.facebook.max
integer
(query)

This parameter is used for finding stories whose Facebook social shares count is less than or equal to the specified value.

social_shares_count.google_plus.min
integer
(query)

This parameter is used for finding stories whose Google+ social shares count is greater than or equal to the specified value.

social_shares_count.google_plus.max
integer
(query)

This parameter is used for finding stories whose Google+ social shares count is less than or equal to the specified value.

social_shares_count.linkedin.min
integer
(query)

This parameter is used for finding stories whose LinkedIn social shares count is greater than or equal to the specified value.

social_shares_count.linkedin.max
integer
(query)

This parameter is used for finding stories whose LinkedIn social shares count is less than or equal to the specified value.

social_shares_count.reddit.min
integer
(query)

This parameter is used for finding stories whose Reddit social shares count is greater than or equal to the specified value.

social_shares_count.reddit.max
integer
(query)

This parameter is used for finding stories whose Reddit social shares count is less than or equal to the specified value.

cluster
boolean
(query)

This parameter enables clustering for the returned stories. You can read more about working with clustering here.

Default value: false

cluster.algorithm
string
(query)

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.

Default value: lingo

return[]
array [string]
(query)

This parameter is used for specifying return fields.

Available values: 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
(query)

This parameter is used for changing the order column of the results. You can read about sorting results here.

Default value: published_at

sort_direction
string
(query)

This parameter is used for changing the order direction of the result. You can read about sorting results here.

Default value: desc

cursor
string
(query)

This parameter is used for finding a specific page. You can read more about pagination of results here.

Default value: *

per_page
integer
(query)

This parameter is used for specifying number of items in each page You can read more about pagination of results here

Default value: 10

Response

Code Description
200

An object including an array of stories

401

Unauthorized

404

Not Found

422

Unprocessable Entity

429

Too Many Requests

  • X-RateLimit-Limit: The number of allowed requests in the current period.
  • X-RateLimit-Remaining: The number of remaining requests in the current period.
  • X-RateLimit-Reset: The remaining window before the rate limit resets in UTC epoch seconds.
500

Internal Server Error

Related Stories

from __future__ import print_function
import time
import aylien_news_api
from aylien_news_api.rest import ApiException
from pprint import pprint
configuration = aylien_news_api.Configuration()
# Configure API key authorization: app_id
configuration.api_key['X-AYLIEN-NewsAPI-Application-ID'] = 'YOUR_API_KEY'
# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['X-AYLIEN-NewsAPI-Application-ID'] = 'Bearer'
configuration = aylien_news_api.Configuration()
# Configure API key authorization: app_key
configuration.api_key['X-AYLIEN-NewsAPI-Application-Key'] = 'YOUR_API_KEY'
# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['X-AYLIEN-NewsAPI-Application-Key'] = 'Bearer'

# Defining host is optional and default to https://api.aylien.com/news
configuration.host = "https://api.aylien.com/news"
# Create an instance of the API class
api_instance = aylien_news_api.DefaultApi(aylien_news_api.ApiClient(configuration))

opts = {
  'id': [56], 
  'not_id': [56], 
  'title': 'title_example', 
  'body': 'body_example', 
  'text': 'text_example', 
  'translations_en_title': 'translations_en_title_example', 
  'translations_en_body': 'translations_en_body_example', 
  'translations_en_text': 'translations_en_text_example', 
  'language': ['language_example'], 
  'not_language': ['language_example'], 
  'published_at_start': 'published_at_start_example', 
  'published_at_end': 'published_at_end_example', 
  'categories_taxonomy': 'categories_taxonomy_example', 
  'categories_confident': True, 
  'categories_id': ['categories_id_example'], 
  'not_categories_id': ['categories_id_example'], 
  'categories_level': [56], 
  'not_categories_level': [56], 
  'entities_title_text': ['entities_title_text_example'], 
  'not_entities_title_text': ['entities_title_text_example'], 
  'entities_title_type': ['entities_title_type_example'], 
  'not_entities_title_type': ['entities_title_type_example'], 
  'entities_title_links_dbpedia': ['entities_title_links_dbpedia_example'], 
  'not_entities_title_links_dbpedia': ['entities_title_links_dbpedia_example'], 
  'entities_body_text': ['entities_body_text_example'], 
  'not_entities_body_text': ['entities_body_text_example'], 
  'entities_body_type': ['entities_body_type_example'], 
  'not_entities_body_type': ['entities_body_type_example'], 
  'entities_body_links_dbpedia': ['entities_body_links_dbpedia_example'], 
  'not_entities_body_links_dbpedia': ['entities_body_links_dbpedia_example'], 
  'sentiment_title_polarity': 'sentiment_title_polarity_example', 
  'not_sentiment_title_polarity': 'sentiment_title_polarity_example', 
  'sentiment_body_polarity': 'sentiment_body_polarity_example', 
  'not_sentiment_body_polarity': 'sentiment_body_polarity_example', 
  'media_images_count_min': 56, 
  'media_images_count_max': 56, 
  'media_images_width_min': 56, 
  'media_images_width_max': 56, 
  'media_images_height_min': 56, 
  'media_images_height_max': 56, 
  'media_images_content_length_min': 56, 
  'media_images_content_length_max': 56, 
  'media_images_format': ['media_images_format_example'], 
  'not_media_images_format': ['media_images_format_example'], 
  'media_videos_count_min': 56, 
  'media_videos_count_max': 56, 
  'author_id': [56], 
  'not_author_id': [56], 
  'author_name': 'author_name_example', 
  'not_author_name': 'author_name_example', 
  'source_id': [56], 
  'not_source_id': [56], 
  'source_name': ['source_name_example'], 
  'not_source_name': ['source_name_example'], 
  'source_domain': ['source_domain_example'], 
  'not_source_domain': ['source_domain_example'], 
  'source_locations_country': ['source_locations_country_example'], 
  'not_source_locations_country': ['source_locations_country_example'], 
  'source_locations_state': ['source_locations_state_example'], 
  'not_source_locations_state': ['source_locations_state_example'], 
  'source_locations_city': ['source_locations_city_example'], 
  'not_source_locations_city': ['source_locations_city_example'], 
  'source_scopes_country': ['source_scopes_country_example'], 
  'not_source_scopes_country': ['source_scopes_country_example'], 
  'source_scopes_state': ['source_scopes_state_example'], 
  'not_source_scopes_state': ['source_scopes_state_example'], 
  'source_scopes_city': ['source_scopes_city_example'], 
  'not_source_scopes_city': ['source_scopes_city_example'], 
  'source_scopes_level': ['source_scopes_level_example'], 
  'not_source_scopes_level': ['source_scopes_level_example'], 
  'source_links_in_count_min': 56, 
  'source_links_in_count_max': 56, 
  'source_rankings_alexa_rank_min': 56, 
  'source_rankings_alexa_rank_max': 56, 
  'source_rankings_alexa_country': ['source_rankings_alexa_country_example'], 
  'social_shares_count_facebook_min': 56, 
  'social_shares_count_facebook_max': 56, 
  'social_shares_count_google_plus_min': 56, 
  'social_shares_count_google_plus_max': 56, 
  'social_shares_count_linkedin_min': 56, 
  'social_shares_count_linkedin_max': 56, 
  'social_shares_count_reddit_min': 56, 
  'social_shares_count_reddit_max': 56, 
  'clusters': ['clusters_example'], 
  '_return': ['_return_example'], 
  'story_id': 56, 
  'story_url': 'story_url_example', 
  'story_title': 'story_title_example', 
  'story_body': 'story_body_example', 
  'boost_by': 'boost_by_example', 
  'story_language': 'auto', 
  'per_page': 3 
}

try:
    # List related stories
    api_response = api_instance.list_related_stories(**opts)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling DefaultApi->list_related_stories: %s\n" % e)

Related Stories returns semantically similar stories for an input article, or any free-form text. For example, if you want to find stories similar to a tweet, you can supply the text of the tweet, and Related Stories will analyze it to extract topics and entities from it, and find stories with similar topical distribution and entities. You can use the standard filtering options to set additional filters, for example to retrieve stories that are related to an input story, but from a particular source, or with a particular sentiment.

HTTP Request

  • GET https://api.aylien.com/news/related_stories
  • POST https://api.aylien.com/news/related_stories

Parameters

Name Description
X-AYLIEN-NewsAPI-Application-ID *
string
(header)
x-data-threescale-name: app_ids

Your access API ID

X-AYLIEN-NewsAPI-Application-Key *
string
(header)
x-data-threescale-name: app_keys

Your access API Key

global_clustering
integer
(query)

This parameter is used for enabling the clustering functionality. Setting the value to 1 enables clustering, 0 disables the functionality. Defaults to 0. Clustering requires an Advanced or Enterprise license key. Start a free trial or contact sales to upgrade your account.

clusters[]
array [integer]
(query)

This parameter is used for finding stories associated with a specific cluster (currently accepts one cluster per search).

translations.title.__
string
(query)

This parameter is used for filtering stories translated from a specified language containing a query term in the title. To specify a language, use the ISO 639-1 standard. Translation requires an Advanced or Enterprise license key. Start a free trial or contact sales to upgrade your account.

translations.body.__
string
(query)

This parameter is used for filtering stories translated from a specified language containing a query term in the body. To specify a language, use the ISO 639-1 standard. Translation requires an Advanced or Enterprise license key. Start a free trial or contact sales to upgrade your account.

id[]
array [integer]
(query)

This parameter is used for finding stories by story id.

!id[]
array [integer]
(query)

This parameter is used for excluding stories by story id.

title
string
(query)

This parameter is used for finding stories whose title contains a specific keyword. It supports boolean operators.

body
string
(query)

This parameter is used for finding stories whose body contains a specific keyword. It supports boolean operators.

text
string
(query)

This parameter is used for finding stories whose title or body contains a specific keyword. It supports boolean operators.

language[]
array [string]
(query)

This parameter is used for finding stories whose language is the specified value. It supports ISO 639-1 language codes.

Available values: en, de, fr, it, es, pt, ru, nl, ar, tr, zh-tw, zh-cn, sv, da.

!language[]
array [string]
(query)

This parameter is used for excluding stories whose language is the specified value. It supports ISO 639-1 language codes.

Available values: en, de, fr, it, es, pt, ru, nl, ar, tr, zh-tw, zh-cn, sv, da.

published_at.start
string
(query)

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.

published_at.end
string
(query)

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.

categories.taxonomy
string
(query)

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.

categories.confident
boolean
(query)

This parameter is used for finding stories whose categories are confident. You can read more about working with categories here.

Default value: true

categories.id[]
array [string]
(query)

This parameter is used for finding stories by categories id. You can read more about working with categories here, and find category ids here.

!categories.id[]
array [string]
(query)

This parameter is used for excluding stories by categories id. You can read more about working with categories here, and find category ids here.

categories.level[]
array [integer]
(query)

This parameter is used for finding stories by categories level. You can read more about working with categories here, and find category ids here.

!categories.level[]
array [integer]
(query)

This parameter is used for excluding stories by categories level. You can read more about working with categories here, and find category ids here.

entities.title.text[]
array [string]
(query)

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.

!entities.title.text[]
array [string]
(query)

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.

entities.title.type[]
array [string]
(query)

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.

!entities.title.type[]
array [string]
(query)

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.

entities.title.links.dbpedia[]
array [string]
(query)

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.

!entities.title.links.dbpedia[]
array [string]
(query)

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.

entities.body.text[]
array [string]
(query)

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.

!entities.body.text[]
array [string]
(query)

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.

entities.body.type[]
array [string]
(query)

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.

!entities.body.type[]
array [string]
(query)

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.

entities.body.links.dbpedia[]
array [string]
(query)

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.

!entities.body.links.dbpedia[]
array [string]
(query)

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.

sentiment.title.polarity
string
(query)

This parameter is used for finding stories whose title sentiment is the specified value.

!sentiment.title.polarity
string
(query)

This parameter is used for excluding stories whose title sentiment is the specified value.

sentiment.body.polarity
string
(query)

This parameter is used for finding stories whose body sentiment is the specified value.

!sentiment.body.polarity
string
(query)

This parameter is used for excluding stories whose body sentiment is the specified value.

media.images.count.min
integer
(query)

This parameter is used for finding stories whose number of images is greater than or equal to the specified value.

media.images.count.max
integer
(query)

This parameter is used for finding stories whose number of images is less than or equal to the specified value.

media.images.width.min
integer
(query)

This parameter is used for finding stories whose width of images are greater than or equal to the specified value.

media.images.width.max
integer
(query)

This parameter is used for finding stories whose width of images are less than or equal to the specified value.

media.images.height.min
integer
(query)

This parameter is used for finding stories whose height of images are greater than or equal to the specified value.

media.images.height.max
integer
(query)

This parameter is used for finding stories whose height of images are less than or equal to the specified value.

media.images.content_length.min
integer
(query)

This parameter is used for finding stories whose images content length are greater than or equal to the specified value.

media.images.content_length.max
integer
(query)

This parameter is used for finding stories whose images content length are less than or equal to the specified value.

media.images.format[]
array [string]
(query)

This parameter is used for finding stories whose images format are the specified value.

Available values: BMP, GIF, JPEG, PNG, TIFF, PSD, ICO, CUR, WEBP, SVG

!media.images.format[]
array [string]
(query)

This parameter is used for excluding stories whose images format are the specified value.

Available values: BMP, GIF, JPEG, PNG, TIFF, PSD, ICO, CUR, WEBP, SVG

media.videos.count.min
integer
(query)

This parameter is used for finding stories whose number of videos is greater than or equal to the specified value.

media.videos.count.max
integer
(query)

This parameter is used for finding stories whose number of videos is less than or equal to the specified value.

author.id[]
array [integer]
(query)

This parameter is used for finding stories whose author id is the specified value.

!author.id[]
array [integer]
(query)

This parameter is used for excluding stories whose author id is the specified value.

author.name
string
(query)

This parameter is used for finding stories whose author full name contains the specified value.

!author.name
string
(query)

This parameter is used for excluding stories whose author full name contains the specified value.

source.id[]
array [integer]
(query)

This parameter is used for finding stories whose source id is the specified value.

!source.id[]
array [integer]
(query)

This parameter is used for excluding stories whose source id is the specified value.

source.name[]
array [string]
(query)

This parameter is used for finding stories whose source name contains the specified value.

!source.name[]
array [string]
(query)

This parameter is used for excluding stories whose source name contains the specified value.

source.domain[]
array [string]
(query)

This parameter is used for finding stories whose source domain is the specified value.

!source.domain[]
array [string]
(query)

This parameter is used for excluding stories whose source domain is the specified value.

source.locations.country[]
array [string]
(query)

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.

!source.locations.country[]
array [string]
(query)

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.

source.locations.state[]
array [string]
(query)

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.

!source.locations.state[]
array [string]
(query)

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.

source.locations.city[]
array [string]
(query)

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.

!source.locations.city[]
array [string]
(query)

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.

source.scopes.country[]
array [string]
(query)

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.

!source.scopes.country[]
array [string]
(query)

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.

source.scopes.state[]
array [string]
(query)

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.

!source.scopes.state[]
array [string]
(query)

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.

source.scopes.city[]
array [string]
(query)

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.

!source.scopes.city[]
array [string]
(query)

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.

source.scopes.level[]
array [string]
(query)

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.

Available values: international, national, local

!source.scopes.level[]
array [string]
(query)

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.

Available values: international, national, local

source.links_in_count.min
integer
(query)

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.

source.links_in_count.max
integer
(query)

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.

source.rankings.alexa.rank.min
integer
(query)

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.

source.rankings.alexa.rank.max
integer
(query)

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.

source.rankings.alexa.country[]
array [string]
(query)

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.

social_shares_count.facebook.min
integer
(query)

This parameter is used for finding stories whose Facebook social shares count is greater than or equal to the specified value.

social_shares_count.facebook.max
integer
(query)

This parameter is used for finding stories whose Facebook social shares count is less than or equal to the specified value.

social_shares_count.google_plus.min
integer
(query)

This parameter is used for finding stories whose Google+ social shares count is greater than or equal to the specified value.

social_shares_count.google_plus.max
integer
(query)

This parameter is used for finding stories whose Google+ social shares count is less than or equal to the specified value.

social_shares_count.linkedin.min
integer
(query)

This parameter is used for finding stories whose LinkedIn social shares count is greater than or equal to the specified value.

social_shares_count.linkedin.max
integer
(query)

This parameter is used for finding stories whose LinkedIn social shares count is less than or equal to the specified value.

social_shares_count.reddit.min
integer
(query)

This parameter is used for finding stories whose Reddit social shares count is greater than or equal to the specified value.

social_shares_count.reddit.max
integer
(query)

This parameter is used for finding stories whose Reddit social shares count is less than or equal to the specified value.

cluster
boolean
(query)

This parameter enables clustering for the returned stories. You can read more about working with clustering here.

Default value: false

cluster.algorithm
string
(query)

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.

Default value: lingo

return[]
array [string]
(query)

This parameter is used for specifying return fields.

Available values: 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

story_id
integer
(query)

A story id

story_url
string
(query)

An article or webpage

story_title
string
(query)

Title of the article

story_body
string
(query)

Body of the article

boost_by
string
(query)

This parameter is used for boosting the result by the specified value.

story_language
string
(query)

This parameter is used for setting the language of the story. It supports ISO 639-1 language codes.

Default value: auto

per_page
integer
(query)

This parameter is used for specifying number of items in each page.

Default value: 3

Response

Code Description
200

An object including an array of related stories

401

Unauthorized

404

Not Found

422

Unprocessable Entity

429

Too Many Requests

  • X-RateLimit-Limit: The number of allowed requests in the current period.
  • X-RateLimit-Remaining: The number of remaining requests in the current period.
  • X-RateLimit-Reset: The remaining window before the rate limit resets in UTC epoch seconds.
500

Internal Server Error

Coverages

from __future__ import print_function
import time
import aylien_news_api
from aylien_news_api.rest import ApiException
from pprint import pprint
configuration = aylien_news_api.Configuration()
# Configure API key authorization: app_id
configuration.api_key['X-AYLIEN-NewsAPI-Application-ID'] = 'YOUR_API_KEY'
# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['X-AYLIEN-NewsAPI-Application-ID'] = 'Bearer'
configuration = aylien_news_api.Configuration()
# Configure API key authorization: app_key
configuration.api_key['X-AYLIEN-NewsAPI-Application-Key'] = 'YOUR_API_KEY'
# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['X-AYLIEN-NewsAPI-Application-Key'] = 'Bearer'

# Defining host is optional and default to https://api.aylien.com/news
configuration.host = "https://api.aylien.com/news"
# Create an instance of the API class
api_instance = aylien_news_api.DefaultApi(aylien_news_api.ApiClient(configuration))

opts = {
  'id': [56], 
  'not_id': [56], 
  'title': 'title_example', 
  'body': 'body_example', 
  'text': 'text_example', 
  'translations_en_title': 'translations_en_title_example', 
  'translations_en_body': 'translations_en_body_example', 
  'translations_en_text': 'translations_en_text_example', 
  'language': ['language_example'], 
  'not_language': ['language_example'], 
  'published_at_start': 'published_at_start_example', 
  'published_at_end': 'published_at_end_example', 
  'categories_taxonomy': 'categories_taxonomy_example', 
  'categories_confident': True, 
  'categories_id': ['categories_id_example'], 
  'not_categories_id': ['categories_id_example'], 
  'categories_level': [56], 
  'not_categories_level': [56], 
  'entities_title_text': ['entities_title_text_example'], 
  'not_entities_title_text': ['entities_title_text_example'], 
  'entities_title_type': ['entities_title_type_example'], 
  'not_entities_title_type': ['entities_title_type_example'], 
  'entities_title_links_dbpedia': ['entities_title_links_dbpedia_example'], 
  'not_entities_title_links_dbpedia': ['entities_title_links_dbpedia_example'], 
  'entities_body_text': ['entities_body_text_example'], 
  'not_entities_body_text': ['entities_body_text_example'], 
  'entities_body_type': ['entities_body_type_example'], 
  'not_entities_body_type': ['entities_body_type_example'], 
  'entities_body_links_dbpedia': ['entities_body_links_dbpedia_example'], 
  'not_entities_body_links_dbpedia': ['entities_body_links_dbpedia_example'], 
  'sentiment_title_polarity': 'sentiment_title_polarity_example', 
  'not_sentiment_title_polarity': 'sentiment_title_polarity_example', 
  'sentiment_body_polarity': 'sentiment_body_polarity_example', 
  'not_sentiment_body_polarity': 'sentiment_body_polarity_example', 
  'media_images_count_min': 56, 
  'media_images_count_max': 56, 
  'media_images_width_min': 56, 
  'media_images_width_max': 56, 
  'media_images_height_min': 56, 
  'media_images_height_max': 56, 
  'media_images_content_length_min': 56, 
  'media_images_content_length_max': 56, 
  'media_images_format': ['media_images_format_example'], 
  'not_media_images_format': ['media_images_format_example'], 
  'media_videos_count_min': 56, 
  'media_videos_count_max': 56, 
  'author_id': [56], 
  'not_author_id': [56], 
  'author_name': 'author_name_example', 
  'not_author_name': 'author_name_example', 
  'source_id': [56], 
  'not_source_id': [56], 
  'source_name': ['source_name_example'], 
  'not_source_name': ['source_name_example'], 
  'source_domain': ['source_domain_example'], 
  'not_source_domain': ['source_domain_example'], 
  'source_locations_country': ['source_locations_country_example'], 
  'not_source_locations_country': ['source_locations_country_example'], 
  'source_locations_state': ['source_locations_state_example'], 
  'not_source_locations_state': ['source_locations_state_example'], 
  'source_locations_city': ['source_locations_city_example'], 
  'not_source_locations_city': ['source_locations_city_example'], 
  'source_scopes_country': ['source_scopes_country_example'], 
  'not_source_scopes_country': ['source_scopes_country_example'], 
  'source_scopes_state': ['source_scopes_state_example'], 
  'not_source_scopes_state': ['source_scopes_state_example'], 
  'source_scopes_city': ['source_scopes_city_example'], 
  'not_source_scopes_city': ['source_scopes_city_example'], 
  'source_scopes_level': ['source_scopes_level_example'], 
  'not_source_scopes_level': ['source_scopes_level_example'], 
  'source_links_in_count_min': 56, 
  'source_links_in_count_max': 56, 
  'source_rankings_alexa_rank_min': 56, 
  'source_rankings_alexa_rank_max': 56, 
  'source_rankings_alexa_country': ['source_rankings_alexa_country_example'], 
  'social_shares_count_facebook_min': 56, 
  'social_shares_count_facebook_max': 56, 
  'social_shares_count_google_plus_min': 56, 
  'social_shares_count_google_plus_max': 56, 
  'social_shares_count_linkedin_min': 56, 
  'social_shares_count_linkedin_max': 56, 
  'social_shares_count_reddit_min': 56, 
  'social_shares_count_reddit_max': 56, 
  'clusters': ['clusters_example'], 
  '_return': ['_return_example'], 
  'story_id': 56, 
  'story_url': 'story_url_example', 
  'story_title': 'story_title_example', 
  'story_body': 'story_body_example', 
  'story_published_at': '2013-10-20T19:20:30+01:00', 
  'story_language': 'auto', 
  'per_page': 3 
}
try:
    # List coverages
    api_response = api_instance.list_coverages(**opts)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling DefaultApi->list_coverages: %s\n" % e)

Coverages works similarly to Related Stories in that it tries to find stories that are similar or related to an input article. However, in addition to that, Coverages enforces stricter similarity rules to capture articles that are coverages of the same topics or events as the source article. This allows you to understand the reach a story has had in the media. For example, you can track the coverage of a press release in various outlets using Coverages.

HTTP Request

  • GET https://api.aylien.com/news/coverages
  • POST https://api.aylien.com/news/coverages

Parameters

Name Description
X-AYLIEN-NewsAPI-Application-ID *
string
(header)
x-data-threescale-name: app_ids

Your access API ID

X-AYLIEN-NewsAPI-Application-Key *
string
(header)
x-data-threescale-name: app_keys

Your access API Key

global_clustering
integer
(query)

This parameter is used for enabling the clustering functionality. Setting the value to 1 enables clustering, 0 disables the functionality. Defaults to 0. Clustering requires an Advanced or Enterprise license key. Start a free trial or contact sales to upgrade your account.

clusters[]
array [integer]
(query)

This parameter is used for finding stories associated with a specific cluster (currently accepts one cluster per search).

translations.title.__
string
(query)

This parameter is used for filtering stories translated from a specified language containing a query term in the title. To specify a language, use the ISO 639-1 standard. Translation requires an Advanced or Enterprise license key. Start a free trial or contact sales to upgrade your account.

translations.body.__
string
(query)

This parameter is used for filtering stories translated from a specified language containing a query term in the body. To specify a language, use the ISO 639-1 standard. Translation requires an Advanced or Enterprise license key. Start a free trial or contact sales to upgrade your account.

id[]
array [integer]
(query)

This parameter is used for finding stories by story id.

!id[]
array [integer]
(query)

This parameter is used for excluding stories by story id.

title
string
(query)

This parameter is used for finding stories whose title contains a specific keyword. It supports boolean operators.

body
string
(query)

This parameter is used for finding stories whose body contains a specific keyword. It supports boolean operators.

text
string
(query)

This parameter is used for finding stories whose title or body contains a specific keyword. It supports boolean operators.

language[]
array [string]
(query)

This parameter is used for finding stories whose language is the specified value. It supports ISO 639-1 language codes.

Available values: en, de, fr, it, es, pt, ru, nl, ar, tr, zh-tw, zh-cn, sv, da.

!language[]
array [string]
(query)

This parameter is used for excluding stories whose language is the specified value. It supports ISO 639-1 language codes.

Available values: en, de, fr, it, es, pt, ru, nl, ar, tr, zh-tw, zh-cn, sv, da.

published_at.start
string
(query)

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.

published_at.end
string
(query)

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.

categories.taxonomy
string
(query)

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.

categories.confident
boolean
(query)

This parameter is used for finding stories whose categories are confident. You can read more about working with categories here.

Default value: true

categories.id[]
array [string]
(query)

This parameter is used for finding stories by categories id. You can read more about working with categories here, and find category ids here.

!categories.id[]
array [string]
(query)

This parameter is used for excluding stories by categories id. You can read more about working with categories here.

categories.level[]
array [integer]
(query)

This parameter is used for finding stories by categories level. You can read more about working with categories here, and find category ids here.

!categories.level[]
array [integer]
(query)

This parameter is used for excluding stories by categories level. You can read more about working with categories here, and find category ids here.

entities.title.text[]
array [string]
(query)

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.

!entities.title.text[]
array [string]
(query)

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.

entities.title.type[]
array [string]
(query)

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.

!entities.title.type[]
array [string]
(query)

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.

entities.title.links.dbpedia[]
array [string]
(query)

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.

!entities.title.links.dbpedia[]
array [string]
(query)

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.

entities.body.text[]
array [string]
(query)

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.

!entities.body.text[]
array [string]
(query)

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.

entities.body.type[]
array [string]
(query)

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.

!entities.body.type[]
array [string]
(query)

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.

entities.body.links.dbpedia[]
array [string]
(query)

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.

!entities.body.links.dbpedia[]
array [string]
(query)

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.

sentiment.title.polarity
string
(query)

This parameter is used for finding stories whose title sentiment is the specified value.

!sentiment.title.polarity
string
(query)

This parameter is used for excluding stories whose title sentiment is the specified value.

sentiment.body.polarity
string
(query)

This parameter is used for finding stories whose body sentiment is the specified value.

!sentiment.body.polarity
string
(query)

This parameter is used for excluding stories whose body sentiment is the specified value.

media.images.count.min
integer
(query)

This parameter is used for finding stories whose number of images is greater than or equal to the specified value.

media.images.count.max
integer
(query)

This parameter is used for finding stories whose number of images is less than or equal to the specified value.

media.images.width.min
integer
(query)

This parameter is used for finding stories whose width of images are greater than or equal to the specified value.

media.images.width.max
integer
(query)

This parameter is used for finding stories whose width of images are less than or equal to the specified value.

media.images.height.min
integer
(query)

This parameter is used for finding stories whose height of images are greater than or equal to the specified value.

media.images.height.max
integer
(query)

This parameter is used for finding stories whose height of images are less than or equal to the specified value.

media.images.content_length.min
integer
(query)

This parameter is used for finding stories whose images content length are greater than or equal to the specified value.

media.images.content_length.max
integer
(query)

This parameter is used for finding stories whose images content length are less than or equal to the specified value.

media.images.format[]
array [string]
(query)

This parameter is used for finding stories whose images format are the specified value.

Available values: BMP, GIF, JPEG, PNG, TIFF, PSD, ICO, CUR, WEBP, SVG

!media.images.format[]
array [string]
(query)

This parameter is used for excluding stories whose images format are the specified value.

Available values: BMP, GIF, JPEG, PNG, TIFF, PSD, ICO, CUR, WEBP, SVG

media.videos.count.min
integer
(query)

This parameter is used for finding stories whose number of videos is greater than or equal to the specified value.

media.videos.count.max
integer
(query)

This parameter is used for finding stories whose number of videos is less than or equal to the specified value.

author.id[]
array [integer]
(query)

This parameter is used for finding stories whose author id is the specified value.

!author.id[]
array [integer]
(query)

This parameter is used for excluding stories whose author id is the specified value.

author.name
string
(query)

This parameter is used for finding stories whose author full name contains the specified value.

!author.name
string
(query)

This parameter is used for excluding stories whose author full name contains the specified value.

source.id[]
array [integer]
(query)

This parameter is used for finding stories whose source id is the specified value.

!source.id[]
array [integer]
(query)

This parameter is used for excluding stories whose source id is the specified value.

source.name[]
array [string]
(query)

This parameter is used for finding stories whose source name contains the specified value.

!source.name[]
array [string]
(query)

This parameter is used for excluding stories whose source name contains the specified value.

source.domain[]
array [string]
(query)

This parameter is used for finding stories whose source domain is the specified value.

!source.domain[]
array [string]
(query)

This parameter is used for excluding stories whose source domain is the specified value.

source.locations.country[]
array [string]
(query)

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.

!source.locations.country[]
array [string]
(query)

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.

source.locations.state[]
array [string]
(query)

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.

!source.locations.state[]
array [string]
(query)

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.

source.locations.city[]
array [string]
(query)

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.

!source.locations.city[]
array [string]
(query)

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.

source.scopes.country[]
array [string]
(query)

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.

!source.scopes.country[]
array [string]
(query)

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.

source.scopes.state[]
array [string]
(query)

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.

!source.scopes.state[]
array [string]
(query)

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.

source.scopes.city[]
array [string]
(query)

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.

!source.scopes.city[]
array [string]
(query)

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.

source.scopes.level[]
array [string]
(query)

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.

Available values: international, national, local

!source.scopes.level[]
array [string]
(query)

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.

Available values: international, national, local

source.links_in_count.min
integer
(query)

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.

source.links_in_count.max
integer
(query)

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.

source.rankings.alexa.rank.min
integer
(query)

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.

source.rankings.alexa.rank.max
integer
(query)

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.

source.rankings.alexa.country[]
array [string]
(query)

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.

social_shares_count.facebook.min
integer
(query)

This parameter is used for finding stories whose Facebook social shares count is greater than or equal to the specified value.

social_shares_count.facebook.max
integer
(query)

This parameter is used for finding stories whose Facebook social shares count is less than or equal to the specified value.

social_shares_count.google_plus.min
integer
(query)

This parameter is used for finding stories whose Google+ social shares count is greater than or equal to the specified value.

social_shares_count.google_plus.max
integer
(query)

This parameter is used for finding stories whose Google+ social shares count is less than or equal to the specified value.

social_shares_count.linkedin.min
integer
(query)

This parameter is used for finding stories whose LinkedIn social shares count is greater than or equal to the specified value.

social_shares_count.linkedin.max
integer
(query)

This parameter is used for finding stories whose LinkedIn social shares count is less than or equal to the specified value.

social_shares_count.reddit.min
integer
(query)

This parameter is used for finding stories whose Reddit social shares count is greater than or equal to the specified value.

social_shares_count.reddit.max
integer
(query)

This parameter is used for finding stories whose Reddit social shares count is less than or equal to the specified value.

cluster
boolean
(query)

This parameter enables clustering for the returned stories. You can read more about working with clustering here.

Default value: false

cluster.algorithm
string
(query)

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.

Default value: lingo

return[]
array [string]
(query)

This parameter is used for specifying return fields.

Available values: 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

story_id
integer
(query)

A story id

story_url
string
(query)

An article or webpage

story_title
string
(query)

Title of the article

story_body
string
(query)

Body of the article

story_published_at
string
(query)

Publish date of the article. If you use a url or title and body of an article for getting coverages, this parameter is required. The format used is a restricted form of the canonical representation of dateTime in the XML Schema specification (ISO 8601).

story_language
string
(query)

This parameter is used for setting the language of the story. It supports ISO 639-1 language codes.

Default value: auto

per_page
integer
(query)

This parameter is used for specifying number of items in each page.

Default value: 3

Response

Code Description
200

An object including an array of coverages

401

Unauthorized

404

Not Found

422

Unprocessable Entity

429

Too Many Requests

  • X-RateLimit-Limit: The number of allowed requests in the current period.
  • X-RateLimit-Remaining: The number of remaining requests in the current period.
  • X-RateLimit-Reset: The remaining window before the rate limit resets in UTC epoch seconds.
500

Internal Server Error

Autocompletes

from __future__ import print_function
import time
import aylien_news_api
from aylien_news_api.rest import ApiException
from pprint import pprint
configuration = aylien_news_api.Configuration()
# Configure API key authorization: app_id
configuration.api_key['X-AYLIEN-NewsAPI-Application-ID'] = 'YOUR_API_KEY'
# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['X-AYLIEN-NewsAPI-Application-ID'] = 'Bearer'
configuration = aylien_news_api.Configuration()
# Configure API key authorization: app_key
configuration.api_key['X-AYLIEN-NewsAPI-Application-Key'] = 'YOUR_API_KEY'
# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['X-AYLIEN-NewsAPI-Application-Key'] = 'Bearer'

# Defining host is optional and default to https://api.aylien.com/news
configuration.host = "https://api.aylien.com/news"
# Create an instance of the API class
api_instance = aylien_news_api.DefaultApi(aylien_news_api.ApiClient(configuration))

opts = {
  'type': 'source_names', 
  'term': 'News',
  'language': 'en',
  'per_page': 3
}

try:
    # List autocompletes
    api_response = api_instance.list_autocompletes(**opts)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling DefaultApi->list_autocompletes: %s\n" % e)

Autocompletes is a helper endpoint that takes a string of characters and an entity type (such as sources, or DBpedia entities) and returns matching entities of the specified type along with additional metadata. For example, if you provide the Autocompletes endpoint with the term "New York C" and select the type dbpedia_resources, the API will return links to the DBpedia resources such as New_York_City, New_York_City_Subway, New_York_City_Police_Department, and so on.

HTTP Request

  • GET https://api.aylien.com/news/autocompletes

Parameters

Name Description
X-AYLIEN-NewsAPI-Application-ID *
string
(header)
x-data-threescale-name: app_ids

Your access API ID

X-AYLIEN-NewsAPI-Application-Key *
string
(header)
x-data-threescale-name: app_keys

Your access API Key

type *
string
(query)

This parameter is used for defining the type of autocompletes. For a list of accepted types, see the table below.

term *
string
(query)

This parameter is used for finding autocomplete objects that contain the specified value.

language
string
(query)

This parameter is used for autocompletes whose language is the specified value. It supports ISO 639-1 language codes.

Default value: en

per_page
integer
(query)

This parameter is used for specifying number of items in each page.

Default value: 3

Autocomplete Types

The Autocompletes endpoint accepts four types as input, two that return information on News API sources and two that return information from DBpedia.

News API DBpedia

source_names

entity_types

source_domains

dbpedia_resources

Response

Code Description
200

An object including an array of autocompletes

401

Unauthorized

404

Not Found

422

Unprocessable Entity

429

Too Many Requests

  • X-RateLimit-Limit: The number of allowed requests in the current period.
  • X-RateLimit-Remaining: The number of remaining requests in the current period.
  • X-RateLimit-Reset: The remaining window before the rate limit resets in UTC epoch seconds.
500

Internal Server Error

Time Series

from __future__ import print_function
import time
import aylien_news_api
from aylien_news_api.rest import ApiException
from pprint import pprint
configuration = aylien_news_api.Configuration()
# Configure API key authorization: app_id
configuration.api_key['X-AYLIEN-NewsAPI-Application-ID'] = 'YOUR_API_KEY'
# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['X-AYLIEN-NewsAPI-Application-ID'] = 'Bearer'
configuration = aylien_news_api.Configuration()
# Configure API key authorization: app_key
configuration.api_key['X-AYLIEN-NewsAPI-Application-Key'] = 'YOUR_API_KEY'
# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['X-AYLIEN-NewsAPI-Application-Key'] = 'Bearer'

# Defining host is optional and default to https://api.aylien.com/news
configuration.host = "https://api.aylien.com/news"
# Create an instance of the API class
api_instance = aylien_news_api.DefaultApi(aylien_news_api.ApiClient(configuration))

opts = {
  'id': [56], 
  'not_id': [56], 
  'title': 'title_example', 
  'body': 'body_example', 
  'text': 'text_example', 
  'translations_en_title': 'translations_en_title_example', 
  'translations_en_body': 'translations_en_body_example', 
  'translations_en_text': 'translations_en_text_example', 
  'language': ['language_example'], 
  'not_language': ['language_example'], 
  'categories_taxonomy': 'categories_taxonomy_example', 
  'categories_confident': True, 
  'categories_id': ['categories_id_example'], 
  'not_categories_id': ['categories_id_example'], 
  'categories_level': [56], 
  'not_categories_level': [56], 
  'entities_title_text': ['entities_title_text_example'], 
  'not_entities_title_text': ['entities_title_text_example'], 
  'entities_title_type': ['entities_title_type_example'], 
  'not_entities_title_type': ['entities_title_type_example'], 
  'entities_title_links_dbpedia': ['entities_title_links_dbpedia_example'], 
  'not_entities_title_links_dbpedia': ['entities_title_links_dbpedia_example'], 
  'entities_body_text': ['entities_body_text_example'], 
  'not_entities_body_text': ['entities_body_text_example'], 
  'entities_body_type': ['entities_body_type_example'], 
  'not_entities_body_type': ['entities_body_type_example'], 
  'entities_body_links_dbpedia': ['entities_body_links_dbpedia_example'], 
  'not_entities_body_links_dbpedia': ['entities_body_links_dbpedia_example'], 
  'sentiment_title_polarity': 'sentiment_title_polarity_example', 
  'not_sentiment_title_polarity': 'sentiment_title_polarity_example', 
  'sentiment_body_polarity': 'sentiment_body_polarity_example', 
  'not_sentiment_body_polarity': 'sentiment_body_polarity_example', 
  'media_images_count_min': 56, 
  'media_images_count_max': 56, 
  'media_images_width_min': 56, 
  'media_images_width_max': 56, 
  'media_images_height_min': 56, 
  'media_images_height_max': 56, 
  'media_images_content_length_min': 56, 
  'media_images_content_length_max': 56, 
  'media_images_format': ['media_images_format_example'], 
  'not_media_images_format': ['media_images_format_example'], 
  'media_videos_count_min': 56, 
  'media_videos_count_max': 56, 
  'author_id': [56], 
  'not_author_id': [56], 
  'author_name': 'author_name_example', 
  'not_author_name': 'author_name_example', 
  'source_id': [56], 
  'not_source_id': [56], 
  'source_name': ['source_name_example'], 
  'not_source_name': ['source_name_example'], 
  'source_domain': ['source_domain_example'], 
  'not_source_domain': ['source_domain_example'], 
  'source_locations_country': ['source_locations_country_example'], 
  'not_source_locations_country': ['source_locations_country_example'], 
  'source_locations_state': ['source_locations_state_example'], 
  'not_source_locations_state': ['source_locations_state_example'], 
  'source_locations_city': ['source_locations_city_example'], 
  'not_source_locations_city': ['source_locations_city_example'], 
  'source_scopes_country': ['source_scopes_country_example'], 
  'not_source_scopes_country': ['source_scopes_country_example'], 
  'source_scopes_state': ['source_scopes_state_example'], 
  'not_source_scopes_state': ['source_scopes_state_example'], 
  'source_scopes_city': ['source_scopes_city_example'], 
  'not_source_scopes_city': ['source_scopes_city_example'], 
  'source_scopes_level': ['source_scopes_level_example'], 
  'not_source_scopes_level': ['source_scopes_level_example'], 
  'source_links_in_count_min': 56, 
  'source_links_in_count_max': 56, 
  'source_rankings_alexa_rank_min': 56, 
  'source_rankings_alexa_rank_max': 56, 
  'source_rankings_alexa_country': ['source_rankings_alexa_country_example'], 
  'social_shares_count_facebook_min': 56, 
  'social_shares_count_facebook_max': 56, 
  'social_shares_count_google_plus_min': 56, 
  'social_shares_count_google_plus_max': 56, 
  'social_shares_count_linkedin_min': 56, 
  'social_shares_count_linkedin_max': 56, 
  'social_shares_count_reddit_min': 56, 
  'social_shares_count_reddit_max': 56, 
  'published_at_start': 'NOW-7DAYS/DAY', 
  'published_at_end': 'NOW/DAY', 
  'period': '+1DAY' 
}

try:
    # List time series
    api_response = api_instance.list_time_series(**opts)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling DefaultApi->list_time_series: %s\n" % e)

Time Series allows you to track changes in quantitative values contained in stories over time. This information can be anything from mentions of a topic or entities, sentiment about a topic, or the volume of stories published by a source, to name but a few. The full list of parameters is given below. Using the Date Math Syntax, you can easily set your query to return information from any time period, from the current point in time to when the News API started collecting stories. The returned information can be rounded to a time also specified by you, for example by setting the results into hourly, daily, or weekly data points.

HTTP Request

  • GET https://api.aylien.com/news/time_series

Parameters

Name Description
X-AYLIEN-NewsAPI-Application-ID *
string
(header)
x-data-threescale-name: app_ids

Your access API ID

X-AYLIEN-NewsAPI-Application-Key *
string
(header)
x-data-threescale-name: app_keys

Your access API Key

global_clustering
integer
(query)

This parameter is used for enabling the clustering functionality. Setting the value to 1 enables clustering, 0 disables the functionality. Defaults to 0. Clustering requires an Advanced or Enterprise license key. Start a free trial or contact sales to upgrade your account.

clusters[]
array [integer]
(query)

This parameter is used for finding stories associated with a specific cluster (currently accepts one cluster per search).

translations.title.__
string
(query)

This parameter is used for filtering stories translated from a specified language containing a query term in the title. To specify a language, use the ISO 639-1 standard. Translation requires an Advanced or Enterprise license key. Start a free trial or contact sales to upgrade your account.

translations.body.__
string
(query)

This parameter is used for filtering stories translated from a specified language containing a query term in the body. To specify a language, use the ISO 639-1 standard. Translation requires an Advanced or Enterprise license key. Start a free trial or contact sales to upgrade your account.

id[]
array [integer]
(query)

This parameter is used for finding stories by story id.

!id[]
array [integer]
(query)

This parameter is used for excluding stories by story id.

title
string
(query)

This parameter is used for finding stories whose title contains a specific keyword. It supports boolean operators.

body
string
(query)

This parameter is used for finding stories whose body contains a specific keyword. It supports boolean operators.

text
string
(query)

This parameter is used for finding stories whose title or body contains a specific keyword. It supports boolean operators.

language[]
array [string]
(query)

This parameter is used for finding stories whose language is the specified value. It supports ISO 639-1 language codes.

Available values: en, de, fr, it, es, pt, ru, nl, ar, tr, zh-tw, zh-cn, sv, da.

!language[]
array [string]
(query)

This parameter is used for excluding stories whose language is the specified value. It supports ISO 639-1 language codes.

Available values: en, de, fr, it, es, pt, ru, nl, ar, tr, zh-tw, zh-cn, sv, da.

categories.taxonomy
string
(query)

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.

categories.confident
boolean
(query)

This parameter is used for finding stories whose categories are confident. You can read more about working with categories here.

Default value: true

categories.id[]
array [string]
(query)

This parameter is used for finding stories by categories id. You can read more about working with categories here, and find category ids here.

!categories.id[]
array [string]
(query)

This parameter is used for excluding stories by categories id. You can read more about working with categories here, and find category ids here.

categories.level[]
array [integer]
(query)

This parameter is used for finding stories by categories level. You can read more about working with categories here, and find category ids here.

!categories.level[]
array [integer]
(query)

This parameter is used for excluding stories by categories level. You can read more about working with categories here, and find category ids here.

entities.title.text[]
array [string]
(query)

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.

!entities.title.text[]
array [string]
(query)

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.

entities.title.type[]
array [string]
(query)

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.

!entities.title.type[]
array [string]
(query)

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.

entities.title.links.dbpedia[]
array [string]
(query)

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.

!entities.title.links.dbpedia[]
array [string]
(query)

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.

entities.body.text[]
array [string]
(query)

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.

!entities.body.text[]
array [string]
(query)

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.

entities.body.type[]
array [string]
(query)

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.

!entities.body.type[]
array [string]
(query)

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.

entities.body.links.dbpedia[]
array [string]
(query)

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.

!entities.body.links.dbpedia[]
array [string]
(query)

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.

sentiment.title.polarity
string
(query)

This parameter is used for finding stories whose title sentiment is the specified value.

!sentiment.title.polarity
string
(query)

This parameter is used for excluding stories whose title sentiment is the specified value.

sentiment.body.polarity
string
(query)

This parameter is used for finding stories whose body sentiment is the specified value.

!sentiment.body.polarity
string
(query)

This parameter is used for excluding stories whose body sentiment is the specified value.

media.images.count.min
integer
(query)

This parameter is used for finding stories whose number of images is greater than or equal to the specified value.

media.images.count.max
integer
(query)

This parameter is used for finding stories whose number of images is less than or equal to the specified value.

media.images.width.min
integer
(query)

This parameter is used for finding stories whose width of images are greater than or equal to the specified value.

media.images.width.max
integer
(query)

This parameter is used for finding stories whose width of images are less than or equal to the specified value.

media.images.height.min
integer
(query)

This parameter is used for finding stories whose height of images are greater than or equal to the specified value.

media.images.height.max
integer
(query)

This parameter is used for finding stories whose height of images are less than or equal to the specified value.

media.images.content_length.min
integer
(query)

This parameter is used for finding stories whose images content length are greater than or equal to the specified value.

media.images.content_length.max
integer
(query)

This parameter is used for finding stories whose images content length are less than or equal to the specified value.

media.images.format[]
array [string]
(query)

This parameter is used for finding stories whose images format are the specified value.

Available values: BMP, GIF, JPEG, PNG, TIFF, PSD, ICO, CUR, WEBP, SVG

!media.images.format[]
array [string]
(query)

This parameter is used for excluding stories whose images format are the specified value.

Available values: BMP, GIF, JPEG, PNG, TIFF, PSD, ICO, CUR, WEBP, SVG

media.videos.count.min
integer
(query)

This parameter is used for finding stories whose number of videos is greater than or equal to the specified value.

media.videos.count.max
integer
(query)

This parameter is used for finding stories whose number of videos is less than or equal to the specified value.

author.id[]
array [integer]
(query)

This parameter is used for finding stories whose author id is the specified value.

!author.id[]
array [integer]
(query)

This parameter is used for excluding stories whose author id is the specified value.

author.name
string
(query)

This parameter is used for finding stories whose author full name contains the specified value.

!author.name
string
(query)

This parameter is used for excluding stories whose author full name contains the specified value.

source.id[]
array [integer]
(query)

This parameter is used for finding stories whose source id is the specified value.

!source.id[]
array [integer]
(query)

This parameter is used for excluding stories whose source id is the specified value.

source.name[]
array [string]
(query)

This parameter is used for finding stories whose source name contains the specified value.

!source.name[]
array [string]
(query)

This parameter is used for excluding stories whose source name contains the specified value.

source.domain[]
array [string]
(query)

This parameter is used for finding stories whose source domain is the specified value.

!source.domain[]
array [string]
(query)

This parameter is used for excluding stories whose source domain is the specified value.

source.locations.country[]
array [string]
(query)

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.

!source.locations.country[]
array [string]
(query)

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.

source.locations.state[]
array [string]
(query)

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.

!source.locations.state[]
array [string]
(query)

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.

source.locations.city[]
array [string]
(query)

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.

!source.locations.city[]
array [string]
(query)

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.

source.scopes.country[]
array [string]
(query)

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.

!source.scopes.country[]
array [string]
(query)

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.

source.scopes.state[]
array [string]
(query)

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.

!source.scopes.state[]
array [string]
(query)

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.

source.scopes.city[]
array [string]
(query)

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.

!source.scopes.city[]
array [string]
(query)

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.

source.scopes.level[]
array [string]
(query)

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.

Available values: international, national, local

!source.scopes.level[]
array [string]
(query)

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.

Available values: international, national, local

source.links_in_count.min
integer
(query)

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.

source.links_in_count.max
integer
(query)

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.

source.rankings.alexa.rank.min
integer
(query)

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.

source.rankings.alexa.rank.max
integer
(query)

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.

source.rankings.alexa.country[]
array [string]
(query)

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.

social_shares_count.facebook.min
integer
(query)

This parameter is used for finding stories whose Facebook social shares count is greater than or equal to the specified value.

social_shares_count.facebook.max
integer
(query)

This parameter is used for finding stories whose Facebook social shares count is less than or equal to the specified value.

social_shares_count.google_plus.min
integer
(query)

This parameter is used for finding stories whose Google+ social shares count is greater than or equal to the specified value.

social_shares_count.google_plus.max
integer
(query)

This parameter is used for finding stories whose Google+ social shares count is less than or equal to the specified value.

social_shares_count.linkedin.min
integer
(query)

This parameter is used for finding stories whose LinkedIn social shares count is greater than or equal to the specified value.

social_shares_count.linkedin.max
integer
(query)

This parameter is used for finding stories whose LinkedIn social shares count is less than or equal to the specified value.

social_shares_count.reddit.min
integer
(query)

This parameter is used for finding stories whose Reddit social shares count is greater than or equal to the specified value.

social_shares_count.reddit.max
integer
(query)

This parameter is used for finding stories whose Reddit social shares count is less than or equal to the specified value.

published_at.start
string
(query)

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.

Default value: NOW-7DAYS/DAY

published_at.end
string
(query)

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.

Default value: NOW/DAY

period
string
(query)

The size of each date range is expressed as an interval to be added to the lower bound. It supports Date Math Syntax. Valid options are + following an integer number greater than 0 and one of the Date Math keywords. e.g. +1DAY, +2MINUTES and +1MONTH. Here are Supported keywords.

Default value: +1DAY

Response

Code Description
200

An object including an array of time series

401

Unauthorized

404

Not Found

422

Unprocessable Entity

429

Too Many Requests

  • X-RateLimit-Limit: The number of allowed requests in the current period.
  • X-RateLimit-Remaining: The number of remaining requests in the current period.
  • X-RateLimit-Reset: The remaining window before the rate limit resets in UTC epoch seconds.
500

Internal Server Error

Trends

from __future__ import print_function
import time
import aylien_news_api
from aylien_news_api.rest import ApiException
from pprint import pprint
configuration = aylien_news_api.Configuration()
# Configure API key authorization: app_id
configuration.api_key['X-AYLIEN-NewsAPI-Application-ID'] = 'YOUR_API_KEY'
# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['X-AYLIEN-NewsAPI-Application-ID'] = 'Bearer'
configuration = aylien_news_api.Configuration()
# Configure API key authorization: app_key
configuration.api_key['X-AYLIEN-NewsAPI-Application-Key'] = 'YOUR_API_KEY'
# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['X-AYLIEN-NewsAPI-Application-Key'] = 'Bearer'

# Defining host is optional and default to https://api.aylien.com/news
configuration.host = "https://api.aylien.com/news"
# Create an instance of the API class
api_instance = aylien_news_api.DefaultApi(aylien_news_api.ApiClient(configuration))

field = 'keywords'
opts = {
  'id': [56], 
  'not_id': [56], 
  'title': 'title_example', 
  'body': 'body_example', 
  'text': 'text_example', 
  'translations_en_title': 'translations_en_title_example', 
  'translations_en_body': 'translations_en_body_example', 
  'translations_en_text': 'translations_en_text_example', 
  'language': ['language_example'], 
  'not_language': ['language_example'], 
  'published_at_start': 'published_at_start_example', 
  'published_at_end': 'published_at_end_example', 
  'categories_taxonomy': 'categories_taxonomy_example', 
  'categories_confident': True, 
  'categories_id': ['categories_id_example'], 
  'not_categories_id': ['categories_id_example'], 
  'categories_level': [56], 
  'not_categories_level': [56], 
  'entities_title_text': ['entities_title_text_example'], 
  'not_entities_title_text': ['entities_title_text_example'], 
  'entities_title_type': ['entities_title_type_example'], 
  'not_entities_title_type': ['entities_title_type_example'], 
  'entities_title_links_dbpedia': ['entities_title_links_dbpedia_example'], 
  'not_entities_title_links_dbpedia': ['entities_title_links_dbpedia_example'], 
  'entities_body_text': ['entities_body_text_example'], 
  'not_entities_body_text': ['entities_body_text_example'], 
  'entities_body_type': ['entities_body_type_example'], 
  'not_entities_body_type': ['entities_body_type_example'], 
  'entities_body_links_dbpedia': ['entities_body_links_dbpedia_example'], 
  'not_entities_body_links_dbpedia': ['entities_body_links_dbpedia_example'], 
  'sentiment_title_polarity': 'sentiment_title_polarity_example', 
  'not_sentiment_title_polarity': 'sentiment_title_polarity_example', 
  'sentiment_body_polarity': 'sentiment_body_polarity_example', 
  'not_sentiment_body_polarity': 'sentiment_body_polarity_example', 
  'media_images_count_min': 56, 
  'media_images_count_max': 56, 
  'media_images_width_min': 56, 
  'media_images_width_max': 56, 
  'media_images_height_min': 56, 
  'media_images_height_max': 56, 
  'media_images_content_length_min': 56, 
  'media_images_content_length_max': 56, 
  'media_images_format': ['media_images_format_example'], 
  'not_media_images_format': ['media_images_format_example'], 
  'media_videos_count_min': 56, 
  'media_videos_count_max': 56, 
  'author_id': [56], 
  'not_author_id': [56], 
  'author_name': 'author_name_example', 
  'not_author_name': 'author_name_example', 
  'source_id': [56], 
  'not_source_id': [56], 
  'source_name': ['source_name_example'], 
  'not_source_name': ['source_name_example'], 
  'source_domain': ['source_domain_example'], 
  'not_source_domain': ['source_domain_example'], 
  'source_locations_country': ['source_locations_country_example'], 
  'not_source_locations_country': ['source_locations_country_example'], 
  'source_locations_state': ['source_locations_state_example'], 
  'not_source_locations_state': ['source_locations_state_example'], 
  'source_locations_city': ['source_locations_city_example'], 
  'not_source_locations_city': ['source_locations_city_example'], 
  'source_scopes_country': ['source_scopes_country_example'], 
  'not_source_scopes_country': ['source_scopes_country_example'], 
  'source_scopes_state': ['source_scopes_state_example'], 
  'not_source_scopes_state': ['source_scopes_state_example'], 
  'source_scopes_city': ['source_scopes_city_example'], 
  'not_source_scopes_city': ['source_scopes_city_example'], 
  'source_scopes_level': ['source_scopes_level_example'], 
  'not_source_scopes_level': ['source_scopes_level_example'], 
  'source_links_in_count_min': 56, 
  'source_links_in_count_max': 56, 
  'source_rankings_alexa_rank_min': 56, 
  'source_rankings_alexa_rank_max': 56, 
  'source_rankings_alexa_country': ['source_rankings_alexa_country_example'], 
  'social_shares_count_facebook_min': 56, 
  'social_shares_count_facebook_max': 56, 
  'social_shares_count_google_plus_min': 56, 
  'social_shares_count_google_plus_max': 56, 
  'social_shares_count_linkedin_min': 56, 
  'social_shares_count_linkedin_max': 56, 
  'social_shares_count_reddit_min': 56, 
  'social_shares_count_reddit_max': 56
}

try:
    # List trends
    api_response = api_instance.list_trends(field, **opts)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling DefaultApi->list_trends: %s\n" % e)

Trends allows you to identify the most-frequent values for categorical attributes contained in stories, e.g. most frequent entities, concepts or keywords. This endpoint allows you to set parameters like a time period, a subject category, or an entity, and it will return the most mentioned entities or keywords that are mentioned in relation to your query.

HTTP Request

  • GET https://api.aylien.com/news/trends

Parameters

Name Description
X-AYLIEN-NewsAPI-Application-ID *
string
(header)
x-data-threescale-name: app_ids

Your access API ID

X-AYLIEN-NewsAPI-Application-Key *
string
(header)
x-data-threescale-name: app_keys

Your access API Key

global_clustering
integer
(query)

This parameter is used for enabling the clustering functionality. Setting the value to 1 enables clustering, 0 disables the functionality. Defaults to 0. Clustering requires an Advanced or Enterprise license key. Start a free trial or contact sales to upgrade your account.

clusters[]
array [integer]
(query)

This parameter is used for finding stories associated with a specific cluster (currently accepts one cluster per search).

translations.title.__
string
(query)

This parameter is used for filtering stories translated from a specified language containing a query term in the title. To specify a language, use the ISO 639-1 standard. Translation requires an Advanced or Enterprise license key. Start a free trial or contact sales to upgrade your account.

translations.body.__
string
(query)

This parameter is used for filtering stories translated from a specified language containing a query term in the body. To specify a language, use the ISO 639-1 standard. Translation requires an Advanced or Enterprise license key. Start a free trial or contact sales to upgrade your account.

id[]
array [integer]
(query)

This parameter is used for finding stories by story id.

!id[]
array [integer]
(query)

This parameter is used for excluding stories by story id.

title
string
(query)

This parameter is used for finding stories whose title contains a specific keyword. It supports boolean operators.

body
string
(query)

This parameter is used for finding stories whose body contains a specific keyword. It supports boolean operators.

text
string
(query)

This parameter is used for finding stories whose title or body contains a specific keyword. It supports boolean operators.

language[]
array [string]
(query)

This parameter is used for finding stories whose language is the specified value. It supports ISO 639-1 language codes.

Available values: en, de, fr, it, es, pt, ru, nl, ar, tr, zh-tw, zh-cn, sv, da.

!language[]
array [string]
(query)

This parameter is used for excluding stories whose language is the specified value. It supports ISO 639-1 language codes.

Available values: en, de, fr, it, es, pt, ru, nl, ar, tr, zh-tw, zh-cn, sv, da.

published_at.start
string
(query)

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.

published_at.end
string
(query)

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.

categories.taxonomy
string
(query)

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.

categories.confident
boolean
(query)

This parameter is used for finding stories whose categories are confident. You can read more about working with categories here.

Default value: true

categories.id[]
array [string]
(query)

This parameter is used for finding stories by categories id. You can read more about working with categories here, and find category ids here.

!categories.id[]
array [string]
(query)

This parameter is used for excluding stories by categories id. You can read more about working with categories here, and find category ids here.

categories.level[]
array [integer]
(query)

This parameter is used for finding stories by categories level. You can read more about working with categories here, and find category ids here.

!categories.level[]
array [integer]
(query)

This parameter is used for excluding stories by categories level. You can read more about working with categories here, and find category ids here.

entities.title.text[]
array [string]
(query)

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.

!entities.title.text[]
array [string]
(query)

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.

entities.title.type[]
array [string]
(query)

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.

!entities.title.type[]
array [string]
(query)

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.

entities.title.links.dbpedia[]
array [string]
(query)

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.

!entities.title.links.dbpedia[]
array [string]
(query)

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.

entities.body.text[]
array [string]
(query)

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.

!entities.body.text[]
array [string]
(query)

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.

entities.body.type[]
array [string]
(query)

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.

!entities.body.type[]
array [string]
(query)

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.

entities.body.links.dbpedia[]
array [string]
(query)

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.

!entities.body.links.dbpedia[]
array [string]
(query)

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.

sentiment.title.polarity
string
(query)

This parameter is used for finding stories whose title sentiment is the specified value.

!sentiment.title.polarity
string
(query)

This parameter is used for excluding stories whose title sentiment is the specified value.

sentiment.body.polarity
string
(query)

This parameter is used for finding stories whose body sentiment is the specified value.

!sentiment.body.polarity
string
(query)

This parameter is used for excluding stories whose body sentiment is the specified value.

media.images.count.min
integer
(query)

This parameter is used for finding stories whose number of images is greater than or equal to the specified value.

media.images.count.max
integer
(query)

This parameter is used for finding stories whose number of images is less than or equal to the specified value.

media.images.width.min
integer
(query)

This parameter is used for finding stories whose width of images are greater than or equal to the specified value.

media.images.width.max
integer
(query)

This parameter is used for finding stories whose width of images are less than or equal to the specified value.

media.images.height.min
integer
(query)

This parameter is used for finding stories whose height of images are greater than or equal to the specified value.

media.images.height.max
integer
(query)

This parameter is used for finding stories whose height of images are less than or equal to the specified value.

media.images.content_length.min
integer
(query)

This parameter is used for finding stories whose images content length are greater than or equal to the specified value.

media.images.content_length.max
integer
(query)

This parameter is used for finding stories whose images content length are less than or equal to the specified value.

media.images.format[]
array [string]
(query)

This parameter is used for finding stories whose images format are the specified value.

Available values: BMP, GIF, JPEG, PNG, TIFF, PSD, ICO, CUR, WEBP, SVG

!media.images.format[]
array [string]
(query)

This parameter is used for excluding stories whose images format are the specified value.

Available values: BMP, GIF, JPEG, PNG, TIFF, PSD, ICO, CUR, WEBP, SVG

media.videos.count.min
integer
(query)

This parameter is used for finding stories whose number of videos is greater than or equal to the specified value.

media.videos.count.max
integer
(query)

This parameter is used for finding stories whose number of videos is less than or equal to the specified value.

author.id[]
array [integer]
(query)

This parameter is used for finding stories whose author id is the specified value.

!author.id[]
array [integer]
(query)

This parameter is used for excluding stories whose author id is the specified value.

author.name
string
(query)

This parameter is used for finding stories whose author full name contains the specified value.

!author.name
string
(query)

This parameter is used for excluding stories whose author full name contains the specified value.

source.id[]
array [integer]
(query)

This parameter is used for finding stories whose source id is the specified value.

!source.id[]
array [integer]
(query)

This parameter is used for excluding stories whose source id is the specified value.

source.name[]
array [string]
(query)

This parameter is used for finding stories whose source name contains the specified value.

!source.name[]
array [string]
(query)

This parameter is used for excluding stories whose source name contains the specified value.

source.domain[]
array [string]
(query)

This parameter is used for finding stories whose source domain is the specified value.

!source.domain[]
array [string]
(query)

This parameter is used for excluding stories whose source domain is the specified value.

source.locations.country[]
array [string]
(query)

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.

!source.locations.country[]
array [string]
(query)

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.

source.locations.state[]
array [string]
(query)

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.

!source.locations.state[]
array [string]
(query)

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.

source.locations.city[]
array [string]
(query)

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.

!source.locations.city[]
array [string]
(query)

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.

source.scopes.country[]
array [string]
(query)

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.

!source.scopes.country[]
array [string]
(query)

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.

source.scopes.state[]
array [string]
(query)

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.

!source.scopes.state[]
array [string]
(query)

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.

source.scopes.city[]
array [string]
(query)

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.

!source.scopes.city[]
array [string]
(query)

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.

source.scopes.level[]
array [string]
(query)

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.

Available values: international, national, local

!source.scopes.level[]
array [string]
(query)

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.

Available values: international, national, local

source.links_in_count.min
integer
(query)

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.

source.links_in_count.max
integer
(query)

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.

source.rankings.alexa.rank.min
integer
(query)

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.

source.rankings.alexa.rank.max
integer
(query)

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.

source.rankings.alexa.country[]
array [string]
(query)

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.

social_shares_count.facebook.min
integer
(query)

This parameter is used for finding stories whose Facebook social shares count is greater than or equal to the specified value.

social_shares_count.facebook.max
integer
(query)

This parameter is used for finding stories whose Facebook social shares count is less than or equal to the specified value.

social_shares_count.google_plus.min
integer
(query)

This parameter is used for finding stories whose Google+ social shares count is greater than or equal to the specified value.

social_shares_count.google_plus.max
integer
(query)

This parameter is used for finding stories whose Google+ social shares count is less than or equal to the specified value.

social_shares_count.linkedin.min
integer
(query)

This parameter is used for finding stories whose LinkedIn social shares count is greater than or equal to the specified value.

social_shares_count.linkedin.max
integer
(query)

This parameter is used for finding stories whose LinkedIn social shares count is less than or equal to the specified value.

social_shares_count.reddit.min
integer
(query)

This parameter is used for finding stories whose Reddit social shares count is greater than or equal to the specified value.

social_shares_count.reddit.max
integer
(query)

This parameter is used for finding stories whose Reddit social shares count is less than or equal to the specified value.

field *
string
(query)

This parameter is used to specify the trend field.

Response

Code Description
200

An object including an array of trends

401

Unauthorized

404

Not Found

422

Unprocessable Entity

429

Too Many Requests

  • X-RateLimit-Limit: The number of allowed requests in the current period.
  • X-RateLimit-Remaining: The number of remaining requests in the current period.
  • X-RateLimit-Reset: The remaining window before the rate limit resets in UTC epoch seconds.
500

Internal Server Error

Histograms

from __future__ import print_function
import time
import aylien_news_api
from aylien_news_api.rest import ApiException
from pprint import pprint
configuration = aylien_news_api.Configuration()
# Configure API key authorization: app_id
configuration.api_key['X-AYLIEN-NewsAPI-Application-ID'] = 'YOUR_API_KEY'
# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['X-AYLIEN-NewsAPI-Application-ID'] = 'Bearer'
configuration = aylien_news_api.Configuration()
# Configure API key authorization: app_key
configuration.api_key['X-AYLIEN-NewsAPI-Application-Key'] = 'YOUR_API_KEY'
# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['X-AYLIEN-NewsAPI-Application-Key'] = 'Bearer'

# Defining host is optional and default to https://api.aylien.com/news
configuration.host = "https://api.aylien.com/news"
# Create an instance of the API class
api_instance = aylien_news_api.DefaultApi(aylien_news_api.ApiClient(configuration))
field = 'social_shares_count' 

opts = {
  'id': [56],
  'not_id': [56],
  'title': 'title_example',
  'body': 'body_example',
  'text': 'text_example',
  'translations_en_title': 'translations_en_title_example',
  'translations_en_body': 'translations_en_body_example',
  'translations_en_text': 'translations_en_text_example',
  'language': ['language_example'], 
  'not_language': ['language_example'], 
  'published_at_start': 'published_at_start_example',
  'published_at_end': 'published_at_end_example',
  'categories_taxonomy': 'categories_taxonomy_example',
  'categories_confident': True, 
  'categories_id': ['categories_id_example'], 
  'not_categories_id': ['categories_id_example'], 
  'categories_level': [56], 
  'not_categories_level': [56], 
  'entities_title_text': ['entities_title_text_example'], 
  'not_entities_title_text': ['entities_title_text_example'], 
  'entities_title_type': ['entities_title_type_example'], 
  'not_entities_title_type': ['entities_title_type_example'], 
  'entities_title_links_dbpedia': ['entities_title_links_dbpedia_example'], 
  'not_entities_title_links_dbpedia': ['entities_title_links_dbpedia_example'], 
  'entities_body_text': ['entities_body_text_example'], 
  'not_entities_body_text': ['entities_body_text_example'], 
  'entities_body_type': ['entities_body_type_example'], 
  'not_entities_body_type': ['entities_body_type_example'], 
  'entities_body_links_dbpedia': ['entities_body_links_dbpedia_example'], 
  'not_entities_body_links_dbpedia': ['entities_body_links_dbpedia_example'], 
  'sentiment_title_polarity': 'sentiment_title_polarity_example',
  'not_sentiment_title_polarity': 'sentiment_title_polarity_example',
  'sentiment_body_polarity': 'sentiment_body_polarity_example',
  'not_sentiment_body_polarity': 'sentiment_body_polarity_example',
  'media_images_count_min': 56, 
  'media_images_count_max': 56, 
  'media_images_width_min': 56, 
  'media_images_width_max': 56, 
  'media_images_height_min': 56, 
  'media_images_height_max': 56, 
  'media_images_content_length_min': 56, 
  'media_images_content_length_max': 56, 
  'media_images_format': ['media_images_format_example'], 
  'not_media_images_format': ['media_images_format_example'], 
  'media_videos_count_min': 56, 
  'media_videos_count_max': 56, 
  'author_id': [56], 
  'not_author_id': [56], 
  'author_name': 'author_name_example',
  'not_author_name': 'author_name_example',
  'source_id': [56], 
  'not_source_id': [56], 
  'source_name': ['source_name_example'], 
  'not_source_name': ['source_name_example'], 
  'source_domain': ['source_domain_example'], 
  'not_source_domain': ['source_domain_example'], 
  'source_locations_country': ['source_locations_country_example'], 
  'not_source_locations_country': ['source_locations_country_example'], 
  'source_locations_state': ['source_locations_state_example'], 
  'not_source_locations_state': ['source_locations_state_example'], 
  'source_locations_city': ['source_locations_city_example'], 
  'not_source_locations_city': ['source_locations_city_example'], 
  'source_scopes_country': ['source_scopes_country_example'], 
  'not_source_scopes_country': ['source_scopes_country_example'], 
  'source_scopes_state': ['source_scopes_state_example'], 
  'not_source_scopes_state': ['source_scopes_state_example'], 
  'source_scopes_city': ['source_scopes_city_example'], 
  'not_source_scopes_city': ['source_scopes_city_example'], 
  'source_scopes_level': ['source_scopes_level_example'], 
  'not_source_scopes_level': ['source_scopes_level_example'], 
  'source_links_in_count_min': 56, 
  'source_links_in_count_max': 56, 
  'source_rankings_alexa_rank_min': 56, 
  'source_rankings_alexa_rank_max': 56, 
  'source_rankings_alexa_country': ['source_rankings_alexa_country_example'], 
  'social_shares_count_facebook_min': 56, 
  'social_shares_count_facebook_max': 56, 
  'social_shares_count_google_plus_min': 56, 
  'social_shares_count_google_plus_max': 56, 
  'social_shares_count_linkedin_min': 56, 
  'social_shares_count_linkedin_max': 56, 
  'social_shares_count_reddit_min': 56, 
  'social_shares_count_reddit_max': 56, 
  'interval_start': 56, 
  'interval_end': 56, 
  'interval_width': 56 
  }

try:
    # List histograms
    api_response = api_instance.list_histograms(field=field, **opts)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling DefaultApi->list_histograms: %s\n" % e)

Histograms allows you to retrieve a histogram snapshot of any quantitative attribute of articles that match your query. The histogram will show the distribution of articles over a range of values for your specified parameter. For example, to understand how long articles written by a particular journalist are on average, you can use Histograms and specify the journalist's name using author.id[] or author.name, then set the field value to words_count to retrieve a histogram that shows how many of this author's articles are how long (in words). You can also specify the histogram's start and endpoints, as well as the bin width using interval.start, interval.end and interval.width respectively.

HTTP Request

  • GET https://api.aylien.com/news/histograms

Parameters

Name Description
X-AYLIEN-NewsAPI-Application-ID *
string
(header)
x-data-threescale-name: app_ids

Your access API ID

X-AYLIEN-NewsAPI-Application-Key *
string
(header)
x-data-threescale-name: app_keys

Your access API Key

global_clustering
integer
(query)

This parameter is used for enabling the clustering functionality. Setting the value to 1 enables clustering, 0 disables the functionality. Defaults to 0. Clustering requires an Advanced or Enterprise license key. Start a free trial or contact sales to upgrade your account.

clusters[]
array [integer]
(query)

This parameter is used for finding stories associated with a specific cluster (currently accepts one cluster per search).

translations.title.__
string
(query)

This parameter is used for filtering stories translated from a specified language containing a query term in the title. To specify a language, use the ISO 639-1 standard. Translation requires an Advanced or Enterprise license key. Start a free trial or contact sales to upgrade your account.

translations.body.__
string
(query)

This parameter is used for filtering stories translated from a specified language containing a query term in the body. To specify a language, use the ISO 639-1 standard. Translation requires an Advanced or Enterprise license key. Start a free trial or contact sales to upgrade your account.

id[]
array [integer]
(query)

This parameter is used for finding stories by story id.

!id[]
array [integer]
(query)

This parameter is used for excluding stories by story id.

title
string
(query)

This parameter is used for finding stories whose title contains a specific keyword. It supports boolean operators.

body
string
(query)

This parameter is used for finding stories whose body contains a specific keyword. It supports boolean operators.

text
string
(query)

This parameter is used for finding stories whose title or body contains a specific keyword. It supports boolean operators.

language[]
array [string]
(query)

This parameter is used for finding stories whose language is the specified value. It supports ISO 639-1 language codes.

Available values: en, de, fr, it, es, pt, ru, nl, ar, tr, zh-tw, zh-cn, sv, da.

!language[]
array [string]
(query)

This parameter is used for excluding stories whose language is the specified value. It supports ISO 639-1 language codes.

Available values: en, de, fr, it, es, pt, ru, nl, ar, tr, zh-tw, zh-cn, sv, da.

published_at.start
string
(query)

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.

published_at.end
string
(query)

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.

categories.taxonomy
string
(query)

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.

categories.confident
boolean
(query)

This parameter is used for finding stories whose categories are confident. You can read more about working with categories here.

Default value: true

categories.id[]
array [string]
(query)

This parameter is used for finding stories by categories id. You can read more about working with categories here, and find category ids here.

!categories.id[]
array [string]
(query)

This parameter is used for excluding stories by categories id. You can read more about working with categories here, and find category ids here.

categories.level[]
array [integer]
(query)

This parameter is used for finding stories by categories level. You can read more about working with categories here, and find category ids here.

!categories.level[]
array [integer]
(query)

This parameter is used for excluding stories by categories level. You can read more about working with categories here, and find category ids here.

entities.title.text[]
array [string]
(query)

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.

!entities.title.text[]
array [string]
(query)

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.

entities.title.type[]
array [string]
(query)

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.

!entities.title.type[]
array [string]
(query)

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.

entities.title.links.dbpedia[]
array [string]
(query)

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.

!entities.title.links.dbpedia[]
array [string]
(query)

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.

entities.body.text[]
array [string]
(query)

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.

!entities.body.text[]
array [string]
(query)

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.

entities.body.type[]
array [string]
(query)

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.

!entities.body.type[]
array [string]
(query)

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.

entities.body.links.dbpedia[]
array [string]
(query)

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.

!entities.body.links.dbpedia[]
array [string]
(query)

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.

sentiment.title.polarity
string
(query)

This parameter is used for finding stories whose title sentiment is the specified value.

!sentiment.title.polarity
string
(query)

This parameter is used for excluding stories whose title sentiment is the specified value.

sentiment.body.polarity
string
(query)

This parameter is used for finding stories whose body sentiment is the specified value.

!sentiment.body.polarity
string
(query)

This parameter is used for excluding stories whose body sentiment is the specified value.

media.images.count.min
integer
(query)

This parameter is used for finding stories whose number of images is greater than or equal to the specified value.

media.images.count.max
integer
(query)

This parameter is used for finding stories whose number of images is less than or equal to the specified value.

media.images.width.min
integer
(query)

This parameter is used for finding stories whose width of images are greater than or equal to the specified value.

media.images.width.max
integer
(query)

This parameter is used for finding stories whose width of images are less than or equal to the specified value.

media.images.height.min
integer
(query)

This parameter is used for finding stories whose height of images are greater than or equal to the specified value.

media.images.height.max
integer
(query)

This parameter is used for finding stories whose height of images are less than or equal to the specified value.

media.images.content_length.min
integer
(query)

This parameter is used for finding stories whose images content length are greater than or equal to the specified value.

media.images.content_length.max
integer
(query)

This parameter is used for finding stories whose images content length are less than or equal to the specified value.

media.images.format[]
array [string]
(query)

This parameter is used for finding stories whose images format are the specified value.

Available values: BMP, GIF, JPEG, PNG, TIFF, PSD, ICO, CUR, WEBP, SVG

!media.images.format[]
array [string]
(query)

This parameter is used for excluding stories whose images format are the specified value.

Available values: BMP, GIF, JPEG, PNG, TIFF, PSD, ICO, CUR, WEBP, SVG

media.videos.count.min
integer
(query)

This parameter is used for finding stories whose number of videos is greater than or equal to the specified value.

media.videos.count.max
integer
(query)

This parameter is used for finding stories whose number of videos is less than or equal to the specified value.

author.id[]
array [integer]
(query)

This parameter is used for finding stories whose author id is the specified value.

!author.id[]
array [integer]
(query)

This parameter is used for excluding stories whose author id is the specified value.

author.name
string
(query)

This parameter is used for finding stories whose author full name contains the specified value.

!author.name
string
(query)

This parameter is used for excluding stories whose author full name contains the specified value.

source.id[]
array [integer]
(query)

This parameter is used for finding stories whose source id is the specified value.

!source.id[]
array [integer]
(query)

This parameter is used for excluding stories whose source id is the specified value.

source.name[]
array [string]
(query)

This parameter is used for finding stories whose source name contains the specified value.

!source.name[]
array [string]
(query)

This parameter is used for excluding stories whose source name contains the specified value.

source.domain[]
array [string]
(query)

This parameter is used for finding stories whose source domain is the specified value.

!source.domain[]
array [string]
(query)

This parameter is used for excluding stories whose source domain is the specified value.

source.locations.country[]
array [string]
(query)

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.

!source.locations.country[]
array [string]
(query)

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.

source.locations.state[]
array [string]
(query)

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.

!source.locations.state[]
array [string]
(query)

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.

source.locations.city[]
array [string]
(query)

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.

!source.locations.city[]
array [string]
(query)

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.

source.scopes.country[]
array [string]
(query)

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.

!source.scopes.country[]
array [string]
(query)

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.

source.scopes.state[]
array [string]
(query)

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.

!source.scopes.state[]
array [string]
(query)

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.

source.scopes.city[]
array [string]
(query)

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.

!source.scopes.city[]
array [string]
(query)

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.

source.scopes.level[]
array [string]
(query)

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.

Available values: international, national, local

!source.scopes.level[]
array [string]
(query)

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.

Available values: international, national, local

source.links_in_count.min
integer
(query)

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.

source.links_in_count.max
integer
(query)

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.

source.rankings.alexa.rank.min
integer
(query)

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.

source.rankings.alexa.rank.max
integer
(query)

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.

source.rankings.alexa.country[]
array [string]
(query)

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.

social_shares_count.facebook.min
integer
(query)

This parameter is used for finding stories whose Facebook social shares count is greater than or equal to the specified value.

social_shares_count.facebook.max
integer
(query)

This parameter is used for finding stories whose Facebook social shares count is less than or equal to the specified value.

social_shares_count.google_plus.min
integer
(query)

This parameter is used for finding stories whose Google+ social shares count is greater than or equal to the specified value.

social_shares_count.google_plus.max
integer
(query)

This parameter is used for finding stories whose Google+ social shares count is less than or equal to the specified value.

social_shares_count.linkedin.min
integer
(query)

This parameter is used for finding stories whose LinkedIn social shares count is greater than or equal to the specified value.

social_shares_count.linkedin.max
integer
(query)

This parameter is used for finding stories whose LinkedIn social shares count is less than or equal to the specified value.

social_shares_count.reddit.min
integer
(query)

This parameter is used for finding stories whose Reddit social shares count is greater than or equal to the specified value.

social_shares_count.reddit.max
integer
(query)

This parameter is used for finding stories whose Reddit social shares count is less than or equal to the specified value.

interval.start
integer
(query)

This parameter is used for setting the start data point of histogram intervals.

interval.end
integer
(query)

This parameter is used for setting the end data point of histogram intervals.

interval.width
integer
(query)

This parameter is used for setting the width of histogram intervals.

field
string
(query)

This parameter is used for specifying the y-axis variable for the histogram.

Default value: social_shares_count

Response

Code Description
200

An object including an array of histogram intervals

401

Unauthorized

404

Not Found

422

Unprocessable Entity

429

Too Many Requests

  • X-RateLimit-Limit: The number of allowed requests in the current period.
  • X-RateLimit-Remaining: The number of remaining requests in the current period.
  • X-RateLimit-Reset: The remaining window before the rate limit resets in UTC epoch seconds.
500

Internal Server Error