Welcome!

The AYLIEN News API is the most powerful way of sourcing, searching, and syndicating analyzed news content. On this page, we’ll help you get up and running and give you some code to make your first calls. Specifically, you’ll:

• build a simple search to retrieve your first news stories,
• filter stories by topics discussed and entities mentioned,
• search for stories from sources around the globe and access content translated from multiple human languages,
• use the quantitative analysis endpoints to see aggregated trends.

Before we start:

Not an SDK fan? You can use raw HTTP requests instead - the URLs and parameters for calling each endpoint are listed in the documentation pages for each one.

Prefer iPython Notebooks? Check out this walkthrough with some cool data visualizations here.

Also, for a more detailed introduction to the News API, check out this introductory blog series. With that out of the way, let's dive in!

Install your SDK

pip install aylien-news-api

We're assuming you have your SDK installed already, but if you don't, you can install them using various package managers or by cloning repos from GitHub. You can find full instructons for installing your chosen SDK here.

The JSON story object

Stories you retrieve from the News API are returned as JSON objects by default. These JSON story objects contain 22 top-level fields, whereas a full story object will contain 95 unique data points.

Note that you can use most of these data points as query parameters in calls to the Stories endpoint, so when you see a field that contains information that is important to you, you can use these as filters in your searches.

We can group the data in the JSON object into three types:

• the story data (e.g. the story body, title),
• story metadata (e.g. word count, publication date, and time),
• NLP enrichments - insights generated by our NLP engine about the story (the topics discussed, the entities mentioned, the real-world event the story refers to, and much more).

To see more detail on the data returned within the JSON object, take a look at this introductory blog.

Basic story search: keywords, dates, sorting

import aylien_news_api
from aylien_news_api.rest import ApiException
from pprint import pprint as pp

## Configure your connection to the API
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_API_KEY'
configuration.host = "https://api.aylien.com/news"
api_instance = aylien_news_api.DefaultApi(aylien_news_api.ApiClient(configuration))

## List our parameters as search operators
opts= {
    'title': '"Bank of America" OR "Deutsche Bank"',
    'body': 'fraud',
    'language': ['en'],
    'published_at_start': 'NOW-7DAYS',
    'published_at_end': 'NOW',
    'per_page': 1,
    'sort_by': 'relevance'
}

try:
    ## Make a call to the Stories endpoint for stories that meet the criteria of the search operators
    api_response = api_instance.list_stories(**opts)
    ## Print the returned story
    pp(api_response.stories)
except ApiException as e:
    print('Exception when calling DefaultApi->list_stories: %s\n' % e)

The code snippet on the right will get you started with your first call to the News API's Stories endpoint (remember to paste in your credentials before you run it). It returns a story from the past seven days that mentions either "Bank of America" or "Deutsche Bank" in the title, and “fraud” in the body.

Remember to always include a language parameter specifying the languages you want to retrieve content in - this ensures the most accurate results.

The published_at parameters accept both Date Math Syntax (as in the snippet) and dates in the format 2020-01-23T00:00:00Z.

The per_page parameter here has been supplied with the value of 1, meaning we will retrieve one story, but this can be set as high as 100. If you want to source more than 100 stories, you can use cursor. This parameter defaults to 10.

The sort_by parameter allows you to sort results according to six criteria:

• Relevance
• Recency
• Hotness
• Number of photos/videos
• Alexa ranking of domain (global/national)

Targeted story search: categories & entities

import aylien_news_api
from aylien_news_api.rest import ApiException

configuration = aylien_news_api.Configuration()
configuration.api_key['X-AYLIEN-NewsAPI-Application-ID'] = 'YOUR_API_KEY'
configuration.api_key['X-AYLIEN-NewsAPI-Application-Key'] = 'YOUR_API_KEY'
configuration.host = "https://api.aylien.com/news"

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

opts= {
    'entities_links_wikipedia': ['https://en.wikipedia.org/wiki/Citizens_Financial_Group'],
    'entities_types': ['Bank'],
    'categories_taxonomy': 'iptc-subjectcode',
    'categories_id': ['04006002'],
    'language': ['en'],
    'per_page': 20,
    'sort_by': 'recency'
}

try:
    ## Make a call to the Stories endpoint for stories that meet the criteria of the search operators
    api_response = api_instance.list_stories(**opts)
    for story in api_response.stories:
        ## Print the title, source, and date of each story
        print("{}  ||  {}  ||  {}".format(story.published_at, story.source.name, story.title))
except ApiException as e:
    print('Exception when calling DefaultApi->list_stories: %s\n' % e)

To leverage some more of the News API’s capabilities, we’re going to use a sample script that utilizes some of the NLP enrichments as parameters in our search, namely the categories and entities parameters.

Instead of searching for a keyword in the title, this script on the right uses the entities parameter to search for Citizens Bank. This is useful because the keyword "citizen" refers to concepts other than the bank, and by understanding every news story it ingests, the News API will filter out stories that refer to these other concepts.

