News API Documentation API Endpoints
python ruby javascript go
News API Documentation

Our 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. Each of our eight endpoints returns a different type of data. Click on each endpoint's documentation on the list to the left or search this page to find documentation on a specific parameter.

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

The parameters listed below pertain to the Entities V3 model. For Concepts V2 parameters see this doc.

Our Retrieval Endpoints

These endpoints are used to search for and retrieve JSON-formatted story or cluster objects.

Stories - Retrieve news articles enriched with NLP metadata
Clusters - Discover the events being reported in the news
Related Stories - Find semantically similar or related stories


Our Analysis Endpoints

Each of these endpoints searches across our live dataset and returns quantitative data about the stories within it.

Trends - Aggregate trends across news coverage
Time Series - Analyze story volumes over time
Histograms - Understand distributions of data within stories
Autocompletes - Discover search functions and features

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_ID'
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)

# load the gem
require 'aylien_news_api'

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

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

api_instance = AylienNewsApi::DefaultApi.new
opts = {
  :id => [123],
  :not_id => [321],
  :story_count_min => 1,
  :story_count_max => 35,
  :time_start => 'NOW-7DAYS/DAY',
  :time_end => 'NOW',
  :earliest_story_start => 'NOW-8DAYS/DAY',
  :earliest_story_end => 'NOW/DAY',  
  :latest_story_start => 'NOW-8DAYS/DAY',
  :latest_story_end => 'NOW/DAY',
  :location_country => ['US'],
  :not_location_country => ['GB']
}

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

var AylienNewsApi = require("aylien-news-api");
var defaultClient = AylienNewsApi.ApiClient.instance;

// Configure API key authorization: app_id
var app_id = defaultClient.authentications['app_id'];
app_id.apiKey = 'YOUR APP ID';

// Configure API key authorization: app_key
var app_key = defaultClient.authentications['app_key'];
app_key.apiKey = 'YOUR API KEY';

var apiInstance = new AylienNewsApi.DefaultApi();
var opts = {
  'id': [null],
  'notId': [null],
  'storyCountMin': 56,
  'storyCountMax': 56,
  'timeStart': "timeStart_example",
  'timeEnd': "timeEnd_example",
  'earliestStoryStart': "earliestStoryStart_example",
  'earliestStoryEnd': "earliestStoryEnd_example",
  'latestStoryStart': "latestStoryStart_example",
  'latestStoryEnd': "latestStoryEnd_example",
  'locationCountry': ["IE"],
  'notLocationCountry': ["IN"]
};
apiInstance.listClusters(opts, (error, data, response) => {
  if (error) {
    console.error(error);
  } else {
    console.log(data.clusters);
  }
});

package main

// Import the library
import (
  "context"
  "fmt"
  newsapi "github.com/AYLIEN/aylien_newsapi_go"
  "github.com/antihax/optional"
)

func main() {

  cfg := newsapi.NewConfiguration()
  cfg.DefaultHeader["X-AYLIEN-NewsAPI-Application-ID"] = "YOUR_APP_ID"
  cfg.DefaultHeader["X-AYLIEN-NewsAPI-Application-Key"] = "YOUR_API_KEY"

  client := newsapi.NewAPIClient(cfg)
  api := client.DefaultApi

  clustersParams := &newsapi.ListClustersOpts{
    Id:                             optional.NewInterface([]int64{123}),
    NotId:                          optional.NewInterface([]int64{123}),
    StoryCountMin:                  optional.NewInt32(3),
    StoryCountMax:                  optional.NewInt32(200),            
    TimeStart:                      optional.NewString("NOW-7DAYS"),
    TimeEnd:                        optional.NewString("NOW-2DAYS"),
    EarliestStoryStart:             optional.NewString("NOW-7DAYS"),
    EarliestStoryEnd:               optional.NewString("NOW-1DAY"),
    LatestStoryStart:               optional.NewString("NOW-7DAYS"),
    LatestStoryEnd:                 optional.NewString("NOW-2DAYS"),
    LocationCountry:                optional.NewInterface([]string{"IE"}),
    NotLocationCountry:             optional.NewInterface([]string{"IN"}),
  }

  clustersResponse, res, err := api.ListClusters(context.Background(), clustersParams)

  if err != nil {
    panic(err)
  }

  _ = res

  for _, cluster := range clustersResponse.Clusters {
    fmt.Println(cluster)
  }
}

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.


What is a cluster?
A cluster is a collection of news stories that all refer to the same real-world event. For example, multiple stories referring to a specific company’s earnings will appear in the same cluster, just as multiple stories about a single road accident will.


What is the lifecycle of a cluster?
A newly published story is compared with representative stories of other clusters to see if a cluster already exists for this event. This is achieved by converting the new story’s body to a vector, which is compared against the other story vectors. If the story is found to be similar to other stories (i.e. having a small vector distance), it will be added to that cluster. If the new story is not similar to any existing stories (i.e. having a large vector distance), a new cluster is created containing that single story. Thus a new cluster is born and subsequently grows with every new, related story that is published. This process happens in real time, i.e. within 3 minutes of us receiving the story from the publisher.

If no stories have been added to a cluster within a maximum two-week period the cluster is “frozen”. No more stories can be added to the cluster after that point. This cluster lifecycle (creation, growth, decline and freeze) repeats for each and every cluster.


Can an article be in more than one cluster?
No. A story only belongs to the most appropriate, single cluster, and this remains the case through all stages of the cluster lifecycle. A story cannot move from one cluster to another.


To see workflows for discovering clusters, go to the Working With Clusters documentation page. If you would like to see more on what the clustering endpoint returns and what it is for, take a look at this introductory blog post.


HTTP Request URL

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

HTTP 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.
location.country
array [string]
(query)

This parameter allows you to specify clusters that refer to events in specific countries. It supports ISO 3166-1 alpha-2 country codes.
!location.country
array [string]
(query)

This parameter allows you to specify clusters that do not refer to events in specifc countries. It supports ISO 3166-1 alpha-2 country codes.
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.

HTTP Response Codes

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

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_id': ['entities_id_example'],
  'not_entities_id': ['entities_id_example'],
  'entities_surface_forms_text': ['entities_surface_form_text_example'],
  'not_entities_surface_forms_text': ['entities_surface_form_text_example'],
  'entities_types': ['entities_types_example'],
  'not_entities_types': ['entities_types_example']
  'entities_links_wikipedia': ['entities_links_wikipedia_example'],
  'not_entities_links_wikipedia': ['entities_links_wikipedia_example'],
  'entities_links_wikidata': ['entities_links_wikidata_example'],
  'not_entities_links_wikidata': ['entities_links_wikidata_example'],
  'entities_stock_ticker': ['entities_stock_ticker_example'],
  'not_entities_stock_ticker': ['entities_stock_ticker_example'],
  'entities_title_surface_forms_text': ['entities_title_surface_form_text_example'],
  'not_entities_title_surface_forms_text': ['entities_title_surface_form_text_example'],
  'entities_body_surface_forms_text': ['entities_body_surface_form_text_example'],
  'not_entities_body_surface_forms_text': ['entities_body_surface_form_text_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'],
  'clusters': ['clusters_example'],
  '_return': ['_return_example'],
  'sort_by': 'published_at',
  'sort_direction': 'desc',
  'aql': 'aql_example'
  '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)

# load the gem
require 'aylien_news_api'
require 'pp'
# setup authorization
AylienNewsApi.configure do |config|
  # Configure API key authorization: app_id
  config.api_key['X-AYLIEN-NewsAPI-Application-ID'] = "YOUR APP ID"
  # Uncomment the following line to set a prefix for the API key, e.g. 'Bearer' (defaults to nil)
  #config.api_key_prefix['X-AYLIEN-NewsAPI-Application-ID'] = 'Bearer'

  # Configure API key authorization: app_key
  config.api_key['X-AYLIEN-NewsAPI-Application-Key'] = "YOUR API KEY"
  # Uncomment the following line to set a prefix for the API key, e.g. 'Bearer' (defaults to nil)
  #config.api_key_prefix['X-AYLIEN-NewsAPI-Application-Key'] = 'Bearer'
end

api_instance = AylienNewsApi::DefaultApi.new

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_id => ['entities_id_example'],
  :not_entities_id => ['entities_id_example'],
  :entities_surface_forms_text => ['entities_surface_form_text_example'],
  :not_entities_surface_forms_text => ['entities_surface_form_text_example'],
  :entities_types => ['entities_types_example'],
  :not_entities_types => ['entities_types_example'],
  :entities_links_wikipedia => ['entities_links_wikipedia_example'],
  :not_entities_links_wikipedia => ['entities_links_wikipedia_example'],
  :entities_links_wikidata => ['entities_links_wikidata_example'],
  :not_entities_links_wikidata => ['entities_links_wikidata_example'],
  :entities_stock_ticker => ['entities_stock_ticker_example'],
  :not_entities_stock_ticker => ['entities_stock_ticker_example'],
  :entities_title_surface_forms_text => ['entities_title_surface_form_text_example'],
  :not_entities_title_surface_forms_text => ['entities_title_surface_form_text_example'],
  :entities_body_surface_forms_text => ['entities_body_surface_form_text_example'],
  :not_entities_body_surface_forms_text => ['entities_body_surface_form_text_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'],
  :clusters => ['clusters_example'],
  :_return => ['title'],
  :sort_by => 'published_at',
  :sort_direction => 'desc',
  :aql => 'aql_example'
  :cursor => '*',
  :per_page => 10
}

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

var AylienNewsApi = require("aylien-news-api");
var defaultClient = AylienNewsApi.ApiClient.instance;

// Configure API key authorization: app_id
var app_id = defaultClient.authentications['app_id'];
app_id.apiKey = 'YOUR_APP_ID';
// Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
//app_id.apiKeyPrefix = 'Token';
// Configure API key authorization: app_key
var app_key = defaultClient.authentications['app_key'];
app_key.apiKey = 'YOUR API KEY';
// Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
//app_key.apiKeyPrefix = 'Token';

var apiInstance = new AylienNewsApi.DefaultApi();

var opts = {
  'id': [null],
  'notId': [null],
  'title': "title_example",
  'body': "body_example",
  'text': "text_example",
  'translationsEnTitle': "translationsEnTitle_example",
  'translationsEnBody': "translationsEnBody_example",
  'translationsEnText': "translationsEnText_example",
  'language': ["null"],
  'notLanguage': ["null"],
  'publishedAtStart': "publishedAtStart_example",
  'publishedAtEnd': "publishedAtEnd_example",
  'categoriesTaxonomy': "categoriesTaxonomy_example",
  'categoriesConfident': true,
  'categoriesId': ["null"],
  'notCategoriesId': ["null"],
  'categoriesLevel': [null],
  'notCategoriesLevel': [null],
  'entitiesId': ["entitiesId_example"],
  'notEntitiesId': ["entitiesId_example"],
  'entitiesSurfaceFormsText': ["entitiesSurfaceFormsText_example"],
  'notEntitiesSurfaceFormsText': ["entitiesSurfaceFormsText_example"],
  'entitiesTypes': ["entitiesTypes_example"],
  'notEntitiesTypes': ["entitiesTypes_example"],
  'entitiesLinksWikipedia': ["entitiesLinksWikipedia_example"],
  'notEntitiesLinksWikipedia': ["entitiesLinksWikipedia_example"],
  'entitiesLinksWikidata': ["entitiesLinksWikidata_example"],
  'notEntitiesLinksWikidata': ["entitiesLinksWikidata_example"], 
  'entitiesStockTicker': ["entitiesStockTicker_example"],
  'notEntitiesStockTicker': ["entitiesStockTicker_example"], 
  'entitiesTitleSurfaceFormsText': ["entitiesTitleSurfaceFormsText_example"],
  'notEntitiesTitleSurfaceFormsText': ["entitiesTitleSurfaceFormsText_example"],
  'entitiesBodySurfaceFormsText': ["entitiesBodySurfaceFormsText_example"],
  'notEntitiesBodySurfaceFormsText': ["entitiesBodySurfaceFormsText_example"],
  'sentimentTitlePolarity': "sentimentTitlePolarity_example",
  'notSentimentTitlePolarity': "sentimentTitlePolarity_example",
  'sentimentBodyPolarity': "sentimentBodyPolarity_example",
  'notSentimentBodyPolarity': "sentimentBodyPolarity_example",
  'mediaImagesCountMin': 56,
  'mediaImagesCountMax': 56,
  'mediaImagesWidthMin': 56,
  'mediaImagesWidthMax': 56,
  'mediaImagesHeightMin': 56,
  'mediaImagesHeightMax': 56,
  'mediaImagesContentLengthMin': 56,
  'mediaImagesContentLengthMax': 56,
  'mediaImagesFormat': ["null"],
  'notMediaImagesFormat': ["null"],
  'mediaVideosCountMin': 56,
  'mediaVideosCountMax': 56,
  'authorId': [null],
  'notAuthorId': [null],
  'authorName': "authorName_example",
  'notAuthorName': "authorName_example",
  'sourceId': [null],
  'notSourceId': [null],
  'sourceName': ["null"],
  'notSourceName': ["null"],
  'sourceDomain': ["null"],
  'notSourceDomain': ["null"],
  'sourceLocationsCountry': ["null"],
  'notSourceLocationsCountry': ["null"],
  'sourceLocationsState': ["null"],
  'notSourceLocationsState': ["null"],
  'sourceLocationsCity': ["null"],
  'notSourceLocationsCity': ["null"],
  'sourceScopesCountry': ["null"],
  'notSourceScopesCountry': ["null"],
  'sourceScopesState': ["null"],
  'notSourceScopesState': ["null"],
  'sourceScopesCity': ["null"],
  'notSourceScopesCity': ["null"],
  'sourceScopesLevel': ["null"],
  'notSourceScopesLevel': ["null"],
  'sourceLinksInCountMin': 56,
  'sourceLinksInCountMax': 56,
  'sourceRankingsAlexaRankMin': 56,
  'sourceRankingsAlexaRankMax': 56,
  'sourceRankingsAlexaCountry': ["null"],
  'clusters': ["clusters_example"],
  '_return': ["_return_example"],
  'sortBy': "sortBy_example" ,
  'sortDirection': "desc",
  'aql': 'aql_example'
  'cursor': "*",
  'perPage': 10
};

apiInstance.listStories(opts, (error, data, response) => {
  if (error) {
    console.error(error);
  } else {
    console.log(data.stories);
  }
});

