This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

News API Reference

Specrom News API endpoints fetch news articles by keyword, region, latitude, longitude.

1 - Simple News Search

A Specrom News API endpoint for fetching latest news within past 24h with full_text content.

We reccomend that all the new users try out this API endpoint before using the other more advanced keyword search endpoints only when they either need more results (using similar keyword search), or need results with very low latency (instead of 24h in this case) or historical search.

This endpoint will fetch news articles with full-text using variety of inputs.


import requests

url = "https://specrom-news-api.p.rapidapi.com/"

payload = {
  "api_type": "exhaustive_news_search_24h",
  "q": "bitcoin",
  "author_only": "",
  "content": "",
  "domains": "",
  "page": "1",
  "qInTitle": "",
  "topic": ""
}
headers = {
  "content-type": "application/json",
  "X-RapidAPI-Key": "API_Key",
  "X-RapidAPI-Host": "specrom-news-api.p.rapidapi.com"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)
	
	POST / HTTP/1.1
Content-Type: application/json
X-Rapidapi-Key: API_Key
X-Rapidapi-Host: specrom-news-api.p.rapidapi.com
Host: specrom-news-api.p.rapidapi.com
Content-Length: 192

{
    "api_type": "exhaustive_news_search_24h",
    "q": "bitcoin",
    "author_only": "",
    "content": "",
    "domains": "",
    "page": "1",
    "qInTitle": "",
    "topic": ""
}
	
	
Parameter Description
api_type exhaustive_news_search_24h
domains The domain url for filtering by news source. In this version, you can only specify one domain address. In case you do not want to filter by domain address, than simply leave the field empty ("")
topic: Filter the news articles by their topic. Options include: “politics”, “tech”, “entertainment”, “business”, “sport”. If you want to fetch all articles without topic filtering, than simply specify “”.
q filter the news articles by a keyword; optionally you can simply leave it empty ("") if you do not wish to filter by keyword. Only one keyword is supported by this API; if you want to search by phrases, than we reccomend using our keyword news search endpoint
qInTitle filter the news articles by a keyword present in the title. Only one keyword is supported by this endpoint.
content If you want full text of the news articles in the content key of the response JSON then set this field to “true” otherwise set it to “false”.
author_only (optional) if “true” then it only returns results with author names.

Output


{
  "Article": [
    {
      "author": "[\"Lauren Fox and Ted Barrett, CNN\"]",
      "description": "Divisions within the Republican conference spilled out once again Tuesday as GOP senators dismissed key pieces of their own leadership's stimulus proposal not even a day after its release.",
      "publishedAt": "2020-07-28",
      "source_name": "CNN",
      "source_url": "cnn.com",
      "title": "Republicans revolt against GOP's initial stimulus plan  - CNNPolitics",
      "url": "https://www.cnn.com/2020/07/28/politics/republican-reaction-gop-stimulus-plan/index.html?utm_source=feedburner&utm_medium=feed&utm_campaign=Feed%3A+rss%2Fcnn_allpolitics+%28RSS%3A+CNN+-+Politics%29",
      "urlToImage": "https://cdn.cnn.com/cnnnext/dam/assets/200518181852-senator-ben-sasse-1-super-tease.jpg"
    },
    .
    .
    (output truncated)
    ],
  "status": "ok",
  "totalResults": 113
}

This endpoint returns a JSON object containing the following elements:

Parameter Description
status This key will return “ok” if results from all the shards are being fetched correctly. Please raise a support ticket with us by email to info@specrom.com if is reporting a “fail”.
totalResults this mentions the total number of articles found by our endpoint. Note: this is not exhaustive results for You can use our other keyword search endpoint
Article This key contains a list of dictionaries representing individual news articles.
Author A list of author names for the news articles.
content: Full text of the news articles (upto 30% text); we trncate the full_text at 30% to respect the rights of the original copyright holder. If your use-case does’nt involve making the full_text public (such as using it for internal data analytics, training an AI model etc) , then you can get the entire full_text of each news article using fetch complete news article by URL endpoint.
title: title of the news article
description description of the news article extracted and parsed from meta tags of the HTML page.
publishedAt publication date of the news article (based on on UTC timezone).
source_name Name of the news source.
source_url domain address of the news source.
url url of the news article
urlToImage url of the most relevant image from the news article.

