Product

Getting Started with the News API Part 2: Insights

August 18, 2016 - Product

Getting Started with the News API Part 2: Insights

Introduction

Welcome to Part 2 of our Getting Started with the News API series. In Part 1 we introduced you to the API, the demo/query builder and the supporting interactive documentation. We also showed you how to perform a variety of basic searches to help you get familiar with the API.

Today we’ll begin to explore some of the more advanced capabilities that the API has to offer from an analysis and insights point of view. Whether you’re pushing data from the News API into an app, resurfacing the analysis in a news feed or building intuitive dashboards with the extracted data, the News API enables you to obtain a deep understanding for what’s happening in the news, in near real-time.

With this in mind, we’ll today be focusing on getting you up to speed with the following features;

  • Time Series – leveraging time stamped data
  • Sentiment – comparing the positive/negative polarity in author opinion
  • Histograms – working with numerical data points and metrics
  • Trends – uncovering useful insights

Before you go any further – have you created an AYLIEN account?

If not, we recommend you sign up for your Free trial and head back to Part 1 to learn the basics of search, making calls and creating specific search queries;

 

Basic Search News API

 

If you’ve created your account already and learned how to perform basic searches in Part 1, let’s get cracking with Part 2, starting with the Time Series endpoint.

Making calls:

We’ve created SDKs for some of the most popular programming languages which make using the API super easy. Just like Part 1, we’ve also included some code snippets for you to copy and build on.

Results:

News API results are returned in JSON format, making it easy for you to do as you please with the data. Throughout this post, we will be displaying charts and graphs that we generated using the JSON results returned from the code snippet examples provided.

1. Time Series – leveraging time stamped data

A Time Series is a sequence of data points plotted over a specified time period. The News API /time_series endpoint can be used to analyze a set of data points relative to this specified period. This makes it easy to analyze timestamped data, allowing you to easily visualize the data in an understandable and meaningful format.

In keeping with our analysis of the US Presidential election from Part 1, we’ll use the following example;

 

Search stories from sources in the USA mentioning Hillary Clinton from the past 60 Days
 

setApiKey('X-AYLIEN-NewsAPI-Application-ID', 'YOUR_APP_ID');

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

$api_instance = new Aylien\NewsApi\Api\DefaultApi();

$opts = array(
  'text' => '"Hillary Clinton"',
  'source_locations_country' => ['US'],
  'published_at_start' => 'NOW-60DAYS',
  'published_at_end' => 'NOW'
);

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

import aylien_news_api
from aylien_news_api.rest import ApiException

# Configure API key authorization: app_id
aylien_news_api.configuration.api_key['X-AYLIEN-NewsAPI-Application-ID'] = 'YOUR_APP_ID'
# Configure API key authorization: app_key
aylien_news_api.configuration.api_key['X-AYLIEN-NewsAPI-Application-Key'] = 'YOUR_APP_KEY'

# create an instance of the API class
api_instance = aylien_news_api.DefaultApi()

text = '"Hillary Clinton"'
country = ['US']
since = 'NOW-60DAYS'
until = 'NOW'

try:
    # List stories
    api_response = api_instance.list_time_series(text=text, source_locations_country=country, published_at_start=since, published_at_end=until)
    print(api_response)
except ApiException as e:
    print("Exception when calling DefaultApi->list_time_series: %s\n" % e)

package com.aylien.newsapisample;

import com.aylien.newsapi.*;
import com.aylien.newsapi.auth.*;
import com.aylien.newsapi.models.*;
import com.aylien.newsapi.parameters.*;
import com.aylien.newsapi.api.DefaultApi;

import java.util.*;

public class Main {