package main

// Import the library
import (
  "context"
  "fmt"
  newsapi "github.com/AYLIEN/aylien_newsapi_go"
  "github.com/antihax/optional"
)

func main() {

  cfg := newsapi.NewConfiguration()
  cfg.DefaultHeader["X-AYLIEN-NewsAPI-Application-ID"] = "YOUR_APP_ID"
  cfg.DefaultHeader["X-AYLIEN-NewsAPI-Application-Key"] = "YOUR_API_KEY"

  client := newsapi.NewAPIClient(cfg)
  api := client.DefaultApi

  storiesParams := &newsapi.ListStoriesOpts{
    Id:                               optional.NewInterface([]int64{123}),
    NotId:                            optional.NewInterface([]int64{123}),
    Title:                            optional.NewString("startup"),
    Body:                             optional.NewString("investment"),
    Text:                             optional.NewString("AI"),
    TranslationsEnTitle:              optional.NewString("Trump"),
    TranslationsEnBody:               optional.NewString("bank"),
    TranslationsEnText:               optional.NewString("sanctions"),
    Language:                         optional.NewInterface([]string{"en"}),
    NotLanguage:                      optional.NewInterface([]string{"zh-cn"}),
    PublishedAtStart:                 optional.NewString("NOW-1MONTH"),
    PublishedAtEnd:                   optional.NewString("NOW-1DAY"),
    CategoriesTaxonomy:               optional.NewString("iptc-subjectcode"),
    CategoriesConfident:              optional.NewBool(true),
    CategoriesId:                     optional.NewInterface([]string{"04000000"}),
    NotCategoriesId:                  optional.NewInterface([]string{"17000000"}),
    CategoriesLevel:                  optional.NewInterface([]int32{1}),
    NotCategoriesLevel:               optional.NewInterface([]int32{2, 3}),
    EntitiesId:                       optional.NewInterface([]string{"EntitiesId_example"}),
    NotEntitiesId:                    optional.NewInterface([]string{"EntitiesId_example"}),
    EntitiesSurfaceFormsText:         optional.NewInterface([]string{"EntitiesSurfaceFormsText_example"}),
    NotEntitiesSurfaceFormsText:      optional.NewInterface([]string{"EntitiesSurfaceFormsText_example"}),
    EntitiesTypes:                     optional.NewInterface([]string{"EntitiesTypes_example"}),
    NotEntitiesTypes:                  optional.NewInterface([]string{"EntitiesTypes_example"}),
    EntitiesLinksWikipedia:           optional.NewInterface([]string{"EntitiesLinksWikipedia_example"}),
    NotEntitiesLinksWikipedia:        optional.NewInterface([]string{"EntitiesLinksWikipedia_example"}),
    EntitiesLinksWikidata:            optional.NewInterface([]string{"EntitiesLinksWikidata_example"}),
    NotEntitiesLinksWikidata:         optional.NewInterface([]string{"EntitiesLinksWikidata_example"}),
    EntitiesStockTicker:              optional.NewInterface([]string{"EntitiesStockTicker_example"}),
    NotEntitiesStockTicker:           optional.NewInterface([]string{"EntitiesStockTicker_example"}),  
    EntitiesTitleSurfaceFormsText:    optional.NewInterface([]string{"EntitiesTitleSurfaceFormsText_example"}),
    NotEntitiesTitleSurfaceFormsText: optional.NewInterface([]string{"EntitiesTitleSurfaceFormsText_example"}),
    EntitiesBodySurfaceFormsText:     optional.NewInterface([]string{"EntitiesBodySurfaceFormsText_example"}),
    SentimentTitlePolarity:           optional.NewString("positive"),
    NotSentimentTitlePolarity:        optional.NewString("negative"),
    SentimentBodyPolarity:            optional.NewString("positive"),
    NotSentimentBodyPolarity:         optional.NewString("neutral"),
    MediaImagesCountMin:              optional.NewInt32(1),
    MediaImagesCountMax:              optional.NewInt32(4),
    MediaImagesWidthMin:              optional.NewInt32(640),
    MediaImagesWidthMax:              optional.NewInt32(1200),
    MediaImagesHeightMin:             optional.NewInt32(700),
    MediaImagesHeightMax:             optional.NewInt32(1500),
    MediaImagesContentLengthMin:      optional.NewInt32(25000),
    MediaImagesContentLengthMax:      optional.NewInt32(40000),
    MediaImagesFormat:                optional.NewInterface([]string{"JPEG"}),
    NotMediaImagesFormat:             optional.NewInterface([]string{"PNG"}),
    MediaVideosCountMin:              optional.NewInt32(1),
    MediaVideosCountMax:              optional.NewInt32(2),
    AuthorId:                         optional.NewInterface([]int32{123}),
    NotAuthorId:                      optional.NewInterface([]int32{321}),
    AuthorName:                       optional.NewString("Charlie Kelly"),
    NotAuthorName:                    optional.NewString("Frank Reynolds"),
    SourceId:                         optional.NewInterface([]int32{123}),
    NotSourceId:                      optional.NewInterface([]int32{321}),
    SourceName:                       optional.NewInterface([]string{"The Irish Times"}),
    NotSourceName:                    optional.NewInterface([]string{"The Irish Independent"}),
    SourceDomain:                     optional.NewInterface([]string{"bbc.com"}),
    NotSourceDomain:                  optional.NewInterface([]string{"cnn.com"}),
    SourceLocationsCountry:           optional.NewInterface([]string{"US"}),
    NotSourceLocationsCountry:        optional.NewInterface([]string{"GB"}),
    SourceLocationsState:             optional.NewInterface([]string{"Florida"}),
    NotSourceLocationsState:          optional.NewInterface([]string{"California"}),
    SourceLocationsCity:              optional.NewInterface([]string{"Miami"}),
    NotSourceLocationsCity:           optional.NewInterface([]string{"Austin"}),
    SourceScopesCountry:              optional.NewInterface([]string{"IE"}),
    NotSourceScopesCountry:           optional.NewInterface([]string{"DE"}),
    SourceScopesState:                optional.NewInterface([]string{"Illinois"}),
    NotSourceScopesState:             optional.NewInterface([]string{"Montana"}),
    SourceScopesCity:                 optional.NewInterface([]string{"Sheboygan"}),
    NotSourceScopesCity:              optional.NewInterface([]string{"Westport"}),
    SourceScopesLevel:                optional.NewInterface([]string{"national"}),
    NotSourceScopesLevel:             optional.NewInterface([]string{"international"}),
    SourceLinksInCountMin:            optional.NewInt32(1),
    SourceLinksInCountMax:            optional.NewInt32(3000),
    SourceRankingsAlexaRankMin:       optional.NewInt32(1),
    SourceRankingsAlexaRankMax:       optional.NewInt32(1000),
    SourceRankingsAlexaCountry:       optional.NewInterface([]string{"US"}),
    Clusters:                         optional.NewInterface([]int32{1234567}),
    Return_:                          optional.NewInterface([]string{"title"}),
    SortBy:                           optional.NewString("published_at"),
    SortDirection:                    optional.NewString("desc"),
    Aql:                              optional.NewString("aql_example"),
    Cursor:                           optional.NewString("*"),
    PerPage:                          optional.NewInt32(5),
  }

  storiesResponse, res, err := api.ListStories(context.Background(), storiesParams)

  if err != nil {
    panic(err)
  }

  _ = res

  for _, story := range storiesResponse.Stories {
    fmt.Println(story.PublishedAt, story.Title, " / ", story.Source.Name)
  }
}

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.

Since we learned that categories are a very important part of our users' workflows for filtering for relevant content, we have introduced the Smart Tagger. this new feature is our latest article tagging feature that leverages state-of-the-art classification models built using a vast collection of manually tagged news articles based on domain-specific industry and topical category taxonomies. With a taxonomy of ~3000 topical categories and ~1500 industries, the Smart tagger classifies articles with a high precision, making it easier for users to filter for articles most relevant to them and their usecases. To sign up for a free trial of the Smart Tagger, click on the button below.

View Taxonomy Explorer



HTTP Request URL

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

HTTP 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
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.en.title
string
(query)

This parameter is used for filtering stories translated from a non-English language containing an English-language query term in the title. Translation requires an Advanced or Enterprise license key. Start a free trial or contact sales to upgrade your account.

translations.en.body
string
(query)

This parameter is used for filtering stories translated from a non-English language containing an English-language query term in the body. 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 advanced search operators.
body
string
(query)

This parameter is used for finding stories whose title contains a specific keyword. It supports advanced search operators.
text
string
(query)

This parameter is used for finding stories whose title contains a specific keyword. It supports advanced search operators.
language[]
array [string]
(query)

This parameter is used for finding stories whose language is the specified value. To ensure the most accurate results, you should always incude a this parameter listing the languages you want to retrieve content in. 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, which is used for defining the type of taxonomy for the rest of the categories query, is available for our standard IPTC and IAB category taxonomies. Please click here to learn more about our Smart Tagger taxonomies, and about using the right taxonomy for you.
categories.confident
boolean
(query)

This parameter which is used for finding stories whose categories are confident, is available for our standard IPTC and IAB category taxonomies. Please click here to learn more about our Smart Tagger taxonomies, and about using the right taxonomy for you.

Default value: true
categories.id[]
array [string]
(query)

This parameter, which is used for finding stories by categories id, is available for our standard IPTC and IAB category taxonomies. Please click here to learn more about our Smart Tagger taxonomies, and about using the right taxonomy for you.
!categories.id[]
array [string]
(query)

This parameter, which is used for excluding stories by categories id, is available for our standard IPTC and IAB category taxonomies. Please click here to learn more about our Smart Tagger taxonomies, and about using the right taxonomy for you.
categories.level[]
array [integer]
(query)

This parameter, which is used for finding stories by categories level, is available for our standard IPTC and IAB category taxonomies. Please click here to learn more about our Smart Tagger taxonomies, and about using the right taxonomy for you.
categories.level[]
array [integer]
(query)

This parameter, which is used for finding stories by categories level, is available for our standard IPTC and IAB category taxonomies. Please click here to learn more about our Smart Tagger taxonomies, and about using the right taxonomy for you.
industries
(query)

This parameter is not available in flat search. However, you can filter for articles containing specific industries using AQL. You can read more about the industries filter here here, and find industry ids and labels here.
entities.id[]
array [string]
(query)

This parameter is used to find stories based on the specified entities id in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
!entities.id[]
array [string]
(query)

This parameter is used to exclude stories based on the specified entities id in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
entities.surface_forms.text[]
array [string]
(query)

This parameter is used to find stories based on the specified entities surface form text in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
!entities.surface_forms.text[]
array [string]
(query)

This parameter is used to exclude stories based on the specified entities surface form text in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
entities.types[]
array [string]
(query)

This parameter is used to find stories based on the specified entities type in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
!entities.types[]
array [string]
(query)

This parameter is used to exclude stories based on the specified entities type in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
entities.links.wikipedia[]
array [string]
(query)

This parameter is used to find stories based on the specified entities wikipedia URL in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
!entities.links.wikipedia[]
array [string]
(query)

This parameter is used to exclude stories based on the specified entities wikipedia URL in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
entities.links.wikidata[]
array [string]
(query)

This parameter is used to find stories based on the specified entities wikidata URL in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
!entities.links.wikidata[]
array [string]
(query)

This parameter is used to exclude stories based on the specified entities wikidata URL in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
entities.stock_ticker[]
array [string]
(query)

This parameter is used to find stories based on the specified entities stock tickers in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
!entities.stock_ticker[]
array [string]
(query)

This parameter is used to exclude stories based on the specified entities stock tickers in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
entities.title.surface_forms.text[]
array [string]
(query)

This parameter is used to find stories based on the specified entities surface form text in story titles. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
!entities.title.surface_forms.text[]
array [string]
(query)

This parameter is used to exclude stories based on the specified entities surface form text in story titles. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
entities.body.surface_forms.text[]
array [string]
(query)

This parameter is used to find stories based on the specified entities surface form text in story bodies. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
!entities.body.surface_forms.text[]
array [string]
(query)

This parameter is used to exclude stories based on the specified entities surface form text in story bodies. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
sentiment.title.polarity
string [string]
(query)

This parameter is used for finding stories whose title sentiment is the specified value.
!sentiment.title.polarity
string [string]
(query)

This parameter is used for excluding stories whose title sentiment is the specified value.
sentiment.body.polarity
string [string]
(query)

