Get started
To get started you'll need an API key. They're free for development, open-source, and non-commercial use and you can get one over here Also we're assuming you know how to make web requests in your chosen programming language. We've included some crude ways to do this in our examples below if you need a place to start. Alternatively you can use one of our client libraries.
I want to show my users live top and breaking news headlines
News API is great as a data source for news tickers and other applications where you want to show your users live headlines. We track headlines in 20 categories across over 60 countries, and at over a hundred top publications and blogs, in near real time. Let's make a request to get live top headlines in the US right now. We'll use the /top-headlines endpoint for this.
//Insert your api key here, if you dont have get one from web.geetmark.com
$myKey = "myKey";
$url = "https://web.geetmark.com/api/news/data/?country=". $country ."&category=".$category . "&key=".$myKey."&language=".$language."&page=".$page;
$ch = curl_init();
curl_setopt($ch,CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_HEADER, 0);
$resp = curl_exec($ch);
// print_r($resp);
curl_close($ch);
$json = json_decode($resp);
print_r($json);
var url = 'https://web.geetmark.com/api/news/data/?' +
'ty=top-headlines&' +
'country=us&' +
'Key=myKey';
var req = new Request(url);
fetch(req)
.then(function(response) {
console.log(response.json());
})
import requests
url = ('https://web.geetmark.com/api/news/data/?country=us&key=myKey')
response = requests.get(url)
print response.json()
using System.Net;
var url = "https://web.geetmark.com/api/news/data/?" +
"country=us&" +
"key=myKey";
var json = new WebClient().DownloadString(url);
Console.WriteLine(json);
Top headlines in the US right now
Everything /?ty=everything
- we index every recent news and blog article published by over 80,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.
Request parameters
country
The 2-letter ISO 3166-1 code of the country you want to get headlines for.
Possible options:
Code | Country & Language |
---|---|
/?country=DE&language=de | Deutsche |
/?country=BD&language=bn | বাংলা |
/?country=BG&language=bg | България |
/?country=CN&language=zh | 中文 |
/?country=TW&language=zh | 繁體中文-台灣 |
/?country=KR&language=ko | 한국어 |
/?country=DK&language=da | Dansk |
/?country=ZA&language=en | English - South Africa |
/?country=AU&language=en | English - Australie |
/?country=CA&language=en | English - Canada |
/?country=US&language=en | English - United States |
/?country=ZZ&language=en | English - Global |
/?country=NG&language=en | English - Nigeria |
/?country=PK&language=en | English - Pakistan |
/?country=PH&language=en | English - Philippines |
/?country=GB&language=en | English - United Kingdom |
/?country=ES&language=es | Español - España |
/?country=MX&language=es | Español - México |
/?country=FR&language=fr | Français - France |
/?country=IN&language=hi | हिंदी |
/?country=BE&language=nl | Hollandais - Belgique |
/?country=NL&language=nl | Hollandais - Pays-bas |
/?country=ID&language=id | Indonésien |
/?country=IT&language=it | Italiano |
/?country=JP&language=ja | 日本人 |
/?country=NO&language=no | Norsk |
/?country=PL&language=pl | Polskie |
/?country=BR&language=pt | Portugues - brasil |
/?country=PT&language=pt | Portugues - portugal |
/?country=CZ&language=cs | Czech Republic |
/?country=RU&language=ru | Русский - Россия |
/?country=SE&language=sv | Svenska |
/?country=TH&language=th | ไทย |
/?country=TR&language=tr | Türk |
/?country=UA&language=uk | Український |
/?country=VN&language=vi | Tiếng Việt |
/?country=AE&language=ar | العربية (الإمارات العربية المتحدة) |
/?country=BH&language=ar | العربية (البحرين) |
/?country=DZ&language=ar | العربية (الجزائر) |
/?country=EG&language=ar | العربية (مصر) |
/?country=IQ&language=ar | العربية (العراق) |
/?country=JO&language=ar | العربية (الأردن) |
/?country=KW&language=ar | العربية (الكويت) |
/?country=LB&language=ar | العربية (لبنان) |
/?country=LY&language=ar | العربية (ليبيا) |
/?country=MA&language=ar | العربية (المغرب) |
/?country=OM&language=ar | العربية (عمان) |
/?country=QA&language=ar | العربية (قطر) |
/?country=SA&language=ar | العربية (السعودية) |
/?country=SY&language=ar | العربية (سوريا) |
/?country=TN&language=ar | العربية (تونس) |
/?country=YE&language=ar | العربية (اليمن) |
category
The category you want to get headlines for. Possible options:
animals art business cinema culture economy entertainment fashion food health humour medias music politic science social sports technology
Code | Category |
---|---|
/?country=animals | Animals |
/?country=art | Art |
/?country=business | Business |
/?country=cinema | Cinema |
/?country=culture | Culture |
/?country=economy | Economy |
/?country=entertainment | Entertainment |
/?country=fashion | Fashion |
/?country=food | Food |
/?country=health | Health |
/?country=humour | Humour |
/?country=medias | Medias |
/?country=music | Music |
/?country=politic | Politics |
/?country=science | Science |
/?country=social | Social |
/?country=sports | Sports |
/?country=technology | Technology |
q
Keywords or a phrase to search for.
page
Use this to page through the results if the total results found is greater than the page size.
Response object
status
If the request was successful or not. Options: ok, error. In the case of error a code and message property will be populated.return string
totalResults
The total number of results available for your request. return int
articles
The results of the request. return array[article]
name | message | return |
---|---|---|
title | The headline or title of the article. | String |
description | A description or snippet from the article. | String |
url | The direct URL to the article. | String |
publishedAt | The date and time that the article was published, in UTC (+000) | String |
image | The URL to a relevant image for the article. | String |
source | The identifier id and a display name name for the source this article came from. | String |
author | The author of the article | String |
Authentication
Authentication is handled with a simple API key.
Your API key is: 825dfdffe0dff88e0dff88e032dd9
You can attach your API key to a request in one of three ways:
Via the apiKey querystring parameter.
Via the X-Api-Key HTTP header.
Via the Authorization HTTP header. Bearer optional, do not base 64 encode.
We strongly recommend the either of latter 2 so that your API key isn't visible to others in logs or request sniffing.
If you don't append your API key correctly, or your API key is invalid, you will receive a 401 - Unauthorized HTTP error.
Errors
If you make a bad request we'll let you know by returning a relevant HTTP status code along with more details in the body.
Client libraries
Use a client library (SDK) to quickly and easily get started with News API without worrying about the underlying set up.
We have libraries for the following languages: