The News API can be used in a variety of ways. We’ve put together some sample workflows and handy code snippets to help you get the most out of the solution:

Real-time Monitoring of News Content
Building a search with Boolean queries
Guides on working with numerous filters (dates, locations, categories, entities and media results)
News Clustering
Source popularity

Working with clusters

The News API provides access to millions of stories from thousands of news sources across the world. The clustering feature groups these stories into clusters that broadly correspond to real-world events. Clustering requires an Advanced or Enterprise license key. Start a free trial or contact sales to upgrade your account.

The Cluster Object

A cluster is a collection of stories that are grouped together based on similarity. A cluster object is a new type of JSON object that provides a cluster’s id along with metadata about the stories in a cluster. The terms cluster and cluster object are used interchangeably.

A cluster has the following properties:
Each cluster has an unique ID in the News API index
A cluster can have one or more stories associated with it.
A story will always belong to just one cluster.
The relationship between the story and cluster does not change - it will not be reassigned to another cluster at a later time.

Currently, clustering is carried out on new stories in real-time. Most stories will be associated with clusters a short time after they have been analyzed.

JSON Response

{
  "cluster_count": 2042945,
  "clusters": [
    {
      "id": 4992716,
      "time": "2019-07-20T07:16:03Z",
      "story_count": 26488,
      "earliest_story": "2019-07-20T07:16:03Z",
      "latest_story": "2019-08-03T07:41:09Z",
      "representative_story": {
        "id": 21466483,
        "title": "Analysts Offer Predictions for A. O. Smith Corp’s Q3 2019 Earnings (NYSE:AOS)",
        "permalink": "https://www.tickerreport.com/banking-finance/4497288/analysts-offer-predictions-for-a-o-smith-corps-q3-2019-earnings-nyseaos.html",
        "published_at": "2019-08-03T07:15:26Z"
      },
      "location": {
        "country": "US"
      }
    },
    {
      ...
    }
  ],
  "next_page_cursor": "<string to use in pagination of results>"
}

Retrieving clusters using the Clusters endpoint

The Clusters endpoint allows you to retrieve clusters from a specific time window.

This endpoint is useful for monitoring the news for important, “breaking” news events that are receiving a specified level of coverage. Since each cluster provides metadata on the number of stories in it, new clusters with a lot of stories usually refer to an new, important event (you can additionally filter the events by country to localize your search).

Once you have retrieved the cluster objects, you can query the Stories endpoint with the cluster id to gather the stories associated with the cluster.

Code snippet

This code snippet shows how you can gather clusters that were created in the last 6 hours and have more than 10 stories associated with them.

import aylien_news_api
from aylien_news_api.rest import ApiException
from pprint import pprint

configuration = aylien_news_api.Configuration()
configuration.api_key['X-AYLIEN-NewsAPI-Application-ID'] = 'YOUR_APP_ID'
configuration.api_key['X-AYLIEN-NewsAPI-Application-Key'] = 'YOUR_APP_KEY'

client = aylien_news_api.ApiClient(configuration)
api_instance = aylien_news_api.DefaultApi(client)

try:
    api_response = api_instance.list_clusters(
        time_end='NOW-6HOURS',
        story_count_min=10
    )
    pprint(api_response)
except ApiException as e:
    print("Exception when calling DefaultApi->list_clusters: %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'

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

api_instance = AylienNewsApi::DefaultApi.new

opts = {
    :time_end => 'NOW-6HOURS',
    :story_count_min => 10
}

begin
    #List stories
    result = api_instance.list_clusters(opts)

    puts "====================================="
    pp result
  rescue AylienNewsApi::ApiError => e
    puts "Exception when calling DefaultApi->list_stories: #{e}"
    puts e.response_body
  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_APP_KEY';

var apiInstance = new AylienNewsApi.DefaultApi();
var opts = {
  'storyCountMin': 10,
  'timeStart': 'NOW-6HOURS'
};
apiInstance.listClusters(opts, (error, data, response) => {
  if (error) {
    console.error(error);
  } else {
    console.log(data.clusters);
  }
});

<?php
require_once(__DIR__ . '/vendor/autoload.php');

// Configure API key authorization: app_id
$config = Aylien\NewsApi\Configuration::getDefaultConfiguration()->setApiKey('X-AYLIEN-NewsAPI-Application-ID', 'YOUR_APP_ID');

// Configure API key authorization: app_key
$config = Aylien\NewsApi\Configuration::getDefaultConfiguration()->setApiKey('X-AYLIEN-NewsAPI-Application-Key', 'YOUR_APP_KEY');


$apiInstance = new Aylien\NewsApi\Api\DefaultApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
    // This is optional, `GuzzleHttp\Client` will be used as default.
    new GuzzleHttp\Client(),
    $config
);
$associate_array['story_count_min'] = 10;
$associate_array['time_start'] = 'NOW-6HOURS';

try {
    $result = $apiInstance->listClusters($associate_array);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling DefaultApi->listClusters: ', $e->getMessage(), PHP_EOL;
}
?>

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{
    StoryCountMin:                  optional.NewInt32(3),     
    TimeStart:                      optional.NewString("NOW-6HOURS"),
    LocationCountry:                optional.NewInterface([]string{"GB"}),
  }

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

  if err != nil {
    panic(err)
  }

  _ = res

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

To retrieve stories associated with the cluster, you can either use the representative story, or else make an additional call to the stories endpoint with the cluster id.

Retrieving clusters using the Trends endpoint

The Trends endpoint allows you to filter clusters based on the stories contained within the clusters. For example, you can filter clusters that contain stories with a specific category label, mention a specific entity, or even have a specific sentiment score.

You can use this endpoint for real time monitoring of events about a specific topic or entity.

The Trends endpoint returns the id of clusters sorted by the count of stories associated with them. Once you have each cluster’s id, you can go on to - get the cluster metadata from the Clusters endpoint - get the stories for each of the clusters from the Stories endpoint.

The trends endpoint only returns the top 100 clusters for a given query. As such, if your intention is to support real time monitoring, you should ensure that your query is very specific and covers a small enough interval to retrieve all of the relevant clusters.

Code snippet

The sample code below shows how you can gather clusters that, over the last 12 hours, were associated with stories classified with the politcs category (IPTC code : 11000000), and mentioning the US Congress. The Stories endpoint then returns 3 associated stories from sources with the highest Alexa rankings in the US.

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


def get_cluster_from_trends():

    """
    Returns a list of up to 100 clusters that meet the parameters set out.
    """
    response = api_instance.list_trends(
        field='clusters',
        categories_taxonomy='iptc-subjectcode',
        categories_id=['11000000'],
        published_at_end='NOW-12HOURS',
        entities_title_links_dbpedia=[
            'http://dbpedia.org/resource/United_States_Congress']
    )

    return [item.value for item in response.trends]


def get_cluster_metadata(cluster_id):

    """
    Returns the representative story, number of stories, and time value for a given cluster
    """

    response = api_instance.list_clusters(
        id=[cluster_id]
    )

    clusters = response.clusters

    if clusters is None or len(clusters) == 0:
        return None

    first_cluster = clusters[0]

    return {
        "cluster": first_cluster.id,
        "representative_story": first_cluster.representative_story,
        "story_count": first_cluster.story_count,
        "time": first_cluster.time
    }


def get_top_stories(cluster_id):
    """
    Returns 3 stories associated with the cluster from the highest-ranking publishers
    """
    response = api_instance.list_stories(
        clusters=[cluster_id],
        sort_by="source.rankings.alexa.rank.US",
        per_page=3
    )

    return response.stories


clusters = {}
cluster_ids = get_cluster_from_trends()

for cluster_id in cluster_ids:
    metadata = get_cluster_metadata(cluster_id)
    if metadata is not None:
        stories = get_top_stories(cluster_id)
        metadata["stories"] = stories
        pprint(metadata)
    else:
        print("{} empty".format(cluster_id))

package main

import (
  "context"
  "fmt"
  newsapi "github.com/AYLIEN/aylien_newsapi_go"
  "github.com/antihax/optional"
  "strconv"
)

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

  getTrends := func (searchTerm string) newsapi.Trends{

    field := "clusters"
    trendsParams := &newsapi.ListTrendsOpts{
      Title:      optional.NewString(searchTerm),
    }

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

    if err != nil {
      panic(err)
    }
    _ = res

    return trendsResponse
  }

  getClusterMetadata := func(clusterId int64) newsapi.Cluster{

    clustersParams := &newsapi.ListClustersOpts{
      Id:       optional.NewInterface([]int64{clusterId}),
    }

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

    if err != nil {
      panic(err)
    }
    _ = res

    return clustersResponse.Clusters[0]
  } 

  getTopStories := func(clusterId int64) newsapi.Stories{
    storiesParams := &newsapi.ListStoriesOpts{
      Clusters:   optional.NewInterface([]int64{clusterId}),
      PerPage:    optional.NewInt32(3),
      SortBy:     optional.NewString("source.rankings.alexa.rank.US"),
    }

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

    if err != nil {
      panic(err)
    }
    _ = res

    return storiesResponse
  }

  trends := getTrends("Trump")

  for _, trend := range trends.Trends{

    fmt.Println("\n----------")

    clusterId, err := strconv.ParseInt(trend.Value, 10, 64)
    if err != nil {
      panic(err)
    }

    metadata := getClusterMetadata(clusterId)

    fmt.Println("Cluster ID: ", clusterId, "\nStory count: ", metadata.StoryCount, "\nDetected Location: ", metadata.Location, "\nRepresentative Story:", metadata.RepresentativeStory.Title, "\n\nStories:")

    topStories := getTopStories(clusterId)
    for _, story := range topStories.Stories{
      fmt.Println(" - ", story.Source.Name,  " / ", story.Title)
    }
  }
}

var util = require('util')
var AylienNewsApi = require('aylien-news-api');

var apiInstance = new AylienNewsApi.DefaultApi();

var app_id = apiInstance.apiClient.authentications['app_id'];
app_id.apiKey = "app_id";

var app_key = apiInstance.apiClient.authentications['app_key'];
app_key.apiKey = "app_key";

function getTrends(search_term) {

    var field = "clusters";
    var trends_opts = {
        'title': search_term,
        'categories_taxonomy': 'iptc-subjectcode',
        'categories_id': ['11000000'],
        'published_at_end': 'NOW-12HOURS',
        'per_page': 2
    };

    apiInstance.listTrends(field, trends_opts, (error, data, response) => {
        if (error) {
            console.log(error);
        } else {
            for (var i = 0; i < data.trends.length; i++) {
                var cluster_opts = {
                    'id': [data.trends[i].value]
                }
                apiInstance.listClusters(cluster_opts, (error, cluster_data, response) => {
                    if (error) {
                        console.error(error);
                    } else {
                        console.log(util.inspect(cluster_data, {showHidden: false, depth: null}));

                    }
                })
            }
        }
    });
}

var clusters = getTrends("Trump");
console.log(clusters);

require 'aylien_news_api'
require 'pp'

def get_trends(search_term)

    clusters = []
    field = 'clusters'
    opts = {
        title: search_term
    }

    begin

        result = $api_instance.list_trends(field, opts)

        # pp result
        trends = result.trends
        # pp result
        trends.each do |trend|
            clusters.push(trend.value)
        end

        rescue AylienNewsApi::ApiError => e
            puts "Exception when calling DefaultApi->list_trends: #{e}"
    end

    clusters
end

def get_cluster(cluster_ID)

    cluster_opts = {
        id: cluster_ID
    }
    begin 
        result = $api_instance.list_clusters(cluster_opts)    
        cluster_data = result.clusters
    rescue AylienNewsApi::ApiError => e
        puts "Exception when calling DefaultApi->list_clusters: #{e}"
    cluster_data
    end
end

AylienNewsApi.configure do |config|
    config.api_key['X-AYLIEN-NewsAPI-Application-ID'] = 'app_id'
    config.api_key['X-AYLIEN-NewsAPI-Application-Key'] = 'api_key'
  end


$api_instance = AylienNewsApi::DefaultApi.new

