At AYLIEN we pride ourselves on creating robust, scalable, developer friendly tools. We do our best to make it as easy as possible for our users to get up and running with our APIs. In this post we’re going to talk you through the process of making calls to our News API.
Our News API allows you to search and source news content from around the web in realtime. We use Machine Learning and Natural Language Processing to monitor, source and index news content at scale, providing an enriched and flexible news data source.
While making calls to the API is relatively simple, the possibilities for what you can do with the API are endless and the number of endpoints and parameters available can sometimes feel a little overwhelming to new users. For that reason we have decided to put together a series of blog posts aimed at guiding our users through some basic capabilities of the API.
This post will serve as a gentle introduction to the basic search capabilities of the API. Part 2 will then focus on how to analyze and draw meaningful insights from your stories.
First things first – familiarize yourself with the API
We recommend that you spend some time creating example queries using our demo/query builder. Once you’ve familiarised yourself with the concept of the API we’d strongly recommend spending some time in the interactive documentation section of our website to learn more about the various endpoints and parameters available in the API.
When you’ve got your head around how the API works, you can begin making some basic calls and collecting stories.
We’ve created SDKs for some of the most popular programming languages which make using the API super easy. Throughout this blog we’ve also included some code snippets for you to copy and build on.
1. Basic Search
Firstly, let’s look at how we can start monitoring news content and collecting stories. For the purpose of this guide we’ll assume the role of a news agency who want to gather news stories and insights around the presidential elections in the US.
Our API supports Boolean Search which allows you to build simple search queries using standard boolean operators. This means that you can build general or more targeted queries based on your interests and requirements.
The easiest way to start getting useful data from the API is to start collecting stories based around a search that interests you. As an example, let’s create a search that retrieves stories relevant to the US elections based on simple criteria;
Let’s build a query to retrieve stories that mention Donald Trump and Hillary Clinton that were published in the last 10 days and were written in Spanish.
The `text` parameter allows us to search by keyword. The ‘language’ parameter let’s you choose the language the stories are written in, and the `publishedAt` parameter allows you to easily set timeframes around when the articles you wish to retrieve have been published.
Note: Make sure you replace the APP_ID and APP_KEY placeholders with your own API credentials. If you haven’t got an API account you can sign up here.
Combined: “Donald Trump” AND “Hillary Clinton” in Spanish from the past 10 days
2. Targeted search
So we’ve looked at how you can use keywords and some other basic parameters like the ‘published at’ time to build some useful queries. Now let’s look at how you can use some other parameters and endpoints to build some more targeted searches.
As with any election, opinions often tend to vary by geographic location. This is evident each time a US presidential election takes place as individual states are deemed ‘Red’ or ‘Blue’ depending on their republican or democratic bias. As we know, however, it is often the ‘swing’ states that well, swing the outcome one way or the other! These states and the news around them can be of particular interest to analysts, writers and the candidates themselves.
With this in mind, we’ll now show you how to narrow your search to focus on particular entities (places, people, companies, etc), from within specific categories and news sources. The parameters we will use here are:
For this example, we will search for mentions of two entities, which are traditionally two swing states: Ohio and Florida. We also want to ensure we are only collecting relevant stories so we will search for articles that are classified as in the Law, Government and Politics category. We will also only focus our search on three popular news sources: CNN, CBS News and Reuters
Our next search will focus on finding stories with a particular sentiment polarity from a particular geographic region. While our previous entities search focused on stories about specific locations (Ohio & Florida), this search will focus on stories from outlets in a specific location.
We’re going to search for negative stories, mentioning Trump, from sources based in Mexico.
As before, we will use the `text` parameter to indicate ‘Trump’ as our keyword. You could also use `title` if you wished to search for mentions of Trump in the article title only. The parameter sentiment.title.polarity is set to ‘negative’ and `source.locations.country` to ‘MX’.
There you have it. We hope that this gentle introduction to using our News API has helped you get started with the basics, making calls and creating specific search queries. Of course, the API is more than just a news aggregator and we have merely scratched the surface of what this awesome tool is capable of today. You will see the true power and benefits of the API as you begin to explore some of the more advanced capabilities it offers from an analysis and insights point of view.
Check back next week for Part 2 where we will be showing you how easy it is to use the API to look for insights, trends and correlations in news content.