### Install Documentation Dependencies

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/contributing.md

Install the necessary Python packages for building the documentation using pip.

```console
pip install -r docs-requirements.txt
```

--------------------------------

### Install Development Version from GitHub

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/install.md

Clone the repository and install the library locally for development purposes. This installs the latest code directly from the master branch.

```bash
git clone git@github.com:danielnsilva/semanticscholar.git
cd semanticscholar
pip install .
```

--------------------------------

### Install and Build Project

Source: https://github.com/danielnsilva/semanticscholar/blob/master/AGENTS.md

Installs project dependencies, test requirements, and the package in editable mode. Runs unit tests.

```bash
pip install -r requirements.txt \
  && pip install -r test-requirements.txt \
  && pip install -e .
python -m unittest
```

--------------------------------

### Install Test Dependencies

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/contributing.md

Install the necessary dependencies for running tests. This command should be run before executing any test commands.

```console
pip install -r test-requirements.txt
```

--------------------------------

### Get Recommended Papers

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/usage.md

Shows how to retrieve recommended papers based on a single paper ID or a list of positive and negative paper examples.

```APIDOC
## Get Recommended Papers

Retrieve papers recommended based on a given paper or lists of example papers.

### By Paper ID

Get recommendations for a specific paper.

```python
from semanticscholar import SemanticScholar
sch = SemanticScholar()
results = sch.get_recommended_papers('10.2139/ssrn.2250500')
```

### By Paper Lists

Get recommendations based on positive and optionally negative paper ID examples.

```python
from semanticscholar import SemanticScholar
sch = SemanticScholar()
positive_paper_ids = ['10.1145/3544585.3544600']
negative_paper_ids = ['10.1145/301250.301271']

# With both positive and negative lists
results_both = sch.get_recommended_papers_from_lists(positive_paper_ids, negative_paper_ids)

# With only positive list
results_positive = sch.get_recommended_papers_from_lists(positive_paper_ids)
```
```

--------------------------------

### Example Output of Paper Title

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/overview.md

This is the expected output when printing the title of the paper fetched in the previous example.

```text
Computing Machinery and Intelligence
```

--------------------------------

### Install Development Version via Pip VCS Support

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/install.md

Install the latest development version directly from GitHub using pip's version control system (VCS) support. This is an alternative to cloning the repository.

```bash
pip install git+https://github.com/danielnsilva/semanticscholar@master
```

--------------------------------

### Install Latest Release with Pip

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/install.md

Use this command to install the most recent stable version of the Semantic Scholar library from PyPI.

```bash
pip install semanticscholar
```

--------------------------------

### Get Recommended Papers from Positive List Only

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/usage.md

Retrieves recommended papers based solely on a list of positive paper IDs, omitting negative examples. Requires importing SemanticScholar.

```python
from semanticscholar import SemanticScholar
sch = SemanticScholar()
positive_paper_ids = ['10.1145/3544585.3544600']
negative_paper_ids = []
results = sch.get_recommended_papers_from_lists(positive_paper_ids, negative_paper_ids)
```

--------------------------------

### Get Paper Data

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/usage.md

Example of initializing the SemanticScholar class to retrieve paper data using its ID.

```python
from semanticscholar import SemanticScholar
sch = SemanticScholar()
paper = sch.get_paper('10.1093/mind/lix.236.433')
```

--------------------------------

### GET /datasets/v1/release/

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/api.md

Fetches a list of all available dataset releases. This is useful for discovering which versions of datasets are accessible.

```APIDOC
## GET /datasets/v1/release/

### Description
Fetches a list of all available dataset releases. This is useful for discovering which versions of datasets are accessible.

### Method
GET

### Endpoint
/datasets/v1/release/

### Response
#### Success Response (200)
- **releases** (array) - A list of available release objects.
```

--------------------------------

### GET /datasets/v1/release/{release_id}/dataset/{dataset_name}

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/api.md

Gets download links for a specific dataset within a given release. Allows users to obtain URLs to download dataset files.

```APIDOC
## GET /datasets/v1/release/{release_id}/dataset/{dataset_name}

### Description
Gets download links for a specific dataset within a given release. Allows users to obtain URLs to download dataset files.

### Method
GET

### Endpoint
/datasets/v1/release/{release_id}/dataset/{dataset_name}

### Parameters
#### Path Parameters
- **release_id** (string) - Required - The ID of the release.
- **dataset_name** (string) - Required - The name of the dataset.

### Response
#### Success Response (200)
- **download_links** (object) - An object containing download links for the dataset.
```

--------------------------------

### Example Debug Output (HTTP Request)

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/usage.md

Illustrates the debug output format, showing the HTTP request details including the method, URL, headers, payload, and the equivalent cURL command.

```default
DEBUG:semanticscholar:HTTP Request: POST https://api.semanticscholar.org/graph/v1/paper/batch?fields=title,year
DEBUG:semanticscholar:Headers: {'x-api-key': 'F@k3K3y'}
DEBUG:semanticscholar:Payload: {'ids': ['CorpusId:470667', '10.2139/ssrn.2250500', '0f40b1f08821e22e859c6050916cec3667778613']}
DEBUG:semanticscholar:cURL command: curl -X POST -H 'x-api-key: F@k3K3y' -d '{"ids": ["CorpusId:470667", "10.2139/ssrn.2250500", "0f40b1f08821e22e859c6050916cec3667778613"]}' https://api.semanticscholar.org/graph/v1/paper/batch?fields=title,year
```