trends = get_trends('Trump')

trends.each do |cluster_ID|
    pp get_cluster(cluster_ID)
end

<?php
require_once(__DIR__ . '/vendor/autoload.php');

function get_trends($search_term){
    global $api_instance;
    $cluster_ids = [];
    $opts = array(
        'title' => $search_term, 
        'field' => 'clusters'
    );

    try {
        $result = $api_instance->listTrends($opts);
        for($i = 0; $i < sizeof($result->getTrends()); $i++){
            array_push($cluster_ids, $result->getTrends()[$i]->getValue());
          };
    } catch (Exception $e) {
        echo 'Exception when calling DefaultApi->listTrends: ', $e->getMessage(), PHP_EOL;
    }

    return $cluster_ids;
}

$config = Aylien\NewsApi\Configuration::getDefaultConfiguration()->setApiKey('X-AYLIEN-NewsAPI-Application-ID', 'YOUR_APP_ID');
$config = Aylien\NewsApi\Configuration::getDefaultConfiguration()->setApiKey('X-AYLIEN-NewsAPI-Application-Key', 'YOUR_API_KEY');
$api_instance = new Aylien\NewsApi\Api\DefaultApi(new GuzzleHttp\Client(), $config);

$clusters = get_trends("Trump");

for($i = 0; $i < sizeof($clusters); $i++){
    try {
        $result = $api_instance->listClusters(array('id' => $clusters[$i]));
        print_r($result);
    } catch (Exception $e) {
        echo 'Exception when calling DefaultApi->listTrends: ', $e->getMessage(), PHP_EOL;
    }
  };

Retrieving clusters using the Stories endpoint

The Stories endpoint allows you to gather a filtered stream of stories while also retrieving the cluster ID associated with the individual stories.

You can use this to effectively “collapse” stories in a real-time news stream that you are monitoring. This could be useful, for example, to avoid showing similar stories in a rolling news stream.

Once you have the ID for the cluster, you can query the Clusters endpoint to retrieve the cluster’s metadata.

Code snippet

The following code snippet retrieves recent stories mentioning Donald Trump and collapses stories referring to the same event.

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

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

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

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


def get_stories():
    """
    Returns a list of story objects
    """
    response = api_instance.list_stories(
        title='Liverpool',
        published_at_start='NOW-7DAYS',
        per_page=100
    )

    return response.stories


stories = get_stories()
clustered_stories = {}
clusters = []

for story in stories:
    if len(story.clusters) > 0:
        cluster = story.clusters[0]
        if cluster not in clusters:
            clustered_stories[cluster] = [story.title]
        else:
            clustered_stories[cluster].append(story.title)

for cluster in clustered_stories:
    print(cluster, len(
        clustered_stories[cluster]), clustered_stories[cluster][0])

var AylienNewsApi = require('aylien-news-api');

var apiInstance = new AylienNewsApi.DefaultApi();

// Configure API key authorization: app_id
var app_id = apiInstance.apiClient.authentications['app_id'];
app_id.apiKey = "YOUR_APP_ID";

// Configure API key authorization: app_key
var app_key = apiInstance.apiClient.authentications['app_key'];
app_key.apiKey = "YOUR_API_KEY";


var opts = {
    'body': 'Liverpool',
    'publishedAtStart': 'NOW-7DAYS',  
    'perPage': 100   
};

var clusterResult = {};

apiInstance.listStories(opts, (error, data, response) => {
    if (error) {
      console.error(error);
    } else {
        for (var i = 0; i < data.stories.length; i++) {
            if (data.stories[i].clusters.length > 0 && (!(data.stories[i].clusters[0] in clusterResult))){
                clusterResult[data.stories[i].clusters[0]]=[data.stories[i].title];
            } else if (data.stories[i].clusters.length > 0 && (data.stories[i].clusters[0] in clusterResult)){
                clusterResult[data.stories[i].clusters[0]].push(data.stories[i].title); 
            } else {
                console.log(data.stories[i].title, data.stories[i].clusters[0]);
            };
        };
    };
    console.log(clusterResult);
});

package main

import (
  "context"
    "fmt"
    newsapi "github.com/AYLIEN/aylien_newsapi_go"
  "github.com/antihax/optional"
)
type ClusteredStory struct {
  title   string
  source    string
}

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{
        Title:            optional.NewString("Liverpool"),
        PublishedAtStart: optional.NewString("NOW-7DAYS"),
        PublishedAtEnd:   optional.NewString("NOW"),
        PerPage:          optional.NewInt32(100),
        SortBy:           optional.NewString("relevance"),
    }

    storiesResponse, res, err := api.ListStories(context.Background(), storiesParams)
    if err != nil {
        panic(err)
    }
    _ = res

  clusteredStories := make(map[int64][]ClusteredStory, 100)

    for _, story := range storiesResponse.Stories {
    // create a map for each new cluster, append stories to existing clusters 
    if len(story.Clusters) > 0 {
        clusteredStories[story.Clusters[0]] = append(clusteredStories[story.Clusters[0]], ClusteredStory{title:story.Title, source:story.Source.Name})
      }
    }

  for cluster := range clusteredStories {
      fmt.Println(cluster, clusteredStories[cluster])
  }
}

require 'aylien_news_api'
require 'pp'

AylienNewsApi.configure do |config|
  config.api_key['X-AYLIEN-NewsAPI-Application-ID'] = "YOUR_APP_ID"
  config.api_key['X-AYLIEN-NewsAPI-Application-Key'] = "YOUR_API_KEY"
end

api_instance = AylienNewsApi::DefaultApi.new

opts = {
    :pubishedAtStart => "NOW-7DAYS",
    :title => "Liverpool",
    :per_page => 100
}

begin
    result = api_instance.list_stories(opts)
    clusters = {}

    result.stories.each do |story|
        if clusters.has_key?(story.clusters[0]) == true
            clusters[story.clusters[0]].push(story.title)
        else
            clusters[story.clusters[0]] = [story.title]
        end
    end
    pp clusters

    rescue AylienNewsApi::ApiError => e
        puts "Exception when calling DefaultApi->list_stories: #{e}"

end

<?php
require_once(__DIR__ . '/vendor/autoload.php');

$config = Aylien\NewsApi\Configuration::getDefaultConfiguration()->setApiKey('X-AYLIEN-NewsAPI-Application-ID', 'YOUR_APP_ID');
$config = Aylien\NewsApi\Configuration::getDefaultConfiguration()->setApiKey('X-AYLIEN-NewsAPI-Application-Key', 'YOUR_API_KEY');
$api_instance = new Aylien\NewsApi\Api\DefaultApi(new GuzzleHttp\Client(), $config);

$opts = array(
    'title' => 'Liverpool',
    'published_at_start' => 'NOW-7DAYS',
    'published_at_end' => 'NOW-3HOURS',
    'per_page' => 100
);


$clusters = array();

try {
    $result = $api_instance->listStories($opts);
    // print_r($result);
    for ($i = 0; $i < sizeof($result->getStories()); $i++){
        $cluster = $result->getStories()[$i]->getClusters()[0];
        if (array_key_exists($cluster, $clusters) == true) {
            array_push($clusters[$cluster], $result->getStories()[$i]->getTitle());
        }
        else {
            $clusters[$cluster] = array($result->getStories()[$i]->getTitle());
        }
    }
} catch (Exception $e) {
    echo 'Exception when calling DefaultApi->listTrends: ', $e->getMessage(), PHP_EOL;
};
print_r($clusters);
?>

Working with multilingual content

The News API sources content from across the globe in 16 languages. Content from all of these languages is analysed and served through the API.

The supported languages are listed below along with their language codes. The languages available to you would depend on the plan you are subscribed to. Multilingual support requires an Advanced or Enterprise license key. Start a free trial or contact sales to upgrade your account.

Translations

English translation of the title and body of a story are included for all non-English language stories.

You can find the translations in the “translations” field of story objects.

{
  "title": "original title",
  "body": "original body",
  "language": "<non-English language code>", 

  "<...>": "<...>",

  "translations" : {
    "en": {
      "body": "translated body",
      "title": "translated title"
    }
  }
}

Searching multilingual content

The News API provides three ways to search multi lingual content.

You can search over the original text regardless of original language:

"title" : "<search text in native language>"

You can search over text in English regardless of original non-English language

"translations.en.title": "<search text in English>"

You can search over a specific combination of original text and translated text. This can be useful for searching over proper nouns in native language while specifying additional keywords in English.

"title": "<search text in native language>",
"translations.en.title": "<search text in English>"

Note that you can filter content you search on by language by specifying one or more languages in the language field.

Code snippets

The following code snippets demonstrate the three methods of searching listed above.

To search across a Russian stories for a query term in that language ("Путин" - the transliteration of "Putin"):

from __future__ import print_function
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_APP_ID'

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

response = api_instance.list_stories(
    title='Путин',
    language=['ru'],
    published_at_start='NOW-1MONTH/DAY',
    published_at_end='NOW/DAY',
    per_page=3
)

for item in response.stories:
    print(item.title)
    print(item.translations.en.title)

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"

    // Configure API key authorization: app_key
    cfg.DefaultHeader["X-AYLIEN-NewsAPI-Application-Key"] = "YOUR_API_KEY"

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

    storiesParams := &newsapi.ListStoriesOpts{
        Title:            optional.NewString("Путин"),
        Language:         optional.NewInterface([]string{"ru"}),
        PublishedAtStart: optional.NewString("NOW-1MONTH"),
        PublishedAtEnd:   optional.NewString("NOW"),
        PerPage:          optional.NewInt32(3),
    }

    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.Translations.En.Title, ") / ",  story.Source.Name)
    }
}

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

var apiInstance = new AylienNewsApi.DefaultApi();

// 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 opts = {
    'title': 'Путин',
    'language': ['ru'],
    'publishedAtStart': 'NOW-5DAYS',
    'publishedAtEnd': 'NOW-2HOURS',
    'per_page': 3
};


apiInstance.listStories(opts, (error, data, response) => {
    if (error) {
      console.error(error);
    } else {
        for (var i = 0; i < data.stories.length; i++){
            console.log(data.stories[i].title + " / " + data.stories[i].translations.en.title);
          }
    }
  });

require 'aylien_news_api'
require 'pp'

AylienNewsApi.configure do |config|

  config.api_key['X-AYLIEN-NewsAPI-Application-ID'] = "YOUR_APP_ID"
  config.api_key['X-AYLIEN-NewsAPI-Application-Key'] = "YOUR_API_KEY"
end

api_instance = AylienNewsApi::DefaultApi.new

opts = {
    :title => "Путин",
    :language => ["ru"],
    :published_at_start => "NOW-10DAYS",
    :published_at_end => "NOW",
    :_return => ["title"]
}

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

<?php
require_once(__DIR__ . '/vendor/autoload.php');

$config = Aylien\NewsApi\Configuration::getDefaultConfiguration()->setApiKey('X-AYLIEN-NewsAPI-Application-ID', 'YOUR_APP_ID');
$config = Aylien\NewsApi\Configuration::getDefaultConfiguration()->setApiKey('X-AYLIEN-NewsAPI-Application-Key', 'YOUR_API_KEY');

$apiInstance = new Aylien\NewsApi\Api\DefaultApi(
    new GuzzleHttp\Client(),
    $config
);

$opts = array(
  'title' => 'Путин', 
  'language' => array('ru'),
  'published_at_start' => 'NOW-7DAYS', 
  'per_page' => 10
    );  

try {
    $result = $apiInstance->listStories($opts);
    for ($i = 0; $i < sizeof($result->getStories()); $i++) {
        print_r("\n----------\n");
        print_r($result->getStories()[$i]->getTitle());
        print_r($result->getStories()[$i]->getTranslations()["en"]["title"]);
    }
} catch (Exception $e) {
    echo 'Exception when calling DefaultApi->listStories: ', $e->getMessage(), PHP_EOL;
}
?>

To search across translated Russian content mentioning "Путин" in the title that also mention "business" in the English translation of the title:

