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).

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.

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

Endpoints

NewsomaticAPI has 2 main endpoints:

  • Everything https://newsomaticapi.com/apis/news/v1/all – search every article published by over 7,500 different sources large and small in the last 60 days.
  • Top headlines https://newsomaticapi.com/apis/news/v1/top – returns breaking news headlines for countries, categories, and singular publishers.

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

  • Sources https://newsomaticapi.com/apis/news/v1/sources – returns information (including name, description, and category) about all the sources available for searching.

Example request:

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 7,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.

      • 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
  •  
  • qInTitle

    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: ar bg cr czdeenesfr gr hd he hu idit jp kr lt lvnlno plpt ro rsruse si sk sx th tr uaudzh

    Default: all languages returned.

  • country

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

    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: relevancypopularitypublishedAt, 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:
– articles – array[article]

– callcount – The number of API calls remaining for your API key

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.

      • 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
  •  
  • qInTitle

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: ar bg cr czdeenesfr gr hd he hu idit jp kr lt lvnlno plpt ro rsruse si sk sx th tr uaudzh

    Default: all languages returned.

  • country

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

    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: relevancypopularitypublishedAt, 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:
– articles – array[article]

– callcount – The number of API calls remaining for your API key

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:
– sources – array[source]
– callcount – The number of API calls remaining for your API key

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.