ShuttleSEO/API Docs

GET/api/v1/searchv1 · beta

Search keywords

Get Google keyword suggestions with search volume, competition, and bid data in one request.

JavaScript request

const params = new URLSearchParams({
  q: "running shoes",
  country: "us",
  language: "en",
});

const response = await fetch(
  "https://shuttleseo.com/api/v1/search?" + params,
  {
    headers: {
      "X-API-Key": "YOUR_API_KEY",
    },
  },
);

const { data, usage } = await response.json();
console.log(data.items);
console.log(usage.credits.remaining + " searches remaining");

Base URL: https://shuttleseo.com

Query parameters

The endpoint returns the complete result set. There is no pagination.

q

stringrequired

Seed keyword or phrase to research.

country

stringoptional

Country name or two-letter code, for example us, gb, fr, or de. See all country codes.

Default: worldwide

source

stringoptional

Use google, amazon, youtube, local, or all. When omitted, only Google suggestions are returned.

Default: google

language

stringoptional

Language used to generate suggestions. Supported values: en, fr, es, de, pt, it, nl, pl, fi, ja, zh, zh-TW, ko, ru, and ar. See all language codes.

Default: en

Response

A successful request returns every keyword in data.items and normalized query metadata.

200 OK

{
  "data": {
    "items": [
      {
        "text": "best running shoes for beginners",
        "keywordMetrics": {
          "avgMonthlySearches": 60500,
          "competitionIndex": 31,
          "lowTopOfPageBidMicros": 466496,
          "highTopOfPageBidMicros": 1283019
        }
      },
      {
        "text": "running shoes for flat feet",
        "keywordMetrics": {
          "avgMonthlySearches": 18100,
          "competitionIndex": 44,
          "lowTopOfPageBidMicros": 721304,
          "highTopOfPageBidMicros": 1980250
        }
      }
    ]
  },
  "meta": {
    "query": "running shoes",
    "country": "us",
    "language": "en"
  },
  "usage": {
    "creditCost": 1,
    "cacheHit": false,
    "credits": {
      "limit": 10000,
      "used": 47,
      "remaining": 9953,
      "resetAt": "2126-06-08T08:55:16.255+00:00"
    }
  }
}

data.items[].text: Keyword suggestion.
avgMonthlySearches: Estimated average monthly search volume.
competitionIndex: Google Ads competition index, from 1 to 99.
lowTopOfPageBidMicros: Low top-of-page bid estimate in micros.
highTopOfPageBidMicros: High top-of-page bid estimate in micros.
meta.query: The original query.
meta.country: The normalized country or worldwide.
meta.language: The language used for suggestions.
usage.creditCost: Credits consumed by this request: 0 or 1.
usage.cacheHit: Whether the response came from the 30-day cache.
usage.credits: Current limit, used and remaining credits, plus reset date.

Bid values are expressed in micros. Divide by 1,000,000 to get the currency unit.

Usage and caching

API, web, and MCP searches share the same monthly account allowance.

A fresh search consumes one monthly search and returns the complete result set.
Results are cached for 30 days.
Repeating a cached query does not consume another search.
Free accounts reset monthly; paid allowances follow their billing period.

X-RateLimit-Limit: Monthly search allowance.
X-RateLimit-Remaining: Searches remaining.
X-RateLimit-Reset: Current period end date.

Errors

Errors use standard HTTP status codes and return a JSON body.

400

Invalid or missing query parameter.

401

Missing or invalid API key.

429

Monthly allowance exhausted.

503

Metrics temporarily unavailable; retry after 30 seconds.

500

Unexpected server error.

429 Too Many Requests

{
  "error": "Monthly credit quota exceeded",
  "credits": {
    "limit": 100,
    "used": 100,
    "remaining": 0,
    "reset_at": "2026-09-01T00:00:00.000Z"
  }
}

Country codes

Use a two-letter ISO country code in the country parameter. Omit the parameter for worldwide data.

Loading country codes…

Language codes

Use one of these values in the language parameter. English is used by default.

enEnglish

frFrançais

esEspañol

deDeutsch

ptPortuguês

itItaliano

nlNederlands

plPolski

fiSuomi

ja日本語

zh中文

zh-TW繁體中文

ko한국어

ruРусский

arالعربية