API documentation

Pour commencer

Pour commencer à utiliser notre API, vous avez besoin d’une clef d’API.

Contactez notre service commercial pour en obtenir une.

Authentification

L’authentification se fait par une simple clef d’API

Dans cette première version d’API, vous pouvez insérer votre clef d’API d’une seule manière:

  • Via le paramètre de query apiKey .

Exemple: https://api.olifid.com/releases?apikey=votreclefAPI&q=*

Nous vous recommandons de ne pas l’utiliser en front pour éviter de l’exposer.

Si vous ne rentrez pas de clef d’API ou si vous en utilisez une mauvaise, vous recevrez ce message d’erreur HTTP:

403 - Forbidden

et ce payload:

{
« error »: « apikeyinvalid »
}

Endpoints

Olifid propose pour le moment un endpoint principal:

  • Releases : https://api.olifid.com/releases – retourne les 100 derniers communiqués quelques soit les critères choisis

Seule la méthode GET est actuellement disponible

Queries

Les API d’Olifid sont basées sur un moteur Elasticsearch, lui-même basé sur Lucene, la librairie de recherche d’Apache. Elles utilisent donc la syntaxe de requête de Lucene.

Connaître la syntaxe et les opérateurs de Lucene vous aidera grandement à créer des requêtes.

Fonctionnement général: comment faire la requête ?

C’est tout simple, les appels aux API d’Olifid se décomposent ainsi:

GET (seule la méthode GET est disponible) https://api.olifid.com/ (URL de base) + endpoint (nom du endpoint) + ?apikey=votreclefdAPI (clef d’API) + &q=query (votre requête)

Liste des champs retournées dans le JSON

Ce sont autant de paramètres sur lesquels faire varier la query

versioncreated: c’est la date de parution du communiqué au format universel

organisation: c’est le nom de la société ou organisation qui publie le communiqué

source: c’est le diffuseur de niveau 1 du communiqué (un Newswire, une agence de presse…)

headline: c’est le titre du communiqué (en HTML parfois)

subheadline: c’est le sous-titre ou le chapeau du communiqué (en HTML parfois)

dateline: c’est une combinaison de rappel de la date heure et ville (en HTML parfois)

body_xhtml: c’est le corps du communiqué (en HTML)

contact: c’est la liste des contacts liés au communiqué (en HTML)

copyrightnotice: il est obligatoire de reprendre ce copyright et de l’afficher lors de l’affichage des communiqués

language: langage du communiqué (code iso 639-1 à deux lettres exemple: « fr » pour Français)

isin: code isin de la société si la société est cotée

css: CSS parfois fourni pour aider à la mise en forme du communiqué

publicidentifier: numéro unique du communiqué

Exemple:

GET https://api.olifid.com/releases?apikey=XXXXXXXX&q=*
vous retournera les 100 derniers communiqués publiés.

count indique le nombre de communiqués renvoyés dans le payload
nbqueries indique le nombre de queries réalisées dans les dernières 24h
maxqueries indique le nombre max de queries possibles en 24h
query rappelle quelle query a été réalisée
hits c’est l’ensemble des communiqués retournés dans le payload

Par souci de lisibilité nous n’avons affiché que 2 communiqués dans le payload suivant:

Copy to Clipboard

Accélérez le temps de réponse avec le header de compression suivant :

Accept-Encoding: gzip, deflate, br

Opérateurs booléens

Comme avec la plupart des langages informatiques, Elasticsearch prend en charge les opérateurs AND, OR et NOT:

    • GET https://api.olifid.com/releases?apikey=XXXXXXXX&q=(Apple)AND(microsoft)
      – Renverra les communiqués contenant dans n’importe quel champ les mots « apple » et « microsoft »
    • GET https://api.olifid.com/releases?apikey=XXXXXXXX&q=(body_xhtml:Apple)NOT(body_xhtml:microsoft)
      – Renverra les communiqués contenant dans n’importe quel champ les mots « apple » mais pas les mots « microsoft »
    • GET https://api.olifid.com/releases?apikey=XXXXXXXX&q=(Apple)NOT(microsoft)
      – Renverra les communiqués contenant dans n’importe quel champ Apple ou microsoft, ou les deux

Champs

Vous recherchez peut-être des communiqués pour lesquels un champ spécifique contient certains termes. Vous spécifiez cela comme suit:

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

Cette requête vous renverra uniquement les communiqués de la société Apple Inc
Soyez prudent avec les valeurs avec des espaces tels que «Apple Inc». Vous devrez le mettre entre guillemets pour garantir que la valeur entière est utilisée.

Range

Vous pouvez rechercher des champs dans une plage spécifique, en utilisant les crochets pour les recherches de plages inclusives et les accolades pour les recherches de plages exclusives:

    • versioncreated: [2019-10-17 TO 2019-10-21]
      – Reverra les communiqués avec une date comprise entre le 17 et le 21 Octobre 2019
    • versioncreated: {2019-10-17 TO 2019-10-21}
      – Reverra les communiqués avec une date comprise entre le 18 et le 20 Octobre 2019
    • organisation: [Apple TO Microsoft]
      – Renverra les communiqués des sociétés, d’Apple à Microsoft.

Comme vous pouvez le constater dans les exemples ci-dessus, vous pouvez également utiliser des plages dans des champs non numériques tels que des chaînes et des dates.

Ces call renvoient des communiqués dans la limites de 100 communiqués. (Nous contacter pour augmenter le nombre de communiqués retournés).

Wildcards

La recherche ne serait pas une recherche sans caractères génériques. Vous pouvez utiliser le caractère * pour les caractères génériques à plusieurs caractères ou le symbole ? pour les caractères génériques à caractère unique:

    • Ma?S – Correspondra à Mars, à la ville du Mans, ou encore au mot anglais « mass » (la messe ou la masse)
    • Ma * s – Correspondra à Mars, maris ou encore Massachusetts

Exemples de requêtes:

GET https://api.olifid.com/releases?apikey=XXXXXXXX&q=*
Retournera les 100 derniers communiqués

GET https://api.olifid.com/releases?apikey=XXXXXXXX&q=r
Retournera les 100 derniers communiqués contenant la lettre r dans n’importe lequel des champs

GET https://api.olifid.com/releases?apikey=XXXXXXXX&q=source:b*
Retournera les 100 derniers communiqués dont la source commence par b

GET https://api.olifid.com/releases?apikey=XXXXXXXX&q=(organisation:Apple)NOT(source:b*)
Retournera les 100 derniers communiqués des sociétés comprenant le mot « Apple » mais n’émanant pas de source commençant par « b »

GET https://api.olifid.com/releases?apikey=XXXXXXXX&q=(organisation:Apple)NOT(organisation:"Apple Inc")
Retournera les 100 derniers communiqués des sociétés comprenant le mot « Apple » mais ne comprenant pas les sociétés s’appelant « Apple Inc »