This parameter is used for finding stories whose body sentiment is the specified value.
!sentiment.body.polarity
string [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.
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, 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
links.permalink
string
(query)

This parameter is used for finding stories with a specified url.
aql
string
(query)

This parameter is used to supply a sub-query in AYLIEN's custom DSL to leverage advanced keyword operators and enhanced entity search.
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 Codes

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_id': ['entities_id_example'],
  'not_entities_id': ['entities_id_example'],
  'entities_surface_forms_text': ['entities_surface_form_text_example'],
  'not_entities_surface_forms_text': ['entities_surface_form_text_example'],
  'entities_types': ['entities_types_example'],
  'not_entities_types': ['entities_types_example']
  'entities_links_wikipedia': ['entities_links_wikipedia_example'],
  'not_entities_links_wikipedia': ['entities_links_wikipedia_example'],
  'entities_links_wikidata': ['entities_links_wikidata_example'],
  'not_entities_links_wikidata': ['entities_links_wikidata_example'],
  'entities_stock_ticker': ['entities_stock_ticker_example'],
  'not_entities_stock_ticker': ['entities_stock_ticker_example'],
  'entities_title_surface_forms_text': ['entities_title_surface_form_text_example'],
  'not_entities_title_surface_forms_text': ['entities_title_surface_form_text_example'],
  'entities_body_surface_forms_text': ['entities_body_surface_form_text_example'],
  'not_entities_body_surface_forms_text': ['entities_body_surface_form_text_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'],
  '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',
  'aql': 'aql_example',
  '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)

# load the gem
require 'aylien_news_api'
require 'pp'
# setup authorization
AylienNewsApi.configure do |config|
  # Configure API key authorization: app_id
  config.api_key['X-AYLIEN-NewsAPI-Application-ID'] = "YOUR APP ID"
  # Uncomment the following line to set a prefix for the API key, e.g. 'Bearer' (defaults to nil)
  #config.api_key_prefix['X-AYLIEN-NewsAPI-Application-ID'] = 'Bearer'

  # Configure API key authorization: app_key
  config.api_key['X-AYLIEN-NewsAPI-Application-Key'] = "YOUR APP KEY"
  # Uncomment the following line to set a prefix for the API key, e.g. 'Bearer' (defaults to nil)
  #config.api_key_prefix['X-AYLIEN-NewsAPI-Application-Key'] = 'Bearer'
end

api_instance = AylienNewsApi::DefaultApi.new

opts = {
  :id => [5411],
  :not_id => [3625],
  :title => "startup AND (raise OR raised OR raising OR raises)",
  :body => "startup",
  :text => "startup company",
  :language => ["en", "fr"],
  :not_language => ["es", "it"],
  :published_at_start => "NOW-10DAYS",
  :published_at_end => "NOW",
  :categories_taxonomy => "iptc-subjectcode",
  :categories_confident => true,
  :categories_id => ["11000000", "02000000"],
  :not_categories_id => ["11001000", "10000000"],
  :categories_level => [3],
  :not_categories_level => [1, 2],
  :entities_id => ['entities_id_example'],
  :not_entities_id => ['entities_id_example'],
  :entities_surface_forms_text => ['entities_surface_form_text_example'],
  :not_entities_surface_forms_text => ['entities_surface_form_text_example'],
  :entities_types => ['entities_types_example'],
  :not_entities_types => ['entities_types_example'],
  :entities_links_wikipedia => ['entities_links_wikipedia_example'],
  :not_entities_links_wikipedia => ['entities_links_wikipedia_example'],
  :entities_links_wikidata => ['entities_links_wikidata_example'],
  :not_entities_links_wikidata => ['entities_links_wikidata_example'],
  :entities_stock_ticker => ['entities_stock_ticker_example'],
  :not_entities_stock_ticker => ['entities_stock_ticker_example'],
  :entities_title_surface_forms_text => ['entities_title_surface_form_text_example'],
  :not_entities_title_surface_forms_text => ['entities_title_surface_form_text_example'],
  :entities_body_surface_forms_text => ['entities_body_surface_form_text_example'],
  :not_entities_body_surface_forms_text => ['entities_body_surface_form_text_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 => 3,
  :media_images_count_max => 3,
  :media_images_width_min => 640,
  :media_images_width_max => 1024,
  :media_images_height_min => 480,
  :media_images_height_max => 800,
  :media_images_content_length_min => 25411,
  :media_images_content_length_max => 369541,
  :media_images_format => ["JPEG", "BMP", "GIF"],
  :not_media_images_format => ["TIFF", "PNG"],
  :media_videos_count_min => 1,
  :media_videos_count_max => 2,
  :author_id => [4155],
  :not_author_id => [2541],
  :author_name => "John Doe",
  :not_author_name => "Mike Wally",
  :source_id => [124],
  :not_source_id => [54],
  :source_name => ["BBC"],
  :not_source_name => ["Fox News"],
  :source_domain => ["bbc.co.uk"],
  :not_source_domain => ["foxnews.com"],
  :source_locations_country => ["US", "IE"],
  :not_source_locations_country => ["JP", "GB"],
  :source_locations_state => ["California"],
  :not_source_locations_state => ["Arizona"],
  :source_locations_city => ["Los Angeles"],
  :not_source_locations_city => ["Dublin City"],
  :source_scopes_country => ["GB", "IE"],
  :not_source_scopes_country => ["US", "JP"],
  :source_scopes_state => ["Co Dublin"],
  :not_source_scopes_state => ["Co Wicklow"],
  :source_scopes_city => ["Cork"],
  :not_source_scopes_city => ["Galway"],
  :source_scopes_level => ["local"],
  :not_source_scopes_level => ["national"],
  :source_links_in_count_min => 126333,
  :source_links_in_count_max => 521000,
  :source_rankings_alexa_rank_min => 123,
  :source_rankings_alexa_rank_max => 152,
  :source_rankings_alexa_country => ["IE"],
  :_return => ["id", "title", "body", "published_at"],
  :story_id => 789,
  :story_url => "https =>//techcrunch.com/2016/04/07/aylien-launches-news-analysis-api-powered-by-its-deep-learning-tech/",
  :story_title => "Aylien launches news analysis API powered by its deep learning tech",
  :story_body => "Text analysis startup Aylien, which uses deep learning ...",
  :boost_by => "recency",
  :story_language => "auto",
  :aql => "aql_example",
  :per_page => 3
}


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

var AylienNewsApi = require("aylien-news-api");
var defaultClient = AylienNewsApi.ApiClient.instance;
// Configure API key authorization: app_id
var app_id = defaultClient.authentications['app_id'];
app_id.apiKey = 'YOUR APP ID';
// Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
//app_id.apiKeyPrefix = 'Token';
// Configure API key authorization: app_key
var app_key = defaultClient.authentications['app_key'];
app_key.apiKey = 'YOUR API KEY';
// Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
//app_key.apiKeyPrefix = 'Token';

var apiInstance = new AylienNewsApi.DefaultApi();
var opts = {
  'id': [null],
  'notId': [null],
  'title': "title_example",
  'body': "body_example",
  'text': "text_example",
  'translationsEnTitle': "translationsEnTitle_example",
  'translationsEnBody': "translationsEnBody_example",
  'translationsEnText': "translationsEnText_example",
  'language': ["null"],
  'notLanguage': ["null"],
  'publishedAtStart': "publishedAtStart_example",
  'publishedAtEnd': "publishedAtEnd_example",
  'categoriesTaxonomy': "categoriesTaxonomy_example",
  'categoriesConfident': true,
  'categoriesId': ["null"],
  'notCategoriesId': ["null"],
  'categoriesLevel': [null],
  'notCategoriesLevel': [null],
  'entitiesId': ["entitiesId_example"],
  'notEntitiesId': ["entitiesId_example"],
  'entitiesSurfaceFormsText': ["entitiesSurfaceFormsText_example"],
  'notEntitiesSurfaceFormsText': ["entitiesSurfaceFormsText_example"],
  'entitiesTypes': ["entitiesTypes_example"],
  'notEntitiesTypes': ["entitiesTypes_example"],
  'entitiesLinksWikipedia': ["entitiesLinksWikipedia_example"],
  'notEntitiesLinksWikipedia': ["entitiesLinksWikipedia_example"],
  'entitiesLinksWikidata': ["entitiesLinksWikidata_example"],
  'notEntitiesLinksWikidata': ["entitiesLinksWikidata_example"], 
  'entitiesStockTicker': ["entitiesStockTicker_example"],
  'notEntitiesStockTicker': ["entitiesStockTicker_example"], 
  'entitiesId': ["entitiesId_example"],
  'notEntitiesId': ["entitiesId_example"],
  'entitiesSurfaceFormsText': ["entitiesSurfaceFormsText_example"],
  'notEntitiesSurfaceFormsText': ["entitiesSurfaceFormsText_example"],
  'entitiesTypes': ["entitiesTypes_example"],
  'notEntitiesTypes': ["entitiesTypes_example"],
  'entitiesLinksWikipedia': ["entitiesLinksWikipedia_example"],
  'notEntitiesLinksWikipedia': ["entitiesLinksWikipedia_example"],
  'entitiesLinksWikidata': ["entitiesLinksWikidata_example"],
  'notEntitiesLinksWikidata': ["entitiesLinksWikidata_example"], 
  'entitiesStockTicker': ["entitiesStockTicker_example"],
  'notEntitiesStockTicker': ["entitiesStockTicker_example"], 
  'entitiesTitleSurfaceFormsText': ["entitiesTitleSurfaceFormsText_example"],
  'notEntitiesTitleSurfaceFormsText': ["entitiesTitleSurfaceFormsText_example"],
  'entitiesBodySurfaceFormsText': ["entitiesBodySurfaceFormsText_example"],
  'notEntitiesBodySurfaceFormsText': ["entitiesBodySurfaceFormsText_example"],
  'sentimentTitlePolarity': "sentimentTitlePolarity_example",
  'notSentimentTitlePolarity': "sentimentTitlePolarity_example",
  'sentimentBodyPolarity': "sentimentBodyPolarity_example",
  'notSentimentBodyPolarity': "sentimentBodyPolarity_example",
  'mediaImagesCountMin': 56,
  'mediaImagesCountMax': 56,
  'mediaImagesWidthMin': 56,
  'mediaImagesWidthMax': 56,
  'mediaImagesHeightMin': 56,
  'mediaImagesHeightMax': 56,
  'mediaImagesContentLengthMin': 56,
  'mediaImagesContentLengthMax': 56,
  'mediaImagesFormat': ["null"],
  'notMediaImagesFormat': ["null"],
  'mediaVideosCountMin': 56,
  'mediaVideosCountMax': 56,
  'authorId': [null],
  'notAuthorId': [null],
  'authorName': "authorName_example",
  'notAuthorName': "authorName_example",
  'sourceId': [null],
  'notSourceId': [null],
  'sourceName': ["null"],
  'notSourceName': ["null"],
  'sourceDomain': ["null"],
  'notSourceDomain': ["null"],
  'sourceLocationsCountry': ["null"],
  'notSourceLocationsCountry': ["null"],
  'sourceLocationsState': ["null"],
  'notSourceLocationsState': ["null"],
  'sourceLocationsCity': ["null"],
  'notSourceLocationsCity': ["null"],
  'sourceScopesCountry': ["null"],
  'notSourceScopesCountry': ["null"],
  'sourceScopesState': ["null"],
  'notSourceScopesState': ["null"],
  'sourceScopesCity': ["null"],
  'notSourceScopesCity': ["null"],
  'sourceScopesLevel': ["null"],
  'notSourceScopesLevel': ["null"],
  'sourceLinksInCountMin': 56,
  'sourceLinksInCountMax': 56,
  'sourceRankingsAlexaRankMin': 56,
  'sourceRankingsAlexaRankMax': 56,
  'sourceRankingsAlexaCountry': ["null"],
  'clusters': ["null"],
  '_return': ["return_example"],
  'storyId': 789,
  'storyUrl': "storyUrl_example",
  'storyTitle': "storyTitle_example",
  'storyBody': "storyBody_example",
  'boostBy': "boostBy_example",
  'storyLanguage': "auto",
  'aql': "aql_example",
  'perPage': 3
};

apiInstance.listRelatedStoriesGet(opts, (error, data, response) => {
  if (error) {
    console.error(error);
  } else {
    console.log(data.related_stories);
  }
});

package main

// Import the library
import (
  "context"
  "fmt"
  newsapi "github.com/AYLIEN/aylien_newsapi_go"
  "github.com/antihax/optional"
)

func main() {

  cfg := newsapi.NewConfiguration()
  cfg.DefaultHeader["X-AYLIEN-NewsAPI-Application-ID"] = "YOUR_APP_ID"
  cfg.DefaultHeader["X-AYLIEN-NewsAPI-Application-Key"] = "YOUR_API_KEY"

  client := newsapi.NewAPIClient(cfg)
  api := client.DefaultApi

  relatedStoriesParams := &newsapi.ListRelatedStoriesOpts{
    Id:                               optional.NewInterface([]int64{123}),
    NotId:                            optional.NewInterface([]int64{123}),
    Title:                            optional.NewString("startup"),
    Body:                             optional.NewString("investment"),
    Text:                             optional.NewString("AI"),
    TranslationsEnTitle:              optional.NewString("Trump"),
    TranslationsEnBody:               optional.NewString("bank"),
    TranslationsEnText:               optional.NewString("sanctions"),
    Language:                         optional.NewInterface([]string{"en"}),
    NotLanguage:                      optional.NewInterface([]string{"zh-cn"}),
    PublishedAtStart:                 optional.NewString("NOW-1MONTH"),
    PublishedAtEnd:                   optional.NewString("NOW-1DAY"),
    CategoriesTaxonomy:               optional.NewString("iptc-subjectcode"),
    CategoriesConfident:              optional.NewBool(true),
    CategoriesId:                     optional.NewInterface([]string{"04000000"}),
    NotCategoriesId:                  optional.NewInterface([]string{"17000000"}),
    CategoriesLevel:                  optional.NewInterface([]int32{1}),
    NotCategoriesLevel:               optional.NewInterface([]int32{2, 3}),
    EntitiesId:                       optional.NewInterface([]string{"EntitiesId_example"}),
    NotEntitiesId:                    optional.NewInterface([]string{"EntitiesId_example"}),
    EntitiesSurfaceFormsText:         optional.NewInterface([]string{"EntitiesSurfaceFormsText_example"}),
    NotEntitiesSurfaceFormsText:      optional.NewInterface([]string{"EntitiesSurfaceFormsText_example"}),
    EntitiesTypes:                     optional.NewInterface([]string{"EntitiesTypes_example"}),
    NotEntitiesTypes:                  optional.NewInterface([]string{"EntitiesTypes_example"}),
    EntitiesLinksWikipedia:           optional.NewInterface([]string{"EntitiesLinksWikipedia_example"}),
    NotEntitiesLinksWikipedia:        optional.NewInterface([]string{"EntitiesLinksWikipedia_example"}),
    EntitiesLinksWikidata:            optional.NewInterface([]string{"EntitiesLinksWikidata_example"}),
    NotEntitiesLinksWikidata:         optional.NewInterface([]string{"EntitiesLinksWikidata_example"}),
    EntitiesStockTicker:              optional.NewInterface([]string{"EntitiesStockTicker_example"}),
    NotEntitiesStockTicker:           optional.NewInterface([]string{"EntitiesStockTicker_example"}),  
    EntitiesTitleSurfaceFormsText:    optional.NewInterface([]string{"EntitiesTitleSurfaceFormsText_example"}),
    NotEntitiesTitleSurfaceFormsText: optional.NewInterface([]string{"EntitiesTitleSurfaceFormsText_example"}),
    EntitiesBodySurfaceFormsText:     optional.NewInterface([]string{"EntitiesBodySurfaceFormsText_example"}),
    NotEntitiesBodyStockTicker:       optional.NewInterface([]string{"EntitiesBodyStockTicker_example"}),
    SentimentTitlePolarity:           optional.NewString("positive"),
    NotSentimentTitlePolarity:        optional.NewString("negative"),
    SentimentBodyPolarity:            optional.NewString("positive"),
    NotSentimentBodyPolarity:         optional.NewString("neutral"),
    MediaImagesCountMin:              optional.NewInt32(1),
    MediaImagesCountMax:              optional.NewInt32(4),
    MediaImagesWidthMin:              optional.NewInt32(640),
    MediaImagesWidthMax:              optional.NewInt32(1200),
    MediaImagesHeightMin:             optional.NewInt32(700),
    MediaImagesHeightMax:             optional.NewInt32(1500),
    MediaImagesContentLengthMin:      optional.NewInt32(25000),
    MediaImagesContentLengthMax:      optional.NewInt32(40000),
    MediaImagesFormat:                optional.NewInterface([]string{"JPEG"}),
    NotMediaImagesFormat:             optional.NewInterface([]string{"PNG"}),
    MediaVideosCountMin:              optional.NewInt32(1),
    MediaVideosCountMax:              optional.NewInt32(2),
    AuthorId:                         optional.NewInterface([]int32{123}),
    NotAuthorId:                      optional.NewInterface([]int32{321}),
    AuthorName:                       optional.NewString("Charlie Kelly"),
    NotAuthorName:                    optional.NewString("Frank Reynolds"),
    SourceId:                         optional.NewInterface([]int32{123}),
    NotSourceId:                      optional.NewInterface([]int32{321}),
    SourceName:                       optional.NewInterface([]string{"The Irish Times"}),
    NotSourceName:                    optional.NewInterface([]string{"The Irish Independent"}),
    SourceDomain:                     optional.NewInterface([]string{"bbc.com"}),
    NotSourceDomain:                  optional.NewInterface([]string{"cnn.com"}),
    SourceLocationsCountry:           optional.NewInterface([]string{"US"}),
    NotSourceLocationsCountry:        optional.NewInterface([]string{"GB"}),
    SourceLocationsState:             optional.NewInterface([]string{"Florida"}),
    NotSourceLocationsState:          optional.NewInterface([]string{"California"}),
    SourceLocationsCity:              optional.NewInterface([]string{"Miami"}),
    NotSourceLocationsCity:           optional.NewInterface([]string{"Austin"}),
    SourceScopesCountry:              optional.NewInterface([]string{"IE"}),
    NotSourceScopesCountry:           optional.NewInterface([]string{"DE"}),
    SourceScopesState:                optional.NewInterface([]string{"Illinois"}),
    NotSourceScopesState:             optional.NewInterface([]string{"Montana"}),
    SourceScopesCity:                 optional.NewInterface([]string{"Sheboygan"}),
    NotSourceScopesCity:              optional.NewInterface([]string{"Westport"}),
    SourceScopesLevel:                optional.NewInterface([]string{"national"}),
    NotSourceScopesLevel:             optional.NewInterface([]string{"international"}),
    SourceLinksInCountMin:            optional.NewInt32(1),
    SourceLinksInCountMax:            optional.NewInt32(3000),
    SourceRankingsAlexaRankMin:       optional.NewInt32(1),
    SourceRankingsAlexaRankMax:       optional.NewInt32(1000),
    SourceRankingsAlexaCountry:       optional.NewInterface([]string{"US"}),
    Clusters:                         optional.NewInterface([]int32{1234567}),
    Return_:                          optional.NewInterface([]string{"title"}),
    PerPage:                          optional.NewInt32(5),
    StoryId:                          optional.NewInt64(123),
    StoryUrl:                         optional.NewString("https://techcrunch.com/2016/04/07/aylien-launches-news-analysis-api-powered-by-its-deep-learning-tech/"),
    StoryTitle:                       optional.NewString("Aylien launches news analysis API powered by its deep learning tech"),
    StoryBody:                        optional.NewString("Text analysis startup Aylien, which uses deep learning"),
    BoostBy:                          optional.NewString("popularity"),
    Aql:                              optional.NewString("aql_example"),
    StoryLanguage:                    optional.NewString("auto"),
  }

  RelatedStoriesResponse, res, err := api.ListRelatedStories(context.Background(), relatedStoriesParams)

  if err != nil {
    panic(err)
  }

  _ = res

  for _, relatedStory := range RelatedStoriesResponse.RelatedStories{
    fmt.Println(relatedStory.PublishedAt, relatedStory.Title, " / ", relatedStory.Source.Name)
  }
}

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 URL

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

HTTP 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
clusters[]
array [integer]
(query)

This parameter is used for finding stories associated with a specific cluster (currently accepts one cluster per search).
translations.{language}.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.{language}.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 advanced search operators.
body
string
(query)

This parameter is used for finding stories whose title contains a specific keyword. It supports advanced search 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. To ensure the most accurate results, you should always incude a this parameter listing the languages you want to retrieve content in. 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, which is used for defining the type of the taxonomy for the rest of the categories queries, is available for our standard IPTC and IAB category taxonomies. Please click here to learn more about our Smart Tagger taxonomies, and about using the right taxonomy for you.
categories.confident
boolean
(query)

This parameter, which is used for finding stories whose categories are confident, is available for our standard IPTC and IAB category taxonomies. Please click here to learn more about our Smart Tagger taxonomies, and about using the right taxonomy for you.

Default value: true
categories.id[]
array [string]
(query)

This parameter, which is used for finding stories by categories id, is available for our standard IPTC and IAB category taxonomies. Please click here to learn more about our Smart Tagger taxonomies, and about using the right taxonomy for you.
!categories.id[]
array [string]
(query)

This parameter, which is used for excluding stories by categories id, is available for our standard IPTC and IAB category taxonomies. Please click here to learn more about our Smart Tagger taxonomies, and about using the right taxonomy for you.
categories.level[]
array [integer]
(query)

This parameter, which is used for finding stories by categories level, is available for our standard IPTC and IAB category taxonomies. Please click here to learn more about our Smart Tagger taxonomies, and about using the right taxonomy for you.
!categories.level[]
array [integer]
(query)

This parameter, which is used for excluding stories by categories level, is available for our standard IPTC and IAB category taxonomies. Please click here to learn more about our Smart Tagger taxonomies, and about using the right taxonomy for you.
industries
(query)

This parameter is not available in flat search. However, you can filter for articles containing specific industries using AQL. You can read more about the industries filter here here, and find industry ids and labels here.
entities.id[]
array [string]
(query)

This parameter is used to find stories based on the specified entities id in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
!entities.id[]
array [string]
(query)

This parameter is used to exclude stories based on the specified entities id in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
entities.surface_forms.text[]
array [string]
(query)

This parameter is used to find stories based on the specified entities surface form text in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
!entities.surface_forms.text[]
array [string]
(query)

This parameter is used to exclude stories based on the specified entities surface form text in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
entities.types[]
array [string]
(query)

This parameter is used to find stories based on the specified entities type in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
!entities.types[]
array [string]
(query)

This parameter is used to exclude stories based on the specified entities type in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
entities.links.wikipedia[]
array [string]
(query)

This parameter is used to find stories based on the specified entities wikipedia URL in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
!entities.links.wikipedia[]
array [string]
(query)

This parameter is used to exclude stories based on the specified entities wikipedia URL in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
entities.links.wikidata[]
array [string]
(query)

This parameter is used to find stories based on the specified entities wikidata URL in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
!entities.links.wikidata[]
array [string]
(query)

This parameter is used to exclude stories based on the specified entities wikidata URL in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
entities.stock_ticker[]
array [string]
(query)

This parameter is used to find stories based on the specified entities stock tickers in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
!entities.stock_ticker[]
array [string]
(query)

This parameter is used to exclude stories based on the specified entities stock tickers in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
entities.title.surface_forms.text[]
array [string]
(query)

This parameter is used to find stories based on the specified entities surface form text in story titles. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
!entities.title.surface_forms.text[]
array [string]
(query)

This parameter is used to exclude stories based on the specified entities surface form text in story titles. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
entities.body.surface_forms.text[]
array [string]
(query)

This parameter is used to find stories based on the specified entities surface form text in story bodies. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
!entities.body.surface_forms.text[]
array [string]
(query)

This parameter is used to exclude stories based on the specified entities surface form text in story bodies. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
sentiment.title.polarity
string [string]
(query)

This parameter is used for finding stories whose title sentiment is the specified value.
!sentiment.title.polarity
string [string]
(query)

This parameter is used for excluding stories whose title sentiment is the specified value.
sentiment.body.polarity
string [string]
(query)

This parameter is used for finding stories whose body sentiment is the specified value.
!sentiment.body.polarity
string [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.
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, 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
aql
string
(query)

This parameter is used to supply a sub-query in AYLIEN's custom DSL to leverage advanced keyword operators and enhanced entity search.
per_page
integer
(query)

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

Default value: 3

Response Codes

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

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)

# load the gem
require 'aylien_news_api'
require 'pp'
# setup authorization
AylienNewsApi.configure do |config|
  # Configure API key authorization: app_id
  config.api_key['X-AYLIEN-NewsAPI-Application-ID'] = 'YOUR APP ID'
  # Uncomment the following line to set a prefix for the API key, e.g. 'Bearer' (defaults to nil)
  #config.api_key_prefix['X-AYLIEN-NewsAPI-Application-ID'] = 'Bearer'

  # Configure API key authorization: app_key
  config.api_key['X-AYLIEN-NewsAPI-Application-Key'] = 'YOUR APP KEY'
  # Uncomment the following line to set a prefix for the API key, e.g. 'Bearer' (defaults to nil)
  #config.api_key_prefix['X-AYLIEN-NewsAPI-Application-Key'] = 'Bearer'
end

api_instance = AylienNewsApi::DefaultApi.new
type = 'source_names'
term = 'News'
opts = {
  :language => 'en',
  :per_page => 3
}

begin
  #List autocompletes
  result = api_instance.list_autocompletes(type, term, opts)
  pp result
rescue AylienNewsApi::ApiError => e
  puts "Exception when calling DefaultApi->list_autocompletes: #{e}"
end

var AylienNewsApi = require('aylien-news-api');
var defaultClient = AylienNewsApi.ApiClient.instance;

// Configure API key authorization: app_id
var app_id = defaultClient.authentications['app_id'];
app_id.apiKey = 'YOUR_APP_ID';
// Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
//app_id.apiKeyPrefix = 'Token';
// Configure API key authorization: app_key
var app_key = defaultClient.authentications['app_key'];
app_key.apiKey = 'YOUR_API_KEY';
// Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
//app_key.apiKeyPrefix = 'Token';

var apiInstance = new AylienNewsApi.DefaultApi();
var type = 'source_names';
var term = 'News';
var opts = {
  'language': "en",
  'perPage': 3  
};
apiInstance.listAutocompletes(type, term, opts, (error, data, response) => {
  if (error) {
    console.error(error);
  } else {
    console.log(data.autocompletes);
  }
});

package main

// Import the library
import (
  "context"
  "fmt"
  newsapi "github.com/AYLIEN/aylien_newsapi_go"
  "github.com/antihax/optional"
)

func main() {

  cfg := newsapi.NewConfiguration()
  cfg.DefaultHeader["X-AYLIEN-NewsAPI-Application-ID"] = "YOUR_APP_ID"
  cfg.DefaultHeader["X-AYLIEN-NewsAPI-Application-Key"] = "YOUR_API_KEY"

  client := newsapi.NewAPIClient(cfg)
  api := client.DefaultApi

  autocompleteType := "source_names"
  term := "The Daily"

  autocompletesParams := &newsapi.ListAutocompletesOpts{
  Language:      optional.NewString("en"),
  PerPage:      optional.NewInt32(5),
  }

  autocompletesResponse, res, err := api.ListAutocompletes(context.Background(), autocompleteType, term, autocompletesParams)
  if err != nil {
    panic(err)
  }
  _ = res

  for _, result := range autocompletesResponse.Autocompletes{
    fmt.Println(result)
  }

}

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 URL

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

HTTP 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 Codes

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_id': ['entities_id_example'],
  'not_entities_id': ['entities_id_example'],
  'entities_surface_forms_text': ['entities_surface_form_text_example'],
  'not_entities_surface_forms_text': ['entities_surface_form_text_example'],
  'entities_types': ['entities_types_example'],
  'not_entities_types': ['entities_types_example']
  'entities_links_wikipedia': ['entities_links_wikipedia_example'],
  'not_entities_links_wikipedia': ['entities_links_wikipedia_example'],
  'entities_links_wikidata': ['entities_links_wikidata_example'],
  'not_entities_links_wikidata': ['entities_links_wikidata_example'],
  'entities_stock_ticker': ['entities_stock_ticker_example'],
  'not_entities_stock_ticker': ['entities_stock_ticker_example'],
  'entities_title_surface_forms_text': ['entities_title_surface_form_text_example'],
  'not_entities_title_surface_forms_text': ['entities_title_surface_form_text_example'],
  'entities_body_surface_forms_text': ['entities_body_surface_form_text_example'],
  'not_entities_body_surface_forms_text': ['entities_body_surface_form_text_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'],
  'published_at_start': 'NOW-7DAYS/DAY',
  'published_at_end': 'NOW/DAY',
  'period': '+1DAY',
  'aql': 'aql_example'
}

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)