response = api_instance.list_stories(
    title='Путин',
    translations_en_title='business',
    language=['ru'],
    published_at_start='NOW-10DAYS',
    published_at_end='NOW',
    per_page=3
)

storiesParams := &newsapi.ListStoriesOpts{
    Title:                 optional.NewString("Путин"),
    TranslationsEnTitle:   optional.NewString("business"),
    Language:              optional.NewInterface([]string{"ru"}),
    PublishedAtStart:      optional.NewString("NOW-1MONTH"),
    PublishedAtEnd:        optional.NewString("NOW"),
    PerPage:               optional.NewInt32(3),
}

var opts = {
    'title': 'Путин',
    'translationsEnTitle': 'business',
    'language': ['ru'],
    'publishedAtStart': 'NOW-10DAYS',
    'publishedAtEnd': 'NOW-2HOURS',
    'per_page': 3
};

opts = {
    :title => "Путин",
    :translations_en_title => 'business',
    :language => ["ru"],
    :published_at_start => "NOW-10DAYS",
    :published_at_end => "NOW",
    :_return => ["title"]
}

$opts = array(
  'title' => 'Путин',
  'translations_en_title' => 'business', 
  'language' => array('ru'),
  'published_at_start' => 'NOW-7DAYS', 
  'per_page' => 10
    );

To search across all languages for a search term in English:

response = api_instance.list_stories(
    title='Путин',
    translations_en_title='Putin',
    published_at_start='NOW-1MONTH/DAY',
    published_at_end='NOW/DAY',
    per_page=10
)

storiesParams := &newsapi.ListStoriesOpts{
    Title:                 optional.NewString("Путин"),
    TranslationsEnTitle:   optional.NewString("Putin"),
    PublishedAtStart:      optional.NewString("NOW-1MONTH"),
    PublishedAtEnd:        optional.NewString("NOW"),
    PerPage:               optional.NewInt32(3),
    }

var opts = {
    'title': 'Путин',
    'translationsEnTitle': 'Putin',
    'publishedAtStart': 'NOW-5DAYS',
    'publishedAtEnd': 'NOW-2HOURS',
    'per_page': 3
};

opts = {
    :title => "Путин",
    :translations_en_title => 'Putin',
    :published_at_start => "NOW-10DAYS",
    :published_at_end => "NOW",
    :_return => ["title"]
}

$opts = array(
  'title' => 'Путин',
  'translations_en_title' => 'Putin', 
  'language' => array('ru'),
  'published_at_start' => 'NOW-7DAYS', 
  'per_page' => 10
    );

Analyzing Multi Lingual content

All content in all languages benefit from all of the analysis features supported by the News API. This includes Classification, Entity Extraction, Concept Extraction, and Sentiment.

You should however note that analysis for some languages is based on native content and the analysis for others is based on translated content. This means that for German, entities are extracted from the native German text. For Arabic, the entities are extracted from the translated text.

Language	Text Used
en, de, fr, it, es, pt	native
ar, da, fi, nl, no, ru, sv, tr, zh-cn, zh-tw	translated (en)

Real-time monitoring

Real-time monitoring enables you to pull stories in real-time, as they are published, based on your specific search query. This may be of particular interest to users who rely on having the latest stories as soon as they are published, such as news tickers for example.

Newly published stories will be pulled every minute, and duplicates in subsequent searches will be ignored, to ensure you are only getting the most recent publications, rather than a repeat of what has come before.

For more information on using this feature, take a look at our blog post introducing the feature.

Examples

The following example shows how to pull recent stories that contain the term Dublin in the title.

from __future__ import print_function
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'
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))

def fetch_new_stories(params={}):
  print('------------')

  fetched_stories = []
  stories = None

  while stories is None or len(stories) > 0:
    try:
      response = api_instance.list_stories(**params)
    except ApiException as e:
      if ( e.status == 429 ):
        print('Usage limit are exceeded. Wating for 60 seconds...')
        time.sleep(60)
        continue

    stories = response.stories
    params['cursor'] = response.next_page_cursor

    fetched_stories += stories
    print("Fetched %d stories. Total story count so far: %d" %
      (len(stories), len(fetched_stories)))

  return fetched_stories

params = {
  'title': 'Dublin',
  'language': ['en'],
  'published_at_start': 'NOW-1HOUR',
  'published_at_end': 'NOW',
  'cursor': '*',
  'sort_by': 'published_at',
  'sort_direction': 'desc'
}

while True:
  stories = fetch_new_stories(params)

  print('************')
  print("Fetched %d stories which were published between %s and %s" %
    (len(stories), params['published_at_start'], params['published_at_end']))

  if len(stories) > 0:
    last_fetched_at = stories[0].published_at + datetime.timedelta(seconds=1)
    params['published_at_start'] = last_fetched_at.isoformat()[:-6] + 'Z'
    params['cursor'] = '*'

  print('Sleep for 60 seconds until next poll...')
  print('------------')
  time.sleep(60)

require 'aylien_news_api'
require 'time'

def fetch_new_stories(params={})
  puts "------------"

  fetched_stories = []
  stories = nil

  while stories.nil? || stories.size > 0
    begin
      result = $api_instance.list_stories(params)
    rescue AylienNewsApi::ApiError => e
      if e.code == 429
        puts "Usage limit are exceeded. Wating for 60 seconds..."
        sleep(60)
        retry
      end
    end

    stories = result.stories
    params[:cursor] = result.next_page_cursor

    fetched_stories += stories
    puts "Fetched #{stories.size} stories. Total story count so far: #{fetched_stories.size}"
  end

  fetched_stories
end

AylienNewsApi.configure do |config|

  config.api_key['X-AYLIEN-NewsAPI-Application-ID'] = "YOUR_APP_ID"
  config.api_key['X-AYLIEN-NewsAPI-Application-Key'] = "YOUR_API_KEY"

end

$api_instance = AylienNewsApi::DefaultApi.new

opts = { 
  :title => 'Dublin', 
  :language => ["en"], 
  :published_at_start => "NOW-30MINUTES", 
  :published_at_end => "NOW",
  :cursor => "*"
}

while true do
    stories = fetch_new_stories(opts)

    puts "*"*80
    puts "Fetched #{stories.size} stories which were published between #{opts[:published_at_start]} and #{opts[:published_at_end]}"

    if stories.size > 0
      last_fetched_at = stories[0].published_at + Rational(1, 86400)
      opts[:published_at_start] = last_fetched_at.to_time.utc.iso8601
      opts[:cursor] = "*"
    end

    puts "Sleep for 60 seconds until next poll..."
    puts "------------\n\n"

    sleep(60)
  end

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

function sleep(time) {
  return new Promise((resolve) => setTimeout(resolve, time));
}
async function fetchNewStories(opts) {
  let fetchedStories = [];
  let stories = null;
  do {
    await new Promise((resolve, reject) => {
      apiInstance.listStories(opts, (error, data, response) => {
        if (error){
          if (response.status == 429) {
            console.log('Usage limit are exceeded. Wating for 30 seconds...');
            sleep(30 * 1000).then(function(){
              resolve();
            });
          } else {
            reject(error);
          }
        } else {
          opts.cursor = data.nextPageCursor;
          stories = data.stories;
          fetchedStories = fetchedStories.concat(stories);
          console.log("Fetched " + stories.length +
            " stories. Total story count so far: " + fetchedStories.length);
          resolve();
        }
      })
    })
  } while (stories.length > 0);
  return fetchedStories;
}

var apiInstance = new AylienNewsApi.DefaultApi();

// 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 opts = {
  'title': 'Dublin',
  'language': ['en'],
  'publishedAtStart': 'NOW-60MINUTES',
  'publishedAtEnd': 'NOW/MINUTE',
  'cursor': '*',
  'perPage': 100,
  'sortBy': 'published_at',
  'sortDirection': 'desc'
};

var whileCondition = function(){ return true; };

promiseWhile(whileCondition, function(){
  return new Promise(function (resolve, reject){
    fetchNewStories(opts).then(function(stories){
      console.log('Fetched ' + stories.length +
        ' stories which were published between ' + opts['publishedAtStart'] +
        ' and ' + opts['publishedAtEnd']);

      if (stories.length > 0) {
        var newFetchAt = stories[0].published_at.getTime() + 1000;
        opts['publishedAtStart'] = new Date(newFetchAt);
        opts['cursor'] = '*';
      }
      console.log("Sleep for 60 seconds until next poll...");
      console.log('------------- \n');
      sleep(60 * 1000).then(function(){
        resolve();
      });
    });
  });
});

<?php
require_once(__DIR__ . '/vendor/autoload.php');

function fetch_new_stories($opts){
  print_r("-----------\n");
  print_r($opts);

  global $api_instance;

  $fetched_stories = [];
  $stories = NULL;

  while (is_null($stories) || count($stories) > 0) {
    try {
      $result = $api_instance->listStories($opts);
    } catch (Exception $e) {
      $code = $e->getResponseObject()->getErrors()[0]->getStatus();

      if ($code == '429'){
        print_r("Usage limit are exceeded. Wating for 60 seconds...\n");
        sleep(60);
        continue;
      }
    }

    $stories = $result->getStories();
    $fetched_stories = array_merge($fetched_stories, $stories);
    $opts['cursor'] = $result->getNextPageCursor();

    print_r(sprintf("Fetched %d stories. Total story count so far: %d\n",
      count($stories), count($fetched_stories)));
    for($i = 0; $i < sizeof($result->getStories()); $i++){
      print_r($result->getStories()[$i]->getPublishedAt());
    };
    print_r("\n\n");
    }

  return $fetched_stories;
}

$config = Aylien\NewsApi\Configuration::getDefaultConfiguration()->setApiKey('X-AYLIEN-NewsAPI-Application-ID', 'YOUR_APP_ID');
$config = Aylien\NewsApi\Configuration::getDefaultConfiguration()->setApiKey('X-AYLIEN-NewsAPI-Application-Key', 'YOUR_API_KEY');
$api_instance = new Aylien\NewsApi\Api\DefaultApi(new GuzzleHttp\Client(), $config);


$params = array(
  'title' => 'Dublin',
  'published_at_start' => 'NOW-1HOUR',
  'published_at_end' => 'NOW',
  'language' => ['en'],
  'per_page' => 100,
  'sort_by' => 'published_at',
  'sort_direction' => 'desc',
  'cursor' => "*"
);

while(true){
  $stories = fetch_new_stories($params);

  print_r("************\n");
  print_r(sprintf("Fetched %d stories which were published between %s and %s\n",
    count($stories), $params['publishedAtStart'], $params['publishedAtEnd']));

  if (count($stories) > 0){
    $lastFetchedAt = $stories[0]->getPublishedAt()->add(new DateInterval('PT10S'));

    $params['cursor'] = '*';
    $params['publishedAtStart'] = $lastFetchedAt->format('Y-m-d\TH:i:s\Z');
  }

  print_r("Sleep for 60 seconds until next poll...\n");
  print_r("-----------\n\n");

  sleep(60);
}
?>

package main

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

