DISCO API Documentation

All you need to know about DISCO API

In this guide, you will get to know everything about DISCO API; end points, filters, … etc. We also explain how you can retrieve your (alerts and saved searches) results within your API.

We should be answering all your questions here. In case we miss anything, please contact us; clicking on the contact us button at the bottom of this page or using the live chat.

Getting Started

This overview will give you some idea of what data is available, how to find what you need and what you will see when you make an API request.

First of all and to get an API key, you have to have an account on DISCO. If you do not have one already, sign up now to get an instant access.

Steps to get your API key:

  1. Log in to your account.
  2. Click on the cog icon next to your logo.
  3. Click on the first option (Welcome, User Name) and you will be redirected to your dashboard.
  4. Click on Content API tab.
  5. Copy your API key.

Endpoints

We provide several endpoints to retrieve different items:

A. All/ Filtered Content

B. Single Item (One Piece of Content)

C. Alerts

D. Saved Searches

Notes:

  • For end point (A), results can be filtered using the following parameters:
    • API key
    • id
    • content_format_id_i
    • title_id_i
    • date_tdt
    • headline_s
    • publisher_s
    • topic_category_ss
    • detailed_content_format_id_i
    • language_code_s
    • meta_body_s
    • title_name_s
    • country_category_ss
    • industryterm_category_ss
  • End point (A) response contains all the results but the content is infull (truncated body). End point (B) retrieves single item in full. 
  • Results of end point (A) are returned as paginated list of containing, by default, 20 entries per page.

A(1). All Content

The (all content) endpoint (/getUserLatestArticles) returns all pieces of content in your API (your account). For example, let’s suppose that the API key in the link below is yours.

https://marketplace.disco.info/api/getUserLatestArticles?api_key=pciyVhdEo4uTxFte08Td8fKuuLksjj2ylaV6iYBwTVfgqylfx56

Here the (API key) parameter retrieves all the results in your API (all the results available in your DISCO account).

A(2). Filtered Content

Now, you might want to filter down the results to something more meaningful, specifically looking for English language content that includes the word “economic” and finally you want to sort the results retrieved descendingly by date,. The example below shows how you can do that.
We will go through all the parameters you can use to filter down your results in the (search) section of this documentation. Here, we will explain only how you can use the query operators.

https://marketplace.disco.info/api/getUserLatestArticles?search_free_text=economic&languages=en&sort=DESC&api_key=pciyVhdEo4uTxFte08Td8fKuuLksjj2ylaV6iYBwTVfgqylfx56

Query operators

The search_free_text parameter supports AND, OR and NOT operators. Below we explain how you can use the mentioned as conjunctions to combine or exclude keywords in your search, resulting in more focused and productive API results.

Exact Phrase
To search for an exact phrase, write the exact phrase as is, without adding any operators or quotation marks.

Ex: Information Technology would retrieve content containing this exact phrase within the headline or body of the article.
https://marketplace.disco.info/api/getUserLatestArticles?search_free_text=information technology&api_key=pciyVhdEo4uTxFte08Td8fKuuLksjj2ylaV6iYBwTVfgqylfx56


And
The AND operator matches articles where both terms exist anywhere in the text of a single article

Ex: Omaba and Trump returns only content that contains both words; “obama” and “trump”.
https://marketplace.disco.info/api/getUserLatestArticles?search_free_text=obama and trump&api_key=pciyVhdEo4uTxFte08Td8fKuuLksjj2ylaV6iYBwTVfgqylfx56

Or
The OR operator will return results which include either, or both, of the terms.

Ex: Obama or Trump returns content that contains the word “obama”, the word “trump” or both words.
https://marketplace.disco.info/api/getUserLatestArticles?search_free_text=obama or trump&api_key=pciyVhdEo4uTxFte08Td8fKuuLksjj2ylaV6iYBwTVfgqylfx56

Not
The NOT operator excludes articles that contain the term(s) after NOT.

