Overview
This is the first version of the API of Epistemonikos. It allows other sites to retrieve basic information from our database. This project is part of a wider initiative to create a platform of APIs sharing a common data structure, in order to efficiently exchange information, avoid error, decrease workload, and at some moment being able to keep a worldwide distributed workforce supporting living systematic reviews and living guidelines.
The conceptual development of the above mentioned platform is partially based in the existing CochraneTech and GRADEtech initiatives.
First steps
The beta version of our API is restricted to the clients registered in our system. Each registered client counts with a private access token
, which must be set in the Authentication header of each request:
curl "{{ api_url }}/v1/documents/search?q=cancer" -H 'Authorization: Token token="afbadb4ff8485c0adcba486b4ca90cc4"'
If you want to register your application and try our API, please contact us [dev at epistemonikos.org].
Already have an access token? You can try our API in the test page.
API Resources
Our current version provides the resources specified in the following table. As previously stated, all requests must include the Authentication header with a proper access token
, otherwise you'll get an 401: Unauthorized
HTTP status code. You'll find further details by clicking on the icon at the beggining of each row:
Document information GET: {{ api_url }}/v1/documents/{id}[?show={'threads','relations_info','classification_status'}]
Parameters
- id
- You can use a Pubmed ID, Epistemonikos ID or DOI. The DOI must be url-encoded.
- show
- [Optional] A comma separated list stating which aditional document data you want to retrieve. The available options are threads, relations_info and classification_status. They indicate that you want the studies threads including the current document, information about the related references, and the status of the classification of the document.
Response
If the Epistemonikos database contains a document with the provided ID, you'll receive a JSON containing the details of such document and a 200: Ok
status code. Otherwise, you'll get a 404: Not Found
status code. These are the keys that you'll find in the request response:
- id
- The Epistemonikos ID of the document.
- citation
- The document citation, following the Vancouver Style.
- external_links
- URLs to the publisher of the document, and the document in the websites pubmed and epistemonikos.
- identifiers
- The known identifiers of the document (doi, pubmed and epistemonikos).
- content
- The content of the document. Here you'll find the title, abstract, the document's year, a list of authors and information about the document's publication.
- metadata
- The document's metadata, containing the classification (as defined on Epistemonikos - About Us), the study_design (study desing only applies to primary studies, and we are only returning RCT yes/no by now), and the groups where the document belongs (if any).
- threads
- A list containing the studies threads IDs of each thread containing the document. Only shown if the show parameter list contains threads.
- relations_info
-
Information regarding the references related to this document.
The status fields shows if the document is
pending
(no information about it's related references),in_process
(the information is being completed), ordone
(the document has it's related references information completed). The total_references and reported_references fields shows the total amount of references linked to the document in the database, and the amount of included references reported by the authors of the document, respectively. The references field contains a breakdown of all the related references, sorted by classification, and containing the URL to access such references on the Epistemonikos Database. Only shown if the show parameter list contains relations_info. - classification_status
-
This fields shows the current status of the document's classification. It can be
pending
(the document hasn't been classified),machine
(it's onle been classified by our automatic algorithms), orvalidated
(it was classified by our collaborators, or the machine classification was validated by a collaborator). Only shown if the show parameter list contains classification_status.
Example 1: Simple request
Request
curl "{{ api_url }}/v1/documents/aced6ce12e1f54fb98c16d3435195ceb284240d2" -H 'Authorization: Token token="afbadb4ff8485c0adcba486b4ca90cc4"'
Response
Status Code: 200 OK - Content-Type: application/json; charset=utf-8
{{ samples['document_info']['result'] | json }}
Example 2: Request with show=threads parameter
Request
curl "{{ api_url }}/v1/documents/55d025440a4e37c5a56a21ff72baf670b6dd3a22?show=threads" -H 'Authorization: Token token="afbadb4ff8485c0adcba486b4ca90cc4"'
Response
Status Code: 200 OK - Content-Type: application/json; charset=utf-8
{{ samples['document_info_w_threads']['result'] | json }}
Example 3: Request with show=relations_info,classification_status parameters
Request
curl "{{ api_url }}/v1/documents/2063de052783f8c42c38bff9530e57bcee8f1353?show=relations_info,classification_status" -H 'Authorization: Token token="afbadb4ff8485c0adcba486b4ca90cc4"'
Response
Status Code: 200 OK - Content-Type: application/json; charset=utf-8
{{ samples['document_info_w_relations_info']['result'] | json }}
Document search GET: {{ api_url }}/v1/documents/search?q={keywords}[&g={group}&p={page}&sort={'year','score'}&show={'classification','external_links'}&classification={'systematic-review', 'structured-summary-of-systematic-review', 'broad-synthesis', 'primary-study', 'structured-summary-of-primary-study'}]
Parameters
- keywords
- The keywords you want to search in the Epistemonikos database. You can surround them in quote marks to run an exact match query.
- group
- [Optional] The group where you want to search the keywords. The valid groups are: vpp (Patients Values and Preferences), health_systems (documents from the PDQ-Evidence platform), cardiology and pti (Policy Trials Inventory). If the group provided in the query doesn't match any of the specified, the server will respond with a
400: Bad Request
HTTP status code - page
- [Optional] The page you want to retrieve in the search results. It's value is 1 by default (first page). If the value provided isn't a integer greater than zero, the server will respond with a
400: Bad Request
HTTP status code - sort
- [Optional] A comma separated list that specify the order for the results of your query. The valid options for sorting are year and score. You can choose between ascending or descending order by using minus or plus as prefix for each option (e.g.: both
sort=-year,score
andsort=-year,+score
means "sort by year, descending, and then by ascending score"). By default, they will be sorted by relevance (score, descending order). - classification
- [Optional] A comma separated list of document's classifications that you want to use as filters for the search results. The valid classifications are 'systematic-review', 'structured-summary-of-systematic-review', 'broad-synthesis', 'primary-study', and 'structured-summary-of-primary-study'. For more details go to Epistemonikos' database glossary
- show
- [Optional] A comma separated list stating which aditional document data you want to retrieve. Currently you can specify classification and external_links values, indicating that you want to see those attributes of each document in the search results.
Response
The response will contain two main items: the search_info, with information about the search results, and the results, which will contain a list of documents matching your query. Depending on the page you're currently on, the results list will have from zero to ten results.
In the search_info key of the response you'll find the following items:
- total_hits
- The total amount of documents found as result of your query.
- pages
- Inside this item are the URIs to navigate through the pages of your query results. Specifically, self is the URI of the current results page; prev and next are the URIs of the previous and following results page, and are only available when there is a previous or next page (for example, if you're on the first page, you won't see a prev URI); and first and last are the URIs of the first and last pages of results.
The results key contains a list of the results of your query, corresponding to the page received as parameter. Each item of the list contains the following keys:
- id
- The Epistemonikos ID of the document.
- year
- The document's publication year.
- classification
- The document's classification. Only shown if the show list contains classification
- external_links
- The document's external links section. Only shown if the show list contains external_links
- authors
- The document's authors.
- journal
- The document's publication journal.
- title
- The document's title.
- abstract
- The document's abstract.
- document_uri
- The document location in the API.
Example 1: Request without extra parameters
Request
curl {{ api_url }}/v1/documents/search?q=\"adjuvant\ treatment\" -H 'Authorization: Token token="afbadb4ff8485c0adcba486b4ca90cc4"'
Response
Status Code: 200 OK - Content-Type: application/json; charset=utf-8
{{ samples['document_search_wo_page']['result'] | json }}
Example 2: Request with a group, page and show='classification' parameter
Request
curl '{{ api_url }}/v1/documents/search?q=adjuvant&g=health_systems&p=2&show=classification' -H 'Authorization: Token token="afbadb4ff8485c0adcba486b4ca90cc4"'
Response
Status Code: 200 OK - Content-Type: application/json; charset=utf-8
{{ samples['document_search_w_page']['result'] | json }}
Document advanced search POST: {{ api_url }}/v1/documents/advanced_search
Parameters
- query
- The boolean query you want to search in the Epistemonikos database
- page
- [Optional] The page you want to retrieve in the search results. It's value is 1 by default (first page). If the value provided isn't a integer greater than zero, the server will respond with a
400: Bad Request
HTTP status code - page_size
- [Optional] The amount of results per page you want to retrieve. It must be a number between 0 and 500. It's value is 10 by default
- min_year
- [Optional] The lower limit of a date range for your results.
- max_year
- [Optional] The upper limit of a date range for your results.
- sort
- [Optional] A comma separated list that specify the order for the results of your query. The valid options for sorting are year and score. You can choose between ascending or descending order by using minus or plus as prefix for each option (e.g.: both
sort=-year,score
andsort=-year,+score
means "sort by year, descending, and then by ascending score"). By default, they will be sorted by relevance (score, descending order). - show
- [Optional] A comma separated list stating which aditional data you want to retrieve. Currently, only two values are available: classification, indicating that you want the classification of each document in the search results, and facets, which will show results faceting by publication year.
- exclude_cochrane
- [Optional] A parameter that allows you to exclude all results belonging to the Cochrane Library. It can be
true
orfalse
. - only_reviews
- [Optional] A parameter to restrict your search to Systematic Reviews only. It can be
true
orfalse
.
Response
The response will contain two main items: the search_info, with information about the search results, and the results, which will contain a list of documents matching your query. Depending on the page you're currently on, the results list will have from zero to ten results (or the value set in the page_size parameter). If your request includes the show=facets parameter, an aditional years_facets item will be included in the response.
In the search_info key of the response you'll find the following items:
- total_hits
- The total amount of documents found as result of your query.
- current_page
- The retrieved results page number.
- results_per_page
- The amount of documents retrieved per page.
The results key contains a list of the results of your query, corresponding to the page received as parameter. Each item of the list contains the following keys:
- id
- The Epistemonikos ID of the document.
- citation
- The document citation.
- authors
- The document's authors.
- year
- The document's publication year.
- journal
- The document's publication journal.
- classification
- The document's classification. Only shown if the show parameter list contains classification
- title
- The document's title.
- abstract
- The document's abstract.
- document_uri
- The document location in the API.
Example 1: Request without extra parameters
Post parameters
{{ samples['document_adv_search_wo_params']['params'] | json }}
Request
curl -X POST -H 'Authorization: Token token="afbadb4ff8485c0adcba486b4ca90cc4"' -H "Content-Type: application/json" -d '{{ JSON.stringify(samples['document_adv_search_wo_params']['params']) | json }}' {{ api_url }}/v1/documents/advanced_search
Response
Status Code: 200 OK - Content-Type: application/json; charset=utf-8
{{ samples['document_adv_search_wo_params']['result'] | json }}
Example 2: Request with page, page_size, min_year, max_year, sort, show, exclude_cochrane and only_reviews parameters
Post parameters
{{ samples['document_adv_search_w_params']['params'] | json }}
Request
curl -X POST -H 'Authorization: Token token="afbadb4ff8485c0adcba486b4ca90cc4"' -H "Content-Type: application/json" -d '{{ JSON.stringify(samples['document_adv_search_w_params']['params']) | json }}' {{ api_url }}/v1/documents/advanced_search
Response
Status Code: 200 OK - Content-Type: application/json; charset=utf-8
{{ samples['document_adv_search_w_params']['result'] | json }}
Studies thread information GET: {{ api_url }}/v1/studies_threads/{id}
Parameters
- id
- The studies thread ID.
Response
If the Epistemonikos database contains a studies thread with the provided ID, you'll receive a JSON containing the details of such thread and a 200: Ok
status code. Otherwise, you'll get a 404: Not Found
status code. These are the keys that you'll find in the request response:
- id
- The Epistemonikos ID of the studies thread.
- name
- The studies thread name
- fullname
- The studies thread fullname
- documents
- Contains a list with all the documents contained in the studies thread
Each document contained in the documents list contains the following keys:
- id
- The Epistemonikos ID of the document.
- title
- The document's title.
- document_uri
- The document location in the API.
- doi
- The DOI of the document.
- pubmed
- The PubMed ID of the document.
Example
Request
curl "{{ api_url }}/v1/studies_threads/5411b5b65f844e413814e99e" -H 'Authorization: Token token="afbadb4ff8485c0adcba486b4ca90cc4"'
Response
Status Code: 200 OK - Content-Type: application/json; charset=utf-8
{{ samples['studies_thread_info']['result'] | json }}
Matrix information GET: {{ api_url }}/v1/matrices/{id}[?show={'abstracts','threads'}]
Parameters
- id
- The ID of the public matrix you want to retrieve.
- show
- [Optional] A comma separated list stating which aditional matrix data you want to retrieve. If abstracts is submitted, it indicates that you want the abstract of each document. If threads is submitted, the result will show the studies threads that contains each document.
Response
If the Epistemonikos database contains a public matrix with the provided ID, you'll receive a JSON containing the details of such matrix and a 200: Ok
status code. If the matrix does exists but it isn't public, you'll get a minimal JSON document stating that your matrix isn't public yet. If our database doesn't contain a matrix with the ID provided you'll get a 404: Not Found
status code. These are the keys that you'll find in the request response:
- id
- The Epistemonikos ID of the matrix.
- is_public
- The publication state of the matrix. If it is
false
, none of the following keys will be displayed. - title
- The title of the matrix.
- authors
- A list containing the Epistemonikos usernames of the matrix authors.
- date
- The matrix creation date, in ISODate format.
- external_links
- URLs to the matrix in the epistemonikos platform.
- references
- Contains a list with all the documents contained in the matrix, separated by classification (primary_studies and systematic_reviews).
Each document contained in either primary_studies or systematic_reviews lists has the following keys:
- id
- The Epistemonikos ID of the document.
- title
- The document's title.
- abstract
- The document's abstract. Only shown if the show parameter list contains abstracts.
- document_uri
- The document location in the API.
- authors
- The document authors list.
- rct
true
,false
ornull
, depending on the documents being marked as RCT.- year
- The document's publication year.
- threads
- A list containing the studies threads IDs of each thread containing the document. Only shown if the show parameter list contains threads.
- doi
- The DOI of the document.
- pubmed
- The PubMed ID of the document.
Example 1: Not published matrix
Request
curl "{{ api_url }}/v1/matrices/51cb0836659e9351fbb431cf" -H 'Authorization: Token token="afbadb4ff8485c0adcba486b4ca90cc4"'
Response
Status Code: 200 OK - Content-Type: application/json; charset=utf-8
{{ samples['matrix_info_not_public']['result'] | json }}
Example 2: Published matrix
Request
curl "{{ api_url }}/v1/matrices/54171ed67aaac82af9fbeba0" -H 'Authorization: Token token="afbadb4ff8485c0adcba486b4ca90cc4"'
Response
Status Code: 200 OK - Content-Type: application/json; charset=utf-8
{{ samples['matrix_info']['result'] | json }}
Example 2: Published matrix with show=abstracts,threads parameters
Request
curl "{{ api_url }}/v1/matrices/54171ed67aaac82af9fbeba0?show=abstracts,threads" -H 'Authorization: Token token="afbadb4ff8485c0adcba486b4ca90cc4"'
Response
Status Code: 200 OK - Content-Type: application/json; charset=utf-8
{{ samples['matrix_info_w_abstract_threads']['result'] | json }}