Before you begin

Note that you can bypass reading this document if you use the Newsomatic plugin together with this API. You should read this document only if you will create your own implementation of the code that will use this API. If this is the case, lets get started!

General Info

NewsomaticAPI is a simple HTTP REST API for searching and retrieving live articles from all over the web. It can help you answer questions like:

  • What top stories is CNN running right now?
  • What new articles were published about the next gaming laptop, today?
  • Has my service or product been mentioned or reviewed by any blogs recently?

You can search for articles with any combination of the following criteria:

  • Keyword or phrase. Eg: find all articles containing the word ‘Microsoft’.
  • Date published. Eg: find all articles published yesterday.
  • Source domain name. Eg: find all articles published on thenextweb.com.
  • Language. Eg: find all articles written in English.

You can sort the results in the following orders:

  • Date published
  • Relevancy to search keyword
  • Popularity of source

API Keys

You need an API key to use the API – this is a unique key that identifies your requests. You can get an API key here (you will need a purchase code for the Newsomatic plugin). If you use this API key, you will have a 500 API call/day limit. If you wish to get more, you need to subscribe NewsomaticAPI on RapidAPI.

If you create an API key based on a purchase code of the Newsomatic plugin, authentication is handled with a simple API key. You can attach your API key to a request in this simple way: via the apikey query string parameter.
If you are using a subscription to NewsomaticAPI from RapidAPI, you will need to pass the following headers to your request:

  • X-RapidAPI-Host: newsomaticapi.p.rapidapi.com
  • X-RapidAPI-Key: YOUR_API_KEY_FROM_RAPIDAPI

In this case, you will not need to use the apikey URL parameter to send your API key, but the API key needs to be sent using the above header.

We strongly recommend the either of last two so that your API key isn’t visible to others in logs or via request sniffing.

API Base URLs

If you create an API key based on a purchase code of the Newsomatic plugin, the base URL of the API will be:

https://newsomaticapi.com/apis/news/v1

If you subscribe to NewsomaticAPI on RapidAPI, the base URL of the API will be:

https://newsomaticapi.p.rapidapi.com

Endpoints

NewsomaticAPI has 3 main endpoints:

  • Everything /all – search every article published by over 2,500 different sources large and small in the last 60 days.
  • Top headlines /top – returns breaking news headlines for countries, categories, and singular publishers.
  • Sources /sources – returns information (including name, description, and category) about all the sources available for searching.

Examples of the above endpoints:

  • https://newsomaticapi.com/apis/news/v1/all
  • https://newsomaticapi.p.rapidapi.com/all

There is also a minor endpoint that can be used to retrieve a small subset of the publishers we can scan:

Example request (using the 500 API request/day API key):

https://newsomaticapi.com/apis/news/v1/all?apikey=xxxxxxxxxxxxxxxxxxx&q=trump&country=us&language=en&pageSize=5&category=general

Endpoint: Everything

Search through millions of articles from over 2,500 large and small news sources and blogs.