# load the gem
require 'aylien_news_api'
require 'pp'
# setup authorization
AylienNewsApi.configure do |config|
  # Configure API key authorization: app_id
  config.api_key['X-AYLIEN-NewsAPI-Application-ID'] = 'YOUR API KEY'
  # Uncomment the following line to set a prefix for the API key, e.g. 'Bearer' (defaults to nil)
  #config.api_key_prefix['X-AYLIEN-NewsAPI-Application-ID'] = 'Bearer'

  # Configure API key authorization: app_key
  config.api_key['X-AYLIEN-NewsAPI-Application-Key'] = 'YOUR API KEY'
  # Uncomment the following line to set a prefix for the API key, e.g. 'Bearer' (defaults to nil)
  #config.api_key_prefix['X-AYLIEN-NewsAPI-Application-Key'] = 'Bearer'
end

api_instance = AylienNewsApi::DefaultApi.new

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_id => ['entities_id_example'],
  :not_entities_id => ['entities_id_example'],
  :entities_surface_forms_text => ['entities_surface_form_text_example'],
  :not_entities_surface_forms_text => ['entities_surface_form_text_example'],
  :entities_types => ['entities_types_example'],
  :not_entities_types => ['entities_types_example'],
  :entities_links_wikipedia => ['entities_links_wikipedia_example'],
  :not_entities_links_wikipedia => ['entities_links_wikipedia_example'],
  :entities_links_wikidata => ['entities_links_wikidata_example'],
  :not_entities_links_wikidata => ['entities_links_wikidata_example'],
  :entities_stock_ticker => ['entities_stock_ticker_example'],
  :not_entities_stock_ticker => ['entities_stock_ticker_example'],
  :entities_title_surface_forms_text => ['entities_title_surface_form_text_example'],
  :not_entities_title_surface_forms_text => ['entities_title_surface_form_text_example'],
  :entities_body_surface_forms_text => ['entities_body_surface_form_text_example'],
  :not_entities_body_surface_forms_text => ['entities_body_surface_form_text_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'],
  :published_at_start => 'NOW-7DAYS/DAY',
  :published_at_end => 'NOW/DAY',
  :period => '+1DAY',
  :aql => 'aql_example'
}