    public static void main(String[] args) {
        ApiClient defaultClient = Configuration.getDefaultApiClient();

        // 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_APP_KEY");

        DefaultApi apiInstance = new DefaultApi();

        TimeSeriesParams.Builder timeSeriesBuilder = TimeSeriesParams.newBuilder();

        String text = "\"Hillary Clinton\"";
        List sourceLocationsCountry = new ArrayList() {{
            add("US");
        }};
        String since = "NOW-60DAYS";
        String until = "NOW";

        timeSeriesBuilder.setText(text);
        timeSeriesBuilder.setSourceLocationsCountry(sourceLocationsCountry);
        timeSeriesBuilder.setPublishedAtStart(since);
        timeSeriesBuilder.setPublishedAtEnd(until);

        try {
            TimeSeriesList result = apiInstance.listTimeSeries(timeSeriesBuilder.build());
            System.out.println(result);
        } catch (ApiException e) {
            System.err.println("Exception when calling DefaultApi#listTimeSeries");
            e.printStackTrace();
        }
    }
}

# 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 = {
  :text => '"Hillary Clinton"',
  :source_locations_country => ['US'],
  :published_at_start => "NOW-60DAYS",
  :published_at_end => "NOW"
}


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

package main

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

func main() {
	api := newsapi.NewDefaultApi()

	// Configure API key authorization: app_id
	api.Configuration.APIKeyPrefix["X-AYLIEN-NewsAPI-Application-ID"] = "YOUR_APP_ID"

	// Configure API key authorization: app_key
	api.Configuration.APIKeyPrefix["X-AYLIEN-NewsAPI-Application-Key"] = "YOUR_APP_KEY"

	text := "\"Hillary Clinton\""
	sourceLocationsCountry := []string{"US"}
	until := "NOW"
	since := "NOW-60DAYS"

	timeSeriesParams := &newsapi.TimeSeriesParams{
		Text: text,
		SourceLocationsCountry: sourceLocationsCountry,
		PublishedAtStart:       since,
		PublishedAtEnd:         until}

	timeSeriesResponse, res, err := api.ListTimeSeries(timeSeriesParams)
	if err != nil {
		panic(err)
	}
	_ = res

	fmt.Println(timeSeriesResponse)
}

using System;
using System.Diagnostics;
using Aylien.NewsApi.Api;
using Aylien.NewsApi.Client;
using Aylien.NewsApi.Model;
using System.Collections.Generic;

namespace Example
{
    public class Example
    {
        static void Main(string[] args)
        {
            
            // Configure API key authorization: app_id
            Configuration.Default.ApiKey.Add("X-AYLIEN-NewsAPI-Application-ID", "YOUR_APP_ID");

            // Configure API key authorization: app_key
            Configuration.Default.ApiKey.Add("X-AYLIEN-NewsAPI-Application-Key", "YOUR_APP_KEY");

            var apiInstance = new DefaultApi();
            
            string text  = "\"Hillary Clinton\"";
            string since = "NOW-60DAYS";
            string until = "NOW";
            List sourceLocationsCountry = new List { "US" };

            try
            {
                // List time series
                TimeSeriesList result = apiInstance.ListTimeSeries(text: text, publishedAtStart: since, publishedAtEnd: until, sourceLocationsCity: sourceLocationsCountry);
                Debug.WriteLine(result);
            }
            catch (Exception e)
            {
                Debug.Print("Exception when calling DefaultApi.ListTimeSeries: " + e.Message );
            }
        }
    }
}
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_APP_KEY";

var opts = {
  'text': '"Hillary Clinton"',
  'sourceLocationsCountry': ['US'],
  'publishedAtStart': 'NOW-60DAYS',
  'publishedAtEnd': 'NOW'
};

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.listTimeSeries(opts, callback);

 

Note: Make sure you replace the APP_ID and APP_KEY placeholders with your own API credentials. Again, if you haven’t got an API account you can sign up here.

 

Visualized Results

As we mentioned earlier, because the News API returns results in JSON format, you can display the results as you please. Here’s an example of a chart we built using the results obtained from the snippet above.

Screen Shot 2016-08-10 at 16.39.39

