Livewire API

The Livewire API provides programmatic access to the full range of data, statistics, and information collected by the seoClarity platform. It is designed to be simple to use and flexible enough to accommodate a wide range of integration needs, from pulling data into internal warehouses to building custom applications powered by seoClarity data.

The API is RESTful and returns results in XML format via standard HTTP requests. JSON and CSV are also supported on most endpoints via the wt parameter.

Requirements

To get started with the Livewire API you will need:

1. An active seoClarity account with API access
2. Familiarity with how to use a REST API
3. A Livewire API access token

To obtain an API token, follow the instructions HERE or email support@seoclarity.net. A unique token is generated per domain. If API access is needed across multiple domains, a separate token is required for each.

Keep Your Token Secure Your API token is a sensitive credential. Store and protect it the same way you would an account password. Never share it publicly or include it in client-facing documentation.

Limits & Quotas

Query Limits

API call quotas are based on your subscription and the number of keywords tracked in the platform. The standard ratio is 31 API calls per month for each tracked keyword.

• Quotas are set at the domain + user level
• An administrator can distribute the quota across authorized users
• Contact your Client Success Manager to adjust limits or distribution

Rate Limits

Limit requests to no more than 1 per second. If you need to query faster, contact support@seoclarity.net to discuss options.

Row Limits & Pagination

To retrieve more than 100 rows, use the offset parameter to page through results. Set the offset to the starting row of the next batch and repeat until the full dataset is retrieved.

Pricing

Data for any element you already track in seoClarity is available through the Livewire API at no additional charge. For example, ranking data for tracked keywords is included in your subscription.

Access to data outside your tracked elements — such as search volume for untracked keywords — is available as a paid add-on. Methods that incur an additional charge are noted in the endpoint documentation below.

Additional datasets and API methods (including seoclarity.dev) are available by request. Contact your Client Success Manager or support@seoclarity.net for details.

Available Endpoints

Help & Discovery

GET /help

Returns a list of all available API commands.

• Cost: Free
• Request: http://api.seoclarity.net/seoClarity/help

<!-- Sample Response -->
<commands>
  <command>
    <name>keyword</name>
    <version>v2.0</version>
    <description>Query keyword rank</description>
  </command>
  <command>
    <name>tag</name>
    <version>v1.0</version>
    <description>Query tag</description>
  </command>
</commands>

GET /help/{command}

Returns parameter documentation for a specific API command.

• Cost: Free
• Request: https://api.seoclarity.net/seoClarity/help/{command}
• Example: http://api.seoclarity.net/seoClarity/help/keyword

Managed Elements

GET /geturl - Managed Pages

Returns all managed URLs tracked in the platform.

• Cost: Free
• Request: http://api.seoclarity.net/seoClarity/geturl?access_token=XXXXXXXXXX&limit=X&offset=X

<!-- Sample Response -->
<Urls>
  <url>
    <targetUrl>http://www.example.com/</targetUrl>
  </url>
  <url>
    <targetUrl>http://www.example.com/page/</targetUrl>
  </url>
</Urls>

GET /tag - Keyword / Page Tags

Returns a list of keyword and/or page tags in the account along with the unique ID assigned to each. Tag IDs can be used with other tag endpoints to retrieve more granular data.

• Cost: Free
• Request: http://api.seoclarity.net/seoClarity/tag?access_token=XXXXXXXXXX&type=0&limit=10&offset=0

// Sample Response (JSON)
[
  {"tagId":"2","tagName":"Florida","tagType":"Url Tag"},
  {"tagId":"2622","tagName":"Alabama","tagType":"Url Tag"},
  {"tagId":"3210","tagName":"Top Ranked Keywords","tagType":"Keyword Tag"}
]

GET /keyword - Keyword Rankings

Returns ranking data for keywords tracked in the platform. Supports date ranges up to 30 days and returns rankings for your domain as well as Universal Competitors.

• Cost: Free
• Request: http://api.seoclarity.net/seoClarity/keyword?access_token=XXXXXXXXXX&engine=XXXX&market=XXXX&sdate=XXXX&edate=XXXX

