Working with Entities


An “entity” or “named 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.

To make the definition of entities clearer, let's consider the role of the word "apple" in the following sentences:

  • Apple is a great source of vitamins.
  • Apple was founded by Steve Jobs and Steve Wozniak.

In the first sentence, "apple" refers to the following entity:

  • Text (also called surface form): "Apple"
  • Name: Apple
  • Type: Fruit, Eukaryote, Plant, etc.
  • Unique identifier:

Whereas in the second sentence, "apple" represents a different entity:

  • Text: "Apple"
  • Name: Apple Inc.
  • Type: Company, Organization, etc.
  • Unique identifier:

In the News API, we extract entities found in the title and the body of each individual story, and you can filter your search results in most endpoints based on these values.

Searching by Entities

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

  • : List of surface forms for entities found in the story title
  • : List of types for entities found in the story title
  • : List of identifiers (DBpedia URI) for entities found in the story title
  • : List of surface forms for entities found in the story body
  • : List of types for entities found in the story body
  • : List of identifiers (DBpedia URI) for entities found in the story body

These parameters allow you to first decide where in the article (title or body) the desired entity(ies) should appear. Secondly, you can search based on entity names (e.g. "Apple" or "Kim Kardashian"), entity types (e.g. Person or College) and/or entity links (e.g.

DBpedia Links and 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 the structured counterpart of Wikipedia, where distinct entities are given URIs, and their attributes and relations to other entities are presented in a graph structure.

Using DBpedia links or URIs to refer to entities has several advantages. Most importantly, it enables the party presenting information and the party receiving information to ensure that they are referring to the same exact thing and eliminate ambiguity as they communicate with each other.

For instance if two well-known people share the same name (e.g. Michael Jackson), we could differentiate them by using their DBpedia identifiers: for the entertainer and for the basketball player.

While using the News API, if you wish to focus on a well-known entity, by using its DBpedia link you can clarify your intent unambiguously, to reduce the number of false positives.

Additionally, knowing the DBpedia link of an entity enables us to query DBpedia (or Freebase) to retrieve additional information about that entity. For instance, to retrieve a list of all Apple products, we can run the following query through DBpedia's SPARQL interface:

select ?products where {
  <> <> ?products 
(try it here)

Since DBpedia contains URIs for all of Apple's products, we can query the News API to retrieve stories that mention any of Apple's products.

Finding DBpedia URIs for Entities

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 and provide all or a part of the entity's name using the parameter.

Similarly, you can search over all entity types by setting 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 ( or ) instead.

DBpedia Types

The DBpedia project has its own extensive ontology for entity types, which goes beyond the common types such as person, organization or place. For a complete list of these, refer to the Ontology Classes document on the DBpedia project website.

To filter based on DBpedia types, you can simply use the and/or parameters.

Note: For simplicity, we omit the "" prefix from DBpedia type strings. For instance, to retrieve all stories where any Member of Parliament (DBpedia type is mentioned in the title, you can set .


The following example shows articles that are in English, mention Harvey Norman or Apple Inc. in the body, 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 = {
  'entitiesBodyLinksDbpedia': [
  'language': ['en'],
  'publishedAtStart': 'NOW-1DAY',
  'publishedAtEnd': 'NOW'

var callback = function(error, data, response) {
  if (error) {
  } else {
    console.log('The API has been called successfully.');
    for (var i = 0; i < data.stories.length; i++){
      console.log(data.stories[i].title + " / " + data.stories[i];
apiInstance.listStories(opts, callback);
import aylien_news_api
from 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()

opts = {
  'entities_body_links_dbpedia': [
  'language': ['en'],
  'published_at_start': 'NOW-1DAY',
  'published_at_end': 'NOW'

    # List stories
    api_response = api_instance.list_stories(**opts)
    print('The API has been called successfully.')
    for story in api_response.stories:
      print(story.title + " / " +
except ApiException as e:
    print("Exception when calling DefaultApi->list_stories: %s\n" % e)
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(
  'entities_body_links_dbpedia' => [
  'language' => ['en'],
  'published_at_start' => 'NOW-1DAY',
  'published_at_end' => 'NOW'

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

        // Configure API key authorization: app_key
        ApiKeyAuth app_key = (ApiKeyAuth) defaultClient.getAuthentication("app_key");

        DefaultApi apiInstance = new DefaultApi();

        StoriesParams.Builder storiesBuilder = StoriesParams.newBuilder();


        try {
            Stories result = apiInstance.listStories(;
            for (Iterator<Story> i = result.getStories().iterator(); i.hasNext();){
                Story story =;
                System.out.println(story.getTitle() + " / " + story.getSource().getName());
        } catch (ApiException e) {
            System.err.println("Exception when calling DefaultApi#listStories");
# 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'

api_instance =

opts = {
  :entities_body_links_dbpedia => [
  :language => ['en'],
  :published_at_start => "NOW-1DAY",
  :published_at_end => "NOW"

  #List stories
  result = api_instance.list_stories(opts)
  puts 'The API has been called successfully.'
  puts '====================================='
  result.stories.each do |story|
    puts "#{story.title} / #{}"
rescue AylienNewsApi::ApiError => e
  puts "Exception when calling DefaultApi->list_stories: #{e}"
  puts e.response_body
package main

// Import the library
import (
    newsapi ""

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"

    storiesParams := &newsapi.StoriesParams{
        EntitiesBodyLinksDbpedia: []string{
        Language:         []string{"en"},
        PublishedAtStart: "NOW-1DAY",
        PublishedAtEnd:   "NOW"}

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

    fmt.Println("The API has been called successfully.")
    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)
            // 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();

                // List stories
                Stories storiesResponse = apiInstance.ListStories(
                    entitiesBodyLinksDbpedia: new List<String> { 
                        "" },
                    language: new List<String> { "en" },
                    publishedAtStart: "NOW-1DAY",
                    publishedAtEnd: "NOW"

                Console.WriteLine("The API has been called successfully.");
                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);