Getting Started
Before getting started, you need a API key. We provide free plans for development, open-source, and non-commercial use, you can apply here first.
You also need to know how to make web requests in your preferred programming language. We have included some basic ways to do in our examples below if you need a place to start. However, we also provide client libraries in Node.js, Python, and R for quick start.
You can also jump right in to explore our API endpoints here using Swagger. But do remember to get your free API key by signing up first. For more details about the endpoints and modifiers you can lookup articles with, including possible responses, check the full documentation.
We will go through how our API using two examples:
1. Grab the latest news in your preferred language
2. Obtain filtered historical data by applying certain criterias
Access latest news
Currents API provide news in 15 different languages across over 50 countries in forms of news, article, forum discussion topics. We also have packages build to support access to this service in Node.js, Python, and R.
In this example we will focus in getting the latest, near live news from English using the endpoint /latest-news. We'll use the /latest-news endpoint for this.
This returns a JSON object with the results in an array we can iterate over. We limited the results to the top 5 for illustration purposes. Actual number of results varies depending on the query itself
{
"status": "ok",
"news": [
{
"id": "e1749cf0-8a49-4729-88b2-e5b4d03464ce",
"title": "US House speaker Nancy Pelosi backs congressional legislation on Hong Kong",
"description": "US House speaker Nancy Pelosi on Wednesday threw her support behind legislation meant to back Hong Kong's anti-government protesters.Speaking at a news conference featuring Hong Kong activists Joshua Wong Chi-fung and Denise Ho, who testified before the Congressional-Executive Commission on China (C...",
"url": "https://www.scmp.com/news/china/politics/article/3027994/us-house-speaker-nancy-pelosi-backs-congressional-legislation",
"author": "Robert Delaney",
"image": "None",
"language": "en",
"category": [
"world"
],
"published": "2019-09-18 21:08:58 +0000"
},
{
"id": "76b7101b-8170-4314-8036-477b97776d27",
"title": "Congress moving quickly on bill to support Hong Kong protesters",
"description": "(Sept 18): Momentum is building for quick action in Congress to pressure China to back off any crackdown on pro-democracy protesters by threatening Hong Kong's special trading status with the U.S.\nLegislation is moving through the House and Senate that would require annual assessments of whether the...",
"url": "http://www.theedgemarkets.com/article/congress-moving-quickly-bill-support-hong-kong-protesters",
"author": "shireen.koshy",
"image": "None",
"language": "en",
"category": [
"politics",
"business"
],
"published": "2019-09-18 20:35:04 +0000"
},
{
"id": "3ed38e9e-f825-48ca-aa79-2cc7201ff241",
"title": "Hong Kong hotel workers go on unpaid leave as tourists shun city",
"description": "As the protests in Hong Kong drive away visitors, the city\u2019s hotel workers are in the firing line.",
"url": "https://sg.finance.yahoo.com/news/hong-kong-hotel-workers-go-on-unpaid-leave-as-tourists-shun-city-073722827.html",
"author": "Bloomberg",
"image": "https://s.yimg.com/uu/api/res/1.2/y5C.6QPFXkZKJyM5u8dT2g--~B/aD0zMzQwO3c9NTAxMDtzbT0xO2FwcGlkPXl0YWNoeW9u/https://media-mbst-pub-ue1.s3.amazonaws.com/creatr-images/2019-09/c5ccb950-d9e4-11e9-afff-6ee6ea2f5ee4",
"language": "en",
"category": [
"regional"
],
"published": "2019-09-18 19:53:25 +0000"
},
{
"id": "70af452f-40a3-4131-bbd2-201e4cc1d727",
"title": "Budweiser maker revives Hong Kong IPO plan with reduced ambitions",
"description": "The maker of Budweiser and Stella Artois beers has revived plans to list its Asia unit in Hong Kong, saying it wants to raise almost $5 billion in what would be the world's second-biggest initial public offering this year. The decision by Belgium-listed Anheuser-Busch InBev to sell the stake will",
"url": "https://sg.news.yahoo.com/budweiser-maker-revives-hong-kong-ipo-plan-reduced-041515087--finance.html",
"author": "AFP News",
"image": "https://s.yimg.com/uu/api/res/1.2/.C5lyuXzK7xnGFqsfNz1lA--~B/aD01MTI7dz03Njg7c209MTthcHBpZD15dGFjaHlvbg--/http://media.zenfs.com/en_sg/News/AFP/e85b3dfc8246de73dfb949cdd2e96dc94a80eee7.jpg",
"language": "en",
"category": [
"regional"
],
"published": "2019-09-18 19:53:25 +0000"
},
{
"id": "61e150e0-3dfa-4d4d-98a0-4381f5822267",
"title": "Places in Singapore that'll make you believe you're in Hong Kong's Tsim Sha Tsui, Victoria Peak & Mongkok",
"description": "It seems like the Hong Kong protests aren't\u00a0dying down anytime soon,\u00a0and you may be\u00a0feeling a little glum that your trip to the land of dim sum\u00a0has to be postponed until further notice.\nWe've put together a light-hearted article that might just make up for the dampened mood, and you can recreate the...",
"url": "http://www.asiaone.com/lifestyle/places-singapore-thatll-make-you-believe-youre-hong-kongs-tsim-sha-tsui-victoria-peak",
"author": "Melissa Goh",
"image": "None",
"language": "en",
"category": [
"travel",
"lifestyle"
],
"published": "2019-09-18 19:28:36 +0000"
}
]
}Retrieve historical data
In this section, we will cover a use case where historical data is retrieved to get insights into trends or for analytics and machine learning use case.
The example below show how to access news that contain the keyword Amazon and sort them by published date. Since we want to search based on some filters we can use the /search endpoint.
This will return the follow data. We limited the results to the top 5 for illustration purposes. Actual number of results varies depending on the query itself
{
"status": "ok",
"news": [
{
"id": "2f47618d-5579-4caa-9237-1c797015cea2",
"title": "The Best Meat Thermometers on Amazon, According to Thousands of Reviews",
"description": "A digital meat thermometer is an essential for chefs and home cooks alike. Whether you're cooking a Thanksgiving turkey or a Sunday roast, these are the best meat thermometers you'll use again and again. ",
"url": "https://www.foodandwine.com/lifestyle/kitchen/best-meat-thermometers",
"author": "Food & Wine",
"image": "https://cdn-image.foodandwine.com/sites/default/files/styles/4_3_horizontal_-_1200x900/public/1570224510/best-meat-thermometer-main-FT-BLOG1019.jpg?itok=nNK-L-j8",
"language": "en",
"category": [
"food"
],
"published": "2019-10-05 07:54:53 +0000"
},
{
"id": "641d97af-7e71-4a29-a629-5bf785f6785f",
"title": "An Amazonian tribe adopted me as an honorary member decades ago \u2013 now they're facing slaughter",
"description": "Without a mass global civil disobedience movement overthrowing our consumerist empires, there will be no stopping atrocities like these",
"url": "https://www.independent.co.uk/voices/amazon-rainforest-bolsonaro-trump-yanomami-tribe-indigenous-climate-a9116296.html",
"author": "Donnachadh McCarthy",
"image": "None",
"language": "en",
"category": [],
"published": "2019-10-05 07:54:26 +0000"
},
{
"id": "2dbb0321-4d4e-47ce-b4ba-180f966a9265",
"title": "Amazon Prime Day 2019: When is it and how can I get the best deals?",
"description": "You can make huge savings on an array of products, from TVs to coffee machines",
"url": "https://www.independent.co.uk/extras/indybest/amazon-prime-day-2019-date-best-deals-how-to-tv-tech-a9001846.html",
"author": "Sarah Young",
"image": "None",
"language": "en",
"category": [],
"published": "2019-10-05 07:44:12 +0000"
},
{
"id": "37dbac54-a60f-45c5-9ef5-4b2017b91574",
"title": "Amazon Black Friday deals 2019: What to expect and how to bag the best bargains",
"description": "Last year's sale was the biggest shopping event in the online retailer's history",
"url": "https://www.independent.co.uk/extras/indybest/black-friday-2019-amazon-deals-uk-when-guide-date-sale-tips-cyber-monday-a9119901.html",
"author": "IndyBest Team",
"image": "None",
"language": "en",
"category": [],
"published": "2019-10-05 07:43:53 +0000"
},
{
"id": "deefad65-3a74-4ce0-b994-f34db6797cb3",
"title": "Ecosia: Could a search engine that plants trees really help save the Amazon?",
"description": "'Reforestation is essential but means nothing if we're still watching the Amazon go up in smoke,' says Greenpeace",
"url": "https://www.independent.co.uk/environment/ecosia-tree-planting-search-engine-amazon-wildfires-bolsonaro-google-a9095181.html",
"author": "Phoebe Weston",
"image": "None",
"language": "en",
"category": [],
"published": "2019-10-05 07:43:41 +0000"
}
]
}We can further filter the news source using the domain
The result is a reduced subset of the original query, limited to a particular news source. We limited the results to the top 5 for illustration purposes. Actual number of results varies depending on the query itself
{
"status": "ok",
"news": [
{
"id": "4af5665d-80df-4cb6-a48e-dab3d89e04ec",
"title": "Smart speaker wars: As Amazon moves up, Sonos moves out",
"description": "Voice agents like Alexa have already caused Sonos to rethink its product line. Now, it's looking beyond the home as Amazon starts to go for its throat with the Echo Studio.",
"url": "https://www.zdnet.com/article/smart-speaker-wars-as-amazon-moves-up-sonos-moves-out/",
"author": "@ZDNet",
"image": "https://zdnet3.cbsistatic.com/hub/i/r/2019/10/02/7ef5f448-803b-4de9-95e1-7ded2110cd0b/thumbnail/770x578/6936480a65669e52bca49e2e578ad44e/screen-shot-2019-10-02-at-4-22-37-pm.png",
"language": "en",
"category": [
"hardware",
"technology"
],
"published": "2019-10-02 23:24:50 +0000"
},
{
"id": "dfe7cbaf-3a24-43b7-ae7a-4d0973caaaff",
"title": "Amazon device event: Evolutionary, not revolutionary, and there's nothing wrong with that",
"description": "While Amazon's various devices inspired a range of reactions -- from \"awesome\" to \"nonsense\" -- the event overshadowed a potentially even bigger announcement that the company made a day earlier.",
"url": "https://www.zdnet.com/article/amazon-device-event-evolutionary-not-revolutionary-and-theres-nothing-wrong-with-that/",
"author": "@ZDNet",
"image": "https://zdnet4.cbsistatic.com/hub/i/r/2019/09/25/28feaaac-33ca-4109-9df4-4effde7af621/thumbnail/770x578/a15f92d45a765dc16fefb3c1e1a87b2e/amazon-alexa-glasses.jpg",
"language": "en",
"category": [
"hardware",
"technology"
],
"published": "2019-10-01 13:47:30 +0000"
},
{
"id": "a72703c5-3338-4fec-8f0a-4075e7cab215",
"title": "How Amazon and Microsoft could build the world's biggest app store",
"description": "Last week, in China, Huawei launched the Mate 30 Pro. This high-end smartphone has earned the highest DXOMark rating for photographic quality and camera hardware ever recorded on a mobile device, achi...",
"url": "https://www.zdnet.com/article/how-amazon-and-microsoft-could-build-the-worlds-biggest-app-store/",
"author": "Jason Perlow",
"image": "https://zdnet3.cbsistatic.com/hub/i/r/2019/09/28/c24f7f0e-2a48-4b5d-b64a-ad9da98ad6fe/thumbnail/770x578/3b4b23fd080a3eabf66fc2ba173b1fb3/use.jpg",
"language": "en",
"category": [
"technology"
],
"published": "2019-09-30 12:35:45 +0000"
},
{
"id": "681c5661-ebd1-49fb-9598-9210612bfcc8",
"title": "Walmart to take on Amazon Fire with trio of cheap Android tablets",
"description": "The new devices, which include a $64 8-inch and $79 10.1-inch slate and a $99 10.1-inch model with detachable keyboard, go on sale this week under the company's Onn electronics brand.",
"url": "https://www.zdnet.com/article/walmart-to-take-on-amazon-fire-with-trio-of-cheap-android-tablets/",
"author": "@ZDNet",
"image": "https://zdnet2.cbsistatic.com/hub/i/r/2019/05/22/c178362b-685e-4e66-9a1e-23af4d218795/thumbnail/770x578/fd2c09b82a16bbf200133c4f348e1f3e/walmart-onn-android-tablet-detachable-keyboard-cheap-budget-tablets.jpg",
"language": "en",
"category": [
"technology"
],
"published": "2019-09-29 12:44:10 +0000"
},
{
"id": "9e7eadd7-ee6f-4881-a6fc-4c2c65b2afff",
"title": "Best business laptops on Amazon Business",
"description": "The very best business laptops to buy right now on Amazon Business.",
"url": "https://www.zdnet.com/article/best-business-laptops-on-amazon-business/",
"author": "@ZDNet",
"image": "https://zdnet1.cbsistatic.com/hub/i/r/2019/08/06/545a78f8-5806-4df3-9d4f-5f9058b5de91/thumbnail/770x578/4e193a1fc60457360f8f55711cf95755/use.jpg",
"language": "en",
"category": [
"technology"
],
"published": "2019-09-29 12:44:10 +0000"
}
]
}