# npm Package Intelligence (`atesen-software/npm-package-intelligence`) Actor

Look up npm versions, dependency names, license identifiers, deprecation flags and download trends from official APIs. Search or submit a list of public packages.

- **URL**: https://apify.com/atesen-software/npm-package-intelligence.md
- **Developed by:** [Atesen Software](https://apify.com/atesen-software) (community)
- **Categories:** Developer tools
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$0.45 / 1,000 package or daily results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## npm Package Intelligence

Get current versions, dependency names, license identifiers, deprecation flags and download trends from the official npm registry and downloads APIs. Supply package names, including scoped packages, or discover packages with an npm search query. Results are flat rows suitable for CSV, JSON and spreadsheet export.

The Actor does not download package tarballs, install queried packages, execute their code, fetch repository/homepage URLs, inspect private packages or use a browser, proxy, login, token or paid API.

### Why use this Actor

- **Before you adopt a package**: check its license, runtime dependency names, Node engine constraint and deprecation flag in one row, without installing anything.
- **Registry and SBOM research**: build structured inventories of the dependency names a package declares, including scoped packages.
- **Ecosystem comparisons**: batch a group of packages and compare last-week vs last-month download totals.
- **Lists from npm search**: discover packages by keyword with one bounded official search request, then audit each result.
- **Trend tracking over time**: schedule runs (daily or weekly) and store the emitted rows to follow `latest` versions and download totals.

Every row carries the official npm API URL it was built from, so values stay verifiable.

### Start small

```json
{
  "packages": ["express"],
  "maxPackages": 1,
  "maxRows": 1,
  "includeDownloads": true
}
```

For a batch, increase both caps:

```json
{
  "packages": ["express", "@apify/consts"],
  "maxPackages": 2,
  "maxRows": 2,
  "includeDownloads": true
}
```

For discovery, omit `packages` and use `"searchQuery": "keywords:framework"`. Search uses one bounded official search request; there is no automatic pagination.

### Inputs and limits

| Input | Default | Behavior |
| --- | --- | --- |
| `packages` | `["express"]` when no search | Up to 30 public lowercase package names; duplicates removed |
| `searchQuery` | omitted | 1–200 characters; alternative to packages |
| `maxPackages` | `1` | 1–30 packages processed; also bounds search size |
| `maxRows` | `1` | 1–2730 real rows across package metadata and daily history |
| `includeDownloads` | `true` | Add last-week and last-month totals to each package row |
| `includeDailyDownloads` | `false` | Emit one additional row per returned UTC day |
| `dailyDays` | `7` | 1–90 inclusive UTC days ending yesterday |

Daily output requires a sufficiently large `maxRows`: for one package and seven days, use at least eight. Package metadata is emitted before its daily rows; daily rows consume the shared result cap and can prevent later packages from being processed. Status rows do not count toward `maxRows` or result billing. Package names must be exact npm names. URLs, arbitrary paths, traversal and pre-encoded strings are rejected. A scoped name is encoded as one path component before API requests.

### Output

Example `package` row (illustrative values, matching the dataset schema):

```json
{
  "recordType": "package",
  "packageName": "express",
  "version": "5.1.0",
  "license": "MIT",
  "dependencies": "accepts, body-parser, content-disposition",
  "dependencyCount": 3,
  "deprecated": false,
  "nodeEngine": ">= 0.10.0",
  "weeklyDownloads": 30000000,
  "monthlyDownloads": 120000000,
  "weeklyMonthlyDownloadRatio": 0.25,
  "weekStart": "2026-10-15", "weekEnd": "2026-10-21",
  "monthStart": "2026-09-22", "monthEnd": "2026-10-21",
  "npmUrl": "https://www.npmjs.com/package/express",
  "sourceUrl": "https://registry.npmjs.org/express/latest",
  "fetchedAt": "2026-10-22T09:00:00.000Z"
}
```

With `includeDailyDownloads` on, each returned UTC day also produces one row:

```json
{
  "recordType": "daily",
  "packageName": "express",
  "day": "2026-10-21",
  "downloads": 4200000,
  "sourceUrl": "https://api.npmjs.org/downloads/range/2026-10-15:2026-10-21/express",
  "fetchedAt": "2026-10-22T09:00:00.000Z"
}
```

Each `package` row contains:

- Name, the version currently referenced by the `latest` tag, the declared license identifier or expression, and a boolean `deprecated` flag.
- Dependency, devDependency, peerDependency and optionalDependency names as comma-separated text, plus the runtime dependency count and a Node engine constraint when it uses supported range syntax.
- Last-week/month download totals and their actual returned period boundaries, plus `weeklyMonthlyDownloadRatio` = weekly downloads divided by monthly downloads. This is a raw share, not a growth rate or normalized trend estimate. A missing or zero monthly denominator returns `null`.
- npm page, official source API URL and retrieval timestamp.

Each optional `daily` row contains package name, UTC `day`, integer `downloads`, source URL and retrieval timestamp. The Actor reports recognized SPDX license identifiers and expressions, plus npm's standalone `UNLICENSED` marker. Custom references and free-form license text are omitted. Legacy arrays of recognized licenses are joined with `OR` for display. The latest tag need not be the highest semantic version. The Actor verifies that the version string is valid SemVer.

The `OUTPUT` key-value record contains status, package/daily/result counts, request count, warnings and timestamps. Noncompleted or partial runs also have a `status` dataset row without the custom result billing event. Invalid input, no results, missing packages and failures are never synthesized as paid package rows. Missing download statistics produce `null` values and a partial warning while preserving metadata. A later upstream failure preserves earlier emitted rows and marks the summary partial.

### Download-count caveats

Download counts measure downloads recorded by npm, not unique people, installs, active users or revenue. Counts can be delayed or unavailable for new and scoped packages. The Actor checks that npm's `last-week` and `last-month` boundaries are valid UTC calendar dates in order. An invalid period stops the run without billing for that package. Daily history ends yesterday in UTC and may lag the API's daily processing. The Actor skips duplicate days, invalid dates, and records outside the requested range.

### Network and charging behavior

Only HTTPS requests to `registry.npmjs.org` and `api.npmjs.org` are allowed, and redirects are forbidden. Requests run sequentially, at least 200ms apart. A request times out after 20 seconds. HTTP 429, 5xx and network failures get at most one retry. Numeric and HTTP-date Retry-After values are respected; if the requested wait exceeds ten seconds, the run stops without issuing an early retry. A 404 is not retried. A repeated throttle/server/network failure stops the run rather than retrying all remaining packages.

A normal package takes one metadata request plus two requests if weekly/monthly totals are enabled. Daily history adds one request when the shared row cap allows it. Search adds one initial request. Nothing is fetched after the output cap or SDK billing allowance is exhausted.

On a pay-per-event deployment, each real `package` or `daily` row is one custom `result` event through awaited `Actor.pushData(row, 'result')`. No startup or error event is charged. Configure only `result` pricing and leave synthetic/default dataset item pricing at zero, so status rows remain free. The SDK allowance and combined row prices are checked before requests and each write. Pricing must be configured separately in Apify; this source package neither enables pricing nor promises a price. Current run cost also depends on Apify platform usage. [SDK charging documentation](https://docs.apify.com/sdk/js/docs/concepts/pay-per-event).

### Run locally

Node.js 22+ is required. Apify SDK 3.7.2 is pinned with a lockfile. The narrow `basic-ftp` 6.2.3 override addresses a transitive audit finding; the Actor does not use FTP.

License validation uses [spdx-expression-parse](https://github.com/jslicense/spdx-expression-parse.js) (MIT). Its [SPDX exception identifiers](https://github.com/jslicense/spdx-exceptions.json#copyright-and-licensing) are credited to the Linux Foundation and its contributors under [CC BY 3.0](https://creativecommons.org/licenses/by/3.0/). Its [license identifier list](https://github.com/jslicense/spdx-license-ids) is CC0 1.0. Version validation uses [node-semver](https://github.com/npm/node-semver) (ISC).

```powershell
npm ci --ignore-scripts
npm test
$env:LOCAL_MODE = '1'
$env:INPUT_PATH = 'example-input.json'
$env:OUTPUT_DIR = 'data'
npm start
```

Local mode imports no Apify SDK and reads no credentials. It reads `INPUT_PATH` (or the first command-line argument, default `input.json`) and writes `dataset.json` and `OUTPUT.json` to `OUTPUT_DIR` (default `data`). It makes only the official public npm API calls, with no Apify calls or charges. Unset `LOCAL_MODE` for cloud operation.

The checked-in `example-input.json` requests one Express package row with weekly and monthly download totals. The local tests cover excluded publisher fields, scoped discovery, zero budget and the SDK's named result event.

### Use via API

- [Public npm registry API, latest-version and search endpoints](https://github.com/npm/registry/blob/main/docs/REGISTRY-API.md)
- [npm download-count API and UTC processing](https://github.com/npm/registry/blob/main/docs/download-counts.md)
- [Package metadata response fields](https://github.com/npm/registry/blob/main/docs/responses/package-metadata.md)
- [npm Open-Source Terms for public API access](https://docs.npmjs.com/policies/open-source-terms/)

The upstream services determine availability, coverage and future API changes. No third-party fallback is used.

```bash
curl -X POST "https://api.apify.com/v2/acts/atesen-software~npm-package-intelligence/run-sync-get-dataset-items?timeout=120" \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"packages":["express"],"includeDownloads":true}'
```

**JavaScript** (`npm install apify-client`):

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

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('atesen-software/npm-package-intelligence').call({ packages: ["express"], includeDownloads: true });
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

### Use with AI agents (MCP)

Claude Desktop, Cursor, VS Code and other MCP clients can call this Actor as a tool through the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp). Load only this Actor with:

```text
https://mcp.apify.com?tools=atesen-software/npm-package-intelligence
```

Client config (sign in with Apify OAuth when the browser opens, or add an `Authorization: Bearer <APIFY_TOKEN>` header instead):

```json
{
  "mcpServers": {
    "apify": { "url": "https://mcp.apify.com?tools=atesen-software/npm-package-intelligence" }
  }
}
```

Then ask in plain words, for example: "Show the latest version, license, maintainers and weekly downloads of the npm package express." The agent fills the same input fields you see on the Input tab, and runs are billed to your Apify account at the prices on the Pricing tab.

### How much does npm Package Intelligence cost?

Each saved package or daily download row is one `result` event. The current event price appears on the Pricing tab. Status rows, error rows and empty lookups are not charged. The run stops when it reaches the maximum cost per run.

### FAQ

**How many packages can one run process?**
Up to 30 packages, with a shared cap of 2,730 real rows across package metadata and daily history. Daily rows consume that shared cap, so package metadata is emitted first and later packages can be skipped if daily rows fill the cap first.

**Does it resolve or audit dependencies?**
No. It reports the dependency names a package declares (as comma-separated text plus a runtime count) and does nothing more with them: no dependency resolution, no installation, no vulnerability scan.

**Does the search option paginate?**
No. `searchQuery` runs one bounded official search request with no automatic pagination; `maxPackages` bounds how many results are processed.

**Why do my download numbers differ from other websites?**
Download counts are recorded downloads per period, not installs, unique users or revenue; new and scoped packages can have delayed or missing counts, daily history ends yesterday UTC, and missing dates are never filled with zeros.

**Can I schedule it?**
Yes. A daily or weekly schedule with `includeDownloads` on is a common way to track `latest` versions and download totals for your dependency list.

**What happens if npm is throttling or down?**
HTTP 429/5xx and network failures get at most one respectful retry (honoring `Retry-After` up to ten seconds), and a repeated failure stops the run as partial instead of fabricating rows. Already-emitted rows are preserved.

**Is any personal data involved?**
The exported data omits maintainer accounts, contact fields, package descriptions, deprecation messages, and publisher-supplied homepage and repository URLs. Scoped package and dependency names remain intact as registry identifiers. npm's official public APIs receive the package names or search query you enter.

### Support and disclaimers

Problems, feature requests and pricing questions belong on the **Issues** tab of the Actor's page on Apify. This Actor is an independent tool: it is not affiliated with npm, Inc., it reads only the official public npm registry and download APIs, and it is subject to their availability, rate limits and terms.

### Related actors

- [OSV Package Vulnerability Audit: npm, PyPI, Go, Maven](https://apify.com/atesen-software/osv-package-vulnerability-audit)
- [Stack Overflow & Stack Exchange Questions and Answers](https://apify.com/atesen-software/stack-exchange-questions)
- [Hugging Face Models Scraper: Downloads, Likes & Licenses](https://apify.com/atesen-software/huggingface-model-intel)

# Actor input Schema

## `packages` (type: `array`):

Up to 30 public lowercase names, including @scope/name. Clear this field when using searchQuery.

## `searchQuery` (type: `string`):

Official registry search query, up to 200 characters; use instead of packages.

## `maxPackages` (type: `integer`):

Limit unique direct or search packages processed; increase for batches.

## `maxRows` (type: `integer`):

Total package plus optional daily rows. Increase for batches or daily history. Status rows are excluded.

## `includeDownloads` (type: `boolean`):

Two official npm download requests per package.

## `includeDailyDownloads` (type: `boolean`):

Emit additional daily rows, bounded by dailyDays and maxRows.

## `dailyDays` (type: `integer`):

1–90 UTC days ending yesterday. Used only when daily history is enabled.

## Actor input object example

```json
{
  "packages": [
    "express"
  ],
  "maxPackages": 1,
  "maxRows": 1,
  "includeDownloads": true,
  "includeDailyDownloads": false,
  "dailyDays": 7
}
```

# Actor output Schema

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

No description

## `summary` (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 = {
    "packages": [
        "express"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("atesen-software/npm-package-intelligence").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 = { "packages": ["express"] }

# Run the Actor and wait for it to finish
run = client.actor("atesen-software/npm-package-intelligence").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 '{
  "packages": [
    "express"
  ]
}' |
apify call atesen-software/npm-package-intelligence --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,atesen-software/npm-package-intelligence"
        }
    }
}
```

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/VxD8JELWL6FxI5cK2/builds/ebe5ELMinUIO14ZKC/openapi.json
