Docs / API Reference

API Reference

Complete reference for the SEOLens REST API.

Base URL

https://seolens.dev/api/v1

Authentication

The API is currently free and does not require authentication. Rate limits apply per IP address. Future versions may introduce API key authentication for higher rate limits.

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://seolens.dev/api/v1/research", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    keyword: "nextjs seo",
    countryCode: "US",
    languageCode: "en",
  }),
});

const data = await response.json();
console.log(data.metrics.avgMonthlySearches);
console.log(data.difficulty);
console.log(data.suggestions);

Python

requests

import requests

response = requests.post(
    "https://seolens.dev/api/v1/research",
    json={
        "keyword": "nextjs seo",
        "countryCode": "US",
        "languageCode": "en",
    },
)

data = response.json()
print(f"Volume: {data['metrics']['avgMonthlySearches']}")
print(f"Difficulty: {data['difficulty']}")
print(f"Suggestions: {len(data['suggestions'])}")

cURL

bash

# Single keyword
curl -X POST https://seolens.dev/api/v1/research \
  -H "Content-Type: application/json" \
  -d '{"keyword": "nextjs seo", "countryCode": "US"}'

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

Error Codes

Status	Description
200	Success - keyword data returned
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