API Documentation

SerperMatrix provides a simple REST API to access real-time Google search results. All endpoints accept POST requests with JSON body and require an API key.

Authentication

Include your API key in the X-API-KEY header with every request:

curl -X POST 'https://api.serpermatrix.com/v1/search' \
  -H 'X-API-KEY: sm_live_your_key_here' \
  -H 'Content-Type: application/json' \
  -d '{"q": "your search query"}'

Base URL

https://api.serpermatrix.com/v1

Available Endpoints

POST /api/v1/search — Web Search
POST /api/v1/images — Image Search
POST /api/v1/news — News Articles
POST /api/v1/places — Google Places/Maps
POST /api/v1/shopping — Shopping Results
POST /api/v1/videos — Video Search
POST /api/v1/scholar — Academic Papers
POST /api/v1/patents — Patent Search
POST /api/v1/autocomplete — Search Suggestions

Request Parameters

Parameter	Type	Required	Description
`q`	string	Yes	Search query
`gl`	string	No	Country code (e.g. "us", "uk")
`hl`	string	No	Language code (e.g. "en", "fr")
`location`	string	No	Location string (e.g. "New York, NY")
`num`	integer	No	Number of results (default: 10)
`page`	integer	No	Page number (default: 1)

Response Headers

Header	Description
`X-Response-Time`	Time taken to process the request
`X-Credits-Remaining`	Your remaining credit balance
`X-RateLimit-Remaining`	Requests remaining in current window
`X-Cache`	HIT or MISS — whether response was cached

Error Codes

Code	Meaning
`400`	Bad request — invalid parameters or missing query
`401`	Unauthorized — missing or invalid API key
`402`	Payment required — insufficient credits
`429`	Rate limit exceeded
`502`	Upstream provider error

Code Examples

Python

import requests

response = requests.post(
    "https://api.serpermatrix.com/v1/search",
    headers={"X-API-KEY": "sm_live_your_key"},
    json={"q": "machine learning"}
)
print(response.json())

JavaScript (fetch)

const res = await fetch("https://api.serpermatrix.com/v1/search", {
    method: "POST",
    headers: {
        "X-API-KEY": "sm_live_your_key",
        "Content-Type": "application/json",
    },
    body: JSON.stringify({ q: "machine learning" }),
});
const data = await res.json();

Get Your API Key