API Specification
Introduction
AIM - API gives you access to information in a format suitable for processing in particular in JSON format.
Services are split into five entities:
- Substances -
/api/substances
- References -
/api/references
- Substance reference relations -
/api/substance-reference-relations
- Clinical trials -
/api/clinical-trials
- Clinical trials substances relations -
/api/clinical-tirals-substances
Method of providing data
- All dates are text strings formatted in compliance with ISO 8601 as
YYYY-MM-DD
- If the syntax request is incorrect (missing or incorrectly formatted parameters) an HTTP 400 Bad Request response will be returned. The body of the response may include an explanation.
- Data
updated_at
(used for queryingchanged-from
) refers only to a particular entity and not its logical relations. Example: If a new substance reference relation is added, but the substance detail has not changed, this is reflected in the substance reference relation endpoint where a new entity withid
and current dates increated_at
andupdated_at
fields will be added, but in substances or references endpoint nothing has changed.
The recommended way of sequential download
- During the first download, it is possible to obtain all data by entering an old enough date
in
the parameter value changed-from, for example:
changed-from=2020-01-01
It is important to write down the date on which the receiving the data was initiated let’s say2020-10-20
- For repeated data downloads, it is sufficient to receive only the records in which something
has changed. It can therefore be requested with the parameter
changed-from=2020-10-20
(example from the previous bullet). Again, it is important to write down the date when the updates were downloaded (eg.2020-10-20
). This date will be used in the next update (refresh) of the data.
Services for entities
List of endpoint URLs:
- /api/substances
- /api/references
- /api/substance-reference-relations
- /api/clinical-trials
- /api/clinical-trials-substances
Format of the request
All endpoints have these parameters in common:
changed-from
- a parameter to return only the entities that have been modified on a given date or later.continue-after-id
- a parameter to return only the entities that have a larger ID than specified in the parameter.limit
- a parameter to return only the number of records specified (up to 1000). The preset number is 100.
Request example:
/api/references?changed-from=2020-01-01&continue-after-id=1&limit=100
Format of the response
The response format is the same for all endpoints.
number_of_remaining_ids
- the number of remaining entities that meet the specified criteria but are not displayed on the page. An integer of virtually unlimited size.entities
- an array of entity details in JSON format.
Response example:
{
"number_of_remaining_ids" : 100,
"entities" : [
{
"id": 3,
"url": "https://www.ncbi.nlm.nih.gov/pubmed/32147628",
"title": "Discovering drugs to treat coronavirus disease 2019 (COVID-19).",
"impact_factor": "Discovering drugs to treat coronavirus disease 2019 (COVID-19).",
"tested_on_species": "in silico",
"publication_date": "2020-22-02",
"created_at": "2020-30-03",
"updated_at": "2020-31-03",
"deleted_at": null
},
{
"id": 4,
"url": "https://www.ncbi.nlm.nih.gov/pubmed/32157862",
"title": "CT Manifestations of Novel Coronavirus Pneumonia: A Case Report",
"impact_factor": "CT Manifestations of Novel Coronavirus Pneumonia: A Case Report",
"tested_on_species": "Patient",
"publication_date": "2020-06-03",
"created_at": "2020-30-03",
"updated_at": "2020-30-03",
"deleted_at": null
},
]
}
Endpoint details
Substances
URL: /api/substances
Substances endpoint returns data in the format specified in Response example as an array of entities in JSON format specified in the entity format section.
Entity format:
id
- Unique identifier in our database (unsigned integer)name
- Name of the Substance (string)description
- Description (HTML code)phase_of_research
- Phase of research (string)how_it_helps
- How it helps (string)drug_status
- Drug status (string)general_information
- General information (HTML code)synonyms
- Synonyms (string)marketed_as
- "Marketed as" (string)dietary_sources
- Dietary sources name (string)dietary_sources_url
- Dietary sources URL (string)prescribing_information
- Prescribing information as an array of JSON objects with description and URL attributes as stringsformula
- Formula (HTML code)created_at
- Date when the entity was added to our database (Date in ISO 8601 format)updated_at
- Date when the entity was last updated in our database (Date in ISO 8601 format)deleted_at
- Date when the entity was deleted in our database (Date in ISO 8601 format)
References
URL: /api/referencesReferences endpoint returns data in the format specified in Response example as an array of entities in JSON format specified in the entity format section.
Entity format:id
- Unique identifier in our database (unsigned integer)url
- URL link of the scientific article (string)title
- Title of the scientific article (string)impact_factor
- Impact factor of the scientific article (string)tested_on_species
- What testing model was used for the study (string)publication_date
- Date of publication of the scientific article (Date in ISO 8601 format)created_at
- Date when the entity was added to our database (Date in ISO 8601 format)updated_at
- Date when the entity was last updated in our database (Date in ISO 8601 format)deleted_at
- Date when the entity was deleted in our database (Date in ISO 8601 format)
Reference substance relation
URL: /api/substance-reference-relationsReference substance relation endpoint returns data in the format specified in Response example as an array of entities in JSON format specified in the entity format section.
Entity format:id
- Unique identifier in our database (unsigned integer)reference_id
- Id of a reference in our DB (unsigned integer)substance_id
- Id of a substance in our DB (unsigned integer)note
- Specific note for this relation (string)supporting
- Is evidence supporting or contradictory (Boolean, true if supporting)created_at
- Date when the entity was added to our database (Date in ISO 8601 format)updated_at
- Date when the entity was last updated in our database (Date in ISO 8601 format)deleted_at
- Date when the entity was deleted in our database (Date in ISO 8601 format)
Clinical trials
URL: /api/clinical-trialsReference substance relation endpoint returns data in the format specified in Response example as an array of entities in JSON format specified in the entity format section.
Entity format:id
- Unique identifier in our database (unsigned integer)title
- Title of clinical trial studyacronym_title
- Id of a substance in our DB (unsigned integer)source_id
- Id of reference in original database (string)source_id_optional
- Optional Id in original database (multiple strings delimited by ",")interventions
- Description of intervention in studystudy_type
- Type of clinical trialstudy_results
- Current results of clinical trialphase
- Phase in which the study currently the clinical trial isurl
- Url to clinical trial pagestatus
- Status of progress in clinical trialstart_date
- Start date of clinical trialcompletion_date
- Completion date of clinical trialcreated_at
- Date when the entity was created in our database (Date in ISO 8601 format)updated_at
- Date when the entity was last updated in our database (Date in ISO 8601 format)deleted_at
- Date when the entity was deleted in our database (Date in ISO 8601 format)
Clinical trial substances
URL: /api/clinical-trials-substancesReference substance relation endpoint returns data in the format specified in Response example as an array of entities in JSON format specified in the entity format section.
This entity doesn't have Unique identifier (ID) and for that reason filtration parameter "continue after ID" was replaced with "offset" filter
offset
- Number of entities to skip and from beginig to get next chunk of data
clinical_trial_id
- Id of a clinical trial in our DB (unsigned integer)substance_id
- Id of a substance in our DB (unsigned integer)created_at
- Date when the entity was added to our database (Date in ISO 8601 format)updated_at
- Date when the entity was last updated in our database (Date in ISO 8601 format)deleted_at
- Date when the entity was deleted in our database (Date in ISO 8601 format)