News API
Retrieve headlines, news articles, announcements, reports and more.
There are two generations of this API. v1 is the full-featured news service; v2 is a newer REST service that currently covers categories, vendors and PDF retrieval. They are separate services with different base URLs, different scopes and different error formats.
At a glance
| v1 | v2 | |
|---|---|---|
| Scope | news-api | news-rest-api |
| Test | https://test-news-api.openmarkets.com.au/ | https://test-news-rest-api.openmarkets.com.au/ |
| Production | https://news-api.openmarkets.com.au/ | https://news-rest-api.openmarkets.com.au/ |
| Error format | Openmarkets error envelope | Standard HTTP status codes |
The v1 API is marked as in development and is not production ready. Confirm which version your integration should target with API support before building against it.
What's in it
| Area | Purpose |
|---|---|
| News | Headlines, text stories, categories and vendors. |
| Sessions | Session management. |
Getting started
Request a token with the news-api scope, then list the available categories:
curl 'https://test-news-api.openmarkets.com.au/categories/v1' \
-H 'Authorization: Bearer {access_token}'
/headlines/v1 returns headlines, and /textstories/v1 returns the article bodies. /vendors/v1 lists the vendor codes used throughout the API.
In v2, /v2/{newsVendorCode}/{headlineId}/pdf retrieves a headline as a PDF. Note that v2 needs its own token, requested with the news-rest-api scope.
Tokens come from the identity service, which is shared by every Openmarkets API:
| Environment | Token endpoint |
|---|---|
| Test | https://stage-identity.openmarkets.com.au/connect/token |
| Production | https://identity.openmarkets.com.au/connect/token |
See Authentication for the full flow.
Conventions
All API access is sent and received as JSON, and must be requested over HTTPS. Every endpoint requires a bearer token.
Blank and null fields are omitted from requests. JSON request and response bodies use camelCase, except authorisation and authentication requests, which use snake_case to follow the OAuth2 and OpenID Connect specifications.
Parameters
| Method | Where parameters go |
|---|---|
GET | Required parameters form part of the URL path. Optional parameters are query string parameters. |
GET (large parameter sets) | Endpoints that retrieve resources but take many optional parameters accept a POST instead, to avoid URL length limits. |
POST, PUT, DELETE | Parameters that are not part of the URL are JSON encoded in the request body. |
Dates and times
Date-time values are RFC 3339 date-time, and are usually provided in UTC. This example represents 19 December 2016 at 4:30pm Sydney daylight saving time:
{
"dateTimeFieldName": "2016-12-19T16:30:00+11:00"
}
Where a time component is not relevant, the value is an RFC 3339 full-date. Plain dates should be used literally, without any timezone conversion.
Rate limits and availability
Requests are rate limited according to the package or plan chosen when your application was registered. Throttled requests return HTTP 429 with one of ApiCallsFrequencyExceeded, ActiveApiCallsExceeded or MaxUpdatesQueuedExceeded. See Errors.
Cache your access token for its full expires_in lifetime. Requesting a token per API call is the most common cause of unexpected throttling. Implement a circuit breaker with increasing delay between retries rather than retrying immediately.
The v1 API is briefly unavailable on a regular maintenance schedule. See Known issues.
