# aggregateScholarlyWorks

**Identifier:** `lens_aggregateScholarlyWorks`

**Provider:** [Lens](https://kirha.com/providers/lens.md)

Run statistical aggregations over scholarly works matching a query or filters: publications per year, top authors, institutions, journals, publishers, funders, fields of study, countries, MeSH terms, open access and publication type breakdowns, and citation metrics including patent citations. Use for research landscape and science-to-patent impact analysis; pair with aggregatePatents for the patent side.

## Run it with the CLI

```bash
kirha tools run lens_aggregateScholarlyWorks \
  --input '{
    "aggregationType": "by_year"
  }'
```

`--input` takes a JSON object that matches the input schema. Pass `--input -` to read it from stdin.

## Call it over HTTP

```bash
curl https://api.kirha.com/tools/v1/execute \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: **********' \
  --data '{
  "tool_name": "lens_aggregateScholarlyWorks",
  "input": {
    "aggregationType": "by_year"
  }
}'
```

Replace the stars with an API key from https://app.kirha.com/api-keys.

## Input schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "aggregationSize": {
      "default": 10,
      "description": "Number of top buckets",
      "maximum": 100,
      "minimum": 1,
      "type": "number"
    },
    "aggregationType": {
      "enum": [
        "by_year",
        "top_authors",
        "top_institutions",
        "top_journals",
        "top_publishers",
        "top_funders",
        "by_field_of_study",
        "by_country",
        "by_open_access",
        "by_publication_type",
        "by_mesh_term",
        "by_year_and_open_access",
        "by_year_and_publication_type",
        "citation_metrics"
      ],
      "type": "string"
    },
    "author": {
      "description": "e.g., Jennifer Doudna",
      "type": "string"
    },
    "citedByPatents": {
      "type": "boolean"
    },
    "clinicalTrialId": {
      "description": "e.g., NCT00105716",
      "type": "string"
    },
    "country": {
      "description": "Author affiliation country, ISO alpha-2, e.g., US, FR",
      "type": "string"
    },
    "fieldOfStudy": {
      "description": "e.g., Immunology, Machine learning",
      "type": "string"
    },
    "funder": {
      "description": "e.g., National Institutes of Health, European Research Council",
      "type": "string"
    },
    "institution": {
      "description": "e.g., Harvard University",
      "type": "string"
    },
    "journal": {
      "description": "e.g., Nature Communications",
      "type": "string"
    },
    "meshTerm": {
      "description": "Case-sensitive MeSH heading, e.g., Neoplasms",
      "type": "string"
    },
    "openAccess": {
      "type": "boolean"
    },
    "publicationType": {
      "enum": [
        "journal_article",
        "review",
        "preprint",
        "conference_proceedings_article",
        "conference_proceedings",
        "book",
        "book_chapter",
        "dissertation",
        "dataset",
        "report",
        "letter",
        "editorial",
        "clinical_trial",
        "clinical_study",
        "working_paper",
        "standard",
        "other"
      ],
      "type": "string"
    },
    "publisher": {
      "description": "e.g., Elsevier",
      "type": "string"
    },
    "query": {
      "description": "Keywords searched in title, abstract and full text, e.g., CRISPR base editing",
      "type": "string"
    },
    "retracted": {
      "type": "boolean"
    },
    "rorId": {
      "description": "Institution ROR ID, e.g., 01an7q238",
      "type": "string"
    },
    "yearFrom": {
      "maximum": 2100,
      "minimum": 1800,
      "type": "number"
    },
    "yearTo": {
      "maximum": 2100,
      "minimum": 1800,
      "type": "number"
    }
  },
  "required": [
    "aggregationType"
  ],
  "type": "object"
}
```

## Output schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "properties": {
    "aggregationType": {
      "enum": [
        "by_year",
        "top_authors",
        "top_institutions",
        "top_journals",
        "top_publishers",
        "top_funders",
        "by_field_of_study",
        "by_country",
        "by_open_access",
        "by_publication_type",
        "by_mesh_term",
        "by_year_and_open_access",
        "by_year_and_publication_type",
        "citation_metrics"
      ],
      "type": "string"
    },
    "buckets": {
      "items": {
        "additionalProperties": false,
        "properties": {
          "count": {
            "type": "number"
          },
          "key": {
            "type": "string"
          },
          "subBuckets": {
            "items": {
              "additionalProperties": false,
              "properties": {
                "count": {
                  "type": "number"
                },
                "key": {
                  "type": "string"
                }
              },
              "required": [
                "key",
                "count"
              ],
              "type": "object"
            },
            "type": "array"
          }
        },
        "required": [
          "key",
          "count"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "context": {
      "type": "string"
    },
    "metrics": {
      "additionalProperties": false,
      "properties": {
        "avgScholarlyCitations": {
          "type": "number"
        },
        "totalPatentCitations": {
          "type": "number"
        },
        "totalScholarlyCitations": {
          "type": "number"
        },
        "worksCitedByPatents": {
          "type": "number"
        }
      },
      "type": "object"
    },
    "total": {
      "type": "number"
    }
  },
  "required": [
    "context",
    "total",
    "aggregationType"
  ],
  "type": "object"
}
```

## Related tools

Other Lens tools that this tool refers to, or that refer to it.

- [`aggregatePatents`](https://kirha.com/providers/lens/aggregatePatents.md)

-----

[All Lens tools](https://kirha.com/providers/lens.md) · [< Back to tools list](https://kirha.com/tools.md)