Introduction

Welcome to the IFR Story API documentation page. Here you will find information about the IFR API news products, API endpoints, authentication and how to process the NewsML format returned by the API.


Products

The IFR Story API includes all IFR authored news across Bonds, Structured Finance, Loans, Equities, Rates, Economics and People & Markets. It also includes FX content from Reuters FX Buzz. The US Rates content is subject to regulatory restrictions and so may be included or excluded depending on the terms of the agreement.


Subscriptions

The IFR Story API offers all the latest IFR news content, securely available on a real time, headline only, delayed or end of day basis. In addition, and depending on subscription level, a full archive extract is available for download. Please contact your IFR account manager to discuss all available options.


Endpoints

The Story API is composed of the following endpoints:


Authentication

Use this endpoint to request a token that will be sent with subsequent requests for stories.

The endpoint can either be used via the Swagger UI or programmatically.

  • Swagger UI - login using your credentials and copy the returned token into your client code for use in the authentication header.
  • Programmatically - call the endpoint once at the beginning of a session and use the token in subsequent requests.

Method POST
URL https://news-api.ifre.com/v1/auth
Input Username and Password
Request content type application/x-www-form-urlencoded
Response content type application/xml
Success An XML response with token and success message. Sample below
                                
                                    <TokenResponse>
                                        <Token>XXXXXXXXXXXXXXX</Token>
                                        <Message>Success</Message>
                                    </TokenResponse>
                                
                            
Login failed 401 code and XML below
                                
                                    <TokenResponse>
                                        <Message>Response status code does not indicate success: 401 (Unauthorized).</Message>
                                    </TokenResponse>
                                
                            
Other possible errors Code 500, if there is an issue with the server

Realtime Endpoint

Use this endpoint to request the latest published stories.

  • Poll for content a maximum of once every 30 seconds.
  • The content returned is based on your subscription. The only input required is the token from the authentication endpoint.
  • The endpoint returns content that you have not processed before in the order in which the content was published.
  • A maximum of 500 stories can be returned per call.

Method GET
URL https://news-api.ifre.com/v1/realtime
Input Authorisation header using the token from the Authentication endpoint
                                Authorization: Bearer <token>
                                
Response content type application/xml
The response is specialized XML format called NewsML-G2
Success XML list of stories
Authorisation failed 403 code and XML below
                                
                                    <TokenResponse>
                                        <Response status code does not indicate success: 403 (Forbidden)..</Message>
                                    </TokenResponse>
                                
                            
Other possible errors Code 500

Archive Endpoint

Use this endpoint to request and download historical content.

  • Ensure you have a subscription that allows for historical content before calling this endpoint.
  • The content returned is based on your subscription (and any customisations applied). In addition to the authentication header you can also provide a date range to filter stories and some pagination parameters.
  • A maximum of 500 stories will be returned per call. The pagination element can be utilised to scroll through the results.

Method POST
URL https://news-api.ifre.com/v1/archive
Input Authorisation header using the token from the Authentication endpoint
                                Authorization: Bearer <token>
                                
XML request in body
                                
                                        <NewsRequest>
                                            <StartDate></StartDate>
                                            <EndDate></EndDate>
                                            <PageNumber></PageNumber>
                                            <PageSize></PageSize>
                                        </NewsRequest>
                                    
                                

Dates format: YYYY-MM-DD or YYYY-MM-DD HH:mm:ss

Time must be in UTC. If YYYY-MM-DD is used,data is returned with timestamps between start date 00:00:00 UTC and end date 23:59:59 UTC

Request content type application/xml
Response content type application/xml
The response is specialized XML format called NewsML-G2
Success XML list of stories
Authorisation failed 403 code and XML below
                                
                                    <TokenResponse>
                                        <Message>Response status code does not indicate success: 403 (Forbidden).</Message>
                                    </TokenResponse>
                                
                            
Other possible errors Code 500

Delayed Endpoint

Use this endpoint to request the published stories delayed by 24 hours.

  • Poll for content a maximum of once every 30 seconds.
  • The content returned is based on your subscription. The only input required is the token from the authentication endpoint.
  • The endpoint returns content that you have not processed before in the order in which the content was published.
  • A maximum of 500 stories can be returned per call.