Request parameters:

  • apikey *REQUIRED

    Your API key. Get it using your purchase code for the Newsomatic plugin, from this page.

  • q

    Keywords or phrases to search for in the article title and body. Advanced search is supported here:

    • Surround phrases with quotes (“) for exact match.
    • Prepend words or phrases that must appear with a + symbol. Eg: +bitcoin
    • Prepend words that must not appear with a – symbol. Eg: -bitcoin

    The complete value for q must be URL-encoded.

      •  

  • qInTitle

    • Keywords or phrases to search for in the article title only.

      Advanced search is supported here:

      • Surround phrases with quotes (“) for exact match.
      • Prepend words or phrases that must appear with a + symbol. Eg: +bitcoin
      • Prepend words that must not appear with a – symbol. Eg: -bitcoin

    The complete value for qInTitle must be URL-encoded.

  • sources

    A comma separated string of identifiers (maximum 10) for the news sources or blogs you want headlines from. Use the /sources endpoint to locate these programmatically or look at the sources index.

  • domains

    A comma separated string of domains (eg bbc.co.uk, techcrunch.com, engadget.com) to restrict the search to.

  • excludeDomains

    A comma separated string of domains (eg bbc.co.uk, techcrunch.com, engadget.com) to remove from the results.

  • from

    A date and optional time for the oldest article allowed. This should be in ISO 8601 format (e.g. 2021-04-11 or 2021-04-11T19:40:08)

    Default: the oldest according to your plan.

  • to

    A date and optional time for the newest article allowed. This should be in ISO 8601 format (e.g. 2021-04-11 or 2021-04-11T19:40:08)

    Default: the newest according to your plan.

  • language

    The 2-letter ISO-639-1 code of the language you want to get headlines for. Possible options: all ar bg cr cz de en es fr gr hd he hu id it jp kr lt lv nl no pl pt ro rs ru se si sk sx th tr ua ud zh vn

    Default: all languages returned.

  • country

    The 2-letter ISO-639-1 code of the country you want to get headlines for. Possible options: ar au br bs ca zh cz de es fr gb ie in it nl no pk ru sa se us za ae at be bg ch co cu do eg gh gr hk hu id is jp kr ke lt lv ma mx my ng nz pe ph pl pt ro hr jm rs sg si sk th tr tt tw ua ve vn

    Default: all countries returned.

  • excludeCountry

    The 2-letter ISO-639-1 code of the country you want to exclude from results. You can add a comma separated list of maximum 5 countries. Possible options: ar au br bs ca zh cz de es fr gb ie in it nl no pk ru sa se us za ae at be bg ch co cu do eg gh gr hk hu id is jp kr ke lt lv ma mx my ng nz pe ph pl pt ro hr jm rs sg si sk th tr tt tw ua ve vn

    Default: all countries returned.

  • category

    Find sources that display news of this category. Possible options: businessentertainmentgeneralhealthsciencesportstechnology. Default: all categories.

  • sortBy

    The order to sort the articles in. Possible options: relevancy, popularity, publishedAt, random.
    relevancy = articles more closely related to q come first.
    popularity = articles from popular sources and publishers come first.
    publishedAt = newest articles come first.
    random = random articles.

    Default: publishedAt

  • pageSize *must be int

    The number of results to return per page.

    Default: 8. Maximum: 100.

  • page *must be int

    Use this to page through the results.

    Default: 1.

Response object

The results of the request:
– callcount:
The number of API calls remaining for your API key
– pagination:
Details about the pagination of results. Contained fields are: current_page (the page displayed in the API call), total_pages (how many pages of results exist), page_size (the number of results displayed for each page), total_results (the total number of results available), remaining_pages (how many pages are still available)
– articles:
array[article]

Contents of an article object:

  • source
    The identifier id and a display name name for the source this article came from.
  • author
    The author of the article
  • title
    The headline or title of the article.
  • description
    A description or snippet from the article.
  • url
    The direct URL to the article.
  • urlToImage
    The URL to a relevant image for the article.
  • publishedAt
    The date and time that the article was published.
  • content
    The unformatted content of the article.

Endpoint: Top Headlines

This endpoint provides live top and breaking headlines for a country, specific category in a country, single source, or multiple sources. You can also search with keywords. Articles are sorted by the earliest date published first.

Request parameters

  • apikey *REQUIRED

    Your API key. Get it using your purchase code for the Newsomatic plugin, from this page.

  • q

    Keywords or phrases to search for in the article title and body. Advanced search is supported here:

    • Surround phrases with quotes (“) for exact match.
    • Prepend words or phrases that must appear with a + symbol. Eg: +bitcoin
    • Prepend words that must not appear with a – symbol. Eg: -bitcoin

    The complete value for q must be URL-encoded.

      •  

  • qInTitle

        • Keywords or phrases to search for in the article title only.

          Advanced search is supported here:

          • Surround phrases with quotes (“) for exact match.
          • Prepend words or phrases that must appear with a + symbol. Eg: +bitcoin
          • Prepend words that must not appear with a – symbol. Eg: -bitcoin
    •  