begin
  #List time series
  result = api_instance.list_time_series(opts)
  pp result
rescue AylienNewsApi::ApiError => e
  puts "Exception when calling DefaultApi->list_time_series: #{e}"
end

var AylienNewsApi = require('aylien-news-api');
var defaultClient = AylienNewsApi.ApiClient.instance;
// Configure API key authorization: app_id
var app_id = defaultClient.authentications['app_id'];
app_id.apiKey = 'YOUR APP ID';
// Uncomment the following line to set a prefix for the API key, e.g. 'Token' (defaults to null)
//app_id.apiKeyPrefix = 'Token';
// Configure API key authorization: app_key
var app_key = defaultClient.authentications['app_key'];
app_key.apiKey = 'YOUR API KEY';
// Uncomment the following line to set a prefix for the API key, e.g. 'Token' (defaults to null)
//app_key.apiKeyPrefix = 'Token';

var apiInstance = new AylienNewsApi.DefaultApi();

var opts = {
  'id': [null],
  'notId': [null],
  'title': 'title_example',
  'body': 'body_example',
  'text': 'text_example',
  'translationsEnTitle': 'translationsEnTitle_example',
  'translationsEnBody': 'translationsEnBody_example',
  'translationsEnText': 'translationsEnText_example',
  'language': ['null'],
  'notLanguage': ['null'],
  'categoriesTaxonomy': 'categoriesTaxonomy_example',
  'categoriesConfident': true,
  'categoriesId': ['null'],
  'notCategoriesId': ['null'],
  'categoriesLevel': [null],
  'notCategoriesLevel': [null],
  'entitiesId': ["entitiesId_example"],
  'notEntitiesId': ["entitiesId_example"],
  'entitiesSurfaceFormsText': ["entitiesSurfaceFormsText_example"],
  'notEntitiesSurfaceFormsText': ["entitiesSurfaceFormsText_example"],
  'entitiesTypes': ["entitiesTypes_example"],
  'notEntitiesTypes': ["entitiesTypes_example"],
  'entitiesLinksWikipedia': ["entitiesLinksWikipedia_example"],
  'notEntitiesLinksWikipedia': ["entitiesLinksWikipedia_example"],
  'entitiesLinksWikidata': ["entitiesLinksWikidata_example"],
  'notEntitiesLinksWikidata': ["entitiesLinksWikidata_example"], 
  'entitiesStockTicker': ["entitiesStockTicker_example"],
  'notEntitiesStockTicker': ["entitiesStockTicker_example"], 
  'entitiesTitleSurfaceFormsText': ["entitiesTitleSurfaceFormsText_example"],
  'notEntitiesTitleSurfaceFormsText': ["entitiesTitleSurfaceFormsText_example"],
  'entitiesBodySurfaceFormsText': ["entitiesBodySurfaceFormsText_example"],
  'notEntitiesBodySurfaceFormsText': ["entitiesBodySurfaceFormsText_example"],
  'sentimentTitlePolarity': "sentimentTitlePolarity_example",
  'notSentimentTitlePolarity': "sentimentTitlePolarity_example",
  'sentimentBodyPolarity': "sentimentBodyPolarity_example",
  'notSentimentBodyPolarity': "sentimentBodyPolarity_example",
  'mediaImagesCountMin': 56,
  'mediaImagesCountMax': 56,
  'mediaImagesWidthMin': 56,
  'mediaImagesWidthMax': 56,
  'mediaImagesHeightMin': 56,
  'mediaImagesHeightMax': 56,
  'mediaImagesContentLengthMin': 56,
  'mediaImagesContentLengthMax': 56,
  'mediaImagesFormat': ['null'],
  'notMediaImagesFormat': ['null'],
  'mediaVideosCountMin': 56,
  'mediaVideosCountMax': 56,
  'authorId': [null],
  'notAuthorId': [null],
  'authorName': 'authorName_example',
  'notAuthorName': 'authorName_example',
  'sourceId': [null],
  'notSourceId': [null],
  'sourceName': ['null'],
  'notSourceName': ['null'],
  'sourceDomain': ['null'],
  'notSourceDomain': ['null'],
  'sourceLocationsCountry': ['null'],
  'notSourceLocationsCountry': ['null'],
  'sourceLocationsState': ['null'],
  'notSourceLocationsState': ['null'],
  'sourceLocationsCity': ['null'],
  'notSourceLocationsCity': ['null'],
  'sourceScopesCountry': ['null'],
  'notSourceScopesCountry': ['null'],
  'sourceScopesState': ['null'],
  'notSourceScopesState': ['null'],
  'sourceScopesCity': ['null'],
  'notSourceScopesCity': ['null'],
  'sourceScopesLevel': ['null'],
  'notSourceScopesLevel': ['null'],
  'sourceLinksInCountMin': 56,
  'sourceLinksInCountMax': 56,
  'sourceRankingsAlexaRankMin': 56,
  'sourceRankingsAlexaRankMax': 56,
  'sourceRankingsAlexaCountry': ['null'],
  'publishedAtStart': 'publishedAtStart_example',
  'publishedAtEnd': 'publishedAtEnd_example',
  'period': 'period_example',
  'aql': 'aql_example'
};

apiInstance.listTimeSeries(opts, (error, data, response) => {
  if (error) {
    console.error(error);
  } else {
    console.log(data.time_series);
  }
});

package main

// Import the library
import (
  "context"
  "fmt"
  newsapi "github.com/AYLIEN/aylien_newsapi_go"
  "github.com/antihax/optional"
)

func main() {

  cfg := newsapi.NewConfiguration()
  cfg.DefaultHeader["X-AYLIEN-NewsAPI-Application-ID"] = "YOUR_APP_ID"
  cfg.DefaultHeader["X-AYLIEN-NewsAPI-Application-Key"] = "YOUR_API_KEY"

  client := newsapi.NewAPIClient(cfg)
  api := client.DefaultApi


  timeSeriesParams := &newsapi.ListTimeSeriesOpts{
    Period:                           optional.NewString("+1DAY"),
    PublishedAtStart:                 optional.NewString("NOW-1MONTH"),
    PublishedAtEnd:                   optional.NewString("NOW-1DAY"),
    Id:                               optional.NewInterface([]int64{123}),
    NotId:                            optional.NewInterface([]int64{123}),
    Title:                            optional.NewString("startup"),
    Body:                             optional.NewString("investment"),
    Text:                             optional.NewString("AI"),
    TranslationsEnTitle:              optional.NewString("Trump"),
    TranslationsEnBody:               optional.NewString("bank"),
    TranslationsEnText:               optional.NewString("sanctions"),
    Language:                         optional.NewInterface([]string{"en"}),
    NotLanguage:                      optional.NewInterface([]string{"zh-cn"}),
    CategoriesTaxonomy:               optional.NewString("iptc-subjectcode"),
    CategoriesConfident:              optional.NewBool(true),
    CategoriesId:                     optional.NewInterface([]string{"04000000"}),
    NotCategoriesId:                  optional.NewInterface([]string{"17000000"}),
    CategoriesLevel:                  optional.NewInterface([]int32{1}),
    NotCategoriesLevel:               optional.NewInterface([]int32{2, 3}),
    EntitiesId:                       optional.NewInterface([]string{"EntitiesId_example"}),
    NotEntitiesId:                    optional.NewInterface([]string{"EntitiesId_example"}),
    EntitiesSurfaceFormsText:         optional.NewInterface([]string{"EntitiesSurfaceFormsText_example"}),
    NotEntitiesSurfaceFormsText:      optional.NewInterface([]string{"EntitiesSurfaceFormsText_example"}),
    EntitiesTypes:                     optional.NewInterface([]string{"EntitiesTypes_example"}),
    NotEntitiesTypes:                  optional.NewInterface([]string{"EntitiesTypes_example"}),
    EntitiesLinksWikipedia:           optional.NewInterface([]string{"EntitiesLinksWikipedia_example"}),
    NotEntitiesLinksWikipedia:        optional.NewInterface([]string{"EntitiesLinksWikipedia_example"}),
    EntitiesLinksWikidata:            optional.NewInterface([]string{"EntitiesLinksWikidata_example"}),
    NotEntitiesLinksWikidata:         optional.NewInterface([]string{"EntitiesLinksWikidata_example"}),
    EntitiesStockTicker:              optional.NewInterface([]string{"EntitiesStockTicker_example"}),
    NotEntitiesStockTicker:           optional.NewInterface([]string{"EntitiesStockTicker_example"}),  
    EntitiesTitleSurfaceFormsText:    optional.NewInterface([]string{"EntitiesTitleSurfaceFormsText_example"}),
    NotEntitiesTitleSurfaceFormsText: optional.NewInterface([]string{"EntitiesTitleSurfaceFormsText_example"}),
    EntitiesBodySurfaceFormsText:     optional.NewInterface([]string{"EntitiesBodySurfaceFormsText_example"}),
    NotEntitiesBodySurfaceFormsText:  optional.NewInterface([]string{"EntitiesBodySurfaceFormsText_example"}),
    SentimentTitlePolarity:           optional.NewString("positive"),
    NotSentimentTitlePolarity:        optional.NewString("negative"),
    SentimentBodyPolarity:            optional.NewString("positive"),
    NotSentimentBodyPolarity:         optional.NewString("neutral"),
    MediaImagesCountMin:              optional.NewInt32(1),
    MediaImagesCountMax:              optional.NewInt32(4),
    MediaImagesWidthMin:              optional.NewInt32(640),
    MediaImagesWidthMax:              optional.NewInt32(1200),
    MediaImagesHeightMin:             optional.NewInt32(700),
    MediaImagesHeightMax:             optional.NewInt32(1500),
    MediaImagesContentLengthMin:      optional.NewInt32(25000),
    MediaImagesContentLengthMax:      optional.NewInt32(40000),
    MediaImagesFormat:                optional.NewInterface([]string{"JPEG"}),
    NotMediaImagesFormat:             optional.NewInterface([]string{"PNG"}),
    MediaVideosCountMin:              optional.NewInt32(1),
    MediaVideosCountMax:              optional.NewInt32(2),
    AuthorId:                         optional.NewInterface([]int32{123}),
    NotAuthorId:                      optional.NewInterface([]int32{321}),
    AuthorName:                       optional.NewString("Charlie Kelly"),
    NotAuthorName:                    optional.NewString("Frank Reynolds"),
    SourceId:                         optional.NewInterface([]int32{123}),
    NotSourceId:                      optional.NewInterface([]int32{321}),
    SourceName:                       optional.NewInterface([]string{"The Irish Times"}),
    NotSourceName:                    optional.NewInterface([]string{"The Irish Independent"}),
    SourceDomain:                     optional.NewInterface([]string{"bbc.com"}),
    NotSourceDomain:                  optional.NewInterface([]string{"cnn.com"}),
    SourceLocationsCountry:           optional.NewInterface([]string{"US"}),
    NotSourceLocationsCountry:        optional.NewInterface([]string{"GB"}),
    SourceLocationsState:             optional.NewInterface([]string{"Florida"}),
    NotSourceLocationsState:          optional.NewInterface([]string{"California"}),
    SourceLocationsCity:              optional.NewInterface([]string{"Miami"}),
    NotSourceLocationsCity:           optional.NewInterface([]string{"Austin"}),
    SourceScopesCountry:              optional.NewInterface([]string{"IE"}),
    NotSourceScopesCountry:           optional.NewInterface([]string{"DE"}),
    SourceScopesState:                optional.NewInterface([]string{"Illinois"}),
    NotSourceScopesState:             optional.NewInterface([]string{"Montana"}),
    SourceScopesCity:                 optional.NewInterface([]string{"Sheboygan"}),
    NotSourceScopesCity:              optional.NewInterface([]string{"Westport"}),
    SourceScopesLevel:                optional.NewInterface([]string{"national"}),
    NotSourceScopesLevel:             optional.NewInterface([]string{"international"}),
    SourceLinksInCountMin:            optional.NewInt32(1),
    SourceLinksInCountMax:            optional.NewInt32(3000),
    SourceRankingsAlexaRankMin:       optional.NewInt32(1),
    SourceRankingsAlexaRankMax:       optional.NewInt32(1000),
    SourceRankingsAlexaCountry:       optional.NewInterface([]string{"US"}),
    PublishedAtStart:                optional.NewString("publishedAtStart_example")
    PublishedAtEnd:                  optional.NewString("publishedAtEnd_example"),
    Period:                          optional.NewString("period_example"),
    Aql:                             optional.NewString("aql_example"),
  }

  timeSeriesResponse, res, err := api.ListTimeSeries(context.Background(), timeSeriesParams)

  if err != nil {
    panic(err)
  }

  _ = res

  for _, period := range timeSeriesResponse.TimeSeries {
    fmt.Println(period)
  }
}

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.

To read about what the Time Series endpoint is and see a use case, check out our blog

Since we learned that categories are a very important part of our users' workflows for filtering for relevant content, we have introduced the Smart Tagger. this new feature is our latest article tagging feature that leverages state-of-the-art classification models built using a vast collection of manually tagged news articles based on domain-specific industry and topical category taxonomies. With a taxonomy of ~3000 topical categories and ~1500 industries, the Smart tagger classifies articles with a high precision, making it easier for users to filter for articles most relevant to them and their usecases. To sign up for a free trial of the Smart Tagger, click on the button below.

View Taxonomy Explorer



HTTP Request URL

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

HTTP 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
clusters[]
array [integer]
(query)

This parameter is used for finding stories associated with a specific cluster (currently accepts one cluster per search).
translations.{language}.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.{language}.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 advanced keyword operators.
body
string
(query)

