Financelayer API

The financelayer API was built to provide a powerful, scalable yet easy-to-use REST API interface delivering worldwide live and historical financial news data in handy JSON format. The API comes with a single news HTTP GET endpoint along with a series of parameters and options you can use to narrow down your finance news data results. Among other options, you can filter by dates and timeframes, sources, and search keywords, tags, and tickers.

In this page, you will find out about the API structure, the methods, potential errors you may encounter, and code examples. If you still have questions and doubts, please do not hesitate to contact us. Our team will do their best to help you. If you do not have an account yet, please make sure to get a free API key now to start testing the API and retrieve your first news article.

API Key

The API has a unique identifier as an API key that gets passed into the API as an URL parameter access_key. This parameter serves as a unique identifying authentication with the financelayer API.

256-bit HTTPS Encryption

To connect to the financelayer API using 256-bit HTTPS (SSL) encryption, you will need to be subscribed to the Standard Plan or higher. If you are on the Free Plan, please note that you will be limited to HTTP connections.

Base URL:

https://api.financelayer.com/v1/

Append your API Key: See an example of how to authenticate the financelayer API with the access_key parameter:

https://api.financelayer.com/v1/news
    ? access_key = API_KEY

API Response

The data is returned in a standard JSON format and easily parsed in any programming language.

Example Response: See below an example of an API response that provides information about financial news.

{
    "pagination": {
        "limit": 25,
        "offset": 0,
        "count": 25,
        "total": 10000
    },
    "data": [
        {
            "title": "AT&T: Best Investment For Investors Seeking Value And Growth",
            "url": "https://seekingalpha.com/article/4457821-at-and-t-value-and-growth",
            "description": "AT&T and Discovery merger provides investors with the potential for valuation and dividend appreciation. See more on how this merger can boost T stock here.",
            "source": "seekingalpha.com",
            "tickers": [
                "dis",
                "disca",
                "discb",
                "disck",
                "nflx",
                "tmus",
                "vz"
            ],
            "tags": [
                "Business",
                "Communication Services",
                "Consumer Cyclical",
                "Dis",
                "Disca",
                "Discb",
                "Disck",
                "Nflx",
                "Stock",
                "T",
                "Tmus",
                "Vz"
            ],
            "published_at": "2021-09-30T14:53:42+00:00"
        },
    {...}
]
}

Error Codes

If your API request was unsuccessful, you will receive a JSON error in the format outlined below, carrying code, message and context response objects in order to communicate the type of error that occurred and details to go with it. The API will also return HTTP status codes in accordance with the type of API response sent.

Below you will find an example API error that occurs if an unknown value is set for the API's date parameter.

Example Error:

{
   "error": {
      "code": "validation_error",
      "message": "Validation error",
      "context": {
         "date": [
            "NO_SUCH_CHOICE_ERROR"
         ]
      }
   }
}

Common API Errors:

Type Info
404_not_found The requested resource does not exist.
invalid_access_key No API Key was specified or an invalid API Key was specified.
invalid_api_function The requested API endpoint does not exist.
usage_limit_reached The maximum allowed API amount of monthly API requests has been reached.
missing_access_key No API access key was supplied.
inactive_user The given user account is inactive.
https_access_restricted HTTPS access is not supported on the current subscription plan.
function_access_restricted The given API endpoint is not supported on the current subscription plan.
rate_limit_reached The given user account has reached the rate limit.
internal_error An internal error occurred.

API Features

Live Financial News

The full set of available real-time news articles can be accessed using a simple API request to the financelayer API's news endpoint. Below you will find an example API request as well as a series of optional parameters you can use to filter your news results.

Delayed news on Free Plan: Please note that accounts subscribed to the Free Plan will receive live news only with a 60-minute delay. To lift this limitation and get news in real-time, please sign up or upgrade to the Standard Plan or higher.

API Request:

GET https://api.financelayer.com/v1/news
    ? access_key = API_KEY
    & keywords = salesforce
    & sources = forbes.com

