semrush-api-client

A Node.js/TypeScript client for accessing the SEMrush API easily.

Installation

npm install semrush-api-client

Usage Example

First, set your SEMrush API key in your environment variables (e.g., in a .env file):

SEMRUSH_API_KEY=your_api_key_here

Then, use the client in your code:

import { SemrushAPIClient } from "semrush-api-client";
const client = new SemrushAPIClient({
  api_key: process.env.SEMRUSH_API_KEY!,
});

// Get domain rank
client.getDomainOverview({ domain: "apple.com" });

// Get keyword data
client.getKeywordOverview({ phrase: "apple" });

API v4

Semrush's v4 endpoints are also available. They are suffixed with V4, take an Authorization: Apikey header instead of a key query param, and return a JSON { meta, data } envelope instead of CSV rows.

// Keyword Reports v4 (replaces the deprecated v3 keyword reports)
const { data } = await client.getKeywordMetricsV4({
  keyword: "seo tools",
  country: "us", // ISO 3166-1 alpha-2
  // month: "2026-06",  // Optional, defaults to the current month
});
console.log(data.search_volume, data.keyword_difficulty, data.intents);

// Backlinks v4
await client.getBacklinksOverviewV4({ url: "apple.com", scope: "ROOT_DOMAIN" });
await client.getBacklinksV4({ url: "apple.com", scope: "ROOT_DOMAIN", limit: 10 });

| Method | Endpoint | | --- | --- | | getKeywordMetricsV4 | /apis/v4/keywords/v1/metrics | | getBacklinksOverviewV4 | /apis/v4/backlinks/v1/overview | | getBacklinksHistoricalSummaryV4 | /apis/v4/backlinks/v1/summary | | getBacklinksV4 | /apis/v4/backlinks/v1/links | | getReferringDomainsV4 | /apis/v4/backlinks/v1/ref-domains | | getReferringIpsV4 | /apis/v4/backlinks/v1/ref-ips | | getIndexedPagesV4 | /apis/v4/backlinks/v1/pages | | getAnchorsV4 | /apis/v4/backlinks/v1/anchors | | getBacklinksScoreProfileV4 | /apis/v4/backlinks/v1/score-profile | | getBacklinksCompetitorsV4 | /apis/v4/backlinks/v1/competitors |

scope accepts ROOT_DOMAIN, SUBDOMAIN, SUBFOLDER or PAGE (it replaces v3's target_type). The list reports take fields, orderBy, direction, limit, offset and filter.

Note: v4 access is granted separately from v3. A key that works for the v3 reports can still return 401 Unauthorized on v4 — check that your Semrush plan and API key are enabled for API v4.

Running the endpoint smoke tests

npm run test:endpoints      # v3
npm run test:endpoints:v4   # v4

Both read SEMRUSH_API_KEY from .env and consume real API units.

Contributing

Contributions are welcome! Feel free to open issues or submit pull requests to improve this project.

License

See LICENSE.