2 - Get News Headlines By Keyword Search

Get near real time news articles by searching using a keyword or a keyphrase.

This API endpoint is excellent for running queries with multiple keywords or keyphrases.

Fetch near real time news articles by searching using a keyword or keyphrase

Input

import requests

url = "https://specrom-news-api.p.rapidapi.com/"

payload = {
  "api_type": "news_by_keyword_search",
  "keyword": "Donald Trump"
}
headers = {
  "content-type": "application/json",
  "X-RapidAPI-Key": "API_key",
  "X-RapidAPI-Host": "specrom-news-api.p.rapidapi.com"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)
	
	POST / HTTP/1.1
Content-Type: application/json
X-Rapidapi-Key: API_key
X-Rapidapi-Host: specrom-news-api.p.rapidapi.com
Host: specrom-news-api.p.rapidapi.com
Content-Length: 96

{
    "api_type": "news_by_keyword_search",
    "keyword": "Donald Trump"
}
	
	
Parameter Description
api_type news_by_keyword_search
country two digit country code
keyword Search using the keyword or keyphrase. In case of a keyphrase containing more than two words (say Donald Trump), the keyphrase searched will be “Donald AND Trump”.

Output


[

{
"source_url":"",
"source name":"",
"published_date":"2023-04-12T10:01:50Z",
"title":"Trump Leads DeSantis In Our New 2024 Republican Primary Polling Average",
"matched_text":"Donald Trump",
"url_id":"W2KracEB6QSg2AMRzLoV0JlBt5QiEJiIoMNEgq9l7vYR4F5yktDFc32OboItXqVpM80wmoALot3dO1a4YNQWuI/Ip4i2Ez2XIpgXyX1yz5RTuzkfMiNOVA4RAZzso5tMkzucFHXVOjNAECDOswQ0Dv1iqTt8JthEm4asfBCGdlqbxLG8vgkThGMlSfxKFNMdz8CpwbKAvYlnAJE2pXKPei1srKjY9Ce1Q0fKpG9HjEhIm06bsEtEtfBRDm8ApfpQLXhvpP20DNJuRHp+QaUNZqFIW6tbBxKac9YCepD5Ac/EpZAI+Ho3tu8h/JPwKoo8SV2ZkEBQGq6E3gutpF0arOpZN1fkkihSETsV0uCXSA==z0JGhuTDznqBaiJ6cMa0QA==k3ZkWXy8+3HBa/h2NQJI4A=="
},

{
"source_url":"",
"source name":"",
"published_date":"2023-04-17T05:07:24Z",
"title":"Trump news – latest: SNL mocks Trump for claim NYPD ‘cried’ during arrest",
"matched_text":"Donald Trump",
"url_id":"UcP9TICRECQitflcKckLSuPVuVymb1DSxJxLopzwZjfaTlzjvtj0vQIwavE4smL7pEUdjKCxAeIqHOPqUYbAYINA88tUx1cQAzxplf5+bcibNJlG+I7rzqTe/6yuch+mGJejhSdzRwUMAfkzQ1FAO4uyzUueVOmPYa+SAnJA/xR5MPKyoJA45rvWLkrUMKptw4vW6eLKAch7lZX976IFqy6Yt3+7vONHBNdN+1QQIjhN1yzJ9hEkww9QWiIbyCPh4z1hgj82AoMApw96nj5LX1LqqGxa/m1WeMFyi02JTf8g0YxcoFoyL0uFjg42y0Cm5vmaXu9FZYwd/aoCFZHzUUP+VfLeA31g7wGRA7096GKbDbhrQU8Xbu2hwLQAMqQidjM1hcE8ShPysXbiKxStKaRG1X256aTIXGSG3EqrRU6M38uwXdeiZs3rypRed5DjUhtxjSdMdvXihhZJKVWT1zCoUzXRTRvfWwfinkLUDTczUcA75/owNrRDq0EVRdvkjzS4JA==btCc5KU/AkvM/Rb1sPfo7g==J5YrGi3Qg8ZgePxkRBF2sg==vuJWPkwttgAi+hWMLJBcng=="
},
.
.
.
(output truncated)

]
Parameter Description
source url web domain of the media outlet
source name name of the media outlet
publishedAt date of the news article
title title of the news article
matched_text input keyword
url_id unique url_id of the news article. Use our separate endpoint called fetch news article by url_id to fetch complete details such as full_text, author, url etc. of the news article

