Atoka API User Reference

News Search

Our unique semantic tools let you search for companies mentions in daily news from thousands of sources: each day, we process more than 70.000 articles!

You can also restrict to articles where specific kinds of events are detected through our semantic analysis technologies (more at dandelion.eu).

https://api.atoka.io/v2/news

All requests must be properly authenticated.

Contents

Restrict to articles where specific kinds of events are detected.

Parameters
  • fields string,
    default is "items"

    Choose the content to return in the response.

    Choose only one among:

    • items Return the result items (news) for the query.
    • facets Return various counts of entities, events, etc. with the results.
    • none Return the metadata for the request.
  • fullText string

    Query string for standard text search.

  • sector array

    Select the press or official source topics of the news.

    To specify multiple values, repeat the parameter: will match on any value (logic OR).

    Possible values are:

    • cronaca_locale Cronaca Locale
    • cultura Cultura
    • prima_pagina Prima Pagina
    • economia_finanza Economia / Finanza
    • sport Sport
    • interni_politica Interni / Politica
    • esteri Esteri
    • non_specificata Non specificata
    • editoriali_opinioni Editoriali / Opinioni
    • comunicato_stampa Comunicato Stampa
  • event array

    Matches when one of specified kind of event was detected.

    To specify multiple values, repeat the parameter: will match on any value (logic OR).

    Possible values are:

    • licenziamento licenziamenti, cassa integrazioni, pre-pensionamenti, demansionamenti, esuberi, restrutturazione, chiusure
    • chiusura chiusura, bancarotta, crack, fallimento, liquidazione, insolvenza (semplici o fraudolenti)
    • protesta agitazioni del personale, proteste, presidi, scioperi
    • truffa danni economici (ricevuti), furto, truffa, estorsione, frode, usura
    • danni danni materiali, incendio, crollo, disastro, incidenti (anche alle persone)
    • crisi perdite finanziarie, a rischio, underperforming, debiti, risarcimenti, delisting, richiamo dei prodotti, tagli, riduzioni, deinvestimenti, sottofinanziamenti, decurtazioni, razionalizzazioni, sottopagati
    • tribunale guai giudiziari, contenziosi, arresti, condanne, denunce, sanzioni, vertenze, indagati, sequestri, processi, corruzione, evasione fiscale, risarcimenti, frode, falso in bilancio, incidenti sul lavoro, regolamentazione, riciclaggio, dimissioni, bancarotta/crack/insolvenza, violazioni brevetti, class action
    • fusioni_acquisizioni Fusioni e acquisizioni
    • nuovi_prodotti Lancio di nuovi prodotti e servizi
    • cambio_ruolo Cambio di ruolo
  • eventMinConfidence number,
    default is 0.5

    Do not consider event for which classifications confidence is lower than this parameter (this is valida only for the negative events).

    Use a number between 0.5 and 1.

  • dateStart string

    Retrieve news created starting from this date (the format is YYYY-MM-DD), default value is 30 days ago.

  • dateEnd string

    Retrieve news created until this date (the format is YYYY-MM-DD), default value is today.

  • highlightTagStart string,
    default is "<em>"

    Text preceding extract of company mention within article.

  • highlightTagEnd string,
    default is "</em>"

    Text following extract of company mention within article.

  • highlightHtmlEscape boolean,
    default is true

    To apply or not to apply the HTML escaping to the highlighted text before adding highlighting tags.

curl -G "https://api.atoka.io/v2/news" -d "fields=facets" -d "fullText=la Fiat vende la Piaggio" -d "sector=cronaca_locale" -d "sector=economia_finanza" -d "event=danni" -d "event=truffa" -d "eventMinConfidence=0.6" -d "dateStart=2016-01-15" -d "dateEnd=2016-01-27" -d "highlightTagStart=<span class="snippet-mention">" -d "highlightTagEnd=</span>"

Response modifications

When fields is items, the response will be:

