Guide to use News API in 5 minutes for Free !
In this article, we will show you how to use News API to its full potential and the range of news headlines that you are able to retrieve using its FREE version.
Documentation News API is a simple HTTP REST API for searching and retrieving live articles from all over the web. It can help you answer questions like:
Any news today for Samsung ?
What is the top 10 news headline for BBC ?
How many sources do we get the news from ?
You can search for articles with any combination of the following criteria:
Keyword or phrase. Eg: find all articles containing the word ‘Telsa’.
Date published. Eg: find all articles published last month.
Source name. Eg: find all articles by ‘Elon Musk’.
Source domain name. Eg: find all articles published on techcrunch.com.
Language. Eg: find all articles written in Italian.
GET API KEY
First you need an API key to use the API — this is a unique key that identifies your requests.
To start off, we would need to first obtain an API key first, simply fill out the form below and you would be provided the API key sent to your registered email.
News API has 2 main endpoints:
Top headlines /v2/top-headlines
This end point returns breaking news headlines for a country and category, or currently running on a single or multiple sources.
This is perfect for use with news tickers or anywhere you want to display live up-to-date news headlines and images.
For this end point, we index every recent news and blog article published by over 50,000 different sources large and small, and you can search through them with this endpoint.
This endpoint is better suited for news analysis and article discovery, but can be used to retrieve articles for display too.
We also have a minor endpoint that can be used to retrieve a small subset of the publishers we index from:
- Sources /v2/sources
This end point returns information (including name, description, and category) about the most notable sources we index.
This list could be piped directly through to your users when showing them some of the options available.
Lets start with top news headlines.
Top headlines /v2/top-headlines
I have created a customized script for your own convenience where you can download it on my GitHub portfolio :)
Create a URL
First we will first need to create a URL for top category news headlines, to do that we would need to refer to the documentation for News API headlines endpoint.
We can see the request parameters available for top news headlines below.
Once we have the request parameters, the next thing is to create a URL .
catenewsheadlinesurl = ('http://newsapi.org/v2/top-headlines?' 'q=trump&' #the keyword we are looking for 'country=us&' #we chose the country we want 'category=general&' #we chose the category we want 'language=en&' #we chose the language we want 'pageSize=30&' #no. of results. Default 20, max 100 'apiKey=Your_api_key') # Your Api keys
In the above example, we would like to find :
- Using “trump” as the keyword
- Within United States (Country)
- Under General category
- With English Language
- Return result of 30
- API key (Your own API key)
Of course you can change the request parameters according to what you would like to find in the news headlines!
Create the request to GET news headlines
catenewsheadlinesurlresponse = requests.get(catenewsheadlinesurl)Test the connection if it returns 200 means connection is ready
catenewsheadlinesurlresponse<Response [200]>
Below are the possible errors that you might get.
HTTP status codes summary
- 200 — OK. The request was executed successfully.
- 400 — Bad Request. The request was unacceptable, often due to a missing or misconfigured parameter.
- 401 — Unauthorized. Your API key was missing from the request, or wasn’t correct.
- 429 — Too Many Requests. You made too many requests within a window of time and have been rate limited. Back off for a while.
- 500 — Server Error. Something went wrong on our side.
Error codes
When an HTTP error is returned we populate the code and message properties in the response containing more information. Here are the possible options:
- apiKeyDisabled — Your API key has been disabled.
- apiKeyExhausted — Your API key has no more requests available.
- apiKeyInvalid — Your API key hasn’t been entered correctly. Double check it and try again.
- apiKeyMissing — Your API key is missing from the request. Append it to the request with one of these methods.
- parameterInvalid — You’ve included a parameter in your request which is currently not supported. Check the
messageproperty for more details. - parametersMissing — Required parameters are missing from the request and it cannot be completed. Check the
messageproperty for more details. - rateLimited — You have been rate limited. Back off for a while before trying the request again.
- sourcesTooMany — You have requested too many sources in a single request. Try splitting the request into 2 smaller requests.
- sourceDoesNotExist — You have requested a source which does not exist.
- unexpectedError — This shouldn’t happen, and if it does then it’s our fault, not yours. Try the request again shortly.
Convert headlines to JSON format
catenewsheadlines=catenewsheadlinesurlresponse.json()Below is an example of what you would get after converting to JSON format.
You can see that the JSON format is organised nicely into shown in the documentation below:
- ‘articles’
- ‘status’
- ‘totalResults’
Extract the articles column and convert it to data-frame.
catenewsheadlines = catenewsheadlines['articles']
df = pd.DataFrame(catenewsheadlines)You can see that they will be classified as per documentation below.
There you go ! You have successfully managed to obtain top news headlines on trump from difference news sources for today!
As this is a developer version(Free) , I would like to point out there is a limit to how many news headlines you can obtain.
For commercial purpose, you can visit their pricing options.
The method for the other endpoints will be about the same.
If you are interested to obtain the script for all the endpoints , you can visit my Github to download my script !
You can use my script to search any kind of news that you are interested in.
Have fun playing with it , its free anyway !