Request Parameters:

 
Parameter Description
access_key [Required] Your API Key.
fallback [Optional]: It can be: 'on' (default) or 'off'. Fallback is used in case the search query doesn't return any news, then it will return the default results
sources [Optional] Use this parameter to include or exclude one or multiple comma-separated news sources. Example: To include forbes.com, but exclude bloomberg.com: &sources=forbes.com, -bloomberg.com
keywords [Optional] Use this parameter to search for sentences, you can also exclude words that you do not want to appear in your search results. Example: To search for "New bitcoin news 2021" but exclude "Etherum": &sources=new bitcoin news 2021, -etherum
tickers [Optional] Use this parameter to search for ticker symbols. You can search multiple tickers, separating them with comma, you can also exclude tickers that you do not want to appear in your search results. Example: &tickers=btc, pifi, -appl. Results will exclude ticker appl from results
tags [Optional] Use this parameter to search for tags by which news are tagged. You can search by multiple tags, separating tags with a comma, you can also exclude tags that you do not want to appear in your search results. Example: &tags=Bitcoin, -money. Results will exclude tags money from results
date [Optional] Use this parameter to specify a date or date range. Available options:
today
thisweek
thismonth
last7days
last30days
last3months
yeartodate
YYYY-MM-DD
YYYY-MM-DD,YYYY-MM-DD
Example: &date=2020-01-01 for news on Jan 1st and &date=2020-12-24,2020-12-31 for news between Dec 24th and 31st.
sort [Optional] Use this parameter to specify sorting order. Available values by published date: desc, asc
limit [Optional] Use this parameter to specify a pagination limit (number of results per page) for your API request. The default limit value is 25, the maximum allowed limit value is 100.
offset [Optional] Use this parameter to specify a pagination offset value for your API request. Example: An offset value of 100 combined with a limit value of 10 would show results 100-110. The default value is 0, starting with the first available result.

API Response:

If your API request has been successful, the financelayer API will return HTTP status 200 together with a JSON result, carrying a pagination object as well as a data object containing one or multiple financial news articles.

{
    "pagination": {
        "limit": 25,
        "offset": 0,
        "count": 25,
        "total": 10000
    },
    "data": [
        {
            "title": "AT&T: Best Investment For Investors Seeking Value And Growth",
            "url": "https://seekingalpha.com/article/4457821-at-and-t-value-and-growth",
            "description": "AT&T and Discovery merger provides investors with the potential for valuation and dividend appreciation. See more on how this merger can boost T stock here.",
            "source": "seekingalpha.com",
            "tickers": [
                "dis",
                "disca",
                "discb",
                "disck",
                "nflx",
                "tmus",
                "vz"
            ],
            "tags": [
                "Business",
                "Communication Services",
                "Consumer Cyclical",
                "Dis",
                "Disca",
                "Discb",
                "Disck",
                "Nflx",
                "Stock",
                "T",
                "Tmus",
                "Vz"
            ],
            "published_at": "2021-09-30T14:53:42+00:00"
        },
    {...}
]
}

Response Objects:

Parameter/Object Description
pagination > limit Returns your pagination limit value.
pagination > offset Returns your pagination offset value.
pagination > count Returns the results count on the current page.
pagination > total Returns the total count of results available. Note: The maximum that can be returned is 10.000
data > title Returns the title text of the given news article.
data > url Returns the URL leading to the given news article.
data > description Returns the description text of the given news article.
data > source Returns information about the region in which the country is
data > tickers Returns the tickers of the given news article
data > tags Returns the tags of the given news article.
data > published_at Returns the exact time stamp the given news article was published.

Empty Data: Please note that if no results are found for your specific query, the data object will contain no results.

Historical News

If you are subscribed to the Standard Plan or higher, you will be able to access historical news data by specifying a historical date using the API's date parameter in YYYY-MM-DD format. Find an example request below.

Options that can be used as a date parameter
today
thisweek
thismonth
last7days
last30days
last3months
yeartodate
YYYY-MM-DD
YYYY-MM-DD,YYYY-MM-DD

API Request:

GET https://api.financelayer.com/v1/news
    ? access_key = API_KEY & date =

Request Parameters:

Parameter Description
access_key [Required] Your API Key.
date [Optional] Use this parameter to specify a date or date range. Example: &date=2020-01-01 for news on Jan 1st and &date=2020-12-24,2020-12-31 for news between Dec 24th and 31st.

The API response and parameters are given above in the /news endpoint example.

Specify Sources

When making a news data API request, you can filter down your results by news sources. To do that you will need to attach the sources parameter to your API request URL and set it to one or multiple news source values. As you can see in the example below, it is also possible to exclude specific news sources by prepending them with a - symbol.

GET https://api.financelayer.com/v1/news
    ? access_key = API_KEY & sources = forbes.com
Parameter Description
access_key [Required] Your API Key.
sources [Optional] Use this parameter to include or exclude one or multiple comma-separated news sources. Example: To include forbes.com, but exclude bloomberg.com: &sources=forbes.com, -bloomberg.com

