{"swagger":"2.0","info":{"description":"Europe PMC Annotations API provides text mining annotations contained in abstracts and open access full text articles, using the W3C Open Annotation Data Model","version":"2.0.3","title":"Europe PMC Annotations API","contact":{"name":"Europe PMC","email":"helpdesk@europepmc.org"},"license":{"name":"Apache License Version 2.0","url":"https://www.apache.org/licenses/LICENSE-2.0"}},"host":"www.ebi.ac.uk","basePath":"/","tags":[{"name":"annotations-api-controller","description":"Europe PMC Annotations API"}],"paths":{"/europepmc/annotations_api/annotationsByArticleIds":{"get":{"tags":["annotations-api-controller"],"summary":"Get the annotations contained in the list of articles specified","operationId":"getAnnotationsArticlesByIdsUsingGET","consumes":["application/json"],"produces":["*/*"],"parameters":[{"name":"articleIds","in":"query","description":"Article Id lists contain between 1 and 8 values. Each value must follow the format SOURCE:EXTERNAL_ID. Allowed values for the field SOURCE are MED: PubMed MEDLINE, PMC: PubMedCentral not in (PubMed), PAT: Patents, AGR: Agricola (USDA/NAL), CBA: Chinese biological abstracts, HIR: NHS Evidence (UK HIR), CTX: CiteXplore submission, ETH: EThOS theses (BL), CIT: CiteSeer (PSU), PPR: Preprints, NBK: NLM Books (not in PubMed). EXTERNAL_ID must be the relevant identifier for the specified source (i.e. if SOURCE=MED it must be the PubMed ID or if SOURCE=PMC it must be a number representing the pmcid). Possible examples are MED:14670548 or PMC:19992","required":true,"type":"string"},{"name":"type","in":"query","description":"Type of the annotations that the user is interested in. If this parameter list is specified only annotations of the specified types in the list will be retrieved. User can choose more than one value from list e.g. Gene_Proteins,Organisms or Chemicals,Diseases,Accession Numbers. Result will get all annotations of type Gene_Proteins or type Organisms and for second example all annotations with type either Chemicals or Diseases or Accession Numbers","required":false,"type":"array","items":{"type":"string","enum":["Gene_Proteins","Organisms","Chemicals","Gene Ontology","Diseases","Accession Numbers","Resources","Gene Function","Gene Disease","Protein Interaction","Biological Event","Gene Mutations","TF_TG","Software MentionsCell Line","Cell","Sequence","Organ Tissue","Molecular Process","Clinical Drug","Experimental Methods","Molecule","Pathway","Anatomy","Phenotype","Sample-Material","Body-Site","Host","State","Site","Place","Date","Engineered","Ecoregion","Treatment","Kit","Primer","Gene","LS","LCM","Sequencing","COVoc","Gene Disease Relationship","Gene Drug Relationship","Disease Drug Relationship","Software Mentions"]},"collectionFormat":"multi","enum":["Gene_Proteins","Organisms","Chemicals","Gene Ontology","Diseases","Accession Numbers","Resources","Gene Function","Gene Disease","Protein Interaction","Biological Event","Gene Mutations","TF_TG","Software MentionsCell Line","Cell","Sequence","Organ Tissue","Molecular Process","Clinical Drug","Experimental Methods","Molecule","Pathway","Anatomy","Phenotype","Sample-Material","Body-Site","Host","State","Site","Place","Date","Engineered","Ecoregion","Treatment","Kit","Primer","Gene","LS","LCM","Sequencing","COVoc","Gene Disease Relationship","Gene Drug Relationship","Disease Drug Relationship","Software Mentions"]},{"name":"subType","in":"query","description":"Database of the Resource or of the Accession Number annotations that the user is interested in. It is taken into account only if the type list parameter contains atleast one type from following Resources or Accession Numbers. User can choose more than one value from sub type list and result will be filtered accordingly. e.g. if type parameteris Resources,Accession Numbers,Chemicals and subtype containes arrayexpress,biomodels, result will contain all annotations of type Resources and subtype wither arrayexpress or biomodels, with type Accesscion Numbers with subtypes either biomodels and arrayexpress and with all annotations of type chemicals with no subtype because subtype is only valid for type Resources and Accession Numbers only.","required":false,"type":"array","items":{"type":"string","enum":["alphafold","arrayexpress","bia","biomodels","bioproject","biosamples","biostudies","brenda","cath","chebi","cellosaurus","chembl","complexportal","dbgap","doi","efo","ega","emdb","empiar","ena","ensembl","ensemblgenomes","enzymeportal","epmc","eudract","eva","gca","geo","go","gisaid","gwas","gxa","hgnc","hipsci","hpa","hPSCreg","identifiers","igsr","intact","intenz","interpro","metabolights","metagenomics","mint","nct","ols","omim","orphadata","pdb","pfam","pride","reactome","rhea","refseq","refsnp","rfam","rnacentral","rrid","silva","stringdb","surechembl","treefam","uniparc","uniprot","vectorbase","wormbase"]},"collectionFormat":"multi","enum":["alphafold","arrayexpress","bia","biomodels","bioproject","biosamples","biostudies","brenda","cath","chebi","cellosaurus","chembl","complexportal","dbgap","doi","efo","ega","emdb","empiar","ena","ensembl","ensemblgenomes","enzymeportal","epmc","eudract","eva","gca","geo","go","gisaid","gwas","gxa","hgnc","hipsci","hpa","hPSCreg","identifiers","igsr","intact","intenz","interpro","metabolights","metagenomics","mint","nct","ols","omim","orphadata","pdb","pfam","pride","reactome","rhea","refseq","refsnp","rfam","rnacentral","rrid","silva","stringdb","surechembl","treefam","uniparc","uniprot","vectorbase","wormbase"]},{"name":"section","in":"query","description":"Section of the annotations that the user is interested in. If this parameter list is specified annotations belonging to the atleast one of specified article section list will be retrieved. More than one value can also be choose for this parameter e.g. Methods,Introduction,Abstract. result will contains all annotations for specified article with section Methods or Introduction or Abstract.","required":false,"type":"array","items":{"type":"string","enum":["Title","Abstract","Introduction","Methods","Results","Discussion","Acknowledgments","References","Article","Table","Figure","Case study","Supplementary material","Conclusion","Abbreviations","Competing Interests","Author Contributions","Data Availability"]},"collectionFormat":"multi","enum":["Title","Abstract","Introduction","Methods","Results","Discussion","Acknowledgments","References","Article","Table","Figure","Case study","Supplementary material","Conclusion","Abbreviations","Competing Interests","Author Contributions","Data Availability"]},{"name":"provider","in":"query","description":"Provider of the annotations that the user is interested in. If this parameter is specified annotations provideds from the specified list of provider will be retrieved. More than one value can also be choose for this parameter e.g. Europe PMC,OntoGene,OpenTargets. result will contains all annotations for specified article from provider Europe PMC or OntoGene or OpenTargets.","required":false,"type":"array","items":{"type":"string","enum":["Europe PMC","HES-SO_SIB","OpenTargets","NaCTeM","IntAct","DisGeNET","PubTator_NCBI","NTNU/BSC","OntoGene","PheneBank","Metagenomics","Biostudies","Scicrunch"]},"collectionFormat":"multi","enum":["Europe PMC","HES-SO_SIB","OpenTargets","NaCTeM","IntAct","DisGeNET","PubTator_NCBI","NTNU/BSC","OntoGene","PheneBank","Metagenomics","Biostudies","Scicrunch"]},{"name":"format","in":"query","description":"Output format of the response: ","required":false,"type":"string","enum":["JSON","JSON-LD","XML"]}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/ResultArticleIdDoc"}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}}},"/europepmc/annotations_api/annotationsByEntity":{"get":{"tags":["annotations-api-controller"],"summary":"Get the annotations of the articles which have at least one annotation tagging the specified entity","operationId":"getAnnotationsArticlesByEntityUsingGET","consumes":["application/json"],"produces":["*/*"],"parameters":[{"name":"entity","in":"query","description":"Entity that the user is interested in","required":true,"type":"string"},{"name":"filter","in":"query","description":"If the parameter is equal to 1, for each article only annotations tagging the specified entity will be retrieved. If the parameter is equal to 0, all the annotations will be retrieved for articles which also contain the specific tagged entity. For example, if you search for annotations with the entity 'P53', you would get an overview of all annotations for each article, together with the annotations tagging 'P53'","required":false,"type":"integer","default":1,"format":"int32","enum":[0,1]},{"name":"format","in":"query","description":"Output format of the response: ","required":false,"type":"string","default":"JSON","enum":["JSON","JSON-LD","XML","ID_LIST"]},{"name":"cursorMark","in":"query","description":"CursorMark for pagination of the result list. For the first request you can omit the parameter or use the default value 0.0. For every following page use the value of the returned nextCursorMark element","required":false,"type":"number","default":0.0,"format":"double"},{"name":"pageSize","in":"query","description":"Number of articles the user wishes to retrieve in each page. The value must be between 1 and 8","required":false,"type":"integer","default":4,"maximum":8.0,"minimum":1.0,"format":"int32"}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/ResultDoc"}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}}},"/europepmc/annotations_api/annotationsByProvider":{"get":{"tags":["annotations-api-controller"],"summary":"Get the annotations of the articles which have at least one annotation provided by the specified provider","operationId":"getAnnotationsArticlesByProviderUsingGET","consumes":["application/json"],"produces":["*/*"],"parameters":[{"name":"provider","in":"query","description":"Provider of the annotations that the user is interested in.","required":true,"type":"string","enum":["Europe PMC","HES-SO_SIB","OpenTargets","NaCTeM","IntAct","DisGeNET","PubTator_NCBI","NTNU/BSC","OntoGene","PheneBank","Metagenomics","Biostudies","Scicrunch","SoFAIR"]},{"name":"filter","in":"query","description":"If the parameter is equal to 1, for each article only annotations of the specific provider will be retrieved. If the parameter is equal to 0, all the annotations will be retrieved for articles which also contain annotations of the specific provider. For example, if you search for annotations of the provider 'Europe PMC', you would get an overview of all annotations for each article, together with the annotations of the provider 'Europe PMC'","required":false,"type":"integer","default":1,"format":"int32","enum":[0,1]},{"name":"format","in":"query","description":"Output format of the response: ","required":false,"type":"string","default":"JSON","enum":["JSON","JSON-LD","XML","ID_LIST"]},{"name":"cursorMark","in":"query","description":"CursorMark for pagination of the result list. For the first request you can omit the parameter or use the default value 0.0. For every following page use the value of the returned nextCursorMark element","required":false,"type":"number","default":0.0,"format":"double"},{"name":"pageSize","in":"query","description":"Number of articles the user wishes to retrieve in each page. The value must be between 1 and 8","required":false,"type":"integer","default":4,"maximum":8.0,"minimum":1.0,"format":"int32"}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/ResultDoc"}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}}},"/europepmc/annotations_api/annotationsByRelationship":{"get":{"tags":["annotations-api-controller"],"summary":"Get the annotations of the articles which have at least one annotation tagging both the specified entities (i.e. Gene-Disease relationship)","operationId":"getAnnotationsArticlesByRelationshipUsingGET","consumes":["application/json"],"produces":["*/*"],"parameters":[{"name":"firstEntity","in":"query","description":"First entity that the user is interested in","required":true,"type":"string"},{"name":"secondEntity","in":"query","description":"Second entity that the user is interested in","required":true,"type":"string"},{"name":"filter","in":"query","description":"If the parameter is equal to 1, for each article only annotations tagging both the specified entities will be retrieved. If the parameter is equal to 0, all the annotations will be retrieved for articles which also contain both specific tagged entities. For example, if you search for annotations with both entities 'cancer' and 'MMP-9', you would get an overview of all annotations for each article, together with the annotations tagging both 'cancer' and 'MMP-9'","required":false,"type":"integer","default":1,"format":"int32","enum":[0,1]},{"name":"format","in":"query","description":"Output format of the response: ","required":false,"type":"string","default":"JSON","enum":["JSON","JSON-LD","XML","ID_LIST"]},{"name":"cursorMark","in":"query","description":"CursorMark for pagination of the result list. For the first request you can omit the parameter or use the default value 0.0. For every following page use the value of the returned nextCursorMark element","required":false,"type":"number","default":0.0,"format":"double"},{"name":"pageSize","in":"query","description":"Number of articles the user wishes to retrieve in each page. The value must be between 1 and 8","required":false,"type":"integer","default":4,"maximum":8.0,"minimum":1.0,"format":"int32"}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/ResultDoc"}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}}},"/europepmc/annotations_api/annotationsBySectionAndOrType":{"get":{"tags":["annotations-api-controller"],"summary":"Get the annotations of the articles which have at least one annotation of a type (if specified) inside an article section (if specified). At least one value between section and type must be specified.","operationId":"getAnnotationsArticlesBySectionAndOrTypeUsingGET","consumes":["application/json"],"produces":["*/*"],"parameters":[{"name":"type","in":"query","description":"Type of the annotations that the user is interested in","required":false,"type":"string","default":"UNSPECIFIED","enum":["Gene_Proteins","Organisms","Chemicals","Gene Ontology","Diseases","Accession Numbers","Resources","Gene Function","Gene Disease","Protein Interaction","Biological Event","Gene Mutations","TF_TG","Cell Line","Cell","Sequence","Organ Tissue","Molecular Process","Clinical Drug","Experimental Methods","Molecule","Pathway","Anatomy","Phenotype","Sample-Material","Body-Site","Host","State","Site","Place","Date","Engineered","Ecoregion","Treatment","Kit","Primer","Gene","LS","LCM","Sequencing","COVoc","Gene Disease Relationship","Gene Drug Relationship","Disease Drug Relationship","Software Mentions"]},{"name":"subType","in":"query","description":"Database of the Resource or of the Accession Number annotations that the user is interested in. It is taken into account only if the type parameter is either equal to Resources or Accession Numbers","required":false,"type":"string","default":"UNSPECIFIED","enum":["alphafold","arrayexpress","bia","biomodels","bioproject","biosamples","biostudies","brenda","cath","chebi","cellosaurus","chembl","complexportal","dbgap","doi","efo","ega","emdb","empiar","ena","ensembl","ensemblgenomes","enzymeportal","epmc","eudract","eva","gca","geo","go","gisaid","gwas","gxa","hgnc","hipsci","hpa","hPSCreg","identifiers","igsr","intact","intenz","interpro","metabolights","metagenomics","mint","nct","ols","omim","orphadata","pdb","pfam","pride","reactome","rhea","refseq","refsnp","rfam","rnacentral","rrid","silva","stringdb","surechembl","treefam","uniparc","uniprot","vectorbase","wormbase"]},{"name":"section","in":"query","description":"Section of the annotations that the user is interested in","required":false,"type":"string","default":"UNSPECIFIED","enum":["Title","Abstract","Introduction","Methods","Results","Discussion","Acknowledgments","References","Article","Table","Figure","Case study","Supplementary material","Conclusion","Abbreviations","Competing Interests","Author Contributions","Data Availability"]},{"name":"filter","in":"query","description":"If the parameter is equal to 1, for each article only annotations of the specified type belonging to the specified article section will be retrieved. If the parameter is equal to 0, all the annotations will be retrieved for articles which also contain annotations of the specified type belonging to the specified article section. For example, if you search for annotations of the type 'Gene_Proteins' belonging to the section 'Introduction', you would get an overview of all annotations for each article, together with the annotations of the type 'Gene_Proteins' belonging to the section 'Introduction'","required":false,"type":"integer","default":1,"format":"int32","enum":[0,1]},{"name":"format","in":"query","description":"Output format of the response: ","required":false,"type":"string","default":"JSON","enum":["JSON","JSON-LD","XML","ID_LIST"]},{"name":"cursorMark","in":"query","description":"CursorMark for pagination of the result list. For the first request you can omit the parameter or use the default value 0.0. For every following page use the value of the returned nextCursorMark element","required":false,"type":"number","default":0.0,"format":"double"},{"name":"pageSize","in":"query","description":"Number of articles the user wishes to retrieve in each page. The value must be between 1 and 8","required":false,"type":"integer","default":4,"maximum":8.0,"minimum":1.0,"format":"int32"}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/ResultDoc"}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}}}}},"definitions":{"AnnotationJsonLD":{"type":"object","properties":{"@context":{"type":"string","description":"JSON-LD context file"},"creator":{"type":"string","description":"Provider of the annotation"},"id":{"type":"string","description":"Link back to the specific sentence of the article that contains the annotation"},"memberOf":{"type":"string","description":"Field populated only for accession numbers or resource names annotations. It indicates the database name the annotations are belonging to."},"type":{"type":"string","description":"Type of the resource"}},"description":"It holds the annotation data in JSON-LD format. To see details about JSON-LD go to http://europepmc.org/AnnotationsApi#jsonLD"},"AnnotationTagInfo":{"type":"object","properties":{"name":{"type":"string","description":"Name of the external database resource"},"uri":{"type":"string","description":"URI of the external database resource"}},"description":"It holds the data describing an external database resource tagged by an annotation"},"ResultDoc":{"type":"object","properties":{"annotations":{"type":"array","description":"List of annotations in JSON-LD format. It is only populated when the format parameter is equal to JSON-LD. To see details about JSON-LD go to http://europepmc.org/AnnotationsApi#jsonLD","items":{"$ref":"#/definitions/AnnotationJsonLDDoc"}},"articles":{"type":"array","description":"List of articles with the relative annotations. It is only populated when the format parameter is equal to either JSON or XML or ID_LIST","items":{"$ref":"#/definitions/ArticleResult"}},"cursorMark":{"type":"number","format":"double","description":"CursorMark used in the current call to get the current page of the result set"},"nextCursorMark":{"type":"number","format":"double","description":"CursorMark to be used in the next call to get the next page of the result set"}},"description":"It holds the annotations of a number of articles"},"AnnotationJsonLDDoc":{"type":"object","properties":{"@context":{"type":"string","description":"JSON-LD context file"},"body":{"type":"string","description":"For named entity annotations (i.e. provided by Europe PMC) it represents the URI of the database resource the annotation is referring to.
For sentence based annotations (i.e. provided by HES-SO / SIB Text Mining for Elixir, NaCTeM, IntAct) and annotations containing Gene Disease relationships (i.e. provided by Open Targets Platform and DisGeNET) it represents the portion of the article where the annotation is contained:
\"body\": {
   \"id\": \"http://europepmc.org/abstract/MED/15892892#geneRif_356408_P36159\", # ann_link
   \"type\": \"TextualBody\",
   \"value\": \"In this work, we show that the yeast homolog of ELAC2, encoded by TRZ1 (tRNase Z 1), is involved genetically in RNA processing.\", # exact
   \"source\": \"http://europepmc.org/articles/MED/15892892\", # ext_id
   \"isPartOf\": \"Abstract\" #section
} "},"creator":{"type":"string","description":"Provider of the annotation"},"id":{"type":"string","description":"Link back to the specific sentence of the article that contains the annotation"},"memberOf":{"type":"string","description":"Field populated only for accession numbers or resource names annotations. It indicates the database name the annotations are belonging to."},"target":{"type":"string","description":"For named entity annotations (i.e. provided by Europe PMC) it represents the portion of the article where the annotation is contained:
\"target\": {
   \"id\": \"http://europepmc.org/articles/MED/21494379#europepmc_1-1\", # ann_link
   \"source\": \"http://europepmc.org/articles/MED/21494379\", # ext_id
   \"isPartOf\": \"Title\", # section
   \"selector\": {
      \"type\": \"TextQuoteSelector\",
      \"exact\": \"Fluoride\",
      \"prefix\": \"\",
      \"suffix\": \" concentration of some brands of ferment\"
   }
}.
For sentence based annotations (i.e. provided by HES-SO / SIB Text Mining for Elixir, NaCTeM, IntAct) it represents the URI of the database resource the annotation is referring to.
For annotations containing Gene Disease relationships (i.e. provided by Open Targets Platform and DisGeNET) represents the URI of both gene and disease the annotation is referring to :
\"target\": {
   \"type\": \"List\",
   \"items\": [ { \"id\": \"http://purl.uniprot.org/uniprot/Q14790\", \"label\": \"caspase 8\" }, { \"id\": \"http://www.ebi.ac.uk/efo/EFO_0001668\", \"label\": \"HPV\" } ] # tags
}."},"type":{"type":"string","description":"Type of the resource"}},"description":"It holds the annotation data in JSON-LD format. To see details about JSON-LD go to http://europepmc.org/AnnotationsApi#jsonLD"},"ArticleResult":{"type":"object","properties":{"annotations":{"type":"array","description":"Annotations contained in this article","items":{"$ref":"#/definitions/Annotation"}},"extId":{"type":"string","description":"Identifier of the article connected with the domain specified by the source field (i.e. if SOURCE=MED it will be the PubMed ID or if SOURCE=PMC it will be a number representing the pmcid)"},"fullTextIdList":{"type":"array","description":"fulltext identifiers of the article if available","items":{"type":"string"}},"pmcid":{"type":"string","description":"pmcid of the article if available"},"source":{"type":"string","description":"Source of the article","enum":["MED","PMC","PAT","AGR","CBA","HIR","CTX","ETH","CIT","PPR","NBK"]}},"description":"It holds the annotations corresponding to a specific article"},"Annotation":{"type":"object","properties":{"exact":{"type":"string","description":"Text of the annotation inside the article"},"fileName":{"type":"string","description":"Subcategorization of the specific section of the article. It is relevant only for section type : Supplementary material."},"frequency":{"type":"integer","format":"int32","description":"Frequency of the annotation"},"id":{"type":"string","description":"Link to be used to link back to the specific sentence of the article that contains the annotation"},"postfix":{"type":"string","description":"Suffix of the annotation inside the article"},"prefix":{"type":"string","description":"Prefix of the annotation inside the article"},"provider":{"type":"string","description":"Provider of the annotation"},"section":{"type":"string","description":"Section of the article where the annotation is appearing"},"subType":{"type":"string","description":"Subcategorization of the semantic type of the annotation. It is relevant only for specific semantic types: Accession Numbers and Resources."},"tags":{"type":"array","description":"List of external database resources connected with the annotation","items":{"$ref":"#/definitions/AnnotationTagInfo"}},"type":{"type":"string","description":"Semantic type of the annotation"}},"description":"It holds the data of a specific annotation"},"ResultArticleIdDoc":{"type":"object","properties":{"annotations":{"type":"array","description":"List of annotations in JSON-LD format. It is only populated when the format parameter is equal to JSON-LD. To see details about JSON-LD go to http://europepmc.org/AnnotationsApi#jsonLD","items":{"$ref":"#/definitions/AnnotationJsonLDDoc"}},"articles":{"type":"array","description":"List of articles with the relative annotations. It is only populated when the format parameter is equal to either JSON or XML or ID_LIST","items":{"$ref":"#/definitions/ArticleResult"}}},"description":"It holds the annotations of the articles coming from the api when the user search by Article Ids. The response will be an array of articles of type ArticleResult in case the format parameter is equal to either JSON or XML or ID_LIST. Otherwise if the format parameter is equal to JSON_LD the response will be an array of annotations of type AnnotationJsonLDDoc. To see details about Json LD go to http://europepmc.org/AnnotationsApi#jsonLD. "},"Result":{"type":"object","properties":{"annotations":{"type":"array","description":"list of annotations in JSON LD format. It is populated only in case the format parameter is equal to JSON_LD","items":{"$ref":"#/definitions/AnnotationJsonLD"}},"articles":{"type":"array","description":"list of articles with the relative annotations. It is populated only in case the format parameter is equal to either JSON or XML","items":{"$ref":"#/definitions/ArticleResult"}},"cursorMark":{"type":"number","format":"double","description":"cursorMark used in the current call to get the current page of the result set"},"nextCursorMark":{"type":"number","format":"double","description":"cursorMark to be used in the next call to get the next page of the result set"}},"description":"It holds the annotations of a number of articles coming from the api"}}}