This parameter is used for finding stories whose body contains a specific keyword. It supports advanced search 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. To ensure the most accurate results, you should always incude a this parameter listing the languages you want to see data for. 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, wihch is used for defining the type of the taxonomy for the rest of the categories queries, is available for our standard IPTC and IAB category taxonomies. Please click here to learn more about our Smart Tagger taxonomies, and about using the right taxonomy for you.
categories.confident
boolean
(query)

This parameter, which is used for finding stories whose categories are confident, is available for our standard IPTC and IAB category taxonomies. Please click here to learn more about our Smart Tagger taxonomies, and about using the right taxonomy for you.

Default value: true
categories.id[]
array [string]
(query)

This parameter, which is used for finding stories by categories id, is available for our standard IPTC and IAB category taxonomies. Please click here to learn more about our Smart Tagger taxonomies, and about using the right taxonomy for you.
!categories.id[]
array [string]
(query)

This parameter, which is used for excluding stories by categories id, is available for our standard IPTC and IAB category taxonomies. Please click here to learn more about our Smart Tagger taxonomies, and about using the right taxonomy for you.
categories.level[]
array [integer]
(query)

This parameter, which is used for finding stories by categories level, is available for our standard IPTC and IAB category taxonomies. Please click here to learn more about our Smart Tagger taxonomies, and about using the right taxonomy for you.
!categories.level[]
array [integer]
(query)

This parameter, which is used for excluding stories by categories level, is available for our standard IPTC and IAB category taxonomies. Please click here to learn more about our Smart Tagger taxonomies, and about using the right taxonomy for you.
industries
(query)

This parameter is not available in flat search. However, you can filter for articles containing specific industries using AQL. You can read more about the industries filter here here, and find industry ids and labels here.
entities.id[]
array [string]
(query)

This parameter is used to find stories based on the specified entities id in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
!entities.id[]
array [string]
(query)

This parameter is used to exclude stories based on the specified entities id in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
entities.surface_forms.text[]
array [string]
(query)

This parameter is used to find stories based on the specified entities surface form text in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
!entities.surface_forms.text[]
array [string]
(query)

This parameter is used to exclude stories based on the specified entities surface form text in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
entities.types[]
array [string]
(query)

This parameter is used to find stories based on the specified entities type in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
!entities.types[]
array [string]
(query)

This parameter is used to exclude stories based on the specified entities type in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
entities.links.wikipedia[]
array [string]
(query)

This parameter is used to find stories based on the specified entities wikipedia URL in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
!entities.links.wikipedia[]
array [string]
(query)

This parameter is used to exclude stories based on the specified entities wikipedia URL in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
entities.links.wikidata[]
array [string]
(query)

This parameter is used to find stories based on the specified entities wikidata URL in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
!entities.links.wikidata[]
array [string]
(query)

This parameter is used to exclude stories based on the specified entities wikidata URL in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
entities.stock_ticker[]
array [string]
(query)

This parameter is used to find stories based on the specified entities stock tickers in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
!entities.stock_ticker[]
array [string]
(query)

This parameter is used to exclude stories based on the specified entities stock tickers in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
entities.title.surface_forms.text[]
array [string]
(query)

This parameter is used to find stories based on the specified entities surface form text in story titles. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
!entities.title.surface_forms.text[]
array [string]
(query)

This parameter is used to exclude stories based on the specified entities surface form text in story titles. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
entities.body.surface_forms.text[]
array [string]
(query)

This parameter is used to find stories based on the specified entities surface form text in story bodies. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
!entities.body.surface_forms.text[]
array [string]
(query)

This parameter is used to exclude stories based on the specified entities surface form text in story bodies. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
sentiment.title.polarity
string [string]
(query)

This parameter is used for finding stories whose title sentiment is the specified value.
!sentiment.title.polarity
string [string]
(query)

This parameter is used for excluding stories whose title sentiment is the specified value.
sentiment.body.polarity
string [string]
(query)

This parameter is used for finding stories whose body sentiment is the specified value.
!sentiment.body.polarity
string [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.
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
aql
string
(query)

This parameter is used to supply a sub-query in AYLIEN's custom DSL to leverage advanced keyword operators and enhanced entity search.

Response Codes

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_id': ['entities_id_example'],
  'not_entities_id': ['entities_id_example'],
  'entities_surface_forms_text': ['entities_surface_form_text_example'],
  'not_entities_surface_forms_text': ['entities_surface_form_text_example'],
  'entities_types': ['entities_types_example'],
  'not_entities_types': ['entities_types_example']
  'entities_links_wikipedia': ['entities_links_wikipedia_example'],
  'not_entities_links_wikipedia': ['entities_links_wikipedia_example'],
  'entities_links_wikidata': ['entities_links_wikidata_example'],
  'not_entities_links_wikidata': ['entities_links_wikidata_example'],
  'entities_stock_ticker': ['entities_stock_ticker_example'],
  'not_entities_stock_ticker': ['entities_stock_ticker_example'],
  'entities_title_surface_forms_text': ['entities_title_surface_form_text_example'],
  'not_entities_title_surface_forms_text': ['entities_title_surface_form_text_example'],
  'entities_body_surface_forms_text': ['entities_body_surface_form_text_example'],
  'not_entities_body_surface_forms_text': ['entities_body_surface_form_text_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'],
  'aql': 'aql_example'
}

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)

# load the gem
require 'aylien_news_api'
require 'pp'
# setup authorization
AylienNewsApi.configure do |config|
  # Configure API key authorization: app_id
  config.api_key['X-AYLIEN-NewsAPI-Application-ID'] = 'YOUR API KEY'
  # Uncomment the following line to set a prefix for the API key, e.g. 'Bearer' (defaults to nil)
  #config.api_key_prefix['X-AYLIEN-NewsAPI-Application-ID'] = 'Bearer'

  # Configure API key authorization: app_key
  config.api_key['X-AYLIEN-NewsAPI-Application-Key'] = 'YOUR API KEY'
  # Uncomment the following line to set a prefix for the API key, e.g. 'Bearer' (defaults to nil)
  #config.api_key_prefix['X-AYLIEN-NewsAPI-Application-Key'] = 'Bearer'
end

api_instance = AylienNewsApi::DefaultApi.new
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_id => ['entities_id_example'],
  :not_entities_id => ['entities_id_example'],
  :entities_surface_forms_text => ['entities_surface_form_text_example'],
  :not_entities_surface_forms_text => ['entities_surface_form_text_example'],
  :entities_types => ['entities_types_example'],
  :not_entities_types => ['entities_types_example'],
  :entities_links_wikipedia => ['entities_links_wikipedia_example'],
  :not_entities_links_wikipedia => ['entities_links_wikipedia_example'],
  :entities_links_wikidata => ['entities_links_wikidata_example'],
  :not_entities_links_wikidata => ['entities_links_wikidata_example'],
  :entities_stock_ticker => ['entities_stock_ticker_example'],
  :not_entities_stock_ticker => ['entities_stock_ticker_example'],
  :entities_title_surface_forms_text => ['entities_title_surface_form_text_example'],
  :not_entities_title_surface_forms_text => ['entities_title_surface_form_text_example'],
  :entities_body_surface_forms_text => ['entities_body_surface_form_text_example'],
  :not_entities_body_surface_forms_text => ['entities_body_surface_form_text_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'],
  :aql => 'aql_example'
}

begin
  #List trends
  result = api_instance.list_trends(field, opts)
  pp result
rescue AylienNewsApi::ApiError => e
  puts "Exception when calling DefaultApi->list_trends: #{e}"
end

var AylienNewsApi = require('aylien-news-api');
var defaultClient = AylienNewsApi.ApiClient.instance;

// Configure API key authorization: app_id
var app_id = defaultClient.authentications['app_id'];
app_id.apiKey = 'YOUR APP ID';
// Uncomment the following line to set a prefix for the API key, e.g. 'Token' (defaults to null)
//app_id.apiKeyPrefix = 'Token';

// Configure API key authorization: app_key
var app_key = defaultClient.authentications['app_key'];
app_key.apiKey = 'YOUR API KEY';
// Uncomment the following line to set a prefix for the API key, e.g. 'Token' (defaults to null)
//app_key.apiKeyPrefix = 'Token';

var apiInstance = new AylienNewsApi.DefaultApi();
var field = 'keywords';

var opts = {
  'id': [null],
  'notId': [null],
  'title': 'title_example',
  'body': 'body_example',
  'text': 'text_example',
  'translationsEnTitle': 'translationsEnTitle_example',
  'translationsEnBody': 'translationsEnBody_example',
  'translationsEnText': 'translationsEnText_example',
  'language': ['null'],
  'notLanguage': ['null'],
  'publishedAtStart': 'publishedAtStart_example',
  'publishedAtEnd': 'publishedAtEnd_example',
  'categoriesTaxonomy': 'categoriesTaxonomy_example',
  'categoriesConfident': true,
  'categoriesId': ['null'],
  'notCategoriesId': ['null'],
  'categoriesLevel': [null],
  'notCategoriesLevel': [null],
  'entitiesId': ["entitiesId_example"],
  'notEntitiesId': ["entitiesId_example"],
  'entitiesSurfaceFormsText': ["entitiesSurfaceFormsText_example"],
  'notEntitiesSurfaceFormsText': ["entitiesSurfaceFormsText_example"],
  'entitiesTypes': ["entitiesTypes_example"],
  'notEntitiesTypes': ["entitiesTypes_example"],
  'entitiesLinksWikipedia': ["entitiesLinksWikipedia_example"],
  'notEntitiesLinksWikipedia': ["entitiesLinksWikipedia_example"],
  'entitiesLinksWikidata': ["entitiesLinksWikidata_example"],
  'notEntitiesLinksWikidata': ["entitiesLinksWikidata_example"], 
  'entitiesStockTicker': ["entitiesStockTicker_example"],
  'notEntitiesStockTicker': ["entitiesStockTicker_example"], 
  'entitiesTitleSurfaceFormsText': ["entitiesTitleSurfaceFormsText_example"],
  'notEntitiesTitleSurfaceFormsText': ["entitiesTitleSurfaceFormsText_example"],
  'entitiesBodySurfaceFormsText': ["entitiesBodySurfaceFormsText_example"],
  'notEntitiesBodySurfaceFormsText': ["entitiesBodySurfaceFormsText_example"],
  'sentimentTitlePolarity': "sentimentTitlePolarity_example",
  'notSentimentTitlePolarity': "sentimentTitlePolarity_example",
  'sentimentBodyPolarity': "sentimentBodyPolarity_example",
  'notSentimentBodyPolarity': "sentimentBodyPolarity_example",
  'mediaImagesCountMin': 56,
  'mediaImagesCountMax': 56,
  'mediaImagesWidthMin': 56,
  'mediaImagesWidthMax': 56,
  'mediaImagesHeightMin': 56,
  'mediaImagesHeightMax': 56,
  'mediaImagesContentLengthMin': 56,
  'mediaImagesContentLengthMax': 56,
  'mediaImagesFormat': ['null'],
  'notMediaImagesFormat': ['null'],
  'mediaVideosCountMin': 56,
  'mediaVideosCountMax': 56,
  'authorId': [null],
  'notAuthorId': [null],
  'authorName': 'authorName_example',
  'notAuthorName': 'authorName_example',
  'sourceId': [null],
  'notSourceId': [null],
  'sourceName': ['null'],
  'notSourceName': ['null'],
  'sourceDomain': ['null'],
  'notSourceDomain': ['null'],
  'sourceLocationsCountry': ['null'],
  'notSourceLocationsCountry': ['null'],
  'sourceLocationsState': ['null'],
  'notSourceLocationsState': ['null'],
  'sourceLocationsCity': ['null'],
  'notSourceLocationsCity': ['null'],
  'sourceScopesCountry': ['null'],
  'notSourceScopesCountry': ['null'],
  'sourceScopesState': ['null'],
  'notSourceScopesState': ['null'],
  'sourceScopesCity': ['null'],
  'notSourceScopesCity': ['null'],
  'sourceScopesLevel': ['null'],
  'notSourceScopesLevel': ['null'],
  'sourceLinksInCountMin': 56,
  'sourceLinksInCountMax': 56,
  'sourceRankingsAlexaRankMin': 56,
  'sourceRankingsAlexaRankMax': 56,
  'sourceRankingsAlexaCountry': ['null'],
  'aql': 'aql_example'
};

apiInstance.listTrends(field, opts, (error, data, response) => {
  if (error) {
    console.error(error);
  } else {
    console.log(data.trends);
  }
});

package main

// Import the library
import (
  "context"
  "fmt"
  newsapi "github.com/AYLIEN/aylien_newsapi_go"
  "github.com/antihax/optional"
)