3 - Get Latest News By City, State, Country

Get near real time news articles published in local newspapers and other media outlets by specifying a region (city, state) and country.

This API endpoint is excellent for fetching local and regional news.

Fetch local news using city, state, country as input

Input

import requests

url = "https://specrom-news-api.p.rapidapi.com/"

payload = {
  "api_type": "news_by_city_country",
  "country": "US",
  "region": "Atlanta, GA"
}
headers = {
  "content-type": "application/json",
  "X-RapidAPI-Key": "API_key",
  "X-RapidAPI-Host": "specrom-news-api.p.rapidapi.com"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)
	
	POST / HTTP/1.1
Content-Type: application/json
X-Rapidapi-Key: API_key
X-Rapidapi-Host: specrom-news-api.p.rapidapi.com
Host: specrom-news-api.p.rapidapi.com
Content-Length: 96

{
    "api_type": "news_by_city_country",
    "country": "US",
    "region": "Atlanta, GA"
}
	
	
Parameter Description
api_type news_by_city_country
country two digit country code
region city name followed by state code

A list of country codes are below


Country Country Code
USA US
Japan JP
United Kingdom UK
Spain ES
Canada CA
Deutschland DE
Italia IT
France FR
Australia AU
Taiwan TW
Nederland NL
Brasil BR
Turkey TR
Belgium BE
Greece GR
India IN
Mexico MX
Denmark DK
Argentina AR
Switzerland CH
Chile CL
Austria AT
Korea KR
Ireland IE
Colombia CO
Poland PL
Portugal PT
Pakistan PK

Output