Also, we are now limiting our search to the banking category of the IPTC taxonomy (code 04006002), so stories about the bank in other topics (like politics, for example) will be filtered out.

To see news about all banks instead of just Citizens Bank, comment out the entities_title_links_dbpedia parameter and the uncomment the entities_title_type parameter. This leverages one of the NLP enrichments in the entities story field.

Again, be sure to to play around with the parameters and check out the support guides. For categories:

• Find the category code for the topic that interests you (searchable table)
• Which taxonomy is best for your use case? (blog post)
• Working with categories (documentation)

For entities:

• Working with entities (documentation)
• Leveraging entity types (blog post)

Global story search: source location & story language

import aylien_news_api
from aylien_news_api.rest import ApiException

configuration = aylien_news_api.Configuration()
configuration.api_key['X-AYLIEN-NewsAPI-Application-ID'] = 'YOUR_API_KEY'
configuration.api_key['X-AYLIEN-NewsAPI-Application-Key'] = 'YOUR_API_KEY'
configuration.host = "https://api.aylien.com/news"

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

opts= {
    # 'not_language': ['en'],
    'language': ['ru'],
    'source_locations_country': ['RU'],
    'translations_en_body': '"crime" OR "fraud" OR "laundering"',
    'published_at_start': 'NOW-60DAYS',
    'sort_by': 'relevance'
}

try:
    api_response = api_instance.list_stories(**opts)
    for story in api_response.stories:
        print("{}  ||  {}  ||  {} \n{} \n ".format(story.source.name, story.title, story.translations.en.title, story.links.permalink))
except ApiException as e:
    print('Exception when calling DefaultApi->list_stories: %s\n' % e)

The News API enables us to retrieve content from around the world across 16 languages.

To refine our search to sources in a given country, we use the source_locations_country parameter, which accepts ISO-formatted country codes. In the script on the right, we're limiting our search to publishers located in Russia. You can also search by source_locations_state and source_locations_city.

To search for stories in the Russian language, we set the language parameter to "ru" (note that language ISO codes need to be lower case while country codes need to be capital case). To search for keywords in the body of Russian-language stories, we can either supply a transliterated Russian keyword to the body parameter ("Путин" for "Putin"), or search the English keyword in the translations_en_body parameter.

To see content across multiple non-English languages and countries around the globe, uncomment the not_language parameter and comment out the language parameter. source_locations_country.

Time series data

import aylien_news_api
from aylien_news_api.rest import ApiException
from pprint import pprint as pp

configuration = aylien_news_api.Configuration()
configuration.api_key['X-AYLIEN-NewsAPI-Application-ID'] = 'YOUR_API_KEY'
configuration.api_key['X-AYLIEN-NewsAPI-Application-Key'] = 'YOUR_API_KEY'
configuration.host = "https://api.aylien.com/news"

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

opts= {
    'title': 'Trump',
    'published_at_start': 'NOW-50DAYS',
    'period': '+1DAY'
}

try:
    api_response = api_instance.list_time_series(**opts)
    pp(api_response)

except ApiException as e:
    print('Exception when calling DefaultApi->list_stories: %s\n' % e)

In addition to retrieving stories themselves, the Time Series endpoint provides the count of stories published over time matching your parameters. Calls to this endpoint don't return stories, and therefore do not count toward your story allowance. Instead, they return JSON time series objects, like this one:

You can use the script on the right to make your first call to the Time Series endpoint.

The published_at parameters specify the time frame we want to retrieve data on, while the period parameter specifies the length of time covered by each data point return in the results. The period parameter can be set as low as one minute, but defaults to one day. The endpoint can return up to 100 data points per page.

In this script, we will receive data from the past seven days, with one data point from each day. To see more granular data, try setting the period parameter to "+30MINUTES", and the published_at_start parameter to "NOW-1DAY". Likewise you can increase the period and published_at_start parameters to look at data over a longer time period.

Analyzing trends

import aylien_news_api
from aylien_news_api.rest import ApiException
from pprint import pprint as pp 

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

## Add the 'field' you want to retrieve data on
field = "entities.body.links.dbpedia"

opts= {
    'title': 'Trump'
}

try:
    ## Make a call to the Trends endpoint using the operators and field arguments
    api_response = api_instance.list_trends(field, **opts)
    print(api_response)

except ApiException as e:
    print('Exception when calling DefaultApi->list_stories: %s\n' % e)

The Trends endpoint is used to analyze quanitative data from the News API that is not spread over time.

The script on the right gives a sample use case of the this endpoint, returning a list of the most-mentioned entities in stories with "Trump" in the title over one sample week. Once again, it returns its own JSON trends object, like the one below.

Notice that you need to specify the field parameter to define what type of data you want to retrieve from the API. There are 14 values that the field parameter accepts.

What next?

Now that you're up and running with the News API, be sure to check out the product-oriented posts or take a look at the documentation for each endpoint.