Docs / API Reference

API Reference

Complete reference for the SEOLens REST API.

Base URL

https://seo-lens.site/api/v1

Authentication

All API requests require an API key. Sign in to your dashboard to create a free API key. Include it in every request via the Authorization header or x-api-key header.

Authorization: Bearer YOUR_API_KEY

# or

x-api-key: YOUR_API_KEY

POST

/research

Research one or more keywords and retrieve search volume, difficulty, CPC data, and related keyword suggestions.

Request Body

Parameter	Type	Required	Description
keyword	string	Yes*	Single keyword to research
keywords	string[]	Yes*	Array of keywords (max 50). Use instead of `keyword`
countryCode	string	No	Country code (default: "US"). Options: US, JP, GB, DE, FR, CA, AU, BR, IN, KR, MX, ES, IT, NL, SE, TW, TH, VN, ID, PH
languageCode	string	No	Language code (default: "en"). Options: en, ja, de, fr, es, pt, it, nl, ko, zh, th, vi, id, sv

* Provide either keyword or keywords, not both.

Response Format (Single Keyword)

200 OK

{
  "keyword": "react hooks",
  "metrics": {
    "avgMonthlySearches": 18100,
    "competition": "LOW",
    "cpcLow": 0.15,
    "cpcHigh": 1.85
  },
  "difficulty": "easy",
  "suggestions": [
    {
      "keyword": "react custom hooks",
      "avgMonthlySearches": 6600,
      "competition": "LOW",
      "cpcLow": 0.10,
      "cpcHigh": 0.95
    }
  ]
}

Response Format (Batch)

200 OK

{
  "results": [
    {
      "keyword": "react hooks",
      "metrics": { ... },
      "difficulty": "easy",
      "suggestions": [ ... ]
    },
    {
      "keyword": "vue composables",
      "metrics": { ... },
      "difficulty": "medium",
      "suggestions": [ ... ]
    }
  ]
}

Code Examples

JavaScript / TypeScript

fetch

const response = await fetch("https://seo-lens.site/api/v1/research", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY",
  },
  body: JSON.stringify({
    keywords: ["nextjs seo"],
    countryCode: "US",
    languageCode: "en",
  }),
});

const data = await response.json();
console.log(data.results);

Python

requests

import requests

response = requests.post(
    "https://seo-lens.site/api/v1/research",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "keywords": ["nextjs seo"],
        "countryCode": "US",
        "languageCode": "en",
    },
)

data = response.json()
print(f"Results: {data['results']}")

cURL

bash

# Single keyword
curl -X POST https://seo-lens.site/api/v1/research \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"keywords": ["nextjs seo"], "countryCode": "US"}'

# Batch keywords
curl -X POST https://seo-lens.site/api/v1/research \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"keywords": ["react hooks", "vue composables"], "countryCode": "US"}'

Error Codes

Status	Description
200	Success - keyword data returned
401	Unauthorized - missing or invalid API key
400	Bad Request - missing or invalid parameters
429	Rate Limit Exceeded - too many requests
500	Internal Server Error - please try again later

Rate Limits

The free tier is rate-limited to ensure fair usage for all users.

100 requests per day per IP address
50 keywords per batch request
Cached results do not count against the rate limit