{
  "article_list": [
    {
      "source url": "https://www.wsbtv.com",
      "source name": "WSB Atlanta",
      "published_date": "Fri, 07 Apr 2023 00:49:00 GMT",
      "title": "Credit union members say their money being held hostage, can’t access funds - WSB Atlanta",
      "url_id": "O8sAqcnybFac+cCXoC/TYt4Wwn5V+FmLjbXhqb98G0qrCZdRnAYHraHKEITnpaXK0J9+5t++Ccd0ddV8HIed/rayUGYk3zqWEHocNJuTD23tEwEhz1td+LENnUbwNS+0xPYlHTgC0p/AT3cU0KqcX+aAIRI8iSwgYj/ChiW31+Vlh1qFp4RFejj8SoGj1lD20vx9redXFlhKj7m/rIkSfTVHbOq+DpmapNZdNjB3lvgAn7DVwNcA5g+gbt0WvHLc4gVRfkjHu3+QjaimG6QPwk4fhJpZWPPR/r8kxMxSkjNbkFvxpgsitCAhc+ryo/wZAahCVR9n0Z9B6MtCN42XcHzuh2JhHZz7twcg0uSFcYXZDsDWtRUxZ4NMddEvOonxMLEOx+6dYS0MSadPK65iHDpVUcGkUHD+O+Nl9b12/1EUGNF6rQ8GPH3GuVu90ky4KJV5DbiH8oPm1+3C7JOa+FiqmB86zP5k9cZ2QyrGexKcOym7ywneq6PSo9hPJS0cvVCY/jilk4r01mT22Tdf9HrlbPvYkbYBbhePiIadMDPAdYDK1GJncq208uSOh+Sf2O+iAIIdSjEXGatgRNYSZTc7*f8QvuCUSqeMUelzr87slBA==*cnjF1ZxjpZgeXTHFwVsazQ==*MkCp3nEWhsKyC4fFJU9XjQ=="
    },
    {
      "source url": "https://www.wsbtv.com",
      "source name": "WSB Atlanta",
      "published_date": "Fri, 07 Apr 2023 02:59:00 GMT",
      "title": "Training facility back in compliance after stop work order issued, order to be lifted Friday morning - WSB Atlanta",
      "url_id": "NjEV3/1FQf8ffd3Ey5AtAYDsZ2I7X4qmI+hVWNX9asd4xPf8ARn3VowPd6A4WQHhrjTO+etcIqKlAjN9sCQQWAImueJVxzPWl69eBaeS2VlpmJ6GcaJlrpCGlj8wJYLwXg2JsvjU6mJnYYF4NCY6dV+Rl+Ng/ilfGCKoe+FBCAbnMpFbX+vOw3bxp7VwnndM+0J5DGZVfO4U/Npu9eX25E8uGVawfctsbBB11p72+0pqQjsYPFBani+ioiR+Xnq7srLMZ8ta5U0lvkAJ3Ya4bc8aMDlb+GAww2zWvugMRH14npLO8SNMY1GbA6cMhtEMbXCLsLALqXotRMFIt3pr67EJ5CMEINdSn3To7lMId9y1vSRfHvtvqNktlXFs+Y3a6QSmq4/8RJE2Zd+m5MNkPGc3b5YtsXab53ohf2fxILlePq7oPqdJWsQ4/gp/z5gsvvwRzdcdDnkc8NJBYn4ZjS1hA1P3CCZHdkFtcOx/J8n+vGHygkgoXW6VvmC3r8SyKvvvN4PmCZyH8z7suLGbPToQviPIAwp94HRkb1bOINAUdxbOEtKoF5MgOLsF7lI8ClW7IJ4Ge3Dz5jCKLQVbzwHyAmcZdnYsEuVdDYjb5LgpORCWSh+xhw==*LgI2UsNQctdt3mLM4TFArg==*6kVcegsMBPGdTGK0X7YHAg==*Gm1QJtk0CUrYnX97xKY0mw=="
    },
    .
	.
	.
	(Output Truncated)
	
	
    }
  ]
}
Parameter Description
article_list A list of dictionaries containing individual news articles
source url web domain of the media outlet
source name name of the media outlet
publishedAt date of the news article
title title of the news article
url_id unique url_id of the news article. Use our separate endpoint called fetch news article by url_id to fetch complete details such as full_text, author, url etc. of the news article

4 - Get Latest News By Latitude, Longitude

Get near real time news articles published in local newspapers and other media outlets by specifying a geolocation coordinates (latitude, longitude).

This API endpoint is excellent for fetching local and regional news.

Fetch local news using geolocation coordinates (latitude, longitude) as input

Input

import requests

url = "https://specrom-news-api.p.rapidapi.com/"

payload = {
  "api_type": "news_by_latitude_longitude",
  "lat": "40.730610",
  "longitude": "-73.935242"
}
headers = {
  "content-type": "application/json",
  "X-RapidAPI-Key": "API_key",
  "X-RapidAPI-Host": "specrom-news-api.p.rapidapi.com"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)
	
	POST / HTTP/1.1
Content-Type: application/json
X-Rapidapi-Key: API_key
X-Rapidapi-Host: specrom-news-api.p.rapidapi.com
Host: specrom-news-api.p.rapidapi.com
Content-Length: 96

{
    "api_type": "news_by_latitude_longitude",
    "lat": "40.730610",
    "longitude": "-73.935242"
}
	
	
Parameter Description
api_type news_by_latitude_longitude
lat Latitude
longitude Longitude

Output