Method GET
URL https://news-api.ifre.com/v1/delayed
Input Authorisation header using the token from the Authentication endpoint
                                Authorization: Bearer <token>
                                
Response content type application/xml
The response is specialized XML format called NewsML-G2
Success XML list of stories
Authorisation failed 403 code and XML below
                                
                                    <TokenResponse>
                                        <Response status code does not indicate success: 403 (Forbidden)..</Message>
                                    </TokenResponse>
                                
                            
Other possible errors Code 500

End Of Day Endpoint

Use this endpoint to request the published stories published the previous day.

  • The content returned is based on your subscription (and any customisations applied).
  • In addition to the authentication header you can also provide a date to filter stories and some pagination parameters.
  • The API can be called any time from 00:00 UTC to get stories from the previous day.
  • A maximum of 500 stories will be returned per call. The pagination element can be utilised to scroll through the results.

Method POST
URL https://news-api.ifre.com/v1/end-of-day
Input Authorisation header using the token from the Authentication endpoint
                                Authorization: Bearer <token>
                                
XML request in body
                                
                                        <DayNewsRequest>
                                            <date></date>
                                            <PageNumber></PageNumber>
                                            <PageSize></PageSize>
                                        </DayNewsRequest>
                                    
                                

Dates format: YYYY-MM-DD

Response content type application/xml
The response is specialized XML format called NewsML-G2
Success XML list of stories
Authorisation failed 403 code and XML below
                                
                                    <TokenResponse>
                                        <Response status code does not indicate success: 403 (Forbidden)..</Message>
                                    </TokenResponse>
                                
                            
Other possible errors Code 500

Swagger

Swagger UI can be found here.


News ML

The API returns data that conforms to the NewsML-G2 standard. Details of the standard can be found at https://iptc.org/standards/newsml-g2/.

This section provides a guide on how to process the xml in the context of the Story API. We also document custom elements that convey additional information not in the standard.


News Message

The following snippet is a high level XML structure returned by the API. Standard documentation can be found here.

                    
                        <newsMessage>
                            <header>
                                <sent>06/13/2022 09:10:54</sent>
                                <catalogRef href="http://www.iptc.org/std/catalog/catalog.IPTC-G2-Standards_32.xml"/>
                                <sender>https://www.lseg.com/</sender>
                                <transmitId>5a41bc27-cd80-4acd-a950-9d8d86a650e79</transmitId>
                                <priority>1</priority>
                                <origin>IFROne</origin>
                                <timestamp role="received">06/13/2022 09:10:54</timestamp>
                                <timestamp role="transmitted">06/13/2022 09:10:54</timestamp>
                                <signal qcode="nmsig:atomic"/>
                            </header>
                            <itemSet>
                                <packageItem>
                                    <itemRef residref="1" />
                                    <itemRef residref="2" />
                                    <itemRef residref="3" />
                                    <itemRef residref="n" />
                                </packageItem>
                                <newsItem guid="1"></newsItem>
                                <newsItem guid="2"></newsItem>
                                <newsItem guid="3"></newsItem>
                                <newsItem guid="n"></newsItem>
                            </itemSet>
                            <newsPaging pageIndex="1" totalPages="1" pageSize="500" totalCount="100" listCount="100" startIndex="1" endIndex="100" hasPreviousPage="false" hasNextPage="false" />
                      </newsMessage>
                        
                    

/newsMessage Uppermost element that encapsulates the API response
/newsMessage/header The header contains information related to the response whole transmission. This includes the sender and timestamps of when the message was generated.
/newsMessage/itemSet The item set wraps the news items being transmitted.
/newsMessage/itemSet/packageItem We are using the package item to list references to news items items contained in the response. The .//itemRef/@residref corresponds to the guid attribute on the newsItem.
/newsMessage/itemSet/newsItem The news item contains details of each individual article.
/newsMessage/newsPaging CUSTOM This extension element provides pagination information useful for processing large datasets.


News Item