[ // Result items (news).
{ // A news article.
"categories": [ // Generic topics of an article.
"string",
...
],
"newsId": "string", // Unique identifier of the article in the index.
"date": "string", // Time of the article creation.
"url": "string", // Url of the article source, if present.
"headline": "string", // Title of the article.
"body": "string", // Content of the article.
"abstract": "string", // A short abstract of the content of the article
"highlight": { // Contains highlighted snippets extracted from several fields of the article
"headline": "string", // The highlighted headline
"abstract": "string" // The highlighted abstract
},
"lang": "string", // Main language of the content of the article
"esLink": "string", // Url of the Elastisearch json of the article.
"sourceName": "string", // Name of the newspaper of this article.
"sourceType": "string", // Type of content source.
"officialSource": "string", // In the official press news this is the unique ID of the company publishing this article.
"free": boolean, // If true the article is freely distributed, if false it requires a premium account in the press source.
"otherSources": [ // List of duplicates from other newspapers.
{
"newsId": "string", // Unique identifier of the article in the index.
"sourceName": "string", // Name of the newspaper of this article.
"url": "string", // Url of the article source, if present.
"esLink": "string" // Url of the Elastisearch json of the article.
},
...
],
"otherSourceTotal": int, // Total number of dublicates from other newspapers.
"events": [ // Filter news by one or more (the parameter has to be replicated) specific events: - *licenziamento* - licenziamenti, cassa integrazioni, pre-pensionamenti, demansionamenti, esuberi, restrutturazione, chiusure - *chiusura* - chiusura, bancarotta, crack, fallimento, liquidazione, insolvenza (semplici o fraudolenti) - *protesta* - agitazioni del personale, proteste, presidi, scioperi - *truffa* - danni economici (ricevuti), furto, truffa, estorsione, frode, usura - *danni* - danni materiali, incendio, crollo, disastro, incidenti (anche alle persone) - *crisi* - perdite finanziarie, a rischio, underperforming, debiti, risarcimenti, delisting, richiamo dei prodotti, tagli, riduzioni, deinvestimenti, sottofinanziamenti, decurtazioni, razionalizzazioni, sottopagati - *tribunale* - guai giudiziari, contenziosi, arresti, condanne, denunce, sanzioni, vertenze, indagati, sequestri, processi, corruzione, evasione fiscale, risarcimenti, frode, falso in bilancio, incidenti sul lavoro, regolamentazione, riciclaggio, dimissioni, bancarotta/crack/insolvenza, violazioni brevetti, class action - *fusioni_acquisizioni* - Fusioni e acquisizioni - *nuovi_prodotti* - Lancio di nuovi prodotti e servizi - *cambio_ruolo* - Cambio di ruolo
"string",
...
],
"sectors": [ // Press or official source topics of the news: - *cronaca_locale* - Cronaca Locale - *cultura* - Cultura - *prima_pagina* - Prima Pagina - *economia_finanza* - Economia / Finanza - *sport* - Sport - *interni_politica* - Interni / Politica - *esteri* - Esteri - *non_specificata* - Non specificata - *editoriali_opinioni* - Editoriali / Opinioni - *comunicato_stampa* - Comunicato Stampa
"string",
...
],
"companies": [ // List of companies that occur in the article, with each mention.
{
"companyId": undefined, // The unique ID of the company. Get company info via [Company Details](#company) or [Companies Search](#companies) API calls.
"mentions": [
{
"field": "string", // In which content field this mention occurs.
"confidence": float, // A confidence score of the annotation, given by the annotator.
"start": int, // Start position of the mention in the field's text.
"end": int // End position of the mention in the field's text.
},
...
]
},
...
],
"people": [ // List of people that occur in the article, with each mention.
{
"personId": undefined, // Unique ID of the mentioned person.
"mentions": [
{
"field": "string", // In which content field this mention occur.
"confidence": float, // A confidence score of the annotation, given by the annotator.
"start": int, // Start position of the mention in the field's text.
"end": int // End position of the mention in the field's text.
},
...
]
},
...
],
"entities": { // Lists of entities grouped by language.
"it": [ // List of Italian Wikipedia and company entities that occur in the article.
{
"url": "string", // Wikipedia url of the entity.
"confidence": float, // A confidence score of the annotation, given by the annotator.
"types": [ // List of DBpedia types for this entity.
"string", // A DBpedia type url.
...
],
"label": "string", // Human readable name for this entity.
"image": { // An image of this entity.
"full": "string", // Url of the image at full size.
"thumbnail": "string" // Url of the image at reduced size.
}
},
...
]
}
},
...
]
curl -G "https://api.atoka.io/v2/news" -d "fields=items"

When fields is facets, the response will be:

curl -G "https://api.atoka.io/v2/news" -d "fields=facets"

Ordering & Pagination

To download long lists of results you can paginate returned items using these parameters.

Parameters
  • offset integer,
    default is 0

    Start visualizing results in the page from the rank defined by this value.

    Use a number bigger than 0.

  • limit integer,
    default is 10

    This is the number of individual news that are returned in the results page.

    Use a number between 1 and 100.

curl -G "https://api.atoka.io/v2/news" -d "offset=10" -d "limit=5"

Companies

Get only news related to specific companies.

Parameters
  • companies array

    Return news about specific companies. Using the unique company ID returned via Companies Search or Company Details API calls.

    Accepts multiple values, separated with , (comma) char.

  • officialCompanies array

    Return official press releases of specific companies. Using the unique company ID returned via Companies Search or Company Details API calls.

    Accepts multiple values, separated with , (comma) char.

  • people array

    A set of people to filter

    Accepts multiple values, separated with , (comma) char.

  • companyMinConfidence number,
    default is 0.8

    Do not consider annotations for which company identification confidence is lower than this parameter.

    Use a number between 0.6 and 1.

curl -G "https://api.atoka.io/v2/news" -d "companies=7829a472b02d,c72c5350e4a5" -d "officialCompanies=7829a472b02d,c72c5350e4a5" -d "people=7829a472b02d,c72c5350e4a5" -d "companyMinConfidence=0.75"

Sources

Filter for news sources.

Parameters
  • sourceType string,
    default is "*"

    Filter news by the type of content source. DEPRECATED in favour of sectors.

    Choose only one among:

    • official only official press releases
    • press only news from the press
    • * matches for any value
  • otherSourcesLimit integer,
    default is 0

    How many duplicates for each article we want returned in the results.

    Use a number between 0 and 100.

  • lang string,
    default is "it"

    Filter news by the language code.

    Choose only one among:

    • it
    • en
curl -G "https://api.atoka.io/v2/news" -d "sourceType=press" -d "otherSourcesLimit=3" -d "lang=it"