trackserps

n8n community node for TrackSERPs SEO Rank Tracking

Package Information

Released: this month
Downloads: 0 weekly / 0 monthly
Latest Version: 1.1.0
Author: TrackSERPs

Documentation

TrackSERPs n8n Community Node (@trackserps/n8n-nodes-trackserps)

This is an n8n community node package that integrates TrackSERPs into your self-hosted or cloud n8n automation workflows.

Track keyword rankings, receive instant webhook alerts when rankings change or runs finish, dynamically add keywords, and query credit balances and usage.


Features

  • Credentials:
    • TrackSERPs API: Configurable API Key (ts_live_... or ts_test_...) with password masking and configurable Base URL (default https://api.trackserps.com/v1).
    • Built-in credential validation against GET /account.
  • TrackSERPs Node (Regular Node):
    • Project:
      • Create: Create a new tracking project with domain, location code, folder name/ID, schedule, and optional initial keywords.
      • Get Many: List all projects with cursor-based pagination.
      • Get: Retrieve specific project metadata.
    • Lookup:
      • Create: Submit one-off SERP rank lookups (1 credit per item) without creating project keywords. Supports single item or multiple items via fixedCollection, plus fresh cache bypass toggle.
      • Get: Retrieve status, rank position, and top competitors for a lookup ID.
      • Get Many: List historical one-off rank lookups with optional status filter.
    • Keyword:
      • Get Many: List tracked keywords for a project with optional tag filters.
      • Add: Upsert new keywords (one per line or comma-separated) with device overrides, location overrides, and tags. Returns credit estimates before and after.
      • Delete: Archive a keyword by ID.
    • Ranking:
      • Get Latest: Retrieve current ranking positions, 7-day and 30-day changes, URLs, and SERP features.
      • Get History: Query historical rankings across custom date ranges (YYYY-MM-DD).
    • Run:
      • Start: Trigger an on-demand rank check. Includes a Dry Run toggle to preview credit requirements, optional Keyword IDs for targeted checks, and a Fresh toggle to bypass cache.
      • Get: Check execution status (queued, running, completed, failed).
      • Get Latest: Retrieve the most recent check results.
    • Usage:
      • Get: Query monthly credit balances, remaining quota, and API rate limits.
  • TrackSERPs Trigger Node (Webhook Node):
    • Automates webhook registration on workflow activation (POST /webhooks) and cleanup on deactivation (DELETE /webhooks/{id}).
    • Supported events: rankings.updated, run.completed, run.failed, lookup.completed, alert.triggered, credits.low, credits.exhausted.
    • Unroll Ranking Changes: Emits individual workflow executions per changed keyword for easy downstream routing (e.g., Slack alerts, Notion updates).

Installation in n8n

Option A: Install via n8n Community Nodes (Recommended)

  1. Open your self-hosted n8n instance.
  2. Go to Settings > Community Nodes.
  3. Click Install a community node.
  4. Enter @trackserps/n8n-nodes-trackserps.
  5. Check the box agreeing to the risks of community nodes and click Install.

Option B: Manual Installation (Docker / Self-Hosted)

Inside your n8n root directory (or container):

npm install @trackserps/n8n-nodes-trackserps

Restart your n8n instance.


Development & Testing

  1. Install Dependencies:
    cd integrations/n8n
    npm install
    
  2. Build TypeScript & Assets:
    npm run build
    
    Compiles TypeScript files to ./dist and copies node icon assets.
  3. Run Unit Tests:
    npm test
    
    Executes automated tests validating credentials configuration, query parameter building, body serialization, and node definitions.

Publishing to npm (For Maintainers)

  1. Ensure the build passes:
    cd integrations/n8n
    npm run build && npm test
    
  2. Verify package metadata in package.json (name: "@trackserps/n8n-nodes-trackserps").
  3. Log in to your npm maintainer account:
    npm login
    
  4. Publish:
    npm publish --access public
    
  5. Once published to the npm registry, the package is immediately discoverable inside n8n's Community Nodes browser.

Screenshots Placeholder Reference

The following descriptions define the expected visual presentation in n8n:

  1. [Screenshot Placeholder: n8n TrackSERPs Credential Modal]
    • Description: Modal window in n8n titled "TrackSERPs API Credential". Displays masked input field for "API Key" (••••••••), and "Base URL" populated with https://api.trackserps.com/v1. Circular status pill in top right showing green checkmark "Connection tested successfully".
  2. [Screenshot Placeholder: n8n TrackSERPs Node - Add Keywords]
    • Description: n8n workflow canvas showing the TrackSERPs node open on right panel. "Resource" dropdown set to "Keyword". "Operation" set to "Add". "Project ID" populated with expression {{ $json.projectId }}. Multi-line "Keywords" text area showing input phrases. Output preview panel showing returned JSON with estimated_monthly_credits: { before: 120, after: 180 }.
  3. [Screenshot Placeholder: n8n TrackSERPs Trigger Node]
    • Description: n8n canvas showing start node titled "TrackSERPs Trigger". Properties panel showing "Events" multi-select with pills for "Rankings Updated" and "Alert Triggered". Toggle switch for "Unroll Ranking Changes" set to active. Workflow status indicator in upper right showing "Active".

Discussion