func main() {

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

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

  fetchNewStories := func (apiInstance *newsapi.DefaultApiService, storiesParams *newsapi.ListStoriesOpts) []newsapi.Story {
    var fetchedStories []newsapi.Story
    var stories []newsapi.Story
    isFirstCall := true

    for isFirstCall || len(stories) > 0 {
      storiesResponse, res, err := apiInstance.ListStories(context.Background(), storiesParams)
      if err != nil {
        panic(err)
      }

      if res.StatusCode == 429 {
        fmt.Println("Usage limit are exceeded. Wating for 60 seconds...")
        time.Sleep(time.Duration(60) * time.Second)
        continue
      }

      isFirstCall = false
      stories = storiesResponse.Stories
      storiesParams.Cursor = optional.NewString(storiesResponse.NextPageCursor)

      fetchedStories = append(fetchedStories, stories...)

      fmt.Printf("Fetched %d stories. Total story count so far: %d\n", len(stories), len(fetchedStories))
    }

    return fetchedStories
  }
  for {
    storiesParams := &newsapi.ListStoriesOpts{
      Title:             optional.NewString("Dublin"),
      PublishedAtStart: optional.NewString("NOW-60SECONDS"),
      PublishedAtEnd:   optional.NewString("NOW"),
      SortBy:           optional.NewString("published_at"),
    }

    stories := fetchNewStories(api, storiesParams)
    fmt.Printf("Fetched %d stories which were published between %s and %s\n",
    len(stories), storiesParams.PublishedAtStart, storiesParams.PublishedAtEnd)
    for _, story := range stories{
      fmt.Println(story.PublishedAt,  " / ", story.Title)
    }

    if len(stories) > 0 {
    lastFetchedAt := stories[0].PublishedAt.Add(time.Duration(1) * time.Second)
    // messy type transformation needed for the antihax library
    storiesParams.PublishedAtStart = optional.NewString(lastFetchedAt.Format("2006-01-02T15:04:05Z"))
    e := lastFetchedAt.Format("2006-01-02T15:04:05Z")
    fmt.Println(e)
    storiesParams.Cursor = optional.NewString("*")
    }

    fmt.Println("Sleeping for 60 seconds until next poll...")
    fmt.Println("------------")
    time.Sleep(time.Duration(60) * time.Second)
  }
}

Pagination of Results

This workflow allows you to decide how the results of a search are split into multiple pages on your UI.

Fetching a Large Number of Sorted Results: Cursor

The API supports using a cursor to scan through results. In the API, a cursor is a logical concept that doesn't cache any state information on the server. Instead, the sort values of the last story returned to the client are used to compute a next_page_cursor, representing a logical point in the ordered space of sort values. That next_page_cursor can be specified in the parameters of subsequent requests to tell the API where to continue.

Using a Cursor

To use a cursor with the API, specify a cursor parameter with the value of *. This is the same as declaring page=1 to tell the API "start at the beginning of my sorted results," except it also informs the API that you want to use a cursor. The default value of cursor is * unless you specify otherwise. In addition to returning the top N sorted results (where you can control N using the per_page parameter) the API response will also include an encoded String named next_page_cursor.

You then take the next_page_cursor String value from the response, and pass it back to the API as the cursor parameter for your next request. You can repeat this process until you've fetched as many stories as you want, or until the next_page_cursor returns matches the cursor you've already specified — indicating that there are no more results.

Using the Per Page Attribute

The API supports using a per_page to specify the maximum number of stories per page. This parameter is used to paginate results from a query. The possible value for this parameter is between 1 to 100.

Examples

The following example shows how to retrieve all stories in English, that are about Sports and were published between 1 hour ago and now.

from __future__ import print_function
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'
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))

def fetch_new_stories(params={}):
  fetched_stories = []
  stories = None

  while stories is None or len(stories) > 0:
    try:
      response = api_instance.list_stories(**params)
    except ApiException as e:
      if ( e.status == 429 ):
        print('Usage limit are exceeded. Wating for 60 seconds...')
        time.sleep(60)
        continue

    stories = response.stories
    params['cursor'] = response.next_page_cursor

    fetched_stories += stories
    print("Fetched %d stories. Total story count so far: %d" %
      (len(stories), len(fetched_stories)))

  return fetched_stories

params = {
  'language': ['en'],
  'title': 'startup',
  'published_at_start': 'NOW-1HOUR',
  'published_at_end': 'NOW',
  'cursor': '*',
  'sort_by': 'published_at'
}

stories = fetch_new_stories(params)

print('************')
print("Fetched %d stories mentioning 'startup' in the title, are in English, and were published between %s and %s" %
(len(stories), params['published_at_start'], params['published_at_end']))

# Load the gem
require 'aylien_news_api'

def fetch_new_stories(params={})
  fetched_stories = []
  stories = nil

  while stories.nil? || stories.size > 0
    begin
      result = $api_instance.list_stories(params)
    rescue AylienNewsApi::ApiError => e
      if e.code == 429
        puts 'Usage limit are exceeded. Wating for 30 seconds...'
        sleep(30)
        retry
      end
    end

    stories = result.stories
    stories.each do |story|
        puts story.title
    end
    params[:cursor] = result.next_page_cursor

    fetched_stories += stories
    puts "Fetched #{stories.size} stories. Total story count so far: #{fetched_stories.size}"
  end

  fetched_stories
end

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

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

# create an instance of the API class
$api_instance = AylienNewsApi::DefaultApi.new

opts = {
  :title => 'startup',
  :published_at_start => 'NOW-10HOURS',
  :published_at_end => 'NOW',
  :per_page => 5,
  :sort_by => 'published_at'
}

stories = fetch_new_stories(opts)

puts "*"*80
puts "Fetched #{stories.size} stories in total."

var AylienNewsApi = require('aylien-news-api');

function sleep(time) {
  return new Promise((resolve) => setTimeout(resolve, time));
}
async function fetchNewStories(opts) {
  let fetchedStories = [];
  let stories = null;
  do {
    await new Promise((resolve, reject) => {
      apiInstance.listStories(opts, (error, data, response) => {
        if (error){
          if (response.status == 429) {
            console.log('Usage limit are exceeded. Wating for 30 seconds...');
            sleep(30 * 1000).then(function(){
              resolve();
            });
          } else {
            reject(error);
          }
        } else {
          opts.cursor = data.nextPageCursor;
          stories = data.stories;
          fetchedStories = fetchedStories.concat(stories);
          console.log("Fetched " + stories.length +
            " stories. Total story count so far: " + fetchedStories.length);
          resolve();
        }
      })
    })
  } while (stories.length > 0);
  return fetchedStories;
}

var apiInstance = new AylienNewsApi.DefaultApi();
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 opts = {
  'language': ['en'],
  'publishedAtStart': 'NOW-1HOUR',
  'publishedAtEnd': 'NOW',
  'categoriesTaxonomy': 'iab-qag',
  'categoriesId': ['IAB17'],
  'cursor': '*',
  'perPage': 16
};

fetchNewStories(opts).then(function(stories){
  console.log('**************');
  console.log('Fetched ' + stories.length +
    ' stories which are in English, are about Sports and were' +
    ' published between 1 hour ago and now');
});

<?php
require_once(__DIR__ . '/vendor/autoload.php');

function fetch_new_stories($opts){
  global $api_instance;

  $fetched_stories = [];
  $stories = NULL;
  print_r($opts);
  while (is_null($stories) || count($stories) > 0) {
    try {
      $result = $api_instance->listStories($opts);
      print_r($result);
    } catch (Exception $e) {
      $code = $e->getResponseObject()->getErrors()[0]->getStatus();

      if ($code == '429'){
        print_r("Usage limit are exceeded. Wating for 30 seconds...\n");
        sleep(30);
        continue;
      }
    }

    $stories = $result->getStories();
    $fetched_stories = array_merge($fetched_stories, $stories);
    $opts['cursor'] = $result->getNextPageCursor();

    print_r("Fetched " . count($stories) . " stories. Total story count so far: " . count($fetched_stories) . "\n");
  }

  return $fetched_stories;
}

$config = Aylien\NewsApi\Configuration::getDefaultConfiguration()->setApiKey('X-AYLIEN-NewsAPI-Application-ID', 'YOUR_APP_ID');
$config = Aylien\NewsApi\Configuration::getDefaultConfiguration()->setApiKey('X-AYLIEN-NewsAPI-Application-Key', 'YOUR_API_KEY');
$api_instance = new Aylien\NewsApi\Api\DefaultApi(new GuzzleHttp\Client(), $config);

$params = array(
  'published_at_start' => 'NOW-4HOURS',
  'published_at_end' => 'NOW',
  'language' => ['en'],
  'categories_taxonomy' => 'iab-qag',
  'categories_id' => ['IAB17'],
  'sort_by' => 'published_at',
  'sort_direction' => 'desc',
  'return' => ['title', 'published_at'],
  'per_page' => 10
);

$stories = fetch_new_stories($params);

print_r("************\n");
print("Fetched " . count($stories) . " stories in English, are about Sports and were published between 1 hour ago and now\n");
?>

package main

import (
  "time"
  "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

  fetchNewStories := func (apiInstance *newsapi.DefaultApiService, params *newsapi.ListStoriesOpts) []newsapi.Story {
    var fetchedStories []newsapi.Story
    var stories []newsapi.Story
    isFirstCall := true

    for isFirstCall || len(stories) > 0 {
    storiesResponse, res, err := apiInstance.ListStories(context.Background(), params)
    if err != nil {
      panic(err)
    }

    if res.StatusCode == 429 {
      fmt.Println("Usage limit are exceeded. Wating for 60 seconds...")
      time.Sleep(time.Duration(60) * time.Second)
      continue
    }

    isFirstCall = false
    stories = storiesResponse.Stories
    params.Cursor = optional.NewString(storiesResponse.NextPageCursor)

    fetchedStories = append(fetchedStories, stories...)

    fmt.Printf("Fetched %d stories. Total story count so far: %d \n",
      len(stories), len(fetchedStories))
    }

    return fetchedStories
  }

  storiesParams := &newsapi.ListStoriesOpts{
    Cursor:         optional.NewString("*"),
    PerPage:        optional.NewInt32(10),
    PublishedAtStart:       optional.NewString("NOW-12HOURS"),
    PublishedAtEnd:         optional.NewString("NOW"),
    SortBy:         optional.NewString("published_at"),
    Title:          optional.NewString("startup"),
    }

  stories := fetchNewStories(api, storiesParams)

  fmt.Println("***************")
  fmt.Printf("Fetched %d stories which are in English, are about startups and were published between %s and %sn",
  len(stories), storiesParams.PublishedAtStart, storiesParams.PublishedAtEnd)
}

Sorting Results

You can choose how you want your results to be sorted by using the sort_by parameter. This allows you to receive the most relevant results of your query first, with relevance based on a value you choose as a parameter.

The sort_by parameter can take one of the following values:

Relevance

Using the relevance value returns the stories that most closely matches your search input. The parameter value is relevance.

Recency

There are two ways of sorting your results by recency:

Using the recency value gives a higher rank to stories that were published more recently but also gives weight to your query too.
Using published_at as the value here will rank your results based only on how recently your returned stores were published.

Hotness

Using the hotness value gives a higher rank to stories that were published more recently but also gives weight to social media sharing, inbound links, and Alexa ranking.

Social Media shares

It is possible to sort your results by the following Social Media-based metrics:

Shares on LinkedIn (social_shares_count.linkedin)
Upvotes on Reddit (social_shares_count.reddit)
Total number of shares on all the above networks (social_shares_count)

Number of photos

This value allows users to rank results based on the number of photos on the page. The parameter value is media.images.count.

Number of videos

This value allows users to rank results based on the number of videos on the page. The parameter value is media.videos.count.

Alexa ranking

Alexa is a ranking system that ranks websites based on the volume of traffic they have generated over the previous 3 months. The more traffic a website receives, the higher its ranking. For example, Google.com has a ranking of 1, BBC.co.uk has a ranking of around 100, and so on. Alexa gives two options to users when seeking the ranking of sites:

Global ranking, based on how popular a website is globally
National ranking, based on how popular a site is in a given country. This is available for every country in the world, and is accessed by adding the ISO 3166-1 alpha-2 country code to your parameter. For more information, take a look at our page on working with Alexa rankings.

Each of the parameters above can sort results by ascending or descending value. This is achieved by entering either asc or desc as a value of the sort_direction parameter. If this parameter is not declared, results will be returned in descending order.

Examples

The code below gathers stories that mention baseball from the last month and sorts them according to recency.

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

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

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

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

params = {
  'language': ['en'],
  'published_at_start': 'NOW-1MONTH',
  'published_at_end': 'NOW',
  'entities_title_links_dbpedia': ['http://dbpedia.org/resource/Baseball'],
  'sort_by': 'published_at'
}

try:
    # List stories
    api_response = api_instance.list_stories(**params)
    print('The API has been called successfully.')
    print('=====================================')
    for story in api_response.stories:
      print(story.title + " / " + story.source.name)