The news item contains details of each individual article. Use the xpath /newsMessage/itemSet/newsItem to get a list of stories from the result.

                        
                            <newsItem guid="7db610e2-d101-4c7d-96c1-345dj443d34f" version="1.0" standard="NewsML-G2" standardversion="2.28">
                                <Identification>
                                    <NewsIdentifier>
                                        <Briefings />
                                    </NewsIdentifier>
                                </Identification>
                                <rightsInfo>
                                    <copyrightHolder uri="https://www.lseg.com/">
                                    <name>LSEG</name>
                                    </copyrightHolder>
                                    <copyrightNotice>Copyright � LSEG 2022. Click For Restrictions - https://www.lseg.com/en/policies/website-disclaimer </copyrightNotice>
                                    <usageTerms>https://www.lseg.com/en/policies/website-disclaimer </usageTerms>
                                </rightsInfo>
                                <itemMeta>
                                    <itemClass qcode="ninat:text" msgType="S" />
                                    <provider qcode="nprov:LSEG" />
                                    <versionCreated>2022-06-13T01:29:53.599396</versionCreated>
                                    <firstCreated>2022-06-13T01:29:53.599396</firstCreated>
                                    <pubStatus qcode="stat:usable" />
                                    <publisherAction>CreateNew</publisherAction>
                                    <isPublic>false</isPublic>
                                    <signal qcode="sig:update" />
                                    <signal qcode="edStat:N" />
                                    <role qcode="itemRole:N" />
                                </itemMeta>
                                <contentMeta>
                                    <deals>
                                        <ifr />
                                        <sdc />
                                    </deals>
                                    <contentCreated>2022-06-13T01:29:53.599396</contentCreated>
                                    <contentModified>2022-06-13T01:29:53.599396</contentModified>
                                    <located />
                                    <creator role="cRole:source" qcode="NS:IFR" />
                                    <infoSource role="cRole:source" qcode="NS:IFR" />
                                    <infoSource role="cRole:origProv" qcode="NS:IFR" />
                                    <subject type="topic" qcode="GB">
                                    <name xml:lang="en">United Kingdom</name>
                                    </subject>
                                    <subject type="topic" qcode="B:1795">
                                    <name xml:lang="en">Cloud Computing Services (TRBC level 5)</name>
                                    </subject>
                                    <subject type="company" qcode="R:LSEG.L">
                                    <name xml:lang="en">London Stock Exchange Group PLC</name>
                                    <permId>4298007752</permId>
                                    </subject>
                                    <subject type="company" qcode="">
                                    <name xml:lang="en">GFT Group Limited</name>
                                    <permId>5080175626</permId>
                                    </subject>
                                    <audience type="product" qcode="1LEHY">
                                    <name xml:lang="en">Europe High Yield Briefing</name>
                                    </audience>
                                    <audience type="product" qcode="1LECB">
                                    <name xml:lang="en">Europe Corporate Briefing</name>
                                    </audience>        
                                    <slugline />
                                    <headline>Sample story 1</headline>
                                    <url>https://www.ifre.com/story/3235057/sample-story-1-6lt53bp7k4</url>
                                </contentMeta>
                                <contentSet>
                                    <inlineXML contenttype="application/nitf+xml">
                                    <nitf>
                                        <head xmlns="http://iptc.org/std/NITF/2006-10-18/">
                                        <docdata>
                                            <doc.copyright holder="LSEG" year="2022" />
                                        </docdata>
                                        </head>
                                        <body xmlns="http://iptc.org/std/NITF/2006-10-18/">
                                        <body.head>
                                            <hedline>
                                            <hl1>
                                                <Value>Sample story 1</Value>
                                            </hl1>
                                            </hedline>
                                            <dateline>
                                            <story.date>2022-06-13T01:29:53.599+00:00</story.date>
                                            </dateline>
                                        </body.head>
                                        <body.content>
                                            <span xmlns="">
                                            <p>By Author One</p>
                                            <p>
                                                London , Jun 13 (IFR) 
                                            </p>
                                            <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p>
                                            <p>Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.</p>
                                            <p>(Reporting by Author One; Editing by Editor One)</p>
                                            <p>((author.one@lseg.com))</p>
                                            </span>
                                        </body.content>
                                        <body.end>
                                            <tagline>Author One,012 345 6789,author.one@lseg.com</tagline>
                                        </body.end>
                                        </body>
                                    </nitf>
                                    </inlineXML>
                                </contentSet>
                                </newsItem>
                        
                    