Visit our documentation for more info on the Time Series endpoint.

Sentiment Analysis

Now let’s dive a little deeper by changing up and specifying our search to look at the levels of sentiment within the stories we retrieve. We’re narrowing our search parameters to only include stories from the past two days and from CNN and Fox News only;

 

Search stories from sources CNN and Fox News in the US mentioning Hillary Clinton from the past 2 Days
 

setApiKey('X-AYLIEN-NewsAPI-Application-ID', 'YOUR_APP_ID');

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

$api_instance = new Aylien\NewsApi\Api\DefaultApi();

$opts = array(
  'text' => '"Donald Trump"',
  'source_locations_country' => ['GB'],
  'published_at_start' => 'NOW-7DAYS',
  'published_at_end' => 'NOW'
);

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


import aylien_news_api
from aylien_news_api.rest import ApiException

# Configure API key authorization: app_id
aylien_news_api.configuration.api_key['X-AYLIEN-NewsAPI-Application-ID'] = 'YOUR_APP_ID'
# Configure API key authorization: app_key
aylien_news_api.configuration.api_key['X-AYLIEN-NewsAPI-Application-Key'] = 'YOUR_APP_KEY'

# create an instance of the API class
api_instance = aylien_news_api.DefaultApi()

text = '"Donald Trump"'
country = ['GB']
since = 'NOW-7DAYS'
until = 'NOW'

try:
    # List histograms
    api_response = api_response = api_instance.list_histograms(text=text, source_locations_country=country, published_at_start=since, published_at_end=until)
    print(api_response)
except ApiException as e:
    print("Exception when calling DefaultApi->list_histograms: %s\n" % e)

package com.aylien.newsapisample;

import com.aylien.newsapi.*;
import com.aylien.newsapi.auth.*;
import com.aylien.newsapi.models.*;
import com.aylien.newsapi.parameters.*;
import com.aylien.newsapi.api.DefaultApi;

import java.util.*;

public class Main {

    public static void main(String[] args) {
        ApiClient defaultClient = Configuration.getDefaultApiClient();

        // 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_APP_KEY");

        DefaultApi apiInstance = new DefaultApi();

        HistogramsParams.Builder histogramsBuilder = HistogramsParams.newBuilder();

        String text = "\"Donald Trump\"";
        List sourceLocationsCountry = new ArrayList() {{
            add("GB");
        }};
        String since = "NOW-7DAYS";
        String until = "NOW";

        histogramsBuilder.setText(text);
        histogramsBuilder.setSourceLocationsCountry(sourceLocationsCountry);
        histogramsBuilder.setPublishedAtStart(since);
        histogramsBuilder.setPublishedAtEnd(until);

        try {
            Histograms result = apiInstance.listHistograms(histogramsBuilder.build());
            System.out.println(result);
        } catch (ApiException e) {
            System.err.println("Exception when calling DefaultApi#listHistograms");
            e.printStackTrace();
        }
    }
}


# 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 = {
  :text => '"Donald Trump"',
  :source_locations_country => ['GB'],
  :published_at_start => "NOW-7DAYS",
  :published_at_end => "NOW"
}


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

package main

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

func main() {
	api := newsapi.NewDefaultApi()

	// Configure API key authorization: app_id
	api.Configuration.APIKeyPrefix["X-AYLIEN-NewsAPI-Application-ID"] = "YOUR_APP_ID"

	// Configure API key authorization: app_key
	api.Configuration.APIKeyPrefix["X-AYLIEN-NewsAPI-Application-Key"] = "YOUR_APP_KEY"

	text := "\"Donald Trump\""
	sourceLocationsCountry := []string{"GB"}
	until := "NOW"
	since := "NOW-7DAYS"

	histogramsParams := &newsapi.HistogramsParams{
		Text: text,
		SourceLocationsCountry: sourceLocationsCountry,
		PublishedAtStart:       since,
		PublishedAtEnd:         until}

	histogramsResponse, res, err := api.ListHistograms(histogramsParams)
  if err != nil {
      panic(err)
  }
  _ = res

  fmt.Println(histogramsResponse)
}

