Example Queries and Results
The following are examples of valid DSL queries and the type of JSON data they return. See also the Data Sources section for examples of how query using relationships between different source documents.
See also
The Dimensions API Lab on Github contains more tutorials and Jupyter notebooks.
Minimal valid query
search grants return grants
Retrieves the latest scientific research grants.
{
"grants": [
{
"project_num": "HDTRA11710002",
"active_year": [
2019,
2020,
2021
],
"title_language": "en",
"funding_org_name": "Defense Threat Reduction Agency",
"start_year": 2019,
"funders": [
{
"acronym": "DTRA",
"country_name": "United States",
"id": "grid.452918.3",
"name": "Defense Threat Reduction Agency"
}
],
"id": "grant.6795027",
"original_title": "Discriminatory Transcriptional Response of Environmental Microorganisms and Microbial Communities to Low-Dose Ionizing Radiation",
"start_date": "2019-11-16T00:00:00Z",
"language": "en",
"title": "Discriminatory Transcriptional Response of Environmental Microorganisms and Microbial Communities to Low-Dose Ionizing Radiation",
"end_date": "2021-11-15T00:00:00Z"
},
{
"project_num": "BB/P023959/1",
"active_year": [
2019,
2020
],
"title_language": "en",
"funding_org_name": "BBSRC",
"start_year": 2019,
"funder": [
{
"acronym": "BBSRC",
"country_name": "United Kingdom",
"id": "grid.418100.c",
"name": "Biotechnology and Biological Sciences Research Council"
}
],
"id": "grant.6711354",
"original_title": "FunPDBe - Community driven enrichment of PDB data with structural and functional annotations",
"start_date": "2019-08-31T23:00:00Z",
"language": "en",
"title": "FunPDBe - Community driven enrichment of PDB data with structural and functional annotations",
"end_date": "2020-08-30T23:00:00Z"
},
"...more grants here..."
]
}
Searching records
Search terms
See also
Documentation for “for”, Definition of search term
search publications for "AIDS" return publications
search publications in title_abstract_only for "AIDS" return publications
Retrieves scholarly publications matching the search term “AIDS”.
{
"publications": [
{
"issue": "1",
"journal": {
"id": "jour.1045337",
"title": "Scientific reports"
},
"title": "An Amidase_3 domain-containing N- acetylmuramyl-L-alanine amidase is required for mycobacterial cell division",
"volume": "7",
"pages": "1140",
"pmc_id": "5430687",
"id": "pub.1085056356",
"year": 2017
},
{
"issue": "1",
"journal": {
"id": "jour.1045337",
"title": "Scientific reports"
},
"title": "Possible association between SIRT1 single nucleotide polymorphisms and predisposition to antisocial personality traits in Chinese adolescents",
"volume": "7",
"pages": "1099",
"pmc_id": "5430697",
"id": "pub.1084946868",
"year": 2017
},
{
"issue": "1",
"journal": {
"id": "jour.1024954",
"title": "BMC public health"
},
"title": "\u201cEnsure that you are well aware of the risks you are taking\u2026\u201d: actions and activities medical tourists\u2019 informal caregivers can undertake to protect their health and safety",
"volume": "17",
"pages": "487",
"pmc_id": "5440913",
"id": "pub.1085558642",
"year": 2017
},
"...more publications here..."
]
}
Filters
See also
Documentation for “where”
Simple filters
See also
Documentation for simple filters, definition of field
search publications for "HIV"
where year<=2010
return publications
Retrieves the first N publications after restricting the search set to only those records published in 2010 or earlier.
{
"publications": [
{
"issue": "53",
"journal": {
"id": "jour.1077138",
"title": "The Journal of biological chemistry"
},
"id": "pub.1031758467",
"volume": "285",
"pages": "41772-41780",
"title": "CC Chemokine Receptor 5 (CCR5) Desensitization CYCLING RECEPTORS ACCUMULATE IN THE TRANS-GOLGI NETWORK",
"year": 2010
},
{
"issue": "6",
"journal": {
"id": "jour.1016936",
"title": "Acta obstetricia et gynecologica Scandinavica"
},
"id": "pub.1036396282",
"volume": "89",
"pages": "789-793",
"title": "Recording of maternal deaths in an East African university hospital",
"year": 2010
},
{
"issue": "27",
"journal": {
"id": "jour.1014075",
"title": "The New England journal of medicine"
},
"id": "pub.1024626801",
"volume": "363",
"pages": "2663-2665",
"title": "Oral Preexposure Prophylaxis for HIV \u2014 Another Arrow in the Quiver?",
"year": 2010
},
"...more publications here..."
]
}
Boolean operators
See also
Documentation for boolean operators in filters
search grants for "HIV"
where ((start_year>2010 and start_year<=2012) or funding_org_name="European Commission")
return grants[title + start_year + funding_org_name] sort by title
Retrieves HIV-related grants from any funder which started after 2010 and no later than 2012 (i.e. started in 2011 or 2012), along with HIV-related grants from any year which were funded by the European Commission.
(For display purposes, grant records include only the title, start year, and funding organization name, and are sorted by title in reverse alphabetical order. See Returning records below for explanation of these features.)
{
"grants": [
{
"start_year": 2011,
"title": "hnRNP A1 inhibition of HIV-1 replication",
"funding_org_name": "NATIONAL INSTITUTE OF ALLERGY AND INFECTIOUS DISEASES"
},
{
"start_year": 2012,
"title": "development of hepatocellular carcinoma novel therapeutics that target wnt signaling and dUTPase",
"funding_org_name": "Japan Society for the Promotion of Science"
},
{
"start_year": 1997,
"title": "dNTP interaction with the active sites of human DNA polymerases and human immunodeficiency virus reverse transcriptase",
"funding_org_name": "European Commission"
},
{
"start_year": 2011,
"title": "aptamer",
"funding_org_name": "Japan Society for the Promotion of Science"
},
{
"start_year": 2012,
"title": "Zinc for HIV Disease among Alcohol Users -An RCT in the Russia ARCH Cohort",
"funding_org_name": "NATIONAL INSTITUTE ON ALCOHOL ABUSE AND ALCOHOLISM"
},
{
"start_year": 2016,
"title": "ZIKAction: Preparedness, research and action network on maternal-paediatric axis of ZIKV infection in Latin America and the Caribbean",
"funding_org_name": "European Commission"
},
{
"start_year": 2012,
"title": "Youth and political engagement in contemporary Africa",
"funding_org_name": "Academy of Finland"
},
"...more grants here..."
]
}
Partial-match filters
See also
Documentation for Partial string matching with ~
search grants
where research_orgs.name~"National Blood"
return research_orgs[name]
Retrieves research organization of grants, restricted to organizations whose names include the terms “National” and “Blood”, in any spacing/order.
{
"research_orgs": [
{
"id": "grid.279885.9",
"count": 1745,
"name": "National Heart, Lung, and Blood Institute"
},
{
"id": "grid.452091.b",
"count": 8,
"name": "Hungarian National Blood Transfusion Service"
},
{
"id": "grid.436467.4",
"count": 5,
"name": "National Blood Clot Alliance"
},
"...more research_orgs here..."
]
}
Contrast this with the exact-match filter in the query
search grants where research_org.name="National Blood" return research_orgs:[name]
(using the = operator instead of ~), which would result in an error
because there is no known organization with the exact name “National Blood”.
Ranges
See also
Documentation for range and list filters
search publications for "HIV"
where year in [2005:2015]
return publications
Retrieves HIV-related publications which were published between the years 2005 and 2015, inclusive.
{
"publications": [
{
"issue": "1-2",
"journal": {
"title": "Addiction & health",
"id": "26175"
},
"year": 2015,
"volume": "7",
"pages": "1-13",
"pmc_id": "PMC4530188",
"id": "26322205",
"title": "Network Location and Risk of Human Immunodeficiency Virus Transmission among Injecting Drug Users: Results of Multiple Membership Multilevel Modeling of Social Networks."
},
{
"issue": "3-4",
"journal": {
"title": "Addiction & health",
"id": "26175"
},
"year": 2015,
"volume": "7",
"pages": "164-73",
"pmc_id": "PMC4741237",
"id": "26885353",
"title": "Client-Level Coverage of Needle and Syringe Program and High-Risk Injection Behaviors: A Case Study of People Who Inject Drugs in Kermanshah, Iran."
},
{
"issue": "4",
"journal": {
"title": "Communicable diseases intelligence quarterly report",
"id": "9622"
},
"year": 2015,
"volume": "39",
"pages": "E635",
"pmc_id": "",
"id": "26779742",
"title": "HIV surveillance, 1 January to 31 March 2014."
},
"...more grants here..."
]
}
The range filter syntax is a shorthand notation for convenience. The same results could be retrieved using the following equivalent query:
search publications for "HIV"
where year>=2005 and year<=2015
return publications
Lists
See also
Documentation for range and list filters
search grants for "H2O"
where language in ["de", "zh", "fr"]
return grants
Retrieves grants related to water (“H2O”) where the language of original publication is either German (“de”), Chinese (“zh”), or French (“fr”).
{
"grants": [
{
"project_num": "578812",
"active_year": [
2015,
2016
],
"title_language": "fr",
"funding_org_name": "Natural Sciences and Engineering Research Council of Canada",
"start_year": 2015,
"funders": [
{
"acronym": "NSERC",
"country_name": "Canada",
"id": "grid.452912.9",
"name": "Natural Sciences and Engineering Research Council of Canada"
}
],
"id": "grant.5529279",
"original_title": "D\u00e9veloppement d'une plate-forme de calibration pour des analyseurs de syngaz",
"start_date": "2015-04-01T00:00:00Z",
"language": "fr",
"title": "Development of a calibration rig for analyzers syngas",
"end_date": "2016-03-31T00:00:00Z"
},
{
"title": "Electrical conductivity and dissociation of fluids in the crust and mantle",
"project_num": "238445505",
"active_year": [
2013
],
"start_date": "2013-01-01T00:00:00Z",
"title_language": "de",
"funding_org_name": "German Research Foundation",
"start_year": 2013,
"language": "de",
"funders": [
{
"acronym": "DFG",
"country_name": "Germany",
"id": "grid.424150.6",
"name": "German Research Foundation"
}
],
"id": "grant.4826432",
"original_title": "Elektrische Leitf\u00e4higkeit und Dissoziation von Fluiden in Kruste und Mantel"
},
{
"project_num": "51072096",
"active_year": [
2011,
2012,
2013
],
"title_language": "zh",
"funding_org_name": "National Natural Science Foundation",
"start_year": 2011,
"funders": [
{
"acronym": "NSFC",
"country_name": "China",
"id": "grid.419696.5",
"name": "National Natural Science Foundation"
}
],
"id": "grant.4996277",
"original_title": "\u94a1\u6539\u6027\u8fc7\u6e21\u91d1\u5c5e-\u94c8\u57fa\u590d\u5408\u6c27\u5316\u7269\u8bbe\u8ba1\u3001\u5236\u5907\u53ca\u78b3\u70df\u6c27\u5316\u50ac\u5316\u673a\u5236\u7814\u7a76",
"start_date": "2011-01-01T00:00:00Z",
"language": "zh",
"title": "Modified barium transition metals - cerium oxide-based composite design preparation and soot oxidation catalytic mechanism research,",
"end_date": "2013-12-31T00:00:00Z"
},
"...more grants here..."
]
}
The list syntax is a shorthand notation for convenience. The same results could be retrieved using the following equivalent query:
search grants for "H2O"
where language="de" or language="zh" or language="fr"
return grants
Entity metadata
See also
Documentation for entity filters, Definition of entity
Simple entity filters
search grants for "Zika"
where funders.acronym="NHLBI"
return grants
Retrieves grants related to Zika that were funded by the organization(s) whose acronym is “NHLBI”, by first searching all the known funders to find the ID number(s) for the organization(s) that have this acronym. In this case, there is only one matching funding organization, the (US) National Heart, Lung, and Blood Institute.
{
"grants": [
{
"project_num": "R21HL137439",
"active_year": [
2017,
2018
],
"title_language": "en",
"funding_org_name": "NATIONAL HEART, LUNG, AND BLOOD INSTITUTE",
"start_year": 2017,
"funders": [
{
"acronym": "NHLBI",
"country_name": "United States",
"id": "grid.279885.9",
"name": "National Heart, Lung, and Blood Institute"
}
],
"id": "grant.6541541",
"original_title": "Clinical Outcomes of Zika Virus in Sickle Cell Disease",
"start_date": "2017-01-09T00:00:00Z",
"language": "en",
"title": "Clinical Outcomes of Zika Virus in Sickle Cell Disease",
"end_date": "2018-12-31T00:00:00Z"
},
{
"project_num": "268201100001I-0-26800003-1",
"active_year": [
2016,
2017,
2018,
2019
],
"title_language": "en",
"funding_org_name": "NATIONAL HEART, LUNG, AND BLOOD INSTITUTE",
"start_year": 2016,
"funders": [
{
"acronym": "NHLBI",
"country_name": "United States",
"id": "grid.279885.9",
"name": "National Heart, Lung, and Blood Institute"
}
],
"id": "grant.6501375",
"original_title": "IGF::OT::IGF: Task Order TO No. HHSN26800003, titled Recipient Epidemiology and Donor Evaluation Study III REDS-III Central Laboratory - Characterization of blood transfusion-transmission of Zika viru",
"start_date": "2016-09-15T00:00:00Z",
"language": "en",
"title": "IGF::OT::IGF: Task Order TO No. HHSN26800003, titled Recipient Epidemiology and Donor Evaluation Study III REDS-III Central Laboratory - Characterization of blood transfusion-transmission of Zika viru",
"end_date": "2019-08-31T00:00:00Z"
},
{
"project_num": "R01HL105704",
"active_year": [
2011,
2012,
2013,
2014,
2015,
2016,
2017,
2018,
2019,
2020
],
"title_language": "en",
"funding_org_name": "NATIONAL HEART, LUNG, AND BLOOD INSTITUTE",
"start_year": 2011,
"funders": [
{
"acronym": "NHLBI",
"country_name": "United States",
"id": "grid.279885.9",
"name": "National Heart, Lung, and Blood Institute"
}
],
"id": "grant.2543102",
"original_title": "Pan-Genomic Approaches for Comprehensive Blood Screening of Novel or Emerging Infectious Agents",
"start_date": "2011-04-01T00:00:00Z",
"language": "en",
"title": "Pan-Genomic Approaches for Comprehensive Blood Screening of Novel or Emerging Infectious Agents",
"end_date": "2020-12-31T00:00:00Z"
}
]
}
Complex entity filters
Like all filters, entity metadata filters may be combined using boolean operators and parentheses, as seen in the following example:
search publications for "women"
where (research_orgs.country_name="Senegal" or research_orgs.country_name="Gambia")
and (year>=2000 and year<=2015)
return publications
Retrieves publications related to women that were published between 2000 and 2015 (inclusive) by research organizations in the countries of Senegal or the Gambia.
{
"publications": [
{
"issue": "11",
"journal": {
"id": "jour.1115714",
"title": "Tropical medicine & international health : TM & IH"
},
"id": "pub.1028124172",
"volume": "20",
"pages": "1415-1423",
"title": "Improving survey data on pregnancy\u2010related deaths in low\u2010and middle\u2010income countries: a validation study in Senegal",
"year": 2015
},
{
"journal": {
"id": "jour.1093956",
"title": "Social science & medicine (1982)"
},
"id": "pub.1000413115",
"volume": "133",
"pages": "296-303",
"title": "HIV/AIDS in mid-sized cities in Senegal: From individual to place-based vulnerability",
"year": 2015
},
{
"issue": "9",
"journal": {
"id": "jour.1113424",
"title": "Environmental science and pollution research international"
},
"id": "pub.1036429543",
"volume": "22",
"pages": "7101-7111",
"title": "Human exposure to mercury in artisanal small-scale gold mining areas of Kedougou region, Senegal, as a function of occupational activity and fish consumption",
"year": 2015
},
{
"issue": "7",
"journal": {
"id": "jour.1097360",
"title": "AIDS (London, England)"
},
"id": "pub.1050874164",
"volume": "29",
"pages": "825",
"title": "Hair concentrations of antiretrovirals predict viral suppression in HIV-infected pregnant and breastfeeding Ugandan women",
"year": 2015
},
"...more publications here..."
]
}
Both
search publications for "AIDS"
where year=2010
return publications
search publications where year=2010 for "AIDS" return publications
Both queries retrieve publications matching the search term “AIDS”, but only those publications published in the year 2010 are included in the set to be ranked against the search term.
The two queries are equivalent; the for and where phrases are independent, and can occur in either order.
Note
As noted in the documentation of where, filtering is performed before ranking records by similarity with the search term.
{
"publications": [
{
"issue": "6",
"journal": {
"id": "jour.1016936",
"title": "Acta obstetricia et gynecologica Scandinavica"
},
"id": "pub.1036396282",
"volume": "89",
"pages": "789-793",
"title": "Recording of maternal deaths in an East African university hospital",
"year": 2010
},
{
"issue": "1",
"journal": {
"id": "jour.1143853",
"title": "Revista Direito e Pr\u00e1xis"
},
"id": "pub.1064764436",
"volume": "1",
"title": "Assessoria jur\u00eddica universit\u00e1ria popular: bases comuns para rumos diferentes / Universitarian legal aid: common basis for different strategies",
"year": 2010
},
"...more publications here..."
]
}
Returning records
See also
Documentation for Returning results, Definition of record
Fields
See also
Documentation for specifying fields
Fieldsets
See also
Documentation for named fieldsets, Definition of fieldset
Supported fieldsets for each source
Basics
search grants for "malaria" return grants[basics]
search grants for "malaria" return grants
In both queries, the JSON results will only include a limited, predefined set of fields (the basics fieldset) for each grant (in this case, a single grant specified by ID).
These two queries are equivalent, as the language uses basics as the default fieldset if no fields are specified.
{
"grants": [
{
"project_num": "170702",
"active_year": [
2017,
2018,
2019,
2020,
2021
],
"title_language": "en",
"funding_org_name": "Swiss National Science Foundation",
"start_year": 2017,
"funders": [
{
"acronym": "SNF",
"country_name": "Switzerland",
"id": "grid.425888.b",
"name": "Swiss National Science Foundation"
}
],
"id": "grant.6918131",
"original_title": "Multi-scale mathematical modelling of parasite, drug and vaccine interactions: optimising public health and disease elimination\u00a0strategies",
"start_date": "2017-07-01T00:00:00Z",
"language": "en",
"title": "Multi-scale mathematical modelling of parasite, drug and vaccine interactions: optimising public health and disease elimination\u00a0strategies",
"end_date": "2021-06-30T00:00:00Z"
},
"...more grants here..."
]
}
Detailed
search grants for "malaria" return grants[basics + extras]
In contrast to the previous query, the JSON results include all fields predefined as part of the larger detailed fieldset.
{
"grants": [
{
"project_num": "170702",
"linkout": "http://p3.snf.ch/project-170702",
"active_year": [
2017,
2018,
2019,
2020,
2021
],
"funding_org_acronym": "SNF",
"title_language": "en",
"funding_org_name": "Swiss National Science Foundation",
"funding_org_country_name": "Switzerland",
"research_org_names": "Universit\u00e4t Basel",
"funder_country": [
"CH"
],
"id": "grant.6918131",
"funders": [
{
"acronym": "SNF",
"country_name": "Switzerland",
"id": "grid.425888.b",
"name": "Swiss National Science Foundation"
}
],
"funding_org_city": "Berne",
"end_date": "2021-06-30T00:00:00Z",
"start_year": 2017,
"original_title": "Multi-scale mathematical modelling of parasite, drug and vaccine interactions: optimising public health and disease elimination\u00a0strategies",
"language": "en",
"title": "Multi-scale mathematical modelling of parasite, drug and vaccine interactions: optimising public health and disease elimination\u00a0strategies",
"start_date": "2017-07-01T00:00:00Z"
},
"...more grants here..."
]
}
Arbitrary fieldlist
See also
Documentation for specifying arbitrary fields, Definition of field
Supported fields for each source
search grants for "malaria"
return grants[id + title + start_date]
The JSON results for each grant only contain the three specified fields id, title, and date.
{
"grants": [
{
"title": "Multi-scale mathematical modelling of parasite, drug and vaccine interactions: optimising public health and disease elimination\u00a0strategies",
"id": "grant.6918131",
"date": "2017-07-01T00:00:00Z"
},
"...more grants here..."
]
}
Sorting
search grants
return grants[id + title] sort by id
Returns grants sorted by the value of a field on the record, in this case the grant ID numbers (in descending order), as opposed to the default date-based sorting.
Note
At the moment it is not possible to specify the sorting direction (ascending or descending), only the sorting indicator; the direction is always descending for the time being. This will be changed in a future version of the language.
{
"grants": [
{
"title": "Universal Plasma Generator for Selective Removal of Anti-A and Anti-B Antibodies from Donor Plasma",
"id": "grant.6919794"
},
{
"title": "Interactive Sensor Fusion for Context-Aware Discrimination",
"id": "grant.6919793"
},
{
"title": "Revolutionary Airlift Innovation",
"id": "grant.6919792"
},
"...more grants here..."
]
}
Returning facets
See also
Documentation for Returning results, Definition of facet
Supported facetable fields for each source
Simple facets
search grants return funders
Retrieves grant funders sorted by the number (count) of grants each has funded.
Does not retrieve any grant records themselves, only the aggregation over the
funders facet of the grants source.
{
"funders": [
{
"name": "Japan Society for the Promotion of Science",
"acronym": "JSPS",
"country_name": "Japan",
"count": 309610,
"id": "127739"
},
{
"name": "Natural Sciences and Engineering Research Council of Canada",
"acronym": "NSERC",
"country_name": "Canada",
"count": 155666,
"id": "57766"
},
{
"name": "National Natural Science Foundation",
"acronym": "NSFC",
"country_name": "China",
"count": 94643,
"id": "137853"
},
"...more funders here..."
]
}
Fields (metadata)
See also
Documentation for specifying fields, Definitions for entity, field, fieldset
Supported fields/fieldsets for each entity
search grants
return funders[name + acronym + country_name]
return research_orgs[basics]
return research_org_countries[basics]
In addition to computing grant count aggregations for the specified facets, fetches the metadata associated with each entity according to the fields specified, and displays this information alongside the aggregations in the facet results.
{
"research_orgs": [
{
"name": "University of Tokyo",
"acronym": "UT",
"country_name": "Japan",
"count": 23086,
"id": "grid.26999.3d"
},
{
"name": "University of Toronto",
"country_name": "Canada",
"count": 22735,
"id": "grid.17063.33"
},
{
"name": "University of British Columbia",
"acronym": "UBC",
"country_name": "Canada",
"count": 19067,
"id": "grid.17091.3e"
},
"...more organizations here..."
],
"funders": [
{
"name": "Japan Society for the Promotion of Science",
"acronym": "JSPS",
"country_name": "Japan",
"count": 335376,
"id": "grid.54432.34"
},
{
"name": "Natural Sciences and Engineering Research Council of Canada",
"acronym": "NSERC",
"country_name": "Canada",
"count": 155665,
"id": "grid.452912.9"
},
{
"name": "National Natural Science Foundation",
"acronym": "NSFC",
"country_name": "China",
"count": 94643,
"id": "grid.419696.5"
},
"...more funders here..."
],
"research_org_countries": [
{
"name": "United States",
"count": 516027,
"id": "US"
},
{
"name": "Japan",
"count": 331080,
"id": "JP"
},
{
"name": "Canada",
"count": 248156,
"id": "CA"
},
"...more countries here..."
]
}
Facets and records
search grants
return grants[id + title]
return funders
return research_orgs
Retrieves grant documents, as well as funders and research organizations of grants (both sorted by the count of grants funded).
{
"grants": [
{
"title": "Discriminatory Transcriptional Response of Environmental Microorganisms and Microbial Communities to Low-Dose Ionizing Radiation",
"id": "grant.6795027"
},
{
"title": "FunPDBe - Community driven enrichment of PDB data with structural and functional annotations",
"id": "grant.6711354"
},
{
"title": "THE GLOBAL PRECIPITATION MISSION, TROPICAL RAINFALL MEASURING MISSION, AND RELATED SATELLITES HAVE OBSERVED A HUGE NUMBER OF PRECIPITATING SYSTEMS AROUND THE GLOBE. PAIRING HIGH-QUALITY GROUND-BASED RADAR DATA WITH COINCIDENT SATELLITE OBSERVATIONS CAN HE",
"id": "grant.6620299"
},
"...more grants here..."
],
"funders": [
{
"id": "grid.54432.34",
"acronym": "JSPS",
"country_name": "Japan",
"count": 335376,
"name": "Japan Society for the Promotion of Science"
},
{
"id": "grid.452912.9",
"acronym": "NSERC",
"country_name": "Canada",
"count": 155665,
"name": "Natural Sciences and Engineering Research Council of Canada"
},
{
"id": "grid.419696.5",
"acronym": "NSFC",
"country_name": "China",
"count": 94643,
"name": "National Natural Science Foundation"
},
"...more funders here..."
],
"research_orgs": [
{
"count": 23086,
"id": "grid.26999.3d",
"name": "University of Tokyo",
"acronym": "UT",
"country_name": "Japan"
},
{
"count": 22735,
"name": "University of Toronto",
"id": "grid.17063.33",
"country_name": "Canada"
},
{
"count": 19067,
"id": "grid.17091.3e",
"name": "University of British Columbia",
"acronym": "UBC",
"country_name": "Canada"
},
"...more research_orgs here..."
]
}
Aggregations
See also
Documentation for “aggregate”, Definition of indicator
Supported indicators for each source
Single indicator
search grants
return funders
return active_year aggregate funding
Differs from search grants return funders, years only in the fact that in addition to tallying the counts of grants for each funder/year, also computes the total funding amount (the sum of grant funding amounts in USD) for each funder/year, and lists this in the results. However, the funders and years are still sorted by count.
{
"funders": [
{
"id": "grid.54432.34",
"count": 851126,
"acronym": "JSPS",
"name": "Japan Society for the Promotion of Science",
"country_name": "Japan"
},
{
"id": "grid.452912.9",
"count": 263814,
"acronym": "NSERC",
"name": "Natural Sciences and Engineering Research Council",
"country_name": "Canada"
},
"...more funders here..."
],
"active_year": [
{
"id": 2012,
"count": 618634,
"funding": 504408758245.0
},
{
"id": 2011,
"count": 608777,
"funding": 490680695027.0
}
]
}
Multiple indicators
search publications
return funders aggregate rcr_avg, altmetric_median
Returns funders of publications, but in addition to tallying the counts of publications funded by each funder, also computes the average Relative Citation Ratio (RCR) score and median Altmetric Attention Score across all publications funded by that funder, and includes these aggregations in the facet results. However, funders are still sorted by the count of publications funded.
{
"funders": [
{
"count": 872461,
"name": "National Natural Science Foundation",
"rcr_avg": 1.1086178498538546,
"altmetric_median": 0.0,
"acronym": "NSFC",
"country_name": "China",
"id": "grid.419696.5"
},
{
"count": 236845,
"name": "National Cancer Institute",
"rcr_avg": 1.7967137112199267,
"altmetric_median": 2.0,
"acronym": "NCI",
"country_name": "United States",
"id": "grid.48336.3a"
},
{
"count": 180779,
"name": "National Institute of General Medical Sciences",
"rcr_avg": 1.7253180846501697,
"altmetric_median": 2.0,
"acronym": "NIGMS",
"country_name": "United States",
"id": "grid.280785.0"
},
"...more funders here..."
]
}
Sorting
search publications return funders aggregate rcr_avg, altmetric_median sort by rcr_avg
Returns the same results as the previous query, except that now the funders are sorted by their average RCR score (descending) instead of by the default indicator, publication count (though counts are still tallied and included in the results).
{
"funders": [
{
"count": 111,
"name": "Motor Neurone Disease Association",
"rcr_avg": 3.573468110784217,
"altmetric_median": 7.0,
"country_name": "United Kingdom",
"id": "57744"
},
{
"count": 13079,
"name": "National Human Genome Research Institute",
"rcr_avg": 3.328925121266537,
"altmetric_median": 5.0,
"country_name": "United States",
"id": "57944"
},
{
"count": 964,
"name": "Parkinson's UK",
"rcr_avg": 2.908692933904364,
"altmetric_median": 3.0,
"country_name": "United Kingdom",
"id": "57748"
},
"...more facets here..."
]
}
Naming/grouping results
Aliases
See also
Documentation for result aliases
search grants
return grants as "projects"
return funders as "entity_funder"
Retrieves the same results as search grants return grants return funders, but the results are listed under the specified aliases of "projects" and "entity_funder", respectively, instead of the default names "grants" and "funders" .
{
"entity_funder": [
{
"id": "grid.54432.34",
"acronym": "JSPS",
"country_name": "Japan",
"count": 335376,
"name": "Japan Society for the Promotion of Science"
},
{
"id": "grid.452912.9",
"acronym": "NSERC",
"country_name": "Canada",
"count": 155665,
"name": "Natural Sciences and Engineering Research Council of Canada"
},
{
"id": "grid.419696.5",
"acronym": "NSFC",
"country_name": "China",
"count": 94643,
"name": "National Natural Science Foundation"
},
"...more funders here..."
],
"projects": [
{
"project_num": "HDTRA11710002",
"active_year": [
2019,
2020,
2021
],
"title_language": "en",
"funding_org_name": "Defense Threat Reduction Agency",
"start_year": 2019,
"funder": [
{
"acronym": "DTRA",
"country_name": "United States",
"id": "grid.452918.3",
"name": "Defense Threat Reduction Agency"
}
],
"id": "grant.6795027",
"original_title": "Discriminatory Transcriptional Response of Environmental Microorganisms and Microbial Communities to Low-Dose Ionizing Radiation",
"start_date": "2019-11-16T00:00:00Z",
"language": "en",
"title": "Discriminatory Transcriptional Response of Environmental Microorganisms and Microbial Communities to Low-Dose Ionizing Radiation",
"end_date": "2021-11-15T00:00:00Z"
},
"...more grants here..."
]
}
Groups
See also
Documentation for result groups
search grants
return in "docs" grants
return in "facets" funders aggregate funding
return in "facets" research_orgs
return in "facets" research_org_countries
Retrieves the same results as search grants return grants return funders aggregate funding return research_orgs, research_org_countries, but organizes the results into two groups as specified: the docs group, containing grants, and the facets group, containing funders, research_orgs, and research_org_countries.
{
"docs": {
"grants": [
{
"project_num": "HDTRA11710002",
"active_year": [
2019,
2020,
2021
],
"title_language": "en",
"funding_org_name": "Defense Threat Reduction Agency",
"start_year": 2019,
"funders": [
{
"acronym": "DTRA",
"country_name": "United States",
"id": "grid.452918.3",
"name": "Defense Threat Reduction Agency"
}
],
"id": "grant.6795027",
"original_title": "Discriminatory Transcriptional Response of Environmental Microorganisms and Microbial Communities to Low-Dose Ionizing Radiation",
"start_date": "2019-11-16T00:00:00Z",
"language": "en",
"title": "Discriminatory Transcriptional Response of Environmental Microorganisms and Microbial Communities to Low-Dose Ionizing Radiation",
"end_date": "2021-11-15T00:00:00Z"
},
"...more grants here..."
]
},
"facets": {
"funders": [
{
"count": 335376,
"name": "Japan Society for the Promotion of Science",
"acronym": "JSPS",
"country_name": "Japan",
"id": "grid.54432.34",
"funding": 26873150144.0
},
{
"count": 155665,
"name": "Natural Sciences and Engineering Research Council of Canada",
"acronym": "NSERC",
"country_name": "Canada",
"id": "grid.452912.9",
"funding": 9862770465.0
},
{
"count": 94643,
"name": "National Natural Science Foundation",
"acronym": "NSFC",
"country_name": "China",
"id": "grid.419696.5",
"funding": 4965484408.0
},
"...more funders here..."
],
"research_orgs": [
{
"name": "University of Tokyo",
"acronym": "UT",
"country_name": "Japan",
"count": 23086,
"id": "grid.26999.3d"
},
{
"name": "University of Toronto",
"country_name": "Canada",
"count": 22735,
"id": "grid.17063.33"
},
{
"name": "University of British Columbia",
"acronym": "UBC",
"country_name": "Canada",
"count": 19067,
"id": "grid.17091.3e"
},
"...more research_orgs here..."
],
"research_org_countries": [
{
"count": 516027,
"name": "United States",
"id": "US"
},
{
"count": 331080,
"name": "Japan",
"id": "JP"
},
{
"count": 248156,
"name": "Canada",
"id": "CA"
},
"...more research_org_countries here..."
]
}
}
Aliases within Groups
search grants
return in "docs" grants as "projects"
return in "facets" funders as "project_funders" aggregate funding
return in "facets" research_orgs as "project_research_organizations"
Retrieves the same results as search grants return grants return funders aggregate funding return research_orgs, but names and groups the results as specified in the query and illustrated in the results below.
{
"docs": {
"projects": [
{
"active_year": [
2019,
2020,
2021
],
"end_date": "2021-11-15T00:00:00Z",
"funders": [
{
"acronym": "DTRA",
"country_name": "United States",
"name": "Defense Threat Reduction Agency",
"id": "grid.452918.3"
}
],
"funding_org_name": "Defense Threat Reduction Agency",
"id": "grant.6795027",
"language": "en",
"original_title": "Discriminatory Transcriptional Response of Environmental Microorganisms and Microbial Communities to Low-Dose Ionizing Radiation",
"project_num": "HDTRA11710002",
"start_date": "2019-11-16T00:00:00Z",
"start_year": 2019,
"title": "Discriminatory Transcriptional Response of Environmental Microorganisms and Microbial Communities to Low-Dose Ionizing Radiation",
"title_language": "en"
},
"...more grants here..."
]
},
"facets": {
"project_funders": [
{
"count": 335376,
"name": "Japan Society for the Promotion of Science",
"acronym": "JSPS",
"country_name": "Japan",
"id": "grid.54432.34",
"funding": 26873150144.0
},
{
"count": 155665,
"name": "Natural Sciences and Engineering Research Council of Canada",
"acronym": "NSERC",
"country_name": "Canada",
"id": "grid.452912.9",
"funding": 9862770465.0
},
{
"count": 94643,
"name": "National Natural Science Foundation",
"acronym": "NSFC",
"country_name": "China",
"id": "grid.419696.5",
"funding": 4965484408.0
},
"...more funders here..."
],
"project_research_organizations": [
{
"count": 23086,
"country_name": "Japan",
"acronym": "UT",
"name": "University of Tokyo",
"id": "grid.26999.3d"
},
{
"count": 22735,
"country_name": "Canada",
"name": "University of Toronto",
"id": "grid.17063.33"
},
{
"count": 19067,
"country_name": "Canada",
"acronym": "UBC",
"name": "University of British Columbia",
"id": "grid.17091.3e"
},
"...more research_orgs here..."
]
}
}
Limiting/paging results
See also
Documentation for “limit” and “skip”
Limit
search grants for "ALS"
return grants[id + title] limit 5
return funders limit 3
Returns the top 5 grants matching the query, and the top 3 funders for all grants matching the query.
{
"funders": [
{
"name": "German Research Foundation",
"acronym": "DFG",
"country_name": "Germany",
"count": 17189,
"id": "grid.424150.6"
},
{
"name": "Japan Society for the Promotion of Science",
"acronym": "JSPS",
"country_name": "Japan",
"count": 4725,
"id": "grid.54432.34"
},
{
"name": "Ministry of Education, Universities and Research",
"acronym": "MIUR",
"country_name": "Italy",
"count": 3911,
"id": "grid.425707.3"
}
],
"grants": [
{
"title": "Discovery and validation of \u2018epidrivers\u2019 of cancer evolution and resistance to therapy",
"id": "grant.6623351"
},
{
"title": "Nanoparticle-based immunization, a novel therapeutic strategy for amyotrophic lateral sclerosis",
"id": "grant.6621975"
},
{
"title": "Active-site modulation of metal-ligand Coordinated complex electrocatalysts for PEFCs",
"id": "grant.6622198"
},
{
"title": "Reader, Author, Scholar in a Context of Information Overflow.How to master and manage knowledge when there is too much to know?",
"id": "grant.6623223"
},
{
"title": "Humans On Planet Earth - Long-term impacts on biosphere dynamics",
"id": "grant.6814422"
}
]
}
Skip
search grants for "ALS"
return grants[id + title] limit 5 skip 15
return funders limit 3
Like the previous query, returns 5 grants and 3 grant funders. However, whereas the previous query returned the top 5 grants and top 3 funders, this query returns the grants in 16th-20th position in the search results, and the funders in 10th-12th position.
These results might represent page 4 in a series of results pages where 5 grants and 3 funders are listed per page.
{
"funders": [
{
"name": "S\u00e3o Paulo Research Foundation",
"acronym": "FAPESP",
"country_name": "Brazil",
"count": 711,
"id": "grid.452907.d"
},
{
"name": "Natural Sciences and Engineering Research Council of Canada",
"acronym": "NSERC",
"country_name": "Canada",
"count": 710,
"id": "grid.452912.9"
},
{
"name": "National Council for Scientific and Technological Development",
"acronym": "CNPq",
"country_name": "Brazil",
"count": 706,
"id": "grid.450640.3"
}
],
"grants": [
{
"title": "The Media and Mispricing: Disseminating Misinformation by Business Press",
"id": "grant.6860432"
},
{
"title": "On the diminishing timing role of Accruals: a Revisit",
"id": "grant.6860435"
},
{
"title": "Developing urban planning optimization strategies for improving air quality in compact cities using geo-spatial modelling based on in-situ data",
"id": "grant.6860498"
},
{
"title": "Critical Audit Matter Disclosure",
"id": "grant.6860546"
},
{
"title": "Do Managerial Incentives Matter? Evidence from SOE Pay-Cap Reforms in China",
"id": "grant.6860551"
}
]
}
Indicators Aggregations
This section provides various examples of how to extract common performance indicators using the Dimensions API.
Note
In the following examples, publications are aggregated by funder, however this is just for demonstrative purposes. It is also possible to aggregate by any other facet field. For a complete list of fields that support facets, see the Data Sources.
See also
Documentation for “aggregate”, Definition of indicator
Supported indicators for each source
Publications Output
Aggregated number of publications per entity
search publications
return funders aggregate count
Citations
Number of citations per publication
search publications
return publications [doi + times_cited]
sort by times_cited
Aggregated total number of citations
search publications
return funders aggregate citations_total
sort by citations_total
Arithmetic mean number of citations
search publications
return funders aggregate citations_avg
sort by citations_avg
Median number of citations
search publications
return funders aggregate citations_median
sort by citations_median
Recent citations per publication
search publications
return publications [doi + recent_citations]
sort by recent_citations
Note
Recent citation refers to the number of citations accrued in the last two year period. A single value is stored per document and the year window rolls over in July.
Aggregated number of recent citations
search publications
return funders aggregate recent_citations_total
sort by recent_citations_total
Relative citation ratio (RCR) per publication
search publications
return publications [doi + relative_citation_ratio]
sort by relative_citation_ratio
Arithmetic mean of RCR
search publications
return funders aggregate rcr_avg
sort by rcr_avg
Field citation ratio (FCR) per publication
search publications
return publications [doi + field_citation_ratio]
sort by field_citation_ratio
Geometric mean of FCR
search publications
return funders aggregate fcr_gavg
sort by fcr_gavg
Number of publications with at least n=X citations, in the example below n=10
search publications
where times_cited >= 10
return funders
Altmetric
Altmetric Attention Score per publication
search publications
return publications [doi + altmetric]
sort by altmetric
Median Altmetric Attention Score
search publications
return funders aggregate altmetric_median
sort by altmetric_median
Arithmetic mean Altmetric Attention Score
search publications
return funders aggregate altmetric_avg
sort by altmetric_avg
Collaboration Indicators
Number of publications with exactly one researcher.
search publications
where count(researchers) = 1
return funders
Number of publications with more than one researcher.
search publications
where count(researchers) > 1
return funders
International collaborations: number of publications with more than one author and affiliations located in more than one country.
search publications
where count(researchers) > 1
and count(research_org_countries) > 1
return funders
Domestic collaborations: number of publications with more than one author and more than one affiliation located in exactly one country.
search publications
where count(researchers) > 1
and count(research_org_countries) = 1
return funders
Hyper-authorship: number of publications with at least n=X authors, in the example below the number of authors is n=25
search publications
where count(researchers) >= 25
return funders
Open Access Indicators
All OA: a free version of the publication is available (publication is either Gold, Hybrid, Bronze or Green OA).
search publications
where open_access= "oa_all"
return funders
Gold: publication is published in a fully open access journal (this includes all publications with a Gold OA status in Unpaywall and those on our own fully OA list of journals).
search publications
where open_access= "gold"
return funders
Hybrid: publication freely available under an open licence in a paid-access journal (Unpaywall OA status = Hybrid).
search publications
where open_access= "hybrid"
return funders
Bronze: publication freely available on publisher’s website, but without an open licence (Unpaywall OA status = Bronze).
search publications
where open_access= "bronze"
return funders
Green: publication freely available in an OA repository (Unpaywall OA status = Green, or publication type in Dimensions = Preprint).
search publications
where open_access= "green"
return funders
Closed: freely available version has been identified (publication is neither Gold, Hybrid, Bronze nor Green OA).
search publications
where open_access= "closed"
return funders
Calculating composite indicators
The following examples showcase how different individual indicators can be combined to obtain further insight into the Dimensions data.
Note
These examples reflect the data at specific time point. Therefore we would expect the calculated values from the following queries to change over time, as the coverage of Dimensions data increases.
Calculating percentage of open access papers for a specific funder
In this example we first search for all publications funded by the National Cancer Institute (NCI) and filter for a specific type of open access. In this case we are selecting documents that have a version of the record that is free under an open licence from a full OA, also known as Gold Open Access.
search publications
where open_access = "gold" and funders.name="National Cancer Institute"
return publications
From looking at the stats component of the returned data, we can see that there are 35858 documents that match this query. After that we need to determine what is the total publication output for the funder.
search publications
where funders.name="National Cancer Institute"
return publications
From the query above we get that there are 531281 publications associated with funding from the NCI. Finally by simply calculating the ratio between open access publications and all publications, we can conclude that 6.75% of the publications funded by the NCI are Gold Open Access.
Calculating publications per active grant for specific fields of research
The ratio of publications to active grants can provide insights across different disciplines and shed light on aspects obscured by funding amounts. To calculate this, it is necessary to perform a couple of queries and then manually calculate the ratio.
For the sake of simplicity, let us look into a 3 year funding period (2015-2017) for Monash University in Australia (grid.1002.3). Taking advantage of the fields of research categorisation system (FOR) we can line up specific fields of study across both publications and grants.
First, we search for all Monash University publications aggregated by field of research and published after the first active year of grant funding:
search publications
where research_orgs.id = "grid.1002.3" and year>=2015
return FOR
Next, we can select a couple of categories and store their publication output. After that we perform a similar search on those categories, but this time across grant content.
search grants
where research_orgs.id = "grid.1002.3"
and active_year in [2015:2017]
and FOR.name="1701 Psychology"
return active_year
As you can see from the query, we are looking at grants that were active between 2015 and 2017 for the same university in the field of psychology. The same can be done for another research area like pharmacology.
search grants
where research_orgs.id = "grid.1002.3"
and active_year in [2015:2017]
and FOR.name="1115 Pharmacology and Pharmaceutical Sciences"
return active_year
Based on these three queries we find that the number of grants for psychology and pharmacology are 193 and 148 respectively. However there is a significant difference in the number of publications, as we get 1896 for psychology and only 277 for pharmacology. Finally by calculating the ratio between grants and publication we can see in this case, that research in psychology produces approximately 5 times as many publications as its pharmacological counterpart.