// Sample Response
{
  "keyword name": "string",
  "date": "string",
  "highestTrueRank": "string",
  "highestWebRank": "string",
  "highestRankURL": "string",
  "avgSearchVolume": "string",
  "rank": "string",
  "preferredLandingPage": "string",
  "PLPTrueRank": "string",
  "PLPWebRank": "string"
}

GET /tagsummary - Tag Summary

Returns summarized analytics, rank, and metrics for a specific tag.

• Cost: Free
• Request: http://api.seoclarity.net/seoClarity/tagsummary?access_token=XXXXXXXXXX&tagid=XXXX&sdate=XXXX&edate=XXXX

GET /tagdetail - Tag Detail

Returns keyword or page level detail for a specific tag.

• Cost: Free
• Request: http://api.seoclarity.net/seoClarity/tagdetail?access_token=XXXXXXXXXX&tagid=XXX

Tag Management

GET /addremovekeywords - Add / Remove Keywords

Add or remove managed keywords from Rank Intelligence.

• Cost: Free / Paid (depending on subscription)
• Request: http://api.seoclarity.net/seoClarity/addremovekeywords?access_token=XXXXXXXXXX&keywordlist=XXXXXX&type=XXXXX

GET /addtags - Add Tags

Creates new keyword or page tags.

• Cost: Free
• Request: http://api.seoclarity.net/seoClarity/addtags?access_token=XXXXXXXXXX&tags=tagname&type=2

GET /updatetag - Update Tags

Updates the name of an existing tag.

• Cost: Free
• Request: http://api.seoclarity.net/seoClarity/updatetag?access_token=XXXXXXXXXX&tagidname=xxxxx!_!xxxx

GET /deletetags - Delete Tags

Deletes existing tags.

• Cost: Free
• Request: http://api.seoclarity.net/seoClarity/deletetags?access_token=XXXXXXXXXX&tagIds=xxxxx&type=2

Bulk Rankings (Rank Intelligence)

Provides richer structured ranking data in JSON format. Supports access to ranking extracts from the last 12 months and integrates with Storage Settings for automated delivery to Amazon S3, FTP, or GCS.

POST /task/v1/dailyRanking/ranking

Creates a task to retrieve ranking URLs for your domain and Universal Competitors.

• Cost: Included with most subscriptions
• Endpoint: https://api.seoclarity.net/seoClarity/task/v1/dailyRanking/ranking

// Sample Request
{
  "device": "desktop",
  "top": 10,
  "startDate": 20250101,
  "endDate": 20250103,
  "query": {
    "filters": [
      { "name": "domains", "operation": "ct", "value": "www.example.com" },
      { "name": "rank", "operation": "between", "value": "[1-10]" },
      { "name": "keyword", "operation": "ct", "value": "your keyword" }
    ]
  }
}

Available Parameters:

POST /task/v1/dailyRanking/serpfeature

Creates a task to identify SERP feature rankings for your domain or competitors.

• Cost: Included with most subscriptions
• Endpoint: https://api.seoclarity.net/seoClarity/task/v1/dailyRanking/serpfeature

Same parameters as /dailyRanking/ranking with additional filter support for brands.

Other Datasets

Backlinks (Paid)

Retrieves backlink data for any URL from seoClarity's database. Additional charge applies per call — contact sales@seoclarity.net for pricing.

GET /contentDistributionResource - Content Distribution

Returns Content Distribution Tracker table data.

• Cost: Free
• Request: http://api.seoclarity.net/seoClarity/contentDistributionResource?access_token=XXX&cid=XXX&wt=json

Content Similarity Check (SimCheck)

Compares content similarity between any two pages using NLP analysis.

• Cost: Free
• Request (POST): http://api.seoclarity.net/similarity/check?main_url=XXXX&sub_urls=XXXX&access_token=XXXX

Domain Settings (SCIM User Administration)

The Livewire API supports SCIM (System for Cross-domain Identity Management) for automated user management. Contact support@seoclarity.net to enable this feature.

SCIM is available on request Contact support to get started before using these endpoints.

Permission levels: sysadmin, standard, readonly standard

Supported filter operations for List Users:

API Usage Report

GET /usage

Returns a token usage report for a given date range.

• Cost: Free
• Request: http://api.seoclarity.net/seoClarity/usage?access_token=XXXXXXXXXX&sdate=yyyymmdd&edate=yyyymmdd&group=XXX