except ApiException as e:
    print("Exception when calling DefaultApi->list_stories: %sn" % 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_APP_ID'

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

api_instance = AylienNewsApi::DefaultApi.new

opts = {
  :published_at_start => "NOW-1MONTH",
  :published_at_end => "NOW",
  :entities_body_links_dbpedia => [
    'http://dbpedia.org/resource/Baseball'
  ],
  :categories_taxonomy => 'iab-qag',
  :categories_id => ['IAB17'],
  :language => ['en'],
  :sort_by => 'published_at'
}


begin
  #List stories
  result = api_instance.list_stories(opts)

  puts 'The API has been called successfully.'
  puts '====================================='
  result.stories.each do |story|
    puts "#{story.title} / #{story.source}"
  end
rescue AylienNewsApi::ApiError => e
  puts "Exception when calling DefaultApi->list_stories: #{e}"
  puts e.response_body
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 = {
  'language': ['en'],
  'entitiesBodyLinksDbpedia': [
    'http://dbpedia.org/resource/Baseball'
  ],
  'categoriesTaxonomy': 'iab-qag',
  'categoriesId': ['IAB17'],
  'publishedAtStart': 'NOW-1MONTH',
  'publishedAtEnd': 'NOW',
  'sortBy': 'published_at'
};

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('The API has been called successfully.');
    console.log('=====================================');
    for (var i = 0; i < data.stories.length; i++){
        console.log("\n" + data.stories[i].title + "\n" + data.stories[i].source.name, data.stories[i].source.rankings);
    }
  }
};
apiInstance.listStories(opts, callback);

<?php
require_once(__DIR__ . '/vendor/autoload.php');

// Configure API key authorization: app_id
$config = Aylien\NewsApi\Configuration::getDefaultConfiguration()->setApiKey('X-AYLIEN-NewsAPI-Application-ID', 'YOUR_APP_ID');
// Configure API key authorization: app_key
$config = Aylien\NewsApi\Configuration::getDefaultConfiguration()->setApiKey('X-AYLIEN-NewsAPI-Application-Key', 'YOUR_API_KEY');

$apiInstance = new Aylien\NewsApi\Api\DefaultApi(
    new GuzzleHttp\Client(),
    $config
);

$opts = array(
  'published_at_start' => 'NOW-1MONTH',
  'published_at_end' => 'NOW',
  'entities_title_links_dbpedia' => [
    'http://dbpedia.org/resource/Baseball'
  ],
  'categories_taxonomy' => 'iab-qag',
  'categories_id' => ['IAB17'],
  'language' => ['en'],
  'sort_by' => 'source.rankings.alexa.rank.US'
);

try {
    $result = $apiInstance->listStories($opts);
    print_r("The API has been called successfully.\n");
    print_r("=====================================\n");
    for($i = 0; $i < sizeof($result->getStories()); $i++){
      print_r($result->getStories()[$i]->getTitle() . " / " .
        $result->getStories()[$i]->getSource()->getName() . "\n");
    }
} catch (Exception $e) {
    print_r($e->getResponseObject()->getErrors());
    echo 'Exception when calling DefaultApi->listStories: ', $e->getMessage(), "\n";
}
?>

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{
    Language:                   optional.NewInterface([]string{"en"}),
    PublishedAtStart:           optional.NewString("NOW-1MONTH"),
    PublishedAtEnd:             optional.NewString("NOW"),
    CategoriesTaxonomy:         optional.NewString("iab-qag"),
    CategoriesId:               optional.NewInterface([]string{"IAB17"}),
    SortBy:                     optional.NewString("published_at"),
  }
  storiesResponse, res, err := api.ListStories(context.Background(), storiesParams)
  if err != nil {
    panic(err)
  }
  _ = res

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

Working with Entities

The entities parameters are a powerful tool that you can use to cut out noise and find stories about the things you are interested in. Think of entities like keywords that are enhanced by NLP, allowing you to specify the exact thing that you want, instead of listing dozens of keywords about the same company or brand to ensure you capture all of the mentions.

An entity is a thing with a name, a type and (optionally) a uniform resource identifier (URI), which is a url specifically for that entity that allows a computer to refer to it specifically. Any distinct person, organization, place or product could be considered an entity (the list doesn't end here; these are just 4 highly common types of entities).

The benefits of searching with entities instead of keywords

When a keyword or term can refer to multiple entities, the News API will consider the rest of the document to make an accurate prediction about which entity is being referred to. Take for example two sentences mentioning the keyword “apple”:

"An apple is a great source of vitamins."

Text: "apple"
Name: Apple
Type: Fruit, Eukaryote, Plant, etc.
URI: http://dbpedia.org/resource/Apple

" Apple was founded by Steve Jobs and Steve Wozniak."

Text: "Apple"
Name: Apple Inc.
Type: Company, Organization.
URI: http://dbpedia.org/resource/Apple_Inc

Also, when an entity has multiple terms or keywords that refer to it, the News API will identify the entity for each appearance. Take a look at how the News API recognizes the entity “MetLife,” even when different names for the company are mentioned:

"Shares in Metropolitan Life Insurance fell sharply this morning."

Text: "Metropolitan Life Insurance"
Name: MetLife
Type: Company, Organization.
URI: http://dbpedia.org/resource/MetLife

“MetLife announces new insurance offerings."

Text: "MetLife"
Name: MetLife
Type: Company, Organization.
URI: http://dbpedia.org/resource/MetLife

DBpedia entity types (and when to use them)

DBpedia is a semantic web project that extracts structured information created as part of the Wikipedia project. Think of it as a counterpart of Wikipedia, where distinct entities are referred to by URIs (like http://dbpedia.org/resource/Apple_Inc.) and contain structured information that we can leverage, on of which is the entity type.

Just as Apple and MetLife above have “Company” and “Organization” as their entity types, every entity recognized by the News API has a type. For example, the New York Stock Exchange entity has the type “Index,” referring to stock exchange.

We can use entity types to build intelligent searches - if we want to search for stories that are about MetLife and also mention any stock exchange, we can specify the following parameters:

"entities.body.links.dbpedia" : ["http://dbpedia.org/resource/MetLife"],
"entities.body.type" : ["Index"]

For a complete list of entity types, refer to the Ontology Classes document on the DBpedia project website.

Finding DBpedia URIs

Using the Autocompletes endpoint, you can retrieve the DBpedia link for an entity by providing its name (or a part of it). All you need to do is to set type=dbpedia_resources and provide all or a part of the entity's name using the term parameter.

Similarly, you can search over all entity types by setting type=entity_types while using the Autocompletes endpoint.

For more information, please refer to the examples provided in the Autocompletes documentation.

Note: Not all entities have a DBpedia identifier. Typically, only well-known entities have one. If your Autocompletes search doesn't yield any results, consider providing the name of the entity as text (entities.title.text[] or entities.body.text[]) instead.

How to search by entity

Except for Autocompletes, all of our endpoints support the following attributes for filtering results by entities:

entities.title.text[]: List of surface forms for entities found in the story title
entities.title.type[]: List of types for entities found in the story title
entities.title.links.dbpedia[]: List of identifiers (DBpedia URI) for entities found in the story title
entities.body.text[]: List of surface forms for entities found in the story body
entities.body.type[]: List of types for entities found in the story body
entities.body.links.dbpedia[]: List of identifiers (DBpedia URI) for entities found in the story body

With these parameters you can search by entity name (e.g. "Apple" or "Kim Kardashian"), entity type (e.g. http://dbpedia.org/resource/Person) or entity links (e.g. http://dbpedia.org/resource/Apple_Inc.).

Examples

The following example shows articles that are in English, mention Donald Trump and any currency in the title, and were published between 1 month ago and now:

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

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

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

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

params = {
  'sort_by': 'source.rankings.alexa.rank.US',
  'language': ['en'],
  'published_at_start': 'NOW-1MONTH',
  'published_at_end': 'NOW',
  'entities_title_links_dbpedia': ['http://dbpedia.org/resource/Donald_Trump'],
  'entities_title_type': ['Currency']
}

try:
    # List stories
    api_response = api_instance.list_stories(**params)
    print('The API has been called successfully.')
    print('=====================================')
    for story in api_response.stories:
      print(story.title + " / " + story.source.name)
except ApiException as e:
    print("Exception when calling DefaultApi->list_stories: %sn" % 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_APP_ID'

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

api_instance = AylienNewsApi::DefaultApi.new

opts = {
  :entities_title_links_dbpedia => [
    'http://dbpedia.org/resource/Donald_Trump'
  ],
  :entities_title_type => [
    'Currency'
  ],
  :published_at_start => "NOW-1MONTH",
  :language => ['en'],
}


begin
  #List stories
  result = api_instance.list_stories(opts)

  puts 'The API has been called successfully.'
  puts '====================================='
  result.stories.each do |story|
    puts "#{story.title} / #{story.source.name}"
  end
rescue AylienNewsApi::ApiError => e
  puts "Exception when calling DefaultApi->list_stories: #{e}"
  puts e.response_body
end

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


var apiInstance = new AylienNewsApi.DefaultApi();

// 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 opts = {
  'entitiesTitleLinksDbpedia': [
    'http://dbpedia.org/resource/Donald_Trump'
  ],
  'entitiesTitleType': [
    'Currency'
  ],
  'language': ['en'],
  'publishedAtStart': 'NOW-1MONTH',
  'publishedAtEnd': 'NOW'
};

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('The API has been called successfully.');
    console.log('=====================================');
    for (var i = 0; i < data.stories.length; i++){
      console.log(data.stories[i].title + " / " + data.stories[i].source.name);
    }
  }
};
apiInstance.listStories(opts, callback);

<?php
require_once(__DIR__ . '/vendor/autoload.php');

// Configure API key authorization: app_id
$config = Aylien\NewsApi\Configuration::getDefaultConfiguration()->setApiKey('X-AYLIEN-NewsAPI-Application-ID', 'YOUR_APP_ID');
// Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
// $config = Aylien\NewsApi\Configuration::getDefaultConfiguration()->setApiKeyPrefix('X-AYLIEN-NewsAPI-Application-ID', 'Bearer');

// Configure API key authorization: app_key
$config = Aylien\NewsApi\Configuration::getDefaultConfiguration()->setApiKey('X-AYLIEN-NewsAPI-Application-Key', 'YOUR_API_KEY');
// Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
// $config = Aylien\NewsApi\Configuration::getDefaultConfiguration()->setApiKeyPrefix('X-AYLIEN-NewsAPI-Application-Key', 'Bearer');


$apiInstance = new Aylien\NewsApi\Api\DefaultApi(
    new GuzzleHttp\Client(),
    $config
);

$opts = array(
  'entities_title_links_dbpedia' => [
    'http://dbpedia.org/resource/Donald_Trump'
  ],
  'entities_title_type' => 'Currency',
  'language' => ['en'],
  'published_at_start' => 'NOW-1MONTH',
  'published_at_end' => 'NOW'
);

try {
    $result = $apiInstance->listStories($opts);
    print_r("The API has been called successfully.\n");
    print_r("=====================================\n");
    for($i = 0; $i < sizeof($result->getStories()); $i++){
      print_r($result->getStories()[$i]->getTitle() . " / " .
        $result->getStories()[$i]->getSource()->getName() . "\n");
    }
} catch (Exception $e) {
    print_r($e->getResponseObject()->getErrors());
    echo 'Exception when calling DefaultApi->listStories: ', $e->getMessage(), "\n";
}
?>

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{
    PublishedAtStart:               optional.NewString("NOW-1MONTH"),
    PublishedAtEnd:                 optional.NewString("NOW"),
    EntitiesTitleLinksDbpedia:      optional.NewInterface([]string{"http://dbpedia.org/resource/Donald_Trump"}),
    EntitiesTitleType:              optional.NewInterface([]string{"Currency"}),
    PerPage:                        optional.NewInt32(10),
  }

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

  if err != nil {
    panic(err)
  }

  _ = res

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

Boolean Operators

Boolean operators allow you to apply Boolean logic to queries, requiring the presence or absence of specific terms or conditions in fields in order to match documents. The table below summarizes the Boolean operators supported by the standard query parser.

Boolean Operator	Alternative Symbol	Description
NOT	`!`	Requires that the following term not be present.
AND	`&&`	Requires both terms on either side of the Boolean operator to be present for a match.
	`+`	Requires that the following term be present.
	`-`	Prohibits the following term (that is, matches on fields or documents that do not include that term). The - operator is functionally similar to the Boolean operator !. Because it's used by popular search engines such as Google, it may be more familiar to some user communities.
OR	`\|\|`	Requires that either term (or both terms) be present for a match.

The Boolean Operator NOT (!)

The NOT operator excludes documents that contain the term after NOT. This is equivalent to a difference using sets. The symbol ! can be used in place of the word NOT.

The following queries search for documents that contain the phrase "jakarta apache" but do not contain the phrase "Apache Lucene":

"jakarta apache" NOT "Apache Lucene"

"jakarta apache" ! "Apache Lucene"

The Boolean Operator AND (&&)

The AND operator matches documents where both terms exist anywhere in the text of a single document. This is equivalent to an intersection using sets. The symbol && can be used in place of the word AND.

To search for documents that contain "jakarta apache" and "Apache Lucene," use either of the following queries:

"jakarta apache" AND "Apache Lucene"

"jakarta apache" && "Apache Lucene"

The Boolean Operator +

The + symbol (also known as the "required" operator) requires that the term after the + symbol exist somewhere in a field in at least one document in order for the query to return a match.

For example, to search for documents that must contain "jakarta" and that may or may not contain "lucene," use the following query:

+jakarta lucene

The Boolean Operator -

The - symbol or "prohibit" operator excludes documents that contain the term after the - symbol.

For example, to search for documents that contain "jakarta apache" but not "Apache Lucene," use the following query:

"jakarta apache" -"Apache Lucene"

The Boolean Operator OR (||)

The OR operator is the default conjunction operator. This means that if there is no Boolean operator between two terms, the OR operator is used. The OR operator links two terms and finds a matching document if either of the terms exist in a document. This is equivalent to a union using sets. The symbol || can be used in place of the word OR.

For example, to search for documents that contain either "jakarta apache" or just "jakarta," use the query:

"jakarta apache" jakarta

"jakarta apache" OR jakarta

Grouping Terms to Form Sub-Queries

The API supports using parentheses to group clauses to form sub-queries. This can be very useful if you want to control the Boolean logic for a query.

The query below searches for either "jakarta" or "apache" and "website":

(jakarta OR apache) AND website

This adds precision to the query, requiring that the term "website" exist, along with either term "jakarta" and "apache."

Working with Dates

Date Formatting

The format used is a restricted form of the canonical representation of dateTime in the XML Schema specification (ISO 8601):

YYYY-MM-DDThh:mm:ssZ

YYYY is the year.
MM is the month.
DD is the day of the month.
T is a literal 'T' character that indicates the beginning of the time string.
hh is the hour of the day as on a 24-hour clock.
mm is minutes.
ss is seconds.
Z is a literal 'Z' character indicating that this string representation of the date is in UTC

Note that no time zone can be specified; the String representations of dates is always expressed in Coordinated Universal Time (UTC). Here is an example value:

2016-03-27T13:47:26Z

You can optionally include fractional seconds if you wish, although any precision beyond milliseconds will be ignored. Here are examples value with sub-seconds include:

2016-03-27T13:47:26.822Z
2016-03-27T13:47:26.82Z
2016-03-27T13:47:26.8Z

Date Math

The date field types also supports date math expressions, which makes it easy to create times relative to fixed moments in time, include the current time which can be represented using the special value of "NOW".

Date Math Syntax

Date math expressions can do two things: they can specify a time period by adding time units to the current time, and also round the time to a specified unit. Expressions can be chained and are evaluated left to right.

For example: this represents a point in time two months from now, from the millisecond:

NOW+2MONTHS

This is one day ago, to the millisecond:

NOW-1DAY

A slash is used to indicate rounding. Below is a point in time yesterday, rounded to the previous hour, with millisecond precision (For example, if the current time is 15:42:17.2165, the point below is 15:00:00.0000 yesterday):

NOW-1DAY/HOUR

Below is yesterday at 00:00:00.0000AM:

NOW-1DAY/DAY

Here is the supported keywords in Date Math:

Date part keywords	Alternative keywords	Description
NOW		It represents current date time.
YEAR	YEARS	It represents the year part of date time.
MONTH	MONTHS	It represents the month part of date time.
DAY	DAYS DATE	It represents the day part of date time.
HOUR	HOURS	It represents the hour part of date time.
MINUTE	MINUTES	It represents the minute part of date time.
SECOND	SECONDS	It represents the second part of date time.

Working with Locations

There are three ways to work with locations in the News API. Below we outline the three methods.

Based on Source Location

Description

Source location refers to where the source is based, and allows you to filter results to stories published in a specific location.

Note that country values are supplied in ISO format, whereas city and state values are not.

Examples

The following example shows how to retrieve stories about politics that are from sources located in Florida.

from __future__ import print_function
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'
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))