{
  "article_list": [
    {
	source url:"https://www.foxnews.com"
source name:"Fox News"
published_date:"Thu, 06 Apr 2023 20:22:00 GMT"
title:"NYC man pleads guilty to selling fatal dose of fentanyl-laced heroin to actor Michael K. Williams - Fox News"
url_id:"slCdc3TihL57gNfNqq0hoOVXZy6YoUKEpq2whk9bqGcZVkhol9SRfr1pBGSG5OkysZDHwBqs7ZU57OPCzS+btyMS9kR3yqGtMXtalXoa+xYl+aoQyHwxfUbcJRzY75pvpCAdTRX5PsFHk3xbbXHixP2guu5WWRGJHWebSwuICQa56SuV95ZBUD4Xo2xvG+KfFQkNm7xSVuJMcQNUsXp0KLHrYPK0Peyso76PU0W5cldmqX7ncYOGzW5NakzWBV9xa9r7texCX+LgyGqXCru9faxXqDuibTeM3lSPoZDow8vnfk3/qibj88q+iJEhXB2ISbPEP2XttnJyrpAlSfwKIcfAtuvuLB8MPgmypVS9sXqie99sWmW8n44y7pyRCYl2rS2DwpFzQL5Fh+RwoQjeAzBfAU33udpCY+D60uEa70+4/50i/TVLgqTUmrzAqZOuNtjoEwhdwlxltBA0Wb9cT6jQfOtRweefGA==*9PU3DmkN3DblUuPpApib0g==*6b/1vdOgFWV3Qt3IwCRG5g==*mMg42UOs9Pfh1f8vjQq0Ig=="
},
    
    .
	.
	.
	(Output Truncated)
	
	
    }
  ]
}
Parameter Description
article_list A list of dictionaries containing individual news articles
source url web domain of the media outlet
source name name of the media outlet
publishedAt date of the news article
title title of the news article
url_id unique url_id of the news article. Use our separate endpoint called fetch news article by url_id to fetch complete details such as full_text, author, url etc. of the news article

5 - Fetch Parsed News Article By url_id

A Specrom News API endpoint for fetching the full_text, title, author, main image etc. from the news article using url_id as input.

This is a simple API endpoint that will take in a url_id (generated by our other endpoints) of any news article and return parsed data containing full_text, title, author, main image.

Fetch the full_text, title, author, main image etc. from the news article using url_id as input.

Input

import requests

url = "https://specrom-news-api.p.rapidapi.com/"

payload = {
  "api_type": "fetch_parsed_news_article_by_id",
  "url_id": "2+W9MSIWD4PJ5kF6fcRThhpsnzW92j46dBr8UEiHBKwSjaiOKBMnTWcmr5BXqe0vwpgP9bpT8r6Fgc8MnaYXYyidz9gl7WjxTCFUpKW/scAuJegSL86lw4C+M4Ea9/rPgFkTu1MkA34cs5/QXMTMH6J9xG18dcQG4sbe6a2pV1mY6jzCudZauazA13CO+NVFJH/R7UBIsT42lm2RPY4ISlPHuSh6y5AjrUiCwx4=*o3X7JdWv94Q2Td9x31pIFA==*fRxtKu8HwfTNo++zlEVHnA==*DXgO4zPEi1nWqrKZwosVwA=="
}
headers = {
  "content-type": "application/json",
  "X-RapidAPI-Key": API_Key,
  "X-RapidAPI-Host": "specrom-news-api.p.rapidapi.com"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)
	
POST / HTTP/1.1
Content-Type: application/json
X-Rapidapi-Key: API_Key
X-Rapidapi-Host: specrom-news-api.p.rapidapi.com
Host: specrom-news-api.p.rapidapi.com
Content-Length: 381

{
    "api_type": "fetch_parsed_news_article_by_id",
    "url_id": "2+W9MSIWD4PJ5kF6fcRThhpsnzW92j46dBr8UEiHBKwSjaiOKBMnTWcmr5BXqe0vwpgP9bpT8r6Fgc8MnaYXYyidz9gl7WjxTCFUpKW/scAuJegSL86lw4C+M4Ea9/rPgFkTu1MkA34cs5/QXMTMH6J9xG18dcQG4sbe6a2pV1mY6jzCudZauazA13CO+NVFJH/R7UBIsT42lm2RPY4ISlPHuSh6y5AjrUiCwx4=*o3X7JdWv94Q2Td9x31pIFA==*fRxtKu8HwfTNo++zlEVHnA==*DXgO4zPEi1nWqrKZwosVwA=="
}
	
	
Parameter Description
api_type fetch_parsed_news_article_by_id
url_id url_id of the news article. This is generated by our other endpoints.

