# NCBI Gene Database Scraper (`parseforge/ncbi-eutils-gene-scraper`) Actor

Scrapes NCBI Gene records by Entrez query and returns each gene as a flat row with identifier, symbol, name, location, aliases, OMIM ID, organism, and functional summary.

- **URL**: https://apify.com/parseforge/ncbi-eutils-gene-scraper.md
- **Developed by:** [ParseForge](https://apify.com/parseforge) (community)
- **Categories:** Education, Automation, Integrations
- **Stats:** 1 total users, 0 monthly users, 89.7% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $7.50 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

[![ParseForge](https://raw.githubusercontent.com/ParseForge/apify-assets/main/banner.jpg)](https://apify.com/parseforge?fpr=vmoqkp)

### NCBI Gene Database Scraper

**Scrape NCBI Gene records by gene name, symbol, or Entrez query, up to a million per run.** Every record returns the official symbol, full name, organism, chromosome location, aliases, and functional summary. No API key required. Export to JSON, CSV, Excel, or XML.

NCBI's Gene database is the central authority for gene nomenclature, but downloading records manually through the web portal is slow and not built for bulk work. This Actor reads the public E-utilities API directly, so you can pull structured data for thousands of genes in one go without writing a single line of Entrez code. It is built for bioinformaticians, pharma researchers, and clinical data analysts who need clean, flat gene records fast.

| Who uses it | What they scrape NCBI Gene Database for |
|---|---|
| Bioinformaticians | Building a local gene reference table for a variant annotation pipeline. |
| Pharma R\&D teams | Pulling official gene summaries and OMIM links for a list of drug targets. |
| Clinical geneticists | Collecting chromosome locations and aliases for a panel of disease-associated genes. |
| Academic researchers | Gathering organism-specific gene metadata for a comparative genomics study. |

### What it does

This Actor collects NCBI Gene records by gene name, symbol, or a full Entrez query and returns each gene as a flat row with its official symbol, full name, organism, chromosome location, aliases, and functional summary.

- 🧬 **Gene symbol or name query:** feed it a single gene like BRCA1, or a list of symbols, and get back the full NCBI record.
- 🔍 **Full Entrez query support:** use the exact NCBI query syntax you already know, such as 'BRCA1\[gene] AND human\[orgn]', to filter by organism, gene type, or chromosome.
- 📊 **Flat, analysis-ready rows:** each gene comes back as one row with a fixed schema, ready for pandas, R, or Excel without nested JSON cleanup.
- ⚡ **Bulk collection:** set a high maxItems value and pull up to a million gene records in a single run, respecting NCBI rate limits automatically.

Results export to CSV, JSON, Excel, or XML, or straight from the API.

### What you can do with NCBI Gene Database data

**🧬 Build a gene reference table.**

A bioinformatician feeds a list of 500 gene symbols into the Actor and exports a CSV with official names, chromosome bands, and aliases for a variant annotation pipeline.

**💊 Curate a pharma target list.**

An R\&D scientist runs an Entrez query for 'kinase\[gene] AND human\[orgn]' to pull every human kinase with its functional summary and OMIM link for a target assessment report.

**🧪 Prepare a clinical gene panel.**

A clinical geneticist scrapes the chromosome locations and full names for a set of ACMG-recommended genes to populate a lab report template.

**📚 Gather organism-specific metadata.**

A graduate student queries '16S rRNA\[gene] AND bacteria\[orgn]' to collect ribosomal RNA gene records across bacterial species for a phylogenetics project.

### Why choose this scraper

| | What you get |
|---|---|
| **No API key** | Reads the public NCBI E-utilities endpoint, so you skip the registration and key management. |
| **Entrez syntax** | Accepts the exact query strings you use on the NCBI website, including field tags and boolean operators. |
| **Fixed schema** | Every run returns the same columns, so your downstream scripts never break on a schema change. |
| **Rate-limit safe** | Built-in delays keep you within NCBI's usage guidelines without manual throttling. |

### How it compares

This Actor focuses exclusively on the NCBI Gene database with full Entrez query syntax support, while the competitors listed below either cover multiple NCBI databases or return a narrower set of gene fields.

| Feature | ParseForge | NCBI Gene Lookup - Genomics API for Pharma R\&D | NCBI Bio Datasets | NCBI Gene Records Scraper |
|---|---|---|---|---|
| Full Entrez query syntax support | Yes, accepts any valid Entrez query string with field tags and boolean operators | Not listed | Not listed | Not listed |
| Returns functional gene summary text | Yes | Yes | Not listed | Not listed |
| Returns OMIM ID | Yes | Yes | Not listed | Not listed |
| Returns chromosome location and map locus | Yes | Yes | Not listed | Not listed |
| Queries across multiple NCBI databases (PubMed, Protein, SNPs) | No, Gene database only | Not listed | Yes | Not listed |
| No API key required | Yes | Not listed | Yes | Not listed |

### Configure the run

Drive the Actor with a gene name, symbol, or a full Entrez query, and set a maximum number of genes to collect per run. The Input tab lists every parameter.

A first run with the defaults:

```json
{
 "maxItems": 10
}
```

A larger pull:

```json
{
 "maxItems": 200
}
```

### Pricing

Pay-per-result: **$0.0085 per result** collected. You pay only for the results written to your dataset.

| Results collected | Approximate cost |
|---|---|
| 100 results | $0.85 |
| 1,000 results | $8.50 |
| 10,000 results | $85.00 |

New Apify accounts start with $5 in free credit.

### Free users

Free-plan runs return up to 10 results as a preview. [Upgrade your Apify plan](https://console.apify.com/sign-up?fpr=vmoqkp) to collect up to 1,000,000 results per run.

### Run it

1. [Create a free Apify account with $5 in credit](https://console.apify.com/sign-up?fpr=vmoqkp).
2. Open the [NCBI Gene Database Scraper](https://apify.com/parseforge/ncbi-eutils-gene-scraper?fpr=vmoqkp).
3. Set your inputs and any filters, then click **Start**.
4. Export the results as CSV, Excel, JSON, or XML from the **Dataset** tab.

Run it programmatically through the [Apify API](https://docs.apify.com/api/v2) (`run-sync-get-dataset-items`) or the [ApifyClient](https://docs.apify.com/api/client/js) for JavaScript and Python.

### Use with AI agents (MCP)

Give an AI agent live access to NCBI Gene Database through the Model Context Protocol. Add the Actor to Claude, Cursor, or any MCP client:

```bash
claude mcp add --transport http apify "https://mcp.apify.com/?tools=parseforge/ncbi-eutils-gene-scraper"
```

Then prompt it in plain language to run the scraper and read back the results.

### Troubleshooting

**Why am I getting no results for my query?**

Check that your Entrez query syntax is valid. Try the same query string directly on the NCBI Gene website first. Also ensure you have not set maxItems to 0, and that the gene symbol or name is spelled correctly with the proper case.

**The run is taking a very long time. Is it stuck?**

Large runs with high maxItems values include deliberate delays to respect NCBI rate limits. A run of 10,000 genes can take several hours. Check the run log for progress messages, and consider reducing maxItems if you need results faster.

**Some fields are empty in my output. Is that an error?**

No. NCBI does not provide every field for every gene. For example, some genes lack an OMIM ID or a functional summary. The Actor returns empty cells for missing data rather than omitting the column, so your schema stays consistent.

**I got an error about the query syntax. What is wrong?**

Entrez query syntax requires square brackets for field tags, like 'BRCA1\[gene]'. Make sure your brackets are properly closed and that you are using valid field qualifiers such as \[gene], \[orgn], or \[sym]. Avoid special characters that break URL encoding.

**Can I use this Actor with an NCBI API key for higher rate limits?**

Yes. If you have an NCBI API key, you can pass it as an environment variable in your Apify actor configuration. The Actor will then use the authenticated endpoint, which allows up to 10 requests per second instead of 3.

### FAQ

| Question | Answer |
|---|---|
| Do I need an NCBI API key to use this Actor? | No. This Actor uses the public NCBI E-utilities endpoint, which does not require an API key. If you have an API key and want higher rate limits, you can add it as an environment variable in your Apify run. |
| What exactly does one row of output contain? | Each row is one NCBI Gene record and includes the official gene symbol, full gene name, organism, chromosome location, map locus, aliases, OMIM ID, and a functional summary text when NCBI provides it. |
| Can I query by something other than a gene symbol, like a disease or a chromosome band? | Yes. The query field accepts any valid NCBI Entrez query string. You can search by chromosome location, gene type, organism, or combine terms with boolean operators exactly as you would on the NCBI Gene website. |
| How many genes can I scrape in one run? | You can set the maximum up to 1,000,000 genes per run. The Actor respects NCBI's rate limits by pausing between requests, so large runs complete reliably without being blocked. |
| Does this Actor return sequence data or metadata? | This Actor returns the gene-level metadata: symbol, name, location, aliases, summary, and OMIM link. It does not fetch nucleotide or protein sequences. For sequence data, look for an NCBI sequence scraper. |
| Can I filter results to only human genes? | Yes. Use the Entrez query syntax in the query field, for example 'human\[orgn]' to restrict results to Homo sapiens. You can combine this with any gene name or symbol. |
| What output formats are supported? | The Actor exports to JSON, CSV, Excel, and XML. You choose the format in the Apify dataset settings or when you download the results. |
| How do I write a query for multiple genes at once? | Use the OR operator in your Entrez query, for example 'BRCA1\[gene] OR TP53\[gene] OR EGFR\[gene]'. You can also paste a list of symbols separated by OR if you generate the query string programmatically. |
| Is the output schema always the same? | Yes. Every run returns the same fixed set of columns, even when NCBI omits a field for a particular gene. Missing values appear as empty cells, so your downstream analysis never breaks on a schema change. |
| Does this Actor handle rate limiting automatically? | Yes. The Actor includes built-in delays between requests to stay within NCBI's usage guidelines. For very large runs, it will take longer but complete without manual intervention. |

### Related actors

Browse the full [ParseForge collection](https://apify.com/parseforge?fpr=vmoqkp) for more scrapers.

🆘 **Need help?** Email parseforge@protonmail.com with your run ID, your input, and what you expected.

⚠️ **Disclaimer.** This Actor is unofficial and is not affiliated with, endorsed by, or sponsored by National Center for Biotechnology Information, U.S. National Library of Medicine. It collects only publicly available data. You are responsible for using the collected data in compliance with the source's terms of service and applicable data-protection laws, including GDPR, CCPA, and PIPL. Do not use it to collect personal data unlawfully.

# Actor input Schema

## `query` (type: `string`):

NCBI Gene Entrez query. Example: BRCA1\[gene] AND human\[orgn].

## `maxItems` (type: `integer`):

How many genes to collect per run.

## Actor input object example

```json
{
  "maxItems": 10
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "maxItems": 10
};

// Run the Actor and wait for it to finish
const run = await client.actor("parseforge/ncbi-eutils-gene-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "maxItems": 10 }

# Run the Actor and wait for it to finish
run = client.actor("parseforge/ncbi-eutils-gene-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "maxItems": 10
}' |
apify call parseforge/ncbi-eutils-gene-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,parseforge/ncbi-eutils-gene-scraper"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/XwhssNJakUlB0GZPU/builds/SsqfPFhBr7Hgm5K5n/openapi.json