API doc

Start

To start using our API, you need an API key.

Contact us to get one.

Authentication

Authentication is done by a simple API key

In this first API version, you can insert your API key in one way only:

  • Via the query parameter apiKey

.

Example: https://api.olifid.com/releases?apikey=yourAPIkey&q=**

We recommend that you do not use it in front to avoid exposing it.

If you do not enter an API key or if you use a wrong one, you will receive this HTTP error message:

403 - Forbidden

and this payload:

{
“error”: “apikeyinvalid”
}

Endpoints

Olifid currently offers one main endpoint:

  • releases : https://api.olifid.com/releases – returns the last 100 press releases regardless of the criteria chosen

Only the GET method is currently available

Queries

Olifid’s APIs are based on an Elasticsearch engine, itself based on Lucene, Apache’s search library. They therefore use Lucene’s query syntax.

Knowing Lucene’s syntax and operators will help you create queries.

General operations: how to make requests ?

It’s very simple, the calls to Olifid APIs are done as follows:

GET (only GET is available) https://api.olifid.com/ (base URL) + endpoint (endpoint name) + ?apikey=yourAPIkey (API key) + &q=query (your query)

List of fields returned in JSON:

Those are also parameters on which to vary the query

versioncreated: this is the date of publication of the press release in universal format (UTC)

organisation: name of the company or organization that issues the press release

source: Level 1 broadcaster of the press release (a Newswire, a news agency…)

headline: title of the press release (sometimes in HTML)

subheadline: subtitle or cap of the press release (sometimes in HTML)

dateline: combination of time and city date reminder (sometimes in HTML)

body_xhtml: body of the press release (in HTML)

contact: list of contacts linked to the press release (in HTML)

copyrightnotice: it is mandatory to take over this copyright and display it when displaying press releases

language: language of the press release (two-letter iso code 639-1 example: “fr” for French)

isin: ISIN code of the company if the company is listed

css: CSS that is sometimes provided to help format the release

publicidentifier: unique press release number

Example:

GET https://api.olifid.com/releases?apikey=XXXXXXXX&q=*
will return you the last 100 press releases published.

count indicates the number of press releases returned to the payload
nbqueries indicates the number of queries carried out in the last 24 hours
maxqueries indicates the maximum number of possible queries in 24 hours
query reminds you which query has been performed
hits is the set of press releases returned in the payload

For the sake of readability we have only posted 2 press releases in the following payload:

Copy to Clipboard

Accelerate response time with  the following compression header :

Accept-Encoding: gzip, deflate, br

Boolean operators

As with most computer languages, Elasticsearch supports AND, OR and NOT operators:

    • GET https://api.olifid.com/releases?apikey=XXXXXXXX&q=(Apple)AND(microsoft)
      – Returns press releases containing in any field the words “apple” and “microsoft”
    • GET https://api.olifid.com/releases?apikey=XXXXXXXX&q=(body_xhtml:Apple)NOT(body_xhtml:microsoft)
      – Returns press releases containing in any field the words “apple” but not the words “microsoft”.
    • GET https://api.olifid.com/releases?apikey=XXXXXXXX&q=(Apple)NOT(microsoft)
      – Returns press releases containing in any field Apple or Microsoft, or both

Fields

You may be looking for press releases for which a specific field contains certain terms. You should specify this as follows:

    • GET https://api.olifid.com/releases?apikey=XXXXXXXX&q=organisation:"Apple Inc"

This request will only send you the press releases from Apple Inc.
Be careful with values with spaces such as “Apple Inc”. You will need to put it in quotation marks to ensure that the entire value is used.

Range

You can search for fields in a specific range, using square brackets for inclusive beach searches and curly brackets for exclusive beach searches:

    • versioncreated: [2019-10-17 TO 2019-10-21]
      – Returns the press releases with a date between 17th and 21st of October 2019
    • versioncreated: {2019-10-17 TO 2019-10-21}
      – Returns the press releases with a date between 18th and 20th of October 2019
    • organisation: [Apple TO Microsoft]
      – Returns company press releases, from Apple to Microsoft

As you can see from the examples above, you can also use ranges in non-numeric fields such as strings and dates.

These calls return press releases up to 100 press releases. (Contact us to increase the number of press releases returned).

Wildcards

The search would not be a search without wildcards. You can use the character * for multi-character wildcards or the symbol ? for single-character wildcards:

    • Ma?S – Will correspond to Mars, the city of Le Mans (in France), or the English word “mass”
    • Ma * s – Will correspond to Mars, machs or Massachusetts

Query Examples:

GET https://api.olifid.com/releases?apikey=XXXXXXXX&q=*
Returns the last 100 press releases

GET https://api.olifid.com/releases?apikey=XXXXXXXX&q=r
Returns the last 100 press releases containing the letter r in any of the fields

GET https://api.olifid.com/releases?apikey=XXXXXXXX&q=source:b*
Returns the last 100 press releases whose source begins with b

GET https://api.olifid.com/releases?apikey=XXXXXXXX&q=(organisation:Apple)NOT(source:b*)
Returns the last 100 company press releases that include the word “Apple” but do not come from a source beginning with “b”.

GET https://api.olifid.com/releases?apikey=XXXXXXXX&q=(organisation:Apple)NOT(organisation:"Apple Inc")
Returns the last 100 press releases from companies that include the word “Apple” but do not include companies called “Apple Inc”.