The complete value for qInTitle must be URL-encoded.

  • sources

    A comma separated string of identifiers (maximum 10) for the news sources or blogs you want headlines from. Use the /sources endpoint to locate these programmatically or look at the sources index.

  • domains

    A comma separated string of domains (eg bbc.co.uk, techcrunch.com, engadget.com) to restrict the search to.

  • excludeDomains

    A comma separated string of domains (eg bbc.co.uk, techcrunch.com, engadget.com) to remove from the results.

  • from

    A date and optional time for the oldest article allowed. This should be in ISO 8601 format (e.g. 2021-04-11 or 2021-04-11T19:40:08)

    Default: the oldest according to your plan.

  • to

    A date and optional time for the newest article allowed. This should be in ISO 8601 format (e.g. 2021-04-11 or 2021-04-11T19:40:08)

    Default: the newest according to your plan.

  • language

    The 2-letter ISO-639-1 code of the language you want to get headlines for. Possible options: all ar bg cr cz de en es fr gr hd he hu id it jp kr lt lv nl no pl pt ro rs ru se si sk sx th tr ua ud zh vn

    Default: all languages returned.

  • country

    The 2-letter ISO-639-1 code of the country you want to get headlines for. Possible options: all ar au br bs ca zh cz de es fr gb ie in it nl no pk ru sa se us za ae at be bg ch co cu do eg gh gr hk hu id is jp kr ke lt lv ma mx my ng nz pe ph pl pt ro hr jm rs sg si sk th tr tt tw ua ve vn

    Default: all countries returned.

  • excludeCountry

    The 2-letter ISO-639-1 code of the country you want to exclude from results. You can add a comma separated list of maximum 5 countries. Possible options: ar au br bs ca zh cz de es fr gb ie in it nl no pk ru sa se us za ae at be bg ch co cu do eg gh gr hk hu id is jp kr ke lt lv ma mx my ng nz pe ph pl pt ro hr jm rs sg si sk th tr tt tw ua ve vn

    Default: all countries returned.

  • category

    Find sources that display news of this category. Possible options: businessentertainmentgeneralhealthsciencesportstechnology. Default: all categories.

  • sortBy

    The order to sort the articles in. Possible options: relevancy, popularity, publishedAt, random.
    relevancy = articles more closely related to q come first.
    popularity = articles from popular sources and publishers come first.
    publishedAt = newest articles come first.
    random = random articles.

    Default: publishedAt

  • pageSize *must be int

    The number of results to return per page.

    Default: 100. Maximum: 100.

  • page *must be int

    Use this to page through the results.

    Default: 1.

Response object

The results of the request:
– callcount:
The number of API calls remaining for your API key
– pagination:
Details about the pagination of results. Contained fields are: current_page (the page displayed in the API call), total_pages (how many pages of results exist), page_size (the number of results displayed for each page), total_results (the total number of results available), remaining_pages (how many pages are still available)
– articles:
array[article]

Contents of an article object:

  • source
    The identifier id and a display name name for the source this article came from.
  • author
    The author of the article
  • title
    The headline or title of the article.
  • description
    A description or snippet from the article.
  • url
    The direct URL to the article.
  • urlToImage
    The URL to a relevant image for the article.
  • publishedAt
    The date and time that the article was published.
  • content
    The unformatted content of the article.

Endpoint: Sources

This endpoint returns the subset of news publishers that top headlines are available from. It’s mainly a convenience endpoint that you can use to keep track of the publishers available on the API.

Request parameters

  • apikey *REQUIRED

    Your API key.

Response object

The results of the request:
– callcount:
The number of API calls remaining for your API key
– sources:
array[source]

Contents of a source object:

  • name
    The name of the news source, which acts also as its unique identifier

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. You will also get the “callcount” API response, containing the remaining number of API calls for your API key for the current day.

WordPress Plugin which uses the API

Currently, you can use the NewsomaticAPI in the Newsomatic plugin for WordPress. It provides a done-for-you implementation of this API and it is always kept updated and functional.