SubAPI is a set of terminological services aimed to be used to retrieve information of clinical importance about chemical substances used in medicine. These services are programmable by means of a RESTful API.

The problem

Medical drugs contains one or more active substances that are relevant in clinical treatments. There are many sources of clinical information about medical products and substances. Some of these comes from the industry , from the regulatory authorities, from scientific investigation or from health care organizations.These sources refer to the different substances by terms that in some cases differ slightly from each other or are totally different. This is caused in part by language issues related to the origin of the texts and in other cases is because the authors choose terms from different terminologies in use in their own organizations.

For human readers this is not a big deal, in most of the cases we know about these terms and we are able to translate, most on the fly, between them. But in the case of integrating knowledge about substances in automatic decision support for health care systems, the situation is completely different.

SubAPI is a set of terminological services specialized in translating, and matching substance terms from diverse terminologies. SubAPI has services o retrieve clinical information about these substances and their relation with medical products.


SubAPI provides services that collect information in a Knowledge Base about substances. This Knowledge Base is the "back-end" of the system, we will not now delve into details about how the implementation of this "back-end" has been done but we're just going to describe a conceptual interface to access information from it.

Knowledge Base means in this context, a terminological system aimed to retrieve knowledge items (concepts) from a classification in a particular branch of knowledge, in our case the branch of substances for medical use.

Key notions in the description of a Knowledge Base are: TERM, TERMINOLOGY, KNOWLEDGE_BASE, CONCEPT (in our particular case: SUBSTANCE). Se SubAPI/Concepts



The URLs in the API are relative to given prefix the so called {BASE_URL}, eg: {BASE_URL} = Each installation of SubAPI has its own {BASE_URL}.


It is optional for a particular installation of SubAPI to require that an application key ({APP_KEY}) is included in the URL of each service to be called. Application keys are retrieved by registration in the host of the installation.

{APPL_KEY} is placed as a URL segment directly after the {BASE_URL}, when this is required.


From now on we define {BEP} (Base Entry Point) as: {BEP} = {BASE_URL}/{APP_KEY} if {APP_KEY} is required or else {BEP} = {BASE_URL}.


The last element of the URL in a service can have an optional "file extension" to indicate the required format of the response.

This optional "file extension" is represented by the symbol {.fmt}. Valid formats are: ".html", ".py" and ".json". Not all the formats are available in each service. This is specified in each particular service. Default format is ".json".

Entry Points (EPs)

Each service is accessed by means of a HTTP-URL, the so called Entry Point (EP) of the REST service.

Entry Points in SubAPI contains both static segments as {BEP}, "tlgy", "sid", etc which take constant values and dynamic ones as {prefix}, {term}, {terminology}, etc which take variable values.

SubAPI summary

info{BEP}GETHTML document with information about the current installation and access to the documentation of SubAPI
terminologies{BEP}/tlgy{.fmt}GETA list of valid terminologies in the current repository.
substances_in_terminology{BEP}/tlgy/{terminology}{.fmt}/?psize={n}&pnum={p}GETPage number {p} with names of substances in the terminology {terminology} presented on pages with {n} elements each. Default: {n} = count, {p} = 1. (count is the total count of substances returned)

GETSubstance card for the substance identified by {name}[{terminology}].
If only {name} is given, several substance cards from different terminologies may be returned.
If {name} is given in the form {name[terminology]} is considered equivalent to give name and terminology separatly. E.g. /tlgy/INN/sid/arthemeter is equivalent to /sid/arthemeter[INN]

GETList of synonym terms of {name}[{terminology}] or {name}.
If {name} is given in the form {name[terminology]} is considered equivalent to give name and terminology separatly. E.g. /tlgy/INN/sid/arthemeter/synonyms is equivalent to /sid/arthemeter[INN]/synonyms



GETList of products (NPLids) on which the substance {name}[{terminology}] is an active substance.
If {name} is given in the form {name[terminology]} is considered equivalent to give name and terminology separatly. E.g. /tlgy/INN/sid/arthemeter/products is equivalent to /sid/arthemeter[INN]/products
interagents{BEP}/tlgy/{terminology}/sid/{name}/interagents{.fmt}GETList of substances that have known interactions with the substance {name}[{terminology}]
substance_name_prefix{BEP}/prefix/{prefix}{.fmt}GETRetrieve all the substance terms that starts with the prefix {prefix}.
substance_name{BEP}/name/{name}{.fmt}GETRetrieve all the substance terms with name exactly equal to {name}.
substance_name_synonyms{BEP}/name/{name}/synonyms{.fmt}GETRetrieve all the synonyms tems to any substance with name {name}.
substance_name_match{BEP}/match{.fmt}?pattern={pattern}&page={page}&pcount={page_count}GETRetrieve all the substance terms whose names matches the pattern {pattern}. Accepted patterns are those valid in Unix style file matching, with wildcards ? and *, character sets [abc] for character included and [~abc] for characters excluded.
search{BEP}/search{.fmt}?query={query_text}GETList of substances which satisfy the query on the whole text of the substance card
OS-Descripion Document{BEP}/osGET