On demand through HTTP
This page describes the a way to integrate a companies news feed on there website, that is loaded on demand when a user is visiting the website.
Intro
This is an example of how to use the REST-ish API (but should really be viewed more as a RPC) when using a server side to render a web page, such as wordpress or most other CMS where you have direct access to code. We assume that you have access to a HTTP client and that you know your way around your code base.
In the examples below we will be using JSON, but other formats can be used as well by modifying the extension .json to .xml
We suggest that you inspect the url:s in the example below an get a feeling for how the data and the urls is structured. By removing the extension, eg .json, this will give you a website that shows the content.
Clients (beta)
There are clients available in PHP, Javascript, DotNet/C# and Java.
In general the clients are structured around a builder pattern and should be fairly straight forward to work with.
Find then at the following links
URLs
MFN have a quite flexible url query system. It all starts with https://mfn.se/all/a.json This will return all news for all companies. The idea is then that query params are used to filter down the response to what is needed
UUIDs
MFN uses UUIDs to identify pretty much everything, https://en.wikipedia.org/wiki/Universally_unique_identifier. You will se them appear as identifiers for news, authors, groups and more. They take the from of a 36 char string, 32 hex chars and 4 dashes, eg d502dee6-00d2-48e9-83a4-d9f2a4076e8b
Author
When implementing a news room we construct this from an author and its id. This will filter out all news but the news authored by the entity in question. eg. Volvo https://mfn.se/all/a.json?.author.entity_id=df018f2d-d36c-41d6-92b1-9b255c56ce79
The query param .author.entity_id=df018f2d-d36c-41d6-92b1-9b255c56ce79 should then continue to be used on all queries that relate to the feed. It should be a static part of all queries
The .author.entity_idcan be found in the any feed or news item. But we can also help with it.
Index
Having an index is one of the main features, this gives a user the ability to see what news there are and the possibility to navigate to it. You can see our example of what a Index is here
The most basic index for Volvo is then the following URL https://mfn.se/all/a.json?.author.entity_id=df018f2d-d36c-41d6-92b1-9b255c56ce79
The following sections can be combined in order to create the Index you want.
It important to validate input from the client side to get an expected result.
Types
When integration towards a website, it is important to cover both types. Since default is type=ir PR wont be received by your website unless type=all is specified
We classify all news items into one of two types. They are IR, Investor Relationship, and PR, Public Relationship. Most news items sent through MFN is of the type IR. The main difference between the two is that PR is not sent to third party distributors of news items, such as Avanza or Bloomberg, but mainly suppose to be disseminated via email and at the companies own web site. You can use the the query param type for this. The default is IR, so if you want the PR releases displayed on the page, it is important append type=all so that everything is included.
https://mfn.se/all/a.json?.author.entity_id=b64b654a-26ab-45a5-bf5e-78064331219e&type=all
https://mfn.se/all/a.json?.author.entity_id=b64b654a-26ab-45a5-bf5e-78064331219e&type=ir
https://mfn.se/all/a.json?.author.entity_id=b64b654a-26ab-45a5-bf5e-78064331219e&type=pr
Pagination
This will however only display the top 48 items or so. Some sort of pagination is there for in order. This is done with the limit and offset query param. So let us introduce a variable page and set limit to 20 items to a page. This will result in the following
Page 0, offset = page*limit = 0*20 = 0
https://mfn.se/all/a.json?.author.entity_id=df018f2d-d36c-41d6-92b1-9b255c56ce79&limit=20&offset=0
Page 1: offset = page*limit = 1*20 = 20
https://mfn.se/all/a.json?.author.entity_id=df018f2d-d36c-41d6-92b1-9b255c56ce79&limit=20&offset=20
Page 2: offset = page*limit = 2*20 = 40
https://mfn.se/all/a.json?.author.entity_id=df018f2d-d36c-41d6-92b1-9b255c56ce79&limit=20&offset=40
All response also contains the variable next_url which can be used for the same purpose.
Internationalization
Internationalization is often required and an index containing multiple languages is not always the proper solution. This can be achieved by adding adding the query param lang and used accordingly
Only news written in English https://mfn.se/all/a.json?.author.entity_id=df018f2d-d36c-41d6-92b1-9b255c56ce79&lang=en Only news written in Swedish https://mfn.se/all/a.json?.author.entity_id=df018f2d-d36c-41d6-92b1-9b255c56ce79&lang=sv
Temporal Locality
Enabling an index to show only items from a specific time period is often desired, eg. Showing only news items from 2015, this can be accomplished by using from and to query param. They take a timestamp using ISO 860, 2019-06-26T09:49:12Z
To view only items from 2015 https://mfn.se/all/a.json?.author.entity_id=df018f2d-d36c-41d6-92b1-9b255c56ce79&from=2015-01-01T00%3A00%3A00Z&to=2015-12-31T23%3A59%3A59Z
Tags
Most implementations contains some sort of filter to enable eg. Only viewing news items that are Regulatory or only Reports. This is accomplished by using the tag query param. MFN has quite an expansive set of tags that can be used which can be found in the News Item model taxonomy.
If we want an index only showing regulatory news items, we can do this by using the following url https://mfn.se/all/a.json?.author.entity_id=df018f2d-d36c-41d6-92b1-9b255c56ce79&tag=:regulatory
If we want and index only showing news items that is taged as reports, we can do this by https://mfn.se/all/a.json?.author.entity_id=df018f2d-d36c-41d6-92b1-9b255c56ce79&tag=sub:report
News items sent by other providers then MFN, might not be as expressive in terms of tags
Search
Implementing free text search in the news items could be desirable this can be done with the query param query eg. searching for the keyword nvidia
https://mfn.se/all/a.json?.author.entity_id=df018f2d-d36c-41d6-92b1-9b255c56ce79&query=nvidia
News Item
Fetching and displaying a news item should be done in the manner described below. From the index we fetch the news_id of the item of interest. This will enable you to fetch only this one. https://mfn.se/all/a.json?.author.entity_id=df018f2d-d36c-41d6-92b1-9b255c56ce79&news_id=ae0aa472-4657-4e10-a8e8-1c0f6800f9cc&type=all
Remember to validate that the news id indeed is UUID, if it is left empty you will get a feed for the author
Internationalization
If you are displaying an English news item and want to toggle to the Swedish version of the same item. This is done by using the query param lang and group_id which links translations of the same item.
This can, for now, only be done with news items sent through MFN
Return all translation of the newsitems in group https://mfn.se/all/a.json?.author.entity_id=b64b654a-26ab-45a5-bf5e-78064331219e&.group_id=f13f2e31-ce26-4195-9975-1cf208e79b24&type=all
Returns a English translation, if present. https://mfn.se/all/a.json?.author.entity_id=b64b654a-26ab-45a5-bf5e-78064331219e&.group_id=f13f2e31-ce26-4195-9975-1cf208e79b24&lang=en&type=all
Returns a Swedish translation, if present. https://mfn.se/all/a.json?.author.entity_id=b64b654a-26ab-45a5-bf5e-78064331219e&.group_id=f13f2e31-ce26-4195-9975-1cf208e79b24&lang=sv&type=all
Report Archive
The API can also be used to create an automatic report archive for Financial reports, such at Quarterly or Annual reports.
By adding the tag sub:report you will get all Pressrelease that are considered reports. eg. https://mfn.se/all/a?.author.entity_id=df018f2d-d36c-41d6-92b1-9b255c56ce79&tag=sub:report
Links to the PDFs in question can the be found under items[x].attachments
Notes
When implementing news on any website, is important to remember client side caching and that many browsers has an aggressive default cache policy. Any page that renders news should therefore ensure that the clients browser does not cache the page. This is done by setting caching policy headers on the server side. eg
Cache-Control: max-age=0, no-cache, no-store, must-revalidate
Expires: Thu, 01 Jan 1970 00:00:00 GMT
Pragma: no-cache
Failing this to do this could, in the worst case, be considered a violation of EUs MAR regulation that demands simultaneous publishing
Last updated