semrush-api-client 1.0.11 → 1.0.12

package/README.md

@@ -34,6 +34,56 @@ client.getDomainOverview({ domain: "apple.com" });
 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.
+
+```ts
+// 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
+
+```sh
+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.

package/dist/client/index.d.ts

@@ -5,16 +5,20 @@ import { getRankDifference, getSemrushRank } from "../overview";
 import { getTrafficSummary } from "../trend";
 import { getUrlOverview, getUrlOrganicSearchKeywords, getUrlPaidSearchKeywords } from "../url";
 import { countApiUnits } from "../user";
+import { getBacklinksOverviewV4, getBacklinksHistoricalSummaryV4, getBacklinksV4, getReferringDomainsV4, getReferringIpsV4, getIndexedPagesV4, getAnchorsV4, getBacklinksScoreProfileV4, getBacklinksCompetitorsV4, getKeywordMetricsV4 } from "../v4";
+import { V4Response } from "../v4/types";
 export declare class SemrushAPIClient {
     private client;
     private api_key;
     BASE_URL: string;
     ANALYTICS_URL: string;
+    V4_URL: string;
     constructor({ api_key }: {
         api_key: string;
     });
     parseCsvToObjects(csvString: string, delimiter?: string): Record<string, string>[];
     get<T>(url: string, params?: Record<string, any>, outputObj?: boolean): Promise<T>;
+    getV4<T>(path: string, params?: Record<string, unknown>): Promise<V4Response<T>>;
     getDomainOverview: typeof getDomainOverview;
     getDomainOverviewOneDatabase: typeof getDomainOverviewOneDatabase;
     getDomainOverviewHistory: typeof getDomainOverviewHistory;
@@ -42,4 +46,14 @@ export declare class SemrushAPIClient {
     getUrlOrganicSearchKeywords: typeof getUrlOrganicSearchKeywords;
     getUrlPaidSearchKeywords: typeof getUrlPaidSearchKeywords;
     countApiUnits: typeof countApiUnits;
+    getBacklinksOverviewV4: typeof getBacklinksOverviewV4;
+    getBacklinksHistoricalSummaryV4: typeof getBacklinksHistoricalSummaryV4;
+    getBacklinksV4: typeof getBacklinksV4;
+    getReferringDomainsV4: typeof getReferringDomainsV4;
+    getReferringIpsV4: typeof getReferringIpsV4;
+    getIndexedPagesV4: typeof getIndexedPagesV4;
+    getAnchorsV4: typeof getAnchorsV4;
+    getBacklinksScoreProfileV4: typeof getBacklinksScoreProfileV4;
+    getBacklinksCompetitorsV4: typeof getBacklinksCompetitorsV4;
+    getKeywordMetricsV4: typeof getKeywordMetricsV4;
 }

package/dist/client/index.js

@@ -12,11 +12,13 @@ const overview_1 = require("../overview");
 const trend_1 = require("../trend");
 const url_1 = require("../url");
 const user_1 = require("../user");
+const v4_1 = require("../v4");
 class SemrushAPIClient {
     client;
     api_key;
     BASE_URL = "https://api.semrush.com/";
     ANALYTICS_URL = "https://api.semrush.com/analytics/";
+    V4_URL = "https://api.semrush.com/apis/v4/";
     constructor({ api_key }) {
         this.api_key = api_key;
         this.client = axios_1.default.create({
@@ -57,6 +59,26 @@ class SemrushAPIClient {
             }
         }
     }
+    // API v4 request: the key travels in the Authorization header and the
+    // response is a JSON { meta, data } envelope instead of v3's CSV body.
+    async getV4(path, params) {
+        try {
+            const response = await this.client.get(this.V4_URL + path, {
+                params,
+                headers: { Authorization: `Apikey ${this.api_key}` },
+            });
+            return response.data;
+        }
+        catch (error) {
+            if (axios_1.default.isAxiosError(error)) {
+                const body = error.response?.data;
+                const apiMessage = body?.error?.message;
+                const requestId = body?.meta?.request_id;
+                throw new Error(`Semrush v4 request failed (${path}): ${apiMessage ?? error.message}${error.response?.status ? ` (status: ${error.response.status})` : ""}${requestId ? ` (request_id: ${requestId})` : ""}`);
+            }
+            throw new Error(`Unexpected error: ${error}`);
+        }
+    }
     // Domain methods
     getDomainOverview = domain_1.getDomainOverview;
     getDomainOverviewOneDatabase = domain_1.getDomainOverviewOneDatabase;
@@ -91,5 +113,17 @@ class SemrushAPIClient {
     getUrlPaidSearchKeywords = url_1.getUrlPaidSearchKeywords;
     // User methods
     countApiUnits = user_1.countApiUnits;
+    // Backlinks methods (API v4)
+    getBacklinksOverviewV4 = v4_1.getBacklinksOverviewV4;
+    getBacklinksHistoricalSummaryV4 = v4_1.getBacklinksHistoricalSummaryV4;
+    getBacklinksV4 = v4_1.getBacklinksV4;
+    getReferringDomainsV4 = v4_1.getReferringDomainsV4;
+    getReferringIpsV4 = v4_1.getReferringIpsV4;
+    getIndexedPagesV4 = v4_1.getIndexedPagesV4;
+    getAnchorsV4 = v4_1.getAnchorsV4;
+    getBacklinksScoreProfileV4 = v4_1.getBacklinksScoreProfileV4;
+    getBacklinksCompetitorsV4 = v4_1.getBacklinksCompetitorsV4;
+    // Keyword methods (API v4)
+    getKeywordMetricsV4 = v4_1.getKeywordMetricsV4;
 }
 exports.SemrushAPIClient = SemrushAPIClient;

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 export * from "./client";
 export { Database } from "./type/general/database";
+export * from "./v4";

package/dist/index.js

@@ -20,3 +20,4 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const dotenv_1 = __importDefault(require("dotenv"));
 dotenv_1.default.config();
 __exportStar(require("./client"), exports);
+__exportStar(require("./v4"), exports);

package/dist/v4/backlinks/getAnchorsV4.d.ts

@@ -0,0 +1,5 @@
+import { SemrushAPIClient } from "../../client";
+import { V4Response } from "../types";
+import { BacklinksListArgs } from "./listParams";
+import { AnchorField, AnchorRow } from "./types";
+export declare function getAnchorsV4(this: SemrushAPIClient, args: BacklinksListArgs<AnchorField>): Promise<V4Response<AnchorRow[]>>;

package/dist/v4/backlinks/getAnchorsV4.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAnchorsV4 = getAnchorsV4;
+const listParams_1 = require("./listParams");
+// GET /apis/v4/backlinks/v1/anchors
+// Anchor texts used by the backlinks. v4 replacement for
+// type=backlinks_anchors. Defaults: order_by=domains_count, direction=DESC,
+// limit=100.
+async function getAnchorsV4(args) {
+    return this.getV4("backlinks/v1/anchors", (0, listParams_1.buildBacklinksListParams)(args));
+}

package/dist/v4/backlinks/getBacklinksCompetitorsV4.d.ts

@@ -0,0 +1,12 @@
+import { SemrushAPIClient } from "../../client";
+import { V4Direction, V4Format, V4Response } from "../types";
+import { CompetitorField, CompetitorRow } from "./types";
+export declare function getBacklinksCompetitorsV4(this: SemrushAPIClient, { domain, fields, orderBy, direction, limit, offset, format, }: {
+    domain: string;
+    fields?: CompetitorField[];
+    orderBy?: CompetitorField;
+    direction?: V4Direction;
+    limit?: number;
+    offset?: number;
+    format?: V4Format;
+}): Promise<V4Response<CompetitorRow[]>>;

package/dist/v4/backlinks/getBacklinksCompetitorsV4.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getBacklinksCompetitorsV4 = getBacklinksCompetitorsV4;
+// GET /apis/v4/backlinks/v1/competitors
+// Domains with a backlink profile similar to the target. Unlike the other
+// Backlinks v4 reports this one takes `domain`, not `url`/`scope`.
+// Defaults: order_by=similarity, direction=DESC, limit=100.
+async function getBacklinksCompetitorsV4({ domain, fields, orderBy, direction, limit, offset, format, }) {
+    return this.getV4("backlinks/v1/competitors", {
+        domain,
+        fields: fields?.join(","),
+        order_by: orderBy,
+        direction,
+        limit,
+        offset,
+        format,
+    });
+}

package/dist/v4/backlinks/getBacklinksHistoricalSummaryV4.d.ts

@@ -0,0 +1,12 @@
+import { SemrushAPIClient } from "../../client";
+import { V4Format, V4Response } from "../types";
+import { BacklinksScope, BacklinksSummaryField, BacklinksSummaryRow } from "./types";
+export declare function getBacklinksHistoricalSummaryV4(this: SemrushAPIClient, { url, scope, fields, limit, dateFrom, dateTo, format, }: {
+    url: string;
+    scope?: BacklinksScope;
+    fields?: BacklinksSummaryField[];
+    limit?: number;
+    dateFrom?: string;
+    dateTo?: string;
+    format?: V4Format;
+}): Promise<V4Response<BacklinksSummaryRow[]>>;

package/dist/v4/backlinks/getBacklinksHistoricalSummaryV4.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getBacklinksHistoricalSummaryV4 = getBacklinksHistoricalSummaryV4;
+// GET /apis/v4/backlinks/v1/summary
+// Month-by-month history of the headline backlink metrics. No v3 equivalent in
+// this client.
+async function getBacklinksHistoricalSummaryV4({ url, scope = "ROOT_DOMAIN", fields, limit, dateFrom, dateTo, format, }) {
+    return this.getV4("backlinks/v1/summary", {
+        url,
+        scope,
+        fields: fields?.join(","),
+        limit,
+        date_from: dateFrom,
+        date_to: dateTo,
+        format,
+    });
+}

package/dist/v4/backlinks/getBacklinksOverviewV4.d.ts

@@ -0,0 +1,9 @@
+import { SemrushAPIClient } from "../../client";
+import { V4Format, V4Response } from "../types";
+import { BacklinksOverviewData, BacklinksOverviewField, BacklinksScope } from "./types";
+export declare function getBacklinksOverviewV4(this: SemrushAPIClient, { url, scope, fields, format, }: {
+    url: string;
+    scope?: BacklinksScope;
+    fields?: BacklinksOverviewField[];
+    format?: V4Format;
+}): Promise<V4Response<BacklinksOverviewData>>;

package/dist/v4/backlinks/getBacklinksOverviewV4.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getBacklinksOverviewV4 = getBacklinksOverviewV4;
+// GET /apis/v4/backlinks/v1/overview
+// Current backlink totals for a target. v4 replacement for
+// type=backlinks_overview.
+async function getBacklinksOverviewV4({ url, scope = "ROOT_DOMAIN", fields, format, }) {
+    return this.getV4("backlinks/v1/overview", {
+        url,
+        scope,
+        fields: fields?.join(","),
+        format,
+    });
+}

package/dist/v4/backlinks/getBacklinksScoreProfileV4.d.ts

@@ -0,0 +1,8 @@
+import { SemrushAPIClient } from "../../client";
+import { V4Format, V4Response } from "../types";
+import { BacklinksScope, ScoreProfileData } from "./types";
+export declare function getBacklinksScoreProfileV4(this: SemrushAPIClient, { url, scope, format, }: {
+    url: string;
+    scope?: BacklinksScope;
+    format?: V4Format;
+}): Promise<V4Response<ScoreProfileData[]>>;

package/dist/v4/backlinks/getBacklinksScoreProfileV4.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getBacklinksScoreProfileV4 = getBacklinksScoreProfileV4;
+// GET /apis/v4/backlinks/v1/score-profile
+// Distribution of referring domains by Authority Score. No v3 equivalent in
+// this client. This endpoint takes no `fields` parameter.
+async function getBacklinksScoreProfileV4({ url, scope = "ROOT_DOMAIN", format, }) {
+    return this.getV4("backlinks/v1/score-profile", {
+        url,
+        scope,
+        format,
+    });
+}

package/dist/v4/backlinks/getBacklinksV4.d.ts

@@ -0,0 +1,5 @@
+import { SemrushAPIClient } from "../../client";
+import { V4Response } from "../types";
+import { BacklinksListArgs } from "./listParams";
+import { BacklinkField, BacklinkRow } from "./types";
+export declare function getBacklinksV4(this: SemrushAPIClient, args: BacklinksListArgs<BacklinkField>): Promise<V4Response<BacklinkRow[]>>;

package/dist/v4/backlinks/getBacklinksV4.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getBacklinksV4 = getBacklinksV4;
+const listParams_1 = require("./listParams");
+// GET /apis/v4/backlinks/v1/links
+// Individual backlinks pointing at the target. v4 replacement for
+// type=backlinks. Defaults: order_by=page_score, direction=DESC, limit=100.
+async function getBacklinksV4(args) {
+    return this.getV4("backlinks/v1/links", (0, listParams_1.buildBacklinksListParams)(args));
+}

package/dist/v4/backlinks/getIndexedPagesV4.d.ts

@@ -0,0 +1,5 @@
+import { SemrushAPIClient } from "../../client";
+import { V4Response } from "../types";
+import { BacklinksListArgs } from "./listParams";
+import { IndexedPageField, IndexedPageRow } from "./types";
+export declare function getIndexedPagesV4(this: SemrushAPIClient, args: BacklinksListArgs<IndexedPageField>): Promise<V4Response<IndexedPageRow[]>>;

package/dist/v4/backlinks/getIndexedPagesV4.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getIndexedPagesV4 = getIndexedPagesV4;
+const listParams_1 = require("./listParams");
+// GET /apis/v4/backlinks/v1/pages
+// Pages of the target that hold backlinks. v4 replacement for
+// type=backlinks_pages. Defaults: order_by=domains_count, direction=DESC,
+// limit=100.
+async function getIndexedPagesV4(args) {
+    return this.getV4("backlinks/v1/pages", (0, listParams_1.buildBacklinksListParams)(args));
+}

package/dist/v4/backlinks/getReferringDomainsV4.d.ts

@@ -0,0 +1,5 @@
+import { SemrushAPIClient } from "../../client";
+import { V4Response } from "../types";
+import { BacklinksListArgs } from "./listParams";
+import { ReferringDomainField, ReferringDomainRow } from "./types";
+export declare function getReferringDomainsV4(this: SemrushAPIClient, args: BacklinksListArgs<ReferringDomainField>): Promise<V4Response<ReferringDomainRow[]>>;

package/dist/v4/backlinks/getReferringDomainsV4.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getReferringDomainsV4 = getReferringDomainsV4;
+const listParams_1 = require("./listParams");
+// GET /apis/v4/backlinks/v1/ref-domains
+// Domains linking to the target. v4 replacement for type=backlinks_refdomains.
+// Defaults: order_by=backlinks_count, direction=DESC, limit=100.
+async function getReferringDomainsV4(args) {
+    return this.getV4("backlinks/v1/ref-domains", (0, listParams_1.buildBacklinksListParams)(args));
+}

package/dist/v4/backlinks/getReferringIpsV4.d.ts

@@ -0,0 +1,5 @@
+import { SemrushAPIClient } from "../../client";
+import { V4Response } from "../types";
+import { BacklinksListArgs } from "./listParams";
+import { ReferringIpField, ReferringIpRow } from "./types";
+export declare function getReferringIpsV4(this: SemrushAPIClient, args: BacklinksListArgs<ReferringIpField>): Promise<V4Response<ReferringIpRow[]>>;

package/dist/v4/backlinks/getReferringIpsV4.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getReferringIpsV4 = getReferringIpsV4;
+const listParams_1 = require("./listParams");
+// GET /apis/v4/backlinks/v1/ref-ips
+// IP addresses hosting the referring domains. No v3 equivalent in this client.
+// Defaults: order_by=domains_count, direction=DESC, limit=100.
+async function getReferringIpsV4(args) {
+    return this.getV4("backlinks/v1/ref-ips", (0, listParams_1.buildBacklinksListParams)(args));
+}

package/dist/v4/backlinks/index.d.ts

@@ -0,0 +1,11 @@
+export { getBacklinksOverviewV4 } from "./getBacklinksOverviewV4";
+export { getBacklinksHistoricalSummaryV4 } from "./getBacklinksHistoricalSummaryV4";
+export { getBacklinksV4 } from "./getBacklinksV4";
+export { getReferringDomainsV4 } from "./getReferringDomainsV4";
+export { getReferringIpsV4 } from "./getReferringIpsV4";
+export { getIndexedPagesV4 } from "./getIndexedPagesV4";
+export { getAnchorsV4 } from "./getAnchorsV4";
+export { getBacklinksScoreProfileV4 } from "./getBacklinksScoreProfileV4";
+export { getBacklinksCompetitorsV4 } from "./getBacklinksCompetitorsV4";
+export * from "./types";
+export type { BacklinksListArgs } from "./listParams";

package/dist/v4/backlinks/index.js

@@ -0,0 +1,36 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getBacklinksCompetitorsV4 = exports.getBacklinksScoreProfileV4 = exports.getAnchorsV4 = exports.getIndexedPagesV4 = exports.getReferringIpsV4 = exports.getReferringDomainsV4 = exports.getBacklinksV4 = exports.getBacklinksHistoricalSummaryV4 = exports.getBacklinksOverviewV4 = void 0;
+var getBacklinksOverviewV4_1 = require("./getBacklinksOverviewV4");
+Object.defineProperty(exports, "getBacklinksOverviewV4", { enumerable: true, get: function () { return getBacklinksOverviewV4_1.getBacklinksOverviewV4; } });
+var getBacklinksHistoricalSummaryV4_1 = require("./getBacklinksHistoricalSummaryV4");
+Object.defineProperty(exports, "getBacklinksHistoricalSummaryV4", { enumerable: true, get: function () { return getBacklinksHistoricalSummaryV4_1.getBacklinksHistoricalSummaryV4; } });
+var getBacklinksV4_1 = require("./getBacklinksV4");
+Object.defineProperty(exports, "getBacklinksV4", { enumerable: true, get: function () { return getBacklinksV4_1.getBacklinksV4; } });
+var getReferringDomainsV4_1 = require("./getReferringDomainsV4");
+Object.defineProperty(exports, "getReferringDomainsV4", { enumerable: true, get: function () { return getReferringDomainsV4_1.getReferringDomainsV4; } });
+var getReferringIpsV4_1 = require("./getReferringIpsV4");
+Object.defineProperty(exports, "getReferringIpsV4", { enumerable: true, get: function () { return getReferringIpsV4_1.getReferringIpsV4; } });
+var getIndexedPagesV4_1 = require("./getIndexedPagesV4");
+Object.defineProperty(exports, "getIndexedPagesV4", { enumerable: true, get: function () { return getIndexedPagesV4_1.getIndexedPagesV4; } });
+var getAnchorsV4_1 = require("./getAnchorsV4");
+Object.defineProperty(exports, "getAnchorsV4", { enumerable: true, get: function () { return getAnchorsV4_1.getAnchorsV4; } });
+var getBacklinksScoreProfileV4_1 = require("./getBacklinksScoreProfileV4");
+Object.defineProperty(exports, "getBacklinksScoreProfileV4", { enumerable: true, get: function () { return getBacklinksScoreProfileV4_1.getBacklinksScoreProfileV4; } });
+var getBacklinksCompetitorsV4_1 = require("./getBacklinksCompetitorsV4");
+Object.defineProperty(exports, "getBacklinksCompetitorsV4", { enumerable: true, get: function () { return getBacklinksCompetitorsV4_1.getBacklinksCompetitorsV4; } });
+__exportStar(require("./types"), exports);

package/dist/v4/backlinks/listParams.d.ts

@@ -0,0 +1,14 @@
+import { V4Direction, V4Format } from "../types";
+import { BacklinksScope } from "./types";
+export type BacklinksListArgs<TField extends string> = {
+    url: string;
+    scope: BacklinksScope;
+    fields?: TField[];
+    orderBy?: TField;
+    direction?: V4Direction;
+    limit?: number;
+    offset?: number;
+    filter?: string;
+    format?: V4Format;
+};
+export declare function buildBacklinksListParams<TField extends string>({ url, scope, fields, orderBy, direction, limit, offset, filter, format, }: BacklinksListArgs<TField>): Record<string, unknown>;

package/dist/v4/backlinks/listParams.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildBacklinksListParams = buildBacklinksListParams;
+function buildBacklinksListParams({ url, scope, fields, orderBy, direction, limit, offset, filter, format, }) {
+    return {
+        url,
+        scope,
+        fields: fields?.join(","),
+        order_by: orderBy,
+        direction,
+        limit,
+        offset,
+        filter,
+        format,
+    };
+}

package/dist/v4/backlinks/types.d.ts

@@ -0,0 +1,95 @@
+export type BacklinksScope = "ROOT_DOMAIN" | "SUBDOMAIN" | "SUBFOLDER" | "PAGE";
+export type BacklinksOverviewField = "backlinks_count" | "domains_count" | "follows_count" | "forms_count" | "frames_count" | "images_count" | "ip_class_c_count" | "ips_count" | "lost_count" | "new_count" | "nofollows_count" | "score" | "sponsored_count" | "texts_count" | "ugc_count" | "urls_count";
+export type BacklinksOverviewData = Partial<Record<BacklinksOverviewField, number>>;
+export type BacklinksSummaryField = "backlinks_count" | "domains_count" | "follows_count" | "month_date" | "score";
+export type BacklinksSummaryRow = {
+    backlinks_count?: number;
+    domains_count?: number;
+    follows_count?: number;
+    month_date?: string;
+    score?: number;
+    url?: string;
+};
+export type BacklinkField = "anchor" | "domain_score" | "external_links_count" | "first_seen_at" | "image_alt" | "image_url" | "internal_links_count" | "ip_address" | "is_form" | "is_frame" | "is_image" | "is_lost" | "is_new" | "is_nofollow" | "is_sitewide_main" | "is_sponsored" | "is_ugc" | "lang" | "last_seen_at" | "page_score" | "redirect_url" | "response_code" | "source_domain" | "source_size" | "source_title" | "source_url" | "target_title" | "target_url";
+export type BacklinkRow = {
+    anchor?: string;
+    domain_score?: number;
+    external_links_count?: number;
+    first_seen_at?: string;
+    image_alt?: string;
+    image_url?: string;
+    internal_links_count?: number;
+    ip_address?: string;
+    is_form?: boolean;
+    is_frame?: boolean;
+    is_image?: boolean;
+    is_lost?: boolean;
+    is_new?: boolean;
+    is_nofollow?: boolean;
+    is_sitewide_main?: boolean;
+    is_sponsored?: boolean;
+    is_ugc?: boolean;
+    lang?: string;
+    last_seen_at?: string;
+    page_score?: number;
+    redirect_url?: string;
+    response_code?: number;
+    source_domain?: string;
+    source_size?: number;
+    source_title?: string;
+    source_url?: string;
+    target_title?: string;
+    target_url?: string;
+};
+export type ReferringDomainField = "backlinks_count" | "country" | "domain" | "domain_score" | "first_seen_at" | "ip_address" | "is_follow" | "is_lost" | "is_new" | "last_seen_at";
+export type ReferringDomainRow = Partial<{
+    backlinks_count: number;
+    country: string;
+    domain: string;
+    domain_score: number;
+    first_seen_at: string;
+    ip_address: string;
+    is_follow: boolean;
+    is_lost: boolean;
+    is_new: boolean;
+    last_seen_at: string;
+}>;
+export type ReferringIpField = "backlinks_count" | "country" | "domains_count" | "first_seen_at" | "ip_address" | "last_seen_at";
+export type ReferringIpRow = Partial<{
+    backlinks_count: number;
+    country: string;
+    domains_count: number;
+    first_seen_at: string;
+    ip_address: string;
+    last_seen_at: string;
+}>;
+export type IndexedPageField = "backlinks_count" | "domains_count" | "external_links_count" | "first_seen_at" | "internal_links_count" | "last_seen_at" | "response_code" | "source_title" | "source_url";
+export type IndexedPageRow = Partial<{
+    backlinks_count: number;
+    domains_count: number;
+    external_links_count: number;
+    first_seen_at: string;
+    internal_links_count: number;
+    last_seen_at: string;
+    response_code: number;
+    source_title: string;
+    source_url: string;
+}>;
+export type AnchorField = "anchor" | "backlinks_count" | "domains_count" | "first_seen_at" | "last_seen_at";
+export type AnchorRow = Partial<{
+    anchor: string;
+    backlinks_count: number;
+    domains_count: number;
+    first_seen_at: string;
+    last_seen_at: string;
+}>;
+export type ScoreProfileData = Partial<{
+    domain_score: number;
+    domains_count: number;
+}>;
+export type CompetitorField = "common_refdomains" | "domain" | "similarity";
+export type CompetitorRow = Partial<{
+    common_refdomains: number;
+    domain: string;
+    similarity: number;
+}>;

package/dist/v4/backlinks/types.js

@@ -0,0 +1,4 @@
+"use strict";
+// Types shared by the v4 Backlinks endpoints
+// (https://developer.semrush.com/api/v4/seo/backlinks/).
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/v4/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./types";
+export * from "./backlinks";
+export * from "./keyword";

package/dist/v4/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types"), exports);
+__exportStar(require("./backlinks"), exports);
+__exportStar(require("./keyword"), exports);

package/dist/v4/keyword/getKeywordMetricsV4.d.ts

@@ -0,0 +1,19 @@
+import { SemrushAPIClient } from "../../client";
+import { V4Format, V4Response } from "../types";
+export type KeywordIntent = "COMMERCIAL" | "INFORMATIONAL" | "NAVIGATIONAL" | "TRANSACTIONAL";
+export type KeywordMetricsData = {
+    competitive_density?: number;
+    cpc?: string;
+    intents?: KeywordIntent[];
+    keyword_difficulty?: number;
+    number_of_results?: string;
+    search_volume?: string;
+    serp_features?: string[];
+    trends?: number[];
+};
+export declare function getKeywordMetricsV4(this: SemrushAPIClient, { keyword, country, month, format, }: {
+    keyword: string;
+    country: string;
+    month?: string;
+    format?: V4Format;
+}): Promise<V4Response<KeywordMetricsData>>;

package/dist/v4/keyword/getKeywordMetricsV4.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getKeywordMetricsV4 = getKeywordMetricsV4;
+// GET /apis/v4/keywords/v1/metrics
+// Volume, difficulty, CPC, intents, SERP features and trend for one keyword.
+// v4 replacement for the deprecated v3 phrase_this / phrase_kdi reports.
+// Price: 20 API units per request.
+async function getKeywordMetricsV4({ keyword, country, month, format, }) {
+    if (keyword.length < 1 || keyword.length > 255) {
+        throw new Error("keyword must be between 1 and 255 characters.");
+    }
+    if (month && !/^\d{4}-\d{2}$/.test(month)) {
+        throw new Error("Invalid month format. Format: YYYY-MM");
+    }
+    return this.getV4("keywords/v1/metrics", {
+        keyword,
+        country,
+        month,
+        format,
+    });
+}

package/dist/v4/keyword/index.d.ts

@@ -0,0 +1,2 @@
+export { getKeywordMetricsV4 } from "./getKeywordMetricsV4";
+export type { KeywordIntent, KeywordMetricsData, } from "./getKeywordMetricsV4";

package/dist/v4/keyword/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getKeywordMetricsV4 = void 0;
+var getKeywordMetricsV4_1 = require("./getKeywordMetricsV4");
+Object.defineProperty(exports, "getKeywordMetricsV4", { enumerable: true, get: function () { return getKeywordMetricsV4_1.getKeywordMetricsV4; } });

package/dist/v4/types.d.ts

@@ -0,0 +1,20 @@
+export type V4Format = "json" | "csv";
+export type V4Direction = "ASC" | "DESC";
+export type V4Meta = {
+    request_id: string;
+    status_code: number;
+    success: boolean;
+    [key: string]: unknown;
+};
+export type V4Response<T> = {
+    meta: V4Meta;
+    data: T;
+};
+export type V4ErrorBody = {
+    meta?: Partial<V4Meta>;
+    error?: {
+        code: number;
+        message: string;
+        retryable?: boolean;
+    };
+};

package/dist/v4/types.js

@@ -0,0 +1,5 @@
+"use strict";
+// Shared types for the Semrush API v4 (https://api.semrush.com/apis/v4/).
+// v4 differs from v3: key goes in the `Authorization: Apikey <key>` header,
+// responses are JSON envelopes ({ meta, data }) instead of CSV.
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "semrush-api-client",
-  "version": "1.0.11",
+  "version": "1.0.12",
   "description": "",
   "license": "Apache-2.0",
   "main": "dist/index.js",
@@ -18,7 +18,9 @@
     "release": "bash scripts/release.sh",
     "release:minor": "bash scripts/release.sh minor",
     "release:major": "bash scripts/release.sh major",
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "test:endpoints": "tsx test/test_endpoints.ts",
+    "test:endpoints:v4": "tsx test/test_v4_endpoints.ts"
   },
   "engines": {
     "node": ">=20"
@@ -38,6 +40,7 @@
   ],
   "devDependencies": {
     "@types/node": "^22.15.30",
+    "tsx": "^4.23.1",
     "typescript": "^5.9.3"
   }
 }