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
|
Login failed |
401 code and XML below
|
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
|
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
|
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
XML request in body
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
|
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
|
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
|
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
XML request in body
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
|
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
|
.//itemMeta/role[@qcode] |
Story types
|
.//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
|
.//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] |
|
.//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
|
.//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