Output

{"author":["Perry Stein","Shayna Jacobs"],

"content":"Former president Donald Trump on Tuesday pleaded not guilty to 34 counts stemming from 2016 hush-money payments," ....(output truncated),

"meta_description":"When will he appear in court next? What is the discovery process? Your questions and more answered.",

"og_title":"What’s next for Trump after pleading not guilty to 34 felony counts","

publishedAt":"2023-04-05",

"source_url":"washingtonpost.com",

"title":"What’s next for Trump after pleading not guilty to 34 felony counts",

"url":"https://www.washingtonpost.com/nation/2023/04/05/trump-indictment-whats-next/",

"urlToImage":"https://www.washingtonpost.com/wp-apps/imrs.php?src=https://arc-anglerfish-washpost-prod-washpost.s3.amazonaws.com/public/BSK27QJRAJAVHDMPKYPSIUYUWM.jpg&w=1440"}
Parameter Description
author A list of authors of the news article
content full_text of the news article
meta_description text from the meta_description tag on the page
og_title text from the og_title tag on the page
publishedAt date of the news article
source_url source domain of the news article
title title of the news article
url canonical url of the news article
urlToImage primary image URL from the news article

6 - Fetch Parsed News Article By URL

A Specrom News API endpoint for fetching the full_text, title, author, main image etc. from the news article using URL as input.

This is a simple API endpoint that will take in a URL of any news article and return parsed data containing full_text, title, author, main image.

Fetch the full_text, title, author, main image etc. from the news article using URL as input.

Input

import requests

url = "https://specrom-news-api.p.rapidapi.com/"

payload = {
  "api_type": "fetch_parsed_news_article_by_url",
  "url": "https://edition.cnn.com/2020/06/30/tech/facebook-ad-business-boycott/index.html"
}
headers = {
  "content-type": "application/json",
  "X-RapidAPI-Key": API_Key,
  "X-RapidAPI-Host": "specrom-news-api.p.rapidapi.com"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)
	
	POST / HTTP/1.1
Content-Type: application/json
X-Rapidapi-Key: API_Key
X-Rapidapi-Host: specrom-news-api.p.rapidapi.com
Host: specrom-news-api.p.rapidapi.com
Content-Length: 151

{
    "api_type": "fetch_parsed_news_article_by_url",
    "url": "https://edition.cnn.com/2020/06/30/tech/facebook-ad-business-boycott/index.html"
}
	
	
Parameter Description
api_type fetch_parsed_news_article_by_url
url URL of the news article

Output

{
  "author": [
    "Rishi Iyengar"
  ],
  "content": "San Francisco CNN Business —\n\nEach day, more household names join the list of brands suspending advertising on Facebook to protest what they say are the social network’s failures to stop the spread of hate. On Monday alone, Adidas (ADDDF), HP (HPQ), and Ford (F) added their names to a list that already had Unilever (UL), The North Face, Coca Cola (CCHGY), Honda (HMC) and many others.\n\n"........(output truncated),
  "meta_description": "Each day, more household names join the list of brands suspending advertising on Facebook to protest what they say are the social network's failures to stop the spread of hate. On Monday alone, Adidas, HP, and Ford added their names to a list that already had Unilever, The North Face, Coca Cola, Honda and many others.",
  "og_title": "Here's how big Facebook's ad business really is | CNN Business",
  "publishedAt": "2020-06-30",
  "source_url": "cnn.com",
  "title": "Here’s how big Facebook’s ad business really is",
  "url": "https://www.cnn.com/2020/06/30/tech/facebook-ad-business-boycott/index.html",
  "urlToImage": "https://media.cnn.com/api/v1/images/stellar/prod/200630015227-facebook-ads-stock.jpg?q=x_3,y_243,h_1684,w_2993,c_crop/w_800"
}
Parameter Description
author A list of authors of the news article
content full_text of the news article
meta_description text from the meta_description tag on the page
og_title text from the og_title tag on the page
publishedAt date of the news article
source_url source domain of the news article
title title of the news article
url canonical url of the news article
urlToImage primary image URL from the news article