Example queries and results

The following are examples of valid DSL queries, and the type of results they retrieve from the DSL.

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 works

See also

Definitions of work and source

Search terms

See also

Documentation for “for”, Definition of search terms

search publications for "AIDS" return publications

See also

Documentation for “in”, Definition of full data, title abstract only and title only

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 works 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 works 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 works by similarity with the search terms.

{
  "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 works

See also

Documentation for Returning results, Definition of work

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..."
  ]
}

All

See also

Documentation for fields all, Definitions of work, record

Supported fields for each source

search grants for "malaria" return grants[all]

all may be used in the fields specification to include every available field for the given source, instead of a predefined or manually specified subset of fields.

{
  "grants": [
    {
      "HRCS_RAC": [
        {
          "id": "10304",
          "name": "3.4 Vaccines"
        },
        {
          "id": "10804",
          "name": "8.4 Research design and methodologies"
        }
      ],
      "active_year": [
        2017,
        2018,
        2019,
        2020,
        2021
      ],
      "HRCS_HC": [
        {
          "id": "898",
          "name": "Infection"
        }
      ],
      "funding_org_acronym": "SNF",
      "funding_org_name": "Swiss National Science Foundation",
      "score": 1.1429385,
      "funder_country": [
        "CH"
      ],
      "id": "grant.6918131",
      "original_title": "Multi-scale mathematical modelling of parasite, drug and vaccine interactions: optimising public health and disease elimination\u00a0strategies",
      "funding_amount": 1499495.0,
      "funding_org_city": "Berne",
      "research_org_country": [
        "CH"
      ],
      "RCDC": [
        {
          "id": "583",
          "name": "Vaccine Related"
        },
        {
          "id": "338",
          "name": "Biotechnology"
        },
        {
          "id": "533",
          "name": "Infectious Diseases"
        },
        {
          "id": "457",
          "name": "Malaria"
        },
        {
          "id": "531",
          "name": "Immunization"
        },
        {
          "id": "559",
          "name": "Rare Diseases"
        },
        {
          "id": "558",
          "name": "Prevention"
        },
        {
          "id": "427",
          "name": "Vector-Borne Diseases"
        }
      ],
      "start_date": "2017-07-01T00:00:00Z",
      "start_year": 2017,
      "health_research_areas": [
        {
          "id": "3900",
          "name": "Biomedical"
        }
      ],
      "project_num": "170702",
      "linkout": "http://p3.snf.ch/project-170702",
      "broad_research_areas": [
        {
          "id": "4003",
          "name": "Public Health"
        }
      ],
      "title_language": "en",
      "language": "en",
      "research_org_name": "Universit\u00e4t Basel",
      "funders": [
        {
          "acronym": "SNF",
          "country_name": "Switzerland",
          "id": "grid.425888.b",
          "name": "Swiss National Science Foundation"
        }
      ],
      "FOR": [
        {
          "id": "2344",
          "name": "0102 Applied Mathematics"
        },
        {
          "id": "3114",
          "name": "1108 Medical Microbiology"
        }
      ],
      "research_org_city": [
        "2661604"
      ],
      "research_org_state_code": [
        "CH-BS"
      ],
      "research_orgs": [
        {
          "country_name": "Switzerland",
          "id": "grid.6612.3",
          "name": "University of Basel"
        }
      ],
      "end_date": "2021-06-30T00:00:00Z",
      "date": "2017-07-01T00:00:00Z",
      "funding_org_country_name": "Switzerland",
      "title": "Multi-scale mathematical modelling of parasite, drug and vaccine interactions: optimising public health and disease elimination\u00a0strategies",
      "year": 2017
    },
    "...more grants here..."
  ]
}

Sorting

See also

Documentation for “sort by”, Definition of field

Supported fields for each source

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[all]

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 works

See also

Definitions of work, source, facet

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 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

See also

Documentation for “sort by”, Definition of indicator

Supported indicators for each source

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"
    }
  ]
}