SEO Analytics API

The SEO Analytics API provides comprehensive access to search engine optimization metrics, keyword performance, and website analytics through Cognix's SEO monitoring infrastructure.

---

Getting Started

Authentication

All API requests require authentication using a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Please contact support at cognix.au/contact-us to obtain an API key.

---

API Reference

1. Keyword Rankings API

Track keyword positions and performance across search engines.

Endpoint: GET https://api.cognix.au/v1/seo/rankings

Query Parameters

Parameter	Type	Required	Description
domain	string	Yes	Target domain
date_range	string	Yes	Date range format: YYYY-MM-DDtoYYYY-MM-DD
keywords	string	No	Comma-separated list of keywords
search_engine	string	No	Specific search engine (google, bing)
location	string	No	Geographic location (ISO country code)

Example Response

{
  "status": "success",
  "data": {
    "domain": "example.com",
    "timeframe": {
      "start": "2024-01-01",
      "end": "2024-01-31"
    },
    "rankings": [
      {
        "keyword": "digital marketing",
        "current_position": 3,
        "previous_position": 5,
        "search_volume": 12500,
        "search_engine": "google",
        "location": "AU",
        "trend": "+2"
      }
    ],
    "summary": {
      "total_keywords": 150,
      "improved_positions": 45,
      "declined_positions": 12,
      "unchanged": 93
    }
  }
}

---

2. Technical SEO API

Analyze website technical health and SEO performance.

Endpoint: GET https://api.cognix.au/v1/seo/technical

Query Parameters

Parameter	Type	Required	Description
domain	string	Yes	Target domain
scan_type	string	No	Type of scan (full, quick, specific)
checks	string	No	Comma-separated list of specific checks

Example Response

{
  "status": "success",
  "data": {
    "domain_health": {
      "mobile_friendly": true,
      "https_status": "valid",
      "robots_txt": "valid",
      "sitemap_status": "valid",
      "core_web_vitals": {
        "lcp": "good",
        "fid": "good",
        "cls": "needs_improvement"
      }
    },
    "issues": {
      "critical": 0,
      "warnings": 3,
      "notices": 8
    },
    "page_speed": {
      "mobile_score": 85,
      "desktop_score": 92
    }
  }
}

---

3. Backlink Analysis API

Monitor backlink profile and domain authority metrics.

Endpoint: GET https://api.cognix.au/v1/seo/backlinks

Query Parameters

Parameter	Type	Required	Description
domain	string	Yes	Target domain
date_range	string	Yes	Date range format: YYYY-MM-DDtoYYYY-MM-DD
filter	string	No	Filter by link type or status

Example Response

{
  "status": "success",
  "data": {
    "summary": {
      "total_backlinks": 15000,
      "referring_domains": 2500,
      "domain_authority": 65,
      "new_links_30d": 150
    },
    "link_quality": {
      "follow": 12000,
      "nofollow": 3000,
      "dofollow_ratio": 0.8
    },
    "anchor_text": [
      {
        "text": "brand name",
        "occurrences": 450,
        "percentage": 3
      }
    ],
    "top_referring_domains": [
      {
        "domain": "example.org",
        "links": 25,
        "authority": 75
      }
    ]
  }
}

---

4. Content Performance API

Analyze content performance and SEO metrics.

Endpoint: GET https://api.cognix.au/v1/seo/content

Query Parameters

Parameter	Type	Required	Description
domain	string	Yes	Target domain
url	string	No	Specific page URL
metrics	string	No	Specific metrics to analyze

Example Response

{
  "status": "success",
  "data": {
    "page_metrics": {
      "word_count": 1500,
      "readability_score": 65,
      "keyword_density": {
        "primary": 2.3,
        "secondary": 1.8
      }
    },
    "seo_elements": {
      "title": {
        "length": 58,
        "status": "optimal"
      },
      "meta_description": {
        "length": 155,
        "status": "optimal"
      },
      "h1_tags": {
        "count": 1,
        "status": "optimal"
      }
    },
    "engagement": {
      "average_time": 180,
      "bounce_rate": 45,
      "social_shares": 125
    }
  }
}

---

5. Competitor Analysis API

Compare SEO metrics against competitors.

Endpoint: GET https://api.cognix.au/v1/seo/competitors

Query Parameters

Parameter	Type	Required	Description
domain	string	Yes	Your domain
competitors	string	Yes	Comma-separated list of competitor domains
metrics	string	No	Specific metrics to compare

Example Response

{
  "status": "success",
  "data": {
    "keyword_overlap": [
      {
        "competitor": "competitor1.com",
        "shared_keywords": 250,
        "unique_keywords": 1500,
        "ranking_distribution": {
          "top_3": 45,
          "top_10": 150
        }
      }
    ],
    "market_share": {
      "visibility_score": 35,
      "competitor_scores": {
        "competitor1.com": 42,
        "competitor2.com": 28
      }
    },
    "gap_analysis": {
      "opportunity_keywords": 150,
      "threat_keywords": 75
    }
  }
}

---

Error Handling

Response Codes

Code	Description
200	Success - Request completed successfully
400	Bad Request - Invalid parameters or malformed request
401	Unauthorized - Invalid or missing API key
403	Forbidden - Valid API key but insufficient permissions
404	Not Found - Requested resource doesn't exist
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Server-side error occurred
503	Service Unavailable - Temporary server maintenance

Error Response Format

{
  "status": "error",
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {
      "field": "Additional context about the error",
      "suggestion": "Recommended action to resolve the error"
    }
  },
  "request_id": "unique-request-identifier"
}

Common Error Codes

Authentication Errors

Error Code	Description	Resolution
INVALID_API_KEY	The provided API key is not valid	Please contact support at https://cognix.au/contact-us to verify your API key
EXPIRED_API_KEY	The API key has expired	Generate a new API key
MISSING_API_KEY	No API key provided in the request	Include API key in Authorization header

SEO-Specific Errors

Error Code	Description	Resolution
INVALID_DOMAIN	Domain format is invalid or unreachable	Check domain spelling and accessibility
SCAN_IN_PROGRESS	Technical scan already running for this domain	Wait for current scan to complete
QUOTA_EXCEEDED	Monthly scan quota has been exceeded	Upgrade plan or wait for reset
INVALID_LOCATION	Invalid geographic location specified	Use valid ISO country codes

Best Practices for Error Handling

1. Always check the status field in the response
2. Implement retry logic with exponential backoff for rate limits
3. Log the request_id for all errors
4. Monitor error rates to detect potential issues
5. Handle errors gracefully in your application

---