func main() {

  cfg := newsapi.NewConfiguration()
  cfg.DefaultHeader["X-AYLIEN-NewsAPI-Application-ID"] = "YOUR_APP_ID"
  cfg.DefaultHeader["X-AYLIEN-NewsAPI-Application-Key"] = "YOUR_API_KEY"

  client := newsapi.NewAPIClient(cfg)
  api := client.DefaultApi

  field := "keywords"

  trendsParams := &newsapi.ListTrendsOpts{
    Id:                               optional.NewInterface([]int64{123}),
    NotId:                            optional.NewInterface([]int64{123}),
    Title:                            optional.NewString("startup"),
    Body:                             optional.NewString("investment"),
    Text:                             optional.NewString("AI"),
    TranslationsEnTitle:              optional.NewString("Trump"),
    TranslationsEnBody:               optional.NewString("bank"),
    TranslationsEnText:               optional.NewString("sanctions"),
    Language:                         optional.NewInterface([]string{"en"}),
    NotLanguage:                      optional.NewInterface([]string{"zh-cn"}),
    PublishedAtStart:                 optional.NewString("NOW-1MONTH"),
    PublishedAtEnd:                   optional.NewString("NOW-1DAY"),
    CategoriesTaxonomy:               optional.NewString("iptc-subjectcode"),
    CategoriesConfident:              optional.NewBool(true),
    CategoriesId:                     optional.NewInterface([]string{"04000000"}),
    NotCategoriesId:                  optional.NewInterface([]string{"17000000"}),
    CategoriesLevel:                  optional.NewInterface([]int32{1}),
    NotCategoriesLevel:               optional.NewInterface([]int32{2, 3}),
    EntitiesId:                       optional.NewInterface([]string{"EntitiesId_example"}),
    NotEntitiesId:                    optional.NewInterface([]string{"EntitiesId_example"}),
    EntitiesSurfaceFormsText:         optional.NewInterface([]string{"EntitiesSurfaceFormsText_example"}),
    NotEntitiesSurfaceFormsText:      optional.NewInterface([]string{"EntitiesSurfaceFormsText_example"}),
    EntitiesTypes:                     optional.NewInterface([]string{"EntitiesTypes_example"}),
    NotEntitiesTypes:                  optional.NewInterface([]string{"EntitiesTypes_example"}),
    EntitiesLinksWikipedia:           optional.NewInterface([]string{"EntitiesLinksWikipedia_example"}),
    NotEntitiesLinksWikipedia:        optional.NewInterface([]string{"EntitiesLinksWikipedia_example"}),
    EntitiesLinksWikidata:            optional.NewInterface([]string{"EntitiesLinksWikidata_example"}),
    NotEntitiesLinksWikidata:         optional.NewInterface([]string{"EntitiesLinksWikidata_example"}),
    EntitiesStockTicker:              optional.NewInterface([]string{"EntitiesStockTicker_example"}),
    NotEntitiesStockTicker:           optional.NewInterface([]string{"EntitiesStockTicker_example"}),  
    EntitiesTitleSurfaceFormsText:    optional.NewInterface([]string{"EntitiesTitleSurfaceFormsText_example"}),
    NotEntitiesTitleSurfaceFormsText: optional.NewInterface([]string{"EntitiesTitleSurfaceFormsText_example"}),
    EntitiesBodySurfaceFormsText:     optional.NewInterface([]string{"EntitiesBodySurfaceFormsText_example"}),
    NotEntitiesBodySurfaceFormsText:  optional.NewInterface([]string{"EntitiesBodySurfaceFormsText_example"}),
    SentimentTitlePolarity:           optional.NewString("positive"),
    NotSentimentTitlePolarity:        optional.NewString("negative"),
    SentimentBodyPolarity:            optional.NewString("positive"),
    NotSentimentBodyPolarity:         optional.NewString("neutral"),
    MediaImagesCountMin:              optional.NewInt32(1),
    MediaImagesCountMax:              optional.NewInt32(4),
    MediaImagesWidthMin:              optional.NewInt32(640),
    MediaImagesWidthMax:              optional.NewInt32(1200),
    MediaImagesHeightMin:             optional.NewInt32(700),
    MediaImagesHeightMax:             optional.NewInt32(1500),
    MediaImagesContentLengthMin:      optional.NewInt32(25000),
    MediaImagesContentLengthMax:      optional.NewInt32(40000),
    MediaImagesFormat:                optional.NewInterface([]string{"JPEG"}),
    NotMediaImagesFormat:             optional.NewInterface([]string{"PNG"}),
    MediaVideosCountMin:              optional.NewInt32(1),
    MediaVideosCountMax:              optional.NewInt32(2),
    AuthorId:                         optional.NewInterface([]int32{123}),
    NotAuthorId:                      optional.NewInterface([]int32{321}),
    AuthorName:                       optional.NewString("Charlie Kelly"),
    NotAuthorName:                    optional.NewString("Frank Reynolds"),
    SourceId:                         optional.NewInterface([]int32{123}),
    NotSourceId:                      optional.NewInterface([]int32{321}),
    SourceName:                       optional.NewInterface([]string{"The Irish Times"}),
    NotSourceName:                    optional.NewInterface([]string{"The Irish Independent"}),
    SourceDomain:                     optional.NewInterface([]string{"bbc.com"}),
    NotSourceDomain:                  optional.NewInterface([]string{"cnn.com"}),
    SourceLocationsCountry:           optional.NewInterface([]string{"US"}),
    NotSourceLocationsCountry:        optional.NewInterface([]string{"GB"}),
    SourceLocationsState:             optional.NewInterface([]string{"Florida"}),
    NotSourceLocationsState:          optional.NewInterface([]string{"California"}),
    SourceLocationsCity:              optional.NewInterface([]string{"Miami"}),
    NotSourceLocationsCity:           optional.NewInterface([]string{"Austin"}),
    SourceScopesCountry:              optional.NewInterface([]string{"IE"}),
    NotSourceScopesCountry:           optional.NewInterface([]string{"DE"}),
    SourceScopesState:                optional.NewInterface([]string{"Illinois"}),
    NotSourceScopesState:             optional.NewInterface([]string{"Montana"}),
    SourceScopesCity:                 optional.NewInterface([]string{"Sheboygan"}),
    NotSourceScopesCity:              optional.NewInterface([]string{"Westport"}),
    SourceScopesLevel:                optional.NewInterface([]string{"national"}),
    NotSourceScopesLevel:             optional.NewInterface([]string{"international"}),
    SourceLinksInCountMin:            optional.NewInt32(1),
    SourceLinksInCountMax:            optional.NewInt32(3000),
    SourceRankingsAlexaRankMin:       optional.NewInt32(1),
    SourceRankingsAlexaRankMax:       optional.NewInt32(1000),
    SourceRankingsAlexaCountry:       optional.NewInterface([]string{"US"}),
    Aql:                              optional.NewString("aql_example"),
  }

  trendsResponse, res, err := api.ListTrends(context.Background(), field, trendsParams)

  if err != nil {
    panic(err)
  }

  _ = res

  for _, trend := range trendsResponse.Trends {
    fmt.Println(trend)
  }
}

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.

To see a walkthrough of what the Trends endpoint returns and what it is for, take a look at this introductory blog post



HTTP Request URL

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

HTTP 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
clusters[]
array [integer]
(query)

This parameter is used for finding stories associated with a specific cluster (currently accepts one cluster per search).
translations.{language}.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.{language}.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 advanced keyword operators.
body
string
(query)

This parameter is used for finding stories whose title contains a specific keyword. It supports advanced search operators.
text
string
(query)

This parameter is used for finding stories whose title or body contains a specific keyword. To ensure the most accurate results, you should always incude a this parameter listing the languages you want to see data for. It supports boolean operators.
language[]
array [string]
(query)

This parameter is used for finding stories whose language is the specified value. To ensure the most accurate results, you should always incude a this parameter listing the languages you want to see data for. 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.
industries
(query)

This parameter is not available in flat search. However, you can filter for articles containing specific industries using AQL. You can read more about the industries filter here here, and find industry ids and labels here.
entities.id[]
array [string]
(query)

This parameter is used to find stories based on the specified entities id in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
!entities.id[]
array [string]
(query)

This parameter is used to exclude stories based on the specified entities id in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
entities.surface_forms.text[]
array [string]
(query)

This parameter is used to find stories based on the specified entities surface form text in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
!entities.surface_forms.text[]
array [string]
(query)

This parameter is used to exclude stories based on the specified entities surface form text in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
entities.types[]
array [string]
(query)

This parameter is used to find stories based on the specified entities type in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
!entities.types[]
array [string]
(query)

This parameter is used to exclude stories based on the specified entities type in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
entities.links.wikipedia[]
array [string]
(query)

This parameter is used to find stories based on the specified entities wikipedia URL in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
!entities.links.wikipedia[]
array [string]
(query)

This parameter is used to exclude stories based on the specified entities wikipedia URL in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
entities.links.wikidata[]
array [string]
(query)

This parameter is used to find stories based on the specified entities wikidata URL in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
!entities.links.wikidata[]
array [string]
(query)

This parameter is used to exclude stories based on the specified entities wikidata URL in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
entities.stock_ticker[]
array [string]
(query)

This parameter is used to find stories based on the specified entities stock tickers in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
!entities.stock_ticker[]
array [string]
(query)

This parameter is used to exclude stories based on the specified entities stock tickers in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
entities.title.surface_forms.text[]
array [string]
(query)

This parameter is used to find stories based on the specified entities surface form text in story titles. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
!entities.title.surface_forms.text[]
array [string]
(query)

This parameter is used to exclude stories based on the specified entities surface form text in story titles. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
entities.body.surface_forms.text[]
array [string]
(query)

This parameter is used to find stories based on the specified entities surface form text in story bodies. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
!entities.body.surface_forms.text[]
array [string]
(query)

This parameter is used to exclude stories based on the specified entities surface form text in story bodies. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
sentiment.title.polarity
string [string]
(query)

This parameter is used for finding stories whose title sentiment is the specified value.
!sentiment.title.polarity
string [string]
(query)

This parameter is used for excluding stories whose title sentiment is the specified value.
sentiment.body.polarity
string [string]
(query)

This parameter is used for finding stories whose body sentiment is the specified value.
!sentiment.body.polarity
string [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.
field *
string
(query)

This parameter is used to specify the trend field.
aql
string
(query)

This parameter is used to supply a sub-query in AYLIEN's custom DSL to leverage advanced keyword operators and enhanced entity search.

Response Codes

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 = 'media_images_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_id': ['entities_id_example'],
  'not_entities_id': ['entities_id_example'],
  'entities_surface_forms_text': ['entities_surface_form_text_example'],
  'not_entities_surface_forms_text': ['entities_surface_form_text_example'],
  'entities_types': ['entities_types_example'],
  'not_entities_types': ['entities_types_example']
  'entities_links_wikipedia': ['entities_links_wikipedia_example'],
  'not_entities_links_wikipedia': ['entities_links_wikipedia_example'],
  'entities_links_wikidata': ['entities_links_wikidata_example'],
  'not_entities_links_wikidata': ['entities_links_wikidata_example'],
  'entities_stock_ticker': ['entities_stock_ticker_example'],
  'not_entities_stock_ticker': ['entities_stock_ticker_example'],
  'entities_title_surface_forms_text': ['entities_title_surface_form_text_example'],
  'not_entities_title_surface_forms_text': ['entities_title_surface_form_text_example'],
  'entities_body_surface_forms_text': ['entities_body_surface_form_text_example'],
  'not_entities_body_surface_forms_text': ['entities_body_surface_form_text_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'],
  'interval_start': 56,
  'interval_end': 56,
  'interval_width': 56,
  'aql': 'aql_example'
  }

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)


# load the gem
require 'aylien_news_api'
require 'pp'
# setup authorization
AylienNewsApi.configure do |config|
  # Configure API key authorization: app_id
  config.api_key['X-AYLIEN-NewsAPI-Application-ID'] = 'YOUR API KEY'
  # Uncomment the following line to set a prefix for the API key, e.g. 'Bearer' (defaults to nil)
  #config.api_key_prefix['X-AYLIEN-NewsAPI-Application-ID'] = 'Bearer'

  # Configure API key authorization: app_key
  config.api_key['X-AYLIEN-NewsAPI-Application-Key'] = 'YOUR API KEY'
  # Uncomment the following line to set a prefix for the API key, e.g. 'Bearer' (defaults to nil)
  #config.api_key_prefix['X-AYLIEN-NewsAPI-Application-Key'] = 'Bearer'
end

api_instance = AylienNewsApi::DefaultApi.new

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_id => ['entities_id_example'],
  :not_entities_id => ['entities_id_example'],
  :entities_surface_forms_text => ['entities_surface_form_text_example'],
  :not_entities_surface_forms_text => ['entities_surface_form_text_example'],
  :entities_types => ['entities_types_example'],
  :not_entities_types => ['entities_types_example'],
  :entities_links_wikipedia => ['entities_links_wikipedia_example'],
  :not_entities_links_wikipedia => ['entities_links_wikipedia_example'],
  :entities_links_wikidata => ['entities_links_wikidata_example'],
  :not_entities_links_wikidata => ['entities_links_wikidata_example'],
  :entities_stock_ticker => ['entities_stock_ticker_example'],
  :not_entities_stock_ticker => ['entities_stock_ticker_example'],
  :entities_title_surface_forms_text => ['entities_title_surface_form_text_example'],
  :not_entities_title_surface_forms_text => ['entities_title_surface_form_text_example'],
  :entities_body_surface_forms_text => ['entities_body_surface_form_text_example'],
  :not_entities_body_surface_forms_text => ['entities_body_surface_form_text_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'],
  :interval_start => 56,
  :interval_end => 56,
  :interval_width => 56,
  :field => 'media_images_count',
  :aql => 'aql_example'
}

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

AylienNewsApi = require('aylien-news-api');
var defaultClient = AylienNewsApi.ApiClient.instance;

// Configure API key authorization: app_id
var app_id = defaultClient.authentications['app_id'];
app_id.apiKey = 'YOUR APP ID';
// Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
//app_id.apiKeyPrefix = 'Token';
// Configure API key authorization: app_key
var app_key = defaultClient.authentications['app_key'];
app_key.apiKey = 'YOUR APi KEY';
// Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
//app_key.apiKeyPrefix = 'Token';

var apiInstance = new AylienNewsApi.DefaultApi();

