SearchMCP
Skip to content
REST API

Overview

The SearchMCP REST API gives you fast, reliable Google web search results via simple JSON over HTTPS. Use it from any backend or script. If you’re wiring an agent, also see our MCP Server.

Prerequisite: You’ll need an API key. Create and manage keys at /dashboard/keys and read the API Keys guide.
Base URL & Authentication

Base URL

https://api.searchmcp.io

Headers

  • X-API-Key required
  • Content-Type: application/json

API keys are tied to a team and enforce credits and rate limits.

Endpoint
POST /v1/search

Send a JSON body describing your query and optional targeting.

Request fields

Parameters accepted by the Search endpoint.

  • query
    string required

    The search query text. Example: 'apple inc'.

  • location
    enum | null
    Allowed: UK USA MEXICO JAPAN CALIFORNIA_USA SFO_USA NY_USA MUMBAI_INDIA LONDON_UK PARIS_FRANCE DUBAI BANGKOK SOHO_NYC_USA

    Physical/geographic location context for the search. Default: "UK".

  • country
    string(ISO-3166-1 alpha-2)

    Two-letter country code (e.g., 'US', 'GB', 'IN'). Used for search regionalization.

  • numberOfResults
    integer

    Maximum number of results to return. Default: 10.

  • dateRange
    enum | null
    Allowed: ANYTIME PAST_YEAR PAST_MONTH PAST_WEEK PAST_24_HOURS PAST_HOUR

    Time filter for results.

Example Request
curl -sS https://api.searchmcp.io/v1/search \
  -H "X-API-Key: smcp_XXXXXXXXXXXXXXXX_YYYYYYYYYYYYYYYYYYYYYYYY" \
  -H "Content-Type: application/json" \
  --data '{
    "query": "apple inc",
    "numberOfResults": 8,
    "location": "USA",
    "country": "US"
  }'
Responses fields

Parameters returned by the Search endpoint.

  • status
    enum required
    Allowed: UNAUTHORIZED INSUFFICIENT_CREDITS ERROR SUCCESS

    Execution status of the request.

  • searchParameters
    object required

    Echo of normalized parameters used by the engine.

    • query
      string required

      The search query string.

    • type
      string

      Search mode/type selected by backend.

    • engine
      string

      Engine/provider used for this search.

  • knowledgeGraph
    object|null

    Entity panel if Google returns one for the query.

    • title
      string

      Entity title.

    • imageUrl
      string(url)

      Entity image URL (if available).

    • description
      string

      Short summary text.

    • descriptionSource
      string

      Source label for description (e.g., Wikipedia).

    • descriptionLink
      string(url)

      Source URL for the description.

    • attributes
      map<string, string>

      Key–value facts about the entity (e.g., Headquarters, CEO).

  • organic
    array<object> required

    List of organic results in rank order.

    • title
      string required

      Result title.

    • link
      string(url) required

      Canonical result URL.

    • snippet
      string

      Short summary/excerpt from the page.

    • position
      integer

      1-based result rank for this page.

    • date
      string(ISO-8601)

      Published/seen date when available.

  • relatedSearches
    array<object>|null

    Suggested related queries.

    • query
      string required

      Suggested query text.

  • credits
    integer

    Credits billed for this request (typically 1 per search unless otherwise documented).

Sample response
{
  "status": "SUCCESS",
  "searchParameters": {
    "query": "apple inc",
    "type": "search",
    "engine": "google"
  },
  "knowledgeGraph": {
    "title": "Apple",
    "imageUrl": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcQwGQRv5TjjkycpctY66mOg_e2-npacrmjAb6_jAWhzlzkFE3OTjxyzbA&s=0",
    "description": "Apple Inc. is an American multinational corporation and technology company headquartered in Cupertino, California, in Silicon Valley. It is best known for its consumer electronics, software, and services.",
    "descriptionSource": "Wikipedia",
    "descriptionLink": "https://en.wikipedia.org/wiki/Apple_Inc.",
    "attributes": {
      "CEO": "Tim Cook (Aug 24, 2011–)",
      "COO": "Sabih Khan",
      "Customer service": "1 (800) 275-2273",
      "Founded": "April 1, 1976, Los Altos, CA",
      "Founders": "Steve Jobs, Steve Wozniak, and Ronald Wayne",
      "Headquarters": "Cupertino, CA"
    }
  },
  "organic": [
    {
      "title": "Apple",
      "link": "https://www.apple.com/",
      "snippet": "Discover the innovative world of Apple and shop everything iPhone, iPad, Apple Watch, Mac, and Apple TV, plus explore accessories, entertainment, ...",
      "position": 1,
      "date": null
    },
    {
      "title": "Apple Inc. - Wikipedia",
      "link": "https://en.wikipedia.org/wiki/Apple_Inc.",
      "snippet": "Apple Inc. is an American multinational corporation and technology company headquartered in Cupertino, California, in Silicon Valley.",
      "position": 2,
      "date": null
    }
  ],
  "relatedSearches": [
    {
      "query": "apple inc full form"
    }
  ],
  "credits": 1
}
Errors
  • 401 Unauthorized — Missing or invalid X-API-Key.
  • 402 Payment Required — Insufficient credits.
  • 429 Too Many Requests — Rate limit/QPS exceeded.
  • 5xx — Transient/upstream issues. Retry with backoff.

See REST Errors for full details.

Next Steps