API Documentation

Welcome to the ShuttleSEO API! This documentation provides detailed information about available endpoints.

Authentication

All API requests require an API key for authentication. Include your API key as a query parameter named apiKey in each request.

Example: ?apiKey=YOUR_API_KEY

Need an API key? Contact us now to get yours today!

Keyword Search Data

Retrieves keyword suggestions and their associated metrics based on a provided search term. This endpoint helps you discover related keywords, analyze their search volume, competition, and estimated cost-per-click (CPC) data.

Endpoint

GET

1https://shuttleseo.com/api/keywords/search?searchTerm=shuttle&apiKey=P3aiWQiIy6AFi0JUBiB5X1MfsQ1TKLpi8rZRwx8JARDjMU1h7y4FJkEK28ibzz30

Query Parameters

Successful Response (200 OK)

Upon successful execution, the API returns a JSON object containing an array of keywords along with their detailed metrics.

Example Response Body:

1{
2  "keywordsWithFullMetrics": [
3    {
4      "text": "what are the space shuttle names",
5      "keywordMetrics": {
6        "competition": "LOW",
7        "monthlySearchVolumes": [
8          {"month": "APRIL", "year": "2024", "monthlySearches": "60500"},
9          // ... more months ...
10          {"month": "MARCH", "year": "2025", "monthlySearches": "74000"}
11        ],
12        "avgMonthlySearches": "60500",
13        "competitionIndex": "3",
14        "lowTopOfPageBidMicros": "466496",
15        "highTopOfPageBidMicros": "1283019"
16      },
17      "type": "quesiton",
18      "subtype": "what are"
19    },
20    {
21      "text": "could the space shuttle go to the moon",
22      // ... other metrics ...
23    },
24    // ... more keyword objects ...
25  ]
26}

Response Body Description

• keywordsWithFullMetrics ([Object]): A list containing keyword suggestion objects.
  • text (String): The keyword suggestion text.
  • keywordMetrics (Object): Contains detailed metrics for the keyword.
    • competition (String Enum): Relative competition level ("LOW", "MEDIUM", "HIGH").
    • monthlySearchVolumes ([Object]): Estimated search volumes for the past 12 months.
      • month (String)
      • year (String)
      • monthlySearches (String)
    • avgMonthlySearches (String): Average monthly searches.
    • competitionIndex (String): Numerical index (0-100) representing competition.
    • lowTopOfPageBidMicros (String): Lower range top-of-page bid (in micro-currency units). Divide by 1,000,000.
    • highTopOfPageBidMicros (String): Higher range top-of-page bid (in micro-currency units). Divide by 1,000,000.
  • closeVariants ([String], Optional): Close variations of the keyword text (may contain HTML entities).
  • type (String): Generation method/source (e.g., "suggestion", "alphabetical").
  • subtype (String): More specific detail about the type.

Error Responses

• 400 Bad Request: Malformed request (e.g., missing parameter).

  1{ "message": "Missing required parameter: searchTerm" }

• 401 Unauthorized: Invalid, missing, or expired apiKey.

  1{ "message": "Invalid API Key" }

• 402 Payment Required: Valid apiKey but insufficient credits.

  1{ "message": "Failed to consume credit" }

• 403 Forbidden: Valid apiKey but insufficient permissions.

  1{ "message": "API Key does not have access to this endpoint" }

• 429 Too Many Requests: Rate limit exceeded. Check Retry-After header if provided.

  1{ "message": "Rate limit exceeded" }

• 500 Internal Server Error: Unexpected server-side error.

  1{ "message": "Internal server error. Please try again later." }

(Note: Exact error message formats may vary)

Code Samples

1const https = require('https'); // Or use 'axios' or 'node-fetch'
2
3const apiKey = "YOUR_API_KEY";
4const searchTerm = "coffee";
5const baseUrl = "https://shuttleseo.com/api/keywords/search";
6
7const url = `${baseUrl}?searchTerm=${encodeURIComponent(searchTerm)}&apiKey=${encodeURIComponent(apiKey)}`;
8
9https.get(url, (res) => {
10  let data = '';
11  res.on('data', (chunk) => { data += chunk; });
12  res.on('end', () => {
13    if (res.statusCode >= 200 && res.statusCode < 300) {
14      try {
15        console.log(JSON.stringify(JSON.parse(data), null, 2));
16      } catch (e) { console.error("JSON parsing error:", e.message); }
17    } else {
18      console.error(`Request Failed. Status Code: ${res.statusCode}`);
19      console.error("Response:", data);
20    }
21  });
22}).on("error", (err) => {
23  console.error("API call error:", err.message);
24});
25
26// --- Using node-fetch (recommended) ---
27/*
28import fetch from 'node-fetch'; // npm install node-fetch
29
30async function fetchKeywords() {
31    const apiKey = "YOUR_API_KEY";
32    const searchTerm = "coffee";
33    const baseUrl = "https://shuttleseo.com/api/keywords/search";
34    const url = `${baseUrl}?searchTerm=${encodeURIComponent(searchTerm)}&apiKey=${encodeURIComponent(apiKey)}`;
35
36    try {
37        const response = await fetch(url);
38        if (!response.ok) {
39            const errorText = await response.text();
40            throw new Error(`HTTP error! Status: ${response.status} - ${errorText}`);
41        }
42        const data = await response.json();
43        console.log(JSON.stringify(data, null, 2));
44    } catch (error) {
45        console.error('Error fetching keyword data:', error);
46    }
47}
48fetchKeywords();
49*/