--------------------------------

### Get Dataset Diffs

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/usage.md

Fetches file URLs for incremental updates between two dataset releases. Requires authentication. The library does not support updating local datasets directly; refer to official documentation for Spark examples.

```python
from semanticscholar import SemanticScholar
sch = SemanticScholar()
diffs = sch.get_dataset_diffs('papers', '2023-12-01', '2024-01-01')

print(f"Number of incremental updates: {len(diffs.diffs)}")

# Examine the first diff
first_diff = diffs.diffs[0]
print(f"First update: {first_diff.from_release} -> {first_diff.to_release}")
print(f"Update files: {len(first_diff.update_files)}")
print(f"Delete files: {len(first_diff.delete_files)}")
```

--------------------------------

### Get Autocomplete Suggestions

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/usage.md

Use the `get_autocomplete` method to obtain suggestions for paper queries based on a partial input string.

```python
from semanticscholar import SemanticScholar
sch = SemanticScholar()
suggestions = sch.get_autocomplete('softw')
```

--------------------------------

### GET /graph/v1/paper/autocomplete?query={query}

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/api.md

Provides autocomplete suggestions for paper searches. Helps users complete their search queries efficiently.

```APIDOC
## GET /graph/v1/paper/autocomplete?query={query}

### Description
Provides autocomplete suggestions for paper searches. Helps users complete their search queries efficiently.

### Method
GET

### Endpoint
/graph/v1/paper/autocomplete

### Parameters
#### Query Parameters
- **query** (string) - Required - The search query for autocomplete suggestions.

### Response
#### Success Response (200)
- **suggestions** (array) - A list of autocomplete suggestions.
```

--------------------------------

### Get Dataset Download Links

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/usage.md

Retrieves download links for a specific dataset within a given release. This endpoint requires authentication with a valid API key. Requires importing SemanticScholar.

```python
from semanticscholar import SemanticScholar
sch = SemanticScholar()
dataset = sch.get_dataset_download_links('2025-08-19', 'papers')

print(f"Dataset: {dataset.name}")
print(f"Description: {dataset.description}")
print(f"Number of files: {len(dataset.files)}")

# Print first few download URLs
for i, file_url in enumerate(dataset.files[:3]):
    print(f"File {i+1}: {file_url}")
```

--------------------------------

### Get Recommended Papers from Positive and Negative Lists

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/usage.md

Retrieves recommended papers based on provided lists of positive and negative paper IDs. Requires importing SemanticScholar.

```python
from semanticscholar import SemanticScholar
sch = SemanticScholar()
positive_paper_ids = ['10.1145/3544585.3544600']
negative_paper_ids = ['10.1145/301250.301271']
results = sch.get_recommended_papers_from_lists(positive_paper_ids, negative_paper_ids)
```

--------------------------------

### GET /datasets/v1/release/{release_id}

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/api.md

Retrieves details for a specific dataset release by its ID. Provides information about a particular version of the datasets.

```APIDOC
## GET /datasets/v1/release/{release_id}

### Description
Retrieves details for a specific dataset release by its ID. Provides information about a particular version of the datasets.

### Method
GET

### Endpoint
/datasets/v1/release/{release_id}

### Parameters
#### Path Parameters
- **release_id** (string) - Required - The ID of the release to retrieve details for.

### Response
#### Success Response (200)
- **release_details** (object) - An object containing the details of the specified release.
```

--------------------------------

### Datasets API - Get Dataset Download Links

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/usage.md

Fetches download links for a specific dataset within a release. Requires authentication.

```APIDOC
## Datasets API - Get Dataset Download Links

Retrieve download links for a specific dataset in a release. This endpoint requires authentication.

### Parameters

- `release_id` (str): The identifier of the release (e.g., '2025-08-19').
- `dataset_name` (str): The name of the dataset (e.g., 'papers').

### Example Usage

```python
from semanticscholar import SemanticScholar
sch = SemanticScholar()
# Authentication is required for this endpoint
dataset_info = sch.get_dataset_download_links('2025-08-19', 'papers')

print(f"Dataset: {dataset_info.name}")
print(f"Description: {dataset_info.description}")
print(f"Number of files: {len(dataset_info.files)}")

for i, file_url in enumerate(dataset_info.files[:3]):
    print(f"File {i+1}: {file_url}")
```
```

--------------------------------

### Example cURL Command for API Interaction

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/usage.md

A cURL command generated from debug output, allowing direct interaction with the Semantic Scholar API for testing and validation purposes. It includes the HTTP method, headers, and payload.

```default
curl -X POST -H 'x-api-key: F@k3K3y' -d '{"ids": ["CorpusId:470667", "10.2139/ssrn.2250500", "0f40b1f08821e22e859c6050916cec3667778613"]}' https://api.semanticscholar.org/graph/v1/paper/batch?fields=title,year
```

