Documentation

These are the core API Specifications. Additional detail and interactive features are available via your Developer Dashboard when you sign up.

API Specifications

Authentication

The Alpha News Stream (ANS) requires an X-Api-Key HTTP header to be present with each call made to the API. Once you have signed up for your ANS developer account, you are given an ANS API Key, which must be present as a header in each API call you make.

Your ANS API consumption is tracked and, based on your plan, usage is billed accordingly. We require the API key to be passed using HTTP headers to ensure the security of your credentials in transit.

API specifications
*Once you sign up for a Free Trial you will have access to your API Key here.

Query Parameters

These are the optional input parameters that filter the output depending on which parameters you provide.

  • count: (number) – Headline count (integer). Maximum count is 1000 for recent articles (start_date is less than 2 weeks from today, or no start_date given). Maximum count is 100 for articles older than two weeks. If not given, the default count is 100. Headlines older than two weeks (archived) are available back to January 1, 2017.
  • date: (string) – Date in YYYY-MM-DD format or the string “today”. Note that all times are in UTC.
  • start_date: (string) – Date in YYYY-MM-DD format. Note that all times are in UTC.
  • end_date: (string) – Date in YYYY-MM-DD format. Note that all times are in UTC. May only be used with start_date parameter.
  • start_time: (string) – Time in hh:mm 24-hour format. Note that all times are in UTC. May only be used with date parameter.
  • end_time: (string) – Time in hh:mm 24-hour format. Note that all times are in UTC. May only be used with date parameter.
  • latest: (number) – Returns latest N days of articles
  • symbol: (string) – Single ticker symbol. Symbols for exchanges other than NYSE and NASDAQ require a MIC suffix. Example: ATA.XTSE
  • summary: (string) – Include summary text in the output if yes
  • source: (string) – Selects the press release source only. If not specified, all news sources will be used. The press releases sources are:
    Pressreleases = selects articles from all press release sources.
    PR_Newswire = PR Newswire
    Accesswire = Accesswire
    Marketwire = Marketwired News (ceased service 7/1/18)
    Businesswire = Business Wire
    CNW = CNW Group
    Globe = Globe Newswire
    Thomson = Thomson Reuters (folded into Globe 11/25/19)
    Pressreleases = All of the above sources

    Financial = Tighter selection of more traditional financial news sources (includes all press releases)
  • reference: (string) – Retrieve a single article with a URL encoded URL. May not be combined with any other parameter
  • sector: (string) – Select articles based on sector (list of values will be provided).
  • subsector: (string) – Select articles based on subsector.
  • topic: (string) – Select articles based on topic. The Topic tag is semantically generated based on an open source tagging system and is rarely used. When available, it can use a variety of parameters.
  • category: (string) – Select articles based on category. Categories are editorial tags added to identify a specific financial category or topic. (list of values will be provided).
  • headline_query: (string) – Select articles based on words in headline. Words are separated by comma, plus sign (+) or space (URL entity %20)
  • paywall_notification: (string) – When on, an additional data point will indicate whether the source of the article is paywalled as: Hard (most or all access requires subscription); Soft (articles are free to read until some limit is reached, then subscription is required); or None (all articles are free to read).

Output Schema

These are the objects you will get back with each call to the Alpha News Stream API, providing the schema you can use to integrate into your applications.

news

  • status (string) – The outcome of the news API request (Success or Error).
  • message (string) – The accompanying message for response. If there is an error, this field will contain a plain language message explaining the error.
  • delay (number) – How long the response took, in seconds.
  • articles (array) –

article

  • pub_time (string) – The publication time of article, specified in seconds since January 1, 1970.
  • headline (string) – The headline for the article.
  • date (string) – The date of the article. Specified as MM/DD/YYYY where MM and DD may be one or two digits.
  • time (string) – The time of the article. Specified as HH:MM AM or PM. HH may be one or two digits.
  • source (string) – The source of the article, whether a news or press release source.
  • url (string) – The URL of the article.
  • images (string) – The URL for included article image (for research use only).
  • tags (array) –
  • id (string) – The unique id for the article.
  • summary (string) – A summary of the article; its first 300 characters (for research use only).
  • paywall (string) – Indicates type of paywall (only present when paywall_notification=on). Values are None, Soft, or Hard.

tags

  • symbols (array) – Symbol tags for the article. Symbol format in the output is EXCHANGE:TICKER where the EXCHANGE prefix is in MIC (ISO 10383) format. (Please note that this format is different than the input parameter format TICKER.EXCHANGE, where the EXCHANGE is a suffix.)
  • sectors (array) – Sector tags for the article.
  • subsectors (array) – Subsector tags for the article.
  • companies (array) – Company tags for the article.
  • topics (array) – Topic tags for the article.
  • category_tags (array) – Category tags for the article.