newsItem[@guid] Story unique id. This remains the same across story versions
newsItem[@version] Current story version
.//Identification/NewsIdentifier/BriefingsCUSTOM Name of IFR briefing. Populated when the following product codes are used IECM(IFR European ECM),IUSE(IFR US ECM),IADC(IFR Asia DCM) and IAEC(IFR Asia ECM)
.//rightsInfo Copyright information and usage terms
.//itemMeta/itemClass[@msgType] Message types
  • S - new stories and alerts
  • D - deleted
  • A - Updated stories
.//itemMeta/role[@qcode] Story types
  • itemRole:N - Story
  • itemRole:A - Alert
.//itemMeta/publisherActionCUSTOM Custom element documenting the action taken by authors to create the current version of the story. Full list of actions and the suggested processing by consumers is doumented under the publisher actions below.
.//itemMeta/isPublicCUSTOM Is the story behind the paywall or not?
.//itemMeta/firstCreated Date when the story was first published. The following rules are applied in order
  1. When story type is alert or version is 1 or copy action is newsbreak then use current publish date
  2. If part of alert chaining look for the publish date of the first newsbreak
  3. Any other story look for version 1 publish date
.//itemMeta/versionCreated Current version publish date based on the publisher actions rules.
.//contentMeta/contentCreated Same as .//itemMeta/firstCreated
.//contentMeta/contentModified Same as .//itemMeta/versionCreated
.//contentMeta/creator[@qcode]
.//contentMeta/infoSource[@qcode]
Story source - IFR or PFIE NS:{source}
.//contentMeta/subject Subjects refer to topics or issuers in the article
.contentMeta/subject[@type, @qcode]
  • type - topic or company
  • qcode - topic code or issuer symbol
.//contentMeta/subject/name Topic title or Issuer name
.//contentMeta/subject/permId Issuer PermId
.//contentMeta/audience Linked product codes
.//contentMeta/audience[@qcode] Product code
.//contentMeta/audience/name Product title
.//contentMeta/headline Story title
.//contentMeta/url Story website URL
.//contentMeta/deals CUSTOM Custom element to display linked deals
.//contentMeta/deals/ifr CUSTOM List of IFR deals authored in the deal input tool
.//contentMeta/deals/ifr/ifrdealCUSTOM IFR deal
.//contentMeta/deals/ifr/ifrdeal[@ifrId] CUSTOM Deal ID
.//contentMeta/deals/ifr/ifrdeal/title CUSTOM Deal title
.//contentMeta/deals/ifr/ifrdeal/url CUSTOM Deal website URL
.///contentMeta/deals/ifr/ifrdeal/identifierCUSTOM One or more deal identifiers
  • @type - deal identifier type: CUSIP, ISIN, e.t.c.
  • @value - identifier value
.//contentMeta/deals/sdc CUSTOM Linked SDC deals collection
.//contentMeta/deals/sdcdealCUSTOM SDC deal
.//contentMeta/deals/sdcdeal[@dealnumber] CUSTOM Master deal number
.//contentSet/inlineXML/nitf News item details in the NITF standard
.//contentSet/inlineXML/nitf/head/docdata/doc.copyright Copyright information
.//contentSet/inlineXML/nitf/body/body.head/hedline/hl1/Value Story title
.//contentSet/inlineXML/nitf/body/body.head/dateline/story.date Story publish date
.//contentSet/inlineXML/nitf/body/body.content Story content
.//contentSet/inlineXML/nitf/body/body.end/tagline Story byline or author(s)

Publisher Actions

The following publisher actions are transmitted via the API with the recommended actions clients should take when processing content.

Publisher Action Client Action Publish Date
CreateNew Add New New version date
Overwrite Overwrite Old Maintains first published date
Update Add New New version date
AdditionalUpdate Overwrite Old Maintains first update published date
Correct Add New New version date
Withdraw Remove Old And Add New New version date
Refile Remove Old And Add New New version date
IssueAdvisory Add New New version date
Repeat Add New New version date
Chain Add New - applies to alerts New version date
Newsbreak Add New - applies when an alert is converted to a story New version date

Getting Help

For any queries regarding the Story API please contact https://myaccount.lseg.com/en/helpandsupport

For any queries regarding subscriptions please contact your LSEG account manager.


Changelog

See what's new added, changed, fixed, improved or updated in the latest versions.

Version 1.0 (11 June, 2022)

Initial Release