var opts = {
  'id': [null],
  'notId': [null],
  'title': "title_example",
  'body': "body_example",
  'text': "text_example",
  'translationsEnTitle': "translationsEnTitle_example",
  'translationsEnBody': "translationsEnBody_example",
  'translationsEnText': "translationsEnText_example",
  'language': ["null"],
  'notLanguage': ["null"],
  'publishedAtStart': "publishedAtStart_example",
  'publishedAtEnd': "publishedAtEnd_example",
  'categoriesTaxonomy': "categoriesTaxonomy_example",
  'categoriesConfident': true,
  'categoriesId': ["null"],
  'notCategoriesId': ["null"],
  'categoriesLevel': [null],
  'notCategoriesLevel': [null],
  'entitiesId': ["entitiesId_example"],
  'notEntitiesId': ["entitiesId_example"],
  'entitiesSurfaceFormsText': ["entitiesSurfaceFormsText_example"],
  'notEntitiesSurfaceFormsText': ["entitiesSurfaceFormsText_example"],
  'entitiesTypes': ["entitiesTypes_example"],
  'notEntitiesTypes': ["entitiesTypes_example"],
  'entitiesLinksWikipedia': ["entitiesLinksWikipedia_example"],
  'notEntitiesLinksWikipedia': ["entitiesLinksWikipedia_example"],
  'entitiesLinksWikidata': ["entitiesLinksWikidata_example"],
  'notEntitiesLinksWikidata': ["entitiesLinksWikidata_example"], 
  'entitiesStockTicker': ["entitiesStockTicker_example"],
  'notEntitiesStockTicker': ["entitiesStockTicker_example"], 
  'entitiesTitleSurfaceFormsText': ["entitiesTitleSurfaceFormsText_example"],
  'notEntitiesTitleSurfaceFormsText': ["entitiesTitleSurfaceFormsText_example"],
  'entitiesBodySurfaceFormsText': ["entitiesBodySurfaceFormsText_example"],
  'notEntitiesBodySurfaceFormsText': ["entitiesBodySurfaceFormsText_example"],
  'sentimentTitlePolarity': "sentimentTitlePolarity_example",
  'notSentimentTitlePolarity': "sentimentTitlePolarity_example",
  'sentimentBodyPolarity': "sentimentBodyPolarity_example",
  'notSentimentBodyPolarity': "sentimentBodyPolarity_example",
  'mediaImagesCountMin': 56,
  'mediaImagesCountMax': 56,
  'mediaImagesWidthMin': 56,
  'mediaImagesWidthMax': 56,
  'mediaImagesHeightMin': 56,
  'mediaImagesHeightMax': 56,
  'mediaImagesContentLengthMin': 56,
  'mediaImagesContentLengthMax': 56,
  'mediaImagesFormat': ["null"],
  'notMediaImagesFormat': ["null"],
  'mediaVideosCountMin': 56,
  'mediaVideosCountMax': 56,
  'authorId': [null],
  'notAuthorId': [null],
  'authorName': "authorName_example",
  'notAuthorName': "authorName_example",
  'sourceId': [null],
  'notSourceId': [null],
  'sourceName': ["null"],
  'notSourceName': ["null"],
  'sourceDomain': ["null"],
  'notSourceDomain': ["null"],
  'sourceLocationsCountry': ["null"],
  'notSourceLocationsCountry': ["null"],
  'sourceLocationsState': ["null"],
  'notSourceLocationsState': ["null"],
  'sourceLocationsCity': ["null"],
  'notSourceLocationsCity': ["null"],
  'sourceScopesCountry': ["null"],
  'notSourceScopesCountry': ["null"],
  'sourceScopesState': ["null"],
  'notSourceScopesState': ["null"],
  'sourceScopesCity': ["null"],
  'notSourceScopesCity': ["null"],
  'sourceScopesLevel': ["null"],
  'notSourceScopesLevel': ["null"],
  'sourceLinksInCountMin': 56,
  'sourceLinksInCountMax': 56,
  'sourceRankingsAlexaRankMin': 56,
  'sourceRankingsAlexaRankMax': 56,
  'sourceRankingsAlexaCountry': ["null"],
  'intervalStart': 56,
  'intervalEnd': 56,
  'intervalWidth': 56,
  'field': "words_count",
  'aql': "aql_example"
};

apiInstance.listHistograms(opts, (error, data, response) => {
  if (error) {
    console.error(error);
  } else {
    console.log(data.intervals);
  }
});

package main

// Import the library
import (
  "context"
  "fmt"
  newsapi "github.com/AYLIEN/aylien_newsapi_go"
  "github.com/antihax/optional"
)

func main() {

  cfg := newsapi.NewConfiguration()
  cfg.DefaultHeader["X-AYLIEN-NewsAPI-Application-ID"] = "YOUR_APP_ID"
  cfg.DefaultHeader["X-AYLIEN-NewsAPI-Application-Key"] = "YOUR_API_KEY"

  client := newsapi.NewAPIClient(cfg)
  api := client.DefaultApi

  histogramsParams := &newsapi.ListHistogramsOpts{
    Id:                               optional.NewInterface([]int64{123}),
    NotId:                            optional.NewInterface([]int64{123}),
    Title:                            optional.NewString("startup"),
    Body:                             optional.NewString("investment"),
    Text:                             optional.NewString("AI"),
    TranslationsEnTitle:              optional.NewString("Trump"),
    TranslationsEnBody:               optional.NewString("bank"),
    TranslationsEnText:               optional.NewString("sanctions"),
    Language:                         optional.NewInterface([]string{"en"}),
    NotLanguage:                      optional.NewInterface([]string{"zh-cn"}),
    PublishedAtStart:                 optional.NewString("NOW-1MONTH"),
    PublishedAtEnd:                   optional.NewString("NOW-1DAY"),
    CategoriesTaxonomy:               optional.NewString("iptc-subjectcode"),
    CategoriesConfident:              optional.NewBool(true),
    CategoriesId:                     optional.NewInterface([]string{"04000000"}),
    NotCategoriesId:                  optional.NewInterface([]string{"17000000"}),
    CategoriesLevel:                  optional.NewInterface([]int32{1}),
    NotCategoriesLevel:               optional.NewInterface([]int32{2, 3}),
    EntitiesId:                       optional.NewInterface([]string{"EntitiesId_example"}),
    NotEntitiesId:                    optional.NewInterface([]string{"EntitiesId_example"}),
    EntitiesSurfaceFormsText:         optional.NewInterface([]string{"EntitiesSurfaceFormsText_example"}),
    NotEntitiesSurfaceFormsText:      optional.NewInterface([]string{"EntitiesSurfaceFormsText_example"}),
    EntitiesTypes:                     optional.NewInterface([]string{"EntitiesTypes_example"}),
    NotEntitiesTypes:                  optional.NewInterface([]string{"EntitiesTypes_example"}),
    EntitiesLinksWikipedia:           optional.NewInterface([]string{"EntitiesLinksWikipedia_example"}),
    NotEntitiesLinksWikipedia:        optional.NewInterface([]string{"EntitiesLinksWikipedia_example"}),
    EntitiesLinksWikidata:            optional.NewInterface([]string{"EntitiesLinksWikidata_example"}),
    NotEntitiesLinksWikidata:         optional.NewInterface([]string{"EntitiesLinksWikidata_example"}),
    EntitiesStockTicker:              optional.NewInterface([]string{"EntitiesStockTicker_example"}),
    NotEntitiesStockTicker:           optional.NewInterface([]string{"EntitiesStockTicker_example"}),  
    EntitiesTitleSurfaceFormsText:    optional.NewInterface([]string{"EntitiesTitleSurfaceFormsText_example"}),
    NotEntitiesTitleSurfaceFormsText: optional.NewInterface([]string{"EntitiesTitleSurfaceFormsText_example"}),
    EntitiesBodySurfaceFormsText:     optional.NewInterface([]string{"EntitiesBodySurfaceFormsText_example"}),
    NotEntitiesBodySurfaceFormsText:  optional.NewInterface([]string{"EntitiesBodySurfaceFormsText_example"}),
    SentimentTitlePolarity:           optional.NewString("positive"),
    NotSentimentTitlePolarity:        optional.NewString("negative"),
    SentimentBodyPolarity:            optional.NewString("positive"),
    NotSentimentBodyPolarity:         optional.NewString("neutral"),
    MediaImagesCountMin:              optional.NewInt32(1),
    MediaImagesCountMax:              optional.NewInt32(4),
    MediaImagesWidthMin:              optional.NewInt32(640),
    MediaImagesWidthMax:              optional.NewInt32(1200),
    MediaImagesHeightMin:             optional.NewInt32(700),
    MediaImagesHeightMax:             optional.NewInt32(1500),
    MediaImagesContentLengthMin:      optional.NewInt32(25000),
    MediaImagesContentLengthMax:      optional.NewInt32(40000),
    MediaImagesFormat:                optional.NewInterface([]string{"JPEG"}),
    NotMediaImagesFormat:             optional.NewInterface([]string{"PNG"}),
    MediaVideosCountMin:              optional.NewInt32(1),
    MediaVideosCountMax:              optional.NewInt32(2),
    AuthorId:                         optional.NewInterface([]int32{123}),
    NotAuthorId:                      optional.NewInterface([]int32{321}),
    AuthorName:                       optional.NewString("Charlie Kelly"),
    NotAuthorName:                    optional.NewString("Frank Reynolds"),
    SourceId:                         optional.NewInterface([]int32{123}),
    NotSourceId:                      optional.NewInterface([]int32{321}),
    SourceName:                       optional.NewInterface([]string{"The Irish Times"}),
    NotSourceName:                    optional.NewInterface([]string{"The Irish Independent"}),
    SourceDomain:                     optional.NewInterface([]string{"bbc.com"}),
    NotSourceDomain:                  optional.NewInterface([]string{"cnn.com"}),
    SourceLocationsCountry:           optional.NewInterface([]string{"US"}),
    NotSourceLocationsCountry:        optional.NewInterface([]string{"GB"}),
    SourceLocationsState:             optional.NewInterface([]string{"Florida"}),
    NotSourceLocationsState:          optional.NewInterface([]string{"California"}),
    SourceLocationsCity:              optional.NewInterface([]string{"Miami"}),
    NotSourceLocationsCity:           optional.NewInterface([]string{"Austin"}),
    SourceScopesCountry:              optional.NewInterface([]string{"IE"}),
    NotSourceScopesCountry:           optional.NewInterface([]string{"DE"}),
    SourceScopesState:                optional.NewInterface([]string{"Illinois"}),
    NotSourceScopesState:             optional.NewInterface([]string{"Montana"}),
    SourceScopesCity:                 optional.NewInterface([]string{"Sheboygan"}),
    NotSourceScopesCity:              optional.NewInterface([]string{"Westport"}),
    SourceScopesLevel:                optional.NewInterface([]string{"national"}),
    NotSourceScopesLevel:             optional.NewInterface([]string{"international"}),
    SourceLinksInCountMin:            optional.NewInt32(1),
    SourceLinksInCountMax:            optional.NewInt32(3000),
    SourceRankingsAlexaRankMin:       optional.NewInt32(1),
    SourceRankingsAlexaRankMax:       optional.NewInt32(1000),
    SourceRankingsAlexaCountry:       optional.NewInterface([]string{"US"}),
    IntervalStart:                    optional.NewInt32(0),
    IntervalEnd:                      optional.NewInt32(2000),
    IntervalWidth:                    optional.NewInt32(50),
    Field:                            optional.NewString("words_count"),
    Aql:                              optional.NewString("aql_example"),
  }

  histogramsResponse, res, err := api.ListHistograms(context.Background(), histogramsParams)

  if err != nil {
    panic(err)
  }

  _ = res

  for _, interval := range histogramsResponse.Intervals {
    fmt.Println(interval)
  }
}

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 URL

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

HTTP 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
clusters[]
array [integer]
(query)

This parameter is used for finding stories associated with a specific cluster (currently accepts one cluster per search).
translations.{language}.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.{language}.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 advanced keyword operators.
body
string
(query)

This parameter is used for finding stories whose title contains a specific keyword. It supports advanced search 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. you want to see data forIt 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, which is used for defining the type of the taxonomy for the rest of the categories queries, is available for our standard IPTC and IAB category taxonomies. Please click here to learn more about our Smart Tagger taxonomies, and about using the right taxonomy for you.
categories.confident
boolean
(query)

This parameter, which is used for finding stories whose categories are confident, is available for our standard IPTC and IAB category taxonomies. Please click here to learn more about our Smart Tagger taxonomies, and about using the right taxonomy for you.

Default value: true
categories.id[]
array [string]
(query)

This parameter, which is used for finding stories by categories id, is available for our standard IPTC and IAB category taxonomies. Please click here to learn more about our Smart Tagger taxonomies, and about using the right taxonomy for you.
!categories.id[]
array [string]
(query)

This parameter, which is used for excluding stories by categories id, is available for our standard IPTC and IAB category taxonomies. Please click here to learn more about our Smart Tagger taxonomies, and about using the right taxonomy for you.
categories.level[]
array [integer]
(query)

This parameter, which is used for finding stories by categories level, is available for our standard IPTC and IAB category taxonomies. Please click here to learn more about our Smart Tagger taxonomies, and about using the right taxonomy for you.
!categories.level[]
array [integer]
(query)

This parameter, which is used for excluding stories by categories level, is available for our standard IPTC and IAB category taxonomies. Please click here to learn more about our Smart Tagger taxonomies, and about using the right taxonomy for you.
industries
(query)

This parameter is not available in flat search. However, you can filter for articles containing specific industries using AQL. You can read more about the industries filter here here, and find industry ids and labels here.
entities.id[]
array [string]
(query)

This parameter is used to find stories based on the specified entities id in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
!entities.id[]
array [string]
(query)

This parameter is used to exclude stories based on the specified entities id in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
entities.surface_forms.text[]
array [string]
(query)

This parameter is used to find stories based on the specified entities surface form text in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
!entities.surface_forms.text[]
array [string]
(query)

This parameter is used to exclude stories based on the specified entities surface form text in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
entities.types[]
array [string]
(query)

This parameter is used to find stories based on the specified entities type in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
!entities.types[]
array [string]
(query)

This parameter is used to exclude stories based on the specified entities type in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
entities.links.wikipedia[]
array [string]
(query)

This parameter is used to find stories based on the specified entities wikipedia URL in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
!entities.links.wikipedia[]
array [string]
(query)

This parameter is used to exclude stories based on the specified entities wikipedia URL in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
entities.links.wikidata[]
array [string]
(query)

This parameter is used to find stories based on the specified entities wikidata URL in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
!entities.links.wikidata[]
array [string]
(query)

This parameter is used to exclude stories based on the specified entities wikidata URL in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
entities.stock_ticker[]
array [string]
(query)

This parameter is used to find stories based on the specified entities stock tickers in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
!entities.stock_ticker[]
array [string]
(query)

This parameter is used to exclude stories based on the specified entities stock tickers in stories. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
entities.title.surface_forms.text[]
array [string]
(query)

This parameter is used to find stories based on the specified entities surface form text in story titles. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
!entities.title.surface_forms.text[]
array [string]
(query)

This parameter is used to exclude stories based on the specified entities surface form text in story titles. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
entities.body.surface_forms.text[]
array [string]
(query)

This parameter is used to find stories based on the specified entities surface form text in story bodies. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
!entities.body.surface_forms.text[]
array [string]
(query)

This parameter is used to exclude stories based on the specified entities surface form text in story bodies. When querying for entities, we recommend that users make searches using nested queries. You can learn more about these queries on the Common Workflows page.
sentiment.title.polarity
string [string]
(query)

This parameter is used for finding stories whose title sentiment is the specified value.
!sentiment.title.polarity
string [string]
(query)

This parameter is used for excluding stories whose title sentiment is the specified value.
sentiment.body.polarity
string [string]
(query)

This parameter is used for finding stories whose body sentiment is the specified value.
!sentiment.body.polarity
string [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.
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.
aql
string
(query)

This parameter is used to supply a sub-query in AYLIEN's custom DSL to leverage advanced keyword operators and enhanced entity search.

Response Codes

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