--------------------------------

### Get Specific Dataset Release Information

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/usage.md

Retrieves detailed information about a specific dataset release, including its ID and a list of available datasets within that release. Requires importing SemanticScholar.

```python
from semanticscholar import SemanticScholar
sch = SemanticScholar()
release = sch.get_release('2025-08-19')

print(f"Release ID: {release.release_id}")
print(f"Number of datasets: {len(release.datasets)}")

# List all available datasets in this release
for dataset in release.datasets:
    print(f"- {dataset.name}: {dataset.description}")
```

--------------------------------

### Get Recommended Papers for a Given Paper

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/usage.md

Retrieves a list of recommended papers based on a single specified paper ID. Requires importing SemanticScholar.

```python
from semanticscholar import SemanticScholar
sch = SemanticScholar()
results = sch.get_recommended_papers('10.2139/ssrn.2250500')
```

--------------------------------

### GET /graph/v1/paper/search

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/api.md

Searches for papers based on various criteria. Allows for flexible searching of the paper database.

```APIDOC
## GET /graph/v1/paper/search

### Description
Searches for papers based on various criteria. Allows for flexible searching of the paper database.

### Method
GET

### Endpoint
/graph/v1/paper/search

### Parameters
#### Query Parameters
- **query** (string) - Required - The search query string.
- **limit** (integer) - Optional - The maximum number of results to return.
- **offset** (integer) - Optional - The number of results to skip.

### Response
#### Success Response (200)
- **results** (array) - A list of paper search results.
```

--------------------------------

### Get Available Dataset Releases

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/usage.md

Fetches a list of all available dataset release identifiers (e.g., dates) from the Semantic Scholar API. Requires importing SemanticScholar.

```python
from semanticscholar import SemanticScholar
sch = SemanticScholar()
releases = sch.get_available_releases()
print(releases)
```

--------------------------------

### Initialize and Get Paper by ID

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/usage.md

Basic usage to initialize the SemanticScholar class and retrieve a paper's data using its ID. Access the paper's title from the response object.

```python
from semanticscholar import SemanticScholar
sch = SemanticScholar()
paper = sch.get_paper('10.1093/mind/lix.236.433')
print(paper.title)
```

--------------------------------

### GET /recommendations/v1/papers/forpaper/{paper_id}

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/api.md

Retrieves paper recommendations related to a specific paper. Helps users find papers similar or related to a known paper.

```APIDOC
## GET /recommendations/v1/papers/forpaper/{paper_id}

### Description
Retrieves paper recommendations related to a specific paper. Helps users find papers similar or related to a known paper.

### Method
GET

### Endpoint
/recommendations/v1/papers/forpaper/{paper_id}

### Parameters
#### Path Parameters
- **paper_id** (string) - Required - The ID of the paper for which to get recommendations.

### Response
#### Success Response (200)
- **recommendations** (array) - A list of recommended paper IDs.
```

--------------------------------

### GET /datasets/v1/diffs/{start_release_id}/to/{end_release_id}/{dataset_name}

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/api.md

Retrieves differences between two specified dataset releases. This endpoint allows users to compare versions of datasets.

```APIDOC
## GET /datasets/v1/diffs/{start_release_id}/to/{end_release_id}/{dataset_name}

### Description
Retrieves differences between two specified dataset releases. This endpoint allows users to compare versions of datasets.

### Method
GET

### Endpoint
/datasets/v1/diffs/{start_release_id}/to/{end_release_id}/{dataset_name}

### Parameters
#### Path Parameters
- **start_release_id** (string) - Required - The ID of the starting release.
- **end_release_id** (string) - Required - The ID of the ending release.
- **dataset_name** (string) - Required - The name of the dataset to compare.

### Response
#### Success Response (200)
- **diffs** (object) - An object containing the differences between the two releases.
```

--------------------------------

### GET /graph/v1/paper/search/bulk

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/api.md

Performs a bulk search for papers. This endpoint is similar to `/search` but may offer different performance characteristics or options for bulk operations.

```APIDOC
## GET /graph/v1/paper/search/bulk

### Description
Performs a bulk search for papers. This endpoint is similar to `/search` but may offer different performance characteristics or options for bulk operations.

### Method
GET

### Endpoint
/graph/v1/paper/search/bulk

### Parameters
#### Query Parameters
- **query** (string) - Required - The search query string.
- **limit** (integer) - Optional - The maximum number of results to return.
- **offset** (integer) - Optional - The number of results to skip.

### Response
#### Success Response (200)
- **results** (array) - A list of paper search results.
```

--------------------------------

### GET /graph/v1/author/search

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/api.md

Searches for authors based on various criteria. Allows for flexible searching of the author database.

```APIDOC
## GET /graph/v1/author/search

### Description
Searches for authors based on various criteria. Allows for flexible searching of the author database.

### Method
GET

### Endpoint
/graph/v1/author/search

### Parameters
#### Query Parameters
- **query** (string) - Required - The search query string.
- **limit** (integer) - Optional - The maximum number of results to return.
- **offset** (integer) - Optional - The number of results to skip.

### Response
#### Success Response (200)
- **results** (array) - A list of author search results.
```

