Working with Categories

About

Knowing the high-level semantic category of stories can be extremely helpful.

Taxonomies

Our classifier is capable of classifying content into two taxonomies. Below you can see a list of these taxonomies and their definitions.

Taxonomy Supported Languages Number of classes Levels of depth Commonly used for Taxonomy ID Definition
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

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.

Each classification result contains an object of links, which contains links to the current taxonomy label (rel=self) as well as its parent(s), if any (rel=parent).

To retrieve the entire taxonomy, you can simply remove the category ID from the end of the link attribute, e.g. https://api.aylien.com/api/v1/classify/taxonomy/iab-qag.

Examples

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

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 = {
  'language': ['en'],
  'publishedAtStart': 'NOW-1DAY',
  'publishedAtEnd': 'NOW',
  'categoriesTaxonomy': 'iab-qag',
  'categoriesId': ['IAB15']
};

var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.listStories(opts, callback);
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()

language = ['en']
since = 'NOW-1DAY'
until = 'NOW'
categories_taxonomy = 'iab-qag'
categories_id = ['IAB15']


try:
    # List stories
    api_response = api_instance.list_stories(language=language,
                                             published_at_start=since,
                                             published_at_end=until,
                                             categories_taxonomy=categories_taxonomy,
                                             categories_id=categories_id)
    print(api_response)
except ApiException as e:
    print("Exception when calling DefaultApi->list_stories: %s\n" % e)
<?php
require_once(__DIR__ . '/vendor/autoload.php');

// Configure API key authorization: app_id
Aylien\NewsApi\Configuration::getDefaultConfiguration()->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(
  'published_at_start' => 'NOW-1DAY',
  'published_at_end' => 'NOW',
  'language' => ['en'],
  'categories_taxonomy' => 'iab-qag',
  'categories_id' => ['IAB15']
);

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

    List<String> language = new ArrayList<String>()  {{
        add("en");
    }}; 
    String since = "NOW-1DAY";
    String until = "NOW";
    String categoriesTaxonomy = "iab-qag";
    List<String> categoriesId = new ArrayList<String>()  {{
        add("IAB15");
    }}; 

    storiesBuilder.setLanguage(language);
    storiesBuilder.setPublishedAtStart(since);
    storiesBuilder.setPublishedAtEnd(until);
    storiesBuilder.setCategoriesTaxonomy(categoriesTaxonomy);
    storiesBuilder.setCategoriesId(categoriesId);

    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 = {
  :published_at_start => "NOW-1DAY",
  :published_at_end => "NOW",
  :language => ["en"],
  :categories_taxonomy => "iab-qag",
  :categories_id => ["IAB15"]
}


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"

	until := "NOW"
	since := "NOW-1DAY"
	language := []string{"en"}
	categoriesTaxonomy := "iab-qag"
	categoriesId := []string{"IAB15"}

	storiesParams := &newsapi.StoriesParams{
		Language:           language,
		PublishedAtStart:   since,
		PublishedAtEnd:     until,
		CategoriesTaxonomy: categoriesTaxonomy,
		CategoriesId:       categoriesId}

	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 since = "NOW-1DAY";
            string until = "NOW";
            List<String> language = new List<String> { "en" };
            string categoriesTaxonomy = "iab-qag";
            List<String> categoriesId = new List<String> { "IAB15" };

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