> Searlo API Docs — Scholar & Patents
> Source: https://searlo.tech/docs#scholar-patents
> Full docs: https://searlo.tech/docs/full.md

# Scholar & Patents

Google Scholar and Google Patents results. Both use the same `organic` array as web results, with the scholarly or patent fields alongside.

### Endpoints

```
GET /search/scholar
GET /search/patents
```

**Credits:** 1 per request

### Scholar Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `q` | string | Yes, unless `cluster` or `cites` is set | Search query (1–500 chars) |
| `limit` | number | No | Results (1–20, default: 10) |
| `page` | number | No | Page number (1–100, default: 1) |
| `hl` | string | No | Language code, max 5 chars |
| `yearFrom` | number | No | Earliest publication year (1500–2200) |
| `yearTo` | number | No | Latest publication year (1500–2200) |
| `sortByDate` | boolean | No | Sort by date instead of relevance |
| `includePatents` | boolean | No | Include patents in the results (has no effect when `includeCitations` is `false`) |
| `includeCitations` | boolean | No | Include Scholar's citation-only records (included by default); `false` leaves them out |
| `cluster` | string | No | A `clusterId` from a result (digits, max 32): every version of that work |
| `cites` | string | No | A `citesId` from a result (digits, max 32): the works that cite it |

### Scholar Response

```json
{
  "searchParameters": { "q": "transformer attention", "type": "scholar", "hl": "en", "num": 10, "page": 1, "yearFrom": 2020 },
  "page": 1,
  "totalResults": 128000,
  "hasNextPage": true,
  "organic": [
    {
      "position": 1,
      "title": "An example study of attention mechanisms",
      "link": "https://arxiv.org/abs/2001.00001",
      "snippet": "We study how attention...",
      "domain": "arxiv.org",
      "authors": ["A Author", "B Author"],
      "year": 2021,
      "publication": "arXiv preprint",
      "type": "PDF",
      "citedBy": 1520,
      "citedByLink": "https://scholar.google.com/scholar?cites=2960712678066186980",
      "pdfLink": "https://arxiv.org/pdf/2001.00001",
      "resultId": "u8Yx3kZ1abcJ",
      "citesId": "2960712678066186980",
      "clusterId": "2960712678066186980"
    }
  ],
  "source": "searlo.tech(google_scholar)",
  "credits": 1
}
```

- `citesId` and `clusterId` come back on every result. Pass one back as `cites` or `cluster` to walk the citation graph.
- `totalResults` is Scholar's own estimate for the whole query, not the page size.
- `type` is Scholar's tag for the result (`BOOK`, `PDF`, `HTML`, `CITATION`) or `null`.
- A query with no results returns `200` with an empty `organic` array.

### Patents Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `q` | string | Yes | Search query (1–500 chars) |
| `limit` | number | No | Results (1–100, default: 10). Google Patents serves pages of 10, 25, 50 or 100; other values round down to one of those, and anything under 10 fetches 10 |
| `page` | number | No | Page number (1–100, default: 1) |
| `sort` | string | No | `new` or `old`; relevance when omitted |
| `country` | string | No | Issuing authority, max 40 chars, e.g. `US` or `US,EP` |
| `language` | string | No | Publication language, max 20 chars (sent upper-cased) |
| `status` | string | No | `GRANT` or `APPLICATION` |
| `type` | string | No | `PATENT` or `DESIGN` |
| `inventor` | string | No | Inventor name, max 120 chars |
| `assignee` | string | No | Assignee name, max 120 chars |
| `before` | string | No | Upper date bound: `priority:YYYYMMDD`, `filing:YYYYMMDD` or `publication:YYYYMMDD` |
| `after` | string | No | Lower date bound, same format as `before` |

### Patents Response

```json
{
  "searchParameters": { "q": "solid state battery", "type": "patents", "num": 10, "page": 1 },
  "page": 1,
  "totalResults": 23000,
  "totalPages": 100,
  "hasNextPage": true,
  "organic": [
    {
      "position": 1,
      "title": "Solid-state battery with an example electrolyte",
      "link": "https://patents.google.com/patent/US11000000B2/en",
      "snippet": "A solid-state battery comprising...",
      "patentId": "patent/US11000000B2/en",
      "publicationNumber": "US11000000B2",
      "inventor": "Jane Inventor",
      "assignee": "Example Corp",
      "priorityDate": "2019-05-14",
      "filingDate": "2020-05-12",
      "grantDate": "2021-05-11",
      "publicationDate": "2021-05-11",
      "language": "en",
      "pdfLink": "https://patentimages.storage.googleapis.com/.../US11000000.pdf",
      "thumbnailUrl": "https://patentimages.storage.googleapis.com/...",
      "figures": [
        { "thumbnail": "https://patentimages.storage.googleapis.com/...", "full": "https://patentimages.storage.googleapis.com/..." }
      ]
    }
  ],
  "source": "searlo.tech(google_patents)",
  "credits": 1
}
```

- `totalPages` and `hasNextPage` come from Google Patents' own counts.
- `figures` lists the drawings, each as a `thumbnail` and a `full` image URL.
- A query with no results returns `200` with an empty `organic` array.

## Code Examples

### cURL

```bash
# Papers since 2020
curl "https://api.searlo.tech/api/v1/search/scholar?q=transformer+attention&yearFrom=2020&limit=10" \
  -H "x-api-key: sk_your_api_key"

# The works citing one paper (citesId from a previous result)
curl "https://api.searlo.tech/api/v1/search/scholar?cites=2960712678066186980" \
  -H "x-api-key: sk_your_api_key"

# Granted patents for an assignee, priority date from 2020
curl "https://api.searlo.tech/api/v1/search/patents?q=solid+state+battery&assignee=Example+Corp&status=GRANT&after=priority:20200101&limit=25" \
  -H "x-api-key: sk_your_api_key"
```

### JavaScript

```javascript
const API = "https://api.searlo.tech/api/v1";
const headers = { "x-api-key": process.env.SEARLO_API_KEY };

async function scholar(params) {
  const res = await fetch(`${API}/search/scholar?${new URLSearchParams(params)}`, { headers });
  return res.json();
}

// Find a paper, then walk to the works that cite it
const found = await scholar({ q: "transformer attention", yearFrom: "2020" });
const paper = found.organic[0];
console.log(paper.title, paper.year, paper.citedBy, paper.pdfLink);

const citing = await scholar({ cites: paper.citesId, limit: "20" });
citing.organic.forEach(r => console.log(r.year, r.title));
```

### Python

```python
import os
import requests

res = requests.get(
    "https://api.searlo.tech/api/v1/search/patents",
    params={
        "q": "solid state battery",
        "status": "GRANT",
        "country": "US",
        "after": "priority:20200101",
        "sort": "new",
        "limit": 25,
    },
    headers={"x-api-key": os.environ["SEARLO_API_KEY"]},
)
data = res.json()
print(data["totalResults"], "results,", data["totalPages"], "pages")
for p in data["organic"]:
    print(p["publicationNumber"], p["assignee"], p["priorityDate"], p["title"])
```


---
*From https://searlo.tech/docs — see full docs at https://searlo.tech/docs/full.md*