The schema can be used to generate integration code, and do most of the heavy lifting when decoding the response from the ANS API.

Data Points (Objects)

The list below shows objects we add to each news headline when available or applicable. Press releases will typically include fewer data points.

symbols       

These are tag(s) we add, where possible, to identify company ticker symbols for the following exchanges: NYSE, NASDAQ, TSX, and the LSE’s FT100 stocks. The symbols field that you get back with each call to the API will include the exchange prefix in ISO 10383 format (XNYS, XNAS, XTSE and XLON, respectively). An example is: “XNYS:IBM”. Not every article will include these tags. (Symbol format in the output is EXCHANGE:TICKER whereas input parameter format is TICKER.EXCHANGE). Not every article will include a symbols tag.

sectors      

These are tag(s) we add when a symbol tag is present based on the symbols above. It identifies the company’s industry sector as defined by the exchange. This is distinct from the category_tags; outlined below. Most, but not all, symbols-identified articles will include this tag. The most commonly used sector designations include:

Technology

Energy

Financials

Materials

Utilities

Healthcare

Capital_Goods

Transportation

Telecom

Consumer_Goods

Consumer_Services

Media_Advertising

Business_Services
Industrials 
Real_Estate
Consumer_Cyclical
Consumer_Durables
Consumer_Defensive
Communication_Services

subsectors

These are tag(s) we add, when a symbol tag is present based on the symbols, above. It identifies the company’s industry subsector as defined by the exchange. It includes many potential parameters for companies public or private, so there is no list of all possible parameters. Most, but not all, symbols-identified articles will include this tag.

companies Company names within an article may be listed here.

The above tag is semantically generated and includes many potential parameters for companies public or private, so there is no list of all possible parameters. Not every article will include these tags.  

images Includes the link to an associated image within the RSS newsfeed.

The above data point adds a link, where available, to an image included in the RSS newsfeed content that appears in the originating article. Copyright applies.

paywall Designates whether the headline source has a paywall.

The above tag is generated to show whether the originating news source has a paywall for the linked article. Designations are: Hard (most or all access requires subscription or registration); Soft (articles are free to read until some article limit is reached, then subscription is required); or None (all articles are free to read) 

topics Other topics, even non-financial, may be included here.           

The topics tag may be found in some historical headlines. It was semantically generated based on an open source tagging add-on we no longer utilize and includes a variety of generic topics as parameters. This tag could be used to identify future data points. Topics may include:  

Business_Finance  
Disaster_Accident
Education
Entertainment_Culture
Environment
Health_Medical_Pharma
Hospitality_Recreation
Human_Interest
Labor
Law_Crime
Politics
Religion_Belief
Social_Issues
Sports
Technology_Internet
Weather
War_Conflict
Other

category_tag

These are editorial tag(s) we add to identify a specific financial category or topic. They are specific, finite and defined by our editorial team based on their usefulness. Some will overlap with sector tag parameters. Not every article will include these tags.

Some of these categories are based upon Morningstar sector designations. Category tag parameters may include:

Technology
Energy
Financials
Materials
Utilities
Healthcare
Capital_Goods
Transportation
Telecom
Consumer_Goods
Consumer_Services
Media_Advertising
Business_Services

Precious_Metals
Forex

Financial_News                 An editorially chosen all-purpose financial headline category.
General                               When no topic is specified.
Green_Tech

Business_Video                Just video.
Business_Podcast           Just podcasts
Financial_Bloggers          Just bloggers.

Open API

For your convenience, we have included Open API specifications:

Download Open API Specifications

Limits

Most plans have unlimited usage. Check your plan for specifics.

• Trial plan: 250 requests per day

• Custom plan: per agreement

• Burst rate limit: 1 request per second

• Editorial limit: In headlines where Summary text is available, we provide only the first 300 characters. This Summary text and the link to article images, if available, are for research use only as they are copyright-protected by the source.

• Editorial limit: Archived headlines are available back to January 1, 2017.

Best Practices

Streaming News (no older than 14 days): To avoid missing a headline, the best practice is to request all news, count=1000, once every 5 minutes. Once you have retrieved the headlines, you can sort or filter them as appropriate for your needs (by symbol, by source, by topic, etc.) 

Archived News (any headline older than 14 days): The best practice is to request by symbol or source, count=100, with a start_date and end_date. If you are scanning a large date range, start with the most recent end_date and work backwards, adjusting the end_date to the earliest found article date, and repeat.

Alpha News Stream
© - Frankcom & Associates, Inc.

Resources

Company