# searchScholarlyWorks

**Identifier:** `lens_searchScholarlyWorks`

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

Search scholarly works (articles, preprints, books, conference papers) on Lens with full-text queries and filters for author, institution, journal, funder, field of study, MeSH term, year, open access, retraction and patent citation status. Also supports batch lookup by Lens IDs, DOIs or PMIDs, e.g., the citedScholarlyLensIds returned by getPatent. Use getScholarlyWork for the full record and getScholarlyCitations for citation links.

## Run it with the CLI

```bash
kirha tools run lens_searchScholarlyWorks \
  --input '{}'
```

`--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_searchScholarlyWorks",
  "input": {}
}'
```

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": {
    "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"
    },
    "dois": {
      "description": "Batch lookup by DOI. Ignores other filters.",
      "items": {
        "type": "string"
      },
      "maxItems": 25,
      "type": "array"
    },
    "fieldOfStudy": {
      "description": "e.g., Immunology, Machine learning",
      "type": "string"
    },
    "from": {
      "default": 0,
      "maximum": 9999,
      "minimum": 0,
      "type": "number"
    },
    "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"
    },
    "lensIds": {
      "description": "Batch lookup by scholarly Lens IDs, e.g., from getPatent citedScholarlyLensIds. Ignores other filters.",
      "items": {
        "type": "string"
      },
      "maxItems": 25,
      "type": "array"
    },
    "meshTerm": {
      "description": "Case-sensitive MeSH heading, e.g., Neoplasms",
      "type": "string"
    },
    "openAccess": {
      "type": "boolean"
    },
    "pmids": {
      "description": "Batch lookup by PubMed ID. Ignores other filters.",
      "items": {
        "type": "string"
      },
      "maxItems": 25,
      "type": "array"
    },
    "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"
    },
    "size": {
      "default": 10,
      "maximum": 20,
      "minimum": 1,
      "type": "number"
    },
    "sort": {
      "default": "relevance",
      "enum": [
        "relevance",
        "date_desc",
        "date_asc",
        "citations_desc"
      ],
      "type": "string"
    },
    "yearFrom": {
      "maximum": 2100,
      "minimum": 1800,
      "type": "number"
    },
    "yearTo": {
      "maximum": 2100,
      "minimum": 1800,
      "type": "number"
    }
  },
  "type": "object"
}
```

## Output schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "properties": {
    "context": {
      "type": "string"
    },
    "lensIds": {
      "description": "Scholarly Lens IDs for getScholarlyWork, getScholarlyCitations or searchScholarlyWorks lensIds",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "total": {
      "type": "number"
    },
    "works": {
      "items": {
        "additionalProperties": false,
        "properties": {
          "abstract": {
            "type": "string"
          },
          "authorCount": {
            "type": "number"
          },
          "authors": {
            "description": "First 100",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "citationCount": {
            "description": "Scholarly works citing this one",
            "type": "number"
          },
          "datePublished": {
            "type": "string"
          },
          "doi": {
            "type": "string"
          },
          "fieldsOfStudy": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "journal": {
            "type": "string"
          },
          "lensId": {
            "type": "string"
          },
          "openAccessColour": {
            "type": "string"
          },
          "patentCitationCount": {
            "description": "Patents citing this work",
            "type": "number"
          },
          "pmid": {
            "type": "string"
          },
          "publicationType": {
            "type": "string"
          },
          "publisher": {
            "type": "string"
          },
          "title": {
            "type": "string"
          }
        },
        "required": [
          "lensId"
        ],
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "context",
    "total",
    "works",
    "lensIds"
  ],
  "type": "object"
}
```

## Related tools

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

- [`searchPatents`](https://kirha.com/providers/lens/searchPatents.md)
- [`getPatentCitations`](https://kirha.com/providers/lens/getPatentCitations.md)
- [`getScholarlyWork`](https://kirha.com/providers/lens/getScholarlyWork.md)
- [`getPatent`](https://kirha.com/providers/lens/getPatent.md)
- [`aggregatePatents`](https://kirha.com/providers/lens/aggregatePatents.md)
- [`getScholarlyCitations`](https://kirha.com/providers/lens/getScholarlyCitations.md)

-----

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