--------------------------------

### Get First Page of Search Results

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/usage.md

Retrieves only the first page of results for a paper search query, avoiding additional API calls for subsequent pages. Requires importing SemanticScholar.

```python
results = sch.search_paper('Computing Machinery and Intelligence')
first_page = results.items
```

--------------------------------

### GET /graph/v1/paper/{paper_id}

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/api.md

Retrieves detailed information for a specific paper by its ID. Provides comprehensive data about a single paper.

```APIDOC
## GET /graph/v1/paper/{paper_id}

### Description
Retrieves detailed information for a specific paper by its ID. Provides comprehensive data about a single paper.

### Method
GET

### Endpoint
/graph/v1/paper/{paper_id}

### Parameters
#### Path Parameters
- **paper_id** (string) - Required - The ID of the paper to retrieve.

### Response
#### Success Response (200)
- **paper_details** (object) - An object containing the detailed information of the paper.
```

--------------------------------

### GET /graph/v1/author/{author_id}

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/api.md

Retrieves detailed information for a specific author by their ID. Provides comprehensive data about a single author.

```APIDOC
## GET /graph/v1/author/{author_id}

### Description
Retrieves detailed information for a specific author by their ID. Provides comprehensive data about a single author.

### Method
GET

### Endpoint
/graph/v1/author/{author_id}

### Parameters
#### Path Parameters
- **author_id** (string) - Required - The ID of the author to retrieve.

### Response
#### Success Response (200)
- **author_details** (object) - An object containing the detailed information of the author.
```

--------------------------------

### GET /graph/v1/snippet/search

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/api.md

Searches for snippets of text related to papers. Useful for finding specific information within a larger corpus.

```APIDOC
## GET /graph/v1/snippet/search

### Description
Searches for snippets of text related to papers. Useful for finding specific information within a larger corpus.

### Method
GET

### Endpoint
/graph/v1/snippet/search

### Parameters
#### Query Parameters
- **query** (string) - Required - The search query for snippets.
- **limit** (integer) - Optional - The maximum number of results to return.
- **offset** (integer) - Optional - The number of results to skip.

### Response
#### Success Response (200)
- **snippets** (array) - A list of text snippets.
```

--------------------------------

### HTTP POST Request to Semantic Scholar API

Source: https://github.com/danielnsilva/semanticscholar/blob/master/tests/data/debug_output.txt

This snippet shows a POST request to the Semantic Scholar API for batch paper retrieval. It includes the endpoint, required fields, and an example API key.

```http
DEBUG:semanticscholar:HTTP Request: POST https://api.semanticscholar.org/graph/v1/paper/batch?fields=abstract,authors,citationCount,citationStyles,corpusId,externalIds,fieldsOfStudy,influentialCitationCount,isOpenAccess,journal,openAccessPdf,paperId,publicationDate,publicationTypes,publicationVenue,referenceCount,s2FieldsOfStudy,title,url,venue,year
```

--------------------------------

### Build Documentation Locally

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/contributing.md

Navigate to the docs directory and use the make command to build the HTML documentation locally.

```console
cd docs && make html
```

--------------------------------

### Initialize with API Key

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/usage.md

Configure the SemanticScholar class with an API key for authenticated requests. Replace 'your_api_key_here' with your actual key.

```python
from semanticscholar import SemanticScholar
sch = SemanticScholar(api_key='your_api_key_here')
```

--------------------------------

### Initialize and Use SemanticScholar Client

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/overview.md

Import the client, create an instance, and fetch a paper by its ID. This demonstrates basic usage for retrieving paper details.

```python
# First, import the client from semanticscholar module
from semanticscholar import SemanticScholar

# You'll need an instance of the client to request data from the API
sch = SemanticScholar()

# Get a paper by its ID
paper = sch.get_paper('10.1093/mind/lix.236.433')

# Print the paper title
print(paper.title)
```

--------------------------------

### Run All Unit Tests

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/contributing.md

Execute all unit tests in the project. This is the primary command for verifying the entire test suite.

```console
python -m unittest
```

--------------------------------

### List Available Response Keys

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/usage.md

Use the `keys()` method on the paper response object to see all available fields.

```python
paper = sch.get_paper('10.1093/mind/lix.236.433')
print(paper.keys())
```

--------------------------------

### Run Coverage for Source Code

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/contributing.md

Execute tests while collecting code coverage data for the 'semanticscholar/' directory. This helps identify untested code.

```console
python -m coverage run --source=semanticscholar/ -m unittest discover
```

--------------------------------

### POST /recommendations/v1/papers/

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/api.md

Generates paper recommendations based on provided lists of papers. Useful for discovering related research.

```APIDOC
## POST /recommendations/v1/papers/

### Description
Generates paper recommendations based on provided lists of papers. Useful for discovering related research.

### Method
POST

### Endpoint
/recommendations/v1/papers/

### Parameters
#### Request Body
- **paper_lists** (object) - Required - An object containing lists of papers to base recommendations on.

### Request Example
```json
{
  "paper_lists": {
    "list1": ["paperA", "paperB"],
    "list2": ["paperC"]
  }
}
```

### Response
#### Success Response (200)
- **recommendations** (array) - A list of recommended paper IDs.
```

