Introduction

The fswire API provides real time social analytics including sentiment, volume and trending for major US/UK securities and FX pairs in JSON format. This is presented as two distinct APIs:

  • REST API for historic data, account management and polling implementations

    • Javascript (JQuery/AngularJS)

    • Microsoft.Net/Mono API Limited to authentication and retrieving list of assets (more functionality coming)

  • REAL-TIME streaming API with client libraries for popular programming platforms hosted on our public GitHub repositories

    • Microsoft.Net/Mono API

    • Javascript (TBD)

The API is available for personal/developer use and provides a very cost effective way to experiment with the data, increasing the cost, only as your usage increases.

The following information will provides details on how you can interact with the API and what data it contains.

Prior to any data request you must register for an FSWire account and APP_ID

Concepts

At fswire we supply data a streams of information. A stream consists of a TYPE which defines what information is used, the different stream types are as follows:

  • Curated

    fswire's unique and comprehensive taxonomy is used to identify content pertinent to a particular asset/event/sector

  • Search

    User defined boolean style query which is executed over our fulltext indexes and taxonomy to identify relevant content

  • Curated Search

    Hybrid which allows a user to further filter/search within an fswire curated stream

One defined each stream provides various categories of information, analytics and alerts that a user or machine can consume:

  • Messages

  • Links

  • Alerts

  • Analytics

Authentication

There are two levels of authentication to the api

  • User Authentication Using classical username (usually email address) and password combination which will either provide cookie based session or alternatively return a cycling authentication token for you to use on subsequent calls

    HTTP/Post

    http://api.fswire.com/api/users/sign_in.json? user_login[email]=EMAIL&user_login[password]=PASSWORD

    JSON/Post

    curl -X POST -D '{"user_login": {"email": "", "password": ""}}' http://api.fswire.com/api/v1/users/sign_in --header "Content-Type:application/json"

    returns a JSON payload containing and authorisation token (AUTH_TOKEN) needed for all subsequent calls

    {
    "success": true,
    "auth_token": "",
    "email": "",
    "id": 1,
    "is_admin": false,
    "is_cleaner": false}
  • Stream Authentication

    Once a user is authenticated to the system, subsequent authentication checks are made for each real-time stream one connects too, currently the only method to achieve this is through one of the aforementioned streaming API libraries that we supply

Streaming API

The process of accessing the streaming api requires initial authentication to the server followed by subscription to each asset/security one is interested in. You can retrieve a list of available securities using the Securities List api method, once you have identified the security from the list an additional call is required to identify the open streaming channel one needs to subscribe too in order to received live streaming data. The current implementation favours web-sockets !

Connect to the stream using the FSWire client library of your choice

Resources

Alerts

Resource Description
GET api/v1/streams/:id/alerts returns a list of alerts for this stream
GET api/v1/streams/:id/alerts/:alert_id returns the alert detail for this stream
PUT api/v1/streams/:id/alerts/:alert_id updates the alert as being read by the user

Analytics

Resource Description
GET api/v1/streams/:id/analytics/summary_by_day returns a list of aggregated by day analytics for the stream ordered by descending time series
GET api/v1/streams/:id/analytics/sentiment_summary_by_day returns a list of sentiment aggregated by day analytics for the stream ordered by descending time series
GET api/v1/streams/:id/analytics/volume_summary_by_day returns a list of volume by day for the stream ordered by descending time series
GET api/v1/streams/:id/analytics/ssi_summary_by_day returns a list of aggregated by day analytics for the stream ordered by descending time series
GET api/v1/streams/:id/analytics/message_momentum returns a list of time series fswire momentum data for the stream ordered by descending time series
GET api/v1/streams/:id/analytics/message_percentage_range returns a list of time series fswire volume percentage relative to the date/time range supplied (defaults to the last 7 days) for the stream ordered by descending time series

Links

Resource Description
GET api/v1/streams/:id/links Displays the list of links associated with a stream
GET api/v1/streams/:id/links/historical Displays the list of links associated with a stream for a particular date range
GET api/v1/streams/:id/links/trending Displays the list of trending links associated with a stream for a particular date range

Messages

Resource Description
GET /api/v1/streams/:id/messages Displays the list of messages associated with a stream
GET /api/v1/streams/:id/messages/historical Displays the list of messages associated with a stream for a particular date range
GET /api/v1/messages/:id returns full details of a message
POST /api/v1/messages/:id/report_spam Allows a user to report an inappropriate message to system administrators
POST /api/v1/messages/:id/favourite Allows a user to mark a message as being useful to them
GET /api/v1/messages/favourites Returns the user's favourite messages

Search

Resource Description
GET /api/v1/search Provides full boolean search fidelity across all curated financial data
GET /api/v1/search/messages Provides full boolean search fidelity across all curated messages financial data
GET /api/v1/search/links Provides full boolean search fidelity across all curated web pages
GET /api/v1/search/message_analytics provides per day analytics for any search expresion, including average sentiment and full message volume
GET /api/v1/search/author_analytics provides list of the top authors for a given boolean search over a defined time period

Streams

Resource Description
GET /api/v1/streams/curated List of system-wide curated streams available to the current user
GET /api/v1/streams/current_searchs List of search streams defined and selected by the user
GET /api/v1/streams/current_curated List of curated streams selected by the user
GET /api/v1/streams/current_watch_list List of streams in the user's watch list
GET /api/v1/streams/current List of streams selected by the user
GET /api/v1/streams/index List of streams selected by the user
GET /api/v1/streams/recent List of streams recently accessed by the user (that are NOT current)
GET /api/v1/streams/:id Displays the stream details
GET /api/v1/streams/new Stream template for creating a new stream
POST /api/v1/streams Creates a new stream
PUT /api/v1/streams/:id Updates an existing stream
DELETE /api/v1/streams/:id Removes the stream for the users current list
PUT /api/v1/streams/update_order Updates the order of the list of streams a user has open
GET /api/v1/streams/:id/messages Displays the list of messages associated with a stream
GET /api/v1/streams/:id/historical_messages Displays the list of messages associated with a stream for a particular date range
GET /api/v1/streams/:id/links Displays the list of links associated with a stream
GET /api/v1/streams/:id/historical_links Displays the list of links associated with a stream for a particular date range
GET /api/v1/streams/:id/top_authors Displays the list of top authors for this stream over a particular date range
GET /api/v1/streams/:id/top_domains Displays the list of top domains for this stream over a particular date range
GET /api/v1/streams/:id/top_links Displays the list of top urls/links for this stream over a particular date range

Users

Resource Description
POST /api/users/sign_in Logs in a user and returns the rolling authentication token for subsequent authentication/api calls
DELETE /api/users/sign_out Logs the user out and destroys their associated authentication token
GET /api/v1/users/search Search for users whom have posted messages
GET /api/v1/users/:id/messages Displays the list of messages created by a user