params = {
'language': ['en']
'published_at_start': 'NOW-10DAYS'
'published_at_end': 'NOW'
'categories_taxonomy': 'iptc-subjectcode'
'categories_id': ['11000000']
'source_locations_country': ['US']
'source_locations_state': ['Florida']
}

try:
  # List stories
  api_response = api_instance.list_stories(**opts)
  print(api_response)
except ApiException as e:
  print("Exception when calling DefaultApi->list_stories: %sn" % 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_APP_ID'

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

api_instance = AylienNewsApi::DefaultApi.new

opts = {
  :published_at_start => "NOW-10DAYS",
  :published_at_end => "NOW",
  :language => ['en'],
  :categories_taxonomy => 'iptc-subjectcode',
  :categories_id => ['11000000'],
  :source_locations_country => ['US']
  :source_locations_state => ['Florida']
}


begin
  #List stories
  result = api_instance.list_stories(opts)
  result.stories.each do |story|
    puts "#{story.title} / #{story.source.locations}"
  end
rescue AylienNewsApi::ApiError => e
  puts "Exception when calling DefaultApi->list_stories: #{e}"
end

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


var apiInstance = new AylienNewsApi.DefaultApi();


// 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 opts = {
  'sortBy': 'published_at',
  'language': ['en'],
  'publishedAtStart': 'NOW-10DAYS',
  'publishedAtEnd': 'NOW',
  'sourceLocationsCountry': ['US'],
  'sourceLocationsState': ['Florida'],
  'perPage': 10
};

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    //   console.log(data.stories[0].source.locations[0].country);
      for (var i = 0; i < data.stories.length; i++){
        console.log(data.stories[i].source);
      }  
}
};
apiInstance.listStories(opts, callback);

<?php
require_once(__DIR__ . '/vendor/autoload.php');


// Configure API key authorization: app_id
$config = Aylien\NewsApi\Configuration::getDefaultConfiguration()->setApiKey('X-AYLIEN-NewsAPI-Application-ID', 'YOUR_APP_ID');
// Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
// $config = Aylien\NewsApi\Configuration::getDefaultConfiguration()->setApiKeyPrefix('X-AYLIEN-NewsAPI-Application-ID', 'Bearer');

// Configure API key authorization: app_key
$config = Aylien\NewsApi\Configuration::getDefaultConfiguration()->setApiKey('X-AYLIEN-NewsAPI-Application-Key', 'YOUR_API_KEY');
// Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
// $config = Aylien\NewsApi\Configuration::getDefaultConfiguration()->setApiKeyPrefix('X-AYLIEN-NewsAPI-Application-Key', 'Bearer');


$apiInstance = new Aylien\NewsApi\Api\DefaultApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
    // This is optional, `GuzzleHttp\Client` will be used as default.
    new GuzzleHttp\Client(),
    $config
);

$opts = array(
  'published_at_start' => 'NOW-10DAYS',
  'published_at_end' => 'NOW',
  'language' => ['en'],
  'categories_taxonomy' => 'iptc-subjectcode',
  'categories_id' => ['11000000'],
  'source_locations_country' => ['US']
  'source_locations_state' => ['Florida']
);

try {
  $result = $apiInstance->listStories($opts);
  print_r($result);
} catch (Exception $e) {
  echo 'Exception when calling DefaultApi->listStories: ', $e->getMessage(), PHP_EOL;
}
?>

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{
  SourceLocationsCountry:         optional.NewInterface([]string{"US"}),
  SourceLocationsState:           optional.NewInterface([]string{"Florida"}),
  PublishedAtStart:               optional.NewString("NOW-1MONTH"),
  PublishedAtEnd:                 optional.NewString("NOW"),
  CategoriesTaxonomy:             optional.NewString("iptc-subjectcode"),
  CategoriesId:                   optional.NewInterface([]string{"11000000"}),
  PerPage:                        optional.NewInt32(10),
  }

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

  if err != nil {
    panic(err)
  }

  _ = res

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

Based on Source Scope

Description

Source scope refers to the geographical regions a news source covers. For example, a news source might cover local, national or international news they might also only cover news related to a particular city, state or country. The source scope allows you to filter stories by scope.

Examples

The following example shows how to retrieve stories about business, are published by sources who cover London city, were published between 30 days ago and now and are sorted by their published at value.

from __future__ import print_function
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'
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))

params ={
'language': ['en'],
'published_at_start': 'NOW-30DAYS',
'published_at_end': 'NOW',
'sort_by': 'published_at',
'categories_taxonomy': 'iab-qag',
'categories_id': ['IAB3'],
'source_scopes_city': ['London']
}

try:
  # List stories
  api_response = api_instance.list_stories(**params)
  print(api_response)
except ApiException as e:
  print("Exception when calling DefaultApi->list_stories: %sn" % 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_APP_ID'

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

api_instance = AylienNewsApi::DefaultApi.new

opts = {
  :title => "startup AND (raise OR raised OR raising OR raises)",
  :published_at_start => "NOW-30DAYS",
  :published_at_end => "NOW",
  :language => ['en'],
  :sort_by => 'published_at',
  :categories_taxonomy => 'iab-qag',
  :categories_id => ['IAB3'],
  :source_scopes_city => ['London']
}


begin
  #List stories
  result = api_instance.list_stories(opts)
  result.stories.each do |story|
    puts "#{story.title} / #{story.source.scopes}"
  end
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 = {
    'sortBy': 'published_at',
    'publishedAtStart': 'NOW-30DAYS',
    'publishedAtEnd': 'NOW',
    'sourceScopesCity': ['London'],
    'sourceScopesCountry': ['GB']
  };

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
      for (i=0; i < data.stories.length; i++){
    console.log(data.stories[i].source, data.stories[i].title);
      }
    }
};
apiInstance.listStories(opts, callback);

<?php
require_once(__DIR__ . '/vendor/autoload.php');


// Configure API key authorization: app_id
$config = Aylien\NewsApi\Configuration::getDefaultConfiguration()->setApiKey('X-AYLIEN-NewsAPI-Application-ID', 'YOUR_APP_ID');
// Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
// $config = Aylien\NewsApi\Configuration::getDefaultConfiguration()->setApiKeyPrefix('X-AYLIEN-NewsAPI-Application-ID', 'Bearer');

// Configure API key authorization: app_key
$config = Aylien\NewsApi\Configuration::getDefaultConfiguration()->setApiKey('X-AYLIEN-NewsAPI-Application-Key', 'YOUR_API_KEY');
// Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
// $config = Aylien\NewsApi\Configuration::getDefaultConfiguration()->setApiKeyPrefix('X-AYLIEN-NewsAPI-Application-Key', 'Bearer');


$apiInstance = new Aylien\NewsApi\Api\DefaultApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
    // This is optional, `GuzzleHttp\Client` will be used as default.
    new GuzzleHttp\Client(),
    $config
);

$opts = array(
  'published_at_start' => 'NOW-10DAYS',
  'published_at_end' => 'NOW',
  'language' => ['en'],
  'source_scopes_country' => ['GB'],
  'source_scopes_city' => ['London']
);