--------------------------------

### Run a Specific Unit Test Method

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/contributing.md

Execute a single, specific test method. Ideal for debugging a particular test case.

```console
python -m unittest tests.test_semanticscholar.TestClassName.testMethod
```

--------------------------------

### Datasets API - Available Releases

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/usage.md

Lists all available dataset release identifiers.

```APIDOC
## Datasets API - Available Releases

Retrieve a list of all available dataset release identifiers.

### Example Usage

```python
from semanticscholar import SemanticScholar
sch = SemanticScholar()
releases = sch.get_available_releases()
print(releases)
# Example output: ['2025-08-19', '2025-09-05', ...]
```
```

--------------------------------

### Asynchronous Paper Retrieval

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/usage.md

Demonstrates how to use the `AsyncSemanticScholar` class for making asynchronous requests to fetch paper data. Requires `asyncio`.

```python
import asyncio
from semanticscholar import AsyncSemanticScholar

def fetch_paper():
    async def get_paper():
        sch = AsyncSemanticScholar()
        return await sch.get_paper('10.1093/mind/lix.236.433')
    return asyncio.run(get_paper())

paper = fetch_paper()
```

--------------------------------

### Search Papers with Filters

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/usage.md

Demonstrates how to use the `search_paper` method with various filtering options such as venue, fields of study, publication date, and minimum citation count.

```APIDOC
## `search_paper` with Filters

This method allows searching for papers with specific criteria.

### Parameters

- `venue` (list): Restrict results to a given list of venues.
- `fields_of_study` (list): Restrict results to a given list of fields of study.
- `publication_date_or_year` (str): Restrict results to the given range of publication date (e.g., 'YYYY-MM-DD:YYYY-MM-DD').
- `min_citation_count` (int): Restrict results to papers with at least the given number of citations.

### Example Usage

```python
from semanticscholar import SemanticScholar
sch = SemanticScholar()

# Example with venue filter
results_venue = sch.search_paper('turing test', venue=['ESEM','ICSE','ICSME'])

# Example with fields_of_study filter
results_fields = sch.search_paper('turing test', fields_of_study=['Computer Science','Education'])

# Example with publication_date_or_year filter
results_date = sch.search_paper('turing test', publication_date_or_year='2020-01-01:2021-12-31')

# Example with min_citation_count filter
results_citations = sch.search_paper('turing test', min_citation_count=100)
```
```

--------------------------------

### Fetch Next Page of Paginated Results

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/usage.md

Appends the next batch of results to the current list using the next_page() method. Useful for manually controlling pagination. Requires importing SemanticScholar.

```python
results = sch.search_paper('Computing Machinery and Intelligence')
results.next_page()
first_two_pages = results.items
```

--------------------------------

### Generate HTML Coverage Report

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/contributing.md

Generate an HTML version of the code coverage report. Provides an interactive and detailed view of coverage across files and lines.

```console
python -m coverage html
```

--------------------------------

### Paginated Results

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/usage.md

Explains how to handle paginated results from search queries, including iterating through all results and fetching the next page.

```APIDOC
## Paginated Results

Methods returning large amounts of data support pagination. The default limit is 100 results per page.

### Iterating Through All Results

Automatically fetches all available items when iterated.

```python
from semanticscholar import SemanticScholar
sch = SemanticScholar()
results = sch.search_paper('Computing Machinery and Intelligence')
all_results = [item for item in results]
```

### Accessing First Page

Retrieve only the first page of results without extra API calls.

```python
results = sch.search_paper('Computing Machinery and Intelligence')
first_page = results.items
```

### Fetching Next Page

Append the next batch of items to the current list.

```python
results = sch.search_paper('Computing Machinery and Intelligence')
results.next_page()
first_two_pages = results.items
```
```

--------------------------------

### Generate Coverage Report

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/contributing.md

Generate a text-based report of code coverage after running tests with coverage enabled. Shows which lines of code were executed.

```console
python -m coverage report
```

--------------------------------

### Enable Global Debug Logging

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/usage.md

Enables debug-level logging for all loggers, including the semanticscholar library and its dependencies. This provides comprehensive insight into HTTP requests and responses.

```python
import logging
logging.getLogger().setLevel(logging.DEBUG)
```

--------------------------------

### Search Papers by Title Match

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/usage.md

Retrieve a single paper that best matches the given query in its title. Note that this parameter is not compatible with bulk retrieval.

```python
from semanticscholar import SemanticScholar
sch = SemanticScholar()
paper = sch.search_paper(query='deep learning', match_title=True)
```

--------------------------------

### Iterate Through All Paginated Search Results

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/usage.md

Automatically fetches and collects all available results for a paper search query by iterating through pages. Requires importing SemanticScholar.

```python
from semanticscholar import SemanticScholar
sch = SemanticScholar()
results = sch.search_paper('Computing Machinery and Intelligence')
all_results = [item for item in results]
```

--------------------------------

### Search for Papers by Keyword

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/usage.md

Find papers matching a specific keyword or title. This is a primary method for discovering relevant research.