Ex: Obama not Trump returns content that contains the word “obama” but not the word “trump”.
https://marketplace.disco.info/api/getUserLatestArticles?search_free_text=obama not trump&api_key=pciyVhdEo4uTxFte08Td8fKuuLksjj2ylaV6iYBwTVfgqylfx56

Not Statement
A not statement helps you eliminate content that matches the query after Not.

Ex: (Obama or Trump) not (Bush or Clinton) returns content with “Obama” or “Trump” in the headline or body, but excludes content which include “Bush” or “Clinton”.
https://marketplace.disco.info/api/getUserLatestArticles?search_free_text=(Obama or Trump) not (Bush or Clinton) &api_key=pciyVhdEo4uTxFte08Td8fKuuLksjj2ylaV6iYBwTVfgqylfx56

Parenthesis with operators
You can use parentheses to group clauses to form sub-queries.
Ex: (Obama or Trump) and United States returns content which include the term “United States”, and “Trump”, “Obama”, or both.
https://marketplace.disco.info/api/getUserLatestArticles?search_free_text=(Obama or Trump) and United States &api_key=pciyVhdEo4uTxFte08Td8fKuuLksjj2ylaV6iYBwTVfgqylfx56

Preserved Words
If you wish to treat a search operator (and, or, not) as a search term, you must enclose the entire phrase in quotation marks.
Ex: “Obama and Trump” returns content which include the phrase “Obama and Trump” exactly as it is written, rather than results containing the term “Obama”, as well as the term “Trump”, anywhere in the article.
https://marketplace.disco.info/api/getUserLatestArticles?search_free_text=”Obama and Trump” &api_key=pciyVhdEo4uTxFte08Td8fKuuLksjj2ylaV6iYBwTVfgqylfx56

Proximity searches
A proximity search looks for terms that are within a specific distance from one another. To perform a proximity search, add the tilde character ~ and a numeric value to the end of a search phrase.
Ex: obama trump~10 returns results which include the terms “Obama” and “Trump” within 10 words of each other.
https://marketplace.disco.info/api/getUserLatestArticles?search_free_text=obamatrump~10 &api_key=pciyVhdEo4uTxFte08Td8fKuuLksjj2ylaV6iYBwTVfgqylfx56

Note: The distance referred to here is the number of term movements needed to match the specified phrase. In the example above, if “Trump” and “Obama” were 10 spaces apart in a field, but “Trump” appeared before “Obama”, more than 10 term movements would be required to move the terms together and position “Trump” to the right of “Obama” with a space in between.

 

B. Single Item:
The (single item) endpoint (/viewarticle) returns all the data we have for a given single item (piece of content) id. The parameters you should use are just your API key and the item (piece of conetnt) id as in the example below.
https://marketplace.disco.info/api/viewarticle?id=152580568&api_key=pciyVhdEo4uTxFte08Td8fKuuLksjj2ylaV6iYBwTVfgqylfx56

C. Alerts

When you create an alert on DISCO, we will send you emails when we find new results that match your search query and/or filters.
These results can be retrieved in your API as well and we will explain this further in the Alerts section of this documentation.

D. Saved Searches

Instead of writing the same query and/or entering the same filters multiple times; wasting your time and effort. You can save the searches you are using often and retrieve the results of each in a matter of a few clicks.
You can also see the results of your saved searches within your API. More details on this in the Saved Searches section of this documentation.

Example response

Field Description Type
content_format Content formats String
detailed_content_format Detailed content formats String
languages Languages of the content services you have String
titles Content services you are subscribed to String
countries Countries of the content services you have String
industries Industries of the content services you have String
topics Topics of the content services you have String
id Item ID Integer
title_id_i Content service ID Integer
language_code_s Content service language String
image_ss The ID, URL and captions of the image/s String
video_ss The ID, URL and captions of the video/s String
audio_ss The ID and the URL of the audio/s String
date_tdt Item (piece of content) date Date
meta_body_s Item (piece of content) summary String
headline_s Item (piece of content) headline String
publisher_s Item (piece of content) publisher String
title_content_format_s Item (piece of content) content format String
title_detailed_content_format_s Item (piece of content) detailed content format String
title_name_s Content service name String
country_category_ss Item (piece of content) countries String
topic_category_ss Item (piece of content) topics String
industryterm_category_ss Item (piece of content) industries String
page_limit The number of items returned in this call Integer
current_page The number of the page you are browsing Integer
next_link The API link you can use to browse the next page String
NumFound The number of results available for your search overall Integer
previous_link The API link you can use to browse the previous page String

