kwrds.ai

URL Rankings API

Quickstart

curl --location 'https://keywordresearch.api.kwrds.ai/url-rankings' \
--header 'X-API-KEY: YOUR_API_KEY_GOES_HERE' \
--header 'Content-Type: application/json' \
--data '{
    "url": "tesla.com",
    "search_country": "en-US"
}'

To increase your API limits, please choose your plan right from our pricing page.

Introduction

The URL Rankings API helps you discover which keywords your website is ranking for in search engine results. This powerful endpoint combines data from multiple sources including SERP analysis, branded and non-branded keyword detection, and AI-powered title analysis to provide comprehensive ranking insights. The API returns detailed metrics including search volumes, rankings, and estimated traffic for each keyword.

Watch kwrds.ai URL Rankings API integration

Discover how to seamlessly integrate kwrds.ai data into your application and unlock the power of related keywords for your projects.

Watch demo video

Watch video

Endpoint

POST /url-rankings

This endpoint retrieves ranking keywords and their metrics for a given website URL.

Example Request

Here's an example of how to use the URL Rankings API with cURL:

curl --location 'https://keywordresearch.api.kwrds.ai/url-rankings' \
--header 'X-API-KEY: YOUR_API_KEY_GOES_HERE' \
--header 'Content-Type: application/json' \
--data '{
    "url": "tesla.com",
    "search_country": "en-US"
}'

Request Body

• url: (Required) The website URL for which you want to find ranking keywords. Note that the URL needs to be the one that you want to find the rankings for, ie with or without www, https://, trailing slashes, etc.
• search_country: (Required) The country code (e.g., en-US) for which the search should be localized. The first part is the ISO 639-1 language code, and the second part is the ISO 3166-1 alpha-2 country code.
• version: (Optional) API version string, defaults to "1".

Headers

• X-API-KEY: (Required) Your API key for authentication.
• Content-Type: (Required) The content type of the request, which should be application/json.

Example Response

The API returns a JSON array containing detailed metrics for the ranking keywords. Here's an example response:

[
    {
        "keyword": "tesla model y",
        "volume": 165000,
        "cpc": 1.25,
        "search-intent": "Commercial",
        "competition_value": "HIGH",
        "ranking": 1,
        "ranking_url": "https://www.tesla.com/model-y",
        "ranking_title": "Model Y | Tesla",
        "estimated_traffic": 82500
    },
    {
        "keyword": "tesla cybertruck",
        "volume": 135000,
        "cpc": 0.95,
        "search-intent": "Informational",
        "competition_value": "MEDIUM",
        "ranking": 3,
        "ranking_url": "https://www.tesla.com/cybertruck",
        "ranking_title": "Cybertruck | Tesla",
        "estimated_traffic": 40500
    }
]

Response Structure

Each object in the response array contains:

• keyword: The ranking keyword
• volume: Monthly search volume for the keyword
• cpc: Cost per click for the keyword
• search-intent: Search intent classification (e.g., "Commercial", "Informational", etc.)
• competition_value: Competition level for the keyword
• ranking: The position where your URL ranks for this keyword (1-100, 0 if not ranking)
• ranking_url: The specific URL from your domain that ranks for this keyword
• ranking_title: The title of the ranking page
• estimated_traffic: Estimated monthly organic traffic for this keyword based on position and search volume

Use Cases

The URL Rankings API can be used for:

1. Rank Tracking: Monitor your website's search engine positions
2. Content Performance: Analyze which content is ranking well
3. SEO Opportunities: Identify keywords with potential for improvement
4. Competitor Analysis: Compare rankings with competitors
5. Traffic Estimation: Calculate potential organic traffic

Best Practices

1. Use Relevant Language Codes: Always specify the correct language and country code for targeted results
2. Regular Monitoring: Track rankings periodically to observe trends
3. Error Handling: Implement proper error handling for various HTTP status codes

Error Handling

The URL Rankings API returns standard HTTP status codes:

• 200 OK: Request successful
• 400 Bad Request: Invalid request parameters
• 401 Unauthorized: Missing or invalid API key
• 403 Forbidden: Insufficient permissions or plan limitations
• 404 Not Found: No ranking keywords found
• 429 Too Many Requests: Rate limit exceeded
• 500 Internal Server Error: Server-side error

Next Steps

Now that you understand how to use the URL Rankings API, you can start tracking your website's search engine performance. For questions or support, contact hello@kwrds.ai.