```python
from semanticscholar import SemanticScholar
sch = SemanticScholar()
results = sch.search_paper('Computing Machinery and Intelligence')
```

--------------------------------

### Retrieve Multiple Authors by IDs

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/usage.md

Fetch details for a list of authors using their author IDs. This allows for efficient retrieval of multiple author profiles.

```python
from semanticscholar import SemanticScholar
sch = SemanticScholar()
list_of_author_ids = ['3234559', '1726629', '1711844']
results = sch.get_authors(list_of_author_ids)
```

--------------------------------

### Run Unit Tests in a Specific Class

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/contributing.md

Execute all tests within a particular test class. Useful for focusing on a specific module or feature.

```console
python -m unittest tests.test_semanticscholar.TestClassName
```

--------------------------------

### Search for Text Snippets

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/usage.md

Use this snippet to find text excerpts matching a query. Results include paper metadata and the matched text snippet.

```python
from semanticscholar import SemanticScholar
sch = SemanticScholar()
results = sch.search_snippet('turing test', limit=5)
for item in results:
    print(item.paper.title)
    print(item.snippet.snippet_kind)
    print(item.text)
```

--------------------------------

### Search for Authors by Name

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/usage.md

Find authors by their name. This is useful for locating researchers and their associated publications.

```python
from semanticscholar import SemanticScholar
sch = SemanticScholar()
results = sch.search_author('Alan M. Turing')
```

--------------------------------

### POST /graph/v1/paper/batch

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/api.md

Retrieves information for multiple papers in a single request. Optimized for batch retrieval of paper data.

```APIDOC
## POST /graph/v1/paper/batch

### Description
Retrieves information for multiple papers in a single request. Optimized for batch retrieval of paper data.

### Method
POST

### Endpoint
/graph/v1/paper/batch

### Parameters
#### Request Body
- **paper_ids** (array) - Required - A list of paper IDs to retrieve information for.

### Request Example
```json
{
  "paper_ids": ["paper1", "paper2"]
}
```

### Response
#### Success Response (200)
- **papers** (array) - A list of paper objects.
```

--------------------------------

### Search Papers with Specific Fields

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/usage.md

Searches for papers and returns only the specified fields to optimize response size and performance. By default, all fields are returned.

```python
from semanticscholar import SemanticScholar
sch = SemanticScholar()
results = sch.search_paper('software engineering', fields=['title','year'])
```

--------------------------------

### Set Custom Response Timeout

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/usage.md

Initialize SemanticScholar with a custom timeout value (in seconds) to control how long to wait for an API response.

```python
from semanticscholar import SemanticScholar
sch = SemanticScholar(timeout=5)
```

--------------------------------

### Bulk Paper Search with Sorting

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/usage.md

Retrieve papers in bulk, ordered by a specified field such as citation count in descending order.

```python
# Retrieve highly-cited papers first
response = sch.search_paper(query='deep learning', bulk=True, sort='citationCount:desc')
```

--------------------------------

### POST /graph/v1/paper/{paper_id}/references

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/api.md

Retrieves a list of papers referenced by a specific paper. Helps in tracing the literature background of a paper.

```APIDOC
## POST /graph/v1/paper/{paper_id}/references

### Description
Retrieves a list of papers referenced by a specific paper. Helps in tracing the literature background of a paper.

### Method
POST

### Endpoint
/graph/v1/paper/{paper_id}/references

### Parameters
#### Path Parameters
- **paper_id** (string) - Required - The ID of the paper for which to retrieve references.

### Response
#### Success Response (200)
- **references** (array) - A list of paper objects referenced by the specified paper.
```

--------------------------------

### Retrieve Author Data

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/usage.md

Fetch details for a specific author using their author ID. This is useful for accessing author-specific metadata.

```python
from semanticscholar import SemanticScholar
sch = SemanticScholar()
author = sch.get_author(2262347)
```

--------------------------------

### POST /graph/v1/author/batch

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/api.md

Retrieves information for multiple authors in a single request. This endpoint is optimized for batch processing of author data.

```APIDOC
## POST /graph/v1/author/batch

### Description
Retrieves information for multiple authors in a single request. This endpoint is optimized for batch processing of author data.

### Method
POST

### Endpoint
/graph/v1/author/batch

### Parameters
#### Request Body
- **author_ids** (array) - Required - A list of author IDs to retrieve information for.

### Request Example
```json
{
  "author_ids": ["123", "456"]
}
```

### Response
#### Success Response (200)
- **authors** (array) - A list of author objects.
```

--------------------------------

### cURL Command for Semantic Scholar API Batch Request

Source: https://github.com/danielnsilva/semanticscholar/blob/master/tests/data/debug_output.txt

This snippet provides a cURL command to replicate the Semantic Scholar API batch paper retrieval request. It includes the HTTP method, headers, payload, and URL.

```bash
DEBUG:semanticscholar:cURL command: curl -X POST -H 'x-api-key: F@k3K3y' -d '{"ids": ["CorpusId:470667", "10.2139/ssrn.2250500", "0f40b1f08821e22e859c6050916cec3667778613"]}' https://api.semanticscholar.org/graph/v1/paper/batch?fields=abstract,authors,citationCount,citationStyles,corpusId,externalIds,fieldsOfStudy,influentialCitationCount,isOpenAccess,journal,openAccessPdf,paperId,publicationDate,publicationTypes,publicationVenue,referenceCount,s2FieldsOfStudy,title,url,venue,year
```