Parameters

Authentication parameters

Name Description Type Accepted values
api-key Your API key which is used for the query String API Key

Query term

Name Description Type Accepted values
getUserLatestArticles Returns all pieces of content in your API String API Key

Example response

Field Description Type
content_format Content formats String
detailed_content_format Detailed content formats String
languages Languages of the content services you have String
titles Content services you are subscribed to String
countries Countries of the content services you have String
industries Industries of the content services you have String
topics Topics of the content services you have String
id Item ID Integer
title_id_i Content service ID Integer
language_code_s Content service language String
image_ss The ID, URL and captions of the image/s String
video_ss The ID, URL and captions of the video/s String
audio_ss The ID and the URL of the audio/s String
date_tdt Item (piece of content) date Date
meta_body_s Item (piece of content) summary String
headline_s Item (piece of content) headline String
publisher_s Item (piece of content) publisher String
title_content_format_s Item (piece of content) content format String
title_detailed_content_format_s Item (piece of content) detailed content format String
title_name_s Content service name String
country_category_ss Item (piece of content) countries String
topic_category_ss Item (piece of content) topics String
industryterm_category_ss Item (piece of content) industries String
page_limit The number of items returned in this call Integer
current_page The number of the page you are browsing Integer
next_link The API link you can use to browse the next page String
NumFound The number of results available for your search overall Integer
previous_link The API link you can use to browse the previous page String

Filters

Name Description Type Accepted Values
search_free_text Returns items which match your query String e.g: search_free_text=obama and trump
content_format Returns items with the content formats you enetered Integer e.g: content_format= 1; 4; 5
sort Sorting your results descendingly or accendingly by date String sort=DESC, ACCE
date Retreiving results for a specific date range date eg: &date_from=December+15%2C+2020&date_to=January+12%2C+2021
languages Returns items with the languages you enetered String e.g: language= EN; FR; AR
titles Returns content for the content services you entered Integer e.g: titles=4012; 4013
detailed_content_format Returns content for the detailed content formats you entered Integer detailed_content_format=1; 9
country_location Returns items which are related to the countries you entered String e.g: country_location=UK; UAE
industries Returns items which are related to the industries you entered Integer e.g: industries[]=104&industries[]=105
categories_list Returns items which are related to the topics you entered Integer e.g: categories_list[]=25&categories_list[]=29

Note: All the values accepted for each of the filters can be found in the trees section of the API.

Parameters

Authentication parameters

Name Description Type Accepted values
api-key Your API key which is used for the query String API Key

Query term

Name Description Type Accepted values
getUserLatestArticles Returns all pieces of content in your API String API Key

How you can create an Alert on DISCO:

1. Log in to your DISCO account.
2. Perform your search which you want to create an alert for.
3. Click on the Alerts button.

4. The (Add Alerts) pop up opens. Click on (Add New Alert).

5. Fill out the fields and click on (save).

How you can retrieve your alert results in your API:

1. Click on the (Alerts) button.
2. Next to any of your pre-created alerts, you can click on the (API) button. Immediately, the API link -that matches the chosen alert’s search- will autogenerate and open in a new tab in your browser.

How you can create a saved search on DISCO:

1. Log in to your DISCO account.
2. Perform your search which you want to save.
3. Click on the (save this search) button.

4. The (Saved Searches) pop up will open. Enter the saved search name and click on save.

How you can retrieve your saved searches results in your API:

1. Click on the (saved searches) button.

2. Next to any of your saved searches, you can click on the (API) button. Immediately, the API link -that matches the saved search- will autogenerate and open in a new tab in your browser.

Do you have any questions?