using System;
using System.Diagnostics;
using Aylien.NewsApi.Api;
using Aylien.NewsApi.Client;
using Aylien.NewsApi.Model;
using System.Collections.Generic;

namespace Example
{
    public class Example
    {
        static void Main(string[] args)
        {
            
            // Configure API key authorization: app_id
            Configuration.Default.ApiKey.Add("X-AYLIEN-NewsAPI-Application-ID", "YOUR_APP_ID");

            // Configure API key authorization: app_key
            Configuration.Default.ApiKey.Add("X-AYLIEN-NewsAPI-Application-Key", "YOUR_APP_KEY");

            var apiInstance = new DefaultApi();
            
            string text = "\"Donald Trump\"";
            string since = "NOW-7DAYS";
            string until = "NOW";
            List sourceLocationsCountry = new List { "GB" };

            try
            {
                // List histograms
                Stories result = apiInstance.ListHistograms(text: text, publishedAtStart: since, publishedAtEnd: until, sourceLocationsCountry: sourceLocationsCountry);
                Debug.WriteLine(result);
            }
            catch (Exception e)
            {
                Debug.Print("Exception when calling DefaultApi.ListHistograms: " + e.Message );
            }
        }
    }
}
}
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_APP_KEY";

var opts = {
  'text': '"Donald Trump"',
  'sourceLocationsCountry': ['GB'],
  'publishedAtStart': 'NOW-7DAYS',
  'publishedAtEnd': 'NOW'
};

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.listHistograms(opts, callback);

By displaying our results on a pie chart, we can clearly see that negative sentiment far outweighs positive in our returned stories. By narrowing our search parameters we have the opportunity to compare and contrast sentiment polarity towards various entities from numerous sources, locations and so on. Your options and level of search flexibility here are pretty much endless.

Visualized Results

Screen Shot 2016-08-17 at 14.52.27Visit our documentation for more info on the Sentiment Analysis features.

2. Histograms – working with numerical data points and metrics

A histogram is a graph that represents the distribution of numerical data. Our /histogram endpoint enables you to get an aggregated profile of a certain metric. Whatever that metric is, is up to you.

For this example, let’s look at the Social Shares and Article Length metrics. The former will tell us the volume/spread of social media shares that articles mentioning our search terms have received, while the latter will show us the length of articles in word.

Let’s switch up our search parameters a bit and analyze recent stories mentioning Donald Trump, from sources based in the UK;

Search stories from sources in the UK mentioning Donald Trump from the past 7 Days

setApiKey('X-AYLIEN-NewsAPI-Application-ID', 'YOUR_APP_ID');

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

$api_instance = new Aylien\NewsApi\Api\DefaultApi();

$opts = array(
  'text' => '"Presidential election"',
  'source_locations_country' => ['US'],
  'published_at_start' => 'NOW-2DAYS',
  'published_at_end' => 'NOW',
  'field' => 'keywords'
);

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

import aylien_news_api
from aylien_news_api.rest import ApiException

# Configure API key authorization: app_id
aylien_news_api.configuration.api_key['X-AYLIEN-NewsAPI-Application-ID'] = 'YOUR_APP_ID'
# Configure API key authorization: app_key
aylien_news_api.configuration.api_key['X-AYLIEN-NewsAPI-Application-Key'] = 'YOUR_APP_KEY'

# create an instance of the API class
api_instance = aylien_news_api.DefaultApi()

text = '"Presidential election"'
country = ['US']
since = 'NOW-2DAYS'
until = 'NOW'
field = 'keywords'

try:
    # List trends
    api_response = api_response = api_instance.list_histograms(text=text, source_locations_country=country, published_at_start=since, published_at_end=until, field=field)
    print(api_response)