--------------------------------

### Search Papers with a Limit

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/usage.md

Searches for papers and limits the number of results returned. A smaller limit reduces output size and latency. The default limit is 100.

```python
from semanticscholar import SemanticScholar
sch = SemanticScholar()
results = sch.search_paper('software engineering', limit=5)
```

--------------------------------

### Search Papers by Venue

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/usage.md

Restrict paper search results to a specific list of venues.

```python
results = sch.search_paper('turing test', venue=['ESEM','ICSE','ICSME'])
```

--------------------------------

### Bulk Paper Search with OR Operator

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/usage.md

Perform a bulk search for papers using advanced query syntax, such as the OR operator for broader results.

```python
# Search for papers containing 'deep' or 'learning'
response = sch.search_paper(query='deep | learning', bulk=True)
```

--------------------------------

### Set Response Timeout Property

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/usage.md

Alternatively, set the `timeout` property on an existing SemanticScholar instance to change the wait time for API responses.

```python
from semanticscholar import SemanticScholar
sch = SemanticScholar()
sch.timeout = 5
```

--------------------------------

### Batch Paper Retrieval

Source: https://github.com/danielnsilva/semanticscholar/blob/master/tests/data/debug_output.txt

Retrieve detailed information for multiple papers by providing a list of their IDs. This endpoint allows for efficient fetching of data for several papers at once.

```APIDOC
## POST /graph/v1/paper/batch

### Description
Retrieve detailed information for multiple papers by providing a list of their IDs. This endpoint allows for efficient fetching of data for several papers at once.

### Method
POST

### Endpoint
https://api.semanticscholar.org/graph/v1/paper/batch

### Parameters
#### Query Parameters
- **fields** (string) - Optional - Comma-separated list of fields to include in the response. Available fields include: abstract, authors, citationCount, citationStyles, corpusId, externalIds, fieldsOfStudy, influentialCitationCount, isOpenAccess, journal, openAccessPdf, paperId, publicationDate, publicationTypes, publicationVenue, referenceCount, s2FieldsOfStudy, title, url, venue, year.

#### Request Body
- **ids** (array of strings) - Required - A list of paper identifiers. These can be in the format 'CorpusId:12345', 'doi:10.1000/xyz', or paper IDs.

### Request Example
```json
{
  "ids": ["CorpusId:470667", "10.2139/ssrn.2250500", "0f40b1f08821e22e859c6050916cec3667778613"]
}
```

### Response
#### Success Response (200)
- **data** (array of objects) - Contains information for each requested paper.
- **error** (object) - Contains error details if the request fails.

#### Response Example
```json
{
  "data": [
    {
      "paperId": "2055001",
      "corpusId": 2055001,
      "title": "The Effect of the Internet on the Economy",
      "authors": [
        {
          "authorId": "1440078",
          "name": "Robert E. Litan"
        }
      ],
      "year": 1998,
      "externalIds": {
        "ArXiv": "9801010",
        "ACL": "10.1007/s11192-004-0103-3"
      },
      "url": "https://www.semanticscholar.org/paper/The-Effect-of-the-Internet-on-the-Economy-Litan/2055001",
      "venue": "Brookings Institution Press",
      "fieldsOfStudy": [
        "Economics"
      ],
      "citationCount": 150,
      "referenceCount": 50,
      "isOpenAccess": false,
      "openAccessPdf": null,
      "s2FieldsOfStudy": [
        "Economics"
      ],
      "publicationDate": "1998-01-01",
      "publicationTypes": [
        "Book"
      ],
      "publicationVenue": {
        "name": "Brookings Institution Press",
        "type": "Journal"
      },
      "citationStyles": {
        "bibtex": "@book{Litan1998TheEO,\n title={The Effect of the Internet on the Economy},\n author={Robert E. Litan},\n year={1998},\n publisher={Brookings Institution Press}\n}",
        "harvard": "Litan, R.E., 1998. The Effect of the Internet on the Economy. Brookings Institution Press."
      },
      "abstract": "This paper discusses the economic impact of the internet..."
    }
  ]
}
```
```

--------------------------------

### POST /graph/v1/paper/{paper_id}/citations

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/api.md

Retrieves a list of papers that cite a specific paper. Useful for understanding the impact and influence of a paper.

```APIDOC
## POST /graph/v1/paper/{paper_id}/citations

### Description
Retrieves a list of papers that cite a specific paper. Useful for understanding the impact and influence of a paper.

### Method
POST

### Endpoint
/graph/v1/paper/{paper_id}/citations

### Parameters
#### Path Parameters
- **paper_id** (string) - Required - The ID of the paper for which to retrieve citations.

### Response
#### Success Response (200)
- **citations** (array) - A list of paper objects that cite the specified paper.
```

--------------------------------

### Search Papers by Fields of Study

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/usage.md

