Request & Response Formats

Response Format

The response is represented in JSON format and includes the keys:

  • total (object) - an object with the keys "value" and "relation".
    • value (integer) - the number of articles matching your search query. If the number of matching articles exceeds 10,000, the key "relation" is set to gte (greater than or equal). If the number of matching articles is less than 10,000, "relation" is set to eq (equal).
    • relation (string) - either eq (equal) or gte.
  • sort (array) - each element of the array represents the various sorting conditions. If no sorting condition is provided, it defaults to "order by field publishedAt, newest first". The JSON representation is {publishedAt: {order: "desc"}}.
  • size (integer) - the number of articles being requested, e.g. 50
  • from (integer) - the start index used for pagination, e.g. 0
  • articles (array) - an array holding all articles matching your search query. The number of articles returned in one response is defined with the request parameter size. If size is set to 50, and 50 or more articles match your search query, the array holds 50 articles. An article object is represented as follows:
    • id (string) - unique ID of the article
    • title (string) - title of the article
    • description (string) - short description of the article
    • sourceUrl (string) - URL to original article
    • imageUrl (string, optional) - URL of article thumbnail
    • publishedAt (string) - ISO 8601 formatted date of publication time, e.g. 2020-06-08T12:23:00-04:00
    • source (object) - the source of the article. See the list below for all supported sources.
      • id (string) - unique ID of news source, e.g. businesswire
      • name (string) - human readable name of news source, e.g. BusinessWire
    • symbols (array) - array of ticker symbols mentioned in the article, e.g. AAPL
    • industries (array) - industries of the tickers mentioned in the article.
    • sectors (array) - sectors of the tickers mentioned in the article.

Response Example

{
  "total": {
    "value": 6610,
    "relation": "eq"
  },
  "from": 0,
  "size": 10,
  "sort": [
    {
      "publishedAt": {
        "order": "desc"
      }
    }
  ],
  "articles": [
    {
      "source": {
        "id": "bloomberg",
        "name": "Bloomberg"
      },
      "symbols": ["MSFT", "COTY"],
      "title": "There Isn’t a Single Down Stock in the S&P Over Last 10 Weeks",
      "description": "Here’s something to consider with the S&P 500 on the verge of erasing all its 2020 losses: Ever since the benchmark bottomed in March, every single one of its members has posted a positive return.",
      "sourceUrl": "https://www.bloomberg.com/news/articles/2020-06-08/there-isn-t-a-single-down-stock-in-the-s-p-over-last-10-weeks",
      "imageUrl": "https://assets.bwbx.io/images/users/iqjWHBFdfxIU/iFFvjKH9uTwE/v0/-1x-1.png",
      "publishedAt": "2020-06-08T15:50:02.473Z",
      "id": "25a5e721982ce5b75f340c2d30bc7bc3",
      "industries": [
        "Software - Infrastructure",
        "Household & Personal Products"
      ],
      "sectors": ["Technology", "Consumer Defensive"]
    },
    {
      "source": {
        "id": "bloomberg",
        "name": "Bloomberg"
      },
      "symbols": ["C"],
      "title": "Citigroup Sees Illinois Bonds Already Pricing In Worst Outcome",
      "description": "When it comes to Illinois bonds, Citigroup Inc. says the worst-case-scenario has already been priced in.",
      "sourceUrl": "https://www.bloomberg.com/news/articles/2020-06-08/citigroup-sees-illinois-bonds-already-pricing-in-worst-outcome",
      "imageUrl": "https://assets.bwbx.io/images/users/iqjWHBFdfxIU/i4xxGH1AndIg/v2/-1x-1.png",
      "publishedAt": "2020-06-08T17:30:17.263Z",
      "id": "65c8a53206ed9f030bd4cb18552bdaf0",
      "industries": ["Banks - Global"],
      "sectors": ["Financial Services"]
    },
    {
      "source": {
        "id": "bloomberg",
        "name": "Bloomberg"
      },
      "symbols": ["TSLA"],
      "title": "Tesla Hails Air-Quality Effects of Shutdowns Elon Musk Called Fascist",
      "description": "Tesla Inc. is proffering a decidedly different take on the coronavirus-related shutdowns Elon Musk called “fascist” and sued over weeks ago by suggesting they may bolster the case for banning internal-combustion engine cars.",
      "sourceUrl": "https://www.bloomberg.com/news/articles/2020-06-08/tesla-hails-air-quality-effects-of-shutdowns-musk-called-fascist",
      "imageUrl": "https://assets.bwbx.io/images/users/iqjWHBFdfxIU/i3CTYqmBlg6o/v1/-1x-1.jpg",
      "publishedAt": "2020-06-08T17:29:57.367Z",
      "id": "15524708278c27207c1fb617acc598c6",
      "industries": ["Auto Manufacturers"],
      "sectors": ["Consumer Cyclical"]
    }
  ]
}

Request Format

JSON format:

  • queryString (string) - The query string is typed in Lucene syntax. This tutorial describes how to use Lucene syntax. You can query for all keys listed in the Response Format section and keys returned by the API in the response body.

    Inclusive ranges are specified with square brackets [min TO max] and exclusive ranges with curly brackets {min TO max}. For example, publishedAt:[now-15m TO *] retrieves articles published in the last 15 minutes.

  • from (integer) - start index. Similar to offset in SQL. Increase the value by size to paginate over the results. Defaults to 0.

  • size (integer) - number of articles matching the query condition to be returned in one request. Defaults to 50. Maximum: 50

Note: the sum of "from" and "size" cannot exceed 10,000. For example, if you set "from" to 11,000 and "size" to "200", you will run into an error. In order to fetch more than 10,000 results, we recommend batching your search query by dates. For example, you can query for articles from a specific source published in one day and then iterate over days. Use "from" and "size" to paginate through the results for one day.

Request Example

Published in last 15 minutes

Return all articles from PR Newswire and BusinessWire that were published in the last 15 minutes.

{
  "queryString": "(source.id:prNewswire OR source.id:businessWire) AND publishedAt:[now-15m TO *]",
  "from": 0,
  "size": 10
}

TSLA SEC filings filed in last 30 days

{
  "queryString": "source.id:sec-api AND symbols:TSLA AND publishedAt:[now-30d/d TO *]",
  "from": 0,
  "size": 10
}

Articles not including "4 Form"

Ignore articles with titles including "4 Form", from source SEC.

{
  "queryString": "source.id:sec-api AND NOT title:\"4 Form\"",
  "from": 0,
  "size": 10
}

Merger articles

Return all articles mentioning Merger published between 11/02/2020 and 19/02/2020. Response size is 10 articles, starting from the first article, sorted by publishedAt, newest first.

{
  "queryString": "(title:merger OR description:merger) AND publishedAt:[2020-02-11 TO 2020-02-19]",
  "from": 0,
  "size": 10
}

FDA approvals

Return all articles with "FDA Approval" (exact match) in the title or description of the article.

Demo: https://reqbin.com/pvtioxqz

Request:

{
  "queryString": "title:\"FDA Approval\" OR description:\"FDA Approval\""
}

Apple news

Return all articles mentioning AAPL.

Demo: https://reqbin.com/zkr3uskr

Request:

{
  "queryString": "title:AAPL OR description:AAPL OR symbols:AAPL"
}

Commodities

Return all articles mentioning corn, soybeans or natural gas. Each commodity is seperated by a comma (=OR operator) and the \" operator is used for exact matches in case there is a space in between, eg \"natural gas\"

{
  "queryString": "corn, soybeans, \"natural gas\""
}
← AuthenticationExample: Python →