The News API can be used in a variety of ways. We’ve put together some sample workflows with handy code snippets to help you get up and running quickly. Scroll through the full list on the left or jump to some of the most-used workflows below.
Working with Multilingual Content
Working with Source Locations
Retrieving +100 Stories at Once
Real-time Monitoring
Working with Entities
Adding Booleans to Your Search
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 based on the real-world events they talk about. Clustering is only accessible to News API users with an Enterprise plan. Contact our sales team to upgrade or test the feature out.
How can I work with clusters on the Aylien News API?
A description of how to retrieve clusters and use the clusters endpoint is provided below.
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 associated with it.
A cluster has the following properties:
- Each cluster has a unique ID in the News API
- 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.
Most stories will be clustered in the minutes after they have been ingested by the News API.
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)
}
}
using System;
using Aylien.NewsApi.Api;
using Aylien.NewsApi.Client;
using Aylien.NewsApi.Model;
namespace RetrievingClustersExample
{
class Program
{
static void Main(string[] args)
{
Configuration.Default.BasePath = "https://api.aylien.com/news";
// Configure API key authorization: app_id
Configuration.Default.AddApiKey("X-AYLIEN-NewsAPI-Application-ID", "YOUR_APP_ID");
// Configure API key authorization: app_key
Configuration.Default.AddApiKey("X-AYLIEN-NewsAPI-Application-Key", "YOUR_API_KEY");
var apiInstance = new DefaultApi();
try
{
// List Stories
Clusters clustersResponse = apiInstance.ListClusters(
timeEnd: "NOW-6HOURS",
storyCountMin: 10
);
Console.WriteLine("The API has been called successfully.");
Console.WriteLine("=====================================");
Console.OutputEncoding = System.Text.Encoding.UTF8;
foreach (var cluster in clustersResponse._Clusters)
{
Console.WriteLine(string.Format("{0} [{1} stories] / {2}", cluster.Location.Country, cluster.StoryCount, cluster.RepresentativeStory.Title));
}
}
catch (Exception e)
{
Console.WriteLine("Exception when calling DefaultApi.ListClusters: " + e.Message);
}
}
}
}
package com.example;
import com.aylien.newsapi.ApiClient;
import com.aylien.newsapi.ApiException;
import com.aylien.newsapi.Configuration;
import com.aylien.newsapi.api.DefaultApi;
import com.aylien.newsapi.auth.*;
import com.aylien.newsapi.models.*;
import java.util.*;
public class Main {
public static void main(String[] args) {
ApiClient defaultClient = Configuration.getDefaultApiClient();
defaultClient.setBasePath("https://api.aylien.com/news/");
// Configure API key authorization: app_id
ApiKeyAuth app_id = (ApiKeyAuth)defaultClient.getAuthentication("app_id");
app_id.setApiKey("YOUR_APP_ID");
// Configure API key authorization: app_key
ApiKeyAuth app_key = (ApiKeyAuth)defaultClient.getAuthentication("app_key");
app_key.setApiKey("YOUR_API_KEY");
DefaultApi apiInstance = new DefaultApi(defaultClient);
Integer storyCountMin = 10;
String timeStart = "NOW-1DAY";
List<String> locationCountry = Arrays.asList("IE");
try {
Clusters result = apiInstance.listClusters()
.storyCountMin(storyCountMin)
.timeStart(timeStart)
.locationCountry(locationCountry)
.execute();
System.out.println(result);
} catch (ApiException e) {
System.err.println("Exception when calling DefaultApi#listClusters");
System.err.println("Status code: " + e.getCode());
System.err.println("Reason: " + e.getResponseBody());
System.err.println("Response headers: " + e.getResponseHeaders());
e.printStackTrace();
}
}
}
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;
}
};
using System;
using System.Linq;
using Aylien.NewsApi.Api;
using Aylien.NewsApi.Client;
using Aylien.NewsApi.Model;
using System.Collections.Generic;
namespace RetrievingClustersWithTrendsExample
{
class Program
{
static DefaultApi apiInstance;
class ClusterMetaData
{
internal long ClusterId { get; set; }
internal RepresentativeStory RepresentativeStory { get; set; }
internal int StoryCount { get; set; }
internal List<Story> Stories { get; set; }
internal DateTime Time { get; set; }
}
static void Main(string[] args)
{
apiInstance = new DefaultApi();
Configuration.Default.BasePath = "https://api.aylien.com/news";
// Configure API key authorization: app_id
Configuration.Default.AddApiKey("X-AYLIEN-NewsAPI-Application-ID", "YOUR_APP_ID");
// Configure API key authorization: app_key
Configuration.Default.AddApiKey("X-AYLIEN-NewsAPI-Application-Key", "YOUR_API_KEY");
try
{
List<string> clusterIds = GetClusterFromTrends();
foreach (string clusterId in clusterIds)
{
ClusterMetaData metaData = GetClusterMetaData(long.Parse(clusterId));
if (metaData != null)
{
metaData.Stories = GetTopStories(long.Parse(clusterId));
Console.WriteLine(string.Format("{0} {1} [{2}] - {3}", metaData.ClusterId, metaData.Time, metaData.StoryCount, metaData.RepresentativeStory));
}
else
{
Console.WriteLine(clusterId + " is empty") ;
}
}
}
catch (Exception e)
{
Console.WriteLine("Exception when calling DefaultApi: " + e.Message);
}
}
static List<string> GetClusterFromTrends()
{
// Returns a list of up to 100 clusters that meet the parameters set out.
Trends response = apiInstance.ListTrends(
field:"clusters",
categoriesTaxonomy: "iptc-subjectcode",
categoriesId: new List<string> { "11000000" },
publishedAtEnd: "NOW-12HOURS",
entitiesTitleLinksDbpedia: new List<string> { "http://dbpedia.org/resource/United_States_Congress" }
);
return response._Trends.Select(s => s.Value).ToList();
}
static ClusterMetaData GetClusterMetaData(long clusterId)
{
// Returns the representative story, number of stories, and time value for a given cluster
Clusters response = apiInstance.ListClusters(
id: new List<long> { clusterId }
);
List<Cluster> clusters = response._Clusters;
if (clusters == null || clusters.Count == 0)
return null;
Cluster firstCluster = clusters[0];
return new ClusterMetaData {
ClusterId = firstCluster.Id,
RepresentativeStory = firstCluster.RepresentativeStory,
StoryCount = firstCluster.StoryCount,
Time = firstCluster.Time
};
}
static List<Story> GetTopStories(long clusterId)
{
// Returns 3 stories associated with the cluster from the highest-ranking publishers
Stories response = apiInstance.ListStories(
clusters: new List<string> { clusterId.ToString() },
sortBy: "source.rankings.alexa.rank.US",
perPage: 3
);
return response._Stories;
}
}
}
package com.example;
import java.util.ArrayList;
import java.util.Iterator;
import java.util.List;
import com.aylien.newsapi.ApiClient;
import com.aylien.newsapi.ApiException;
import com.aylien.newsapi.Configuration;
import com.aylien.newsapi.api.DefaultApi;
import com.aylien.newsapi.auth.*;
import com.aylien.newsapi.models.*;
public class Main {
public static void main(String[] args) {
ApiClient defaultClient = Configuration.getDefaultApiClient();
defaultClient.setBasePath("https://api.aylien.com/news/");
// Configure API key authorization: app_id
ApiKeyAuth app_id = (ApiKeyAuth)defaultClient.getAuthentication("app_id");
app_id.setApiKey("YOUR_APP_ID");
// Configure API key authorization: app_key
ApiKeyAuth app_key = (ApiKeyAuth)defaultClient.getAuthentication("app_key");
app_key.setApiKey("YOUR_API_KEY");
DefaultApi apiInstance = new DefaultApi(defaultClient);
String title = "Trump";
String publishedAtStart = "NOW-10DAYS";
String publishedAtEnd = "NOW-3DAYS";
for (Long clusterId : retrieveTrends(apiInstance, title, publishedAtStart, publishedAtEnd)) {
System.out.println(getClusterMetadata(apiInstance, clusterId));
try {
Thread.sleep(1000);
}
catch(InterruptedException ex) {
Thread.currentThread().interrupt();
}
}
}
public static List<Long> retrieveTrends(DefaultApi apiInstance, String title, String publishedAtStart, String publishedAtEnd) {
List<Long> clusters = new ArrayList();
String field = "clusters";
try {
Trends result = apiInstance.listTrends(field)
.title(title)
.publishedAtStart(publishedAtStart)
.publishedAtEnd(publishedAtEnd)
.execute();
System.out.println(result);
for (Iterator i = result.getTrends().iterator(); i.hasNext();) {
Trend trend = (Trend)i.next();
clusters.add(Long.valueOf(trend.getValue()));
}
} catch (ApiException e) {
System.out.println(e);
switch (e.getCode()) {
case 429:
System.out.println("Usage limit are exceeded. Wating for 60 seconds...");
try {
Thread.sleep(1000 * 60);
} catch (InterruptedException ex) {
ex.printStackTrace();
}
break;
case 401:
System.out.println("Unauthorized api call. Have you set your api id and key?");
default:
System.out.printf("Error code: %s%n", e.getCode());
}
}
return clusters;
}
public static List<Cluster> getClusterMetadata(DefaultApi apiInstance, Long clusterId) {
// below again, a couple of lines to transform a type. should I do something different?
List<Long> clusters = new ArrayList<>();
clusters.add(clusterId);
System.out.println(clusters);
List<Cluster> clusterMetadata = new ArrayList<>();
try {
Clusters result = apiInstance.listClusters()
.id(clusters)
.execute();
if (result.getClusters().size() > 0) {
clusterMetadata.add(result.getClusters().get(0));
} else {
System.out.println("Cluster not found.");
}
} catch (ApiException e) {
System.out.println(e);
switch (e.getCode()) {
case 429:
System.out.println("Usage limits are exceeded. Waiting for 60 seconds...");
try {
Thread.sleep(1000 * 60);
} catch (InterruptedException ex) {
ex.printStackTrace();
}
break;
case 401:
System.out.println("Unauthorized api call. Have you set your api id and key?");
default:
System.out.printf("Error code: %s%n", e.getCode());
}
}
return clusterMetadata;
}
}
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);
?>
using System;
using System.Linq;
using Aylien.NewsApi.Api;
using Aylien.NewsApi.Client;
using Aylien.NewsApi.Model;
using System.Collections.Generic;
namespace RetrievingClustersFromStories
{
class Program
{
static DefaultApi apiInstance;
class ClusteredStories
{
internal long Cluster { get; set; }
internal List<string> Stories { get; set; }
}
static void Main(string[] args)
{
apiInstance = new DefaultApi();
Configuration.Default.BasePath = "https://api.aylien.com/news";
// Configure API key authorization: app_id
Configuration.Default.AddApiKey("X-AYLIEN-NewsAPI-Application-ID", "YOUR_APP_ID");
// Configure API key authorization: app_key
Configuration.Default.AddApiKey("X-AYLIEN-NewsAPI-Application-Key", "YOUR_API_KEY");
try
{
List<Story> stories = GetStories();
List<ClusteredStories> ClusteredStories = new List<ClusteredStories>();
foreach (Story story in stories)
{
if (story.Clusters.Count > 0)
{
long cluster = story.Clusters[0];
ClusteredStories ClusteredStory = ClusteredStories.FirstOrDefault(w => w.Cluster == cluster);
if (ClusteredStory == null)
{
ClusteredStories.Add(new ClusteredStories
{
Cluster = cluster,
Stories = new List<string> { story.Title }
}); ;
}
else
{
ClusteredStory.Stories.Add(story.Title);
}
}
}
foreach (ClusteredStories clusteredStory in ClusteredStories)
{
Console.WriteLine(string.Format("{0} [{1}] - {2}", clusteredStory.Cluster, clusteredStory.Stories.Count, clusteredStory.Stories[0]));
}
}
catch (Exception e)
{
Console.WriteLine("Exception when calling DefaultApi.ListStories: " + e.Message);
}
}
static List<Story> GetStories()
{
// Returns a list of up to 100 clusters that meet the parameters set out.
Stories response = apiInstance.ListStories(
title:"Liverpool",
publishedAtStart: "NOW-7DAYS",
perPage: 100
);
return response._Stories;
}
}
}
package com.example;
import java.util.Arrays;
import java.util.ArrayList;
import java.util.Iterator;
import java.util.List;
import java.util.HashMap;
import com.aylien.newsapi.ApiClient;
import com.aylien.newsapi.ApiException;
import com.aylien.newsapi.Configuration;
import com.aylien.newsapi.api.DefaultApi;
import com.aylien.newsapi.auth.ApiKeyAuth;
import com.aylien.newsapi.models.Stories;
import com.aylien.newsapi.models.Story;
public class Main {
public static void main(String[] args) {
ApiClient defaultClient = Configuration.getDefaultApiClient();
defaultClient.setBasePath("https://api.aylien.com/news/");
// Configure API key authorization: app_id
ApiKeyAuth app_id = (ApiKeyAuth)defaultClient.getAuthentication("app_id");
app_id.setApiKey("YOUR_APP_ID");
// Configure API key authorization: app_key
ApiKeyAuth app_key = (ApiKeyAuth)defaultClient.getAuthentication("app_key");
app_key.setApiKey("YOUR_API_KEY");
DefaultApi apiInstance = new DefaultApi(defaultClient);
List<String> language = Arrays.asList("en");
String publishedAtStart = "NOW-1MONTH";
String publishedAtEnd = "NOW-3HOURS";
List<String> entitiesTitleLinksDbpedia = Arrays.asList("http://dbpedia.org/resource/Baseball");
String sortBy = "published_at";
Integer perPage = 100;
HashMap<Long, List> clusterMap = new HashMap();
try {
Stories result = apiInstance.listStories()
.entitiesTitleLinksDbpedia(entitiesTitleLinksDbpedia)
.language(language)
.publishedAtStart(publishedAtStart)
.publishedAtEnd(publishedAtEnd)
.sortBy(sortBy)
.perPage(perPage)
.execute();
for (Iterator i = result.getStories().iterator(); i.hasNext();) {
Story story = (Story)i.next();
if ( story.getClusters().size() > 0){
if (clusterMap.containsKey( story.getClusters().get(0)) ) {
clusterMap.get(story.getClusters().get(0)).add(story.getTitle());
} else {
Long cluster = story.getClusters().get(0);
List storyList = new ArrayList();
storyList.add(story.getTitle());
clusterMap.put(cluster, storyList);
}
}
}
} catch (ApiException e) {
System.out.println(e);
switch (e.getCode()) {
case 429:
System.out.println("Usage limit are exceeded. Wating for 60 seconds...");
try {
Thread.sleep(1000 * 60);
} catch (InterruptedException ex) {
ex.printStackTrace();
}
break;
case 401:
System.out.println("Unauthorized api call. Have you set your api id and key?");
default:
System.out.printf("Error code: %s%n", e.getCode());
}
}
for (HashMap.Entry<Long, List> entry : clusterMap.entrySet()) {
System.out.println(entry.getKey() + " / " + entry.getValue());
}
}
}
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;
}
?>
using System;
using Aylien.NewsApi.Api;
using Aylien.NewsApi.Client;
using Aylien.NewsApi.Model;
using System.Collections.Generic;
namespace MultilingualExample
{
class Program
{
static void Main(string[] args)
{
Configuration.Default.BasePath = "https://api.aylien.com/news";
// Configure API key authorization: app_id
Configuration.Default.AddApiKey("X-AYLIEN-NewsAPI-Application-ID", "YOUR_APP_ID");
// Configure API key authorization: app_key
Configuration.Default.AddApiKey("X-AYLIEN-NewsAPI-Application-Key", "YOUR_API_KEY");
var apiInstance = new DefaultApi();
try
{
// List Stories
Stories storiesResponse = apiInstance.ListStories(
title: "Путин",
language: new List<string> { "ru" },
publishedAtStart: "NOW-1MONTH/DAY",
publishedAtEnd: "NOW/DAY",
perPage: 3
);;
Console.WriteLine("The API has been called successfully.");
Console.WriteLine("=====================================");
Console.OutputEncoding = System.Text.Encoding.UTF8;
foreach (var story in storiesResponse._Stories)
{
Console.WriteLine(string.Format("{0} - {1}", story.Title, story.Translations.En.Title));
}
}
catch (Exception e)
{
Console.WriteLine("Exception when calling DefaultApi.ListStories: " + e.Message);
}
}
}
}
package com.example;
import java.util.Arrays;
import java.util.Iterator;
import java.util.List;
import com.aylien.newsapi.ApiClient;
import com.aylien.newsapi.ApiException;
import com.aylien.newsapi.Configuration;
import com.aylien.newsapi.api.DefaultApi;
import com.aylien.newsapi.auth.ApiKeyAuth;
import com.aylien.newsapi.models.Stories;
import com.aylien.newsapi.models.Story;
public class Main {
public static void main(String[] args) {
ApiClient defaultClient = Configuration.getDefaultApiClient();
defaultClient.setBasePath("https://api.aylien.com/news/");
// Configure API key authorization: app_id
ApiKeyAuth app_id = (ApiKeyAuth)defaultClient.getAuthentication("app_id");
app_id.setApiKey("YOUR_APP_ID");
// Configure API key authorization: app_key
ApiKeyAuth app_key = (ApiKeyAuth)defaultClient.getAuthentication("app_key");
app_key.setApiKey("YOUR_API_KEY");
DefaultApi apiInstance = new DefaultApi(defaultClient);
String title = "Путин";
List<String> language = Arrays.asList("ru");
String publishedAtStart = "NOW-1MONTH/DAY";
String publishedAtEnd = "NOW/DAY";
Integer perPage = 3;
try {
Stories result = apiInstance.listStories()
.language(language)
.title(title)
.publishedAtStart(publishedAtStart)
.publishedAtEnd(publishedAtEnd)
.perPage(perPage)
.execute();
for (Iterator i = result.getStories().iterator(); i.hasNext();) {
Story story = (Story)i.next();
System.out.println(story.getTitle() + " / " + story.getTranslations().getEn().getTitle() );
}
} catch (ApiException e) {
System.out.println(e);
switch (e.getCode()) {
case 429:
System.out.println("Usage limit are exceeded. Wating for 60 seconds...");
try {
Thread.sleep(1000 * 60);
} catch (InterruptedException ex) {
ex.printStackTrace();
}
break;
case 401:
System.out.println("Unauthorized api call. Have you set your api id and key?");
default:
System.out.printf("Error code: %s%n", e.getCode());
}
}
}
}
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
);
Stories storiesResponse = apiInstance.ListStories(
title: "Путин",
translationsEnTitle: "business",
language: new List<string> { "ru" },
publishedAtStart: "NOW-10DAYS",
publishedAtEnd: "NOW",
perPage: 3
);
List<String> language = Arrays.asList("ru");
String title = "Путин";
String translationsEnTitle = "business";
String publishedAtStart = "NOW-1MONTH/DAY";
String publishedAtEnd = "NOW/DAY";
Integer perPage = 3;
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
);
Stories storiesResponse = apiInstance.ListStories(
title: "Путин",
translationsEnTitle: "Putin",
publishedAtStart: "NOW-1MONTH/DAY",
publishedAtEnd: "NOW/DAY",
perPage: 10
);
List<String> language = Arrays.asList("ru, en");
String title = "Путин";
String translationsEnTitle = "business";
String publishedAtStart = "NOW-1MONTH/DAY";
String publishedAtEnd = "NOW/DAY";
Integer perPage = 3;
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) |
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 retrieving all of the stories that are relevant to your query.
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 five minutes, 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 limits are exceeded. Waiting 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-5MINUTES',
'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 5 minutes until next poll...')
print('------------')
time.sleep(300)
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 limits are exceeded. Waiting 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-5MINUTES",
: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 5 minutes seconds until next poll..."
puts "------------\n\n"
sleep(300)
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 limits are exceeded. Waiting 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-5MINUTES',
'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 5 minutes seconds until next poll...");
console.log('------------- \n');
sleep(300 * 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 limits are exceeded. Waiting 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-5MINUTES',
'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 5 minutes seconds until next poll...\n");
print_r("-----------\n\n");
sleep(300);
}
?>
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 limits are exceeded. Waiting 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-5MINUTES"),
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)
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 5 minutes until next poll...")
fmt.Println("------------")
time.Sleep(time.Duration(300) * time.Second)
}
}
using System;
using Aylien.NewsApi.Api;
using Aylien.NewsApi.Client;
using Aylien.NewsApi.Model;
using System.Collections.Generic;
using System.Threading;
namespace RealTimeMonitoring
{
class Program
{
static DefaultApi apiInstance;
static void Main(string[] args)
{
Configuration.Default.BasePath = "https://api.aylien.com/news";
// Configure API key authorization: app_id
Configuration.Default.AddApiKey("X-AYLIEN-NewsAPI-Application-ID", "YOUR_APP_ID");
// Configure API key authorization: app_key
Configuration.Default.AddApiKey("X-AYLIEN-NewsAPI-Application-Key", "YOUR_API_KEY");
apiInstance = new DefaultApi();
var publishedAtStart = "NOW-5MINUTES";
var publishedAtEnd = "NOW";
while (true)
{
var stories = FetchNewStories(publishedAtStart, publishedAtEnd);
Console.WriteLine("*****************");
Console.WriteLine(string.Format("Fetched {0} stories which were published between {1} and {2}",
stories.Count, publishedAtStart, publishedAtEnd));
if (stories.Count > 0)
{
var lastFetchedAt = stories[0].PublishedAt.AddSeconds(1);
publishedAtStart = lastFetchedAt.ToString("yyyy-MM-ddTHH:mm:ssZ");
}
Console.WriteLine("Sleep for 5 minutes until next poll...");
Console.WriteLine("------------");
System.Threading.Thread.Sleep(1000 * 300);
}
}
static List<Story> FetchNewStories(String publishedAtStart, String publishedAtEnd)
{
Console.WriteLine("--------------------");
var cursor = "*";
List<Story> fetchedStories = new List<Story>();
List<Story> stories = null;
while (stories == null || stories.Count > 0)
{
try
{
var storiesResponse = apiInstance.ListStoriesWithHttpInfo(
title: "dublin",
language: new List<string> { "en" },
publishedAtStart: publishedAtStart,
publishedAtEnd: publishedAtEnd,
cursor: cursor,
perPage: 5,
sortBy: "published_at",
sortDirection: "desc"
);
stories = storiesResponse.Data._Stories;
cursor = storiesResponse.Data.NextPageCursor;
fetchedStories.AddRange(stories);
Console.WriteLine(string.Format("Fetched {0} stories. Total story count so far: {1}",
stories.Count, fetchedStories.Count));
}
catch (ApiException e)
{
if (e.ErrorCode == 429)
{
Console.WriteLine("Usage limits are exceeded. Waiting for 60 seconds...");
Thread.Sleep(1000 * 60);
}
else
{
Console.WriteLine("Exception when calling DefaultApi.ListStories: " + e.Message);
}
}
}
return fetchedStories;
}
}
}
package com.example;
import com.aylien.newsapi.ApiClient;
import com.aylien.newsapi.ApiException;
import com.aylien.newsapi.Configuration;
import com.aylien.newsapi.api.DefaultApi;
import com.aylien.newsapi.auth.*;
import com.aylien.newsapi.models.*;
import java.util.*;
import org.threeten.bp.OffsetDateTime;
public class Main {
public static void main(String[] args) throws InterruptedException {
ApiClient defaultClient = Configuration.getDefaultApiClient();
defaultClient.setBasePath("https://api.aylien.com/news/");
// Configure API key authorization: app_id
ApiKeyAuth app_id = (ApiKeyAuth)defaultClient.getAuthentication("app_id");
app_id.setApiKey("4e702f43");
// Configure API key authorization: app_key
ApiKeyAuth app_key = (ApiKeyAuth)defaultClient.getAuthentication("app_key");
app_key.setApiKey("2c7eacd54766f854afef7bb991ead798");
DefaultApi apiInstance = new DefaultApi(defaultClient);
List<String> language = Arrays.asList("en");
String title = "Dublin";
String publishedAtStart = "NOW-5MINUTES";
String publishedAtEnd = "NOW";
String sortBy = "published_at";
Integer perPage = 5;
String cursor = "*";
while (true) {
List<Story> stories = fetchNewStories(apiInstance, language, title, publishedAtStart, publishedAtEnd, sortBy, perPage, cursor);
System.out.println("\n*****************\n");
System.out.format("Fetched %d stories which were published between %s and %s\n", stories.size(), publishedAtStart, publishedAtEnd);
if (stories.size() > 0) {
// Below is the line with the problem
OffsetDateTime lastFetchedAt = stories.get(0).getPublishedAt().plusSeconds(1);
publishedAtStart = lastFetchedAt.toString();
cursor = "*";
}
System.out.println("Sleep for 60 seconds until next poll...");
System.out.println("--------------");
try {
Thread.sleep(1000 * 60);
} catch (InterruptedException e) {
e.printStackTrace();
}
}
}
public static List fetchNewStories(DefaultApi apiInstance, List language, String title, String publishedAtStart, String publishedAtEnd, String sortBy, Integer perPage, String cursor) {
System.out.println("--------------");
List fetchedStories = new ArrayList();
List stories = null;
while (stories == null || stories.size() > 0) {
try {
Stories result = apiInstance.listStories()
.language(language)
.title(title)
.publishedAtStart(publishedAtStart)
.publishedAtEnd(publishedAtEnd)
.sortBy(sortBy)
.perPage(perPage)
.cursor(cursor)
.execute();
stories = result.getStories();
cursor = result.getNextPageCursor();
for (Iterator i = result.getStories().iterator(); i.hasNext();) {
Story story = (Story)i.next();
System.out.println( story.getPublishedAt() + " / " + story.getTitle() + " / " + story.getSource().getName());
}
fetchedStories.addAll(stories);
System.out.format("Fetched %d stories. Total story count so far: %d\n", stories.size(), fetchedStories.size());
} catch (ApiException e) {
System.out.println(e);
switch (e.getCode()) {
case 429:
System.out.println("Usage limit are exceeded. Wating for 60 seconds...");
try {
Thread.sleep(1000 * 60);
} catch (InterruptedException ex) {
ex.printStackTrace();
}
break;
case 401:
System.out.println("Unauthorized api call. Have you set your api id and key?");
default:
System.out.printf("Error code: %s%n", e.getCode());
}
}
}
return fetchedStories;
}
}
Pagination of Results
The API returns up to 100 stories per call. This workflow shows you how to use cursor to chain multiple calls together and retrieve more than 100 stories at a time.
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 limits are exceeded. Waiting 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 limits are exceeded. Waiting 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 limits are exceeded. Waiting 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 limits are exceeded. Waiting 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 limits are exceeded. Waiting 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)
}
using System;
using Aylien.NewsApi.Api;
using Aylien.NewsApi.Client;
using Aylien.NewsApi.Model;
using System.Collections.Generic;
using System.Threading;
namespace ResultsPagination
{
class Program
{
static DefaultApi apiInstance;
static void Main(string[] args)
{
Configuration.Default.BasePath = "https://api.aylien.com/news";
// Configure API key authorization: app_id
Configuration.Default.AddApiKey("X-AYLIEN-NewsAPI-Application-ID", "YOUR_APP_ID");
// Configure API key authorization: app_key
Configuration.Default.AddApiKey("X-AYLIEN-NewsAPI-Application-Key", "YOUR_API_KEY");
apiInstance = new DefaultApi();
var publishedAtStart = "NOW-1HOUR";
var publishedAtEnd = "NOW";
var stories = FetchNewStories(publishedAtStart, publishedAtEnd);
Console.WriteLine("*****************");
Console.WriteLine(string.Format("Fetched {0} stories mentioning 'startup' in the title, are in English, and were published between {1} and {2}",
stories.Count, publishedAtStart, publishedAtEnd));
}
static List<Story> FetchNewStories(String publishedAtStart, String publishedAtEnd)
{
var cursor = "*";
var fetchedStories = new List<Story>();
List<Story> stories = null;
while (stories == null || stories.Count > 0)
{
try
{
var storiesResponse = apiInstance.ListStories(
language: new List<string> { "en" },
publishedAtStart: publishedAtStart,
publishedAtEnd: publishedAtEnd,
cursor: cursor,
perPage: 16
);
stories = storiesResponse._Stories;
cursor = storiesResponse.NextPageCursor;
fetchedStories.AddRange(stories);
Console.WriteLine(string.Format("Fetched {0} stories. Total story count so far: {1}",
stories.Count, fetchedStories.Count));
}
catch (ApiException e)
{
if (e.ErrorCode == 429)
{
Console.WriteLine("Usage limits are exceeded. Waiting for 60 seconds...");
Thread.Sleep(1000 * 60);
}
else
{
Console.WriteLine("Exception when calling DefaultApi.ListStories: " + e.Message);
}
}
}
return fetchedStories;
}
}
}
package com.example;
import java.util.*;
import com.aylien.newsapi.ApiClient;
import com.aylien.newsapi.ApiException;
import com.aylien.newsapi.Configuration;
import com.aylien.newsapi.api.DefaultApi;
import com.aylien.newsapi.auth.ApiKeyAuth;
import com.aylien.newsapi.models.Stories;
import com.aylien.newsapi.models.Story;
public class Main {
public static void main(String[] args) throws InterruptedException {
ApiClient defaultClient = Configuration.getDefaultApiClient();
defaultClient.setBasePath("https://api.aylien.com/news/");
// Configure API key authorization: app_id
ApiKeyAuth app_id = (ApiKeyAuth)defaultClient.getAuthentication("app_id");
app_id.setApiKey("YOUR_APP_ID");
// Configure API key authorization: app_key
ApiKeyAuth app_key = (ApiKeyAuth)defaultClient.getAuthentication("app_key");
app_key.setApiKey("YOUR_API_KEY");
DefaultApi apiInstance = new DefaultApi(defaultClient);
List<String> language = Arrays.asList("en");
String publishedAtStart = "NOW-1HOUR";
String publishedAtEnd = "NOW";
String categoriesTaxonomy = "iab-qag";
List<String> categoriesId = Arrays.asList("IAB17-2");
String sortBy = "published_at";
Integer perPage = 5;
String cursor = "*";
List<Story> stories = fetchNewStories(apiInstance, language, publishedAtStart, publishedAtEnd, categoriesTaxonomy, categoriesId, sortBy, perPage, cursor);
System.out.println("\n\n*****************\n");
System.out.format("Fetched %d stories which were published between %s and %s", stories.size(), publishedAtStart, publishedAtEnd);
try {
Thread.sleep(1000 * 900);
} catch (InterruptedException e) {
e.printStackTrace();
}
}
public static List fetchNewStories(DefaultApi apiInstance, List<String> language, String publishedAtStart, String publishedAtEnd, String categoriesTaxonomy, List<String> categoriesId, String sortBy, Integer perPage, String cursor) {
List fetchedStories = new ArrayList();
List stories = null;
while (stories == null || stories.size() > 0) {
try {
Stories result = apiInstance.listStories()
.language(language)
.publishedAtStart(publishedAtStart)
.publishedAtEnd(publishedAtEnd)
.categoriesTaxonomy(categoriesTaxonomy)
.categoriesId(categoriesId)
.sortBy(sortBy)
.perPage(perPage)
.cursor(cursor)
.execute();
stories = result.getStories();
cursor = result.getNextPageCursor();
// Print the story titles to the console
for (Iterator i = result.getStories().iterator(); i.hasNext();) {
Story story = (Story)i.next();
System.out.println( story.getPublishedAt() + " / " + story.getTitle());
}
fetchedStories.addAll(stories);
System.out.format("Fetched %d stories last call. Total story count so far: %d", stories.size(), fetchedStories.size());
System.out.println("\n");
} catch (ApiException e) {
System.out.println(e);
switch (e.getCode()) {
case 429:
System.out.println("Usage limit are exceeded. Wating for 60 seconds...");
try {
Thread.sleep(1000 * 60);
} catch (InterruptedException ex) {
ex.printStackTrace();
}
break;
case 401:
System.out.println("Unauthorized api call. Have you set your api id and key?");
default:
System.out.printf("Error code: %s%n", e.getCode());
}
}
}
return fetchedStories;
}
}
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
recencyvalue gives a higher rank to stories that were published more recently but also gives weight to your query too. - Using
published_atas 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)
}
}
using System;
using Aylien.NewsApi.Api;
using Aylien.NewsApi.Client;
using Aylien.NewsApi.Model;
using System.Collections.Generic;
namespace SortingResultsExample
{
class Program
{
static void Main(string[] args)
{
Configuration.Default.BasePath = "https://api.aylien.com/news";
// Configure API key authorization: app_id
Configuration.Default.AddApiKey("X-AYLIEN-NewsAPI-Application-ID", "YOUR_APP_ID");
// Configure API key authorization: app_key
Configuration.Default.AddApiKey("X-AYLIEN-NewsAPI-Application-Key", "YOUR_API_KEY");
var apiInstance = new DefaultApi();
try
{
// List stories
Stories storiesResponse = apiInstance.ListStories(
publishedAtStart: "NOW-1MONTH",
publishedAtEnd: "NOW",
language: new List<string> { "en" },
entitiesBodyLinksDbpedia: new List<string> {
"http://dbpedia.org/resource/Baseball"
},
sortBy: "published_at"
);
foreach (var story in storiesResponse._Stories)
{
Console.WriteLine(story.Title + " / " + story.Source.Name);
}
}
catch (Exception e)
{
Console.WriteLine("Exception when calling DefaultApi.ListStories: " + e.Message);
}
}
}
}
package com.example;
import com.aylien.newsapi.ApiClient;
import com.aylien.newsapi.ApiException;
import com.aylien.newsapi.Configuration;
import com.aylien.newsapi.api.DefaultApi;
import com.aylien.newsapi.auth.*;
import com.aylien.newsapi.models.*;
import java.util.*;
public class Main {
public static void main(String[] args) {
ApiClient defaultClient = Configuration.getDefaultApiClient();
defaultClient.setBasePath("https://api.aylien.com/news/");
// Configure API key authorization: app_id
ApiKeyAuth app_id = (ApiKeyAuth)defaultClient.getAuthentication("app_id");
app_id.setApiKey("YOUR_APP_ID");
// Configure API key authorization: app_key
ApiKeyAuth app_key = (ApiKeyAuth)defaultClient.getAuthentication("app_key");
app_key.setApiKey("YOUR_API_KEY");
DefaultApi apiInstance = new DefaultApi(defaultClient);
List<String> language = Arrays.asList("en");
String publishedAtStart = "NOW-1MONTH";
List<String> entitiesTitleLinksDbpedia = Arrays.asList("http://dbpedia.org/resource/Baseball");
String sortBy = "published_at";
try {
Stories result = apiInstance.listStories()
.entitiesTitleLinksDbpedia(entitiesTitleLinksDbpedia)
.language(language)
.publishedAtStart(publishedAtStart)
.sortBy(sortBy)
.execute();
for (Iterator i = result.getStories().iterator(); i.hasNext();) {
Story story = (Story)i.next();
System.out.println( story.getPublishedAt() + " / " + story.getTitle() + " / " + story.getSource().getName());
}
} catch (ApiException e) {
System.out.println(e);
switch (e.getCode()) {
case 429:
System.out.println("Usage limit are exceeded. Wating for 60 seconds...");
try {
Thread.sleep(1000 * 60);
} catch (InterruptedException ex) {
ex.printStackTrace();
}
break;
case 401:
System.out.println("Unauthorized api call. Have you set your api id and key?");
default:
System.out.printf("Error code: %s%n", e.getCode());
}
}
}
}
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).
Why use entities instead of keywords?
The News API's entities feature recognises and disambiguates real-world people, companies, and things that appear in the news. This has two main benefits when you're beuilding your search.
First, when a single 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 real-world entity is being referred to. As an example, take the following two sentences mentioning the keyword “apple” and see how the News API will recognise each as a different entity, and how it returns some key information:
| "An apple is a great source of vitamins." | " Apple was founded by Steve Jobs and Steve Wozniak." | |
|---|---|---|
| Suface Form | "apple" | "Apple" |
| Entity Name | Apple | Apple Inc. |
| Entity Type | Fruit, Eukaryote, Plant | Company, Organization |
| DBpedia URI | http://dbpedia.org/resource/Apple | http://dbpedia.org/resource/Apple_Inc |
Second, when a single entity is commonly referred to by multiple different keywords, 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." | “MetLife announces new insurance offerings." | |
|---|---|---|
| Suface Form | "Metropolitan Life Insurance" | "MetLife" |
| Entity Name | MetLife | MetLife |
| Entity Type | Company, Organization | Company, Organization |
| Entity URI | http://dbpedia.org/resource/MetLife | 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)
}
}
using System;
using Aylien.NewsApi.Api;
using Aylien.NewsApi.Client;
using Aylien.NewsApi.Model;
using System.Collections.Generic;
namespace WorkingWithEntitiesExample
{
class Program
{
static void Main(string[] args)
{
Configuration.Default.BasePath = "https://api.aylien.com/news";
// Configure API key authorization: app_id
Configuration.Default.AddApiKey("X-AYLIEN-NewsAPI-Application-ID", "YOUR_APP_ID");
// Configure API key authorization: app_key
Configuration.Default.AddApiKey("X-AYLIEN-NewsAPI-Application-Key", "YOUR_API_KEY");
var apiInstance = new DefaultApi();
try
{
// List stories
Stories storiesResponse = apiInstance.ListStories(
entitiesTitleLinksDbpedia: new List<string> {
"http://dbpedia.org/resource/Donald_Trump" },
entitiesTitleType: new List<string> { "Currency" },
language: new List<string> { "en" },
publishedAtStart: "NOW-1MONTH",
publishedAtEnd: "NOW",
sortBy: "source.rankings.alexa.rank.US"
);
Console.WriteLine("The API has been called successfully.");
Console.WriteLine("=====================================");
foreach (var story in storiesResponse._Stories)
{
Console.WriteLine(story.Title + " / " + story.Source.Name);
}
}
catch (Exception e)
{
Console.WriteLine("Exception when calling DefaultApi.ListStories: " + e.Message);
}
}
}
}
package com.example;
import com.aylien.newsapi.ApiClient;
import com.aylien.newsapi.ApiException;
import com.aylien.newsapi.Configuration;
import com.aylien.newsapi.api.DefaultApi;
import com.aylien.newsapi.auth.*;
import com.aylien.newsapi.models.*;
import java.util.*;
public class Main {
public static void main(String[] args) {
ApiClient defaultClient = Configuration.getDefaultApiClient();
defaultClient.setBasePath("https://api.aylien.com/news/");
// Configure API key authorization: app_id
ApiKeyAuth app_id = (ApiKeyAuth)defaultClient.getAuthentication("app_id");
app_id.setApiKey("YOUR_APP_ID");
// Configure API key authorization: app_key
ApiKeyAuth app_key = (ApiKeyAuth)defaultClient.getAuthentication("app_key");
app_key.setApiKey("YOUR_API_KEY");
DefaultApi apiInstance = new DefaultApi(defaultClient);
List<String> language = Arrays.asList("en");
String publishedAtStart = "NOW-1MONTH";
List<String> entitiesTitleLinksDbpedia = Arrays.asList("http://dbpedia.org/resource/Donald_Trump");
List<String> entitiesTitleType = Arrays.asList("Currency");
String sortBy = "published_at";
try {
Stories result = apiInstance.listStories()
.entitiesTitleLinksDbpedia(entitiesTitleLinksDbpedia)
.entitiesTitleType(entitiesTitleType)
.language(language)
.publishedAtStart(publishedAtStart)
.sortBy(sortBy)
.execute();
for (Iterator i = result.getStories().iterator(); i.hasNext();) {
Story story = (Story)i.next();
System.out.println( story.getPublishedAt() + " / " + story.getTitle() + " / " + story.getSource().getName());
}
} catch (ApiException e) {
System.err.println(e.toString());
e.printStackTrace();
}
}
}
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
or
"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
YYYYis the year.MMis the month.DDis the day of the month.Tis a literal 'T' character that indicates the beginning of the time string.hhis the hour of the day as on a 24-hour clock.mmis minutes.ssis seconds.Zis 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.822Z2016-03-27T13:47:26.82Z2016-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 | Round part? |
|---|---|---|---|
| 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))
opts = {
'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)
}
}
using System;
using Aylien.NewsApi.Api;
using Aylien.NewsApi.Client;
using Aylien.NewsApi.Model;
using System.Collections.Generic;
namespace WorkingWithLocations
{
class Program
{
static void Main(string[] args)
{
Configuration.Default.BasePath = "https://api.aylien.com/news";
// Configure API key authorization: app_id
Configuration.Default.AddApiKey("X-AYLIEN-NewsAPI-Application-ID", "YOUR_APP_ID");
// Configure API key authorization: app_key
Configuration.Default.AddApiKey("X-AYLIEN-NewsAPI-Application-Key", "YOUR_API_KEY");
var apiInstance = new DefaultApi();
try
{
// List Stories
Stories storiesResponse = apiInstance.ListStories(
language: new List<string> { "en" },
publishedAtStart: "NOW-10DAYS",
publishedAtEnd: "NOW",
categoriesTaxonomy: "iptc-subjectcode",
categoriesId: new List<string> { "11000000" },
sourceLocationsCountry: new List<string> { "US" },
sourceLocationsState: new List<string> { "Florida" }
);
Console.WriteLine("The API has been called successfully.");
Console.WriteLine("=====================================");
foreach (var story in storiesResponse._Stories)
{
Console.WriteLine(story.Title + " / " + story.Source.Name);
}
}
catch (Exception e)
{
Console.WriteLine("Exception when calling DefaultApi.ListStories: " + e.Message);
}
}
}
}
package com.example;
import com.aylien.newsapi.ApiClient;
import com.aylien.newsapi.ApiException;
import com.aylien.newsapi.Configuration;
import com.aylien.newsapi.api.DefaultApi;
import com.aylien.newsapi.auth.*;
import com.aylien.newsapi.models.*;
import java.util.*;
public class Main {
public static void main(String[] args) {
ApiClient defaultClient = Configuration.getDefaultApiClient();
defaultClient.setBasePath("https://api.aylien.com/news/");
// Configure API key authorization: app_id
ApiKeyAuth app_id = (ApiKeyAuth)defaultClient.getAuthentication("app_id");
app_id.setApiKey("");
// Configure API key authorization: app_key
ApiKeyAuth app_key = (ApiKeyAuth)defaultClient.getAuthentication("app_key");
app_key.setApiKey("");
DefaultApi apiInstance = new DefaultApi(defaultClient);
List<String> language = Arrays.asList("en");
String publishedAtStart = "NOW-1MONTH";
List<String> sourceLocationsState = Arrays.asList("Florida");
List<String> sourceLocationsCountry = Arrays.asList("IN");
try {
Stories result = apiInstance.listStories()
.sourceLocationsCountry(sourceLocationsCountry)
.sourceLocationsState(sourceLocationsState)
.language(language)
.publishedAtStart(publishedAtStart)
.execute();
for (Iterator i = result.getStories().iterator(); i.hasNext();) {
Story story = (Story)i.next();
System.out.println( story.getSource().getName() + " / " + story.getTitle());
}
} catch (ApiException e) {
System.err.println(e.toString());
e.printStackTrace();
}
}
}
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)
}
}
using System;
using Aylien.NewsApi.Api;
using Aylien.NewsApi.Client;
using Aylien.NewsApi.Model;
using System.Collections.Generic;
namespace WorkingWithLocationsSource
{
class Program
{
static void Main(string[] args)
{
Configuration.Default.BasePath = "https://api.aylien.com/news";
// Configure API key authorization: app_id
Configuration.Default.AddApiKey("X-AYLIEN-NewsAPI-Application-ID", "YOUR_APP_ID");
// Configure API key authorization: app_key
Configuration.Default.AddApiKey("X-AYLIEN-NewsAPI-Application-Key", "YOUR_API_KEY");
var apiInstance = new DefaultApi();
try
{
// List Stories
Stories storiesResponse = apiInstance.ListStories(
language: new List<string> { "en" },
publishedAtStart: "NOW-30DAYS",
publishedAtEnd: "NOW",
sortBy: "published_at",
categoriesTaxonomy: "iab-qag",
categoriesId: new List<string> { "IAB3" },
sourceScopesCity: new List<string> { "London" }
);
Console.WriteLine("The API has been called successfully.");
Console.WriteLine("=====================================");
foreach (var story in storiesResponse._Stories)
{
Console.WriteLine(story.Title + " / " + story.Source.Name);
}
}
catch (Exception e)
{
Console.WriteLine("Exception when calling DefaultApi.ListStories: " + e.Message);
}
}
}
}
package com.example;
import com.aylien.newsapi.ApiClient;
import com.aylien.newsapi.ApiException;
import com.aylien.newsapi.Configuration;
import com.aylien.newsapi.api.DefaultApi;
import com.aylien.newsapi.auth.*;
import com.aylien.newsapi.models.*;
import java.util.*;
public class Main {
public static void main(String[] args) {
ApiClient defaultClient = Configuration.getDefaultApiClient();
defaultClient.setBasePath("https://api.aylien.com/news/");
// Configure API key authorization: app_id
ApiKeyAuth app_id = (ApiKeyAuth)defaultClient.getAuthentication("app_id");
app_id.setApiKey("YOUR_APP_ID");
// Configure API key authorization: app_key
ApiKeyAuth app_key = (ApiKeyAuth)defaultClient.getAuthentication("app_key");
app_key.setApiKey("YOUR_API_KEY");
DefaultApi apiInstance = new DefaultApi(defaultClient);
List<String> language = Arrays.asList("en");
String publishedAtStart = "NOW-1MONTH";
List<String> sourceScopesCity = Arrays.asList("London");
String categoriesTaxonomy = "iab-qag";
List<String> categoriesId = Arrays.asList("IAB3");
try {
Stories result = apiInstance.listStories()
.sourceScopesCity(sourceScopesCity)
.categoriesTaxonomy(categoriesTaxonomy)
.categoriesId(categoriesId)
.language(language)
.publishedAtStart(publishedAtStart)
.execute();
for (Iterator i = result.getStories().iterator(); i.hasNext();) {
Story story = (Story)i.next();
System.out.println( story.getSource().getName() + " / " + story.getTitle());
}
} catch (ApiException e) {
System.err.println(e.toString());
e.printStackTrace();
}
}
}
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)
}
}
using System;
using Aylien.NewsApi.Api;
using Aylien.NewsApi.Client;
using Aylien.NewsApi.Model;
using System.Collections.Generic;
namespace WorkingWithLocationsMentioned
{
class Program
{
static void Main(string[] args)
{
Configuration.Default.BasePath = "https://api.aylien.com/news";
// Configure API key authorization: app_id
Configuration.Default.AddApiKey("X-AYLIEN-NewsAPI-Application-ID", "YOUR_APP_ID");
// Configure API key authorization: app_key
Configuration.Default.AddApiKey("X-AYLIEN-NewsAPI-Application-Key", "YOUR_API_KEY");
var apiInstance = new DefaultApi();
try
{
// List Stories
Stories storiesResponse = apiInstance.ListStories(
language: new List<string> { "en" },
publishedAtStart: "NOW-30DAYS",
publishedAtEnd: "NOW",
sortBy: "published_at",
categoriesTaxonomy: "iab-qag",
categoriesId: new List<string> { "IAB2-10" },
entitiesTitleLinksDbpedia: new List<string> { "http://dbpedia.org/resource/San_Francisco" }
);
Console.WriteLine("The API has been called successfully.");
Console.WriteLine("=====================================");
foreach (var story in storiesResponse._Stories)
{
Console.WriteLine(story.Title + " / " + story.Source.Name);
}
}
catch (Exception e)
{
Console.WriteLine("Exception when calling DefaultApi.ListStories: " + e.Message);
}
}
}
}
package com.example;
import com.aylien.newsapi.ApiClient;
import com.aylien.newsapi.ApiException;
import com.aylien.newsapi.Configuration;
import com.aylien.newsapi.api.DefaultApi;
import com.aylien.newsapi.auth.*;
import com.aylien.newsapi.models.*;
import java.util.*;
public class Main {
public static void main(String[] args) {
ApiClient defaultClient = Configuration.getDefaultApiClient();
defaultClient.setBasePath("https://api.aylien.com/news/");
// Configure API key authorization: app_id
ApiKeyAuth app_id = (ApiKeyAuth)defaultClient.getAuthentication("app_id");
app_id.setApiKey("YOUR_APP_ID");
// Configure API key authorization: app_key
ApiKeyAuth app_key = (ApiKeyAuth)defaultClient.getAuthentication("app_key");
app_key.setApiKey("YOUR_API_KEY");
DefaultApi apiInstance = new DefaultApi(defaultClient);
List<String> language = Arrays.asList("en");
String publishedAtStart = "NOW-1MONTH";
List<String> entitiesTitleLinksDbpedia = Arrays.asList("http://dbpedia.org/resource/San_Francisco");
try {
Stories result = apiInstance.listStories()
.entitiesTitleLinksDbpedia(entitiesTitleLinksDbpedia)
.language(language)
.publishedAtStart(publishedAtStart)
.execute();
for (Iterator i = result.getStories().iterator(); i.hasNext();) {
Story story = (Story)i.next();
System.out.println( story.getSource().getName() + " / " + story.getTitle());
}
} catch (ApiException e) {
System.err.println(e.toString());
e.printStackTrace();
}
}
}
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)
}
}
using System;
using Aylien.NewsApi.Api;
using Aylien.NewsApi.Client;
using Aylien.NewsApi.Model;
using System.Collections.Generic;
namespace WorkingWithCategoriesExample
{
class Program
{
static void Main(string[] args)
{
Configuration.Default.BasePath = "https://api.aylien.com/news";
// Configure API key authorization: app_id
Configuration.Default.AddApiKey("X-AYLIEN-NewsAPI-Application-ID", "YOUR_APP_ID");
// Configure API key authorization: app_key
Configuration.Default.AddApiKey("X-AYLIEN-NewsAPI-Application-Key", "YOUR_API_KEY");
var apiInstance = new DefaultApi();
try
{
// List Stories
Stories storiesResponse = apiInstance.ListStories(
categoriesTaxonomy: "iab-qag",
categoriesId: new List<string> { "IAB15" },
language: new List<string> { "en" },
publishedAtStart: "NOW-1DAY",
publishedAtEnd: "NOW"
);
Console.WriteLine("The API has been called successfully.");
Console.WriteLine("=====================================");
foreach (var story in storiesResponse._Stories)
{
Console.WriteLine(story.Title + " / " + story.Source.Name);
}
}
catch (Exception e)
{
Console.WriteLine("Exception when calling DefaultApi.ListStories: " + e.Message);
}
}
}
}
package com.example;
import com.aylien.newsapi.ApiClient;
import com.aylien.newsapi.ApiException;
import com.aylien.newsapi.Configuration;
import com.aylien.newsapi.api.DefaultApi;
import com.aylien.newsapi.auth.*;
import com.aylien.newsapi.models.*;
import java.util.*;
public class Main {
public static void main(String[] args) {
ApiClient defaultClient = Configuration.getDefaultApiClient();
defaultClient.setBasePath("https://api.aylien.com/news/");
// Configure API key authorization: app_id
ApiKeyAuth app_id = (ApiKeyAuth)defaultClient.getAuthentication("app_id");
app_id.setApiKey("YOUR_APP_ID");
// Configure API key authorization: app_key
ApiKeyAuth app_key = (ApiKeyAuth)defaultClient.getAuthentication("app_key");
app_key.setApiKey("YOUR_API_KEY");
DefaultApi apiInstance = new DefaultApi(defaultClient);
List<String> language = Arrays.asList("en");
String publishedAtStart = "NOW-1DAY";
String categoriesTaxonomy = "iab-qag";
List<String> categoriesId = Arrays.asList("IAB15");
try {
Stories result = apiInstance.listStories()
.categoriesTaxonomy(categoriesTaxonomy)
.categoriesId(categoriesId)
.language(language)
.publishedAtStart(publishedAtStart)
.execute();
for (Iterator i = result.getStories().iterator(); i.hasNext();) {
Story story = (Story)i.next();
System.out.println( story.getSource().getName() + " / " + story.getTitle());
}
} catch (ApiException e) {
System.err.println(e.toString());
e.printStackTrace();
}
}
}
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.minto 1, you are specifying that your query only return stories with at least one image. - By setting
media.videos.count.minto 1, andmedia.videos.count.maxalso to 1, you are specifying that you only want results that contain exactly one video. - By setting
media.videos.count.maxto 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.widthmedia.images.heightmedia.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)
}
}
using System;
using Aylien.NewsApi.Api;
using Aylien.NewsApi.Client;
using Aylien.NewsApi.Model;
using System.Collections.Generic;
namespace WorkingWithMediaResultsExample
{
class Program
{
static void Main(string[] args)
{
Configuration.Default.BasePath = "https://api.aylien.com/news";
// Configure API key authorization: app_id
Configuration.Default.AddApiKey("X-AYLIEN-NewsAPI-Application-ID", "YOUR_APP_ID");
// Configure API key authorization: app_key
Configuration.Default.AddApiKey("X-AYLIEN-NewsAPI-Application-Key", "YOUR_API_KEY");
var apiInstance = new DefaultApi();
try
{
// List Stories
Stories storiesResponse = apiInstance.ListStories(
categoriesTaxonomy: "iab-qag",
categoriesId: new List<string> { "IAB7" },
text: "fitness",
language: new List<string> { "en" },
mediaVideosCountMin: 1,
mediaVideosCountMax: 1,
notMediaImagesFormat: new List<string> { "GIF" },
publishedAtStart: "NOW-1MONTH",
publishedAtEnd: "NOW",
sortBy: "relevance"
);
Console.WriteLine("The API has been called successfully.");
Console.WriteLine("=====================================");
foreach (var story in storiesResponse._Stories)
{
Console.WriteLine(story.Title + " / " + story.Source.Name);
}
}
catch (Exception e)
{
Console.WriteLine("Exception when calling DefaultApi.ListStories: " + e.Message);
}
}
}
}
package com.example;
import com.aylien.newsapi.ApiClient;
import com.aylien.newsapi.ApiException;
import com.aylien.newsapi.Configuration;
import com.aylien.newsapi.api.DefaultApi;
import com.aylien.newsapi.auth.*;
import com.aylien.newsapi.models.*;
import java.util.*;
public class Main {
public static void main(String[] args) {
ApiClient defaultClient = Configuration.getDefaultApiClient();
defaultClient.setBasePath("https://api.aylien.com/news/");
// Configure API key authorization: app_id
ApiKeyAuth app_id = (ApiKeyAuth)defaultClient.getAuthentication("app_id");
app_id.setApiKey("YOUR_APP_ID");
// Configure API key authorization: app_key
ApiKeyAuth app_key = (ApiKeyAuth)defaultClient.getAuthentication("app_key");
app_key.setApiKey("YOUR_API_KEY");
DefaultApi apiInstance = new DefaultApi(defaultClient);
Integer mediaVideosCountMin = 1;
Integer mediaVideosCountMax = 1;
List<String> notMediaImagesFormat = Arrays.asList("GIF");
String categoriesTaxonomy = "iab-qag";
List<String> categoriesId = Arrays.asList("IAB7");
String sortBy = "relevance";
String text = "fitness";
List<String> language = Arrays.asList("en");
String publishedAtStart = "NOW-1MONTH";
try {
Stories result = apiInstance.listStories()
.mediaVideosCountMin(mediaVideosCountMin)
.mediaVideosCountMax(mediaVideosCountMax)
.notMediaImagesFormat(notMediaImagesFormat)
.categoriesTaxonomy(categoriesTaxonomy)
.categoriesId(categoriesId)
.sortBy(sortBy)
.text(text)
.language(language)
.publishedAtStart(publishedAtStart)
.execute();
for (Iterator i = result.getStories().iterator(); i.hasNext();) {
Story story = (Story)i.next();
System.out.println(story.getTitle() + " / " + story.getMedia());
}
} catch (ApiException e) {
System.err.println(e.toString());
e.printStackTrace();
}
}
}
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)
}
}
using System;
using Aylien.NewsApi.Api;
using Aylien.NewsApi.Client;
using Aylien.NewsApi.Model;
using System.Collections.Generic;
namespace WorkingWithAlexaRankings
{
class Program
{
static void Main(string[] args)
{
Configuration.Default.BasePath = "https://api.aylien.com/news";
// Configure API key authorization: app_id
Configuration.Default.AddApiKey("X-AYLIEN-NewsAPI-Application-ID", "YOUR_APP_ID");
// Configure API key authorization: app_key
Configuration.Default.AddApiKey("X-AYLIEN-NewsAPI-Application-Key", "YOUR_API_KEY");
var apiInstance = new DefaultApi();
try
{
// List Stories
Stories storiesResponse = apiInstance.ListStories(
publishedAtStart: "NOW-1DAY",
publishedAtEnd: "NOW",
language: new List<string> { "en" },
categoriesTaxonomy: "iab-qag",
categoriesId: new List<string> { "IAB15" },
sourceRankingsAlexaRankMin: 25,
sourceRankingsAlexaRankMax: 100
);
Console.WriteLine("The API has been called successfully.");
Console.WriteLine("=====================================");
foreach (var story in storiesResponse._Stories)
{
Console.WriteLine(story.Title + " / " + story.Source.Name);
}
}
catch (Exception e)
{
Console.WriteLine("Exception when calling DefaultApi.ListStories: " + e.Message);
}
}
}
}
package com.example;
import com.aylien.newsapi.ApiClient;
import com.aylien.newsapi.ApiException;
import com.aylien.newsapi.Configuration;
import com.aylien.newsapi.api.DefaultApi;
import com.aylien.newsapi.auth.*;
import com.aylien.newsapi.models.*;
import java.util.*;
public class Main {
public static void main(String[] args) {
ApiClient defaultClient = Configuration.getDefaultApiClient();
defaultClient.setBasePath("https://api.aylien.com/news/");
// Configure API key authorization: app_id
ApiKeyAuth app_id = (ApiKeyAuth)defaultClient.getAuthentication("app_id");
app_id.setApiKey("YOUR_APP_ID");
// Configure API key authorization: app_key
ApiKeyAuth app_key = (ApiKeyAuth)defaultClient.getAuthentication("app_key");
app_key.setApiKey("YOUR_API_KEY");
DefaultApi apiInstance = new DefaultApi(defaultClient);
String categoriesTaxonomy = "iab-qag";
List<String> categoriesId = Arrays.asList("IAB15");
String publishedAtStart = "NOW-1DAY";
Integer sourceRankingsAlexaRankMin = 25;
Integer sourceRankingsAlexaRankMax = 100
try {
Stories result = apiInstance.listStories()
.categoriesTaxonomy(categoriesTaxonomy)
.categoriesId(categoriesId)
.publishedAtStart(publishedAtStart)
.sourceRankingsAlexaRankMin(sourceRankingsAlexaRankMin)
.sourceRankingsAlexaRankMax(sourceRankingsAlexaRankMax)
.execute();
for (Iterator i = result.getStories().iterator(); i.hasNext();) {
Story story = (Story)i.next();
System.out.println(story.getSource() + " / " + story.getTitle());
}
} catch (ApiException e) {
System.err.println(e.toString());
e.printStackTrace();
}
}
}
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)
}
}
using System;
using Aylien.NewsApi.Api;
using Aylien.NewsApi.Client;
using Aylien.NewsApi.Model;
using System.Collections.Generic;
namespace WorkingWithLinksInCount
{
class Program
{
static void Main(string[] args)
{
Configuration.Default.BasePath = "https://api.aylien.com/news";
// Configure API key authorization: app_id
Configuration.Default.AddApiKey("X-AYLIEN-NewsAPI-Application-ID", "YOUR_APP_ID");
// Configure API key authorization: app_key
Configuration.Default.AddApiKey("X-AYLIEN-NewsAPI-Application-Key", "YOUR_API_KEY");
var apiInstance = new DefaultApi();
try
{
// List Stories
Stories storiesResponse = apiInstance.ListStories(
publishedAtStart: "NOW-1DAY",
publishedAtEnd: "NOW",
language: new List<string> { "en" },
categoriesTaxonomy: "iab-qag",
categoriesId: new List<string> { "IAB15" },
sourceLinksInCountMin: 100000,
sourceLinksInCountMax: 200000
);
Console.WriteLine("The API has been called successfully.");
Console.WriteLine("=====================================");
foreach (var story in storiesResponse._Stories)
{
Console.WriteLine(story.Title + " / " + story.Source.Name);
}
}
catch (Exception e)
{
Console.WriteLine("Exception when calling DefaultApi.ListStories: " + e.Message);
}
}
}
}
package com.example;
import com.aylien.newsapi.ApiClient;
import com.aylien.newsapi.ApiException;
import com.aylien.newsapi.Configuration;
import com.aylien.newsapi.api.DefaultApi;
import com.aylien.newsapi.auth.*;
import com.aylien.newsapi.models.*;
import java.util.*;
public class Main {
public static void main(String[] args) {
ApiClient defaultClient = Configuration.getDefaultApiClient();
defaultClient.setBasePath("https://api.aylien.com/news/");
// Configure API key authorization: app_id
ApiKeyAuth app_id = (ApiKeyAuth)defaultClient.getAuthentication("app_id");
app_id.setApiKey("YOUR_APP_ID");
// Configure API key authorization: app_key
ApiKeyAuth app_key = (ApiKeyAuth)defaultClient.getAuthentication("app_key");
app_key.setApiKey("YOUR_API_KEY");
DefaultApi apiInstance = new DefaultApi(defaultClient);
String categoriesTaxonomy = "iab-qag";
List<String> categoriesId = Arrays.asList("IAB15");
String publishedAtStart = "NOW-1DAY";
Integer sourceLinksInCountMin = 25;
Integer sourceLinksInCountMax = 100;
try {
Stories result = apiInstance.listStories()
.categoriesTaxonomy(categoriesTaxonomy)
.categoriesId(categoriesId)
.publishedAtStart(publishedAtStart)
.sourceLinksInCountMin(sourceLinksInCountMin)
.sourceLinksInCountMax(sourceLinksInCountMax)
.execute();
for (Iterator i = result.getStories().iterator(); i.hasNext();) {
Story story = (Story)i.next();
System.out.println(story.getSource() + " / " + story.getTitle());
}
} catch (ApiException e) {
System.err.println(e.toString());
e.printStackTrace();
}
}
}