Restrict paper search results to a specific list of fields of study. Refer to the official documentation for a complete list of available fields.

```python
results = sch.search_paper('turing test', fields_of_study=['Computer Science','Education'])
```

--------------------------------

### Retrieve Multiple Papers by IDs

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/usage.md

Fetch details for a list of papers using their unique identifiers. Supports Corpus ID, DOI, and S2Paper ID formats.

```python
from semanticscholar import SemanticScholar
sch = SemanticScholar()
list_of_paper_ids = [
    'CorpusId:470667',
    '10.2139/ssrn.2250500',
    '0f40b1f08821e22e859c6050916cec3667778613'
]
results = sch.get_papers(list_of_paper_ids)
```

--------------------------------

### Enable Semantic Scholar Debug Logging Only

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/usage.md

Restricts debug-level logging specifically to the semanticscholar library. This helps in isolating issues related to the library's interactions with the API.

```python
import logging
logging.getLogger('semanticscholar').setLevel(logging.DEBUG)
```

--------------------------------

### Bulk Paper Retrieval

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/usage.md

Fetch a large number of paper records efficiently. This method is suitable for retrieving more than the default limit of 1,000 results.

```python
from semanticscholar import SemanticScholar
sch = SemanticScholar()
response = sch.search_paper(query='deep learning', bulk=True)
```

--------------------------------

### POST /graph/v1/paper/{author_id}/papers

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/api.md

Retrieves a list of papers authored by a specific author. Links papers to their respective authors.

```APIDOC
## POST /graph/v1/paper/{author_id}/papers

### Description
Retrieves a list of papers authored by a specific author. Links papers to their respective authors.

### Method
POST

### Endpoint
/graph/v1/paper/{author_id}/papers

### Parameters
#### Path Parameters
- **author_id** (string) - Required - The ID of the author whose papers are to be retrieved.

### Response
#### Success Response (200)
- **papers** (array) - A list of paper objects authored by the specified author.
```

--------------------------------

### POST /graph/v1/paper/{paper_id}/authors

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/api.md

Retrieves the authors of a specific paper. Links papers to their authors.

```APIDOC
## POST /graph/v1/paper/{paper_id}/authors

### Description
Retrieves the authors of a specific paper. Links papers to their authors.

### Method
POST

### Endpoint
/graph/v1/paper/{paper_id}/authors

### Parameters
#### Path Parameters
- **paper_id** (string) - Required - The ID of the paper whose authors are to be retrieved.

### Response
#### Success Response (200)
- **authors** (array) - A list of author objects for the specified paper.
```

--------------------------------

### HTTP Headers for Semantic Scholar API Request

Source: https://github.com/danielnsilva/semanticscholar/blob/master/tests/data/debug_output.txt

This snippet displays the HTTP headers used in a Semantic Scholar API request, specifically showing the API key for authentication.

```http
DEBUG:semanticscholar:Headers: {'x-api-key': 'F@k3K3y'}
```

--------------------------------

### Disable Automatic Retries

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/usage.md

Instantiate SemanticScholar with `retry=False` to disable the automatic retry mechanism for rate-limiting responses.

```python
from semanticscholar import SemanticScholar
sch = SemanticScholar(retry=False)
```

--------------------------------

### Search Papers with Open Access PDF

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/usage.md

Filter search results to include only papers that have an available open access PDF.

```python
results = sch.search_paper('turing test', open_access_pdf=True)
```

--------------------------------

### Search Papers by Publication Type

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/usage.md

Restrict search results to specific types of publications, such as 'Journal' or 'Conference' papers.

```python
results = sch.search_paper('turing test', publication_type=['Journal','Conference'])
```

--------------------------------

### Access Raw JSON Data

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/usage.md

Retrieve the raw JSON data of a paper response as a dictionary using the `raw_data` attribute.

```python
paper = sch.get_paper('10.1093/mind/lix.236.433')
print(paper.raw_data)
```

--------------------------------

### Search Papers by Minimum Citation Count

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/usage.md

Restrict paper search results to papers that have at least a specified number of citations.

```python
results = sch.search_paper('turing test', min_citation_count=100)
```

--------------------------------

### Search Papers by Publication Date Range

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/usage.md

Restrict paper search results to a specified range of publication dates. Dates can be in YYYY-MM-DD, YYYY-MM, or YYYY format.

```python
results = sch.search_paper('turing test', publication_date_or_year='2020-01-01:2021-12-31')
```

--------------------------------

### Search Papers by Publication Year

Source: https://github.com/danielnsilva/semanticscholar/blob/master/docs/source/usage.md

Filter search results to include only papers published within a specific year or a range of years.

```python
results = sch.search_paper('turing test', year=2000)
```

--------------------------------

### HTTP Payload for Semantic Scholar API Request

Source: https://github.com/danielnsilva/semanticscholar/blob/master/tests/data/debug_output.txt

This snippet shows the JSON payload sent with a Semantic Scholar API request, containing a list of paper identifiers.

```json
DEBUG:semanticscholar:Payload: {'ids': ['CorpusId:470667', '10.2139/ssrn.2250500', '0f40b1f08821e22e859c6050916cec3667778613']}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.