Subscribe to articles

The Finlight.me WebSocket API allows you to subscribe to article updates in real-time. Once connected and subscribed, you receive the latest article matching your query immediately, followed by any newly published articles that match your criteria as they appear.

Article model

The response article model contains all the information about an article, such as the link, title, publish date and source. It also contains a sentiment and its confidence about that.

Name
link
Type
string
Description
URL to the full article.
Name
source
Type
string
Description
Source website. E.g. www.reuters.com
Name
title
Type
string
Description
Title of the article.
Name
summary
Type
string
Description
Summary of the article if existing. Can be nullable.
Name
publishDate
Type
Date
Description
Publication date as ISO date.
Name
language
Type
string
Description
Language code in ISO 639-1. E.g. en | de | fr
Name
sentiment
Type
string
Description
Sentiment analysis result. Values can be positive | neutral |negative
Name
confidence
Type
number
Description
Confidence level of sentiment analysis from 0 to 1.
Name
images
Type
string[]
Description
Array of image URLs from the article.
Name
content
Type
string
Description
Full content of the article. Is only shown/available with specific subscription tier. Can be nullable.
Name
companies
Type
Company[]
Description
Array of companies that are mentioned in the article. Is only shown/available with specific subscription tier. Can be nullable.

Company model

The response company model contains information about a company that is mentioned in an article. It includes details like the company name, ticker symbol, industry, and more.

Name
companyId
Type
number
Description
Unique identifier for the company.
Name
confidence
Type
string
Description
Confidence level of the company identification from 0 to 1.
Name
country
Type
string
Description
Country where the company is based. E.g. United States | Germany
Name
exchange
Type
string
Description
Stock exchange where the company is listed.
Name
industry
Type
Date
Description
Industry sector of the company. E.g. Biotechnology, Technology
Name
name
Type
string
Description
Full name of the company. E.g. Apple Inc.
Name
sector
Type
string
Description
Sector of the company. E.g. Technology | Health Care
Name
ticker
Type
string
Description
Stock ticker symbol of the company. E.g. AAPL | GOOGL
Name
isin
Type
string
Description
International Securities Identification Number (ISIN) of the company. E.g. US0378331005
Name
openfigi
Type
string
Description
OpenFIGI identifier for the company. E.g. BBG000B9XRY4
Name
primaryListing
Type
object
Description
Primary stock exchange listing information for the company.
Name
primaryListing.ticker
Type
string
Description
Primary ticker symbol on the main exchange.
Name
primaryListing.exchangeCode
Type
string
Description
Code of the primary exchange where the stock is listed.
Name
primaryListing.exchangeCountry
Type
string
Description
Country of the primary exchange where the stock is listed.
Name
isins
Type
string[]
Description
Array of International Securities Identification Numbers (ISINs) for the company.
Name
otherListings
Type
object[]
Description
Array of other stock exchange listings for the company.
Name
otherListings[].ticker
Type
string
Description
Ticker symbol on the alternative exchange.
Name
otherListings[].exchangeCode
Type
string
Description
Code of the alternative exchange where the stock is listed.
Name
otherListings[].exchangeCountry
Type
string
Description
Country of the alternative exchange where the stock is listed.

WEBSOCKETdefault route

Fetch articles

When you subscribe, you’ll first receive the latest article matching your query, followed by any new articles as they are published.

When subscribing, you can specify various parameters to filter the articles you receive:

Name
query
Type
string
Description
Search query to find relevant articles. Advanced queries
Name
sources
Type
string[]
Description
Filter by article single or multiple sources. E.g. ["www.reuters.com", "www.cnbc.com"]. See source endpoint for valid values.
Name
excludeSources
Type
string[]
Description
Excludes single or multiple sources. E.g. ["www.reuters.com", "www.cnbc.com"]. See source endpoint for valid values.
Name
tickers
Type
string[]
Description
Filter by stock ticker symbols (String Array). This will return articles that mention these tickers.
Name
countries
Type
string[]
Description
Filter by company country using ISO 3166-1 alpha-2 country codes (String Array). E.g. ["US", "GB", "DE"]
Name
includeContent
Type
boolean
Description
Includes the full content of the article. Requires a specific subscription tier.
Name
includeEntities
Type
boolean
Description
Includes the companies mentioned in the article. Requires a specific subscription tier.
Name
excludeEmptyContent
Type
boolean
Description
Includes only articles that have a value in the content available. Requires a specific subscription tier.
Name
language
Type
string
Description
Filter by language. Language code in ISO 639-1
Name
extended
Type
boolean
Description
(Deprecated use includeContent) true to receive extended article information (includes content and summary).

Request

WEBSOCKET

import { FinlightApi } from 'finlight-client'

const client = new FinlightApi({
  apiKey: 'YOUR_API_KEY', // Replace with your API key
})

client.websocket.connect(
  {
    query: 'Nvidia',
    language: 'en',
    extended: true,
    countries: ['US', 'GB'],
  },
  (article) => {
    console.log('New article received:', article)
  },
)

Managing Connection Limits: If your subscription tier limits the number of parallel WebSocket connections, you can use the takeover option to automatically close the oldest connection when attempting to open a new one beyond your limit. This prevents connection errors during development or application restarts.

// TypeScript example with takeover enabled
const client = new FinlightApi(
  {
    apiKey: 'YOUR_API_KEY',
  },
  {
    takeover: true, // Automatically close oldest connection when limit is reached
  },
)

# Python example with takeover enabled
from finlight_client import WebSocketConfig

client = FinlightApi(
    config=ApiConfig(api_key="YOUR_API_KEY"),
    websocket_config=WebSocketConfig(takeover=True)
)

By default, takeover is set to false, which means new connections will be rejected if you've reached your limit. Enable it during development for convenience, but consider keeping it disabled in production for explicit connection management.

Response

{
  "link": "https://www.example.com/article1",
  "source": "www.example.com",
  "title": "Stock Market Hits New Highs",
  "summary": "A brief summary of the article...",
  "publishDate": "2023-10-01T12:34:56Z",
  "language": "en",
  "sentiment": "positive",
  "confidence": 0.95,
  "images": [
              "https://www.example.com/image1.jpg",
              "https://www.example.com/image2.jpg"
            ],
  "content": "Full article content here...",
  "companies": [
            {
                "companyId": 41494,
                "confidence": "0.9335401058197021",
                "country": "United States",
                "exchange": "XNAS",
                "industry": "Biotechnology: Pharmaceutical Preparations",
                "name": "Summit Therapeutics Inc. Common Stock",
                "sector": "Health Care",
                "ticker": "SMMT",
                "isin": "US86627T1088",
                "openfigi": "BBG01PH11VP5",
                "primaryListing": {
                    "ticker": "SMMT",
                    "exchangeCode": "XNAS",
                    "exchangeCountry": "United States"
                },
                "isins": ["US86627T1088", "US86627T2088"],
                "otherListings": [
                    {
                        "ticker": "SMMT.L",
                        "exchangeCode": "XLON",
                        "exchangeCountry": "United Kingdom"
                    }
                ]
            },
            ...
          ]
}

You can keep the connection open and receive articles in real-time without additional requests. As new articles become available, they are pushed directly to your callback function.