It’s hard to believe that it has been almost a month since we launched our News API. We have been thrilled with the feedback we have been receiving from our users and wanted to start sharing some useful hints and tips for using the API. Here’s four to begin with 😊.
1. Advanced search using boolean operators
To find what exactly you’re looking for while searching for articles, the News API supports standard boolean search operators such as AND, OR, NOT and brackets in the full-text fields such as Title, Body or Text:
- AND: the AND operator can be used to combine multiple search terms that must appear together. Example: `fashion AND shoes` shows results that include both “fashion” and “shoes”.
- OR: the OR operator can be used to combine multiple search terms that may or may not appear together. Example: `fashion OR shoes` shows results that include “fashion”, “shoes” or both.
- NOT: the NOT or “-” operator can be used to exclude a word or phrase. Example: `fashion NOT shoes` or `fashion -shoes` shows results that include “fashion” but not “shoes”.
- “ ”: double quotes can be used to enforce exact phrase matches. Example: “The Batman Begins” will only match results that include the entire phrase.
- ( ): brackets can be used to group phrases together. Example: `fashion and (shoes or dresses)` matches results that either contain “fashion” and “shoes” OR “fashion” and “dresses”.
Let’s find articles that include “Trump” or “Cruz” in their title, and don’t include “Clinton” nor “Sanders” in their body: API Call:
curl -X GET --header "Accept: application/json" --header "X-AYLIEN-NewsAPI-Application-ID: YOUR_APP_ID" --header "X-AYLIEN-NewsAPI-Application-Key: YOUR_APP_KEY" "https://api.newsapi.aylien.com/api/v1/stories?title=Trump%20OR%20Cruz&body=-Clinton%20-Sanders&language%5B%5D=en&sort_by=published_at&sort_direction=desc&cursor=*&per_page=10"
2. Search article or headline
The News API allows you to search for articles based on the headline, body content or both. Here’s an example: To search for articles that mention “Messi” in their title and “Barcelona” in their body we can run the following query:
curl -X GET --header "Accept: application/json" --header "X-AYLIEN-NewsAPI-Application-ID: YOUR_APP_ID" --header "X-AYLIEN-NewsAPI-Application-Key: YOUR_APP_KEY" "https://api.newsapi.aylien.com/api/v1/stories?title=Messi&language%5B%5D=en&sort_by=published_at&sort_direction=desc&cursor=*&per_page=10"
Other things to try: You can use the above filters together with boolean search (our previous tip) to run more precise queries. For example, search for articles that mention “Donald Trump” in their title, and don’t include any mentions to “Clinton” in their body.
3. Build your own recommendation system and generate related articles based on your own content
Chances are that you have seen the popular “From around the web” feature popping up across a multitude of blogs and news sites on the Internet.Wish you could build your own fully customized version of that? Well look no further.
Using the Related Stories endpoint of the News API, not only can you generate recommendations for articles retrieved through the News API, but also for any other piece of text. All you need is a title and a description. Let’s look at an example: Let’s assume we want to show recommended articles on the Wikipedia article for Hillary Clinton. We can extract the title and a bit of description from the page using a short bit of code, or using the AYLIEN Article Extraction API. From the page we can extract the following:
Title: Hillary Clinton Description: Hillary Diane Rodham Clinton /ˈhɪləri daɪˈæn ˈrɒdəm ˈklɪntən/ (born October 26, 1947) is an American politician. She is a candidate for the Democratic nomination for President of the United States in the 2016 election. She was the 67th United States Secretary of State from 2009 to 2013. From 2001 to 2009, Clinton served as a United States Senator from New York. She is the wife of the 42nd President of the United States Bill Clinton, and was First Lady of the United States during his tenure from 1993 to 2001. Now let’s feed this to the Related Stories endpoint and see what we get back: API Call:
curl -X POST --header "Content-Type: application/x-www-form-urlencoded" --header "Accept: application/json" --header "X-AYLIEN-NewsAPI-Application-ID: YOUR_APP_ID" --header "X-AYLIEN-NewsAPI-Application-Key: YOUR_APP_KEY" -d "story_title=Hillary%20Clinton&story_body=Hillary%20Diane%20Rodham%20Clinton%20%2F%CB%88h%C9%AAl%C9%99ri%20da%C9%AA%CB%88%C3%A6n%20%CB%88r%C9%92d%C9%99m%20%CB%88kl%C9%AAnt%C9%99n%2F%20(born%20October%2026%2C%201947)%20is%20an%20American%20politician.%20She%20is%20a%20candidate%20for%20the%20Democratic%20nomination%20for%20President%20of%20the%20United%20States%20in%20the%202016%20election.%20She%20was%20the%2067th%20United%20States%20Secretary%20of%20State%20from%202009%20to%202013.%20From%202001%20to%202009%2C%20Clinton%20served%20as%20a%20United%20States%20Senator%20from%20New%20York.%20She%20is%20the%20wife%20of%20the%2042nd%20President%20of%20the%20United%20States%20Bill%20Clinton%2C%20and%20was%20First%20Lady%20of%20the%20United%20States%20during%20his%20tenure%20from%201993%20to%202001.&boost_by=recency&per_page=5" "https://api.newsapi.aylien.com/api/v1/related_stories"
And we get the following articles back:
Other things to try: You can use all the regular story filters such as Sentiment, Source or Category filters to further narrow down the scope of the returned stories, e.g. to get related articles with a positive tone, or related stories that are from a specific source, and so on. In the above example we boosted the related stories by recency. You could also boost them by `popularity` to give a higher weight to how popular each story is on social media when sorting the related stories.
4. Trending articles on social media
The News API constantly monitors social media to measure the popularity of each and every article that it retrieves and indexes. This information can be used in two forms: 1. To sort articles by social popularity when searching for articles (using any of the /stories or /related_stories), which can be done by setting the `sort_by` parameter to `social_shares_count`. 2. To profile each article’s popularity over time by looking at its `social_shares_count` property. Let’s get the most popular article that mentions David Bowie from the last 60 days by setting `sort_by` to `social_shares_count` and `per_page` to 1: API Call:
curl -X GET --header "Accept: application/json" --header "X-AYLIEN-NewsAPI-Application-ID: YOUR_APP_ID" --header "X-AYLIEN-NewsAPI-Application-Key: YOUR_APP_KEY" "https://api.newsapi.aylien.com/api/v1/stories?title=%22David%20Bowie%22&language%5B%5D=en&published_at.start=NOW-60DAYS&published_at.end=NOW&categories.confident=true&cluster=false&cluster.algorithm=lingo&sort_by=social_shares_count&sort_direction=desc&cursor=*&per_page=1"
We get the following article that has about 3,000 shares on Facebook:
We continuously and repeatedly profile articles for their social performance, so if you look at the JSON,under the hood you will see something like the following:
Which shows us how the popularity of this article has changed over time.
So there you go. 3 things that you may not have known you could do the AYLIEN News API. Check back regularly as we will be sharing more hints, tips and cool use-cases. Want to try the News API for yourself? Click the image below for a 14-day free trial.