The API response and parameters are given above in the /news endpoint example.

Search keywords

To narrow down your search for articles, even more, you can specify one or multiple comma-separated search keywords. As with other parameters, you can also exclude keywords by prepending a - symbol. Find a few clarifications about this parameter below.

GET https://api.financelayer.com/v1/news
    ? access_key = API_KEY & keywords = bitcoin, etherum
Parameter Description
access_key [Required] Your API Key.
keywords [Optional] Use this parameter to search for sentences, you can also exclude words that you do not want to appear in your search results. Example: To search for "New bitcoin news 2021" but exclude "Etherum": &sources=new bitcoin news 2021, -etherum

The API response and parameters are given above in the /news endpoint example.

Search tags

To narrow down your search for articles, even more, you can specify one or multiple comma-separated tags. As with other parameters, you can also exclude tags by prepending a - symbol. Find a few clarifications about this parameter below.

GET https://api.financelayer.com/v1/news
    ? access_key = API_KEY & tags = bitcoin, crypto, -etherum
Parameter Description
access_key [Required] Your API Key.
tags [Optional] Use this parameter to search for tags by which news are tagged. You can search by multiple tags, separating tags with a comma. Example: &tags=Bitcoin, money

The API response and parameters are given above in the /news endpoint example.

Search tickers

To narrow down your search for articles, even more, you can specify one or multiple comma-separated tickers. As with other parameters, you can also exclude tickers by prepending a - symbol. Find a few clarifications about this parameter below.

GET https://api.financelayer.com/v1/news
    ? access_key = API_KEY & tickers = btc, pifi
Parameter Description
access_key [Required] Your API Key.
tickers [Optional] Use this parameter to search for ticker symbols. You can search multiple tickers, separating them with comma Example: &tickers=btc, pifi

The API response and parameters are given above in the /news endpoint example.

Code Examples

The financelayer news API supports any client and server-side programming language. We have prepared code examples for the languages PHP, Python, jQuery, Go and Ruby.


Code Example - PHP

$queryString = http_build_query([
  'access_key' => 'ACCESS_KEY',
  'keywords' => 'bitcoin etherum 2021 -etherum, // the word "etherum" will be removed
  sources => 'forbes.com,
  'sort' => asc,
]);

$ch = curl_init(sprintf('%s?%s', 'https://api.financelayer.com/v1/news', $queryString));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$json = curl_exec($ch);

curl_close($ch);

$apiResult = json_decode($json, true);

print_r($apiResult);

Code Example - Python

# Python 3
import http.client, urllib.parse

conn = http.client.HTTPConnection('api.financelayer.com')

params = urllib.parse.urlencode({
    'access_key': 'ACCESS_KEY',
    sources: '-forbes.com',
    'sort': 'desc',
    'limit': 10,
    })

conn.request('GET', '/v1/news?{}'.format(params))

res = conn.getresponse()
data = res.read()

print(data.decode('utf-8'))

Code Example - jQuery

$.ajax({
    url: 'https://api.financelayer.com/v1/news',
    data: {
      access_key: 'ACCESS_KEY',
      tags: 'bitcoin',
      limit: 30,
      offset: 30,
    }
  }).done(function(data) {
    console.log(JSON.parse(data));
});

Code Example - Ruby

require 'uri'
require 'net/http'

uri = URI('https://api.financelayer.com/v1/news')

params = {
    'access_key' => 'ACCESS_KEY',
    'keywords' => 'Bitcoin 2021 -etherum,
    sources => '-bloomberg.com,
    'sort' => asc,
}

uri.query = URI.encode_www_form(params)

response = Net::HTTP.get_response(uri)

puts response.read_body

Code Example - Go

package main

import (
	"fmt"
	"io/ioutil"
	"net/http"
	"net/url"
)

func main() {
	baseURL, _ := url.Parse("https://api.financelayer.com")

	baseURL.Path += "v1/news"

	params := url.Values{}
	// Access Key
	params.Add("access_key", "ACCESS_KEY")
	// Parameters
	params.Add("sources", "forbes.com, bloomberg.com")
	params.Add("keywords", "bitcoin,crypto")
	params.Add("tags", "-etherum") // It will exclude etherum results

	baseURL.RawQuery = params.Encode()

	req, _ := http.NewRequest("GET", baseURL.String(), nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()

	body, _ := ioutil.ReadAll(res.Body)

	fmt.Println(string(body))
}