except ApiException as e:
    print("Exception when calling DefaultApi->list_trends: %s\n" % e)

package com.aylien.newsapisample;

import com.aylien.newsapi.*;
import com.aylien.newsapi.auth.*;
import com.aylien.newsapi.models.*;
import com.aylien.newsapi.parameters.*;
import com.aylien.newsapi.api.DefaultApi;

import java.util.*;

public class Main {

    public static void main(String[] args) {
        ApiClient defaultClient = Configuration.getDefaultApiClient();

        // 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_APP_KEY");

        DefaultApi apiInstance = new DefaultApi();

        TrendsParams.Builder trendsBuilder = TrendsParams.newBuilder();

        String text = "\"Presidential election\"";
        List sourceLocationsCountry = new ArrayList() {{
            add("US");
        }};
        String since = "NOW-2DAYS";
        String until = "NOW";
        String field = "keywords";

        trendsBuilder.setText(text);
        trendsBuilder.setSourceLocationsCountry(sourceLocationsCountry);
        trendsBuilder.setPublishedAtStart(since);
        trendsBuilder.setPublishedAtEnd(until);
        trendsBuilder.setField(field);

        try {
            Trends result = apiInstance.listTrends(trendsBuilder.build());
            System.out.println(result);
        } catch (ApiException e) {
            System.err.println("Exception when calling DefaultApi#listTrends");
            e.printStackTrace();
        }
    }
}

# 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 = {
  :text => '"Presidential election"',
  :source_locations_country => ['US'],
  :published_at_start => "NOW-2DAYS",
  :published_at_end => "NOW",
  :field => 'keywords'
}

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

package main

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

func main() {
	api := newsapi.NewDefaultApi()

	// Configure API key authorization: app_id
	api.Configuration.APIKeyPrefix["X-AYLIEN-NewsAPI-Application-ID"] = "YOUR_APP_ID"

	// Configure API key authorization: app_key
	api.Configuration.APIKeyPrefix["X-AYLIEN-NewsAPI-Application-Key"] = "YOUR_APP_KEY"

	text := "\"Presidential election\""
	sourceLocationsCountry := []string{"US"}
	until := "NOW"
	since := "NOW-2DAYS"
	field := "keywords"

	trendsParams := &newsapi.TrendsParams{
		Text: text,
		SourceLocationsCountry: sourceLocationsCountry,
		PublishedAtStart:       since,
		PublishedAtEnd:         until}

	trendsResponse, res, err := api.ListTrends(trendsParams)
  if err != nil {
      panic(err)
  }
  _ = res

  fmt.Println(trendsResponse)
}

using System;
using System.Diagnostics;
using Aylien.NewsApi.Api;
using Aylien.NewsApi.Client;
using Aylien.NewsApi.Model;
using System.Collections.Generic;

namespace Example
{
    public class Example
    {
        static void Main(string[] args)
        {
            
            // Configure API key authorization: app_id
            Configuration.Default.ApiKey.Add("X-AYLIEN-NewsAPI-Application-ID", "YOUR_APP_ID");

            // Configure API key authorization: app_key
            Configuration.Default.ApiKey.Add("X-AYLIEN-NewsAPI-Application-Key", "YOUR_APP_KEY");

            var apiInstance = new DefaultApi();
            
            string text = "\"Presidential election\"";
            string since = "NOW-2DAYS";
            string until = "NOW";
            string field = "keywords";
            List sourceLocationsCountry = new List { "US" };

            try
            {
                // List trends
                Trends result = apiInstance.ListTrends(text: text, publishedAtStart: since, publishedAtEnd: until, sourceLocationsCountry: sourceLocationsCountry, field: field);
                Debug.WriteLine(result);
            }
            catch (Exception e)
            {
                Debug.Print("Exception when calling DefaultApi.ListTrends: " + e.Message );
            }
        }
    }
}

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_APP_KEY";