try {
  $result = $apiInstance->listStories($opts);
  print_r($result);
} catch (Exception $e) {
  echo 'Exception when calling DefaultApi->listStories: ', $e->getMessage(), PHP_EOL;
}
?>

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{
  SourceScopesCity:               optional.NewInterface([]string{"London"}),
  SourceScopesCountry:            optional.NewInterface([]string{"GB"}),
  Title:                          optional.NewString("restaurant"),
  PublishedAtStart:               optional.NewString("NOW-1MONTH"),
  PublishedAtEnd:                 optional.NewString("NOW"),
  PerPage:                        optional.NewInt32(10),
  }

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

  if err != nil {
    panic(err)
  }

  _ = res

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

Based on Mentioned Locations

Description

Mentioned Locations is used to identify when a location as a keyword or entity is mentioned in the title or body of a story.

Examples

The following example shows how to retrieve stories in English, are about Electrical Cars with San Francisco mentioned in their title, were published between 30 days ago and now and sorted by published at date time.

from __future__ import print_function
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'
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))

params = {
  'language':['en'],
  'published_at_start': 'NOW-30DAYS',
  'published_at_end': 'NOW',
  'sort_by': 'published_at',
  'categories_taxonomy': 'iab-qag',
  'categories_id': ['IAB2-10'],
  'entities_title_links_dbpedia': ['http://dbpedia.org/resource/San_Francisco']
}

try:
  # List stories
  api_response = api_instance.list_stories(**params)
  print(api_response)
except ApiException as e:
  print("Exception when calling DefaultApi->list_stories: %sn" % 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_APP_ID'

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

api_instance = AylienNewsApi::DefaultApi.new

opts = {
  :published_at_start => "NOW-30DAYS",
  :published_at_end => "NOW",
  :language => ['en'],
  :sort_by => 'published_at',
  :entities_title_links_dbpedia => ['http://dbpedia.org/resource/San_Francisco']
}


begin
  #List stories
  result = api_instance.list_stories(opts)
  result.stories.each do |story|
    puts story.title
    end
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 = {
  'sortBy': 'published_at',
  'entitiesTitleLinksDbpedia': [
    'http://dbpedia.org/resource/San_Francisco'
  ]
};

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else { 
      for (i=0; i < data.stories.length; i++){
        console.log(data.stories[i].title, data.stories[i].entities.title);
        }
    }
};
apiInstance.listStories(opts, callback);

<?php
require_once(__DIR__ . '/vendor/autoload.php');


// Configure API key authorization: app_id
$config = Aylien\NewsApi\Configuration::getDefaultConfiguration()->setApiKey('X-AYLIEN-NewsAPI-Application-ID', 'YOUR_APP_ID');
// Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
// $config = Aylien\NewsApi\Configuration::getDefaultConfiguration()->setApiKeyPrefix('X-AYLIEN-NewsAPI-Application-ID', 'Bearer');

// Configure API key authorization: app_key
$config = Aylien\NewsApi\Configuration::getDefaultConfiguration()->setApiKey('X-AYLIEN-NewsAPI-Application-Key', 'YOUR_API_KEY');
// Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
// $config = Aylien\NewsApi\Configuration::getDefaultConfiguration()->setApiKeyPrefix('X-AYLIEN-NewsAPI-Application-Key', 'Bearer');


$apiInstance = new Aylien\NewsApi\Api\DefaultApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
    // This is optional, `GuzzleHttp\Client` will be used as default.
    new GuzzleHttp\Client(),
    $config
);

$opts = array(
  'published_at_start' => 'NOW-10DAYS',
  'published_at_end' => 'NOW',
  'language' => ['en'],
  'entities_title_links_dbpedia' => ['http://dbpedia.org/resource/San_Francisco']
);

try {
  $result = $apiInstance->listStories($opts);
  print_r($result);
} catch (Exception $e) {
  echo 'Exception when calling DefaultApi->listStories: ', $e->getMessage(), PHP_EOL;
}
?>

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{
  EntitiesTitleLinksDbpedia:      optional.NewInterface([]string{"http://dbpedia.org/resource/San_Francisco"}),
  PublishedAtStart:               optional.NewString("NOW-1MONTH"),
  PublishedAtEnd:                 optional.NewString("NOW"),
  PerPage:                        optional.NewInt32(10),
  }

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

  if err != nil {
    panic(err)
  }

  _ = res

  for _, story := range storiesResponse.Stories {
    fmt.Println(story.Title)
  }
}

Working with Languages

The News API offers content in 16 languages, and searching for stories in these languages is done by supplying the langauge of your choice to the 'language' parameter.

It is strongly recommended that you always supply a language parameter in your search, no matter how many languages you want to search across. If you do not supply the language parameter, your search will default to all languages, but without the necessary language-specific filters like stop word removal and stemming. This could result in your search not retrieve all of the stories that are relevant to your query.

Taxonomies

Our classifier is capable of classifying content into two taxonomies. Below is a list of these taxonomies and their definitions, and you can browse each taxonomy here.

Taxonomy	Supported Languages	Number of classes	Levels of depth	Commonly used for	Taxonomy ID	JSON
IPTC Subject Codes	en	1400	3	News articles, Blog posts	`iptc-subjectcode`	View
IAB QAG	en	392	2	Websites, Advertisement (e.g. in OpenRTB, details)	`iab-qag`	View

Traversing Taxonomies

Our supported taxonomies are made up of categories and subcategories, or parent categories and child categories, for example with Football being a child category of Sport.

We have standardized all our of our supported taxonomies into a tree-like structure, which allows you to easily traverse from child categories to parent categories, recursively.

Examples

The following example shows articles that are in English, are about Science and were published between 1 day ago and now.

from __future__ import print_function
import aylien_news_api
from aylien_news_api.rest import ApiException

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

params = {
  'categories_taxonomy': 'iab-qag',
  'categories_id': ['IAB15'],
  'language': ['en'],
  'published_at_start': 'NOW-1DAY',
  'published_at_end': 'NOW'
}

try:
    # List stories
    api_response = api_instance.list_stories(**params)
    print('The API has been called successfully.')
    print('=====================================')
    for story in api_response.stories:
      print(story.title + " / " + story.source.name)
except ApiException as e:
    print("Exception when calling DefaultApi->list_stories: %sn" % 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_APP_ID'

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

api_instance = AylienNewsApi::DefaultApi.new

opts = {
  :categories_taxonomy => 'iab-qag',
  :categories_id => ['IAB15'],
  :language => ['en'],
  :published_at_start => "NOW-1DAY",
  :published_at_end => "NOW"
}


begin
  #List stories
  result = api_instance.list_stories(opts)

  puts 'The API has been called successfully.'
  puts '====================================='
  result.stories.each do |story|
    puts "#{story.title} / #{story.source.name}"
  end
rescue AylienNewsApi::ApiError => e
  puts "Exception when calling DefaultApi->list_stories: #{e}"
  puts e.response_body
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 = {
  'categoriesTaxonomy': 'iab-qag',
  'categoriesId': ['IAB15'],
  'language': ['en'],
  'publishedAtStart': 'NOW-1DAY',
  'publishedAtEnd': 'NOW'
};

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('The API has been called successfully.');
    console.log('=====================================');
    for (var i = 0; i < data.stories.length; i++){
      console.log(data.stories[i].title + " / " + data.stories[i].source.name);
    }
  }
};
apiInstance.listStories(opts, callback);

<?php
require_once(__DIR__ . '/vendor/autoload.php');

// Configure API key authorization: app_id
$config = Aylien\NewsApi\Configuration::getDefaultConfiguration()->setApiKey('X-AYLIEN-NewsAPI-Application-ID', 'YOUR_APP_ID');
// Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
// $config = Aylien\NewsApi\Configuration::getDefaultConfiguration()->setApiKeyPrefix('X-AYLIEN-NewsAPI-Application-ID', 'Bearer');

// Configure API key authorization: app_key
$config = Aylien\NewsApi\Configuration::getDefaultConfiguration()->setApiKey('X-AYLIEN-NewsAPI-Application-Key', 'YOUR_API_KEY');
// Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
// $config = Aylien\NewsApi\Configuration::getDefaultConfiguration()->setApiKeyPrefix('X-AYLIEN-NewsAPI-Application-Key', 'Bearer');


$apiInstance = new Aylien\NewsApi\Api\DefaultApi(
    new GuzzleHttp\Client(),
    $config
);

$opts = array(
  'published_at_start' => 'NOW-10DAYS',
  'published_at_end' => 'NOW',
  'language' => ['en'],
  'categories_taxonomy' => 'iab-qag',
  'categories_id' => ['IAB15']
);

try {
  $result = $apiInstance->listStories($opts);
  print_r($result);
} catch (Exception $e) {
  echo 'Exception when calling DefaultApi->listStories: ', $e->getMessage(), PHP_EOL;
}
?>

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{
    PublishedAtStart:               optional.NewString("NOW-1MONTH"),
    PublishedAtEnd:                 optional.NewString("NOW"),
    CategoriesTaxonomy:             optional.NewString("iab-qag"),
    CategoriesId:                   optional.NewInterface([]string{"IAB15"}),
    PerPage:                        optional.NewInt32(10),
  }

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

  if err != nil {
    panic(err)
  }

  _ = res

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

Media Elements

Many stories contain media such as images or videos as well as text, which can be valuable to some users, depending on what they are building. Some users are only interested in stories with video content to increase click through rate, whereas other users do not want videos in their results if they are concerned with the end-user's loading time, as videos take slightly longer to load on poorer connections.

The News API allows you to:

Specify whether your results should include these media or not
Specify the amount of images or videos your results should include (this can be an exact number, a range, or a minimum or maximum)
Sort your results according to how many images or videos they contain
Specify the format of the media in your stories
Display quantitative trends in media with the histograms endpoint

Specifying the amount of media in stories

It is possible to specify whether the stories returned by your query should contain media or not, and also to specify the number of images and videos in each story by using the media.images.count or the media.videos.count parameter.

By setting media.images.count.min to 1, you are specifying that your query only return stories with at least one image.
By setting media.videos.count.min to 1, and media.videos.count.max also to 1, you are specifying that you only want results that contain exactly one video.
By setting media.videos.count.max to 0, you are excluding any stories with videos from your results.

Sorting by media count

To display stories with more images before stories with fewer images in your results, set the sort_by parameter to media.images.count, and the sort_direction parameter to desc. Whenever you use the sort_by parameter, the sort direction will automatically be in descending order (i.e. stories with the most results in the parameter will be shown first). In order to reverse this default, set the sort_by parameter to asc, which will sort the results in ascending order.

Media format & size

It is possible to return or exclude stories that contain images in a specified format, by using the media.images.format[] parameter. These can help avoid any technical issues you can foresee with these formats.

The image formats you can use as a parameter are:

BMP
GIF
JPEG
PNG
TIFF
PSD
ICO
CUR
WEBP
SVG

It is also possible to specify maximum and minimum height, width, and content length by appending .min or .max to the following parameters:

media.images.width
media.images.height
media.images.content_length

Examples

The code below gathers stories that mention fitness with exactly one video and no GIF images from the last month.

from __future__ import print_function
import aylien_news_api
from aylien_news_api.rest import ApiException
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'
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))

params = {
  'categories_taxonomy': 'iab-qag',
  'categories_id': ['IAB7'],
  'text': 'fitness',
  'language': ['en'],
  'media_videos_count_min': 1,
  'media_videos_count_max': 1,
  'not_media_images_format': ['GIF'],
  'published_at_start': 'NOW-1MONTH',
  'published_at_end': 'NOW',
  'sort_by': 'relevance'
}

try:
    # List stories
    api_response = api_instance.list_stories(**params)
    print('The API has been called successfully.')
    print('=====================================')
    for story in api_response.stories:
      print(story.title + " / " + story.source.name)