var opts = {
  'text': '"Presidential election"',
  'sourceLocationsCountry': ['US'],
  'publishedAtStart': 'NOW-2DAYS',
  'publishedAtEnd': 'NOW',
  'field': 'keywords'
};

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.listTrends(opts, callback);

Visualized Results

Screen Shot 2016-08-16 at 16.14.06Visit our documentation for more info on the Histograms endpoint.

3. Trends – uncovering useful insights

Using the /trends endpoint enables you to identify the most frequently mentioned keywords, entities and topical or sentiment-related categories. Put simply, it allows you to measure the amount of times that specific elements of interest are mentioned in the content you source through the API.

To see the /trends endpoint in action, we’re going to perform the following search to uncover the most mentioned entities from election-related stories over the past two days;

Search stories from sources in the US mentioning Presidential election from the past 2 Days

setApiKey('X-AYLIEN-NewsAPI-Application-ID', 'YOUR_APP_ID');

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

$api_instance = new Aylien\NewsApi\Api\DefaultApi();

$opts = array(
  'text' => '"Hillary Clinton"',
  'published_at_start' => 'NOW-2DAYS',
  'published_at_end' => 'NOW',
  'source_name' => ['CNN', 'Fox News']
);

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

import aylien_news_api
from aylien_news_api.rest import ApiException

# Configure API key authorization: app_id
aylien_news_api.configuration.api_key['X-AYLIEN-NewsAPI-Application-ID'] = 'YOUR_APP_ID'
# Configure API key authorization: app_key
aylien_news_api.configuration.api_key['X-AYLIEN-NewsAPI-Application-Key'] = 'YOUR_APP_KEY'

# create an instance of the API class
api_instance = aylien_news_api.DefaultApi()

text = '"Hillary Clinton"'
since = 'NOW-2DAYS'
until = 'NOW'
source_name = ['CNN', 'Fox News']


try:
    # List stories
    api_response = api_instance.list_stories(text=text, source_name=source_name, published_at_start=since, published_at_end=until)
    print(api_response)
except ApiException as e:
    print("Exception when calling DefaultApi->list_stories: %s\n" % e)

package com.aylien.newsapisample;

import com.aylien.newsapi.*;
import com.aylien.newsapi.auth.*;
import com.aylien.newsapi.models.*;
import com.aylien.newsapi.parameters.*;
import com.aylien.newsapi.api.DefaultApi;

import java.util.*;

public class Main {

    public static void main(String[] args) {
        ApiClient defaultClient = Configuration.getDefaultApiClient();

        // 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_APP_KEY");

        DefaultApi apiInstance = new DefaultApi();

        StoriesParams.Builder storiesBuilder = StoriesParams.newBuilder();

        String text = "\"Hillary Clinton\"";
        String since = "NOW-2DAYS";
        String until = "NOW";
        List sourceName = new ArrayList() {{
            add("CNN");
            add("Fox News");
        }};

        storiesBuilder.setText(text);
        storiesBuilder.setPublishedAtStart(since);
        storiesBuilder.setPublishedAtEnd(until);
        storiesBuilder.setSourceName(sourceName);

        try {
            Stories result = apiInstance.listStories(storiesBuilder.build());
            System.out.println(result);
        } catch (ApiException e) {
            System.err.println("Exception when calling DefaultApi#listStories");
            e.printStackTrace();
        }
    }
}

# 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 = {
  :text => '"Hillary Clinton"',
  :published_at_start => "NOW-2DAYS",
  :source_name => ['CNN', 'Fox News']
}


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

package main

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