except ApiException as e:
    print("Exception when calling DefaultApi->list_stories: %sn" % 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_APP_ID'

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

api_instance = AylienNewsApi::DefaultApi.new

opts = {
  :categories_taxonomy => 'iab-qag',
  :categories_id => ['IAB7'],
  :text => 'fitness',
  :language => ['en'],
  :media_videos_count_min => 1,
  :media_videos_count_max => 1,
  :not_media_images_format => ['GIF'],
  :published_at_start => "NOW-1MONTH",
  :published_at_end => "NOW",
  :sort_by => 'relevance'
}


begin
  #List stories
  result = api_instance.list_stories(opts)

  puts 'The API has been called successfully.'
  puts '====================================='
  result.stories.each do |story|
    puts "#{story.title} / #{story.media}"
  end
rescue AylienNewsApi::ApiError => e
  puts "Exception when calling DefaultApi->list_stories: #{e}"
  puts e.response_body
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 = {
  'categoriesTaxonomy': 'iab-qag',
  'categoriesId': ['IAB7'],
  'text': 'fitness',
  'language': ['en'],
  'mediaVideosCountMin': 1,
  'mediaVideosCountMax': 1,
  'notMediaImagesFormat': ['GIF'],
  'publishedAtStart': 'NOW-1MONTH',
  'publishedAtEnd': 'NOW',
  'sortBy': 'relevance'
};

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('The API has been called successfully.');
    console.log('=====================================');
    for (var i = 0; i < data.stories.length; i++){
      console.log(data.stories[i].title, data.stories[i].media);
    }
  }
};
apiInstance.listStories(opts, callback);

<?php
require_once(__DIR__ . '/vendor/autoload.php');

// Configure API key authorization: app_id
$config = Aylien\NewsApi\Configuration::getDefaultConfiguration()->setApiKey('X-AYLIEN-NewsAPI-Application-ID', 'YOUR_APP_ID');
// Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
// $config = Aylien\NewsApi\Configuration::getDefaultConfiguration()->setApiKeyPrefix('X-AYLIEN-NewsAPI-Application-ID', 'Bearer');

// Configure API key authorization: app_key
$config = Aylien\NewsApi\Configuration::getDefaultConfiguration()->setApiKey('X-AYLIEN-NewsAPI-Application-Key', 'YOUR_API_KEY');
// Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
// $config = Aylien\NewsApi\Configuration::getDefaultConfiguration()->setApiKeyPrefix('X-AYLIEN-NewsAPI-Application-Key', 'Bearer');


$apiInstance = new Aylien\NewsApi\Api\DefaultApi(
    new GuzzleHttp\Client(),
    $config
);


$opts = array(
  'text' => 'fitness',
  'language' => ['en'],
  'media_videos_count_min' => 1,
  'media_videos_count_max' => 1,
  'published_at_start' => 'NOW-1MONTH',
  'published_at_end' => 'NOW',
  'sort_by' => 'relevance',
  'return' => 'media'
);

try {
    $result = $apiInstance->listStories($opts);
    print_r("The API has been called successfully.\n");
    print_r("=====================================\n");
    for($i = 0; $i < sizeof($result->getStories()); $i++){
      print_r($result->getStories()[$i]);
    }
} catch (Exception $e) {
    print_r($e->getResponseObject()->getErrors());
    echo 'Exception when calling DefaultApi->listStories: ', $e->getMessage(), "\n";
}
?>

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{
  Title:                          optional.NewString("fitness"),
  MediaImagesCountMin:            optional.NewInt32(1),
  MediaVideosCountMax:            optional.NewInt32(1),
  PublishedAtStart:               optional.NewString("NOW-1MONTH"),
  PublishedAtEnd:                 optional.NewString("NOW"),
  PerPage:                        optional.NewInt32(10),
  }

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

  if err != nil {
    panic(err)
  }

  _ = res

  for _, story := range storiesResponse.Stories {
    fmt.Println(story.Title, "\n\n ", story.Media)
  }
}

Alexa Rankings

The Alexa traffic rank is an estimate of a site's popularity on the internet. It is determined by measuring the volume of traffic a site gets over a rolling 3 month period. The Alexa rank is a scale of 0-50,000+. Sites with a lower Alexa rank will have higher volumes of traffic. For example, Google has an Alexa rank of 1.

Alexa can provide a rank for a website based on traffic volume from the entire world or based on traffic volume from any single nation you input.

Global ranking, based on how popular a website is globally
National ranking, based on how popular a site is in a given country. This is available for every country in the world, and is accessed by adding the ISO 3166-1 alpha-2 country code to your parameter.

Examples

The following example shows articles that are in English, are about Science, that published by sources with an Alexa rank between 25 and 100 and were published between 1 day ago and now.

from __future__ import print_function
import aylien_news_api
from aylien_news_api.rest import ApiException
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'
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 = {
  'language': ['en'],
  'published_at_start': 'NOW-1DAY',
  'published_at_end': 'NOW',
  'categories_taxonomy': 'iab-qag',
  'categories_id': ['IAB15'],
  'source_rankings_alexa_rank_min': 25,
  'source_rankings_alexa_rank_max': 100
}

try:
    # List stories
    api_response = api_instance.list_stories(**opts)
    print(api_response)
except ApiException as e:
    print("Exception when calling DefaultApi->list_stories: %sn" % 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_APP_ID'

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

api_instance = AylienNewsApi::DefaultApi.new

opts = {
  :published_at_start => "NOW-1DAY",
  :published_at_end => "NOW",
  :language => ["en"],
  :categories_taxonomy => "iab-qag",
  :categories_id => ["IAB15"],
  :source_rankings_alexa_rank_min => 25,
  :source_rankings_alexa_rank_max => 100
}


begin
  #List stories
  result = api_instance.list_stories(opts)
  puts 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_KEY';
// 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 = {
  'language': ['en'],
  'publishedAtStart': 'NOW-1DAY',
  'publishedAtEnd': 'NOW',
  'categoriesTaxonomy': 'iab-qag',
  'categoriesId': ['IAB15'],
  'sourceRankingsAlexaRankMin': 25,
  'sourceRankingsAlexaRankMax': 100
};

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    for (i=0; i < data.stories.length; i++){
        console.log('Title: ' + data.stories[i].title);
        console.log(data.stories[i].source);
        console.log('-------------------------');
          }
  }
};
apiInstance.listStories(opts, callback);

<?php
require_once(__DIR__ . '/vendor/autoload.php');

// Configure API key authorization: app_id
$config = Aylien\NewsApi\Configuration::getDefaultConfiguration()->setApiKey('X-AYLIEN-NewsAPI-Application-ID', 'YOUR_APP_ID');
// Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
// $config = Aylien\NewsApi\Configuration::getDefaultConfiguration()->setApiKeyPrefix('X-AYLIEN-NewsAPI-Application-ID', 'Bearer');

// Configure API key authorization: app_key
$config = Aylien\NewsApi\Configuration::getDefaultConfiguration()->setApiKey('X-AYLIEN-NewsAPI-Application-Key', 'YOUR_API_KEY');
// Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
// $config = Aylien\NewsApi\Configuration::getDefaultConfiguration()->setApiKeyPrefix('X-AYLIEN-NewsAPI-Application-Key', 'Bearer');


$apiInstance = new Aylien\NewsApi\Api\DefaultApi(
    new GuzzleHttp\Client(),
    $config
);


$opts = array(
  'published_at_start' => 'NOW-1DAY',
  'published_at_end' => 'NOW',
  'language' => ['en'],
  'categories_taxonomy' => 'iab-qag',
  'categories_id' => ['IAB15'],
  'source_rankings_alexa_rank_min' => 25,
  'source_rankings_alexa_rank_max' => 100,
  'return' => ['title', 'source']
);

try {
    $result = $apiInstance->listStories($opts);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling DefaultApi->listStories: ', $e->getMessage(), "\n";
}
?>

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{
  SourceRankingsAlexaRankMin:     optional.NewInt32(100),
  SourceRankingsAlexaRankMax:     optional.NewInt32(200),
  CategoriesTaxonomy:             optional.NewString("iab-qag"),
  CategoriesId:                   optional.NewInterface([]string{"IAB17"}),
  PublishedAtStart:               optional.NewString("NOW-1MONTH"),
  PublishedAtEnd:                 optional.NewString("NOW"),
  PerPage:                        optional.NewInt32(10),
  }

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

  if err != nil {
    panic(err)
  }

  _ = res

  for _, story := range storiesResponse.Stories {
    fmt.Println(story.Title, "\n\n ", story.Source)
  }
}

Working with Links In Count

The links in count is an estimate of the number of sites linking in, or backlinking, to a website. Generally sites with higher links in counts have more authority and higher traffic.

Examples

The following example shows articles that are in English, are about Science, that published by sources with back linking count between 100000 and 200000 and were published between 1 day ago and now.

from __future__ import print_function
import aylien_news_api
from aylien_news_api.rest import ApiException
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'
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))

params ={
  'language': ['en'],
  'published_at_start': 'NOW-1DAY',
  'published_at_end': 'NOW',
  'categories_taxonomy': 'iab-qag',
  'categories_id': ['IAB15'],
  'source_links_in_count_min': 100000,
  'source_links_in_count_max': 200000
}

try:
    # List stories
    api_response = api_instance.list_stories(**params)
    print(api_response)
except ApiException as e:
    print("Exception when calling DefaultApi->list_stories: %sn" % 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_APP_ID'

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

api_instance = AylienNewsApi::DefaultApi.new

opts = {
  :published_at_start => "NOW-1DAY",
  :published_at_end => "NOW",
  :language => ["en"],
  :categories_taxonomy => "iab-qag",
  :categories_id => ["IAB15"],
  :source_links_in_count_min => 100000,
  :source_links_in_count_max => 200000
}


begin
  #List stories
  result = api_instance.list_stories(opts)
  puts 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 = {
  'language': ['en'],
  'publishedAtStart': 'NOW-15DAYS',
  'publishedAtEnd': 'NOW',
  'sourceLinksInCountMin': 10000
};

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

<?php
require_once(__DIR__ . '/vendor/autoload.php');


// Configure API key authorization: app_id
$config = Aylien\NewsApi\Configuration::getDefaultConfiguration()->setApiKey('X-AYLIEN-NewsAPI-Application-ID', 'YOUR_APP_ID');
// Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
// $config = Aylien\NewsApi\Configuration::getDefaultConfiguration()->setApiKeyPrefix('X-AYLIEN-NewsAPI-Application-ID', 'Bearer');

// Configure API key authorization: app_key
$config = Aylien\NewsApi\Configuration::getDefaultConfiguration()->setApiKey('X-AYLIEN-NewsAPI-Application-Key', 'YOUR_API_KEY');
// Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
// $config = Aylien\NewsApi\Configuration::getDefaultConfiguration()->setApiKeyPrefix('X-AYLIEN-NewsAPI-Application-Key', 'Bearer');


$apiInstance = new Aylien\NewsApi\Api\DefaultApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
    // This is optional, `GuzzleHttp\Client` will be used as default.
    new GuzzleHttp\Client(),
    $config
);


$opts = array(
  'published_at_start' => 'NOW-1DAY',
  'published_at_end' => 'NOW',
  'language' => ['en'],
  'categories_taxonomy' => 'iab-qag',
  'categories_id' => ['IAB15'],
  'source_links_in_count_max' => 10000,
  'source_links_in_count_min' => 100
);

try {
    $result = $apiInstance->listStories($opts);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling DefaultApi->listStories: ', $e->getMessage(), "\n";
}
?>

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{
  SourceLinksInCountMin:          optional.NewInt32(100),
  SourceLinksInCountMax:          optional.NewInt32(200),
  CategoriesTaxonomy:             optional.NewString("iab-qag"),
  CategoriesId:                   optional.NewInterface([]string{"IAB17"}),
  PublishedAtStart:               optional.NewString("NOW-1MONTH"),
  PublishedAtEnd:                 optional.NewString("NOW"),
  PerPage:                        optional.NewInt32(10),
  }

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

  if err != nil {
    panic(err)
  }

  _ = res

  for _, story := range storiesResponse.Stories {
    fmt.Println(story.Title, "\n\n ", story.Source)
  }
}