func main() {
	api := newsapi.NewDefaultApi()

	// Configure API key authorization: app_id
	api.Configuration.APIKeyPrefix["X-AYLIEN-NewsAPI-Application-ID"] = "YOUR_APP_ID"

	// Configure API key authorization: app_key
	api.Configuration.APIKeyPrefix["X-AYLIEN-NewsAPI-Application-Key"] = "YOUR_APP_KEY"

	text := "\"Hillary Clinton\""
	until := "NOW"
	since := "NOW-2DAYS"
	sourceName := []string{"CNN", "Fox News"}

	storiesParams := &newsapi.StoriesParams{
		Text:                     text,
		PublishedAtStart:         since,
		PublishedAtEnd:           until,
		SourceName:               sourceName}

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

	fmt.Println(storiesResponse)
}

using System;
using System.Diagnostics;
using Aylien.NewsApi.Api;
using Aylien.NewsApi.Client;
using Aylien.NewsApi.Model;
using System.Collections.Generic;

namespace Example
{
    public class Example
    {
        static void Main(string[] args)
        {
            
            // Configure API key authorization: app_id
            Configuration.Default.ApiKey.Add("X-AYLIEN-NewsAPI-Application-ID", "YOUR_APP_ID");

            // Configure API key authorization: app_key
            Configuration.Default.ApiKey.Add("X-AYLIEN-NewsAPI-Application-Key", "YOUR_APP_KEY");

            var apiInstance = new DefaultApi();
            
            string text = "\"Hillary Clinton\"";
            string since = "NOW-2DAYS";
            string until = "NOW";
            List sourceName = new List{ "CNN", "Fox News" };

            try
            {
                // List stories
                Stories result = apiInstance.ListStories(text: text, publishedAtStart: since, publishedAtEnd: until, sourceName: sourceName);
                Debug.WriteLine(result);
            }
            catch (Exception e)
            {
                Debug.Print("Exception when calling DefaultApi.ListStories: " + e.Message );
            }
        }
    }
}

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_APP_KEY";

var opts = {
  'text': '"Hillary Clinton"',
  'publishedAtStart': 'NOW-2DAYS',
  'publishedAtEnd': 'NOW',
  'sourceName': ['CNN', 'Fox News']
};

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.listStories(opts, callback);

Visualized Results

We’ve generated the word cloud below to visualize our results. As you can see, the two presidential candidates and their parties are, unsurprisingly, the most mentioned entities from the stories we sourced.

Screen Shot 2016-08-17 at 12.46.24

Of perhaps greater interest, however, are the lesser mentioned (but still very prevalent) entities that can help give us an insight into the key topics that have been discussed in recent days. For example;

Pennsylvania, Ohio, Florida: What is so important about these three most-mentioned states? Since 1960, no US president has been elected without claiming at least two of these states in the election. Aaah!

Visit our documentation for more info on the /trends endpoint.

Next steps

Now that you have learned the basics of using the News API you can start to further explore the various features and endpoints available to you. We’ve laid out everything you need in our interactive documentation with SDKs available in 7 popular programming languages.






News API - Sign up




Author

Avatar

Noel Bambrick

Customer Success Manager @ AYLIEN A graduate of the Dublin Institute of Technology and Digital Marketing Institute in Ireland, Noel heads up Customer Success here at AYLIEN. A keen runner, writer and traveller, Noel joined the team having previously gained experience with SaaS companies in Australia and Canada. Twitter: @noelbambrick

YOU MIGHT ALSO LIKE THESE

Getting Started with the “Text Analysis by AY...
Getting Started with the “Text Analysis by AY...
Product
What section of a LinkedIn profile best repre...
What section of a LinkedIn profile best repre...
Product
Searching and sorting news stories by video a...
Searching and sorting news stories by video a...
Product
Introducing Text Analysis API
Introducing Text Analysis API
Product
Getting started with the News API Part 1: Search
Getting started with the News API Part 1: Sea...
Product
Semantic Labeling added to the Text Analysis ...
Semantic Labeling added to the Text Analysis ...
Product
RIP AlchemyAPI: What to consider before migra...
RIP AlchemyAPI: What to consider before migra...
General, Product, Uncategorized
Text Analysis and Ruby: Getting Started with ...
Text Analysis and Ruby: Getting Started with ...
Product