# Contribute to SERPHouse (/docs/contributing)



SERPHouse is built in the open. Whether you improve an official SDK, write an agent harness guide, fix docs, or ship tooling around the SERP API → **contributions are welcome**.

<ContributeHero />

## Where to contribute [#where-to-contribute]

Everything lives under the &#x2A;*[SERPHouse GitHub organization](https://github.com/SERPHouse)**. Pick a repo, open an issue, or send a pull request.

<ResourceCards>
  <ResourceCard title="GitHub Org" subtitle="github.com/SERPHouse" href="https://github.com/SERPHouse" icon="github" />

  <ResourceCard title="Node.js SDK" subtitle="SERPHouse/serphouse-nodejs" href="https://github.com/SERPHouse/serphouse-nodejs" icon="github" />

  <ResourceCard title="PHP SDK" subtitle="SERPHouse/serphouse-php" href="https://github.com/SERPHouse/serphouse-php" icon="github" />

  <ResourceCard title="MCP Server" subtitle="SERPHouse/serphouse-mcp" href="https://github.com/SERPHouse/serphouse-mcp" icon="github" />
</ResourceCards>

***

## Official open-source repos [#official-open-source-repos]

| Project             | What you'll work on               | Repository                                                                      |
| ------------------- | --------------------------------- | ------------------------------------------------------------------------------- |
| **Node.js SDK**     | Client API, types, examples       | [SERPHouse/serphouse-nodejs](https://github.com/SERPHouse/serphouse-nodejs)     |
| **PHP SDK**         | Client API, packaging, docs       | [SERPHouse/serphouse-php](https://github.com/SERPHouse/serphouse-php)           |
| **MCP Server**      | Tools, config, agent integrations | [SERPHouse/serphouse-mcp](https://github.com/SERPHouse/serphouse-mcp)           |
| **Agent Skills**    | Skill docs for AI coding agents   | [SERPHouse/agent-skills](https://github.com/SERPHouse/agent-skills)             |
| **AI SDK (Python)** | LangChain / LlamaIndex tooling    | [SERPHouse/ai-sdk-python](https://github.com/SERPHouse/ai-sdk-python)           |
| **n8n Node**        | No-code workflows with SERPHouse  | [SERPHouse/n8n-node-serphouse](https://github.com/SERPHouse/n8n-node-serphouse) |

<Callout type="success" title="New to open source?">
  Small PRs are perfect first contributions: typo fixes, clearer examples, and missing parameter notes all help.
</Callout>

***

## Ways you can help [#ways-you-can-help]

### SDKs & libraries [#sdks--libraries]

Bug fixes, new language ports, better error messages, and feature additions are all appreciated. Prefer PRs that include tests and a short note on *why* the change matters.

### Agent harnesses [#agent-harnesses]

Integrations live in `content/docs/agent-harnesses/`. If you've wired SERPHouse into Claude Code, Cursor, Codex CLI, OpenCode, VS Code, Smithery, or another agent → document it using the existing page pattern.

### Documentation [#documentation]

This site is MDX under `content/docs/`. Clearer copy, better tables, and runnable examples make the product easier for everyone.

### More ideas [#more-ideas]

* **Example projects**: dashboards, research tools, SEO workflows
* **Tutorials**: competitor analysis, local SEO tracking, news monitoring
* **Integrations**: WordPress, Shopify, or other platforms
* **Translations**: docs in more languages

***

## How to contribute docs [#how-to-contribute-docs]

<Steps>
  <Step>
    ### Fork the org [#fork-the-org]

    Start from &#x2A;*[github.com/SERPHouse](https://github.com/SERPHouse)** and fork the docs (or the relevant product) repository.
  </Step>

  <Step>
    ### Edit or add a page [#edit-or-add-a-page]

    Add or update MDX under `content/docs/`. Match the tone and structure of nearby pages.
  </Step>

  <Step>
    ### Update navigation [#update-navigation]

    If you add a new page, register it in `content/docs/meta.json` (or the section `meta.json`) so it appears in the sidebar.
  </Step>

  <Step>
    ### Open a pull request [#open-a-pull-request]

    Describe the change, link related issues, and call out anything reviewers should verify.
  </Step>
</Steps>

***

## Guidelines [#guidelines]

<Callout type="info" title="Keep it consistent">
  Follow existing MDX patterns: frontmatter, Callouts, Cards, tables, and resource links.
</Callout>

* Keep examples **concise and runnable**
* **Test API examples** before submitting
* For SDK changes, **include tests** with your PR
* Prefer clear language over jargon → readers should get value in under a minute
* Never commit API keys or secrets

***

## Ready when you are [#ready-when-you-are]

Jump into the org, star a repo you care about, and open your first PR. The community (and future you) will thank you.

## Related Links [#related-links]

<Cards>
  <Card title="SERPHouse on GitHub" description="Browse every public repo and open a PR." href="https://github.com/SERPHouse" />

  <Card title="Getting Started" description="Auth, rate limits, and your first request." href="/getting-started" />

  <Card title="Agent Skills" description="Teach AI agents how to use SERPHouse." href="/agent-skills" />
</Cards>


# FAQ (/docs/faq)



<FAQSchema
  items="[
  {
    question: &#x22;How do I authenticate and make my first API request?&#x22;,
    answer:
      &#x22;Sign up at https://www.serphouse.com/register, confirm your email, and copy your API key from the dashboard. Send it as a Bearer token in the Authorization header (or as an api_token query parameter) on every request, then POST to https://api.serphouse.com/google-web with your query. A 200 response returns the SERP data in the results field; failed requests are always free.&#x22;,
  },
  {
    question:
      &#x22;Where are the correct endpoints, payload fields, documentation, and code examples?&#x22;,
    answer:
      &#x22;Everything lives in this docs site: endpoint references under Getting Started, Google, Bing, Yahoo, and Extra APIs; required fields are marked with an asterisk on every page; and interactive examples are included per endpoint plus Node.js, PHP, and Python SDKs.&#x22;,
  },
  {
    question:
      &#x22;How do credits, trial allowances, plans, request limits, and custom pricing work?&#x22;,
    answer:
      &#x22;Credits are charged only on successful 200 responses; failed requests, retries, and blocks are free. The Free plan is $0/month with 4,000 credits, Basic is $29.99 with 400,000 credits, Regular is $49.99 with 800,000, and Custom scales to your volume. Standard plans are rate-limited to 60 requests per minute, and running out of credits returns HTTP 402.&#x22;,
  },
  {
    question:
      &#x22;What is the difference between live, delayed, and scheduled requests?&#x22;,
    answer:
      &#x22;Live requests are synchronous and return results in the same HTTP response, ideal for dashboards and single lookups. Scheduled (delayed) requests are asynchronous: submit with POST /serp/schedule, poll /serp/check for status, and fetch results with /serp/get. Batches support up to 100 keywords per scheduled request.&#x22;,
  },
  {
    question:
      &#x22;How long do delayed requests take, and how do webhooks, postbacks, or pingbacks work?&#x22;,
    answer:
      &#x22;Delayed jobs complete as capacity allows with no fixed SLA, so use notifications: pingbacks send an HTTP GET to your pingback_url when results are ready, postbacks POST the JSON results to your postback_url, and webhooks are configured on the Webhook page with automatic retries. Payloads are signed with HMAC-SHA256 in the x-serphouse-signature header.&#x22;,
  },
  {
    question:
      &#x22;Why did my request time out, return an error, produce empty results, or remain stuck?&#x22;,
    answer:
      &#x22;Match the HTTP status code: 200 is success, 400 an invalid body, 401 a bad or missing API key, 402 insufficient credits, 404 an invalid SERP ID or endpoint, 429 a rate limit, and 500 a server error. A 200 with msg 'Please try again' is a momentary failure, so just retry after a short wait. For scheduled tasks, poll /serp/check until status is Completed, then fetch with /serp/get.&#x22;,
  },
  {
    question:
      &#x22;How many results are returned, how does pagination work, and why can image, news, shopping, or other result types behave differently?&#x22;,
    answer:
      &#x22;Live requests return up to 10 results per page, and you paginate with the page parameter, where each page is a separate request. The Google Top 100 endpoint fetches up to 100 results across pages using max_pages. The API provides separate endpoints per result type — Web/Search, Image, News, Shopping, Videos, and other dedicated result types — across Google, Bing, and Yahoo, so the response structure varies by which API you call. The deprecated /serp/live endpoint is being removed.&#x22;,
  },
  {
    question: &#x22;Which search engines and domains do you support?&#x22;,
    answer:
      &#x22;SERPHouse supports Google (google.com plus per-country domains such as google.co.uk and google.ca), Bing (bing.com), and Yahoo (regional domains such as uk.yahoo.com). Browse every supported domain on the Domains List page or query GET /domain/list at runtime.&#x22;,
  },
  {
    question: &#x22;What format do API responses come in?&#x22;,
    answer:
      &#x22;JSON is the default, and a successful 200 response returns the SERP data in the results field. Many endpoints also support Markdown and HTML by appending /md or /html to the endpoint URL, for example https://api.serphouse.com/google-web/md for Markdown.&#x22;,
  },
  {
    question: &#x22;Can I try the API for free?&#x22;,
    answer:
      &#x22;Yes, the Free plan is $0/month and includes 4,000 API credits. Failed requests, retries, and blocks are never charged, and you can track your remaining credits anytime with the Account Info endpoint.&#x22;,
  },
  {
    question: &#x22;How fast are live requests?&#x22;,
    answer:
      &#x22;Live requests are synchronous and typically return results within seconds in the same HTTP response. Scheduled jobs run through a queue and complete as capacity allows, so use webhooks or pingbacks to be notified the moment results are ready.&#x22;,
  },
  {
    question: &#x22;Can I run bulk or batch queries?&#x22;,
    answer:
      &#x22;Yes, up to 100 keywords per scheduled request, with optional postback_url or pingback_url delivery straight to your server. For deep SERPs, the Google Top 100 endpoint returns up to 100 results per query via max_pages.&#x22;,
  },
  {
    question: &#x22;Do I need proxies or CAPTCHA solving?&#x22;,
    answer:
      &#x22;No. SERPHouse manages the proxies and handles CAPTCHAs for you. You never solve or forward CAPTCHAs; just send the query and read the results.&#x22;,
  },
  {
    question:
      &#x22;How do I verify my account, retrieve my API key, or resolve signup and CAPTCHA issues?&#x22;,
    answer:
      &#x22;Click the confirmation link emailed after signup at serphouse.com, and your API key appears on the dashboard once your email is confirmed. CAPTCHAs are handled entirely by SERPHouse, so you never solve or forward them. If you did not receive the email, check spam and then contact support.&#x22;,
  },
  {
    question:
      &#x22;How do I update payment details, obtain invoices, or add tax/VAT information?&#x22;,
    answer:
      &#x22;Manage payment methods, invoices, and tax/VAT information from the billing section of your dashboard; invoices are generated each billing cycle. For tax registration changes, invoice address updates, or custom billing arrangements, contact support.&#x22;,
  },
  {
    question: &#x22;How do I cancel or unsubscribe from my subscription?&#x22;,
    answer:
      &#x22;Cancel your subscription from the billing section of your dashboard. Your plan ends immediately after cancellation. After cancelling or downgrading, running out of credits returns a 402; contact support for plan migrations or custom contracts.&#x22;,
  },
  {
    question:
      &#x22;Which locations, languages, devices, and search settings are supported?&#x22;,
    answer:
      &#x22;Pass a location with loc or loc_id (prefer loc_id for stable, machine-readable targeting), language codes such as en or fr, device as desktop or mobile, and settings like verbatim, gfilter, page, num_result, and date_range. Full lists are on the Locations, Languages, and Domains pages.&#x22;,
  },
  {
    question:
      &#x22;Can I connect the API to Google Sheets, spreadsheets, or another export workflow?&#x22;,
    answer:
      &#x22;Yes, the API is plain HTTP. Use Apps Script with UrlFetchApp and a Bearer header for Google Sheets (IMPORTDATA cannot send headers), Excel or Power Query for the live GET endpoint, or pipelines with scheduled tasks, webhooks, and the Node.js, PHP, and Python SDKs.&#x22;,
  },
]"
/>

## Frequently asked questions [#frequently-asked-questions]

Quick answers to the questions developers ask most, from your first request to billing, webhooks, and result pagination.

### 1. How do I authenticate and make my first API request? [#1-how-do-i-authenticate-and-make-my-first-api-request]

Send your API key as a `Bearer` token in the `Authorization` header, or pass `api_token=<YOUR_API_KEY>` as a query string, on every request. Sign up at [serphouse.com](https://www.serphouse.com/register), confirm your email, and copy the key from your dashboard, then send your first POST to `https://api.serphouse.com/google-web`.

**1. Register** at [serphouse.com](https://www.serphouse.com/register) and confirm the
email link sent to your inbox. Only one account is allowed per user; if
you need extra testing credits, contact support instead of creating
duplicates.

**2. Get your API key.** It appears on your account dashboard once your
email is confirmed. Keep it secret and never commit it to public scripts.

**3. Authenticate.** Send your key as a `Bearer` token in the
`Authorization` header of every request, or pass `api_token=<YOUR_API_KEY>`
as a query string:

```http
POST /google-web HTTP/1.1
Host: api.serphouse.com
Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json
```

**4. Minimal live request:**

```bash
curl -X POST "https://api.serphouse.com/google-web" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "coffee",
    "domain": "google.com",
    "lang": "en",
    "device": "desktop",
    "loc": "Alba,Texas,United States"
  }'
```

<Callout type="success" title="You only pay for successful responses">
  A <code>200</code> status means success and returns SERP data in the
  <code>results</code> field. Failed requests, retries, and blocks are always
  free.
</Callout>

See [Getting Started](/getting-started) and
[Google Search API](https://www.serphouse.com/docs/google-apis/google-search) for full field tables.

***

### 2. Where are the correct endpoints, payload fields, documentation, and code examples? [#2-where-are-the-correct-endpoints-payload-fields-documentation-and-code-examples]

Everything lives in this docs site: endpoint references under [Getting Started](/getting-started), [Google](/google-apis), [Bing](/bing-apis), and [Yahoo](/yahoo-apis); required fields are marked with an asterisk on every page; and interactive examples are included per endpoint plus [Node.js](/node.js-sdk), [PHP](/php-sdk), and [Python](/python-sdk) SDKs.

* **Endpoints:** [Getting Started](/getting-started), [Google](/google-apis), [Bing](/bing-apis), [Yahoo](/yahoo-apis), [Extra APIs](/extra-apis)
* **Fields:** every page documents required parameters (marked with an asterisk) and shows sample responses
* **Examples:** interactive snippets per page, plus [Node.js](/node.js-sdk), [PHP](/php-sdk), and [Python](/python-sdk) SDKs

| Endpoint                    | Purpose                              |
| --------------------------- | ------------------------------------ |
| `POST /google-web`          | Google Search API (real-time search) |
| `POST /serp/schedule`       | Queue delayed / batch tasks          |
| `GET /serp/check?id=`       | Check task status                    |
| `GET /serp/get?id=`         | Retrieve task results                |
| `GET /account/info`         | Plan and credit usage                |
| `GET /location/search`      | Look up locations / `loc_id`         |
| `GET /language/list/{type}` | List supported languages             |
| `GET /domain/list`          | List supported domains               |

***

### 3. How do credits, trial allowances, plans, request limits, and custom pricing work? [#3-how-do-credits-trial-allowances-plans-request-limits-and-custom-pricing-work]

Credits are charged **only on successful responses**; failed requests, retries, and blocks are free. The Free plan is $0/month with 4,000 credits, Basic is $29.99/month with 400,000, and Regular is $49.99/month with 800,000; all standard plans allow 60 req/min, and running out of credits returns a `402`.

<Callout type="success" title="You only pay for results">
  Credits are charged <strong>only on successful responses</strong>. Failed
  requests, retries, and blocks are free.
</Callout>

| Serp type         |    Free    |  Basic  | Regular | Custom |
| ----------------- | :--------: | :-----: | :-----: | :----: |
| Price             | $0 / month |  $29.99 |  $49.99 | Custom |
| API credits       |    4,000   | 400,000 | 800,000 | Custom |
| SERP / 1k         |      -     |  $0.75  |  $0.62  | Custom |
| Autocomplete / 1k |      -     |  $0.37  |  $0.31  | Custom |
| Top 100 SERP / 1k |      -     |  $7.50  |  $6.25  | Custom |

* **Rate limit** is **60 req/min** on Free, Basic, and Regular plans (Custom scales as needed)
* Credits **do not** roll over month to month
* Running out of credits returns a &#x2A;*`402`** response
* Custom plans scale credits, rate limits, and pricing to your volume; contact support
* Check usage anytime with [Account Info](/extra-apis/account-info)

***

### 4. What is the difference between live, delayed, and scheduled requests? [#4-what-is-the-difference-between-live-delayed-and-scheduled-requests]

**Live** requests are synchronous and return results in the same HTTP response, best for dashboards and single lookups. **Scheduled** (delayed) requests are asynchronous: submit with `POST /serp/schedule`, poll [Check SERP Status](/extra-apis/check-serp-status), and fetch with [Get SERP Result](/extra-apis/get-serp-result); each batch supports up to 100 keywords.

* **Live:** synchronous. Results come back in the same HTTP response. Best for dashboards and single lookups (available over `GET` & `POST`).
* **Scheduled / delayed:** asynchronous. Submit with `POST /serp/schedule`, then poll [Check SERP Status](/extra-apis/check-serp-status) and fetch with [Get SERP Result](/extra-apis/get-serp-result).
* **Batch:** up to **100 keywords** per scheduled request, optionally delivering via `postback_url` / `pingback_url`.

<Callout type="idea" title="TL;DR">
  Use <strong>live</strong> for instant single lookups and dashboards, and
  <strong>scheduled</strong> when you need bulk jobs of up to 100 keywords.
</Callout>

|            |     Scheduled    |         Live        |
| ---------- | :--------------: | :-----------------: |
| Model      |      Polling     |      Immediate      |
| Task IDs   |    Persistent    |         N/A         |
| HTTP       |       POST       |      GET & POST     |
| Throughput | Built-in queuing | Per-minute throttle |

Full comparison: [About SERPHouse](/about-the-serp-api).

***

### 5. How long do delayed requests take, and how do webhooks, postbacks, or pingbacks work? [#5-how-long-do-delayed-requests-take-and-how-do-webhooks-postbacks-or-pingbacks-work]

Delayed jobs complete **as capacity allows**, with no fixed SLA, so use notifications instead of polling: pingbacks send an HTTP `GET` to your `pingback_url` when results are ready, postbacks `POST` the JSON results to your `postback_url`, and webhooks are configured on the [Webhook Settings](https://www.serphouse.com/wehook-setting) page with automatic retries. Every payload is signed with HMAC-SHA256 in the `x-serphouse-signature` header.

* **Pingback:** an HTTP `GET` to your `pingback_url` when results are ready (then fetch them with Get SERP Result)
* **Postback:** an HTTP `POST` with JSON results to your `postback_url`
* **Webhooks:** configure on the [Webhook Settings](https://www.serphouse.com/wehook-setting) page, with retries at **0s**, **100s**, **1,000s**, and **1,800s** (4 failures = permanent fail)

<Callout type="warn" title="At-least-once delivery">
  Your endpoint may receive the same event <strong>multiple times</strong>.
  Deduplicate with the <code>x-serphouse-task-id</code> header.
</Callout>

If your server doesn't respond within **5 seconds** the delivery is treated as failed and resent.

Payloads are signed with HMAC-SHA256 in the `x-serphouse-signature` header. Validate it to confirm the request really came from SERPHouse.

***

### 6. Why did my request time out, return an error, produce empty results, or remain stuck? [#6-why-did-my-request-time-out-return-an-error-produce-empty-results-or-remain-stuck]

Match the HTTP status code: `200` is success, `400` an invalid body, `401` a bad or missing API key, `402` insufficient credits, `404` an invalid SERP ID or endpoint, `429` a rate limit, and `500` a server error. A `200` with `"msg": "Please try again"` is a momentary failure; just retry after a short wait. For scheduled tasks, poll `/serp/check` until status is `Completed`, then fetch with `/serp/get`.

| Code | Meaning                         |
| ---- | ------------------------------- |
| 200  | Success (SERP in `results`)     |
| 400  | Invalid body / validation error |
| 401  | Bad or missing API key          |
| 402  | Insufficient credits            |
| 404  | Invalid SERP ID / endpoint      |
| 405  | Method not allowed              |
| 429  | Rate limit: slow down           |
| 500  | Internal server error           |

<Callout type="info" title="200 but nothing returned?">
  A <code>200</code> with <code>"msg": "Please try again"</code> is a momentary
  failure; just retry after a short wait. It is not billed.
</Callout>

* Scheduled tasks: poll `/serp/check` until status is `Completed`, then call `/serp/get` to fetch results
* Empty results usually mean the task is still processing or the engine returned nothing
* If a task id seems stuck, re-check after a few minutes before contacting support
* Permanently-failed webhooks can always be fetched manually with the Get SERP Result API

***

### 7. How many results are returned, how does pagination work, and why can image, news, shopping, or other result types behave differently? [#7-how-many-results-are-returned-how-does-pagination-work-and-why-can-image-news-shopping-or-other-result-types-behave-differently]

Live requests return up to **10 results per page**, and you paginate with the `page` parameter, where each page is a separate request. The [Google Top 100](/google-apis/google-serp-top-100-results) endpoint fetches up to 100 results across pages with `max_pages`. The API provides separate endpoints per result type — **Web/Search**, **Image**, **News**, **Shopping**, **Videos**, and other dedicated result types — across Google, Bing, and Yahoo, so the response structure varies by which API you call. The deprecated `/serp/live` endpoint is being removed.

* **Live / single-request:** default **10 results per page**, maximum `num_result` is **10**
* **Pagination:** use the `page` parameter (`1`, `2`, …), each page is a separate request
* **Top 100:** the [Google Top 100](/google-apis/google-serp-top-100-results) endpoint fetches up to **100 results** across pages with `max_pages` (1 page ≈ 10 results, each page costs 10 credits)
* **Result types:** separate APIs per type across Google, Bing, and Yahoo — **Web/Search**, **Image**, **News**, **Shopping**, **Videos**, and other dedicated result types; each endpoint page documents its own response fields
* Different result types expose different fields, so the response shape varies by API endpoint; likewise `verbatim`, `gfilter`, and `date_range` affect what comes back
* The deprecated `/serp/live` endpoint is being removed; use the dedicated per-type APIs instead

## API and data [#api-and-data]

### 1. Which search engines and domains do you support? [#1-which-search-engines-and-domains-do-you-support]

SERPHouse supports **Google** (`google.com` plus per-country domains like `google.co.uk` and `google.ca`), **Bing** (`bing.com`), and **Yahoo** (regional domains such as `uk.yahoo.com`). Browse the full list on the [Domains List](/extra-apis/domains-list) page or query `GET /domain/list` at runtime.

* **Google:** `google.com` plus per-country domains (`google.co.uk`, `google.ca`, `google.co.in`, …)
* **Bing:** `bing.com`
* **Yahoo:** regional domains such as `uk.yahoo.com`
* Browse every supported domain on the [Domains List](/extra-apis/domains-list) page or query the `GET /domain/list` endpoint at runtime

***

### 2. What format do API responses come in? [#2-what-format-do-api-responses-come-in]

**JSON** is the default: a successful `200` response returns the SERP data in the `results` field. Many endpoints also support **Markdown** and **HTML** by appending a suffix to the endpoint URL: `/md` for Markdown and `/html` for HTML (no suffix returns JSON), for example `https://api.serphouse.com/google-web/md`.

* **JSON** is the default; a successful `200` response returns the SERP data in the `results` field
* Some endpoints also support **HTML** and **Markdown**; append a suffix to the endpoint URL to pick the format: `/md` for Markdown and `/html` for HTML (no suffix returns JSON)
  * For example: `https://api.serphouse.com/google-web` → JSON, `https://api.serphouse.com/google-web/md` → Markdown, `https://api.serphouse.com/google-web/html` → HTML
* The fields inside `results` vary by API endpoint; each endpoint page shows a sample response

***

### 3. Can I try the API for free? [#3-can-i-try-the-api-for-free]

**Yes.*&#x2A; The Free plan is **$0/month** and includes **4,000 API credits**, and failed requests, retries, and blocks are **never charged**. Track your remaining credits anytime with [Account Info](/extra-apis/account-info).

* **Yes:*&#x2A; the Free plan is **$0/month** and includes **4,000 API credits**
* Failed requests, retries, and blocks are **never charged**
* Track remaining credits anytime with [Account Info](/extra-apis/account-info)

***

### 4. How fast are live requests? [#4-how-fast-are-live-requests]

Live requests are **synchronous** and typically return results within seconds in the same HTTP response. Scheduled jobs run through a queue and complete **as capacity allows**, so use webhooks or pingbacks to be notified the moment results are ready.

* Live requests are **synchronous**; results come back in the same HTTP response, typically within seconds
* Scheduled jobs run through a queue and complete **as capacity allows** (no fixed SLA). Use webhooks or pingbacks to be notified the moment results are ready

***

### 5. Can I run bulk or batch queries? [#5-can-i-run-bulk-or-batch-queries]

**Yes.** Up to **100 keywords** per scheduled request, with optional `postback_url` / `pingback_url` delivery straight to your server. For deep SERPs, the [Google Top 100](/google-apis/google-serp-top-100-results) endpoint returns up to **100 results** per query via `max_pages`.

* **Yes:** up to **100 keywords** per scheduled request
* Deliver results straight to your server with `postback_url` / `pingback_url`
* For deep SERPs, the [Google Top 100](/google-apis/google-serp-top-100-results) endpoint returns up to **100 results** via `max_pages`

***

### 6. Do I need proxies or CAPTCHA solving? [#6-do-i-need-proxies-or-captcha-solving]

**No.** SERPHouse manages the proxies and handles CAPTCHAs for you. You never solve or forward CAPTCHAs; just send the query and read the results.

* **No:** SERPHouse manages the proxies and handles CAPTCHAs for you
* You never solve or forward CAPTCHAs; just send the query and read the results

## More questions [#more-questions]

### 1. How do I verify my account, retrieve my API key, or resolve signup and CAPTCHA issues? [#1-how-do-i-verify-my-account-retrieve-my-api-key-or-resolve-signup-and-captcha-issues]

Click the **confirmation link** emailed after signup at [serphouse.com](https://www.serphouse.com/register), and your **API key** appears on the dashboard once your email is confirmed. **CAPTCHAs** are handled entirely by SERPHouse; you never solve or forward them. No email? Check spam, then contact support.

* **Verify:** click the confirmation link emailed after signup at [serphouse.com](https://www.serphouse.com/register)
* **API key:** shown on your dashboard once your email is confirmed
* **One account per user:** request extra testing credits from support instead of creating duplicates
* **CAPTCHAs:** handled entirely by SERPHouse; you never solve or forward them
* **No email?** Check spam, then contact support

***

### 2. How do I update payment details, obtain invoices, or add tax/VAT information? [#2-how-do-i-update-payment-details-obtain-invoices-or-add-taxvat-information]

Manage payment methods, invoices, and tax/VAT information from the **billing section** of your dashboard; invoices are generated each billing cycle. For tax registration changes, invoice address updates, or custom billing arrangements, contact support.

Manage payment methods, invoices, and tax/VAT information from the **billing section** of your dashboard. Invoices are generated each billing cycle.

For tax registration changes, invoice address updates, or custom billing arrangements, contact support.

***

### 3. How do I cancel or unsubscribe from my subscription? [#3-how-do-i-cancel-or-unsubscribe-from-my-subscription]

Cancel your subscription from the **billing section** of your dashboard. Your plan ends immediately after cancellation. After cancelling or downgrading, running out of credits returns a `402`; contact support for plan migrations or custom contracts.

Cancel your subscription from the **billing section** of your dashboard. Your plan ends immediately after cancellation.

<Callout type="info">
  After cancelling or downgrading, running out of credits returns a
  <code>402</code>. Contact support for plan migrations or custom contracts.
</Callout>

***

### 4. Which locations, languages, devices, and search settings are supported? [#4-which-locations-languages-devices-and-search-settings-are-supported]

Pass a location with `loc` or `loc_id` (prefer `loc_id` for stable, machine-readable targeting), language codes such as `en` or `fr`, device as `desktop` or `mobile`, and settings like `verbatim`, `gfilter`, `page`, `num_result`, and `date_range`. Full lists are on the [Locations](/extra-apis/locations-list), [Languages](/extra-apis/languages-list), and [Domains](/extra-apis/domains-list) pages.

* **Locations:** [Locations List](/extra-apis/locations-list) or the CSV files ([Google](https://serphouse-space.nyc3.digitaloceanspaces.com/google_locations.csv), [Bing](https://serphouse-space.nyc3.digitaloceanspaces.com/bing_locations.csv)). Pass `loc` or `loc_id`.

<Callout type="idea" title="loc or loc_id?">
  Pass <code>loc\_id</code> for stable, machine-readable targeting;
  <code>loc</code> names are matched flexibly and can change over time.
</Callout>

* **Languages:** [Languages List](/extra-apis/languages-list); pass codes like `en`, `fr`
* **Devices:** `desktop` or `mobile`
* **Domains:** [Domains List](/extra-apis/domains-list) for Google, Bing, and Yahoo
* **Settings:** `verbatim`, `gfilter`, `page`, `num_result`, `date_range` (`h`/`d`/`w`/`m`/`y` or `YYYY-MM-DD,YYYY-MM-DD`)

***

### 5. Can I connect the API to Google Sheets, spreadsheets, or another export workflow? [#5-can-i-connect-the-api-to-google-sheets-spreadsheets-or-another-export-workflow]

**Yes**, the API is plain HTTP. Use Apps Script + `UrlFetchApp` with a `Bearer` header for Google Sheets (`IMPORTDATA` can't send headers), Excel/Power Query for the live `GET` endpoint, or pipelines with scheduled tasks, webhooks, and the [Node.js](/node.js-sdk), [PHP](/php-sdk), and [Python](/python-sdk) SDKs.

Yes, the API is plain HTTP:

* **Google Sheets:** use Apps Script + `UrlFetchApp` with a `Bearer` header (`IMPORTDATA` can't send headers)
* **Excel / Power Query:** call the live `GET` endpoint and parse the returned JSON
* **Pipelines:** scheduled tasks, webhooks, or the SDKs ([Node.js](/node.js-sdk), [PHP](/php-sdk), [Python](/python-sdk))

<Callout type="warn" title="Keep your key private">
  Never hardcode your API key in a shared sheet, a public script, or anywhere it
  could leak. Use an environment variable or a secrets manager.
</Callout>

## Still have questions? [#still-have-questions]

<Callout type="info" title="We're here to help">
  Search the docs using the search bar at the top, or reach out to [SERPHouse
  support](https://serphouse.com) at
  [getsupport@serphouse.com](mailto:getsupport@serphouse.com). We usually reply
  within one business day.
</Callout>


# LangChain Integration (/docs/langchain)



The SERPHouse AI SDK is a Python SDK for the SERPHouse search API, built to plug live web search data directly into AI agents. It provides first-class, framework-native integrations for both LangChain and LlamaIndex.

<ResourceCards>
  <ResourceCard title="GitHub" subtitle="SERPHouse/ai-sdk-python" href="https://github.com/SERPHouse/ai-sdk-python" icon="github" />

  <ResourceCard title="PyPI" subtitle="serphouse-ai-sdk" href="https://pypi.org/project/serphouse-ai-sdk/" icon="pypi" />
</ResourceCards>

## Installation [#installation]

<Callout type="success">
  Quick setup with a single pip command.
</Callout>

```bash
pip install serphouse-ai-sdk[langchain]
```

<Callout type="info">
  For all frameworks: 

  <code>pip install serphouse-ai-sdk[all]</code>
</Callout>

## API Key Setup [#api-key-setup]

<Callout type="warn">
  Set your <code>SERPHOUSE\_API\_KEY</code> environment variable before using the SDK.
</Callout>

```bash
export SERPHOUSE_API_KEY=your_key_here
```

## Available Tools [#available-tools]

| Tool            | Description                | Endpoint                   |
| --------------- | -------------------------- | -------------------------- |
| `search()`      | Google Web Search          | `/web-search-lite`         |
| `news()`        | Google News Search         | `/google-news`             |
| `short_video()` | Google Short Videos Search | `/google-short-videos-api` |

## Usage Example [#usage-example]

```python
from langchain.agents import create_agent
from langchain_openai import ChatOpenAI
from serphouse.langchain import search, news, short_video

agent = create_agent(
    model=ChatOpenAI(model="gpt-4"),
    tools=[search(), news(), short_video()],
)

response = agent.invoke({
    "messages": [{"role": "user", "content": "Latest AI news from OpenAI"}]
})
print(response["messages"][-1].content)
```

<Callout type="idea">
  Works with OpenAI, Anthropic Claude, and Google Gemini models.
</Callout>

## Related Links [#related-links]

<Cards>
  <Card title="LlamaIndex" href="/llamaindex" />

  <Card title="Vercel AI SDK" href="/vercel-ai-sdk" />

  <Card title="MCP Server" href="/mcp-server" />
</Cards>


# LlamaIndex Integration (/docs/llamaindex)



The SERPHouse AI SDK is a Python SDK for the SERPHouse search API, built to plug live web search data directly into AI agents. It provides first-class, framework-native integrations for both LangChain and LlamaIndex.

<ResourceCards>
  <ResourceCard title="GitHub" subtitle="SERPHouse/ai-sdk-python" href="https://github.com/SERPHouse/ai-sdk-python" icon="github" />

  <ResourceCard title="PyPI" subtitle="serphouse-ai-sdk" href="https://pypi.org/project/serphouse-ai-sdk/" icon="pypi" />
</ResourceCards>

## Installation [#installation]

<Callout type="success">
  Quick setup with a single pip command.
</Callout>

```bash
pip install serphouse-ai-sdk[llamaindex]
```

<Callout type="info">
  For all frameworks: 

  <code>pip install serphouse-ai-sdk[all]</code>
</Callout>

## API Key Setup [#api-key-setup]

<Callout type="warn">
  Set your <code>SERPHOUSE\_API\_KEY</code> environment variable before using the SDK.
</Callout>

```bash
export SERPHOUSE_API_KEY=your_key_here
```

## Available Tools [#available-tools]

| Tool            | Description                | Endpoint                   |
| --------------- | -------------------------- | -------------------------- |
| `search()`      | Google Web Search          | `/web-search-lite`         |
| `news()`        | Google News Search         | `/google-news`             |
| `short_video()` | Google Short Videos Search | `/google-short-videos-api` |

## Usage Example [#usage-example]

```python
from llama_index.core.agent.workflow import FunctionAgent
from llama_index.llms.openai import OpenAI
from serphouse.llamaindex import search, news, short_video

agent = FunctionAgent(
    llm=OpenAI(model="gpt-4"),
    tools=[search(), news(), short_video()],
)

response = agent.run("Latest AI news from OpenAI")
print(response)
```

<Callout type="idea">
  Works with OpenAI, Anthropic Claude, and Google Gemini models.
</Callout>

## Related Links [#related-links]

<Cards>
  <Card title="LangChain" href="/langchain" />

  <Card title="Vercel AI SDK" href="/vercel-ai-sdk" />

  <Card title="MCP Server" href="/mcp-server" />
</Cards>


# Vercel AI SDK (/docs/vercel-ai-sdk)



`@serphouse/ai-sdk` is an official AI SDK integration for the SERPHouse Search APIs. It exposes SERPHouse search endpoints as native AI tools, allowing any model supported by the Vercel AI SDK to search the web, retrieve news, or discover short videos through tool calling.

<Callout type="warn">
  Instead of writing HTTP requests, handling authentication, validating inputs, or parsing responses, you simply register the provided tools and let the model decide when to use them.
</Callout>

<ResourceCards>
  <ResourceCard title="GitHub" subtitle="SERPHouse/ai-sdk" href="https://github.com/SERPHouse/ai-sdk" icon="github" />

  <ResourceCard title="NPM" subtitle="@serphouse/ai-sdk" href="https://www.npmjs.com/package/@serphouse/ai-sdk" icon="npm" />
</ResourceCards>

## Why @serphouse/ai-sdk? [#why-serphouseai-sdk]

<Callout type="info">
  Modern LLMs are limited by their training data and cannot reliably answer questions that require fresh information. `@serphouse/ai-sdk` bridges this gap by turning SERPHouse APIs into AI-native tools.
</Callout>

Although SERPHouse already provides powerful Search APIs, integrating them into an AI workflow usually requires building HTTP clients, managing authentication, defining tool schemas, validating inputs, handling API responses, and writing repetitive boilerplate.

`@serphouse/ai-sdk` removes all of that. It wraps SERPHouse APIs into fully typed Vercel AI SDK tools with built-in Zod validation, allowing models to search the internet with only a few lines of code. Instead of manually deciding when to call the API, the language model automatically chooses the appropriate tool whenever it needs external information.

## Features [#features]

<table>
  <thead>
    <tr>
      <th>Feature</th>

      <th>Benefit</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Native `tool()` integration</td>

      <td>Plug-and-play with Vercel AI SDK</td>
    </tr>

    <tr>
      <td>Fully typed with TypeScript</td>

      <td>Autocomplete and type safety</td>
    </tr>

    <tr>
      <td>Built-in Zod validation</td>

      <td>Input validation out of the box</td>
    </tr>

    <tr>
      <td>Zero HTTP boilerplate</td>

      <td>No fetch, no axios, no manual requests</td>
    </tr>

    <tr>
      <td>Automatic tool calling</td>

      <td>Model decides when to search</td>
    </tr>

    <tr>
      <td>Model-agnostic</td>

      <td>Works with OpenAI, Anthropic, Google, and more</td>
    </tr>

    <tr>
      <td>Lightweight & production ready</td>

      <td>Minimal dependencies, fully tested</td>
    </tr>
  </tbody>
</table>

## Installation [#installation]

<Callout type="success">
  Quick setup with a single command.
</Callout>

```bash
npm install @serphouse/ai-sdk
```

Peer dependencies: `npm install ai zod`

<Callout type="info">
  Requires <strong>Node.js >= 18</strong>.
</Callout>

## API Key Setup [#api-key-setup]

<Callout type="warn">
  The SDK automatically reads the <code>SERPHOUSE\_API\_KEY</code> environment variable. You can also pass an API key explicitly when creating a tool.
</Callout>

```bash
export SERPHOUSE_API_KEY="your_api_key"
```

## Getting Started [#getting-started]

Register the tools and let the model decide when to use them:

```ts
import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";
import { search, news } from "@serphouse/ai-sdk";

const { text } = await generateText({
  model: openai("gpt-4o"),
  tools: {
    search: search(),
    news: news(),
  },
  prompt: "What happened in AI this week?",
});

console.log(text);
```

<Callout type="idea">
  The model automatically decides whether a tool is needed, which tool should be called, and what arguments should be passed. No manual API requests are required.
</Callout>

## Available Tools [#available-tools]

| Tool           | Description                | Endpoint                   |
| -------------- | -------------------------- | -------------------------- |
| `search()`     | Google Web Search          | `/web-search-lite`         |
| `news()`       | Google News Search         | `/google-news`             |
| `shortVideo()` | Google Short Videos Search | `/google-short-videos-api` |

Each tool includes a Zod input schema, execute handler, type safety, and automatic tool execution.

## Tool Input Schema [#tool-input-schema]

Every tool accepts the same search parameters (except `gl`, which is only supported by `search()`):

| Property     | Type                    | Default                             | Description                    |
| ------------ | ----------------------- | ----------------------------------- | ------------------------------ |
| `q`          | `string`                | Required                            | Search query                   |
| `domain`     | `string`                | `"google.com"`                      | Google domain                  |
| `lang`       | `string`                | `"en"`                              | Language                       |
| `loc`        | `string`                | `"New York,New York,United States"` | Search location                |
| `page`       | `number`                | `1`                                 | Page number                    |
| `date_range` | `string`                | `"y"`                               | Time filter                    |
| `device`     | `"desktop" \| "mobile"` | `"desktop"`                         | Device                         |
| `gl`         | `string`                | `"US"`                              | Country code (`search()` only) |

## Authentication [#authentication]

<Callout type="info">
  The SDK resolves the API key in the following order.
</Callout>

### Environment Variable [#environment-variable]

```bash
export SERPHOUSE_API_KEY="your_api_key"
```

```ts
const tool = search();
```

### Explicit API Key [#explicit-api-key]

```ts
const tool = search({
  apiKey: "sk-xxxxxxxx",
});
```

Explicit keys always override the environment variable.

## API Reference [#api-reference]

### `search()` [#search]

Google Web Search. Returns organic results, ads, knowledge graph, related searches, featured snippets, and rich results.

```ts
import { search } from "@serphouse/ai-sdk";
const tool = search();
```

### `news()` [#news]

Google News Search. Returns headlines, publishers, publish date, URLs, and news metadata.

```ts
import { news } from "@serphouse/ai-sdk";
const tool = news();
```

### `shortVideo()` [#shortvideo]

Google Short Videos Search. Returns short videos, metadata, and source URLs.

```ts
import { shortVideo } from "@serphouse/ai-sdk";
const tool = shortVideo();
```

### Tool Options [#tool-options]

```ts
type ToolOptions = {
  apiKey?: string;
};
```

## Examples [#examples]

<Tabs items="[&#x22;OpenAI&#x22;, &#x22;Anthropic&#x22;, &#x22;Gemini&#x22;]">
  <Tab>
    ```ts
    import { generateText } from "ai";
    import { openai } from "@ai-sdk/openai";
    import { search, news } from "@serphouse/ai-sdk";

    const { text } = await generateText({
      model: openai("gpt-4o"),
      tools: {
        search: search(),
        news: news(),
      },
      prompt: "Latest AI news",
    });
    ```
  </Tab>

  <Tab>
    ```ts
    import { generateText } from "ai";
    import { anthropic } from "@ai-sdk/anthropic";
    import { search } from "@serphouse/ai-sdk";

    const { text } = await generateText({
      model: anthropic("claude-sonnet-4-20250514"),
      tools: {
        search: search(),
      },
      prompt: "Search for the latest technology news.",
    });
    ```
  </Tab>

  <Tab>
    ```ts
    import { generateText } from "ai";
    import { google } from "@ai-sdk/google";
    import { search } from "@serphouse/ai-sdk";

    const { text } = await generateText({
      model: google("gemini-2.0-flash"),
      tools: {
        search: search(),
      },
      prompt: "Find AI startups founded this year.",
    });
    ```
  </Tab>
</Tabs>

## Using Multiple Tools [#using-multiple-tools]

```ts
import { search, news, shortVideo } from "@serphouse/ai-sdk";

const tools = {
  search: search(),
  news: news(),
  shortVideo: shortVideo(),
};
```

<Callout type="idea">
  The model automatically chooses the correct tool depending on the prompt.
</Callout>

| Prompt                     | Tool           |
| -------------------------- | -------------- |
| Search React documentation | `search()`     |
| Latest NVIDIA news         | `news()`       |
| Best AI coding reels       | `shortVideo()` |

## Error Handling [#error-handling]

<Callout type="error">
  If an API key cannot be found, the SDK throws an authentication error. If SERPHouse returns an API error, it is propagated through the tool execution.
</Callout>

Handle errors normally using `try/catch`:

```ts
try {
  const result = await generateText(...);
} catch (error) {
  console.error(error);
}
```

## Why Use This SDK Instead of Calling the API Directly? [#why-use-this-sdk-instead-of-calling-the-api-directly]

| Direct API               | `@serphouse/ai-sdk`                 |
| ------------------------ | ----------------------------------- |
| Manual HTTP requests     | Native AI SDK tools                 |
| Manual validation        | Built-in Zod schemas                |
| Manual authentication    | Automatic API key resolution        |
| Manual response handling | Automatic tool execution            |
| Boilerplate              | Minimal code                        |
| Model unaware of APIs    | Models can call tools automatically |

## Related Links [#related-links]

<Cards>
  <Card title="LangChain" href="/langchain" />

  <Card title="LlamaIndex" href="/llamaindex" />

  <Card title="MCP Server" href="/mcp-server" />
</Cards>


# Agent Skills (/docs/agent-skills)



Official AI agent skills for the SERPHouse ecosystem. Teach AI agents how to use the SERPHouse REST API, MCP server, and Node.js SDK with accurate, grounded knowledge.

<ResourceCards>
  <ResourceCard title="GitHub" subtitle="SERPHouse/agent-skills" href="https://github.com/SERPHouse/agent-skills" icon="github" />
</ResourceCards>

## Available Skills [#available-skills]

| Skill       | Purpose                                         |
| ----------- | ----------------------------------------------- |
| **Search**  | Routes questions to the correct SERPHouse skill |
| **API**     | Complete REST API reference                     |
| **MCP**     | Complete MCP tool reference                     |
| **Node.js** | Full SDK documentation                          |

## Installation [#installation]

Install only the skill(s) you need.

### Search (Router) [#search-router]

Routes SERPHouse questions to the correct skill doc. Always install this first.

```bash
npx skills add https://github.com/SERPHouse/agent-skills --skill serphouse-search
```

<ManualSetup>
  ```bash
  mkdir -p .skills/serphouse-search
  curl -o .skills/serphouse-search/SKILL.md https://raw.githubusercontent.com/SERPHouse/agent-skills/master/skills/search/SKILL.md
  ```
</ManualSetup>

### API (REST) [#api-rest]

REST API reference: endpoints, auth, parameters, rate limits, credit costs, and cURL examples.

```bash
npx skills add https://github.com/SERPHouse/agent-skills --skill serphouse-api
```

<ManualSetup>
  ```bash
  mkdir -p .skills/serphouse-api
  curl -o .skills/serphouse-api/SKILL.md https://raw.githubusercontent.com/SERPHouse/agent-skills/master/skills/api/SKILL.md
  ```
</ManualSetup>

### MCP (Model Context Protocol) [#mcp-model-context-protocol]

Every MCP tool, parameter, and input format for MCP-compatible clients.

```bash
npx skills add https://github.com/SERPHouse/agent-skills --skill serphouse-mcp
```

<ManualSetup>
  ```bash
  mkdir -p .skills/serphouse-mcp
  curl -o .skills/serphouse-mcp/SKILL.md https://raw.githubusercontent.com/SERPHouse/agent-skills/master/skills/mcp/SKILL.md
  ```
</ManualSetup>

### Node.js (SDK) [#nodejs-sdk]

Full `@serphouse/serphouse-nodejs` SDK docs: imports, types, methods, error handling.

```bash
npx skills add https://github.com/SERPHouse/agent-skills --skill serphouse-nodejs
```

<ManualSetup>
  ```bash
  mkdir -p .skills/serphouse-nodejs
  curl -o .skills/serphouse-nodejs/SKILL.md https://raw.githubusercontent.com/SERPHouse/agent-skills/master/skills/nodejs/SKILL.md
  ```
</ManualSetup>

## Authentication [#authentication]

<Callout type="warn">
  Your API key must be set as an environment variable for the skills to authenticate with SERPHouse.
</Callout>

```bash
export SERPHOUSE_API_KEY="your_api_key"
```

## Related Links [#related-links]

<Cards>
  <Card title="OpenCode" href="/opencode" />

  <Card title="Claude Code" href="/claude-code" />

  <Card title="Cursor" href="/cursor" />
</Cards>


# Claude Code (/docs/claude-code)



Claude Code is Anthropic's AI-powered coding assistant that runs directly in your terminal. By connecting the SERPHouse MCP Server, Claude Code can access SERPHouse tools natively using the Model Context Protocol (MCP).

## Prerequisites [#prerequisites]

* [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview) installed
* An active SERPHouse account
* A valid SERPHouse API key

## Configure the SERPHouse MCP Server [#configure-the-serphouse-mcp-server]

```bash
claude mcp add serphouse \
    --transport http \
    https://mcp.serphouse.com/YOUR_SERPHouse_API_KEY/mcp
```

<Callout type="info">
  Replace <code>YOUR\_SERPHouse\_API\_KEY</code> with your actual SERPHouse API key.
</Callout>

## Verify Configuration [#verify-configuration]

```bash
claude mcp list
```

<Callout type="success">
  If configured correctly, <code>serphouse</code> appears in the list of available MCP servers.
</Callout>

## Using SERPHouse [#using-serphouse]

Once configured, Claude Code automatically invokes SERPHouse whenever a request requires search engine data.

<Callout type="idea">
  Try these example prompts to get started.
</Callout>

* `Search Google for "Laravel Horizon".`
* `Show me the top 10 search results for "AI SEO tools".`
* `Search Google News for "OpenAI".`

## Troubleshooting [#troubleshooting]

| Issue                   | Solution                                                                            |
| ----------------------- | ----------------------------------------------------------------------------------- |
| **401 Unauthorized**    | Verify your API key is valid and active in your [dashboard](https://serphouse.com). |
| **Connection refused**  | Check that `https://mcp.serphouse.com/...` is reachable from your network.          |
| **Tools not appearing** | Restart Claude Code after configuration.                                            |

## Related Links [#related-links]

<Cards>
  <Card title="OpenCode" href="/opencode" />

  <Card title="Cursor" href="/cursor" />

  <Card title="VS Code" href="/vs-code" />
</Cards>


# Codex CLI (/docs/codex-cli)



Codex CLI is OpenAI's terminal-based AI coding assistant with support for Model Context Protocol (MCP) servers.

## Prerequisites [#prerequisites]

* [Codex CLI](https://openai.com/codex) installed
* An active SERPHouse account
* A valid SERPHouse API key

## Configure the SERPHouse MCP Server [#configure-the-serphouse-mcp-server]

Edit `~/.codex/config.toml` and add:

```toml
[mcp_servers.serphouse]
url = "https://mcp.serphouse.com/YOUR_SERPHouse_API_KEY/mcp"
```

<Callout type="info">
  Replace <code>YOUR\_SERPHouse\_API\_KEY</code> with your actual SERPHouse API key.
</Callout>

<Callout type="warn">
  TOML syntax is strict → ensure proper formatting or the server will not load.
</Callout>

## Using SERPHouse [#using-serphouse]

Once configured, Codex CLI automatically invokes SERPHouse whenever a request requires search engine data.

<Callout type="idea">
  Try these example prompts to get started.
</Callout>

* `Search Google for "Laravel Horizon".`
* `Search Google News for "OpenAI".`
* `Search Google Images for "Tesla Model Y".`

## Troubleshooting [#troubleshooting]

| Issue                         | Solution                                                                            |
| ----------------------------- | ----------------------------------------------------------------------------------- |
| **Server doesn't appear**     | Verify your `config.toml` has valid TOML syntax.                                    |
| **401 Unauthorized**          | Verify your API key is valid and active in your [dashboard](https://serphouse.com). |
| **Changes not taking effect** | Restart Codex CLI after making configuration changes.                               |

## Related Links [#related-links]

<Cards>
  <Card title="Claude Code" href="/claude-code" />

  <Card title="Cursor" href="/cursor" />

  <Card title="OpenCode" href="/opencode" />
</Cards>


# Cursor (/docs/cursor)



Cursor is an AI-powered code editor with support for Model Context Protocol (MCP) servers.

## Prerequisites [#prerequisites]

* [Cursor](https://cursor.com) installed
* An active SERPHouse account
* A valid SERPHouse API key

## Configure the SERPHouse MCP Server [#configure-the-serphouse-mcp-server]

Edit `~/.cursor/mcp.json` and add:

```json
{
  "mcpServers": {
    "serphouse": {
      "type": "http",
      "url": "https://mcp.serphouse.com/YOUR_SERPHouse_API_KEY/mcp"
    }
  }
}
```

<Callout type="info">
  Replace <code>YOUR\_SERPHouse\_API\_KEY</code> with your actual SERPHouse API key.
</Callout>

## Using SERPHouse [#using-serphouse]

Once configured, Cursor automatically invokes SERPHouse whenever a request requires search engine data.

<Callout type="idea">
  Try these example prompts to get started.
</Callout>

* `Search Google for "Laravel Horizon".`
* `Show me the top 10 search results for "AI SEO tools".`
* `Search Google News for "OpenAI".`

## Troubleshooting [#troubleshooting]

| Issue                     | Solution                                                                            |
| ------------------------- | ----------------------------------------------------------------------------------- |
| **Server doesn't appear** | Reload Cursor or start a new chat session.                                          |
| **401 Unauthorized**      | Verify your API key is valid and active in your [dashboard](https://serphouse.com). |
| **Tools unavailable**     | Start a new Cursor chat after configuration changes.                                |

## Related Links [#related-links]

<Cards>
  <Card title="Claude Code" href="/claude-code" />

  <Card title="OpenCode" href="/opencode" />

  <Card title="VS Code" href="/vs-code" />
</Cards>


# Open WebUI (/docs/open-web-ui)



[Open WebUI](https://openwebui.com) is a self-hosted AI chat interface with pluggable web search. Connect SERPHouse once and every model can pull live results with citations.

<VisualRef src="/images/agent-harnesses/open-web-ui-flow.png" alt="Flow: User chat to Open WebUI to SERPHouse to model citations" className="w-full rounded-xl border bg-fd-card my-6" />

## Prerequisites [#prerequisites]

* A running Open WebUI instance
* A [SERPHouse API key](https://serphouse.com)
* Admin access

## Configure [#configure]

<Tabs items="['Admin Panel', 'Docker', 'Kubernetes']">
  <Tab value="Admin Panel">
    <Steps>
      <Step>
        Sign in as admin, then open **Admin Panel → Settings → Web Search**.
      </Step>

      <Step>
        Toggle **Web Search** on and set **Web Search Engine** to `serphouse`.
      </Step>

      <Step>
        Paste your API key into **SERPHouse API Key**.

        Optionally set **SERPHouse Domain** (e.g. `google.com`, `google.co.uk`).
      </Step>

      <Step>
        Click **Save**.
      </Step>
    </Steps>
  </Tab>

  <Tab value="Docker">
    Pass env vars on the container. Env vars override Admin Panel values.

    ```bash
    docker run -d \
      -p 3000:8080 \
      -e SERPHOUSE_API_KEY=your_key_here \
      -e SERPHOUSE_DOMAIN=google.com \
      -v open-webui:/app/backend/data \
      --name open-webui \
      --restart always \
      ghcr.io/open-webui/open-webui:main
    ```
  </Tab>

  <Tab value="Kubernetes">
    Add to your Helm `values.yaml` or pod spec:

    ```yaml
    extraEnv:
      - name: SERPHOUSE_API_KEY
        value: "your_key_here"
      - name: SERPHOUSE_DOMAIN
        value: "google.com"
    ```
  </Tab>
</Tabs>

| Variable            | Default      | Notes                                 |
| ------------------- | ------------ | ------------------------------------- |
| `SERPHOUSE_API_KEY` | *(empty)*    | **Required**. Your SERPHouse API key. |
| `SERPHOUSE_DOMAIN`  | `google.com` | Google domain for localized results.  |

<Callout type="warn">
  Keep your API key private. Never commit it or share it in public channels.
</Callout>

## Test it [#test-it]

1. Start a new chat.
2. Click &#x2A;*+** in the prompt field to enable web search.
3. Ask something time-sensitive, e.g. `+latest AI news 2026`.
4. Confirm live results appear in the response.

<Callout type="idea">
  Use the <strong>+</strong> toggle per message. Turn search on only when you
  need fresh data.
</Callout>

## Troubleshooting [#troubleshooting]

| Issue                     | Solution                                                                                             |
| ------------------------- | ---------------------------------------------------------------------------------------------------- |
| **Invalid API key**       | Re-copy the key from the [SERPHouse dashboard](https://serphouse.com). Check for trailing spaces.    |
| **No results**            | Enable &#x2A;*+** web search on the message. Confirm the host can reach `https://api.serphouse.com`. |
| **Wrong region**          | Set `SERPHOUSE_DOMAIN` to a local Google domain, e.g. `google.co.uk`.                                |
| **Model ignores results** | Use a model that supports Open WebUI web search grounding.                                           |
| **Timeouts**              | Check network latency and your SERPHouse credit balance.                                             |

## Related [#related]

<Cards>
  <Card title="Open WebUI Web Search" href="https://docs.openwebui.com/features/chat-conversations/web-search" />

  <Card title="Agent Skills" href="/agent-skills" />

  <Card title="Claude Code" href="/claude-code" />
</Cards>


# OpenCode (/docs/opencode)



OpenCode is an open-source AI coding assistant that supports Model Context Protocol (MCP) servers. By connecting the SERPHouse MCP Server, OpenCode can use SERPHouse as a native search provider.

## Prerequisites [#prerequisites]

* [OpenCode](https://opencode.ai) installed
* An active SERPHouse account
* A valid SERPHouse API key

## Configure the SERPHouse MCP Server [#configure-the-serphouse-mcp-server]

Edit `~/.config/opencode/opencode.json` and add:

```json
{
  "mcp": {
    "serphouse": {
      "enabled": true,
      "type": "remote",
      "url": "https://mcp.serphouse.com/YOUR_SERPHouse_API_KEY/mcp"
    }
  }
}
```

<Callout type="info">
  Replace <code>YOUR\_SERPHouse\_API\_KEY</code> with your actual SERPHouse API key.
</Callout>

## Using SERPHouse [#using-serphouse]

Once configured, OpenCode automatically invokes SERPHouse whenever a request requires search engine data.

<Callout type="idea">
  Try these example prompts to get started.
</Callout>

* `Search Google for "Laravel Horizon".`
* `Show me the top 10 search results for "AI SEO tools".`
* `Search Google News for "OpenAI".`

## Troubleshooting [#troubleshooting]

| Issue                   | Solution                                                                            |
| ----------------------- | ----------------------------------------------------------------------------------- |
| **Server doesn't load** | Verify your configuration file is valid JSON.                                       |
| **401 Unauthorized**    | Verify your API key is valid and active in your [dashboard](https://serphouse.com). |
| **Tool calls fail**     | Check debug logs with `opencode --debug`.                                           |

## Related Links [#related-links]

<Cards>
  <Card title="Claude Code" href="/claude-code" />

  <Card title="Cursor" href="/cursor" />

  <Card title="VS Code" href="/vs-code" />
</Cards>


# Smithery (/docs/smithery)



Smithery is a platform that simplifies MCP server installation and management.

<ResourceCards>
  <ResourceCard title="Smithery" subtitle="serphouse/serphouse-mcp" href="https://smithery.ai/servers/serphouse/serphouse-mcp" icon="smithery" />
</ResourceCards>

## Installation [#installation]

```bash
npx -y @smithery/cli install serphouse/serphouse-mcp --client claude
```

<Callout type="success">
  Replace <code>--client claude</code> with your preferred AI client → Smithery supports Claude Code, Cursor, VS Code, and more.
</Callout>

## Alternative Installation [#alternative-installation]

You can also connect directly using the hosted MCP endpoint:

```
https://mcp.serphouse.com/YOUR_SERPHouse_API_KEY/mcp
```

<Callout type="warn">
  Replace <code>YOUR\_SERPHouse\_API\_KEY</code> with your actual SERPHouse API key.
</Callout>

## Troubleshooting [#troubleshooting]

| Issue                   | Solution                                                                            |
| ----------------------- | ----------------------------------------------------------------------------------- |
| **npx not found**       | Ensure Node.js is installed.                                                        |
| **401 Unauthorized**    | Verify your API key is valid and active in your [dashboard](https://serphouse.com). |
| **Server not detected** | Restart your AI client after installation.                                          |

## Related Links [#related-links]

<Cards>
  <Card title="Claude Code" href="/claude-code" />

  <Card title="Cursor" href="/cursor" />

  <Card title="VS Code" href="/vs-code" />
</Cards>


# VS Code (/docs/vs-code)



Visual Studio Code supports Model Context Protocol (MCP) servers, allowing AI-powered extensions to connect with external tools and services.

## Prerequisites [#prerequisites]

* [Visual Studio Code](https://code.visualstudio.com) installed
* An AI extension with MCP support (e.g., GitHub Copilot, Continue)
* An active SERPHouse account
* A valid SERPHouse API key

## Configure the SERPHouse MCP Server [#configure-the-serphouse-mcp-server]

### One-command install [#one-command-install]

```bash
code --add-mcp '{"name":"serphouse","url":"https://mcp.serphouse.com/YOUR_SERPHouse_API_KEY/mcp","type":"http"}'
```

### Manual setup [#manual-setup]

Open Command Palette (`Ctrl+Shift+P` or `Cmd+Shift+P`) and search for `MCP: Open User Configuration`. Add:

```json
{
  "servers": {
    "serphouse": {
      "type": "http",
      "url": "https://mcp.serphouse.com/YOUR_SERPHouse_API_KEY/mcp"
    }
  }
}
```

<Callout type="info">
  Replace <code>YOUR\_SERPHouse\_API\_KEY</code> with your actual SERPHouse API key in both methods.
</Callout>

## Using SERPHouse [#using-serphouse]

Once configured, your AI assistant automatically invokes SERPHouse whenever a request requires search engine data.

<Callout type="idea">
  Try these example prompts to get started.
</Callout>

* `Search Google for "Laravel 13 documentation".`
* `Search Google News for "OpenAI".`
* `Find top ranking pages for "technical SEO checklist".`

## Troubleshooting [#troubleshooting]

| Issue                     | Solution                                                        |
| ------------------------- | --------------------------------------------------------------- |
| **Server doesn't appear** | Verify MCP configuration contains valid JSON.                   |
| **401 Unauthorized**      | Verify your API key in your [dashboard](https://serphouse.com). |
| **Changes not reflected** | Reload VS Code window after configuration changes.              |

## Related Links [#related-links]

<Cards>
  <Card title="Claude Code" href="/claude-code" />

  <Card title="Cursor" href="/cursor" />

  <Card title="OpenCode" href="/opencode" />
</Cards>


# About SERPHouse (/docs/about-the-serp-api)



<Callout type="info">
  SERPHouse exists to remove the complexity from search data collection. We believe every business, researcher, and developer deserves unfettered access to search engine results, without building and maintaining their own proxy infrastructure, CAPTCHA solvers, or parser pipelines.
</Callout>

Our mission is to be the most **reliable**, **transparent**, and **developer-first** SERP API on the market. We're building the infrastructure layer for web search data, so you don't have to.

The SERPHouse API delivers **top-100 results** tailored to your **search engine**, **location**, and **device** preferences, with two distinct retrieval models: **Scheduled** (async, polling-based) and **Live** (sync, immediate response).

***

## How It Works [#how-it-works]

1. **Submit a query**: Configure your search with engine, location, language, and device parameters.
2. **We handle the complexity**: SERPHouse manages proxy rotation, CAPTCHA resolution, and data parsing.
3. **Receive structured JSON**: Organic results, ads, featured snippets, knowledge panels, and more.

<Callout type="success" title="You Only Pay for Results">
  Every failed request is free. Credits are deducted exclusively on successful responses. No charge for retries, blocks, or errors.
</Callout>

***

## Scheduled API - Asynchronous [#scheduled-api---asynchronous]

The Scheduled model is built for **scale without compromise**. Submit a keyword and receive a persistent `task_id`. Poll the status endpoint when convenient; results wait for you.

<Callout type="idea" title="Built for Scale">
  Queue thousands of keywords without rate-limit concerns. The Scheduled API manages throughput intelligently, processing tasks as capacity allows.
</Callout>

### When to use it [#when-to-use-it]

* **Batch keyword research**: thousands of queries per session
* **Background pipelines**: integrate into ETL workflows and data lakes
* **Rate-limit decoupling**: submit freely, retrieve on your schedule
* **Historical archives**: persistent task IDs let you revisit results at any time

<Callout type="warn" title="Polling Required">
  After submission, call the status endpoint with your `task_id` until the task completes. Use the **Check SERP Status** and **Get SERP Result** endpoints.
</Callout>

***

## Live API - Synchronous [#live-api---synchronous]

The Live model delivers results in a **single request-response cycle**. No polling, no callbacks, just send your query and receive structured data immediately.

<Callout type="success" title="Sub-Second Response">
  Latency-optimized infrastructure returns results in the same HTTP response, making it ideal for time-sensitive applications.
</Callout>

### When to use it [#when-to-use-it-1]

* **Real-time dashboards** and live SERP monitoring
* **User-facing search tools** where speed defines UX
* **Single-keyword lookups** that need instant answers
* **Interactive workflows** that block on search results

Available over both **HTTP GET** and **HTTP POST**, giving you integration flexibility regardless of your stack.

***

## Quick Comparison [#quick-comparison]

| Feature               |  Scheduled (Async) |       Live (Sync)       |
| --------------------- | :----------------: | :---------------------: |
| Response model        |    Polling-based   |        Immediate        |
| Workload fit          | Batch & background | Real-time & interactive |
| Task IDs              |     Persistent     |           N/A           |
| Throughput management |  Built-in queuing  |   Per-minute throttle   |
| HTTP methods          |        POST        |        GET & POST       |

***

## Why SERPHouse [#why-serphouse]

<Callout type="info" title="99.99% Uptime SLA">
  Enterprise-grade infrastructure designed for mission-critical data pipelines. Our track record speaks for itself.
</Callout>

<Callout type="info" title="Zero Infrastructure Overhead">
  We eliminate proxy management, CAPTCHA engineering, and parser maintenance from your roadmap. Focus on your product and leave search infrastructure to us.
</Callout>

***

## Trusted By [#trusted-by]

Thousands of SEO professionals, data teams, and developers rely on SERPHouse to power their search data pipelines, from early-stage startups to established enterprises.

|                                                                            |                                                                 |
| -------------------------------------------------------------------------- | --------------------------------------------------------------- |
| **SEO agencies** monitoring thousands of keywords across client portfolios | **Data scientists** training ML models on fresh SERP data       |
| **SaaS products** embedding competitive intelligence features              | **Enterprise marketing teams** tracking brand presence at scale |

***

## Connect With Us [#connect-with-us]

We believe in building in public. Follow our journey, get updates, and reach out:

<SocialLinks />


# Getting Started (/docs/getting-started)



## Registration [#registration]

To create a new account at SERPHouse is a easy and quick to get into the system, Simply navigate to the Sign Up page and use one of the available sign-up options. You will have access to API Playground and other learning resources.

<Callout type="warn">
  Our system allows single account per user. If you need more testing credits,
  contact our support at
  [getsupport@serphouse.com](mailto:getsupport@serphouse.com).
</Callout>

***

## Authentication [#authentication]

Create an account with SERPHouse and once you confirm your email, you will be able to see an API key on your account dashboard.

### API Key [#api-key]

The API key for SERPHouse API is available after registration and confirming a email. In our documentation, We will refer to the API key by using the following syntax: `<YOUR_API_KEY>`

Passing the API key as a parameter is required in order to authorise your requests. Failing to pass an API key or passing an invalid API key will result in an error.

<Callout type="error" title="Keep your key secure">
  Your API key will directly impact the usage on your subscription plan. In
  order to prevent unauthorized access to your SERPHouse account, make sure you
  store your API key in a secure location and never include it in any public
  scripts or files.
</Callout>

### Authentication Examples [#authentication-examples]

A `Bearer Token` is set in the `Authorization` header of every HTTP Request:

```http
POST /serp/live HTTP/1.1
Host: https://api.serphouse.com
Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json
```

Alternatively, our API allows authentication by passing `api_token` as a query string in every HTTP request:

```http
GET /location/search?q=united&type=google&api_token=<YOUR_API_KEY> HTTP/1.1
Host: api.serphouse.com
```

***

## HTTP Status Codes [#http-status-codes]

| Code | Description                                                                                              |
| ---- | -------------------------------------------------------------------------------------------------------- |
| 200  | Request executed successfully. SERP data available in the `results` field.                               |
| 400  | Invalid request body. Validation error. Check error details in the response.                             |
| 401  | Unauthenticated. Check your API key and ensure it is sent as a Bearer token in the Authorization header. |
| 402  | Insufficient credits. Your account has run out of available credits, or there is a payment issue.        |
| 404  | Endpoint not found. You may have provided an invalid SERP ID in Get or Check API.                        |
| 405  | Method not allowed. Check the HTTP method used in your request.                                          |
| 429  | Rate limit exceeded. Slow down your request rate.                                                        |
| 500  | Internal server error. Our team is notified automatically.                                               |

<Callout type="info" title="2xx only means success">
  Only HTTP 200 indicates a successful request. All other status codes indicate
  an error that needs to be addressed.
</Callout>

<Callout type="warn" title="Response format">
  In some cases, a 200 status may also return this error  retry the request after some time.

  ```json
  {
    "status": "error",
    "msg": "Please try again",
    "error": ""
  }
  ```
</Callout>

***

## Rate Limits [#rate-limits]

A rate limit is the number of API calls an app or user can make within a given time period. If this limit is exceeded or if CPU or total time limits are exceeded, the app or user may be throttled. API requests made by a throttled user or api will fail.

All API requests are subject to rate limits.

<Callout type="idea" title="Need a higher limit?">
  Contact us at [getsupport@serphouse.com](mailto:getsupport@serphouse.com) if
  you are on a custom monthly plan and need to increase your rate limit.
</Callout>

### Standard Rate Limit [#standard-rate-limit]

| Plan        | Rate limit |
| ----------- | ---------: |
| Free plan   | 60 req/min |
| Basic       | 60 req/min |
| Regular     | 60 req/min |
| Custom Plan |  As needed |

Rate limits are calculated per minute.

***

## Pricing [#pricing]

|                                 |    Free    |      Basic     |     Regular    |   Custom  |
| ------------------------------- | :--------: | :------------: | :------------: | :-------: |
| Price                           | $0 / month | $29.99 / month | $49.99 / month |   Custom  |
| API credits                     |    4,000   |     400,000    |     800,000    |   Custom  |
| SERP requests (per 1k)          |      —     |      $0.75     |      $0.62     |   Custom  |
| Auto Complete requests (per 1k) |      —     |      $0.37     |      $0.31     |   Custom  |
| Top 100 Google SERP (per 1k)    |      —     |      $7.50     |      $6.25     |   Custom  |
| Google, Bing & Yahoo data       |  Included  |    Included    |    Included    |  Included |
| HTTPS encryption                |  Included  |    Included    |    Included    |  Included |
| Monthly credit rollover         |     No     |       No       |       No       |     —     |
| Uptime SLA                      |      —     |     99.95%     |     99.95%     |   99.95%  |
| Success rate                    |      —     |      100%      |      100%      |    100%   |
| Support                         |      —     |    Priority    |    Dedicated   | Dedicated |
| Concurrency                     |     60     |       60       |       60       |   Custom  |

## Related Links [#related-links]

<Cards>
  <Card title="About the SERP API" href="/about-the-serp-api" />

  <Card title="Node.js SDK" href="/node.js-sdk" />

  <Card title="Live (HTTP POST)" href="/extra-apis/live-http-post" />
</Cards>


# Webhook (/docs/webhook)



Use webhooks to get notified about events related to the SERPHouse Batch API, such as [Batch SERP](/extra-apis/batch-serp).

Webhooks (Web Callback, HTTP Push API or Reverse API) are one way that a web application can send information to another application in real-time when a specific event happens.

<Callout type="info">
  You can configure your webhook from the{" "}
  <a href="https://www.serphouse.com/wehook-setting">Webhook Setting Page</a> in
  your dashboard.
</Callout>

## Pingback URL [#pingback-url]

Pingback is also known as callback. It alerts you when a desired task is completed. If you have sent 100 keywords batch request, once SERPHouse server completes processing those keywords they will start hitting the `pingback_url` if you have provided a URL.

Once you receive a pingback request from our server, it means your keyword search has been completed and is ready to retrieve data from our server using the [Get SERP Result](/extra-apis/get-serp-result) API.

<Callout type="success" title="HTTP GET">
  Our Pingback Feature is served via HTTP GET Request.
</Callout>

## Postback URL [#postback-url]

Postback is commonly known as a Webhook. While using our Batch API (Delayed SERP API), the postback URL helps you reduce your backend work. While sending a Batch Processing request you are allowed to send up to 100 keywords in a single request with `postback_url` for each keyword.

Once your request reaches SERPHouse server, our backend makes a queue of your keywords and executes them on concurrent threads. As soon as our backend completes keyword processing, you will receive an HTTP POST Request on your provided `postback_url`.

As soon as you receive our request, you must safely validate and store the data and free up our request within a specified timeout.

<Callout type="success" title="HTTP POST with JSON">
  Our Postback Feature is served via HTTP POST Request with JSON Body.
</Callout>

## Webhook SSL Verification [#webhook-ssl-verification]

Webhook SSL verification refers to the process of verifying the authenticity and validity of an SSL certificate used by a webhook endpoint. When a webhook is established between two systems, it is crucial to ensure secure communication and prevent potential security risks. SSL certificates are used to encrypt data transmitted between the systems, providing a secure connection.

SSL verification involves checking the SSL certificate presented by the webhook endpoint to ensure it is issued by a trusted certificate authority (CA) and that it has not expired or been revoked. The verification process confirms the webhook endpoint's identity and ensures that the communication is protected against potential man-in-the-middle attacks or unauthorized access.

To perform SSL verification, the system initiating the webhook request typically checks the SSL certificate chain, including the root CA and intermediate certificates, to ensure they are valid. It verifies that the common name or subject alternative name (SAN) in the certificate matches the endpoint's domain name. Additionally, the system checks if the certificate is within its validity period and hasn't been tampered with or revoked.

If the SSL verification fails, it indicates a potential security risk, and the webhook request may be rejected or considered untrustworthy.

<Callout type="info">
  You can enable or disable SSL Verification for your webhook from your{" "}
  <a href="https://www.serphouse.com/wehook-setting">dashboard</a>.
</Callout>

## Webhook Retry Strategy [#webhook-retry-strategy]

Webhook retry strategy allows our Webhook server to make multiple delivery attempts when your server is temporarily unavailable or unreachable. Here's how it works:

| Attempt | Timing                          |
| ------- | ------------------------------- |
| 1st     | Immediate                       |
| 2nd     | 100 seconds after failure       |
| 3rd     | 1,000 seconds after 2nd failure |
| 4th     | 1,800 seconds after 3rd failure |

After these four attempts, if the webhook delivery still fails, it will be marked as a permanent failure.

<Callout type="warn" title="Manual fallback">
  If webhook delivery fails permanently, you can manually retrieve your results
  using our [Get SERP Result](/extra-apis/get-serp-result) API.
</Callout>

## How to Prevent Duplicate Webhooks [#how-to-prevent-duplicate-webhooks]

There could be scenarios where your endpoint might receive the same webhook event multiple times. This is an expected behaviour based on the webhook design. In such a scenario, we recommend you follow **Idempotency**.

You could be receiving the same events multiple times as SERPHouse follows at-least-once delivery semantics. In this approach, if we do not receive a successful response from your server, we resend the webhook. There could be situations where your server accepts the event but fails to respond in 5 seconds. In such cases, the session is marked timeout. It is assumed that the webhook was not processed and is sent again.

<Callout type="idea" title="Use x-serphouse-task-id">
  To prevent an event from being missed, ensure you configure your server to
  handle or receive the same event details multiple times. Check the value of
  the `x-serphouse-task-id` in the webhook request header. The value for this
  header is unique per event and can help you determine the duplicity of a
  webhook event.
</Callout>

## Validate Webhooks from SERPHouse [#validate-webhooks-from-serphouse]

Validate the webhook before you start using them. When your webhook secret key is set, SERPHouse uses it to create a hash signature with each payload. This hash signature is passed with each request under the `x-serphouse-signature` header that you need to validate at your end.

<Callout type="error" title="Secret rotation">
  If you have changed your webhook secret, remember to use the old secret for
  webhook signature validation while retrying older requests. Using the new
  secret will lead to a signature mismatch.
</Callout>

| Header                  | Description                                                           |
| ----------------------- | --------------------------------------------------------------------- |
| `x-serphouse-signature` | HMAC-SHA256 hash of the request body, keyed with your webhook secret. |

## Related Links [#related-links]

<Cards>
  <Card title="Batch SERP" href="/extra-apis/batch-serp" />

  <Card title="Check SERP Status" href="/extra-apis/check-serp-status" />

  <Card title="Get SERP Result" href="/extra-apis/get-serp-result" />
</Cards>


# Hermes (/docs/hermes)



[Hermes Agent](https://hermes-agent.nousresearch.com) is the open-source, self-improving AI agent built by [Nous Research](https://nousresearch.com). It runs anywhere, remembers across sessions, and connects to 20+ messaging platforms. By adding the SERPHouse MCP Server to Hermes, your personal agent gains live Google, Bing, and Yahoo search across every platform you use it on.

<Profile src="/images/personal-agent/herms.jpeg" alt="Hermes Agent logo" />

<Callout type="success" title="Why SERPHouse + Hermes">
  No browser, no scraping, no rate-limit headaches. Hermes gets structured,
  real-time SERP data from 30+ search engines with a single hosted MCP endpoint.
  Zero extra infrastructure to run.
</Callout>

## What You'll Build [#what-youll-build]

| Capability          | How it works                                                               |
| ------------------- | -------------------------------------------------------------------------- |
| **Live web search** | Hermes calls `mcp_serphouse_search` for fresh Google results on demand     |
| **News & media**    | Google / Bing / Yahoo news, images, and videos from any connected platform |
| **Rank tracking**   | Ask about your position for any keyword, engine, and location              |
| **Daily briefings** | Cron-scheduled SERPHouse searches delivered to Telegram, Discord, and more |

## Prerequisites [#prerequisites]

* An active **SERPHouse account** (free credits included on signup)
* A **SERPHouse API key** from your [dashboard](https://serphouse.com)
* A machine with **Bash** and **network access** to install Hermes

<Callout type="info">
  Hermes supports macOS and Linux. Windows users can use WSL2.
</Callout>

## Step 1: Get Your SERPHouse API Key [#step-1-get-your-serphouse-api-key]

<Steps>
  <Step>
    Sign up at [serphouse.com](https://serphouse.com) and confirm your email.
  </Step>

  <Step>
    Open your 

    **Dashboard**

     and copy the 

    **API key**

     shown there.
  </Step>

  <Step>
    Keep it somewhere safe. You'll paste it into the Hermes config next.
  </Step>
</Steps>

<Callout type="error" title="Keep your key secure">
  Your API key maps directly to your credit usage. Never commit it to a
  repository, share it in public channels, or paste it into a screenshot.
</Callout>

## Step 2: Install Hermes [#step-2-install-hermes]

Install the latest Hermes Agent with the official script:

```bash
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
```

<Steps>
  <Step>
    Run the installer above in your terminal.
  </Step>

  <Step>
    Follow the on-screen prompts to pick your model provider and set your API key.
  </Step>

  <Step>
    Confirm the CLI is available:

    ```bash
    hermes --version
    ```
  </Step>
</Steps>

<Callout type="info" title="Prefer a guided setup?">
  The installer accepts flags like <code>--yes</code> for unattended installs.
  Run{" "}

  <code>
    curl -fsSL [https://hermes-agent.nousresearch.com/install.sh](https://hermes-agent.nousresearch.com/install.sh) | bash -- --help
  </code>

  {" "}

  to see every option.
</Callout>

## Step 3: Add the SERPHouse MCP Server [#step-3-add-the-serphouse-mcp-server]

MCP servers are declared in `~/.hermes/config.yaml` under `mcp_servers`. Open the file and add the SERPHouse hosted endpoint:

```yaml
mcp_servers:
  serphouse:
    url: "https://mcp.serphouse.com/YOUR_SERPHouse_API_KEY/mcp"
```

<Callout type="info">
  Replace <code>YOUR\_SERPHouse\_API\_KEY</code> with your actual SERPHouse API
  key. The key is forwarded to the SERPHouse API as a Bearer token.
</Callout>

## Step 4: Start (or Restart) Hermes [#step-4-start-or-restart-hermes]

```bash
hermes chat
```

<Callout type="success" title="Tools auto-register">
  SERPHouse tools are discovered and registered automatically at startup. Tools
  appear as <code>mcp\_serphouse\_\*</code>, for example{" "}
  <code>mcp\_serphouse\_search</code>.
</Callout>

## Step 5: Verify the Server [#step-5-verify-the-server]

To confirm the server is reachable before using it, reload the MCP config inside a session:

```
/reload-mcp
```

Any connection error will be reported immediately.

<Steps>
  <Step>
    Type <code>/reload-mcp</code> in the chat session.
  </Step>

  <Step>
    Watch for a confirmation that <code>serphouse</code> connected with no
    errors.
  </Step>

  <Step>
    Ask your first search query (see below).
  </Step>
</Steps>

<Callout type="info" title="Tune the tool surface">
  You can narrow the tool surface at any time by editing the server entry. See
  the [Hermes MCP
  docs](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp).
</Callout>

## Using SERPHouse [#using-serphouse]

Once connected, just ask. Hermes picks the right SERPHouse tool automatically.

<Callout type="idea" title="Try these example prompts to get started">
  Pick any prompt and send it to Hermes from any connected platform.
</Callout>

<Tabs items="['Rank Tracking', 'News & Media', 'Local SEO', 'Keyword Research', 'Multi-Engine']">
  <Tab value="Rank Tracking">
    * `Where do we rank for "crm software" on Google US desktop?`
    * `Show me the top 20 results for "AI SEO tools" using max_pages.`
  </Tab>

  <Tab value="News & Media">
    * `Search Google News for "OpenAI" and summarize the top stories.` - `Find
        Bing Images for "minimalist desk setup" and list the sources.`
  </Tab>

  <Tab value="Local SEO">
    * `Top Google Local results for "emergency plumber" in Chicago.` - `Who owns
        the top 5 spots for "project management software" in London?`
  </Tab>

  <Tab value="Keyword Research">
    * `What does Autocomplete suggest for "best saas for"?` - `Compare Google and
        Yahoo suggestions for "keyword tracking".`
  </Tab>

  <Tab value="Multi-Engine">
    * `Search Bing for "electric vehicles" and compare with Yahoo results.`
    * `Cross-check Google and Bing news coverage of "UK election".`
  </Tab>
</Tabs>

## Scheduling Searches [#scheduling-searches]

Hermes has built-in cron. Combine it with SERPHouse for daily briefings delivered to any connected platform:

```
/cron add "0 7 * * *" "Search Google News for 'AI SEO' and send a summary here."
```

<Callout type="idea" title="Make it yours">
  Swap the time, query, or channel in the cron expression to fit your routine,
  like a Monday-morning competitor digest or a Friday industry roundup.
</Callout>

## Troubleshooting [#troubleshooting]

| Issue                   | Solution                                                                                            |
| ----------------------- | --------------------------------------------------------------------------------------------------- |
| **Server doesn't load** | Verify the entry is valid YAML under `mcp_servers` and restart Hermes.                              |
| **401 Unauthorized**    | Verify your API key is valid and active in your [dashboard](https://serphouse.com).                 |
| **Tools not appearing** | Run `/reload-mcp` or restart Hermes; then ask for a search.                                         |
| **Credits exhausted**   | Check your account credit balance in the SERPHouse dashboard.                                       |
| **Yahoo search fails**  | Call the domain list tool first. `yahoo.com` is invalid; use a regional domain like `uk.yahoo.com`. |

<Callout type="info" title="Still stuck?">
  Most issues are fixed by re-verifying your API key, credit balance, and the
  endpoint URL. If it persists, contact [SERPHouse
  support](https://serphouse.com) at
  [getsupport@serphouse.com](mailto:getsupport@serphouse.com).
</Callout>

## Related Links [#related-links]

<Cards>
  <Card title="OpenClaw" href="/openclaw" />

  <Card title="MCP Server" href="/mcp-server" />

  <Card title="Agent Skills" href="/agent-skills" />
</Cards>


# OpenClaw (/docs/openclaw)



[OpenClaw](https://openclaw.ai) is the open-source personal AI assistant that connects Discord, Telegram, WhatsApp, Slack, and more to AI agents on your own hardware. It runs as a persistent Gateway daemon with memory that survives across sessions. By adding the SERPHouse MCP Server, OpenClaw can pull live Google, Bing, and Yahoo results from any channel.

<Profile src="/images/personal-agent/openclaw.png" alt="OpenClaw logo" />

<Callout type="success" title="Why SERPHouse + OpenClaw">
  The Gateway runs 24/7 on your own hardware, so SERPHouse search is always one
  message away. No browser, no scraping, no maintenance.
</Callout>

## What You'll Build [#what-youll-build]

| Capability               | How it works                                                           |
| ------------------------ | ---------------------------------------------------------------------- |
| **Always-on search**     | Message from any platform, get live Google / Bing / Yahoo results back |
| **Local business data**  | Google Local results for nearby businesses on demand                   |
| **Media search**         | Bing Images, Google News, Yahoo News from any channel                  |
| **Multi-engine compare** | Ask for the same query across engines and get a comparison             |

## Prerequisites [#prerequisites]

* A machine running **Linux or macOS** to host the Gateway
* An active **SERPHouse account** (free credits included on signup)
* A **SERPHouse API key** from your [dashboard](https://serphouse.com)

<Callout type="info">
  OpenClaw's install wizard asks for a model provider and API key during
  onboarding. Have those ready.
</Callout>

## Step 1: Get Your SERPHouse API Key [#step-1-get-your-serphouse-api-key]

<Steps>
  <Step>
    Sign up at [serphouse.com](https://serphouse.com) and confirm your email.
  </Step>

  <Step>
    Open your 

    **Dashboard**

     and copy the 

    **API key**

     shown there.
  </Step>

  <Step>
    Keep it handy. You'll add it to OpenClaw next.
  </Step>
</Steps>

<Callout type="error" title="Keep your key secure">
  Your API key maps directly to your credit usage. Never commit it to a
  repository, share it in public channels, or paste it into a screenshot.
</Callout>

## Step 2: Install OpenClaw [#step-2-install-openclaw]

If you haven't set OpenClaw up yet:

```bash
curl -fsSL https://openclaw.ai/install.sh | bash
openclaw onboard --install-daemon
```

<Steps>
  <Step>
    Run the install script above.
  </Step>

  <Step>
    Run <code>openclaw onboard --install-daemon</code> to start onboarding and install the Gateway as a background daemon.
  </Step>

  <Step>
    Follow the wizard: pick a **model provider**, set an **API key**, and configure the **Gateway**.
  </Step>

  <Step>
    Confirm the daemon is running:

    ```bash
    openclaw gateway status
    ```
  </Step>
</Steps>

<Callout type="info" title="Already running OpenClaw?">
  Skip straight to the next step. The SERPHouse server plugs into an existing
  install without re-onboarding.
</Callout>

## Step 3: Add the SERPHouse MCP Server [#step-3-add-the-serphouse-mcp-server]

MCP server definitions live under `mcp.servers` in `~/.openclaw/openclaw.json`. Add the SERPHouse hosted endpoint:

```json
{
  "mcp": {
    "servers": {
      "serphouse": {
        "url": "https://mcp.serphouse.com/YOUR_SERPHouse_API_KEY/mcp",
        "transport": "streamable-http",
        "enabled": true
      }
    }
  }
}
```

<Callout type="info">
  Replace <code>YOUR\_SERPHouse\_API\_KEY</code> with your actual SERPHouse API
  key. The key is forwarded to the SERPHouse API as a Bearer token.
</Callout>

Restart the Gateway to pick up the new definition:

```bash
openclaw gateway restart
```

### Prefer the CLI? [#prefer-the-cli]

The same server can be added in one command:

```bash
openclaw mcp add serphouse \
  --url https://mcp.serphouse.com/YOUR_SERPHouse_API_KEY/mcp \
  --transport streamable-http
```

<Callout type="idea" title="Other ways to add it">
  You can also add the server from the **Control UI: Settings → MCP → Add
  server*&#x2A;, or in a chat via &#x2A;*+ → Connectors → Add MCP server…**.
</Callout>

## Step 4: Verify the Server [#step-4-verify-the-server]

Probe the server to confirm it connects and advertises tools:

```bash
openclaw mcp doctor serphouse --probe
```

<Callout type="success" title="Probe passes">
  A successful probe lists the SERPHouse tools (search, images, news, and more)
  that OpenClaw can now call.
</Callout>

<Steps>
  <Step>
    Run the doctor probe above.
  </Step>

  <Step>
    Confirm <code>serphouse</code> reports <code>connected</code> and the tool
    list is non-empty.
  </Step>

  <Step>
    Message your assistant from any channel and ask your first search query.
  </Step>
</Steps>

## Using SERPHouse [#using-serphouse]

Once connected, message your assistant from any channel. OpenClaw picks the right SERPHouse tool automatically.

<Callout type="idea" title="Try these example prompts to get started">
  Pick any prompt and send it from Discord, Telegram, WhatsApp, Slack, or the
  web chat.
</Callout>

<Tabs items="['Rank Tracking', 'News & Media', 'Local SEO', 'Media Search', 'Multi-Engine']">
  <Tab value="Rank Tracking">
    * `Where do we rank for "crm software" on Google US desktop?`
    * `Who owns the top 5 spots for "project management software" in London?`
  </Tab>

  <Tab value="News & Media">
    * `Search Google News for "OpenAI" and summarize the top stories.` - `What is
        Yahoo News covering about "electric vehicles" right now?`
  </Tab>

  <Tab value="Local SEO">
    * `Top Google Local results for "emergency plumber" in Chicago.` - `Find the
        best-rated coffee shops near "Austin, Texas".`
  </Tab>

  <Tab value="Media Search">
    * `Search Bing Images for "minimalist desk setup".` - `Show me Google Videos
        for "WebAssembly tutorial".`
  </Tab>

  <Tab value="Multi-Engine">
    * `Compare Yahoo and Google news results for "electric vehicles".`
    * `Cross-check Bing and Google web results for "AI agents".`
  </Tab>
</Tabs>

## Troubleshooting [#troubleshooting]

| Issue                                   | Solution                                                                                            |
| --------------------------------------- | --------------------------------------------------------------------------------------------------- |
| **Server appears but exposes no tools** | Run `openclaw mcp doctor serphouse --probe`. Check `toolFilter.include`/`exclude` if you added one. |
| **401 Unauthorized**                    | Verify your API key is valid and active in your [dashboard](https://serphouse.com).                 |
| **Changes don't reach the agent**       | Restart the Gateway or run `openclaw mcp reload`.                                                   |
| **Credits exhausted**                   | Check your account credit balance in the SERPHouse dashboard.                                       |
| **Yahoo search fails**                  | Use a regional domain: call the domain list tool first; `yahoo.com` is invalid.                     |

<Callout type="info" title="Still stuck?">
  Re-verify your API key, credit balance, and the endpoint URL first. If it
  persists, contact [SERPHouse support](https://serphouse.com) at
  [getsupport@serphouse.com](mailto:getsupport@serphouse.com).
</Callout>

## Related Links [#related-links]

<Cards>
  <Card title="Hermes" href="/hermes" />

  <Card title="MCP Server" href="/mcp-server" />

  <Card title="Agent Skills" href="/agent-skills" />
</Cards>


# MCP Server (/docs/mcp-server)



The SERPHouse MCP Server enables AI assistants to access SERPHouse APIs through the Model Context Protocol (MCP). Once configured, supported AI clients can perform Google, Bing, and Yahoo searches, retrieve SERP data, look up locations, and check account details → all from within a conversation.

<Callout type="success" title="Fully Managed">
  The SERPHouse MCP Server is fully managed by SERPHouse: no server to install,
  host, or maintain.
</Callout>

<ResourceCards>
  <ResourceCard title="GitHub" subtitle="SERPHouse/serphouse-mcp" href="https://github.com/SERPHouse/serphouse-mcp" icon="github" />

  <ResourceCard title="NPM" subtitle="serphouse-mcp" href="https://www.npmjs.com/package/serphouse-mcp" icon="npm" />
</ResourceCards>

### Hosted (Default) [#hosted-default]

No infrastructure to manage. The endpoint is always available:

```
https://mcp.serphouse.com/YOUR_SERPHouse_API_KEY/mcp
```

## Quick Start (Hosted) [#quick-start-hosted]

1. Get your API key from the [SERPHouse Dashboard](https://www.serphouse.com/).
2. Add the server to your MCP client config:

```json
{
  "mcpServers": {
    "serphouse": {
      "url": "https://mcp.serphouse.com/YOUR_SERPHouse_API_KEY/mcp"
    }
  }
}
```

Replace `YOUR_SERPHouse_API_KEY` with your actual API key.

3. Start your AI assistant and ask it to search the web.

## Authentication [#authentication]

SERPHouse MCP authenticates using your API key passed as part of the MCP endpoint URL. The key is forwarded to the SERPHouse API as a Bearer token.

```json
{
  "mcpServers": {
    "serphouse": {
      "url": "https://mcp.serphouse.com/YOUR_SERPHouse_API_KEY/mcp"
    }
  }
}
```

<Callout type="info">
  Tools and resources can be discovered **without** a key. The API key is only
  required when calling actual SERPHouse API tools.
</Callout>

## What You Can Ask [#what-you-can-ask]

| Use case                  | Example prompt                                                            |
| ------------------------- | ------------------------------------------------------------------------- |
| **Rank tracking**         | *"Where do we rank for 'crm software' on Google US desktop?"*             |
| **Competitor analysis**   | *"Who owns the top 5 spots for 'project management software' in London?"* |
| **Local search**          | *"Top Google Local results for 'emergency plumber' in Chicago."*          |
| **Keyword discovery**     | *"What does Autocomplete suggest for 'best saas for'?"*                   |
| **Multi-engine coverage** | *"Compare Yahoo and Google news results for 'electric vehicles'."*        |
| **Shopping research**     | *"Search Google Shopping for mechanical keyboards under $150."*           |

## Deployment Options [#deployment-options]

### Self-Hosted [#self-hosted]

<Callout type="warn">
  Only use self-hosted if you need to run the server behind a firewall or in an
  air-gapped environment. For most use cases, the hosted endpoint is
  recommended.
</Callout>

Run the server on your own infrastructure via Docker or Node.

**Docker:**

```bash
docker run -e PORT=8080 -p 8080:8080 serphouse/serphouse-mcp
```

Then configure your MCP client:

```json
{
  "mcpServers": {
    "serphouse": {
      "url": "http://localhost:8080/{API_KEY}/mcp"
    }
  }
}
```

**Node:**

```bash
npx serphouse-mcp
```

Set the API key via the `SERPHOUSE_API_KEY` environment variable for stdio mode:

```json
{
  "mcpServers": {
    "serphouse": {
      "command": "npx",
      "args": ["serphouse-mcp"],
      "env": {
        "SERPHOUSE_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}
```

## Available Tools [#available-tools]

The SERPHouse MCP Server registers **23 tools** across five categories.

### Reference Tools [#reference-tools]

Use these to discover supported domains, languages, and location IDs.

| Tool                        | Description                                                                                           |
| --------------------------- | ----------------------------------------------------------------------------------------------------- |
| `serphouse_domain_list`     | List supported search domains. Call before Yahoo searches → use regional domains like `uk.yahoo.com`. |
| `serphouse_language_list`   | Get supported language codes for Google, Bing, or Yahoo.                                              |
| `serphouse_location_search` | Search SERPHouse location IDs and names for Google or Bing targeting.                                 |
| `serphouse_account_info`    | Get SERPHouse account plan and credit usage.                                                          |

### Default / Lite Search [#default--lite-search]

Fast, lightweight Google organic results. Only `q` is required; `gl` defaults to `US`.

| Tool                        | Description                                       |
| --------------------------- | ------------------------------------------------- |
| `serphouse_search`          | Default web search. Recommended for most queries. |
| `serphouse_google_web_lite` | Alias of `serphouse_search`.                      |

Use `serphouse_google_web` when you need `device`, `gfilter`, or `num_result`. Use `serphouse_serp_google_advanced` for SEO rankings beyond the top 10.

### Google SERP Tools [#google-serp-tools]

Full-featured Google search with device targeting, location, and result control. These require `loc` or `loc_id`.

| Tool                             | Description                                                              |
| -------------------------------- | ------------------------------------------------------------------------ |
| `serphouse_google_web`           | Full Google web search with device, gfilter, and num\_result options.    |
| `serphouse_google_image`         | Google Image search.                                                     |
| `serphouse_google_news`          | Google News search.                                                      |
| `serphouse_google_shop`          | Google Shopping search.                                                  |
| `serphouse_serp_google_advanced` | SEO ranking checks: fetch up to 100 results per query using `max_pages`. |

### Bing SERP Tools [#bing-serp-tools]

Real-time Bing search across web, images, and news. Requires `loc` or `loc_id`.

| Tool                   | Description        |
| ---------------------- | ------------------ |
| `serphouse_bing_web`   | Bing web search.   |
| `serphouse_bing_image` | Bing image search. |
| `serphouse_bing_news`  | Bing news search.  |

### Yahoo SERP Tools [#yahoo-serp-tools]

Real-time Yahoo search across web, images, and news. Uses regional Yahoo domains (e.g., `uk.yahoo.com`). Does **not** require location.

| Tool                    | Description         |
| ----------------------- | ------------------- |
| `serphouse_yahoo_web`   | Yahoo web search.   |
| `serphouse_yahoo_image` | Yahoo image search. |
| `serphouse_yahoo_news`  | Yahoo news search.  |

### Google Verticals [#google-verticals]

Specialized Google search verticals for jobs, autocomplete, videos, forums, and local business discovery.

| Tool                            | Description                                                         |
| ------------------------------- | ------------------------------------------------------------------- |
| `serphouse_google_jobs`         | Google Jobs search.                                                 |
| `serphouse_google_autocomplete` | Google Autocomplete suggestions. Requires `loc` (for localization). |
| `serphouse_google_videos`       | Google Videos search with duration, quality, and captions filters.  |
| `serphouse_google_short_videos` | Google Short Videos search.                                         |
| `serphouse_google_forums`       | Google Forums / Discussions search.                                 |
| `serphouse_google_local`        | Google Local business results (maps).                               |

## MCP Resources [#mcp-resources]

The server also provides built-in resources that teach AI assistants how to use the tools correctly:

| Resource             | Description                                                                 |
| -------------------- | --------------------------------------------------------------------------- |
| `serphouse_guide`    | Tool catalog with routing rules, location guidance, and domain conventions. |
| `serphouse_examples` | Minimal request examples for each search engine.                            |

## Location Targeting [#location-targeting]

Location targeting works differently depending on the tool category:

| Tool group                                                                                                                                   | Method                                     | Required |
| -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | -------- |
| `serphouse_search` / `serphouse_google_web_lite`                                                                                             | `gl` (country code) or `loc` (name string) | Optional |
| `serphouse_google_web` / `serphouse_google_image` / `serphouse_google_news` / `serphouse_google_shop` / `serphouse_serp_google_advanced`     | `loc` or `loc_id`                          | **Yes**  |
| `serphouse_bing_web` / `serphouse_bing_image` / `serphouse_bing_news`                                                                        | `loc` or `loc_id`                          | **Yes**  |
| `serphouse_yahoo_web` / `serphouse_yahoo_image` / `serphouse_yahoo_news`                                                                     | Not supported                              | No       |
| `serphouse_google_jobs` / `serphouse_google_videos` / `serphouse_google_short_videos` / `serphouse_google_forums` / `serphouse_google_local` | `loc` or `loc_id`                          | **Yes**  |
| `serphouse_google_autocomplete`                                                                                                              | `loc` (name string, not ID)                | **Yes**  |

Use `serphouse_location_search` to find location IDs for precise targeting.

## Troubleshooting [#troubleshooting]

<Callout type="idea" title="Quick tips">
  Most issues are resolved by verifying your API key, checking your credit
  balance, and ensuring the endpoint URL is correct.
</Callout>

| Issue                   | Solution                                                                                                  |
| ----------------------- | --------------------------------------------------------------------------------------------------------- |
| **401 Unauthorized**    | Verify your API key is valid and active in the SERPHouse Dashboard.                                       |
| **Connection failed**   | Ensure the endpoint URL is correct and your network allows outbound HTTPS.                                |
| **Tools not appearing** | Restart your AI client after adding the MCP server.                                                       |
| **Request failed**      | Check your account has sufficient credits and the requested tool is supported.                            |
| **Yahoo search fails**  | Call `serphouse_domain_list` first → `yahoo.com` is not valid. Use a regional domain like `uk.yahoo.com`. |

## Support [#support]

* Contact the [SERPHouse support team](https://www.serphouse.com/) at [getsupport@serphouse.com](mailto:getsupport@serphouse.com) for assistance.
* Report bugs or request features on the [GitHub repository](https://github.com/SERPHouse/serphouse-mcp).

## Related Links [#related-links]

<Cards>
  <Card title="Node.js SDK" href="/node.js-sdk" />

  <Card title="Python SDK" href="/python-sdk" />

  <Card title="PHP SDK" href="/php-sdk" />

  <Card title="Agent Skills" href="/agent-skills" />
</Cards>


# Node.js SDK (/docs/node.js-sdk)



The official Node.js SDK makes it easy to integrate the SERPHouse API into any Node.js application.

Instead of manually creating HTTP requests, the SDK handles authentication, request formatting, and response parsing so you can focus on building your application.

<Callout type="info">
  The SDK provides access to Google SERP, Bing SERP, Yahoo SERP, domains,
  languages, locations, and account information.
</Callout>

<ResourceCards>
  <ResourceCard title="GitHub" subtitle="SERPHouse/serphouse-nodejs" href="https://github.com/SERPHouse/serphouse-nodejs" icon="github" />

  <ResourceCard title="NPM" subtitle="@serphouse/serphouse-nodejs" href="https://www.npmjs.com/package/@serphouse/serphouse-nodejs" icon="npm" />
</ResourceCards>

## Requirements [#requirements]

* Node.js 18+
* npm or yarn

## Installation [#installation]

<ApiCodeTabs
  items="[
  { label: &#x22;npm&#x22;, code: &#x22;npm install @serphouse/serphouse-nodejs&#x22; },
  { label: &#x22;yarn&#x22;, code: &#x22;yarn add @serphouse/serphouse-nodejs&#x22; },
  { label: &#x22;pnpm&#x22;, code: &#x22;pnpm add @serphouse/serphouse-nodejs&#x22; },
  { label: &#x22;bun&#x22;, code: &#x22;bun add @serphouse/serphouse-nodejs&#x22; },
  { label: &#x22;deno&#x22;, code: &#x22;deno add npm:@serphouse/serphouse-nodejs&#x22; },
]"
/>

## Get Your API Key [#get-your-api-key]

Create a SERPHouse account and generate an API key from your dashboard.

## Initialize the Client [#initialize-the-client]

```javascript
import { SERPHouse } from "@serphouse/serphouse-nodejs";

const client = new SERPHouse(process.env.SERPHOUSE_API_KEY);
```

<Callout type="warn">
  Using environment variables is recommended. Never hardcode your API key in
  source code.
</Callout>

```bash
SERPHOUSE_API_KEY=your_api_key
```

## Quick Start [#quick-start]

```javascript
const { results } = await client.google.search({
  q: "Coffee",
  domain: "google.com",
  lang: "en",
  device: "desktop",
  loc: "Texas, United States",
});

console.log(results);
```

## Available Services [#available-services]

The SDK exposes the following namespaces.

| Service         | Description                                   |
| --------------- | --------------------------------------------- |
| `client.google` | Google SERP APIs (search, image, news, video) |
| `client.bing`   | Bing SERP APIs (search, image, news)          |
| `client.yahoo`  | Yahoo SERP APIs (search, image, news)         |
| `client.extra`  | Account info, domains, languages, locations   |

## Google SERP [#google-serp]

### Live Search [#live-search]

Retrieve search results immediately.

```javascript
const { results } = await client.google.search({
  q: "Coffee",
  domain: "google.com",
  lang: "en",
  device: "desktop",
  loc: "Texas, United States",
  page: 1,
});
```

### Search Other Engines [#search-other-engines]

The same pattern works for Bing and Yahoo.

```javascript
const { results } = await client.bing.search({
  q: "Coffee",
  lang: "en",
  device: "desktop",
  loc: "Texas, United States",
});
```

```javascript
const { results } = await client.yahoo.search({
  q: "Coffee",
  domain: "uk.yahoo.com",
  lang: "en",
  device: "desktop",
});
```

<Callout type="info">
  Google and Bing searches require a location — pass `loc` or `loc_id` (not
  both). Yahoo searches do not require a location.
</Callout>

### JSON or HTML [#json-or-html]

Requests return structured JSON by default. Pass `{ responseType: "html" }` as
the second argument to get raw HTML instead.

```javascript
const { results } = await client.google.search(
  {
    q: "Coffee",
    domain: "google.com",
    lang: "en",
    device: "desktop",
    loc: "Texas, United States",
  },
  { responseType: "html" },
);
```

## Domains [#domains]

Retrieve all supported search domains.

```javascript
const { results } = await client.extra.domain_list();
```

## Languages [#languages]

Retrieve supported languages.

```javascript
const { results } = await client.extra.language_list();
```

Retrieve Bing languages.

```javascript
const { results } = await client.extra.language_list({
  type: "bing",
});
```

## Locations [#locations]

Search available locations.

```javascript
const { results } = await client.extra.location_search({
  q: "Texas",
  type: "google",
});
```

## Account [#account]

Retrieve account details.

```javascript
const { results } = await client.extra.account_info();
```

## Error Handling [#error-handling]

<Callout type="idea" title="Always handle errors">
  Network issues, invalid API keys, and rate limits can all cause requests to
  fail. Always use try-catch.
</Callout>

```javascript
import { SERPHouse, SERPHouseError } from "@serphouse/serphouse-nodejs";

try {
  const { results } = await client.google.search({
    q: "Coffee",
    domain: "google.com",
    lang: "en",
    device: "desktop",
    loc: "Texas, United States",
  });
  console.log(results);
} catch (error) {
  if (error instanceof SERPHouseError) {
    console.error(`HTTP ${error.statusCode}: ${error.apiMessage}`);
  } else {
    console.error(error.message);
  }
}
```

## Environment Variables [#environment-variables]

Store your API key securely.

```bash
SERPHOUSE_API_KEY=your_api_key
```

```javascript
import "dotenv/config";
import { SERPHouse } from "@serphouse/serphouse-nodejs";

const client = new SERPHouse(process.env.SERPHOUSE_API_KEY);
```

## Complete Example [#complete-example]

```javascript
import "dotenv/config";
import { SERPHouse } from "@serphouse/serphouse-nodejs";

const client = new SERPHouse(process.env.SERPHOUSE_API_KEY);

async function main() {
  const { results } = await client.google.search({
    q: "Coffee",
    domain: "google.com",
    lang: "en",
    device: "desktop",
    loc: "Texas, United States",
  });

  console.log(results);
}

main();
```

## Support [#support]

If you encounter any issues while installing, configuring, or using the SERPHouse Node.js SDK, we're here to help.

* Contact the SERPHouse support team at [getsupport@serphouse.com](mailto:getsupport@serphouse.com) for assistance.
* Report bugs or request features by opening an issue on the GitHub repository.

## Related Links [#related-links]

<Cards>
  <Card title="Python SDK" href="/python-sdk" />

  <Card title="PHP SDK" href="/php-sdk" />

  <Card title="MCP Server" href="/mcp-server" />
</Cards>


# PHP SDK (/docs/php-sdk)



The official PHP SDK makes it easy to integrate the SERPHouse API into any PHP application.

<ResourceCards>
  <ResourceCard title="GitHub" subtitle="SERPHouse/serphouse-php" href="https://github.com/SERPHouse/serphouse-php" icon="github" />

  <ResourceCard title="Packagist" subtitle="serphouse/serphouse-php" href="https://packagist.org/packages/serphouse-php" icon="packagist" />
</ResourceCards>

## Requirements [#requirements]

* PHP 7.2+
* Composer

## Installation [#installation]

```bash
composer require serphouse/serphouse-php
```

## Initialize the Client [#initialize-the-client]

```php
require 'vendor/autoload.php';
use SERPHouse\SERPHouseClient;
$client = new SERPHouseClient('YOUR_API_KEY');
```

<Callout type="info">
  Replace `YOUR_API_KEY` with your actual SERPHouse API key from the <a href="https://www.serphouse.com/">dashboard</a>.
</Callout>

## Live SERP Search [#live-serp-search]

```php
$response = $client->serpApi->live([
    'data' => [
        'q' => 'apple',
        'domain' => 'google.com',
        'lang' => 'en',
        'device' => 'desktop',
        'serp_type' => 'web',
        'loc' => 'Texas, United States',
        'page' => 1,
        'num_result' => 10,
    ]
]);
```

## Schedule a Search [#schedule-a-search]

```php
$response = $client->serpApi->schedule([...]);
```

## Check Search Status [#check-search-status]

```php
$response = $client->serpApi->check($searchId);
```

## Get Search Result [#get-search-result]

```php
$response = $client->serpApi->get($searchId);
```

## Additional Services [#additional-services]

```php
$response = $client->domains->list();
$response = $client->languages->list();
$response = $client->location->search(['q' => 'Texas']);
$response = $client->account->fetch();
```

## Exception Handling [#exception-handling]

The SDK throws dedicated exception classes for common error scenarios:

| Exception                             | When it occurs                      |
| ------------------------------------- | ----------------------------------- |
| `SERPHouseUnauthorizedException`      | Invalid or missing API key          |
| `SERPHouseRateLimitExceededException` | Too many requests in a short period |
| `SERPHousePaymentRequiredException`   | Account credits exhausted           |
| `SERPHouseNotFoundException`          | Invalid SERP ID or endpoint         |
| `SERPHouseServerErrorException`       | Internal server error               |

<Callout type="idea" title="Best practice">
  Always wrap API calls in try-catch blocks and handle each exception type appropriately for a robust integration.
</Callout>

## Related Links [#related-links]

<Cards>
  <Card title="Node.js SDK" href="/node.js-sdk" />

  <Card title="Python SDK" href="/python-sdk" />

  <Card title="MCP Server" href="/mcp-server" />
</Cards>


# Python SDK (/docs/python-sdk)



The official Python SDK makes it easy to integrate the SERPHouse API into any Python application.

Instead of manually creating HTTP requests, the SDK handles authentication, request formatting, and response parsing so you can focus on building your application.

<Callout type="info">
  The SDK provides access to Google SERP, Google News, and Google Short Videos
  directly through a simple typed client.
</Callout>

<ResourceCards>
  <ResourceCard title="GitHub" subtitle="SERPHouse/ai-sdk-python" href="https://github.com/SERPHouse/ai-sdk-python" icon="github" />

  <ResourceCard title="PyPI" subtitle="serphouse-ai-sdk" href="https://pypi.org/project/serphouse-ai-sdk/" icon="pypi" />
</ResourceCards>

## Requirements [#requirements]

* Python 3.10+
* pip

## Installation [#installation]

```bash
pip install serphouse-ai-sdk
```

## Get Your API Key [#get-your-api-key]

Create a SERPHouse account and generate an API key from your dashboard.

## Initialize the Client [#initialize-the-client]

```python
from serphouse import SERPHouseClient

client = SERPHouseClient(api_key="YOUR_API_KEY")
```

<Callout type="warn">
  Using environment variables is recommended. Never hardcode your API key in
  source code.
</Callout>

The SDK reads the `SERPHOUSE_API_KEY` environment variable automatically, so the `api_key` argument is optional when it is set:

```bash
export SERPHOUSE_API_KEY=your_api_key
```

```python
from serphouse import SERPHouseClient

client = SERPHouseClient()
```

## Quick Start [#quick-start]

```python
from serphouse import SERPHouseClient

client = SERPHouseClient()

result = client.post("/web-search-lite", {
    "q": "Coffee",
    "gl": "US",
    "device": "desktop",
})

print(result)
```

## Available Endpoints [#available-endpoints]

The client exposes `get` and `post` methods for the SERPHouse API.

| Endpoint                        | Description                  |
| ------------------------------- | ---------------------------- |
| `POST /web-search-lite`         | Google organic web search    |
| `POST /google-news`             | Google News search           |
| `POST /google-short-videos-api` | Google Short Videos (Shorts) |

## Web Search [#web-search]

Search the web with optional location and language targeting.

```python
result = client.post("/web-search-lite", {
    "q": "coffee shops",
    "domain": "google.com",
    "lang": "en",
    "loc": "Austin,Texas,United States",
    "device": "desktop",
    "page": 1,
})
```

You can target a country directly with the `gl` parameter (ISO 3166-1 alpha-2) instead of `loc`.

```python
result = client.post("/web-search-lite", {
    "q": "coffee shops",
    "gl": "US",
})
```

## Google News [#google-news]

```python
result = client.post("/google-news", {
    "q": "artificial intelligence",
    "date_range": "w",
    "device": "desktop",
})
```

## Google Short Videos [#google-short-videos]

```python
result = client.post("/google-short-videos-api", {
    "q": "cooking recipes",
    "video_quality": "high",
})
```

## Request Parameters [#request-parameters]

| Parameter    | Type  | Default                           | Description                                         |
| ------------ | ----- | --------------------------------- | --------------------------------------------------- |
| `q`          | `str` | —                                 | Search query (required)                             |
| `domain`     | `str` | `google.com`                      | Search domain                                       |
| `lang`       | `str` | `en`                              | Language code                                       |
| `loc`        | `str` | `New York,New York,United States` | Location in `City,State,Country` format             |
| `gl`         | `str` | `US`                              | Country code (web search only)                      |
| `device`     | `str` | `desktop`                         | `desktop` or `mobile`                               |
| `page`       | `int` | —                                 | Page number                                         |
| `date_range` | `str` | `y`                               | `h`, `d`, `w`, `m`, `y`, or `YYYY-MM-DD,YYYY-MM-DD` |

## Error Handling [#error-handling]

<Callout type="idea" title="Always handle errors">
  Network issues, invalid API keys, and rate limits can all cause requests to
  fail. Always wrap calls in try-catch.
</Callout>

```python
from serphouse import SERPHouseClient, ApiError

client = SERPHouseClient()

try:
    result = client.post("/web-search-lite", {
        "q": "Coffee",
    })
    print(result)
except ApiError as error:
    print(f"Request failed with status {error.status}: {error}")
```

The SDK raises `ApiError` with a `status` code and `body` payload for any non-success response.

## Complete Example [#complete-example]

```python
import os

from serphouse import SERPHouseClient

client = SERPHouseClient()

def main():
    results = client.post("/web-search-lite", {
        "q": "Coffee",
        "domain": "google.com",
        "lang": "en",
        "device": "desktop",
        "gl": "US",
    })

    print(results)

if __name__ == "__main__":
    main()
```

## Support [#support]

If you encounter any issues while installing, configuring, or using the SERPHouse Python SDK, we're here to help.

* Contact the SERPHouse support team at [getsupport@serphouse.com](mailto:getsupport@serphouse.com) for assistance.
* Report bugs or request features by opening an issue on the GitHub repository.

## Related Links [#related-links]

<Cards>
  <Card title="Node.js SDK" href="/node.js-sdk" />

  <Card title="PHP SDK" href="/php-sdk" />

  <Card title="MCP Server" href="/mcp-server" />
</Cards>


# Bing Image API (/docs/bing-apis/bing-image-api)





Access real-time Bing image search results and discover relevant images from a wide range of online sources with the Bing Image API.

<Callout type="warn">
  Requires authentication → provide your API key as a Bearer token in the
  Authorization header.
</Callout>

`POST` `https://api.serphouse.com/bing-image`

<Callout type="info" title="Response types">
  These are the response types we support. Append a suffix to the endpoint to
  choose the response format.
</Callout>

| Format         | Endpoint                                    |
| -------------- | ------------------------------------------- |
| JSON (default) | `https://api.serphouse.com/bing-image`      |
| Markdown       | `https://api.serphouse.com/bing-image/md`   |
| HTML           | `https://api.serphouse.com/bing-image/html` |

## Headers [#headers]

| Name                                                           | Type   | Description             |
| -------------------------------------------------------------- | ------ | ----------------------- |
| Authorization <span style="{color: &#x22;red&#x22;}">\*</span> | String | Bearer `<YOUR_API_KEY>` |
| Content-Type <span style="{color: &#x22;red&#x22;}">\*</span>  | String | application/json        |

## Request Body [#request-body]

| Name                                                     | Type              | Description                                                                                                                                                                                                                                                                          |
| -------------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| q <span style="{color: &#x22;red&#x22;}">\*</span>       | string            | Search phrase that you want to search                                                                                                                                                                                                                                                |
| lang <span style="{color: &#x22;red&#x22;}">\*</span>    | string            | You can set language for e.g. `en-US` for english `fr-FR` for french.<br />Get the list of available languages by making a separate request to the [Languages List](/extra-apis/languages-list)                                                                                      |
| loc <span style="{color: &#x22;red&#x22;}">\*</span>     | string            | Optional field if you specify `loc_id`<br />&#x2A;*You must choose one of the fields: `loc_id` or `loc`**<br />You can receive the list of available locations of search engines with their loc\_id by making a separate request to the [Locations List](/extra-apis/locations-list) |
| loc\_id <span style="{color: &#x22;red&#x22;}">\*</span> | integer           | Optional field if you specify `loc`<br />&#x2A;*You must choose one of the fields: `loc_id` or `loc`**<br />You can receive the list of available locations of search engines with their loc\_id by making a separate request to the [Locations List](/extra-apis/locations-list)    |
| page                                                     | integer           | Give specific page to get the result of that page number. By default it will get you first page.                                                                                                                                                                                     |
| no\_trace                                                | string \| integer | Enterprise only. Enables NoTrace mode. Accepted values: `0`, `1`, `true`, and `false`. When enabled (`1` or `true`), search parameters, files, and metadata are not stored on our servers.                                                                                           |

<VisualRef title="Bing Image API" src="/images/bing/bing-image-api.png" alt="Bing image search results" />

## Example Request [#example-request]

<ApiExample endpoint="https://api.serphouse.com/bing-image" query="forest waterfall" lang="en-IN" params="{&#x22;loc&#x22;: &#x22;Mumbai,Maharashtra,India&#x22;, &#x22;page&#x22;: 1}" />

## Example Response [#example-response]

<ApiExample mode="response">
  <ApiTab label="JSON" response="bingImageJsonResponse" />

  <ApiTab label="Markdown" response="bingImageMarkdownResponse" lang="markdown" />
</ApiExample>

## Related Links [#related-links]

<Cards>
  <Card title="Bing Search API" href="/bing-apis/bing-search-api" />

  <Card title="Bing News API" href="/bing-apis/bing-news-api" />
</Cards>


# Bing News API (/docs/bing-apis/bing-news-api)





Access real-time Bing News search results and stay informed with the latest news articles, headlines, and trending stories from trusted sources across the web.

<Callout type="warn">
  Requires authentication → provide your API key as a Bearer token in the
  Authorization header.
</Callout>

`POST` `https://api.serphouse.com/bing-news`

<Callout type="info" title="Response types">
  These are the response types we support. Append a suffix to the endpoint to
  choose the response format.
</Callout>

| Format         | Endpoint                                   |
| -------------- | ------------------------------------------ |
| JSON (default) | `https://api.serphouse.com/bing-news`      |
| Markdown       | `https://api.serphouse.com/bing-news/md`   |
| HTML           | `https://api.serphouse.com/bing-news/html` |

## Headers [#headers]

| Name                                                           | Type   | Description             |
| -------------------------------------------------------------- | ------ | ----------------------- |
| Authorization <span style="{color: &#x22;red&#x22;}">\*</span> | String | Bearer `<YOUR_API_KEY>` |
| Content-Type <span style="{color: &#x22;red&#x22;}">\*</span>  | String | application/json        |

## Request Body [#request-body]

| Name                                                     | Type              | Description                                                                                                                                                                                                                                                                          |
| -------------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| q <span style="{color: &#x22;red&#x22;}">\*</span>       | string            | Search phrase that you want to search                                                                                                                                                                                                                                                |
| lang <span style="{color: &#x22;red&#x22;}">\*</span>    | string            | You can set language for e.g. `en-US` for english `fr-FR` for french.<br />Get the list of available languages by making a separate request to the [Languages List](/extra-apis/languages-list)                                                                                      |
| device <span style="{color: &#x22;red&#x22;}">\*</span>  | string            | `desktop` To extract desktop result `mobile` To extract mobile result                                                                                                                                                                                                                |
| loc <span style="{color: &#x22;red&#x22;}">\*</span>     | string            | Optional field if you specify `loc_id`<br />&#x2A;*You must choose one of the fields: `loc_id` or `loc`**<br />You can receive the list of available locations of search engines with their loc\_id by making a separate request to the [Locations List](/extra-apis/locations-list) |
| loc\_id <span style="{color: &#x22;red&#x22;}">\*</span> | integer           | Optional field if you specify `loc`<br />&#x2A;*You must choose one of the fields: `loc_id` or `loc`**<br />You can receive the list of available locations of search engines with their loc\_id by making a separate request to the [Locations List](/extra-apis/locations-list)    |
| page                                                     | integer           | Give specific page to get the result of that page number. By default it will get you first page.                                                                                                                                                                                     |
| no\_trace                                                | string \| integer | Enterprise only. Enables NoTrace mode. Accepted values: `0`, `1`, `true`, and `false`. When enabled (`1` or `true`), search parameters, files, and metadata are not stored on our servers.                                                                                           |

<VisualRef title="Bing News API" src="/images/bing/bing-news-api.png" alt="Bing news search results" />

## Example Request [#example-request]

<ApiExample endpoint="https://api.serphouse.com/bing-news" query="Climate Change" lang="en-US" params="{&#x22;device&#x22;: &#x22;desktop&#x22;, &#x22;loc&#x22;: &#x22;Holly Springs,United States&#x22;}" />

## Example Response [#example-response]

<ApiExample mode="response">
  <ApiTab label="JSON" response="bingNewsJsonResponse" />

  <ApiTab label="Markdown" response="bingNewsMarkdownResponse" lang="markdown" />
</ApiExample>

## Related Links [#related-links]

<Cards>
  <Card title="Bing Search API" href="/bing-apis/bing-search-api" />

  <Card title="Bing Image API" href="/bing-apis/bing-image-api" />
</Cards>


# Bing Search API (/docs/bing-apis/bing-search-api)





Access real-time web search data from Bing, delivering relevant search results from a wide range of websites and online sources.

<Callout type="warn">
  Requires authentication → provide your API key as a Bearer token in the
  Authorization header.
</Callout>

`POST` `https://api.serphouse.com/bing-web`

<Callout type="info" title="Response types">
  These are the response types we support. Append a suffix to the endpoint to
  choose the response format.
</Callout>

| Format         | Endpoint                                  |
| -------------- | ----------------------------------------- |
| JSON (default) | `https://api.serphouse.com/bing-web`      |
| Markdown       | `https://api.serphouse.com/bing-web/md`   |
| HTML           | `https://api.serphouse.com/bing-web/html` |

## Headers [#headers]

| Name                                                           | Type   | Description             |
| -------------------------------------------------------------- | ------ | ----------------------- |
| Authorization <span style="{color: &#x22;red&#x22;}">\*</span> | String | Bearer `<YOUR_API_KEY>` |
| Content-Type <span style="{color: &#x22;red&#x22;}">\*</span>  | String | application/json        |

## Request Body [#request-body]

| Name                                                     | Type              | Description                                                                                                                                                                                                                                                                          |
| -------------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| q <span style="{color: &#x22;red&#x22;}">\*</span>       | string            | Search phrase that you want to search                                                                                                                                                                                                                                                |
| lang <span style="{color: &#x22;red&#x22;}">\*</span>    | string            | You can set language for e.g. `en-US` for english `fr-FR` for french.<br />Get the list of available languages by making a separate request to the [Languages List](/extra-apis/languages-list)                                                                                      |
| device <span style="{color: &#x22;red&#x22;}">\*</span>  | string            | `desktop` To extract desktop result `mobile` To extract mobile result                                                                                                                                                                                                                |
| loc <span style="{color: &#x22;red&#x22;}">\*</span>     | string            | Optional field if you specify `loc_id`<br />&#x2A;*You must choose one of the fields: `loc_id` or `loc`**<br />You can receive the list of available locations of search engines with their loc\_id by making a separate request to the [Locations List](/extra-apis/locations-list) |
| loc\_id <span style="{color: &#x22;red&#x22;}">\*</span> | integer           | Optional field if you specify `loc`<br />&#x2A;*You must choose one of the fields: `loc_id` or `loc`**<br />You can receive the list of available locations of search engines with their loc\_id by making a separate request to the [Locations List](/extra-apis/locations-list)    |
| page                                                     | integer           | Give specific page to get the result of that page number. By default it will get you first page.                                                                                                                                                                                     |
| date\_range                                              | String            | Sometimes you may want to only find information published during a specific time frame.<br /><br />Parameter values can be comma separated date range `YYYY-MM-DD,YYYY-MM-DD` OR<br /><br />`d` Past 24 hours<br />`w` Past week<br />`m` Past month<br />`y` Past year              |
| no\_trace                                                | string \| integer | Enterprise only. Enables NoTrace mode. Accepted values: `0`, `1`, `true`, and `false`. When enabled (`1` or `true`), search parameters, files, and metadata are not stored on our servers.                                                                                           |

<VisualRef title="Bing Search API" src="/images/bing/bing-search-api.png" alt="Bing web search results" />

## Example Request [#example-request]

<ApiExample endpoint="https://api.serphouse.com/bing-web" query="Coffee" lang="en-US" params="{&#x22;device&#x22;: &#x22;desktop&#x22;, &#x22;loc&#x22;: &#x22;United States&#x22;, &#x22;page&#x22;: 1}" />

## Example Response [#example-response]

<ApiExample mode="response">
  <ApiTab label="JSON" response="bingWebSearchJsonResponse" />

  <ApiTab label="Markdown" response="bingWebSearchMarkdownResponse" lang="markdown" />
</ApiExample>

## Related Links [#related-links]

<Cards>
  <Card title="Bing News API" href="/bing-apis/bing-news-api" />

  <Card title="Bing Image API" href="/bing-apis/bing-image-api" />
</Cards>


# Bing APIs (/docs/bing-apis)



SERPHouse Bing APIs deliver structured Bing search results for web, news, and images. Use them when you need Microsoft’s search index alongside Google and Yahoo.

All endpoints require authentication → pass your API key as a Bearer token in the `Authorization` header.

## Endpoints [#endpoints]

<Cards>
  <Card title="Bing Search API" description="Real-time Bing web search results." href="/bing-apis/bing-search-api" />

  <Card title="Bing News API" description="Latest headlines and trending news from Bing." href="/bing-apis/bing-news-api" />

  <Card title="Bing Image API" description="Bing image search results from online sources." href="/bing-apis/bing-image-api" />
</Cards>

## Related [#related]

<Cards>
  <Card title="Getting Started" href="/getting-started" />

  <Card title="Locations List" href="/extra-apis/locations-list" />

  <Card title="Domains List" href="/extra-apis/domains-list" />

  <Card title="Languages List" href="/extra-apis/languages-list" />
</Cards>


# Account Info (/docs/extra-apis/account-info)





Returns account details including email, name, and plan information with credit totals..

<Callout type="warn">
  Requires authentication → provide your API key as a Bearer token in the
  Authorization header.
</Callout>

## Get Account Information [#get-account-information]

`GET` `https://api.serphouse.com/account/info`

### Headers [#headers]

| Name          | Type   | Description             |
| ------------- | ------ | ----------------------- |
| Authorization | String | Bearer `<YOUR_API_KEY>` |

<Callout type="info">
  Returns account details including email, name, and plan information with
  credit totals.
</Callout>

## Example Request [#example-request]

<ApiExample endpoint="https://api.serphouse.com/account/info" method="GET" />

## Example Response [#example-response]

<ApiExample mode="response" response="accountInfoJsonResponse" />

## Related Links [#related-links]

<Cards>
  <Card title="Domains List" href="/extra-apis/domains-list" />

  <Card title="Languages List" href="/extra-apis/languages-list" />

  <Card title="Locations List" href="/extra-apis/locations-list" />
</Cards>


# Batch SERP (/docs/extra-apis/batch-serp)





Below you will find a detailed description of the fields you can use for setting a task.

All POST data should be sent in JSON format (UTF-8 encoding). The task setting is done using the POST method when the array of tasks is sent in JSON format. We recommend setting up to 100 tasks at a time.

<Callout type="warn">
  Requires authentication → provide your API key as a Bearer token in the
  Authorization header.
</Callout>

`POST` `https://api.serphouse.com/serp/schedule`

## Batch SERP [#batch-serp]

### Headers [#headers]

| Name                                                           | Type   | Description             |
| -------------------------------------------------------------- | ------ | ----------------------- |
| Authorization <span style="{color: &#x22;red&#x22;}">\*</span> | String | Bearer `<YOUR_API_KEY>` |
| Content-Type <span style="{color: &#x22;red&#x22;}">\*</span>  | String | application/json        |

### Request Body [#request-body]

| Name                                                        | Type    | Description                                                                                                                                                                                                                                                                                                                                   |
| ----------------------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| q <span style="{color: &#x22;red&#x22;}">\*</span>          | string  | Search phrase that you want to search                                                                                                                                                                                                                                                                                                         |
| domain <span style="{color: &#x22;red&#x22;}">\*</span>     | string  | Choose `google`, `bing` or `yahoo` domain.<br />You can get the list of available search engines by making a separate request to the [Domains List](/extra-apis/domains-list)                                                                                                                                                                 |
| lang <span style="{color: &#x22;red&#x22;}">\*</span>       | string  | You can set language for e.g. `en` for english `fr` for french.<br />Get the list of available languages by making a separate request to the [Languages List](/extra-apis/languages-list)                                                                                                                                                     |
| device <span style="{color: &#x22;red&#x22;}">\*</span>     | string  | Device can be<br />`desktop` To extract desktop result<br />`mobile` To extract mobile result                                                                                                                                                                                                                                                 |
| serp\_type <span style="{color: &#x22;red&#x22;}">\*</span> | string  | Serp type can be<br />`web` Get structured json result search engines web result<br />`news` Get news result from search engines<br />`image` Search image over search engines and get json result                                                                                                                                            |
| loc <span style="{color: &#x22;red&#x22;}">\*</span>        | string  | Optional field if you specify `loc_id`<br />**When choose yahoo domain then field is optional**<br />&#x2A;*You must choose one of the fields: `loc_id` or `loc`**<br />You can receive the list of available locations of search engines with their loc\_id by making a separate request to the [Locations List](/extra-apis/locations-list) |
| loc\_id <span style="{color: &#x22;red&#x22;}">\*</span>    | integer | Optional field if you specify `loc`<br />&#x2A;*You must choose one of the fields: `loc_id` or `loc`**<br />You can receive the list of available locations of search engines with their loc\_id by making a separate request to the [Locations List](/extra-apis/locations-list)                                                             |
| verbatim                                                    | integer | Set Google Verbatim search, Parameter value can be `0` or `1`                                                                                                                                                                                                                                                                                 |
| gfilter                                                     | integer | Parameter defines if the filters for 'Similar Results' and 'Omitted Results' are on or off. It can be set to `1` (default) to enable these filters, or `0` to disable these filters.                                                                                                                                                          |
| page                                                        | integer | Define google/bing serp result page number.                                                                                                                                                                                                                                                                                                   |
| num\_result                                                 | integer | Define number of results you want to get per page.                                                                                                                                                                                                                                                                                            |
| postback\_url                                               | url     | Return URL for sending task results.<br />If you specify the Postback URL there will be no need to use Get SERP Tasks Results for obtaining results. We will send the result of a completed task by a POST request to the URL as soon as the task is completed. You can change your webhook setting from Webhook Settings Page.               |
| pingback\_url                                               | url     | Pingback URL is Notification URL of a completed task.<br />When a task is completed we will notify you by GET request sent to the URL you have specified. You can change your webhook setting from Webhook Settings Page.                                                                                                                     |
| date\_range                                                 | String  | Sometimes you may want to only find information published during a specific time frame. To limit Google results by date<br /><br />Parameter values can be comma separated date range `YYYY-MM-DD,YYYY-MM-DD` OR<br /><br />`h` Past hour<br />`d` Past 24 hours<br />`w` Past week<br />`m` Past month<br />`y` Past year                    |

## Example Request [#example-request]

<ApiExample
  endpoint="https://api.serphouse.com/serp/schedule"
  items="[
{
&#x22;q&#x22;: &#x22;Electric Vehicles&#x22;,
&#x22;domain&#x22;: &#x22;bing.com&#x22;,
&#x22;lang&#x22;: &#x22;en-IN&#x22;,
&#x22;device&#x22;: &#x22;desktop&#x22;,
&#x22;serp_type&#x22;: &#x22;web&#x22;,
&#x22;loc&#x22;: &#x22;Surat,Gujarat,India&#x22;,
&#x22;page&#x22;: 1
},
{
&#x22;q&#x22;: &#x22;TeOlympicsa&#x22;,
&#x22;domain&#x22;: &#x22;google.com&#x22;,
&#x22;lang&#x22;: &#x22;en&#x22;,
&#x22;device&#x22;: &#x22;mobile&#x22;,
&#x22;serp_type&#x22;: &#x22;web&#x22;,
&#x22;loc&#x22;: &#x22;Surat,Gujarat,India&#x22;,
&#x22;page&#x22;: 1
},
{
&#x22;domain&#x22;: &#x22;us.yahoo.com&#x22;,
&#x22;lang&#x22;: &#x22;lang_en&#x22;,
&#x22;q&#x22;: &#x22;Healthy Recipes&#x22;,
&#x22;device&#x22;: &#x22;desktop&#x22;,
&#x22;serp_type&#x22;: &#x22;web&#x22;
}
]"
/>

## Example Response [#example-response]

<ApiExample mode="response">
  <ApiTab label="JSON" response="scheduleSerpJsonResponse" />
</ApiExample>

## Related Links [#related-links]

<Cards>
  <Card title="Get SERP Result" href="/extra-apis/get-serp-result" />

  <Card title="Check SERP Status" href="/extra-apis/check-serp-status" />

  <Card title="Webhook" href="/webhook" />
</Cards>


# Check SERP Status (/docs/extra-apis/check-serp-status)



As a response of the API server, you will get a status of your SERP task.

<Callout type="warn">
  Requires authentication → provide your API key as a Bearer token in the
  Authorization header.
</Callout>

## Get a Status of Your SERP Task [#get-a-status-of-your-serp-task]

`GET` `https://api.serphouse.com/serp/check`

### Query Parameters [#query-parameters]

| Name                                                | Type   | Description                         |
| --------------------------------------------------- | ------ | ----------------------------------- |
| id <span style="{color: &#x22;red&#x22;}">\*</span> | String | Unique identifier of your SERP task |

### Headers [#headers]

| Name                                                           | Type   | Description             |
| -------------------------------------------------------------- | ------ | ----------------------- |
| Authorization <span style="{color: &#x22;red&#x22;}">\*</span> | String | Bearer `<YOUR_API_KEY>` |

## Example Request [#example-request]

<ApiExample endpoint="https://api.serphouse.com/serp/check" method="GET" params="{&#x22;id&#x22;: &#x22;77224195&#x22;}" />

## Example Response [#example-response]

<ApiExample mode="response" response="{ status: &#x22;success&#x22;, msg: &#x22;Completed&#x22;, results: &#x22;&#x22; }" />

## Related Links [#related-links]

<Cards>
  <Card title="Get SERP Result" href="/extra-apis/get-serp-result" />

  <Card title="Batch SERP" href="/extra-apis/batch-serp" />
</Cards>


# Domains List (/docs/extra-apis/domains-list)





Get the full list of supported domains by our SERP API. This list also contains Bing and Yahoo domains.

<Callout type="warn">
  Requires authentication → provide your API key as a Bearer token in the
  Authorization header.
</Callout>

## Get a List of Domains [#get-a-list-of-domains]

`GET` `https://api.serphouse.com/domain/list`

### Headers [#headers]

| Name                                                           | Type   | Description             |
| -------------------------------------------------------------- | ------ | ----------------------- |
| Authorization <span style="{color: &#x22;red&#x22;}">\*</span> | String | Bearer `<YOUR_API_KEY>` |

<Callout type="info">
  Returns a JSON object with a `results` array containing all supported domain
  strings for Google, Bing, and Yahoo.
</Callout>

## Example Request [#example-request]

<ApiExample endpoint="https://api.serphouse.com/domain/list" method="GET" />

## Example Response [#example-response]

<ApiExample mode="response" response="domainsListJsonResponse" />

## Related Links [#related-links]

<Cards>
  <Card title="Languages List" href="/extra-apis/languages-list" />

  <Card title="Locations List" href="/extra-apis/locations-list" />

  <Card title="Account Info" href="/extra-apis/account-info" />
</Cards>


# Get SERP Result (/docs/extra-apis/get-serp-result)





As a response of the API server, you will receive a JSON array containing the result of your SERP query.

<Callout type="warn">
  Requires authentication → provide your API key as a Bearer token in the
  Authorization header.
</Callout>

`GET` `https://api.serphouse.com/serp/get`

<Callout type="info" title="Response types">
  These are the response types we support. Append a suffix to the endpoint to
  choose the response format.
</Callout>

| Format         | Endpoint                                  |
| -------------- | ----------------------------------------- |
| JSON (default) | `https://api.serphouse.com/serp/get`      |
| html           | `https://api.serphouse.com/serp/get/html` |

## Get SERP Result [#get-serp-result]

### Query Parameters [#query-parameters]

| Name                                                | Type   | Description                         |
| --------------------------------------------------- | ------ | ----------------------------------- |
| id <span style="{color: &#x22;red&#x22;}">\*</span> | String | Unique identifier of your SERP task |

### Headers [#headers]

| Name                                                           | Type   | Description             |
| -------------------------------------------------------------- | ------ | ----------------------- |
| Authorization <span style="{color: &#x22;red&#x22;}">\*</span> | String | Bearer `<YOUR_API_KEY>` |

## Example Request [#example-request]

<ApiExample endpoint="https://api.serphouse.com/serp/get" method="GET" params="{&#x22;id&#x22;: &#x22;260357039&#x22;}" />

## Example Response [#example-response]

<ApiExample mode="response" response="getSerpResultJsonResponse" />

## Related Links [#related-links]

<Cards>
  <Card title="Check SERP Status" href="/extra-apis/check-serp-status" />

  <Card title="Batch SERP" href="/extra-apis/batch-serp" />
</Cards>


# Extra APIs (/docs/extra-apis)



Extra APIs cover live and batch SERP workflows, account details, and lookup helpers for domains, languages, and locations. Use these alongside the Google, Bing, and Yahoo search endpoints.

All endpoints require authentication → pass your API key as a Bearer token in the `Authorization` header.

## Live SERP [#live-serp]

<Cards>
  <Card title="Live (HTTP GET)" description="Real-time SERP searches via query parameters." href="/extra-apis/live-http-get" />

  <Card title="Live (HTTP POST)" description="Real-time SERP searches via a JSON request body." href="/extra-apis/live-http-post" />
</Cards>

## Batch SERP [#batch-serp]

<Cards>
  <Card title="Batch SERP" description="Queue SERP tasks with postback and pingback support." href="/extra-apis/batch-serp" />

  <Card title="Check SERP Status" description="Poll the processing status of a scheduled task." href="/extra-apis/check-serp-status" />

  <Card title="Get SERP Result" description="Retrieve results for a completed scheduled task." href="/extra-apis/get-serp-result" />
</Cards>

## Account & Lookups [#account--lookups]

<Cards>
  <Card title="Account Info" description="Plan details, credit usage, and account status." href="/extra-apis/account-info" />

  <Card title="Domains List" description="Supported domains for Google, Bing, and Yahoo." href="/extra-apis/domains-list" />

  <Card title="Languages List" description="Supported language codes for each engine." href="/extra-apis/languages-list" />

  <Card title="Locations List" description="Search Google and Bing locations for geo targeting." href="/extra-apis/locations-list" />
</Cards>

## Related [#related]

<Cards>
  <Card title="Getting Started" href="/getting-started" />

  <Card title="Webhook" href="/webhook" />

  <Card title="Google APIs" href="/google-apis" />

  <Card title="Bing APIs" href="/bing-apis" />

  <Card title="Yahoo APIs" href="/yahoo-apis" />
</Cards>


# Languages List (/docs/extra-apis/languages-list)





Retrieve the full list of languages by Google, Bing, and Yahoo. You can use the language code in performing SERP requests.

<Callout type="warn">
  Requires authentication → provide your API key as a Bearer token in the
  Authorization header.
</Callout>

## Get a Full List of Languages [#get-a-full-list-of-languages]

`GET` `https://api.serphouse.com/language/list/{type}`

### Path Parameters [#path-parameters]

| Name                                                  | Type   | Description                  |
| ----------------------------------------------------- | ------ | ---------------------------- |
| type <span style="{color: &#x22;red&#x22;}">\*</span> | String | `google`, `bing`, or `yahoo` |

### Headers [#headers]

| Name                                                           | Type   | Description             |
| -------------------------------------------------------------- | ------ | ----------------------- |
| Authorization <span style="{color: &#x22;red&#x22;}">\*</span> | String | Bearer `<YOUR_API_KEY>` |

## Example Request [#example-request]

<ApiExample endpoint="https://api.serphouse.com/language/list/google" method="GET" />

## Example Response [#example-response]

<ApiExample mode="response" response="languagesListJsonResponse" />

## Related Links [#related-links]

<Cards>
  <Card title="Domains List" href="/extra-apis/domains-list" />

  <Card title="Locations List" href="/extra-apis/locations-list" />

  <Card title="Account Info" href="/extra-apis/account-info" />
</Cards>


# Live (HTTP GET) (/docs/extra-apis/live-http-get)





<DeprecatedNotice />

Performing a realtime search is as simple as making a GET HTTP request to the SERPHouse live endpoint. The only required parameters are your API key and `q` (your search query).

<Callout type="warn">
  Requires authentication → provide your API key as a Bearer token in the
  Authorization header.
</Callout>

`GET` `https://api.serphouse.com/serp/live`

<Callout type="info" title="Response types">
  These are the response types we support. Append a suffix to the endpoint to
  choose the response format.
</Callout>

| Format         | Endpoint                                   |
| -------------- | ------------------------------------------ |
| JSON (default) | `https://api.serphouse.com/serp/live`      |
| Markdown       | `https://api.serphouse.com/serp/live/md`   |
| HTML           | `https://api.serphouse.com/serp/live/html` |

## Live SERP (GET) [#live-serp-get]

### Query Parameters [#query-parameters]

| Name                                                        | Type   | Description                                                                                                                                                                                                                                                                                                                                   |
| ----------------------------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| q <span style="{color: &#x22;red&#x22;}">\*</span>          | String | Search phrase that you want to search                                                                                                                                                                                                                                                                                                         |
| domain                                                      | String | Choose `google`, `bing` or `yahoo` domain.<br />You can get the list of available search engines by making a separate request to the [Domains List](/extra-apis/domains-list)                                                                                                                                                                 |
| lang                                                        | String | You can set language for e.g. `en` for english `fr` for french.<br />Get the list of available languages by making a separate request to the [Languages List](/extra-apis/languages-list)                                                                                                                                                     |
| device                                                      | String | Device can be<br />`desktop` To extract desktop result<br />`mobile` To extract mobile result                                                                                                                                                                                                                                                 |
| serp\_type                                                  | String | Serp type can be<br />`web` get structured json result search engines web result<br />`news` Get news result from search engines<br />`image` Search image over search engines and get json result                                                                                                                                            |
| loc                                                         | String | Optional field if you specify `loc_id`<br />**When choose yahoo domain then field is optional**<br />&#x2A;*You must choose one of the fields: `loc_id` or `loc`**<br />You can receive the list of available locations of search engines with their loc\_id by making a separate request to the [Locations List](/extra-apis/locations-list) |
| loc\_id                                                     | String | Optional field if you specify `loc`<br />&#x2A;*You must choose one of the fields: `loc_id` or `loc`**<br />You can receive the list of available locations of search engines with their loc\_id by making a separate request to the [Locations List](/extra-apis/locations-list)                                                             |
| verbatim                                                    | String | Set Google Verbatim search, Parameter value can be `0` or `1`                                                                                                                                                                                                                                                                                 |
| gfilter                                                     | String | Parameter defines if the filters for 'Similar Results' and 'Omitted Results' are on or off. It can be set to `1` (default) to enable these filters, or `0` to disable these filters.                                                                                                                                                          |
| page                                                        | String | Give specific page to get the result of that page number. By default it will get you first page.                                                                                                                                                                                                                                              |
| num\_result                                                 | String | Define the number of results you want to get per page. By default, you will get up to 10 results.<br />Maximum 10 results are available.                                                                                                                                                                                                      |
| api\_token <span style="{color: &#x22;red&#x22;}">\*</span> | String | Your API key<br />**Optional** if you specify an Authorization header in request                                                                                                                                                                                                                                                              |
| date\_range                                                 | String | Sometimes you may want to only find information published during a specific time frame. To limit Google results by date<br /><br />Parameter values can be comma separated date range `YYYY-MM-DD,YYYY-MM-DD` OR<br /><br />`h` Past hour<br />`d` Past 24 hours<br />`w` Past week<br />`m` Past month<br />`y` Past year                    |

### Headers [#headers]

| Name                                                           | Type   | Description             |
| -------------------------------------------------------------- | ------ | ----------------------- |
| Authorization <span style="{color: &#x22;red&#x22;}">\*</span> | String | Bearer `<YOUR_API_KEY>` |

<VisualRef title="Live SERP (HTTP GET)" src="/images/extra/live-http-get-api.png" alt="Live SERP results from an HTTP GET request" />

## Example Request [#example-request]

<ApiExample endpoint="https://api.serphouse.com/serp/live" method="GET" query="apple" domain="google.com" lang="en" params="{&#x22;device&#x22;: &#x22;desktop&#x22;, &#x22;serp_type&#x22;: &#x22;web&#x22;, &#x22;loc&#x22;: &#x22;Alba,Texas,United States&#x22;}" />

## Example Response [#example-response]

<ApiExample mode="response">
  <ApiTab label="JSON" response="liveHttpGetJsonResponse" />

  <ApiTab label="Markdown" response="liveHttpGetMarkdownResponse" lang="markdown" />
</ApiExample>

## Related Links [#related-links]

<Cards>
  <Card title="Live (HTTP POST)" href="/extra-apis/live-http-post" />

  <Card title="Batch SERP" href="/extra-apis/batch-serp" />

  <Card title="Google Search API" href="/google-apis/google-search-api" />
</Cards>


# Live (HTTP POST) (/docs/extra-apis/live-http-post)





<DeprecatedNotice />

Performing a realtime search using HTTP POST is very simple with the SERPHouse live endpoint.

<Callout type="warn">
  Requires authentication → provide your API key as a Bearer token in the
  Authorization header.
</Callout>

`POST` `https://api.serphouse.com/serp/live`

<Callout type="info" title="Response types">
  These are the response types we support. Append a suffix to the endpoint to
  choose the response format.
</Callout>

| Format         | Endpoint                                   |
| -------------- | ------------------------------------------ |
| JSON (default) | `https://api.serphouse.com/serp/live`      |
| Markdown       | `https://api.serphouse.com/serp/live/md`   |
| HTML           | `https://api.serphouse.com/serp/live/html` |

## Live SERP (POST) [#live-serp-post]

### Headers [#headers]

| Name                                                           | Type   | Description             |
| -------------------------------------------------------------- | ------ | ----------------------- |
| Authorization <span style="{color: &#x22;red&#x22;}">\*</span> | String | Bearer `<YOUR_API_KEY>` |
| Content-Type <span style="{color: &#x22;red&#x22;}">\*</span>  | String | application/json        |

### Request Body [#request-body]

| Name                                                        | Type              | Description                                                                                                                                                                                                                                                                                                                                   |
| ----------------------------------------------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| q <span style="{color: &#x22;red&#x22;}">\*</span>          | string            | Search phrase that you want to search                                                                                                                                                                                                                                                                                                         |
| domain <span style="{color: &#x22;red&#x22;}">\*</span>     | string            | Choose `google`, `bing` or `yahoo` domain.<br />You can get the list of available search engines by making a separate request to the [Domains List](/extra-apis/domains-list)                                                                                                                                                                 |
| lang <span style="{color: &#x22;red&#x22;}">\*</span>       | string            | You can set language for e.g. `en` for english `fr` for french.<br />Get the list of available languages by making a separate request to the [Languages List](/extra-apis/languages-list)                                                                                                                                                     |
| device <span style="{color: &#x22;red&#x22;}">\*</span>     | string            | Device can be<br />`desktop` To extract desktop result<br />`mobile` To extract mobile result                                                                                                                                                                                                                                                 |
| serp\_type <span style="{color: &#x22;red&#x22;}">\*</span> | string            | Serp type can be<br />`web` Get structured json result search engines web result<br />`news` Get news result from search engines<br />`image` Search image over search engines and get json result<br />`shop` Get a results of a Google Shopping search from search engines                                                                  |
| loc <span style="{color: &#x22;red&#x22;}">\*</span>        | string            | Optional field if you specify `loc_id`<br />**When choose yahoo domain then field is optional**<br />&#x2A;*You must choose one of the fields: `loc_id` or `loc`**<br />You can receive the list of available locations of search engines with their loc\_id by making a separate request to the [Locations List](/extra-apis/locations-list) |
| loc\_id <span style="{color: &#x22;red&#x22;}">\*</span>    | integer           | Optional field if you specify `loc`<br />&#x2A;*You must choose one of the fields: `loc_id` or `loc`**<br />You can receive the list of available locations of search engines with their loc\_id by making a separate request to the [Locations List](/extra-apis/locations-list)                                                             |
| verbatim                                                    | integer           | Set Google Verbatim search, Parameter value can be `0` or `1`                                                                                                                                                                                                                                                                                 |
| gfilter                                                     | integer           | Parameter defines if the filters for 'Similar Results' and 'Omitted Results' are on or off. It can be set to `1` (default) to enable these filters, or `0` to disable these filters.                                                                                                                                                          |
| page                                                        | integer           | Give specific page to get the result of that page number. By default it will get you first page.                                                                                                                                                                                                                                              |
| num\_result                                                 | integer           | Define the number of results you want to get per page. By default, you will get up to 10 results.<br />Maximum 10 results are available.                                                                                                                                                                                                      |
| date\_range                                                 | String            | Sometimes you may want to only find information published during a specific time frame. To limit Google results by date<br /><br />Parameter values can be comma separated date range `YYYY-MM-DD,YYYY-MM-DD` OR<br /><br />`h` Past hour<br />`d` Past 24 hours<br />`w` Past week<br />`m` Past month<br />`y` Past year                    |
| no\_trace                                                   | string \| integer | Enterprise only. Enables NoTrace mode.                                                                                                                                                                                                                                                                                                        |

<VisualRef title="Live SERP (HTTP POST)" src="/images/extra/live-http-post-api.png" alt="Live SERP results from an HTTP POST request" />

## Example Request [#example-request]

<ApiExample endpoint="https://api.serphouse.com/serp/live" query="Artificial Intelligence" domain="google.com" lang="en" params="{&#x22;device&#x22;: &#x22;desktop&#x22;, &#x22;serp_type&#x22;: &#x22;web&#x22;, &#x22;loc&#x22;: &#x22;Rennes,Brittany,France&#x22;, &#x22;page&#x22;: 1}" />

## Example Response [#example-response]

<ApiExample mode="response">
  <ApiTab label="JSON" response="liveHttpPostJsonResponse" />

  <ApiTab label="Markdown" response="liveHttpPostMarkdownResponse" lang="markdown" />
</ApiExample>

## Related Links [#related-links]

<Cards>
  <Card title="Live (HTTP GET)" href="/extra-apis/live-http-get" />

  <Card title="Batch SERP" href="/extra-apis/batch-serp" />

  <Card title="Google Search API" href="/google-apis/google-search-api" />
</Cards>


# Locations List (/docs/extra-apis/locations-list)





We use Google Geographical Targeting, that's why you can use it as a data source. Google and Bing have different locations.

Download the CSV files:

* [Google Locations](https://serphouse-space.nyc3.digitaloceanspaces.com/google_locations.csv)
* [Bing Locations](https://serphouse-space.nyc3.digitaloceanspaces.com/bing_locations.csv)

<Callout type="warn">
  Requires authentication → provide your API key as a Bearer token in the
  Authorization header.
</Callout>

## Get a List of Locations [#get-a-list-of-locations]

`GET` `https://api.serphouse.com/location/search`

### Query Parameters [#query-parameters]

| Name                                                  | Type   | Description                                                                                                                                                   |
| ----------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| q <span style="{color: &#x22;red&#x22;}">\*</span>    | String | search in our location database                                                                                                                               |
| type <span style="{color: &#x22;red&#x22;}">\*</span> | String | Type can be `google` and `bing`.<br />Google and Bing have a different locations so if you are targeting on Bing then pass type as `bing` otherwise `google`. |

### Headers [#headers]

| Name                                                           | Type   | Description             |
| -------------------------------------------------------------- | ------ | ----------------------- |
| Authorization <span style="{color: &#x22;red&#x22;}">\*</span> | String | Bearer `<YOUR_API_KEY>` |

## Example Request [#example-request]

<ApiExample endpoint="https://api.serphouse.com/location/search" method="GET" params="{&#x22;q&#x22;: &#x22;texas&#x22;, &#x22;type&#x22;: &#x22;google&#x22;}" />

<ApiExample mode="response" response="locationsListJsonResponse" />

## Related Links [#related-links]

<Cards>
  <Card title="Domains List" href="/extra-apis/domains-list" />

  <Card title="Languages List" href="/extra-apis/languages-list" />

  <Card title="Account Info" href="/extra-apis/account-info" />
</Cards>


# Google Autocomplete API (/docs/google-apis/google-autocomplete-api)





Retrieve real-time Google search suggestions (autocomplete results) using the Google Auto Complete API. This endpoint returns keyword suggestions exactly like those shown in the Google search bar while typing a query.

<Callout type="info">
  **Pricing:** 5 credits per Google Autocomplete API request.
</Callout>

<Callout type="warn">
  Requires authentication → provide your API key as a Bearer token in the
  Authorization header.
</Callout>

`POST` `https://api.serphouse.com/google-autocomplete-api`

## Headers [#headers]

| Name                                                           | Type   | Description             |
| -------------------------------------------------------------- | ------ | ----------------------- |
| Authorization <span style="{color: &#x22;red&#x22;}">\*</span> | String | Bearer `<YOUR_API_KEY>` |
| Content-Type <span style="{color: &#x22;red&#x22;}">\*</span>  | String | application/json        |

## Request Body [#request-body]

| Name                                               | Type   | Description                                                                                                                                                                               |
| -------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| q <span style="{color: &#x22;red&#x22;}">\*</span> | string | Search phrase that you want to search                                                                                                                                                     |
| lang                                               | string | You can set language for e.g. `en` for english `fr` for french.<br />Get the list of available languages by making a separate request to the [Languages List](/extra-apis/languages-list) |
| loc                                                | string | Location for localized suggestions<br />You can receive the list of available locations by making a separate request to the [Locations List](/extra-apis/locations-list)                  |
| client                                             | string | `chrome` (default), `chrome-omni`, `home_page`, `safari`, `firefox`, `youtube`                                                                                                            |

## Example Request [#example-request]

<ApiExample endpoint="https://api.serphouse.com/google-autocomplete-api" query="coffee" lang="en" params="{&#x22;loc&#x22;: &#x22;Abernathy,Texas,United States&#x22;, &#x22;client&#x22;: &#x22;chrome&#x22;}" />

## Example Response [#example-response]

<ApiExample mode="response">
  <ApiTab label="JSON" response="googleAutocompleteJsonResponse" />
</ApiExample>

## Related Links [#related-links]

<Cards>
  <Card title="Google Search API" href="/google-apis/google-search-api" />

  <Card title="Google Forums API" href="/google-apis/google-forums-api" />
</Cards>


# Google Forums API (/docs/google-apis/google-forums-api)





Access real-time forum discussions from Google Search with the Google Forums API. Fetch conversations from platforms like Reddit, Stack Exchange, and other communities.

<Callout type="warn">
  Requires authentication → provide your API key as a Bearer token in the
  Authorization header.
</Callout>

`POST` `https://api.serphouse.com/google-forums-api`

<Callout type="info" title="Response types">
  These are the response types we support. Append a suffix to the endpoint to
  choose the response format.
</Callout>

| Format         | Endpoint                                           |
| -------------- | -------------------------------------------------- |
| JSON (default) | `https://api.serphouse.com/google-forums-api`      |
| Markdown       | `https://api.serphouse.com/google-forums-api/md`   |
| HTML           | `https://api.serphouse.com/google-forums-api/html` |

## Headers [#headers]

| Name                                                           | Type   | Description             |
| -------------------------------------------------------------- | ------ | ----------------------- |
| Authorization <span style="{color: &#x22;red&#x22;}">\*</span> | String | Bearer `<YOUR_API_KEY>` |
| Content-Type <span style="{color: &#x22;red&#x22;}">\*</span>  | String | application/json        |

## Request Body [#request-body]

| Name                                                     | Type    | Description                                                                                                                                                                                                                                                                                                                |
| -------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| q <span style="{color: &#x22;red&#x22;}">\*</span>       | string  | Search phrase that you want to search                                                                                                                                                                                                                                                                                      |
| domain <span style="{color: &#x22;red&#x22;}">\*</span>  | string  | Choose google domain.<br /><br />You can retrieve the list of supported Google domains by making a separate request to the [Domains List](/extra-apis/domains-list)                                                                                                                                                        |
| device <span style="{color: &#x22;red&#x22;}">\*</span>  | string  | `desktop` To extract desktop result `mobile` To extract mobile result                                                                                                                                                                                                                                                      |
| lang <span style="{color: &#x22;red&#x22;}">\*</span>    | string  | You can set language for e.g. `en` for english `fr` for french.<br />Get the list of available languages by making a separate request to the [Languages List](/extra-apis/languages-list)                                                                                                                                  |
| loc <span style="{color: &#x22;red&#x22;}">\*</span>     | string  | Optional field if you specify `loc_id`<br />&#x2A;*You must choose one of the fields: `loc_id` or `loc`**<br />You can receive the list of available locations of search engines with their loc\_id by making a separate request to the [Locations List](/extra-apis/locations-list)                                       |
| loc\_id <span style="{color: &#x22;red&#x22;}">\*</span> | integer | Optional field if you specify `loc`<br />&#x2A;*You must choose one of the fields: `loc_id` or `loc`**<br />You can receive the list of available locations of search engines with their loc\_id by making a separate request to the [Locations List](/extra-apis/locations-list)                                          |
| date\_range                                              | String  | Sometimes you may want to only find information published during a specific time frame. To limit Google results by date<br /><br />Parameter values can be comma separated date range `YYYY-MM-DD,YYYY-MM-DD` OR<br /><br />`h` Past hour<br />`d` Past 24 hours<br />`w` Past week<br />`m` Past month<br />`y` Past year |
| page                                                     | integer | Give specific page to get the result of that page number. By default it will get you first page.                                                                                                                                                                                                                           |
| verbatim                                                 | integer | Set Google Verbatim search, Parameter value can be `0` or `1`                                                                                                                                                                                                                                                              |

<VisualRef title="Google Forums API" src="/images/google/google-forums-api.png" alt="Google forums discussion results" />

## Example Request [#example-request]

<ApiExample endpoint="https://api.serphouse.com/google-forums-api" query="how to make the best tea" domain="google.com" lang="en" params="{&#x22;device&#x22;: &#x22;desktop&#x22;, &#x22;loc&#x22;: &#x22;India&#x22;}" />

## Example Response [#example-response]

<ApiExample mode="response">
  <ApiTab label="JSON" response="googleForumsJsonResponse" />

  <ApiTab label="Markdown" response="googleForumsMarkdownResponse" lang="markdown" />
</ApiExample>

## Related Links [#related-links]

<Cards>
  <Card title="Google Search API" href="/google-apis/google-search-api" />

  <Card title="Google Autocomplete API" href="/google-apis/google-autocomplete-api" />

  <Card title="Google Local API" href="/google-apis/google-local-api" />
</Cards>


# Google Image API (/docs/google-apis/google-image-api)





Retrieve real-time Google Image search results quickly and reliably using the Google Image API endpoint.

<Callout type="warn">
  Requires authentication → provide your API key as a Bearer token in the
  Authorization header.
</Callout>

`POST` `https://api.serphouse.com/google-image`

<Callout type="info" title="Response types">
  These are the response types we support. Append a suffix to the endpoint to
  choose the response format.
</Callout>

| Format         | Endpoint                                      |
| -------------- | --------------------------------------------- |
| JSON (default) | `https://api.serphouse.com/google-image`      |
| Markdown       | `https://api.serphouse.com/google-image/md`   |
| HTML           | `https://api.serphouse.com/google-image/html` |

## Headers [#headers]

| Name                                                           | Type   | Description             |
| -------------------------------------------------------------- | ------ | ----------------------- |
| Authorization <span style="{color: &#x22;red&#x22;}">\*</span> | String | Bearer `<YOUR_API_KEY>` |
| Content-Type <span style="{color: &#x22;red&#x22;}">\*</span>  | String | application/json        |

## Request Body [#request-body]

| Name                                                     | Type              | Description                                                                                                                                                                                                                                                                                                                |
| -------------------------------------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| q <span style="{color: &#x22;red&#x22;}">\*</span>       | string            | Search phrase that you want to search                                                                                                                                                                                                                                                                                      |
| domain <span style="{color: &#x22;red&#x22;}">\*</span>  | string            | Choose google domain.<br /><br />You can retrieve the list of supported Google domains by making a separate request to the [Domains List](/extra-apis/domains-list)                                                                                                                                                        |
| lang <span style="{color: &#x22;red&#x22;}">\*</span>    | string            | You can set language for e.g. `en` for english `fr` for french.<br />Get the list of available languages by making a separate request to the [Languages List](/extra-apis/languages-list)                                                                                                                                  |
| loc <span style="{color: &#x22;red&#x22;}">\*</span>     | string            | Optional field if you specify `loc_id`<br />&#x2A;*You must choose one of the fields: `loc_id` or `loc`**<br />You can receive the list of available locations of search engines with their loc\_id by making a separate request to the [Locations List](/extra-apis/locations-list)                                       |
| loc\_id <span style="{color: &#x22;red&#x22;}">\*</span> | integer           | Optional field if you specify `loc`<br />&#x2A;*You must choose one of the fields: `loc_id` or `loc`**<br />You can receive the list of available locations of search engines with their loc\_id by making a separate request to the [Locations List](/extra-apis/locations-list)                                          |
| page                                                     | integer           | Give specific page to get the result of that page number. By default it will get you first page.                                                                                                                                                                                                                           |
| date\_range                                              | String            | Sometimes you may want to only find information published during a specific time frame. To limit Google results by date<br /><br />Parameter values can be comma separated date range `YYYY-MM-DD,YYYY-MM-DD` OR<br /><br />`h` Past hour<br />`d` Past 24 hours<br />`w` Past week<br />`m` Past month<br />`y` Past year |
| no\_trace                                                | string \| integer | Enterprise only. Enables NoTrace mode. Accepted values: `0`, `1`, `true`, and `false`. When enabled (`1` or `true`), search parameters, files, and metadata are not stored on our servers.                                                                                                                                 |

<VisualRef title="Google Image API" src="/images/google/google-image-api.png" alt="Google image search results" />

## Example Request [#example-request]

<ApiExample endpoint="https://api.serphouse.com/google-image" query="baby icons" domain="google.com" lang="en" params="{&#x22;loc&#x22;: &#x22;United States&#x22;}" />

## Example Response [#example-response]

<ApiExample mode="response">
  <ApiTab label="JSON" response="googleImageJsonResponse" />

  <ApiTab label="Markdown" response="googleImageMarkdownResponse" lang="markdown" />
</ApiExample>

## Related Links [#related-links]

<Cards>
  <Card title="Google Search API" href="/google-apis/google-search-api" />

  <Card title="Google News API" href="/google-apis/google-news-api" />
</Cards>


# Google Jobs API (/docs/google-apis/google-jobs-api)





Performing a real-time Google Jobs search using HTTP POST is very simple with the Google Jobs API endpoint.

<Callout type="warn">
  Requires authentication → provide your API key as a Bearer token in the
  Authorization header.
</Callout>

`POST` `https://api.serphouse.com/google-jobs-api`

<Callout type="info" title="Response types">
  These are the response types we support. Append a suffix to the endpoint to
  choose the response format.
</Callout>

| Format         | Endpoint                                         |
| -------------- | ------------------------------------------------ |
| JSON (default) | `https://api.serphouse.com/google-jobs-api`      |
| Markdown       | `https://api.serphouse.com/google-jobs-api/md`   |
| HTML           | `https://api.serphouse.com/google-jobs-api/html` |

## Headers [#headers]

| Name                                                           | Type   | Description             |
| -------------------------------------------------------------- | ------ | ----------------------- |
| Authorization <span style="{color: &#x22;red&#x22;}">\*</span> | String | Bearer `<YOUR_API_KEY>` |
| Content-Type <span style="{color: &#x22;red&#x22;}">\*</span>  | String | application/json        |

## Request Body [#request-body]

| Name                                                     | Type    | Description                                                                                                                                                                                                                                                                                                                |
| -------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| q <span style="{color: &#x22;red&#x22;}">\*</span>       | string  | Search phrase that you want to search                                                                                                                                                                                                                                                                                      |
| domain <span style="{color: &#x22;red&#x22;}">\*</span>  | string  | Choose google domain.<br /><br />You can retrieve the list of supported Google domains by making a separate request to the [Domains List](/extra-apis/domains-list)                                                                                                                                                        |
| lang <span style="{color: &#x22;red&#x22;}">\*</span>    | string  | You can set language for e.g. `en` for english `fr` for french.<br />Get the list of available languages by making a separate request to the [Languages List](/extra-apis/languages-list)                                                                                                                                  |
| loc <span style="{color: &#x22;red&#x22;}">\*</span>     | string  | Optional field if you specify `loc_id`<br />&#x2A;*You must choose one of the fields: `loc_id` or `loc`**<br />You can receive the list of available locations of search engines with their loc\_id by making a separate request to the [Locations List](/extra-apis/locations-list)                                       |
| loc\_id <span style="{color: &#x22;red&#x22;}">\*</span> | integer | Optional field if you specify `loc`<br />&#x2A;*You must choose one of the fields: `loc_id` or `loc`**<br />You can receive the list of available locations of search engines with their loc\_id by making a separate request to the [Locations List](/extra-apis/locations-list)                                          |
| date\_range                                              | String  | Sometimes you may want to only find information published during a specific time frame. To limit Google results by date<br /><br />Parameter values can be comma separated date range `YYYY-MM-DD,YYYY-MM-DD` OR<br /><br />`h` Past hour<br />`d` Past 24 hours<br />`w` Past week<br />`m` Past month<br />`y` Past year |

## Response [#response]

<Callout type="info">
  On success, the API returns structured job listings including position,
  company name, location, description, and apply options.
</Callout>

<VisualRef title="Google Jobs API" src="/images/google/google-jobs-api.png" alt="Google jobs search results" />

## Example Request [#example-request]

<ApiExample endpoint="https://api.serphouse.com/google-jobs-api" query="Software engineer jobs" domain="google.com" lang="de" params="{&#x22;loc&#x22;: &#x22;Germany&#x22;}" />

## Example Response [#example-response]

<ApiExample mode="response">
  <ApiTab label="JSON" response="googleJobsJsonResponse" />

  <ApiTab label="Markdown" response="googleJobsMarkdownResponse" lang="markdown" />
</ApiExample>

## Related Links [#related-links]

<Cards>
  <Card title="Google Search API" href="/google-apis/google-search-api" />

  <Card title="Google News API" href="/google-apis/google-news-api" />
</Cards>


# Google Lite Web Search (/docs/google-apis/google-lite-web-search-api)





Retrieve real-time Google Web Search results with a fast, lightweight response, including organic listings, website titles, links, and snippets.

<Callout type="warn">
  Requires authentication → provide your API key as a Bearer token in the
  Authorization header.
</Callout>

`POST` `https://api.serphouse.com/web-search-lite`

## Headers [#headers]

| Name                                                           | Type   | Description             |
| -------------------------------------------------------------- | ------ | ----------------------- |
| Authorization <span style="{color: &#x22;red&#x22;}">\*</span> | String | Bearer `<YOUR_API_KEY>` |
| Content-Type <span style="{color: &#x22;red&#x22;}">\*</span>  | String | application/json        |

## Request Body [#request-body]

| Name                                                    | Type              | Description                                                                                                                                                                                                                                                                                                                |
| ------------------------------------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| q <span style="{color: &#x22;red&#x22;}">\*</span>      | string            | Search phrase that you want to search                                                                                                                                                                                                                                                                                      |
| domain <span style="{color: &#x22;red&#x22;}">\*</span> | string            | Choose google domain.<br /><br />You can retrieve the list of supported Google domains by making a separate request to the [Domains List](/extra-apis/domains-list)                                                                                                                                                        |
| lang <span style="{color: &#x22;red&#x22;}">\*</span>   | string            | You can set language for e.g. `en` for english `fr` for french.<br />Get the list of available languages by making a separate request to the [Languages List](/extra-apis/languages-list)                                                                                                                                  |
| gl <span style="{color: &#x22;red&#x22;}">\*</span>     | string            | Optional field if you specify `loc`<br />&#x2A;*The request must include either `loc` or `gl`**<br />The `gl` parameter accepts only two-letter ISO country codes (e.g. `IN`, `US`, `GB`). You can retrieve the list of supported country codes from the [Locations List](/extra-apis/locations-list)                      |
| loc <span style="{color: &#x22;red&#x22;}">\*</span>    | string            | Optional field if you specify `gl`<br />&#x2A;*The request must include either `loc` or `gl`**<br />You can receive the list of available locations of search engines with their loc\_id by making a separate request to the [Locations List](/extra-apis/locations-list)                                                  |
| page                                                    | integer           | Give specific page to get the result of that page number. By default it will get you first page.                                                                                                                                                                                                                           |
| date\_range                                             | String            | Sometimes you may want to only find information published during a specific time frame. To limit Google results by date<br /><br />Parameter values can be comma separated date range `YYYY-MM-DD,YYYY-MM-DD` OR<br /><br />`h` Past hour<br />`d` Past 24 hours<br />`w` Past week<br />`m` Past month<br />`y` Past year |
| verbatim                                                | integer           | Set Google Verbatim search, Parameter value can be `0` or `1`                                                                                                                                                                                                                                                              |
| no\_trace                                               | string \| integer | Enterprise only. Enables NoTrace mode. Accepted values: `0`, `1`, `true`, and `false`. When enabled (`1` or `true`), search parameters, files, and metadata are not stored on our servers.                                                                                                                                 |

## Response [#response]

<Callout type="info">
  Returns lightweight JSON with organic search results including title, site
  title, link, and snippet.
</Callout>

## Example Request [#example-request]

<ApiExample endpoint="https://api.serphouse.com/web-search-lite" query="Best ai tools" domain="google.com" lang="en" params="{&#x22;gl&#x22;: &#x22;us&#x22;, &#x22;page&#x22;: 1}" />

## Example Response [#example-response]

<ApiExample mode="response">
  <ApiTab label="JSON" response="googleLiteWebSearchJsonResponse" />
</ApiExample>

## Related Links [#related-links]

<Cards>
  <Card title="Google Search API" href="/google-apis/google-search-api" />

  <Card title="Google News API" href="/google-apis/google-news-api" />
</Cards>


# Google Local (/docs/google-apis/google-local-api)





Google Local API provides structured local business results from Google Search, including position, business name, rating, reviews count, address, GPS coordinates, service options, and direct map navigation links.

<Callout type="warn">
  Requires authentication → provide your API key as a Bearer token in the
  Authorization header.
</Callout>

`POST` `https://api.serphouse.com/google-local-api`

<Callout type="info" title="Response types">
  These are the response types we support. Append a suffix to the endpoint to
  choose the response format.
</Callout>

| Format         | Endpoint                                          |
| -------------- | ------------------------------------------------- |
| JSON (default) | `https://api.serphouse.com/google-local-api`      |
| Markdown       | `https://api.serphouse.com/google-local-api/md`   |
| HTML           | `https://api.serphouse.com/google-local-api/html` |

## Headers [#headers]

| Name                                                           | Type   | Description             |
| -------------------------------------------------------------- | ------ | ----------------------- |
| Authorization <span style="{color: &#x22;red&#x22;}">\*</span> | String | Bearer `<YOUR_API_KEY>` |
| Content-Type <span style="{color: &#x22;red&#x22;}">\*</span>  | String | application/json        |

## Request Body [#request-body]

| Name                                                     | Type    | Description                                                                                                                                                                                                                                                                          |
| -------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| q <span style="{color: &#x22;red&#x22;}">\*</span>       | string  | Search phrase that you want to search                                                                                                                                                                                                                                                |
| domain <span style="{color: &#x22;red&#x22;}">\*</span>  | string  | Choose google domain.<br /><br />You can retrieve the list of supported Google domains by making a separate request to the [Domains List](/extra-apis/domains-list)                                                                                                                  |
| lang <span style="{color: &#x22;red&#x22;}">\*</span>    | string  | You can set language for e.g. `en` for english `fr` for french.<br />Get the list of available languages by making a separate request to the [Languages List](/extra-apis/languages-list)                                                                                            |
| loc <span style="{color: &#x22;red&#x22;}">\*</span>     | string  | Optional field if you specify `loc_id`<br />&#x2A;*You must choose one of the fields: `loc_id` or `loc`**<br />You can receive the list of available locations of search engines with their loc\_id by making a separate request to the [Locations List](/extra-apis/locations-list) |
| loc\_id <span style="{color: &#x22;red&#x22;}">\*</span> | integer | Optional field if you specify `loc`<br />&#x2A;*You must choose one of the fields: `loc_id` or `loc`**<br />You can receive the list of available locations of search engines with their loc\_id by making a separate request to the [Locations List](/extra-apis/locations-list)    |
| page                                                     | integer | Give specific page to get the result of that page number. By default it will get you first page. (up to 20 local results per page)                                                                                                                                                   |

<VisualRef title="Google Local API" src="/images/google/google-local-api.png" alt="Google local business results" />

## Example Request [#example-request]

<ApiExample endpoint="https://api.serphouse.com/google-local-api" query="Restaurants" domain="google.com" lang="en" params="{&#x22;loc&#x22;: &#x22;Mumbai,Maharashtra,India&#x22;}" />

## Example Response [#example-response]

<ApiExample mode="response">
  <ApiTab label="JSON" response="googleLocalJsonResponse" />

  <ApiTab label="Markdown" response="googleLocalMarkdownResponse" lang="markdown" />
</ApiExample>

## Related Links [#related-links]

<Cards>
  <Card title="Google Search API" href="/google-apis/google-search-api" />

  <Card title="Google Forums API" href="/google-apis/google-forums-api" />
</Cards>


# Google News (/docs/google-apis/google-news-api)





The Google News API endpoint provides fast and reliable access to real-time Google News search results.

<Callout type="warn">
  Requires authentication → provide your API key as a Bearer token in the
  Authorization header.
</Callout>

`POST` `https://api.serphouse.com/google-news`

<Callout type="info" title="Response types">
  These are the response types we support. Append a suffix to the endpoint to
  choose the response format.
</Callout>

| Format         | Endpoint                                     |
| -------------- | -------------------------------------------- |
| JSON (default) | `https://api.serphouse.com/google-news`      |
| Markdown       | `https://api.serphouse.com/google-news/md`   |
| HTML           | `https://api.serphouse.com/google-news/html` |

## Headers [#headers]

| Name                                                           | Type   | Description             |
| -------------------------------------------------------------- | ------ | ----------------------- |
| Authorization <span style="{color: &#x22;red&#x22;}">\*</span> | String | Bearer `<YOUR_API_KEY>` |
| Content-Type <span style="{color: &#x22;red&#x22;}">\*</span>  | String | application/json        |

## Request Body [#request-body]

| Name                                                     | Type              | Description                                                                                                                                                                                                                                                                                                                |
| -------------------------------------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| q <span style="{color: &#x22;red&#x22;}">\*</span>       | string            | Search phrase that you want to search                                                                                                                                                                                                                                                                                      |
| domain <span style="{color: &#x22;red&#x22;}">\*</span>  | string            | Choose google domain.<br /><br />You can retrieve the list of supported Google domains by making a separate request to the [Domains List](/extra-apis/domains-list)                                                                                                                                                        |
| device <span style="{color: &#x22;red&#x22;}">\*</span>  | string            | `desktop` To extract desktop result `mobile` To extract mobile result                                                                                                                                                                                                                                                      |
| lang <span style="{color: &#x22;red&#x22;}">\*</span>    | string            | You can set language for e.g. `en` for english `fr` for french.<br />Get the list of available languages by making a separate request to the [Languages List](/extra-apis/languages-list)                                                                                                                                  |
| loc <span style="{color: &#x22;red&#x22;}">\*</span>     | string            | Optional field if you specify `loc_id`<br />&#x2A;*You must choose one of the fields: `loc_id` or `loc`**<br />You can receive the list of available locations of search engines with their loc\_id by making a separate request to the [Locations List](/extra-apis/locations-list)                                       |
| loc\_id <span style="{color: &#x22;red&#x22;}">\*</span> | integer           | Optional field if you specify `loc`<br />&#x2A;*You must choose one of the fields: `loc_id` or `loc`**<br />You can receive the list of available locations of search engines with their loc\_id by making a separate request to the [Locations List](/extra-apis/locations-list)                                          |
| page                                                     | integer           | Give specific page to get the result of that page number. By default it will get you first page.                                                                                                                                                                                                                           |
| date\_range                                              | String            | Sometimes you may want to only find information published during a specific time frame. To limit Google results by date<br /><br />Parameter values can be comma separated date range `YYYY-MM-DD,YYYY-MM-DD` OR<br /><br />`h` Past hour<br />`d` Past 24 hours<br />`w` Past week<br />`m` Past month<br />`y` Past year |
| no\_trace                                                | string \| integer | Enterprise only. Enables NoTrace mode. Accepted values: `0`, `1`, `true`, and `false`. When enabled (`1` or `true`), search parameters, files, and metadata are not stored on our servers.                                                                                                                                 |

<VisualRef title="Google News API" src="/images/google/google-news-api.png" alt="Google news search results" />

## Example Request [#example-request]

<ApiExample endpoint="https://api.serphouse.com/google-news" query="top headlines" domain="google.com" lang="en" params="{&#x22;device&#x22;: &#x22;desktop&#x22;, &#x22;loc&#x22;: &#x22;United Kingdom&#x22;}" />

## Example Response [#example-response]

<ApiExample mode="response">
  <ApiTab label="JSON" response="googleNewsJsonResponse" />

  <ApiTab label="Markdown" response="googleNewsMarkdownResponse" lang="markdown" />
</ApiExample>

## Related Links [#related-links]

<Cards>
  <Card title="Google Search API" href="/google-apis/google-search-api" />

  <Card title="Google Image API" href="/google-apis/google-image-api" />
</Cards>


# Google Batch SERP (Top 100 Results) (/docs/google-apis/google-schedule-serp-top-100-results)





<Callout type="warn">
  Requires authentication → provide your API key as a Bearer token in the
  Authorization header.
</Callout>

`POST` `https://api.serphouse.com/serp/google_advanced_scheduled`

## Headers [#headers]

| Name                                                           | Type   | Description             |
| -------------------------------------------------------------- | ------ | ----------------------- |
| Authorization <span style="{color: &#x22;red&#x22;}">\*</span> | String | Bearer `<YOUR_API_KEY>` |
| Content-Type <span style="{color: &#x22;red&#x22;}">\*</span>  | String | application/json        |

## Request Body [#request-body]

| Name                                                     | Type    | Description                                                                                                                                                                                                                                                                                                                |
| -------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| q <span style="{color: &#x22;red&#x22;}">\*</span>       | string  | Search phrase that you want to search                                                                                                                                                                                                                                                                                      |
| domain <span style="{color: &#x22;red&#x22;}">\*</span>  | string  | Choose google domain.<br /><br />You can retrieve the list of supported Google domains by making a separate request to the [Domains List](/extra-apis/domains-list)                                                                                                                                                        |
| lang <span style="{color: &#x22;red&#x22;}">\*</span>    | string  | You can set language for e.g. `en` for english `fr` for french.<br />Get the list of available languages by making a separate request to the [Languages List](/extra-apis/languages-list)                                                                                                                                  |
| device <span style="{color: &#x22;red&#x22;}">\*</span>  | string  | `desktop` To extract desktop result `mobile` To extract mobile result                                                                                                                                                                                                                                                      |
| loc <span style="{color: &#x22;red&#x22;}">\*</span>     | string  | Optional field if you specify `loc_id`<br />&#x2A;*You must choose one of the fields: `loc_id` or `loc`**<br />You can receive the list of available locations of search engines with their loc\_id by making a separate request to the [Locations List](/extra-apis/locations-list)                                       |
| loc\_id <span style="{color: &#x22;red&#x22;}">\*</span> | integer | Optional field if you specify `loc`<br />&#x2A;*You must choose one of the fields: `loc_id` or `loc`**<br />You can receive the list of available locations of search engines with their loc\_id by making a separate request to the [Locations List](/extra-apis/locations-list)                                          |
| verbatim                                                 | integer | Google Verbatim (`0` or `1`)                                                                                                                                                                                                                                                                                               |
| gfilter                                                  | integer | Filter on/off (`1` or `0`)                                                                                                                                                                                                                                                                                                 |
| postback\_url                                            | url     | POST results to this URL when complete                                                                                                                                                                                                                                                                                     |
| pingback\_url                                            | url     | GET notification URL when complete                                                                                                                                                                                                                                                                                         |
| max\_pages                                               | integer | Pages to return (1–10, default 10)                                                                                                                                                                                                                                                                                         |
| date\_range                                              | String  | Sometimes you may want to only find information published during a specific time frame. To limit Google results by date<br /><br />Parameter values can be comma separated date range `YYYY-MM-DD,YYYY-MM-DD` OR<br /><br />`h` Past hour<br />`d` Past 24 hours<br />`w` Past week<br />`m` Past month<br />`y` Past year |

## Example Request [#example-request]

<ApiExample
  endpoint="https://api.serphouse.com/serp/google_advanced_scheduled"
  items="[
{
&#x22;q&#x22;: &#x22;donlad trump&#x22;,
&#x22;domain&#x22;: &#x22;google.com&#x22;,
&#x22;lang&#x22;: &#x22;en&#x22;,
&#x22;device&#x22;: &#x22;desktop&#x22;,
&#x22;loc&#x22;: &#x22;London,England,United Kingdom&#x22;,
&#x22;max_pages&#x22;: 10
},
{
&#x22;q&#x22;: &#x22;Tesla&#x22;,
&#x22;domain&#x22;: &#x22;google.com&#x22;,
&#x22;lang&#x22;: &#x22;ru&#x22;,
&#x22;device&#x22;: &#x22;mobile&#x22;,
&#x22;loc&#x22;: &#x22;Russia&#x22;,
&#x22;max_pages&#x22;: 4
},
{
&#x22;q&#x22;: &#x22;Artificial Intelligence&#x22;,
&#x22;domain&#x22;: &#x22;google.com&#x22;,
&#x22;lang&#x22;: &#x22;en&#x22;,
&#x22;device&#x22;: &#x22;desktop&#x22;,
&#x22;loc&#x22;: &#x22;Alba,Texas,United States&#x22;,
&#x22;max_pages&#x22;: 7
}
]"
/>

## Example Response [#example-response]

<ApiExample mode="response">
  <ApiTab label="JSON" response="googleScheduleSerpTop100JsonResponse" />
</ApiExample>

## Related Links [#related-links]

<Cards>
  <Card title="Google SERP (Top 100)" href="/google-apis/google-serp-top-100-results" />

  <Card title="Batch SERP" href="/extra-apis/batch-serp" />
</Cards>


# Google SERP (Top 100 Results) (/docs/google-apis/google-serp-top-100-results)





<Callout type="warn">
  Requires authentication → provide your API key as a Bearer token in the
  Authorization header.
</Callout>

`POST` `https://api.serphouse.com/serp/google_advanced`

<Callout type="info" title="Response types">
  These are the response types we support. Append a suffix to the endpoint to
  choose the response format.
</Callout>

| Format         | Endpoint                                              |
| -------------- | ----------------------------------------------------- |
| JSON (default) | `https://api.serphouse.com/serp/google_advanced`      |
| Markdown       | `https://api.serphouse.com/serp/google_advanced/md`   |
| HTML           | `https://api.serphouse.com/serp/google_advanced/html` |

## Headers [#headers]

| Name                                                           | Type   | Description             |
| -------------------------------------------------------------- | ------ | ----------------------- |
| Authorization <span style="{color: &#x22;red&#x22;}">\*</span> | String | Bearer `<YOUR_API_KEY>` |
| Content-Type <span style="{color: &#x22;red&#x22;}">\*</span>  | String | application/json        |

## Request Body [#request-body]

| Name                                                     | Type    | Description                                                                                                                                                                                                                                                                                                                |
| -------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| q <span style="{color: &#x22;red&#x22;}">\*</span>       | string  | Search phrase that you want to search                                                                                                                                                                                                                                                                                      |
| domain <span style="{color: &#x22;red&#x22;}">\*</span>  | string  | Choose google domain.<br /><br />You can retrieve the list of supported Google domains by making a separate request to the [Domains List](/extra-apis/domains-list)                                                                                                                                                        |
| lang <span style="{color: &#x22;red&#x22;}">\*</span>    | string  | You can set language for e.g. `en` for english `fr` for french.<br />Get the list of available languages by making a separate request to the [Languages List](/extra-apis/languages-list)                                                                                                                                  |
| device <span style="{color: &#x22;red&#x22;}">\*</span>  | string  | `desktop` To extract desktop result `mobile` To extract mobile result                                                                                                                                                                                                                                                      |
| loc <span style="{color: &#x22;red&#x22;}">\*</span>     | string  | Optional field if you specify `loc_id`<br />&#x2A;*You must choose one of the fields: `loc_id` or `loc`**<br />You can receive the list of available locations of search engines with their loc\_id by making a separate request to the [Locations List](/extra-apis/locations-list)                                       |
| loc\_id <span style="{color: &#x22;red&#x22;}">\*</span> | integer | Optional field if you specify `loc`<br />&#x2A;*You must choose one of the fields: `loc_id` or `loc`**<br />You can receive the list of available locations of search engines with their loc\_id by making a separate request to the [Locations List](/extra-apis/locations-list)                                          |
| verbatim                                                 | integer | Google Verbatim (`0` or `1`)                                                                                                                                                                                                                                                                                               |
| gfilter                                                  | integer | Filter on/off (`1` or `0`)                                                                                                                                                                                                                                                                                                 |
| max\_pages                                               | integer | Pages to return (1–10, default 10)                                                                                                                                                                                                                                                                                         |
| date\_range                                              | String  | Sometimes you may want to only find information published during a specific time frame. To limit Google results by date<br /><br />Parameter values can be comma separated date range `YYYY-MM-DD,YYYY-MM-DD` OR<br /><br />`h` Past hour<br />`d` Past 24 hours<br />`w` Past week<br />`m` Past month<br />`y` Past year |

## Why this endpoint? [#why-this-endpoint]

<Callout type="idea" title="Why this endpoint?">
  Google recently restricted the `num` parameter to a maximum of 10 results per
  request. To overcome this limitation, we introduced a new endpoint that can
  fetch results from multiple pages.
</Callout>

## How It Works [#how-it-works]

* **`max_pages`** defines how many result pages you want scraped.
* Each page contains up to 10 results.
* `max_pages=5` → up to 50 results (5 pages × 10 results per page)
* `max_pages=10` → up to 100 results (10 pages × 10 results per page)

## Pricing [#pricing]

<Callout type="success">
  The cost is based on the number of pages scraped. **1 page = 10 credits**.
</Callout>

* `max_pages=7` → 7 pages scraped → costs 70 credits
* If `max_pages` is set to 7 but only 2 pages are available, 20 credits are charged.

<VisualRef title="Google SERP (Top 100 Results)" src="/images/google/google-top-100-api.png" alt="Google top 100 SERP results" />

## Example Request [#example-request]

<ApiExample endpoint="https://api.serphouse.com/serp/google_advanced" query="best place in texas to visit" domain="google.com" lang="en" params="{&#x22;device&#x22;: &#x22;desktop&#x22;, &#x22;loc&#x22;: &#x22;Texas,United States&#x22;, &#x22;max_pages&#x22;: 4}" />

## Example Response [#example-response]

<ApiExample mode="response">
  <ApiTab label="JSON" response="googleSerpTop100JsonResponse" />

  <ApiTab label="Markdown" response="googleSerpTop100MarkdownResponse" lang="markdown" />
</ApiExample>

## Related Links [#related-links]

<Cards>
  <Card title="Google Batch SERP (Top 100)" href="/google-apis/google-schedule-serp-top-100-results" />

  <Card title="Google Search API" href="/google-apis/google-search-api" />
</Cards>


# Google Shopping (/docs/google-apis/google-shopping-api)





Get up-to-date Google Shopping results, including product details and pricing information, with the Google Shopping API endpoint.

<Callout type="warn">
  Requires authentication → provide your API key as a Bearer token in the
  Authorization header.
</Callout>

`POST` `https://api.serphouse.com/google-shop`

<Callout type="info" title="Response types">
  These are the response types we support. Append a suffix to the endpoint to
  choose the response format.
</Callout>

| Format         | Endpoint                                     |
| -------------- | -------------------------------------------- |
| JSON (default) | `https://api.serphouse.com/google-shop`      |
| Markdown       | `https://api.serphouse.com/google-shop/md`   |
| HTML           | `https://api.serphouse.com/google-shop/html` |

## Headers [#headers]

| Name                                                           | Type   | Description             |
| -------------------------------------------------------------- | ------ | ----------------------- |
| Authorization <span style="{color: &#x22;red&#x22;}">\*</span> | String | Bearer `<YOUR_API_KEY>` |
| Content-Type <span style="{color: &#x22;red&#x22;}">\*</span>  | String | application/json        |

## Request Body [#request-body]

| Name                                                     | Type              | Description                                                                                                                                                                                                                                                                          |
| -------------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| q <span style="{color: &#x22;red&#x22;}">\*</span>       | string            | Search phrase that you want to search                                                                                                                                                                                                                                                |
| domain <span style="{color: &#x22;red&#x22;}">\*</span>  | string            | Choose google domain.<br /><br />You can retrieve the list of supported Google domains by making a separate request to the [Domains List](/extra-apis/domains-list)                                                                                                                  |
| lang <span style="{color: &#x22;red&#x22;}">\*</span>    | string            | You can set language for e.g. `en` for english `fr` for french.<br />Get the list of available languages by making a separate request to the [Languages List](/extra-apis/languages-list)                                                                                            |
| loc <span style="{color: &#x22;red&#x22;}">\*</span>     | string            | Optional field if you specify `loc_id`<br />&#x2A;*You must choose one of the fields: `loc_id` or `loc`**<br />You can receive the list of available locations of search engines with their loc\_id by making a separate request to the [Locations List](/extra-apis/locations-list) |
| loc\_id <span style="{color: &#x22;red&#x22;}">\*</span> | integer           | Optional field if you specify `loc`<br />&#x2A;*You must choose one of the fields: `loc_id` or `loc`**<br />You can receive the list of available locations of search engines with their loc\_id by making a separate request to the [Locations List](/extra-apis/locations-list)    |
| page                                                     | integer           | Give specific page to get the result of that page number. By default it will get you first page.                                                                                                                                                                                     |
| no\_trace                                                | string \| integer | Enterprise only. Enables NoTrace mode. Accepted values: `0`, `1`, `true`, and `false`. When enabled (`1` or `true`), search parameters, files, and metadata are not stored on our servers.                                                                                           |

<VisualRef title="Google Shopping API" src="/images/google/google-shopping-api.png" alt="Google shopping results" />

## Example Request [#example-request]

<ApiExample endpoint="https://api.serphouse.com/google-shop" query="macbook" domain="google.com" lang="en" params="{&#x22;loc&#x22;: &#x22;South Africa&#x22;}" />

## Example Response [#example-response]

<ApiExample mode="response">
  <ApiTab label="JSON" response="googleShoppingJsonResponse" />

  <ApiTab label="Markdown" response="googleShoppingMarkdownResponse" lang="markdown" />
</ApiExample>

## Related Links [#related-links]

<Cards>
  <Card title="Google Search API" href="/google-apis/google-search-api" />

  <Card title="Google News API" href="/google-apis/google-news-api" />
</Cards>


# Google Short Videos (/docs/google-apis/google-short-videos-api)





The Google Short Videos API enables you to retrieve real-time short video results from Google Search, delivering structured data in a simple HTTP request. It is designed for fast, scalable, and reliable access to short-form video SERP data.

<Callout type="warn">
  Requires authentication → provide your API key as a Bearer token in the
  Authorization header.
</Callout>

`POST` `https://api.serphouse.com/google-short-videos-api`

<Callout type="info" title="Response types">
  These are the response types we support. Append a suffix to the endpoint to
  choose the response format.
</Callout>

| Format         | Endpoint                                                 |
| -------------- | -------------------------------------------------------- |
| JSON (default) | `https://api.serphouse.com/google-short-videos-api`      |
| Markdown       | `https://api.serphouse.com/google-short-videos-api/md`   |
| HTML           | `https://api.serphouse.com/google-short-videos-api/html` |

## Headers [#headers]

| Name                                                           | Type   | Description             |
| -------------------------------------------------------------- | ------ | ----------------------- |
| Authorization <span style="{color: &#x22;red&#x22;}">\*</span> | String | Bearer `<YOUR_API_KEY>` |
| Content-Type <span style="{color: &#x22;red&#x22;}">\*</span>  | String | application/json        |

## Request Body [#request-body]

| Name                                                     | Type    | Description                                                                                                                                                                                                                                                                                                                |
| -------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| q <span style="{color: &#x22;red&#x22;}">\*</span>       | string  | Search phrase that you want to search                                                                                                                                                                                                                                                                                      |
| domain <span style="{color: &#x22;red&#x22;}">\*</span>  | string  | Choose google domain.<br /><br />You can retrieve the list of supported Google domains by making a separate request to the [Domains List](/extra-apis/domains-list)                                                                                                                                                        |
| device <span style="{color: &#x22;red&#x22;}">\*</span>  | string  | `desktop` To extract desktop result `mobile` To extract mobile result                                                                                                                                                                                                                                                      |
| lang <span style="{color: &#x22;red&#x22;}">\*</span>    | string  | You can set language for e.g. `en` for english `fr` for french.<br />Get the list of available languages by making a separate request to the [Languages List](/extra-apis/languages-list)                                                                                                                                  |
| loc <span style="{color: &#x22;red&#x22;}">\*</span>     | string  | Optional field if you specify `loc_id`<br />&#x2A;*You must choose one of the fields: `loc_id` or `loc`**<br />You can receive the list of available locations of search engines with their loc\_id by making a separate request to the [Locations List](/extra-apis/locations-list)                                       |
| loc\_id <span style="{color: &#x22;red&#x22;}">\*</span> | integer | Optional field if you specify `loc`<br />&#x2A;*You must choose one of the fields: `loc_id` or `loc`**<br />You can receive the list of available locations of search engines with their loc\_id by making a separate request to the [Locations List](/extra-apis/locations-list)                                          |
| date\_range                                              | String  | Sometimes you may want to only find information published during a specific time frame. To limit Google results by date<br /><br />Parameter values can be comma separated date range `YYYY-MM-DD,YYYY-MM-DD` OR<br /><br />`h` Past hour<br />`d` Past 24 hours<br />`w` Past week<br />`m` Past month<br />`y` Past year |
| page                                                     | integer | Give specific page to get the result of that page number. By default it will get you first page.                                                                                                                                                                                                                           |
| video\_quality                                           | String  | Allows filtering video results by quality level.<br />By default, videos of all qualities are returned. Use this option to request only high-quality videos.<br /><br />Available value:<br />`high` – high-quality videos only                                                                                            |
| video\_captions                                          | String  | Use this parameter to return only videos that include captions.<br />If not provided, both captioned and non-captioned videos are included in the results.<br /><br />To retrieve only videos with closed captions, the `captioned` parameter should be used.                                                              |

<VisualRef title="Google Short Videos API" src="/images/google/google-short-videos-api.png" alt="Google short videos results" />

## Example Request [#example-request]

<ApiExample endpoint="https://api.serphouse.com/google-short-videos-api" query="cooking recipes" domain="google.com" lang="de" params="{&#x22;device&#x22;: &#x22;desktop&#x22;, &#x22;loc&#x22;: &#x22;Germany&#x22;}" />

## Example Response [#example-response]

<ApiExample mode="response">
  <ApiTab label="JSON" response="googleShortVideosJsonResponse" />

  <ApiTab label="Markdown" response="googleShortVideosMarkdownResponse" lang="markdown" />
</ApiExample>

## Related Links [#related-links]

<Cards>
  <Card title="Google Search API" href="/google-apis/google-search-api" />

  <Card title="Google Videos API" href="/google-apis/google-videos-api" />
</Cards>


# Google Videos (/docs/google-apis/google-videos-api)





The Google Video API allows you to fetch real-time video search results directly from Google using a simple HTTP POST request, making large-scale SERP data collection fast and reliable.

<Callout type="warn">
  Requires authentication → provide your API key as a Bearer token in the
  Authorization header.
</Callout>

`POST` `https://api.serphouse.com/google-videos-api`

<Callout type="info" title="Response types">
  These are the response types we support. Append a suffix to the endpoint to
  choose the response format.
</Callout>

| Format         | Endpoint                                           |
| -------------- | -------------------------------------------------- |
| JSON (default) | `https://api.serphouse.com/google-videos-api`      |
| Markdown       | `https://api.serphouse.com/google-videos-api/md`   |
| HTML           | `https://api.serphouse.com/google-videos-api/html` |

## Headers [#headers]

| Name                                                           | Type   | Description             |
| -------------------------------------------------------------- | ------ | ----------------------- |
| Authorization <span style="{color: &#x22;red&#x22;}">\*</span> | String | Bearer `<YOUR_API_KEY>` |
| Content-Type <span style="{color: &#x22;red&#x22;}">\*</span>  | String | application/json        |

## Request Body [#request-body]

| Name                                                     | Type    | Description                                                                                                                                                                                                                                                                                                                |
| -------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| q <span style="{color: &#x22;red&#x22;}">\*</span>       | string  | Search phrase that you want to search                                                                                                                                                                                                                                                                                      |
| domain <span style="{color: &#x22;red&#x22;}">\*</span>  | string  | Choose google domain.<br /><br />You can retrieve the list of supported Google domains by making a separate request to the [Domains List](/extra-apis/domains-list)                                                                                                                                                        |
| device <span style="{color: &#x22;red&#x22;}">\*</span>  | string  | `desktop` To extract desktop result `mobile` To extract mobile result                                                                                                                                                                                                                                                      |
| lang <span style="{color: &#x22;red&#x22;}">\*</span>    | string  | You can set language for e.g. `en` for english `fr` for french.<br />Get the list of available languages by making a separate request to the [Languages List](/extra-apis/languages-list)                                                                                                                                  |
| loc <span style="{color: &#x22;red&#x22;}">\*</span>     | string  | Optional field if you specify `loc_id`<br />&#x2A;*You must choose one of the fields: `loc_id` or `loc`**<br />You can receive the list of available locations of search engines with their loc\_id by making a separate request to the [Locations List](/extra-apis/locations-list)                                       |
| loc\_id <span style="{color: &#x22;red&#x22;}">\*</span> | integer | Optional field if you specify `loc`<br />&#x2A;*You must choose one of the fields: `loc_id` or `loc`**<br />You can receive the list of available locations of search engines with their loc\_id by making a separate request to the [Locations List](/extra-apis/locations-list)                                          |
| date\_range                                              | String  | Sometimes you may want to only find information published during a specific time frame. To limit Google results by date<br /><br />Parameter values can be comma separated date range `YYYY-MM-DD,YYYY-MM-DD` OR<br /><br />`h` Past hour<br />`d` Past 24 hours<br />`w` Past week<br />`m` Past month<br />`y` Past year |
| page                                                     | integer | Give specific page to get the result of that page number. By default it will get you first page.                                                                                                                                                                                                                           |
| video\_duration                                          | String  | `short` (0-4 min), `medium` (4-20 min), `long` (20+ min)                                                                                                                                                                                                                                                                   |
| video\_quality                                           | String  | Allows filtering video results by quality level.<br />By default, videos of all qualities are returned. Use this option to request only high-quality videos.<br /><br />Available value:<br />`high` – high-quality videos only                                                                                            |
| video\_captions                                          | String  | Use this parameter to return only videos that include captions.<br />If not provided, both captioned and non-captioned videos are included in the results.<br /><br />To retrieve only videos with closed captions, the `captioned` parameter should be used.                                                              |

<VisualRef title="Google Videos API" src="/images/google/google-videos-api.png" alt="Google video search results" />

## Example Request [#example-request]

<ApiExample endpoint="https://api.serphouse.com/google-videos-api" query="scraping guides" domain="google.com" lang="en" params="{&#x22;device&#x22;: &#x22;desktop&#x22;, &#x22;loc&#x22;: &#x22;Mumbai,Maharashtra,India&#x22;}" />

## Example Response [#example-response]

<ApiExample mode="response">
  <ApiTab label="JSON" response="googleVideosJsonResponse" />

  <ApiTab label="Markdown" response="googleVideosMarkdownResponse" lang="markdown" />
</ApiExample>

## Related Links [#related-links]

<Cards>
  <Card title="Google Search API" href="/google-apis/google-search-api" />

  <Card title="Google Short Videos API" href="/google-apis/google-short-videos-api" />
</Cards>


# Google APIs (/docs/google-apis)



SERPHouse Google APIs give you structured access to Google Search results across major verticals. Use them for ranking tracking, competitive research, content discovery, and product intelligence.

All endpoints require authentication → pass your API key as a Bearer token in the `Authorization` header.

## Search & Results [#search--results]

<Cards>
  <Card title="Google Search API" description="Full web SERP with organic results, local pack, and more." href="/google-apis/google-search" />

  <Card title="Google Lite Web Search API" description="Fast, lightweight organic results with titles and snippets." href="/google-apis/google-lite-web-search-api" />

  <Card title="Google SERP (Top 100 Results)" description="Fetch up to 100 results across multiple pages." href="/google-apis/google-serp-top-100-results" />

  <Card title="Google Batch SERP (Top 100)" description="Schedule multi-page searches with credit refund for unused pages." href="/google-apis/google-schedule-serp-top-100-results" />
</Cards>

## Verticals [#verticals]

<Cards>
  <Card title="Google News API" description="Real-time Google News headlines and stories." href="/google-apis/google-news-api" />

  <Card title="Google Image API" description="Google Image search results." href="/google-apis/google-image-api" />

  <Card title="Google Shopping API" description="Product listings, pricing, and shopping data." href="/google-apis/google-shopping-api" />

  <Card title="Google Jobs API" description="Structured job listings and hiring data." href="/google-apis/google-jobs-api" />

  <Card title="Google Local API" description="Local business results with ratings and addresses." href="/google-apis/google-local-api" />

  <Card title="Google Videos API" description="Video search results with duration and quality filters." href="/google-apis/google-videos-api" />

  <Card title="Google Short Videos API" description="Short-form video results from Google Search." href="/google-apis/google-short-videos-api" />

  <Card title="Google Forums API" description="Forum discussions including Reddit and Stack Exchange." href="/google-apis/google-forums-api" />

  <Card title="Google Autocomplete API" description="Real-time search suggestions and autocomplete." href="/google-apis/google-autocomplete-api" />
</Cards>

## Related [#related]

<Cards>
  <Card title="Getting Started" href="/getting-started" />

  <Card title="Locations List" href="/extra-apis/locations-list" />

  <Card title="Domains List" href="/extra-apis/domains-list" />

  <Card title="Languages List" href="/extra-apis/languages-list" />
</Cards>


# Credits & Pricing (/docs/rank-tracker/credits-and-pricing)



<Callout type="info" title="Rank Tracker itself is free">
  There's no separate subscription for the add-on. Every rank check spends
  SERPHouse API credits from your own SERPHouse account, the same pool of
  credits used by any other SERPHouse integration. Plan pricing lives on the
  main [Getting Started](/getting-started#pricing) page; this page explains
  what Rank Tracker specifically does with those credits.
</Callout>

## The formula [#the-formula]

Every keyword + location pair that needs checking costs credits based on your **Search depth** setting, because SERPHouse charges per **page** it scrapes, and Search depth determines how many pages that is.

<Callout type="warning" title="Cost = pages, not position">
  You're charged for every page SERPHouse scrapes to fulfil your Search
  depth, **regardless of where your site turns up** in the results. Rank
  Tracker doesn't ask SERPHouse to stop early once it finds your domain; it
  scans every returned page locally, after the fact. Searching Top 100 costs
  the same whether your site is #2 or absent entirely.
</Callout>

| Search depth | Pages requested (`max_pages`) | Credits per pair, per day |
| ------------ | ----------------------------- | ------------------------- |
| Top 10       | 1                             | 10                        |
| Top 30       | 3                             | 30                        |
| Top 50       | 5                             | 50                        |
| Top 100      | 10                            | 100                       |

This is the same **1 page = 10 credits** rule documented on the [Google SERP (Top 100 Results)](/google-apis/google-serp-top-100-results) endpoint that Rank Tracker calls under the hood. Nothing here is a special or different rate.

## Estimating the cost of a run [#estimating-the-cost-of-a-run]

```text
Estimated cost = (pairs that still need a check today) × (credits per pair, from the table above)
```

The key phrase is &#x2A;"pairs that still need a check today"*, not your full tracked list. A pair that's already ranked or confirmed not-ranked earlier today is skipped entirely on a re-run, at zero extra cost. Only pairs that are blank or marked `F` (failed) get checked. See [What actually gets checked](/rank-tracker/fetching-rankings#what-actually-gets-checked) for the full explanation.

## Where you see the cost before you spend it [#where-you-see-the-cost-before-you-spend-it]

The **Fetch rankings now** sidebar always shows a pre-flight estimate before anything runs: pairs to check, the estimated credit cost, and your current balance, with a warning if the estimate could exceed it.

<Callout type="warning" title="Scheduled runs can't ask permission">
  On a manual fetch, exceeding your balance estimate prompts a "Continue
  anyway?" confirmation. A **scheduled** run has no one to ask, so it logs a
  warning and proceeds anyway. If your balance is genuinely close to zero, a
  scheduled run can start and then simply run out mid-way, so set a
  realistic [low-credit threshold](/rank-tracker/settings) to notice before
  that happens, not after.
</Callout>

## Checking your balance [#checking-your-balance]

Your balance is always visible on the Dashboard's row-2 bar (`Site: … • Credits: …&#x60;), refreshed after every fetch. It turns red with a **⚠ LOW** label once it drops below your configured [low-credit threshold](/rank-tracker/settings) (500 by default). You can also force an immediate check from the menu → **Check credit balance**.

## Reducing what you spend [#reducing-what-you-spend]

* **Lower Search depth.** This is the single biggest lever: dropping from Top 100 to Top 30 cuts the cost of every pair by more than 3×.
* **Track fewer pairs**, or exclude low-priority ones with the [`X` marker](/rank-tracker/dashboard#excluding-a-pair). Excluded pairs cost nothing, and it's reversible at any time.
* **Fetch less often.** Switch [Frequency](/rank-tracker/settings) from Daily to Alternate days or Weekly, and enable Skip weekends.
* **Let the retry model work for you.** There's no need to manually re-run a fetch that already shows "Completed" for the day. Everything that succeeded is skipped automatically on any re-run, so retrying costs nothing extra, but it also gains nothing.

## Worked example [#worked-example]

20 keywords tracked across 5 locations equals **100 pairs**.

| Scenario                       | Credits per run    | Roughly per month |
| ------------------------------ | ------------------ | ----------------- |
| Top 100, run **Daily**         | 100 × 100 = 10,000 | \~300,000         |
| Top 30, run **Daily**          | 100 × 30 = 3,000   | \~90,000          |
| Top 30, run **Alternate days** | 100 × 30 = 3,000   | \~45,000          |

<Callout type="idea" title="Tip">
  Run these numbers against your own tracked list *before* pasting in a few
  hundred keywords at once. It's easy to add a lot of pairs quickly through
  the Setup guide's bulk keyword box, and the cost scales linearly with every
  one you add. Compare the totals above against your plan's credit allowance
  on [Getting Started](/getting-started#pricing).
</Callout>

## Behind the scenes [#behind-the-scenes]

Only one call actually spends credits under this model: the ranking check itself, against the [Google Advanced (Top 100) endpoint](/google-apis/google-serp-top-100-results). The [account balance](/extra-apis/account-info) and [location search](/extra-apis/locations-list) calls Rank Tracker makes elsewhere (checking your balance, validating a location, populating the Add-location search dialog) are separate, administrative lookups, and not part of the ranking-check flow described above.

## Related [#related]

<Cards>
  <Card title="Settings" description="Where Search depth and every other cost-relevant field live." href="/rank-tracker/settings" />

  <Card title="Fetching Rankings" description="The retry model that keeps re-runs from double-billing." href="/rank-tracker/fetching-rankings" />

  <Card title="Google SERP (Top 100 Results)" description="The raw endpoint and pricing rule this page is built on." href="/google-apis/google-serp-top-100-results" />
</Cards>


# Understanding the Dashboard (/docs/rank-tracker/dashboard)



The **Dashboard** sheet is the only tab you're expected to read regularly. It's redrawn automatically every time you open the spreadsheet or make an edit, so it always reflects the latest data without you having to refresh anything.

## Layout at a glance [#layout-at-a-glance]

| Area                    | Contains                                                                                        |
| ----------------------- | ----------------------------------------------------------------------------------------------- |
| Row 1                   | Logo + "Keyword Rank Tracker · powered by SERPHouse.com"                                        |
| Row 2                   | **Site:** your target domain, and &#x2A;*Credits:** your live balance                           |
| Row 3                   | Stats: Total Keywords, Total Locations, Keywords in Top 3, Keywords in Top 10, Average Position |
| Row 4                   | Thin spacer                                                                                     |
| Row 5 (column B onward) | **Locations**, one column per location you track                                                |
| Column A (row 6 onward) | **Keywords**, one row per keyword you track                                                     |
| Row 6+, Column B+       | The **rank** for that keyword at that location, on the most recent fetch                        |

<Callout type="warning" title="Rows 1-4 are not editable">
  The header is redrawn on every open and every edit, which also **reverts
  any manual change** to that area. Think of it as a read-only status bar,
  not a cell you can type into. Your keywords (column A) and locations (row
  5\) are the only parts of the sheet meant for typing.
</Callout>

## The header bar [#the-header-bar]

* **Credits bar (row 2):** shows your last-known SERPHouse balance as `available / total&#x60;. It turns red with a **⚠ LOW** label once your balance drops below the [low-credit threshold](/rank-tracker/settings) you've set. This number doesn't call the API on every render; it's refreshed after every fetch and by the **Check credit balance** menu item. See [Credits & Pricing](/rank-tracker/credits-and-pricing).
* **Stats bar (row 3):** computed from your most recent date sheet only:
  * **Total Keywords / Total Locations**: counts from the Dashboard grid itself.
  * **Keywords in Top 3 / Top 10**: the number of *distinct* keywords ranking that well in **at least one** location.
  * **Average Position**: the mean of every numeric rank found on the latest date (failed and not-ranked pairs are excluded from the average).

## Reading a rank cell [#reading-a-rank-cell]

Each cell in the grid can be in one of six states:

| Example                                                                      | Meaning                                                                                                                                                                                          |
| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| *(blank)*                                                                    | No result yet for the latest date; this pair hasn't been fetched today.                                                                                                                          |
| <span style="{color: &#x22;#000000&#x22;, fontWeight: 700}">12</span>        | Ranked **#12**. Black/plain text means there's nothing to compare it to (first day tracked, or yesterday had no data).                                                                           |
| <span style="{color: &#x22;#0f9d58&#x22;, fontWeight: 700}">8 (+4 ↑)</span>  | Ranked **#8**, up **4 positions** since yesterday. Green always means improvement; remember that a **lower** rank number is better.                                                              |
| <span style="{color: &#x22;#d93025&#x22;, fontWeight: 700}">15 (-3 ↓)</span> | Ranked **#15**, down **3 positions** since yesterday.                                                                                                                                            |
| <span style="{color: &#x22;#d93025&#x22;, fontWeight: 700}">-</span>         | **Not ranked.** The site wasn't found anywhere within your tracked [Search depth](/rank-tracker/settings) on the latest fetch. This is a real, successful result: the site simply didn't appear. |
| <span style="{color: &#x22;#b06000&#x22;, fontWeight: 700}">F</span>         | **Fetch failed.** The last attempt for this pair errored (network issue, transient API error, etc). See [Fetching Rankings](/rank-tracker/fetching-rankings#retries--failures).                  |
| <span style="{color: &#x22;#999999&#x22;, fontWeight: 700}">X</span>         | **Excluded.** You typed `X` into this cell to stop tracking it. See [Excluding a pair](#excluding-a-pair) below.                                                                                 |

<Callout type="error" title="'F' is not the same as '-'">
  A red &#x2A;*`-`*&#x2A; is a confirmed result: your site genuinely isn't ranking.
  An amber &#x2A;*`F`** means Rank Tracker *doesn't know yet*, because the check
  itself failed. Treating an `F` as a ranking drop is the most common
  misread of the Dashboard. Re-run **Fetch rankings now** to resolve it;
  only the failed pairs are re-checked, so this costs nothing extra for
  everything that already succeeded.
</Callout>

## Tooltips & history [#tooltips--history]

Hover over any rank cell to see:

1. **🔗 the ranking URL**: the exact page on your site that ranked, if one was found.
2. **📊 History (Last 10 Days)**: the rank recorded on each of the last 10 dates, or "No Data" for days with nothing recorded.

For a failed (`F`) cell, the tooltip replaces the history with a short explanation instead, so you don't have to guess why a cell looks different.

<Callout type="idea" title="Tip">
  Hovering is the fastest way to sanity-check a sudden change. You can see
  at a glance whether a drop is part of a trend or a one-day blip, without
  opening a single date sheet.
</Callout>

## Invalid location names [#invalid-location-names]

If you type a location directly into row 5 instead of using &#x2A;*Add location…**, it's checked against SERPHouse's location database as you tab away from the cell:

* **Recognized**: the cell is left alone.
* **Not recognized**: the cell is highlighted red with a note explaining it isn't a valid SERPHouse location.

Full details, including how to search for valid locations, are on the [Keywords & Locations](/rank-tracker/keywords-and-locations) page.

## Excluding a pair [#excluding-a-pair]

Type `X` directly into any rank cell to pause tracking for that one keyword + location pair:

* It's skipped by every future fetch, so **0 credits** are spent on it for as long as the `X` stays there.
* It's greyed out on the Dashboard and left out of the Summary sheet's KPIs.
* Nothing else is touched: history already recorded in date sheets is kept, and removing the `X` resumes tracking immediately (an empty cell is fetched again on the next run).

<Callout type="warning">
  Excluding is purely forward-looking. It does not delete or hide anything
  in past date sheets. It only tells future fetches (and the Summary sheet)
  to skip this pair from now on.
</Callout>

## Related [#related]

<Cards>
  <Card title="Fetching Rankings" description="How and when cells actually get filled in." href="/rank-tracker/fetching-rankings" />

  <Card title="Keywords & Locations" description="Adding, validating, and removing what you track." href="/rank-tracker/keywords-and-locations" />

  <Card title="Summary & Logs" description="Trends, KPIs, and run history built from the same data." href="/rank-tracker/summary-and-logs" />

  <Card title="Quick Reference" description="The full marker and menu cheat sheet on one page." href="/rank-tracker/reference" />
</Cards>


# FAQ & Troubleshooting (/docs/rank-tracker/faq)



<FAQSchema
  items="[
  {
    question: &#x22;Why is a cell showing 'F' instead of a rank?&#x22;,
    answer:
      &#x22;F means the last fetch attempt for that keyword and location failed. It is a network or API error, not a real ranking result, so it is automatically retried the next time you fetch at no extra cost and is never confused with '-' (genuinely not ranked).&#x22;,
  },
  {
    question: &#x22;I clicked 'Fetch rankings now' and it said everything is already up to date. Is that a bug?&#x22;,
    answer:
      &#x22;No. A fetch only checks pairs that are blank or marked F for today. If every tracked pair already has a number or a '-' for today, there is nothing left to check, so the run finishes immediately without spending any credits.&#x22;,
  },
  {
    question: &#x22;I got 'A fetch is already running', what do I do?&#x22;,
    answer:
      &#x22;Only one fetch can run at a time per spreadsheet, whether it was started manually, by the schedule, or by an automatic continuation. Wait for it to finish, or open the Fetch rankings now sidebar to check progress and use Stop if it looks stuck, then try again.&#x22;,
  },
  {
    question: &#x22;My scheduled fetch ran at the wrong time. Why?&#x22;,
    answer:
      &#x22;The Run hour setting fires in your spreadsheet's own time zone, set under File then Settings in Sheets, not any other clock. Check that time zone first. If you change Run hour or re-save Settings, the trigger is recreated with the corrected time.&#x22;,
  },
  {
    question: &#x22;Why did an entire run stop early and show 'Aborted'?&#x22;,
    answer:
      &#x22;Either an authorization error, HTTP 401 or 403, usually a bad or expired API key, or five consecutive failures in a row for other reasons, often a temporary SERPHouse outage or an exhausted credit balance. Either way, everything already fetched in that run is kept, so fix the underlying issue and fetch again to finish the rest.&#x22;,
  },
  {
    question: &#x22;I typed a location and the cell turned red. What's wrong?&#x22;,
    answer:
      &#x22;The text you typed is not an exact match for a recognized SERPHouse location. Use the 'Add location' menu item to search and click a valid result instead of typing directly into row 5, which guarantees the correct spelling and format.&#x22;,
  },
  {
    question: &#x22;How do I add a new keyword?&#x22;,
    answer:
      &#x22;Type it directly into any empty row in column A on the Dashboard. It is picked up automatically the next time you fetch, with no extra sync step required. You can also paste a whole list at once from the Setup guide's Add keywords box.&#x22;,
  },
  {
    question: &#x22;How do I stop tracking a keyword I don't want anymore?&#x22;,
    answer:
      &#x22;Delete its row from the Dashboard, then run 'Clean up removed keywords & locations' from the menu. Deleting the row stops it from being fetched immediately; running the cleanup removes its history from every date sheet so old data doesn't keep piling up.&#x22;,
  },
  {
    question: &#x22;I edited a keyword's spelling directly on the Dashboard and now it shows no data. What happened?&#x22;,
    answer:
      &#x22;Rank Tracker matches keywords by exact text, so editing one in place is treated as removing the old keyword and adding a brand new one. The new spelling has no history yet, which is why the row looks blank, while the old spelling's data is still sitting, now orphaned, in your date sheets. Add the corrected keyword, delete the old row, and run 'Clean up removed keywords & locations' to remove the leftover entries.&#x22;,
  },
  {
    question: &#x22;Can two people share this spreadsheet and use their own SERPHouse accounts?&#x22;,
    answer:
      &#x22;Yes. Each person's API key is stored privately to their own Google account and is never visible to anyone else who opens the sheet. Fetch runs themselves are still mutually exclusive per spreadsheet, so only one person's fetch runs at a time.&#x22;,
  },
  {
    question: &#x22;Does re-running a fetch charge me twice for pairs that already succeeded today?&#x22;,
    answer:
      &#x22;No. Any pair that already holds a number or a '-' for today is treated as done and skipped on every re-run. Only pairs that are still blank or marked F are actually checked, so retrying after a partial failure only spends credits on what is still outstanding.&#x22;,
  },
  {
    question: &#x22;Can I track more than one target site from the same spreadsheet?&#x22;,
    answer:
      &#x22;No, Target domain is a single setting per spreadsheet. To track a second site, install Rank Tracker on a separate spreadsheet with its own Dashboard and Settings.&#x22;,
  },
  {
    question: &#x22;What happens if my SERPHouse credits run out mid-fetch?&#x22;,
    answer:
      &#x22;An insufficient-credits response is treated like any other failure: the affected pairs are marked F instead of the run failing immediately. The whole run only stops early if that happens five times in a row. Everything already fetched is kept, so top up your credits and fetch again to pick up the rest for free.&#x22;,
  },
  {
    question: &#x22;Do I need to keep the spreadsheet open for scheduled fetches to run?&#x22;,
    answer:
      &#x22;No. Once scheduling is enabled, the trigger runs on Google's servers on its own schedule, whether or not the spreadsheet is open in a browser anywhere.&#x22;,
  },
]"
/>

<Accordions>
  <Accordion title="Why is a cell showing 'F' instead of a rank?">
    `F` means the last fetch attempt for that pair **failed**: a network hiccup or API error, not a real ranking result. It's automatically retried the next time you fetch, at no extra cost, and is never confused with a red `-` (genuinely not ranked). See [Reading a rank cell](/rank-tracker/dashboard#reading-a-rank-cell).
  </Accordion>

  <Accordion title="I clicked 'Fetch rankings now' and it said everything is already up to date. Is that a bug?">
    No. A fetch only checks pairs that are **blank*&#x2A; or marked &#x2A;*`F`** for today. If every tracked pair already has a number or a `-` for today, there's nothing left to check, so it finishes immediately without spending any credits. See [What actually gets checked](/rank-tracker/fetching-rankings#what-actually-gets-checked).
  </Accordion>

  <Accordion title="I got 'A fetch is already running', what do I do?">
    Only one fetch runs at a time **per spreadsheet**, whether it was started manually, by the schedule, or by an automatic continuation. Open **Fetch rankings now** to check its progress, use **Stop** if it looks stuck, then try again once it's finished.
  </Accordion>

  <Accordion title="My scheduled fetch ran at the wrong time. Why?">
    **Run hour** fires in **your spreadsheet's own time zone**, set under `File → Settings` in Sheets, not your personal computer's clock or any other time zone. Check that setting first. Changing **Run hour**, or simply re-saving Settings, recreates the trigger with the corrected time.
  </Accordion>

  <Accordion title="Why did an entire run stop early and show 'Aborted'?">
    Two possible causes: an **authorization error** (401/403, usually a bad or expired API key), or **five consecutive failures** in a row for any other reason (often a temporary SERPHouse outage or an exhausted credit balance). Either way, everything already fetched in that run is kept. Fix the underlying issue, then fetch again to finish the rest. See [Retries & Failures](/rank-tracker/fetching-rankings#retries--failures).
  </Accordion>

  <Accordion title="I typed a location and the cell turned red. What's wrong?">
    The text isn't an exact match for a recognized SERPHouse location. Use **Add location** from the menu to search and click a valid result instead of typing directly into row 5, which guarantees correct spelling and formatting. See [Keywords & Locations](/rank-tracker/keywords-and-locations).
  </Accordion>

  <Accordion title="How do I add a new keyword?">
    Type it directly into any empty row in column A on the Dashboard. It's picked up automatically the next time you fetch, with no extra sync step required. You can also paste a whole list at once from the Setup guide's "Add keywords" box. Full walkthrough: [How do I add a new keyword?](/rank-tracker/keywords-and-locations#how-do-i-add-a-new-keyword)
  </Accordion>

  <Accordion title="How do I stop tracking a keyword I don't want anymore?">
    Delete its row from the Dashboard, then run **Clean up removed keywords & locations** from the menu. Deleting the row stops it from being fetched right away; the cleanup step removes its history from every date sheet so old data doesn't keep piling up. If you might want it back later, use the [`X` exclusion marker](/rank-tracker/dashboard#excluding-a-pair) instead of deleting. Full walkthrough: [How do I stop tracking a keyword?](/rank-tracker/keywords-and-locations#how-do-i-stop-tracking-a-keyword)
  </Accordion>

  <Accordion title="I edited a keyword's spelling directly on the Dashboard and now it shows no data. What happened?">
    Rank Tracker matches keywords by exact text, so editing one in place is treated as removing the old keyword and adding a brand new one. The new spelling has no history yet, which is why the row looks blank, while the old spelling's data is still sitting, now orphaned, in your date sheets. Add the corrected keyword, delete the old row, and run **Clean up removed keywords & locations** to remove the leftover entries. Full explanation: [Why editing a keyword directly can look like invalid data](/rank-tracker/keywords-and-locations#why-editing-a-keyword-directly-can-look-like-invalid-data).
  </Accordion>

  <Accordion title="Can two people share this spreadsheet and use their own SERPHouse accounts?">
    Yes. Each person's API key is stored privately to their own Google account and is never visible to anyone else who opens the sheet. Fetch runs themselves are still mutually exclusive per spreadsheet, so only one person's fetch runs at a time.
  </Accordion>

  <Accordion title="Does re-running a fetch charge me twice for pairs that already succeeded today?">
    No. Any pair that already holds a number or a `-` for today is treated as done and skipped on every re-run. See [Credits & Pricing](/rank-tracker/credits-and-pricing).
  </Accordion>

  <Accordion title="Can I track more than one target site from the same spreadsheet?">
    No. **Target domain** is a single setting per spreadsheet. To track a second site, install Rank Tracker on a separate spreadsheet with its own Dashboard and Settings.
  </Accordion>

  <Accordion title="What happens if my SERPHouse credits run out mid-fetch?">
    An insufficient-credits response is treated like any other failure: the affected pairs are marked `F` instead of the run failing immediately. The whole run only stops early after five such failures in a row. Everything already fetched is kept, so top up your credits and fetch again to pick up the rest for free.
  </Accordion>

  <Accordion title="Do I need to keep the spreadsheet open for scheduled fetches to run?">
    No. Once scheduling is enabled, the trigger runs on Google's servers on its own, whether or not the spreadsheet is open anywhere.
  </Accordion>
</Accordions>

## Still stuck? [#still-stuck]

<Callout type="info" title="We're here to help">
  Check the [Logs sheet](/rank-tracker/summary-and-logs) first, since it
  records the exact failure message for every run. If that doesn't explain
  it, reach out to [SERPHouse support](https://serphouse.com) at
  [getsupport@serphouse.com](mailto:getsupport@serphouse.com).
</Callout>


# Fetching Rankings (/docs/rank-tracker/fetching-rankings)



Fetching is the process that actually calls SERPHouse and fills in the grid. You can trigger it yourself, or let it run on a schedule; both go through the exact same engine underneath.

<Tabs items="[&#x22;Manual fetch&#x22;, &#x22;Scheduled fetch&#x22;]">
  <Tab>
    Open the menu → **Fetch rankings now**. A sidebar opens with a pre-flight summary before anything runs:

    * **Pairs to check**: how many keyword + location pairs still need a result today (see [What actually gets checked](#what-actually-gets-checked) below; it's usually fewer than your full tracked list).
    * **Est. credits (max)**: the worst-case cost of this run.
    * **Balance**: your current SERPHouse credit balance.
    * A warning banner if the estimate could exceed your balance.

    Click **Start**, and the sidebar tracks progress live: a progress bar, running counts of **Found** / **Not ranked** / **Failed**, and the exact pair currently being checked. Click **Stop** at any time. It finishes the current batch, then stops cleanly, and whatever's left unresolved just gets picked up the next time you fetch.
  </Tab>

  <Tab>
    Turn on **Enable scheduled fetch** in [Settings](/rank-tracker/settings), choose a **Frequency**, and Rank Tracker installs a single daily trigger that runs quietly in the background, with no sidebar and no dialogs.

    | Setting                       | Behavior                                                                                     |
    | ----------------------------- | -------------------------------------------------------------------------------------------- |
    | **Frequency: Daily**          | Runs every day the trigger fires.                                                            |
    | **Frequency: Alternate days** | Runs only if at least 2 days have passed since the last completed run.                       |
    | **Frequency: Weekly**         | Runs only on the **Weekly day** you pick (e.g. every Monday).                                |
    | **Skip weekends**             | Skips Saturday and Sunday entirely, regardless of the frequency above.                       |
    | **Run hour**                  | The hour (0 to 23) the trigger fires, in **your spreadsheet's** time zone, not the script's. |

    Results land the same way a manual fetch would: the Dashboard, Summary, and Logs sheets all update once the run finishes.

    <Callout type="info">
      Because **Run hour** uses your spreadsheet's own time zone (`File → Settings` in Sheets), changing that time zone changes when the scheduled run fires too.
    </Callout>
  </Tab>
</Tabs>

## What actually gets checked [#what-actually-gets-checked]

A fetch never blindly re-checks your entire tracked list. For each keyword + location pair, it looks at **today's** date sheet first:

* A cell that already holds a **number*&#x2A; or a &#x2A;*`-`** is treated as *done*. It's skipped, and costs nothing on a re-run.
* A cell that's **empty*&#x2A; or marked &#x2A;*`F`** (failed) is *unresolved*. It's what actually gets checked.

<Callout type="idea" title="Tip">
  This is why it's always safe to click **Fetch rankings now** again after a
  partial run: only what's still outstanding gets fetched, so you never pay
  twice for a result you already have.
</Callout>

## Rate limits & concurrency [#rate-limits--concurrency]

Requests are sent **concurrently in batches**, not one at a time, which is why large lists finish faster than you might expect, but never faster than your own configured limit:

* Batch size is derived automatically from your [Max requests / minute](/rank-tracker/settings) setting (capped at 20 per batch), so a burst never exceeds the rate you've told SERPHouse to expect.
* A rolling one-minute window tracks how many requests have gone out; if a batch would exceed your per-minute cap, Rank Tracker pauses until the window resets.
* Transient errors, such as a dropped connection, an HTTP `429`/`5xx`, or a `200` response SERPHouse itself flags as a momentary failure, are retried automatically, up to 3 attempts with backoff, **before** a pair is ever counted as failed.

## Retries & Failures [#retries--failures]

If a pair is still failing after its automatic retries, its cell is marked &#x2A;*`F`** and the run continues on to the rest of the list, so one slow or broken pair never blocks everything else. Two situations stop the **entire run** early instead, because continuing would waste credits or time:

| Condition                         | What happens                                                                                                                                                 |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Authorization error** (401/403) | The run stops immediately with a message to check your API key. Nothing further is attempted until it's fixed.                                               |
| **5 consecutive failures**        | The run stops, usually a sign SERPHouse is temporarily down or your quota is exhausted. Everything already fetched is kept; re-run later to finish the rest. |

<Callout type="error" title="'F' isn't a ranking result">
  A failed pair is never recorded as "not ranked." It's retried the next
  time you fetch, and only counts as a real result once SERPHouse actually
  returns one. See [Reading a rank cell](/rank-tracker/dashboard#reading-a-rank-cell).
</Callout>

## Handling the 6-minute execution limit [#handling-the-6-minute-execution-limit]

Google Apps Script caps every single run at 6 minutes. If your tracked list is large enough that fetching it all would run past that limit, Rank Tracker detects this *before* it happens (leaving a safety margin), stops itself cleanly, and schedules a **continuation** to pick up exactly where it left off, one minute later, automatically, with no action from you.

You'll see this reflected in the run's final status:

| Status                  | Meaning                                                                        |
| ----------------------- | ------------------------------------------------------------------------------ |
| **Completed**           | Everything finished.                                                           |
| **Paused (time limit)** | Hit the 6-minute execution cap. Resumes automatically within about a minute.   |
| **Stopped (by user)**   | You clicked **Stop** in the sidebar. Resume manually whenever you like.        |
| **Aborted**             | Hit an auth error or 5 consecutive failures. Needs your attention (see above). |

## Fetches never overlap [#fetches-never-overlap]

Only one fetch, whether manual, scheduled, or a continuation, can run at a time **per spreadsheet**. If you click **Fetch rankings now** while one is already in progress, you'll be told a fetch is already running instead of a second one starting and double-spending credits.

If you've installed Rank Tracker on multiple spreadsheets, or shared one with teammates, this guarantee is also **per-document**: one spreadsheet's fetch, progress bar, and Stop button are completely invisible to any other spreadsheet, and nothing you see or do here can interfere with anyone else's.

## Related [#related]

<Cards>
  <Card title="Settings" description="Every schedule, rate-limit, and depth field explained." href="/rank-tracker/settings" />

  <Card title="Credits & Pricing" description="How the cost of a fetch is actually calculated." href="/rank-tracker/credits-and-pricing" />

  <Card title="Summary & Logs" description="Where a completed run's results end up." href="/rank-tracker/summary-and-logs" />
</Cards>


# Rank Tracker (/docs/rank-tracker)



**Rank Tracker** is a Google Sheets add-on (built on Google Apps Script) that checks where your site ranks on Google for a list of keywords, across as many locations as you want, once a day. Everything, including the tracking grid, the history, and the charts, lives inside a spreadsheet you own. There's nothing to host and nothing to log into.

<Callout type="idea" title="No coding required">
  Install it from the [Google Workspace Marketplace](https://workspace.google.com/marketplace/search/serphouse),
  paste in a SERPHouse API key, and you have a working rank tracker in under
  five minutes. See [Installation & Setup](/rank-tracker/installation-and-setup).
</Callout>

## What it does [#what-it-does]

* **Tracks rank, not just visibility.** For every keyword + location pair, it records your site's exact organic position (1–100) once per day.
* **Shows day-over-day movement.** The Dashboard highlights whether each keyword moved up (green ▲), dropped (red ▼), or stayed put, automatically, every time you open the sheet.
* **Keeps history.** Every day gets its own sheet, so you can look back at any date. The Dashboard tooltips show the last 10 days at a glance, and the Summary sheet plots a sparkline trend over a configurable window.
* **Tracks its own cost.** Your SERPHouse credit balance is shown on the Dashboard and checked *before* every run, so you're never surprised by a bill. See [Credits & Pricing](/rank-tracker/credits-and-pricing).
* **Runs itself.** Turn on scheduling once (daily, every other day, or weekly), and new rankings appear automatically; you only need to open the sheet to read them.
* **Recovers from failure on its own.** A failed lookup is retried the next time you fetch. It never gets silently confused with "not ranked," and you're never billed twice for the same result. See [Fetching Rankings](/rank-tracker/fetching-rankings).

## How the spreadsheet is organized [#how-the-spreadsheet-is-organized]

Rank Tracker manages four kinds of sheet tabs for you. You only ever need to type into one of them.

| Sheet                          | Created by             | What it's for                                                          | Do you edit it?            |
| ------------------------------ | ---------------------- | ---------------------------------------------------------------------- | -------------------------- |
| **Dashboard**                  | Setup guide            | Your master list of keywords & locations, and the latest rank for each | Yes, this is your input    |
| **Date sheets** (`YYYY-MM-DD`) | Automatically, per day | The raw rank recorded for every pair on that day                       | No, read-only reference    |
| **Summary**                    | Automatically          | KPIs, trend sparklines, and biggest movers                             | No, rebuilt on every fetch |
| **Logs**                       | Automatically          | A history of every fetch run (found / not ranked / failed counts)      | No, rebuilt on every fetch |

Read [Understanding the Dashboard](/rank-tracker/dashboard) for a full tour of what every cell, color, and symbol means.

## Get started [#get-started]

<Cards>
  <Card title="Installation & Setup" description="Install the add-on and complete the 4-step guided setup." href="/rank-tracker/installation-and-setup" />

  <Card title="Credits & Pricing" description="Understand the cost before you add hundreds of keywords." href="/rank-tracker/credits-and-pricing" />
</Cards>

## Explore the docs [#explore-the-docs]

<Cards>
  <Card title="Understanding the Dashboard" description="Every color, arrow, and marker on the tracking grid explained." href="/rank-tracker/dashboard" />

  <Card title="Fetching Rankings" description="Manual fetches, scheduling, retries, and rate limits." href="/rank-tracker/fetching-rankings" />

  <Card title="Keywords & Locations" description="Add, validate, and clean up what you track." href="/rank-tracker/keywords-and-locations" />

  <Card title="Settings" description="Every configuration field, explained." href="/rank-tracker/settings" />

  <Card title="Summary & Logs" description="KPIs, sparkline trends, and run history." href="/rank-tracker/summary-and-logs" />

  <Card title="Quick Reference" description="A cheat sheet of every menu item and cell marker." href="/rank-tracker/reference" />

  <Card title="FAQ & Troubleshooting" description="Answers to the questions users ask most." href="/rank-tracker/faq" />
</Cards>

## Under the hood [#under-the-hood]

Rank Tracker isn't a separate product with its own API. It's a client of the same SERPHouse API documented elsewhere on this site, and every rank check is one call to the Google Advanced (Top 100) endpoint, filtered locally for your domain.

<Cards>
  <Card title="Google SERP (Top 100 Results)" description="The exact endpoint Rank Tracker calls to check rankings." href="/google-apis/google-serp-top-100-results" />

  <Card title="Account Info" description="The endpoint that powers the credit balance shown on the Dashboard." href="/extra-apis/account-info" />

  <Card title="Locations List" description="The endpoint behind the location search dialog and validation." href="/extra-apis/locations-list" />
</Cards>


# Installation & Setup (/docs/rank-tracker/installation-and-setup)



## Install the add-on [#install-the-add-on]

Rank Tracker is distributed as a **Google Workspace Editor Add-on**. It installs on top of Google Sheets, not as a separate app.

<Steps>
  <Step>
    **Open a Google Sheet** (a new or existing spreadsheet; this becomes your tracking sheet).
  </Step>

  <Step>
    **Install the add-on** from the [Google Workspace Marketplace](https://workspace.google.com/marketplace/search/serphouse) (search for "SERPHouse"), or find it from inside Sheets via `Extensions → Add-ons → Get add-ons`. A Workspace admin can also install it domain-wide.
  </Step>

  <Step>
    **Reload the spreadsheet.** A new menu appears, **Keyword Rank Tracker - SERPHouse**, either as its own top-level menu or nested under `Extensions`, depending on your Sheets UI version.
  </Step>
</Steps>

<Callout type="info" title="What permissions does it ask for?">
  During install, Google shows a consent screen for a handful of scopes.
  Rank Tracker deliberately requests the narrowest scope available for each,
  notably `spreadsheets.currentonly`, **not** full Drive/Sheets access, so it
  can never read or modify any spreadsheet other than the one it's installed
  on.
</Callout>

| Scope                         | Why it's needed                                                     |
| ----------------------------- | ------------------------------------------------------------------- |
| `userinfo.email` / `.profile` | Identifies you as the installer (used for per-user API key storage) |
| `spreadsheets.currentonly`    | Read/write **only** the spreadsheet the add-on is running in        |
| `script.external_request`     | Call the SERPHouse API (fetch rankings, credits, locations)         |
| `script.scriptapp`            | Create/manage the daily schedule trigger                            |
| `script.container.ui`         | Show the menu, sidebars, and dialogs                                |

## Run the Setup guide [#run-the-setup-guide]

The first time you open the menu, **Setup guide** is listed at the top: a sidebar that walks through everything needed to get your first ranking. It disappears from the menu automatically once setup is complete (you don't have to dismiss it manually, though you can).

<Steps>
  <Step>
    ### 1. API key & your site [#1-api-key--your-site]

    Paste in a **SERPHouse API key** and your **target domain** (the site whose rankings you want to track, e.g. `www.example.com`).

    <Callout type="idea" title="Don't have a key yet?">
      Get one, including a free trial, at [serphouse.com](https://www.serphouse.com/).
    </Callout>

    Click **Save & verify**. Rank Tracker immediately calls the SERPHouse account API to confirm the key works and to show your starting credit balance.

    <Callout type="error" title="Keep your key private">
      Never paste your API key into a spreadsheet cell, a shared doc, or a public
      script. Rank Tracker stores it for you in a private, per-user location that
      no other installer of the same sheet can read (see [How the API key is
      stored](/rank-tracker/settings#how-the-api-key-is-stored)), so you never
      need to store it anywhere else.
    </Callout>
  </Step>

  <Step>
    ### 2. Create the dashboard [#2-create-the-dashboard]

    One click builds the **Dashboard** sheet: the grid where keywords go down the side and locations go across the top. This step is idempotent, so clicking it again on a Dashboard that already has content does nothing, and it's safe to click twice.
  </Step>

  <Step>
    ### 3. Add keywords & locations [#3-add-keywords--locations]

    Paste in keywords (one per line, or comma-separated) and use &#x2A;*Add location…** to search for and add locations by city, region, or country. Full details on how location search and validation work are on the [Keywords & Locations](/rank-tracker/keywords-and-locations) page.
  </Step>

  <Step>
    ### 4. Fetch your first rankings [#4-fetch-your-first-rankings]

    Click **Open fetch panel** to run a real fetch against your own keywords (this spends credits, see [Credits & Pricing](/rank-tracker/credits-and-pricing)), or click **Load sample data** to see the tool work instantly with two example keywords and two example locations already fetched for you.
  </Step>
</Steps>

<Callout type="success" title="You'll know when you're done">
  Once you have a saved API key, a Dashboard, at least one keyword and one
  location, and at least one day of fetched data, the guide marks itself
  complete on its own, with no need to click anything. You can still dismiss
  it early with the **Done** button at the bottom of the guide, and reopen it
  anytime from the menu if it's no longer listed (it's only shown as
  **Setup guide** until then, and folds into the regular menu items after
  that).
</Callout>

<ManualSetup>
  If you're migrating a sheet that already has manually-built tabs (for example, an older version of this tool that used a "Settings" sheet instead of a sidebar), you don't need to redo onboarding:

  * An existing **Settings** sheet is detected and its values are copied in automatically the first time settings are read, so no data is lost.
  * An existing **Dashboard** with content is left untouched by "Create the dashboard"; it only builds a fresh one when none exists.
  * Jump straight to [Settings](/rank-tracker/settings) from the menu instead of the guide if you'd rather configure everything by hand.
</ManualSetup>

## What's next [#whats-next]

<Cards>
  <Card title="Understanding the Dashboard" description="What every color, arrow, and marker on the grid means." href="/rank-tracker/dashboard" />

  <Card title="Credits & Pricing" description="Understand the cost model before adding hundreds of keywords." href="/rank-tracker/credits-and-pricing" />
</Cards>


# Keywords & Locations (/docs/rank-tracker/keywords-and-locations)



Keywords and locations are the two axes of the Dashboard grid. Every combination of one keyword and one location is a **pair**, and every pair gets its own rank checked once a day.

## How do I add a new keyword? [#how-do-i-add-a-new-keyword]

Type it directly into a blank row in **column A** on the Dashboard, starting at row 6. That's the whole process: there's no separate "add keyword" dialog, it's a plain spreadsheet column, and the new keyword is picked up automatically the next time you fetch.

<Steps>
  <Step>
    **Add it directly on the Dashboard.** Click any empty cell in column A below your existing keywords and type the new keyword.
  </Step>

  <Step>
    **Or add several at once from the Setup guide.** Open the menu → **Setup guide** → the "Add keywords" box accepts a whole list, one per line or comma-separated. It skips anything already on the Dashboard, so pasting the same list twice never creates duplicate rows.
  </Step>

  <Step>
    **Fetch as usual.** You don't need to run any sync step first. Fetching automatically creates a slot for the new keyword in today's date sheet, so the very next fetch checks it along with everything else.
  </Step>
</Steps>

<Callout type="info" title="Matching is case-insensitive">
  `SEO Tools` and `seo tools` are treated as the exact same tracked keyword.
  A casing difference alone never creates two separate tracked pairs, since
  every match is normalized (trimmed and lowercased) before comparison.
</Callout>

## How do I stop tracking a keyword? [#how-do-i-stop-tracking-a-keyword]

Delete its row on the Dashboard, then run **Clean up removed keywords & locations** from the menu to clear its history out of every date sheet. Skipping the second step is safe, but it leaves that keyword's old columns and rows sitting in your date sheets indefinitely.

<Steps>
  <Step>
    **Delete the row on the Dashboard.** Right-click the row number for that keyword and choose **Delete row**. It disappears from the grid immediately and is no longer fetched.
  </Step>

  <Step>
    **Open the menu → Clean up removed keywords & locations.** This permanently deletes that keyword's row from **every** date sheet where it still exists, since deleting it from the Dashboard alone doesn't touch historical data. Confirm when prompted.
  </Step>
</Steps>

<Callout type="error" title="Clean up is destructive">
  Clean up removed keywords & locations permanently deletes historical rank
  data for anything no longer on the Dashboard, across every date sheet.
  There's no undo beyond Google Sheets' own version history, so only run it
  once you're sure you don't need that history back.
</Callout>

<Callout type="idea" title="Just pausing? Use X instead of deleting">
  If you might want this keyword back later, don't delete the row at all.
  Type `X` into its rank cells to exclude it from fetching while keeping the
  row and its history intact. See [Excluding a pair](/rank-tracker/dashboard#excluding-a-pair).
</Callout>

## Why editing a keyword directly can look like invalid data [#why-editing-a-keyword-directly-can-look-like-invalid-data]

Rank Tracker matches every keyword and location by exact text, so **renaming** one directly on the Dashboard is not the same as correcting a typo. It's treated as removing the old keyword and adding a brand-new one at the same time.

Here's the mechanism: your date sheets store history under the keyword's old text. The moment you retype that cell on the Dashboard, the Dashboard grid reads the new text immediately, but none of your date sheets have a column of history filed under that new spelling yet. The row now looks blank, shows no day-over-day comparison, and can appear broken or "invalid" even though nothing is actually wrong. Meanwhile, the old spelling's data is still sitting in every date sheet, now orphaned because nothing on the Dashboard points to it anymore.

<Callout type="warning" title="Treat it as delete-and-add, not rename">
  Editing a keyword or location's text in place always starts a new,
  empty-history pair. If you meant to fix a typo, add the corrected keyword
  as described above, delete the old row, and run **Clean up removed
  keywords & locations** to remove the orphaned entries it left behind.
</Callout>

## Adding locations [#adding-locations]

<Tabs items="[&#x22;Search dialog (recommended)&#x22;, &#x22;Typing directly&#x22;]">
  <Tab>
    Open the menu → **Add location**. Type at least 2 characters of a city, region, or country, and matching SERPHouse locations appear live as you type. Click a result to add it as a new column on the Dashboard. It's also added automatically as an empty column to **every existing date sheet**, so there's a slot ready for it the next time you fetch.
  </Tab>

  <Tab>
    You can also type a location straight into row 5. As soon as you tab away from the cell, it's checked against SERPHouse's location database:

    * **Recognized**: nothing happens, the cell is left as-is.
    * **Not recognized**: the cell is highlighted red with a note explaining it isn't a valid location.

    Locations must match SERPHouse's `"City,Region,Country"` format exactly (for example `Surat,Gujarat,India`). This is why the search dialog is the safer default: it guarantees correct spelling and formatting every time.
  </Tab>
</Tabs>

<Callout type="warning" title="Validation needs an API key">
  Live validation calls the SERPHouse locations API, so it only runs once
  you've saved an API key in [Settings](/rank-tracker/settings). Typing a
  location before that point is accepted without a check.
</Callout>

## Removing a location follows the same rule as removing a keyword [#removing-a-location-follows-the-same-rule-as-removing-a-keyword]

Deleting a location's column from the Dashboard stops it from being fetched immediately, but its history stays behind in every date sheet, exactly like a removed keyword. The same two menu items apply to both:

| Menu item                                             | Direction   | What it actually changes                                                                                                                                                                                                   |
| ----------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Add Dashboard locations & keywords to date sheets** | Add-only    | Scans every date sheet and adds a blank column for any Dashboard location, or a blank row for any Dashboard keyword, that sheet is missing. Never removes or overwrites existing data.                                     |
| **Clean up removed keywords & locations**             | Delete-only | Scans every date sheet and permanently deletes any column or row whose keyword or location text no longer appears on the Dashboard. Asks for confirmation, listing how many rows/columns will be removed, before doing it. |

## When would I actually need to run "Add Dashboard locations & keywords to date sheets"? [#when-would-i-actually-need-to-run-add-dashboard-locations--keywords-to-date-sheets]

Rarely during normal day-to-day use, because a fetch already extends **today's** date sheet automatically to match the Dashboard. It's useful in two specific situations:

* You add a keyword or location but don't fetch right away, and want every tab in sync before you forget which ones are new.
* You want **past** date sheets, not just today's, to already have a placeholder column or row ready for something you just added.

## Related [#related]

<Cards>
  <Card title="Understanding the Dashboard" description="What a rank cell looks like once a pair is being tracked." href="/rank-tracker/dashboard" />

  <Card title="Fetching Rankings" description="How a new keyword or location gets its first rank." href="/rank-tracker/fetching-rankings" />

  <Card title="FAQ & Troubleshooting" description="More on the exact symptoms a direct edit can cause." href="/rank-tracker/faq" />
</Cards>


# Quick Reference (/docs/rank-tracker/reference)



Everything on this page is explained in more depth elsewhere. Use this as the fast lookup for "what does this button or marker do again?"

<Tabs items="[&#x22;Menu reference&#x22;, &#x22;Cell markers & colors&#x22;]">
  <Tab>
    All of these live under one menu, **Keyword Rank Tracker - SERPHouse** (shown either as its own top-level menu or nested under `Extensions`, depending on your Sheets UI version).

    | Menu item                                             | What it does                                                                                                                                                                                                                                                                                                                              |
    | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | **Setup guide**                                       | Opens the guided setup sidebar. Only listed until setup is complete.                                                                                                                                                                                                                                                                      |
    | **Fetch rankings now**                                | Opens the fetch sidebar. See [Fetching Rankings](/rank-tracker/fetching-rankings).                                                                                                                                                                                                                                                        |
    | **Add location**                                      | Opens the location search dialog. See [Keywords & Locations](/rank-tracker/keywords-and-locations).                                                                                                                                                                                                                                       |
    | **Check credit balance**                              | Refreshes and shows your current SERPHouse credit balance.                                                                                                                                                                                                                                                                                |
    | **Settings**                                          | Opens the Settings sidebar. See [Settings](/rank-tracker/settings).                                                                                                                                                                                                                                                                       |
    | **Add Dashboard locations & keywords to date sheets** | Add-only. Scans every date sheet and adds any missing Dashboard location as a blank column, or any missing Dashboard keyword as a blank row. Never removes or overwrites anything. See [When would I need this?](/rank-tracker/keywords-and-locations#when-would-i-actually-need-to-run-add-dashboard-locations--keywords-to-date-sheets) |
    | **Clean up removed keywords & locations**             | Delete-only, with confirmation. Scans every date sheet and permanently deletes any column or row whose keyword or location no longer exists on the Dashboard. See [How do I stop tracking a keyword?](/rank-tracker/keywords-and-locations#how-do-i-stop-tracking-a-keyword)                                                              |
    | **Build Summary**                                     | Rebuilds the Summary sheet on demand. See [Summary & Logs](/rank-tracker/summary-and-logs).                                                                                                                                                                                                                                               |
    | **Refresh Dashboard**                                 | Re-renders the header and grid immediately, without waiting for an edit.                                                                                                                                                                                                                                                                  |
  </Tab>

  <Tab>
    | Cell shows                                                                   | Meaning                                                     |
    | ---------------------------------------------------------------------------- | ----------------------------------------------------------- |
    | *(blank)*                                                                    | Not checked yet today.                                      |
    | <span style="{color: &#x22;#000000&#x22;, fontWeight: 700}">12</span>        | Ranked #12, with nothing to compare it to.                  |
    | <span style="{color: &#x22;#0f9d58&#x22;, fontWeight: 700}">8 (+4 ↑)</span>  | Ranked #8, improved 4 positions since yesterday.            |
    | <span style="{color: &#x22;#d93025&#x22;, fontWeight: 700}">15 (-3 ↓)</span> | Ranked #15, dropped 3 positions since yesterday.            |
    | <span style="{color: &#x22;#d93025&#x22;, fontWeight: 700}">-</span>         | Checked, and genuinely not ranked within your Search depth. |
    | <span style="{color: &#x22;#b06000&#x22;, fontWeight: 700}">F</span>         | The check failed. Retried on the next fetch, for free.      |
    | <span style="{color: &#x22;#999999&#x22;, fontWeight: 700}">X</span>         | Manually excluded. Never fetched, never billed.             |

    | Header bar shows                                                                                                                                                        | Meaning                                                                        |
    | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
    | <span style="{background: &#x22;#1a73e8&#x22;, color: &#x22;#fff&#x22;, padding: &#x22;1px 6px&#x22;, borderRadius: &#x22;3px&#x22;}">Site: … • Credits: …</span>       | Normal. Balance is above your low-credit threshold.                            |
    | <span style="{background: &#x22;#d93025&#x22;, color: &#x22;#fff&#x22;, padding: &#x22;1px 6px&#x22;, borderRadius: &#x22;3px&#x22;}">Site: … • Credits: … ⚠ LOW</span> | Balance has dropped below your [low-credit threshold](/rank-tracker/settings). |

    Full explanations: [Understanding the Dashboard](/rank-tracker/dashboard).
  </Tab>
</Tabs>

## Related [#related]

<Cards>
  <Card title="Understanding the Dashboard" description="The full walkthrough behind the cell-marker cheat sheet above." href="/rank-tracker/dashboard" />

  <Card title="FAQ & Troubleshooting" description="Answers to the questions users ask most." href="/rank-tracker/faq" />
</Cards>


# Settings (/docs/rank-tracker/settings)



All configuration lives in one sidebar: menu → **Settings**. Nothing here is stored in a spreadsheet cell. It's saved to the document itself, so it survives even if you clear or rebuild the Dashboard.

<Tabs items="[&#x22;Connection & Search&#x22;, &#x22;Schedule&#x22;, &#x22;Limits & Performance&#x22;]">
  <Tab>
    <TypeTable
      type="{
  &#x22;SERPHouse API key&#x22;: {
    type: &#x22;password field&#x22;,
    default: &#x22;none&#x22;,
    description:
      &#x22;Stored privately per Google account. Leave it blank when saving to keep whatever key is already stored, since you don't need to re-enter it every time.&#x22;,
  },
  &#x22;Target domain&#x22;: {
    type: &#x22;text&#x22;,
    default: '&#x22;www.example.com&#x22;',
    description:
      &#x22;The site whose ranking you're tracking. Matched by registered domain, so any subdomain of it (blog.example.com, shop.example.com, and so on) also counts as a match.&#x22;,
  },
  &#x22;Google domain&#x22;: {
    type: &#x22;dropdown&#x22;,
    default: &#x22;google.com&#x22;,
    description:
      &#x22;Which country's Google to search: google.com, google.co.in, google.co.uk, and around 50 others.&#x22;,
  },
  &#x22;Language&#x22;: {
    type: &#x22;dropdown&#x22;,
    default: &#x22;en (English)&#x22;,
    description:
      &#x22;Search language, sent to SERPHouse as its language code.&#x22;,
  },
  &#x22;Device&#x22;: {
    type: &#x22;dropdown&#x22;,
    default: &#x22;desktop&#x22;,
    description: &#x22;desktop or mobile: which Google result set to check.&#x22;,
  },
  &#x22;Search depth&#x22;: {
    type: &#x22;dropdown&#x22;,
    default: &#x22;Top 100&#x22;,
    description:
      &#x22;How far down the results to search before giving up and recording '-'. One of Top 10 / 30 / 50 / 100, and also the single biggest lever on cost. See Credits & Pricing.&#x22;,
  },
}"
    />
  </Tab>

  <Tab>
    <TypeTable
      type="{
  &#x22;Enable scheduled fetch&#x22;: {
    type: &#x22;toggle&#x22;,
    default: &#x22;Off&#x22;,
    description:
      &#x22;Turns the daily background trigger on or off. The rest of this section only appears once it's on.&#x22;,
  },
  &#x22;Frequency&#x22;: {
    type: &#x22;dropdown&#x22;,
    default: &#x22;Daily&#x22;,
    description:
      &#x22;Daily, Alternate days, or Weekly. See Fetching Rankings for exactly how each is evaluated.&#x22;,
  },
  &#x22;Weekly day&#x22;: {
    type: &#x22;dropdown&#x22;,
    default: &#x22;Monday&#x22;,
    description: &#x22;Only shown, and only used, when Frequency is Weekly.&#x22;,
  },
  &#x22;Run hour (0 to 23)&#x22;: {
    type: &#x22;number&#x22;,
    default: &#x22;6&#x22;,
    description:
      &#x22;The hour the scheduled run fires, in your spreadsheet's own time zone (not the add-on's).&#x22;,
  },
  &#x22;Skip weekends&#x22;: {
    type: &#x22;toggle&#x22;,
    default: &#x22;Off&#x22;,
    description: &#x22;Skips Saturday and Sunday entirely, regardless of Frequency.&#x22;,
  },
}"
    />
  </Tab>

  <Tab>
    <TypeTable
      type="{
  &#x22;Max requests / minute&#x22;: {
    type: &#x22;number&#x22;,
    default: &#x22;60&#x22;,
    description:
      &#x22;Your SERPHouse rate limit. The concurrent batch size used while fetching is derived from this automatically. See Fetching Rankings.&#x22;,
  },
  &#x22;Low-credit threshold&#x22;: {
    type: &#x22;number&#x22;,
    default: &#x22;500&#x22;,
    description:
      &#x22;Below this balance, the credits bar on the Dashboard turns red with a ⚠ LOW label.&#x22;,
  },
  &#x22;Summary window (days)&#x22;: {
    type: &#x22;number&#x22;,
    default: &#x22;30&#x22;,
    description:
      &#x22;How many days of history the Summary sheet's trend table and sparklines cover.&#x22;,
  },
  &#x22;Enable logging&#x22;: {
    type: &#x22;toggle&#x22;,
    default: &#x22;On&#x22;,
    description:
      &#x22;Whether each fetch run appends a row to the Logs sheet. See Summary & Logs.&#x22;,
  },
}"
    />
  </Tab>
</Tabs>

## How the API key is stored [#how-the-api-key-is-stored]

Your API key is saved to **your own Google account's private storage** for this document, not to a shared, document-wide setting. If you and a teammate both install Rank Tracker on the same spreadsheet, you each use your own key, and neither of you can read the other's.

<Callout type="error" title="Keep your key private">
  Never paste your API key into a spreadsheet cell, a shared doc, or a public
  script. The Settings sidebar is the only place it should ever be typed.
</Callout>

<ManualSetup>
  If this spreadsheet previously used an older version of the tool with a manually-built "Settings" sheet, its values are copied into the modern sidebar-based storage automatically the first time settings are read. There's nothing to do on your end, and the old sheet is safe to delete afterward.
</ManualSetup>

## Search depth and cost [#search-depth-and-cost]

Search depth is the one setting that directly controls how many SERPHouse credits each rank check costs, because a deeper search scans more result pages, and pages are what's actually billed. Before changing it on a large tracked list, read [Credits & Pricing](/rank-tracker/credits-and-pricing) to see the exact formula and a worked example.

## Related [#related]

<Cards>
  <Card title="Credits & Pricing" description="How Search depth and your tracked list size determine cost." href="/rank-tracker/credits-and-pricing" />

  <Card title="Fetching Rankings" description="How the Schedule and rate-limit fields are actually used." href="/rank-tracker/fetching-rankings" />
</Cards>


# Summary & Logs (/docs/rank-tracker/summary-and-logs)



Both sheets are generated automatically from the same date-sheet data the Dashboard uses. You never fill either one in by hand, and edits to them are overwritten the next time they're rebuilt.

## The Summary sheet [#the-summary-sheet]

Rebuilt automatically after every completed fetch, and on demand from the menu → **Build Summary**.

| Row        | Contents                                                                                                                             |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| 1          | Title + last-updated timestamp                                                                                                       |
| 2          | **Tracked** · **Average position** · **In top 10**                                                                                   |
| 3          | **Improved** · **Dropped** · **Lost** · **New** (compared against the previous date)                                                 |
| 4          | **Biggest movers**: the single largest ▲ improvement and ▼ drop, with keyword, location, and size                                    |
| 6+ (table) | One row per tracked pair: **Keyword**, **Location**, **Now**, **Δ vs prev**, **Best**, **Worst**, **Avg**, and a **Trend** sparkline |

<Accordions>
  <Accordion title="What do Improved / Dropped / Lost / New mean?">
    * **Improved / Dropped**: the pair had a numeric rank on both the latest and previous date, and it moved.
    * **Lost**: ranked on the previous date, but not ranked (or no data) on the latest one.
    * **New**: ranked on the latest date, but wasn't ranked (or wasn't tracked yet) on the previous one.
    * A pair whose latest fetch **failed** (`F`) is deliberately left out of all four counts, since a failure isn't a ranking change, so it's not counted as "Lost."
  </Accordion>

  <Accordion title="What do 'Best', 'Worst', and 'Avg' cover?">
    All three are computed only from days **within the Summary window** that actually have a numeric rank. Days with no data or a failed fetch are skipped, not treated as zero.
  </Accordion>

  <Accordion title="Why does the Trend sparkline go up when rank gets better?">
    The sparkline plots the *negative* of each day's rank, so an improving position (a lower rank number) always reads as an upward line, matching how the rest of the Dashboard uses green-up / red-down. The window length is [Summary window (days)](/rank-tracker/settings) in Settings (30 by default).
  </Accordion>

  <Accordion title="What shows up in the 'Now' column?">
    A number if the pair is ranked, `-` if it was checked and genuinely not ranked, `F` if the latest fetch for it failed, or blank if it hasn't been checked yet today. The **Δ vs prev** column shows a plain `—` character (not a ranking change) whenever the latest result is a failure or there's nothing to compare it to.
  </Accordion>
</Accordions>

<Callout type="info">
  The Summary sheet has a "warn before editing" protection, like every other
  generated sheet. It's a guardrail against accidental typing, not a hard
  lock: the script itself can always write to it, and only a human editor
  sees the warning.
</Callout>

## The Logs sheet [#the-logs-sheet]

Created automatically the first time a fetch runs, as long as **Enable logging** is on in [Settings](/rank-tracker/settings) (it is, by default).

| Column     | Contents                                                                                                                                                              |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Run time   | Timestamp the run finished (or paused/stopped)                                                                                                                        |
| Date       | The date sheet the run was writing to                                                                                                                                 |
| Status     | `Completed`, `Paused (time limit)`, `Stopped (by user)`, or `Aborted`. See [Fetching Rankings](/rank-tracker/fetching-rankings#handling-the-6-minute-execution-limit) |
| Found      | Pairs successfully ranked this run                                                                                                                                    |
| Not ranked | Pairs checked but not found within your Search depth                                                                                                                  |
| Failed     | Pairs that ended the run marked `F`                                                                                                                                   |
| Details    | The specific failure messages (or abort reason), truncated                                                                                                            |

<Callout type="idea" title="Tip">
  The Logs sheet is the fastest way to spot a pattern in failures. A string
  of `Aborted` runs with the same message usually points to an expired API
  key or an exhausted credit balance, both worth checking in [Credits &
  Pricing](/rank-tracker/credits-and-pricing).
</Callout>

Only the most recent **500 runs** are kept. Older rows are trimmed automatically so the sheet never grows unbounded. Turning **Enable logging** off stops new rows from being added; it doesn't delete what's already there.

## Related [#related]

<Cards>
  <Card title="Fetching Rankings" description="The run statuses that show up in the Logs sheet, explained." href="/rank-tracker/fetching-rankings" />

  <Card title="Understanding the Dashboard" description="The same underlying data, shown as today's snapshot." href="/rank-tracker/dashboard" />
</Cards>


# Yahoo APIs (/docs/yahoo-apis)



SERPHouse Yahoo APIs provide structured Yahoo search results for web, news, and images. Useful for multi-engine coverage and markets where Yahoo remains a primary search surface.

All endpoints require authentication → pass your API key as a Bearer token in the `Authorization` header.

## Endpoints [#endpoints]

<Cards>
  <Card title="Yahoo Search API" description="Full Yahoo SERP with organic results, ads, news, images, and more." href="/yahoo-apis/yahoo-search" />

  <Card title="Yahoo News API" description="Latest headlines and breaking stories from Yahoo News." href="/yahoo-apis/yahoo-news-api" />

  <Card title="Yahoo Image API" description="Yahoo image search for image discovery." href="/yahoo-apis/yahoo-image-api" />
</Cards>

## Related [#related]

<Cards>
  <Card title="Getting Started" href="/getting-started" />

  <Card title="Domains List" href="/extra-apis/domains-list" />

  <Card title="Languages List" href="/extra-apis/languages-list" />
</Cards>


# Yahoo Image API (/docs/yahoo-apis/yahoo-image-api)





Fetch real-time image search results from Yahoo, enabling seamless access to images from a wide range of online sources.

<Callout type="warn">
  Requires authentication → provide your API key as a Bearer token in the
  Authorization header.
</Callout>

`POST` `https://api.serphouse.com/yahoo-image`

<Callout type="info" title="Response types">
  These are the response types we support. Append a suffix to the endpoint to
  choose the response format.
</Callout>

| Format         | Endpoint                                     |
| -------------- | -------------------------------------------- |
| JSON (default) | `https://api.serphouse.com/yahoo-image`      |
| Markdown       | `https://api.serphouse.com/yahoo-image/md`   |
| HTML           | `https://api.serphouse.com/yahoo-image/html` |

## Headers [#headers]

| Name                                                           | Type   | Description             |
| -------------------------------------------------------------- | ------ | ----------------------- |
| Authorization <span style="{color: &#x22;red&#x22;}">\*</span> | String | Bearer `<YOUR_API_KEY>` |
| Content-Type <span style="{color: &#x22;red&#x22;}">\*</span>  | String | application/json        |

## Request Body [#request-body]

| Name                                                    | Type              | Description                                                                                                                                                                                         |
| ------------------------------------------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| q <span style="{color: &#x22;red&#x22;}">\*</span>      | string            | Search phrase that you want to search                                                                                                                                                               |
| domain <span style="{color: &#x22;red&#x22;}">\*</span> | string            | Choose yahoo domain (e.g. `in.yahoo.com`).<br /><br />You can retrieve the list of supported Yahoo domains by making a separate request to the [Domains List](/extra-apis/domains-list)             |
| lang <span style="{color: &#x22;red&#x22;}">\*</span>   | string            | You can set language for e.g. `lang_en` for english `lang_fr` for french.<br />Get the list of available languages by making a separate request to the [Languages List](/extra-apis/languages-list) |
| page                                                    | integer           | Give specific page to get the result of that page number. By default it will get you first page.                                                                                                    |
| no\_trace                                               | string \| integer | Enterprise only. Enables NoTrace mode. Accepted values: `0`, `1`, `true`, and `false`. When enabled (`1` or `true`), search parameters, files, and metadata are not stored on our servers.          |

<Callout type="info">
  Yahoo requires regional domains → browse the [Domains
  List](/extra-apis/domains-list) to find the right domain for your target
  region. <code>yahoo.com</code> is not valid.
</Callout>

<VisualRef title="Yahoo Image API" src="/images/yahoo/yahoo-image-api.png" alt="Yahoo image search results" />

## Example Request [#example-request]

<ApiExample endpoint="https://api.serphouse.com/yahoo-image" query="sunset beach" domain="de.yahoo.com" lang="lang_en" params="{&#x22;page&#x22;: 1}" />

## Example Response [#example-response]

<ApiExample mode="response">
  <ApiTab label="JSON" response="yahooImageJsonResponse" />

  <ApiTab label="Markdown" response="yahooImageMarkdownResponse" lang="markdown" />
</ApiExample>

## Related Links [#related-links]

<Cards>
  <Card title="Yahoo Search API" href="/yahoo-apis/yahoo-search" />

  <Card title="Yahoo News API" href="/yahoo-apis/yahoo-news-api" />
</Cards>


# Yahoo News API (/docs/yahoo-apis/yahoo-news-api)





Retrieve real-time news results from the Yahoo News search page, providing access to the latest headlines, breaking news, and stories from trusted publishers.

<Callout type="warn">
  Requires authentication → provide your API key as a Bearer token in the
  Authorization header.
</Callout>

`POST` `https://api.serphouse.com/yahoo-news`

<Callout type="info" title="Response types">
  These are the response types we support. Append a suffix to the endpoint to
  choose the response format.
</Callout>

| Format         | Endpoint                                    |
| -------------- | ------------------------------------------- |
| JSON (default) | `https://api.serphouse.com/yahoo-news`      |
| Markdown       | `https://api.serphouse.com/yahoo-news/md`   |
| HTML           | `https://api.serphouse.com/yahoo-news/html` |

## Headers [#headers]

| Name                                                           | Type   | Description             |
| -------------------------------------------------------------- | ------ | ----------------------- |
| Authorization <span style="{color: &#x22;red&#x22;}">\*</span> | String | Bearer `<YOUR_API_KEY>` |
| Content-Type <span style="{color: &#x22;red&#x22;}">\*</span>  | String | application/json        |

## Request Body [#request-body]

| Name                                                    | Type              | Description                                                                                                                                                                                         |
| ------------------------------------------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| q <span style="{color: &#x22;red&#x22;}">\*</span>      | string            | Search phrase that you want to search                                                                                                                                                               |
| domain <span style="{color: &#x22;red&#x22;}">\*</span> | string            | Choose yahoo domain (e.g. `in.yahoo.com`).<br /><br />You can retrieve the list of supported Yahoo domains by making a separate request to the [Domains List](/extra-apis/domains-list)             |
| lang <span style="{color: &#x22;red&#x22;}">\*</span>   | string            | You can set language for e.g. `lang_en` for english `lang_fr` for french.<br />Get the list of available languages by making a separate request to the [Languages List](/extra-apis/languages-list) |
| device <span style="{color: &#x22;red&#x22;}">\*</span> | string            | `desktop` To extract desktop result `mobile` To extract mobile result                                                                                                                               |
| page                                                    | integer           | Give specific page to get the result of that page number. By default it will get you first page.                                                                                                    |
| no\_trace                                               | string \| integer | Enterprise only. Enables NoTrace mode. Accepted values: `0`, `1`, `true`, and `false`. When enabled (`1` or `true`), search parameters, files, and metadata are not stored on our servers.          |

<Callout type="info">
  Yahoo requires regional domains → browse the [Domains
  List](/extra-apis/domains-list) to find the right domain for your target
  region. <code>yahoo.com</code> is not valid.
</Callout>

<VisualRef title="Yahoo News API" src="/images/yahoo/yahoo-news-api.png" alt="Yahoo news search results" />

## Example Request [#example-request]

<ApiExample endpoint="https://api.serphouse.com/yahoo-news" query="tesla in india" domain="in.yahoo.com" lang="lang_en" params="{&#x22;device&#x22;: &#x22;desktop&#x22;}" />

## Example Response [#example-response]

<ApiExample mode="response">
  <ApiTab label="JSON" response="yahooNewsJsonResponse" />

  <ApiTab label="Markdown" response="yahooNewsMarkdownResponse" lang="markdown" />
</ApiExample>

## Related Links [#related-links]

<Cards>
  <Card title="Yahoo Search API" href="/yahoo-apis/yahoo-search" />

  <Card title="Yahoo Image API" href="/yahoo-apis/yahoo-image-api" />
</Cards>


# AI Overview (/docs/google-apis/google-search/ai-overview)





Access Google's AI-generated summaries (SGE) directly from search results, providing the full AI overview text and source citations in structured JSON.

<Callout type="warn">
  Requires authentication → provide your API key as a Bearer token in the
  Authorization header.
</Callout>

`POST` `https://api.serphouse.com/google-web`

## Response [#response]

The AI Overview appears in the `ai_overview` field within the response results. It includes the AI-generated summary text and the sources cited.

| Field      | Type   | Description                               |
| ---------- | ------ | ----------------------------------------- |
| title      | string | AI Overview title                         |
| contents   | array  | Text blocks of the AI-generated summary   |
| references | array  | Cited sources with URL, source, and title |

## Example Request [#example-request]

<ApiExample endpoint="https://api.serphouse.com/google-web" query="how to create app" params="{&#x22;device&#x22;: &#x22;desktop&#x22;, &#x22;loc&#x22;: &#x22;New York,United States&#x22;}" />

<VisualRef title="Google AI Overview" src="/images/google-api/ai-overview.png" alt="Google AI Overview result in search results" />

<ApiExample mode="response" response="ai_overview" />

## Related Links [#related-links]

<Cards>
  <Card title="Google Search API" href="/google-apis/google-search" />

  <Card title="Google Organic" href="/google-apis/google-search/organic" />

  <Card title="Google People Also Ask" href="/google-apis/google-search/people-ask-for" />
</Cards>


# Carousel (/docs/google-apis/google-search/carousal)





Access Google's horizontal carousel results that showcase media, events, or entities in an interactive scrollable format within search results.

<Callout type="warn">
  Requires authentication → provide your API key as a Bearer token in the
  Authorization header.
</Callout>

`POST` `https://api.serphouse.com/google-web`

## Response [#response]

Carousel results appear in the `carousel` field within the response results. Each entry contains a carousel item with title, link, and image.

| Field      | Type    | Description                    |
| ---------- | ------- | ------------------------------ |
| position   | integer | Position in the carousel       |
| title      | string  | Item title                     |
| link       | string  | Google search URL for the item |
| image\_url | string  | Item thumbnail image           |

## Example Request [#example-request]

<ApiExample endpoint="https://api.serphouse.com/google-web" query="bollywood movies" params="{&#x22;device&#x22;: &#x22;desktop&#x22;, &#x22;loc&#x22;: &#x22;United States&#x22;}" />

<VisualRef title="Google Carousel" src="/images/google-api/google-carousel-results-desktop.png" alt="Google Carousel in search results" />

<ApiExample mode="response" response="google_carsoule" />

## Related Links [#related-links]

<Cards>
  <Card title="Google Search API" href="/google-apis/google-search" />

  <Card title="Google Inline Images" href="/google-apis/google-search/inline-image" />

  <Card title="Google Top Stories" href="/google-apis/google-search/top-stories" />
</Cards>


# Ads (/docs/google-apis/google-search/google-ads)





Access paid advertisement listings from Google search results, including top and bottom ad placements with sitelinks and extensions.

<Callout type="warn">
  Requires authentication → provide your API key as a Bearer token in the
  Authorization header.
</Callout>

`POST` `https://api.serphouse.com/google-web`

## Response [#response]

Paid ads appear in the `ads` field within the response results. Each ad entry includes position, title, description, source, and optional sitelinks.

| Field           | Type    | Description                         |
| --------------- | ------- | ----------------------------------- |
| position        | integer | Ad ranking position                 |
| block\_position | string  | `top` or `bottom` placement         |
| title           | string  | Ad headline                         |
| link            | string  | Destination URL                     |
| displayed\_link | string  | Displayed URL for the advertisement |
| description     | string  | Ad description text                 |
| source          | string  | Advertiser name                     |
| sitelinks       | array   | Additional sitelink extensions      |

## Example Request [#example-request]

<ApiExample endpoint="https://api.serphouse.com/google-web" query="bluehost" params="{&#x22;device&#x22;: &#x22;desktop&#x22;, &#x22;loc&#x22;: &#x22;Ahmedabad,Gujarat,India&#x22;}" />

<VisualRef title="Google Ads" src="/images/google-api/ads-image.png" alt="Google Ads in search results" />

<ApiExample mode="response" response="google_ads" />

## Related Links [#related-links]

<Cards>
  <Card title="Google Search API" href="/google-apis/google-search" />

  <Card title="Google Organic" href="/google-apis/google-search/organic" />

  <Card title="Google Inline Product" href="/google-apis/google-search/inline-product" />
</Cards>


# Google Search (/docs/google-apis/google-search)





Access Google's search results in real time, providing relevant web pages, search listings, and content from across the internet.

<Callout type="warn">
  Requires authentication → provide your API key as a Bearer token in the
  Authorization header.
</Callout>

`POST` `https://api.serphouse.com/google-web`

<Callout type="info" title="Response types">
  These are the response types we support. Append a suffix to the endpoint to
  choose the response format.
</Callout>

| Format         | Endpoint                                    |
| -------------- | ------------------------------------------- |
| JSON (default) | `https://api.serphouse.com/google-web`      |
| Markdown       | `https://api.serphouse.com/google-web/md`   |
| HTML           | `https://api.serphouse.com/google-web/html` |

## Headers [#headers]

| Name                                                           | Type   | Description             |
| -------------------------------------------------------------- | ------ | ----------------------- |
| Authorization <span style="{color: &#x22;red&#x22;}">\*</span> | String | Bearer `<YOUR_API_KEY>` |
| Content-Type <span style="{color: &#x22;red&#x22;}">\*</span>  | String | application/json        |

## Request Body [#request-body]

| Name                                                     | Type              | Description                                                                                                                                                                                                                                                                                                                |
| -------------------------------------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| q <span style="{color: &#x22;red&#x22;}">\*</span>       | string            | Search phrase that you want to search                                                                                                                                                                                                                                                                                      |
| domain <span style="{color: &#x22;red&#x22;}">\*</span>  | string            | Choose google domain.<br /><br />You can retrieve the list of supported Google domains by making a separate request to the [Domains List](/extra-apis/domains-list)                                                                                                                                                        |
| device <span style="{color: &#x22;red&#x22;}">\*</span>  | string            | `desktop` To extract desktop result `mobile` To extract mobile result                                                                                                                                                                                                                                                      |
| lang <span style="{color: &#x22;red&#x22;}">\*</span>    | string            | You can set language for e.g. `en` for english `fr` for french.<br />Get the list of available languages by making a separate request to the [Languages List](/extra-apis/languages-list)                                                                                                                                  |
| loc <span style="{color: &#x22;red&#x22;}">\*</span>     | string            | Optional field if you specify `loc_id`<br />&#x2A;*You must choose one of the fields: `loc_id` or `loc`**<br />You can receive the list of available locations of search engines with their loc\_id by making a separate request to the [Locations List](/extra-apis/locations-list)                                       |
| loc\_id <span style="{color: &#x22;red&#x22;}">\*</span> | integer           | Optional field if you specify `loc`<br />&#x2A;*You must choose one of the fields: `loc_id` or `loc`**<br />You can receive the list of available locations of search engines with their loc\_id by making a separate request to the [Locations List](/extra-apis/locations-list)                                          |
| page                                                     | integer           | Give specific page to get the result of that page number. By default it will get you first page.                                                                                                                                                                                                                           |
| date\_range                                              | String            | Sometimes you may want to only find information published during a specific time frame. To limit Google results by date<br /><br />Parameter values can be comma separated date range `YYYY-MM-DD,YYYY-MM-DD` OR<br /><br />`h` Past hour<br />`d` Past 24 hours<br />`w` Past week<br />`m` Past month<br />`y` Past year |
| verbatim                                                 | integer           | Set Google Verbatim search, Parameter value can be `0` or `1`                                                                                                                                                                                                                                                              |
| gfilter                                                  | integer           | `1` (default) to enable filters, `0` to disable                                                                                                                                                                                                                                                                            |
| num\_result                                              | integer           | Number of results per page (1–10)                                                                                                                                                                                                                                                                                          |
| no\_trace                                                | string \| integer | Enterprise only. Enables NoTrace mode. Accepted values: `0`, `1`, `true`, and `false`. When enabled (`1` or `true`), search parameters, files, and metadata are not stored on our servers.                                                                                                                                 |

## Response [#response]

<Callout type="info">
  Returns structured JSON with search metadata, parameters, and results
  including organic listings, local pack, and inline shopping.
</Callout>

<VisualRef title="Google Search API" src="/images/google/google-search-api.png" alt="Google search results" />

## Example Request [#example-request]

<ApiExample endpoint="https://api.serphouse.com/google-web" query="how to create app" params="{&#x22;device&#x22;: &#x22;desktop&#x22;, &#x22;loc&#x22;: &#x22;New York,United States&#x22;}" />

## Example Response [#example-response]

<ApiExample mode="response">
  <ApiTab label="JSON" response="googleSearchApiJsonResponse" />

  <ApiTab label="Markdown" response="googleSearchApiMarkdownResponse" lang="markdown" />
</ApiExample>

## Related Links [#related-links]

<Cards>
  <Card title="Google News API" href="/google-apis/google-news-api" />

  <Card title="Google Image API" href="/google-apis/google-image-api" />

  <Card title="Google Lite Web Search API" href="/google-apis/google-lite-web-search-api" />
</Cards>


# Inline Images (/docs/google-apis/google-search/inline-image)





Access Google's inline image results within web search responses, perfect for building image galleries or enhancing applications with relevant visuals.

<Callout type="warn">
  Requires authentication → provide your API key as a Bearer token in the
  Authorization header.
</Callout>

`POST` `https://api.serphouse.com/google-web`

## Response [#response]

Inline images appear in the `inline_images` field within the response results. Each entry contains the image data.

| Field | Type   | Description                                                                                               |
| ----- | ------ | --------------------------------------------------------------------------------------------------------- |
| image | string | The image field may contain either a Base64-encoded image (`src:BASE64...`) or a regular HTTPS image URL. |

## Example Request [#example-request]

<ApiExample endpoint="https://api.serphouse.com/google-web" query="Red apple" params="{&#x22;device&#x22;: &#x22;desktop&#x22;, &#x22;loc&#x22;: &#x22;United States&#x22;}" />

<VisualRef title="Google Inline Images" src="/images/google-api/google-inline-images-results-desktop.png" alt="Google Inline Images in search results" />

<ApiExample mode="response" response="inline_image" />

## Related Links [#related-links]

<Cards>
  <Card title="Google Search API" href="/google-apis/google-search" />

  <Card title="Google Image API" href="/google-apis/google-image-api" />

  <Card title="Google Inline Video" href="/google-apis/google-search/inline-video" />
</Cards>


# Inline Product (/docs/google-apis/google-search/inline-product)





Access Google's inline shopping results that appear within web search, showing product listings with prices, ratings, and merchant information.

<Callout type="warn">
  Requires authentication → provide your API key as a Bearer token in the
  Authorization header.
</Callout>

`POST` `https://api.serphouse.com/google-web`

## Response [#response]

Inline shopping results appear in the `shopping` field within the response results. Each entry contains product details.

| Field           | Type    | Description                      |
| --------------- | ------- | -------------------------------- |
| rank            | integer | Product ranking position         |
| title           | string  | Product name                     |
| link            | string  | Product purchase URL             |
| image           | string  | Product image URL or Base64 data |
| price           | string  | Product price                    |
| unit\_price     | string  | Price per unit                   |
| old\_price      | string  | Original price                   |
| shipping\_price | string  | Shipping cost                    |
| rating          | string  | Product rating                   |
| tags            | string  | Promotional tags                 |
| shop            | string  | Merchant name                    |

## Example Request [#example-request]

<ApiExample endpoint="https://api.serphouse.com/google-web" query="buy apple laptop" params="{&#x22;device&#x22;: &#x22;desktop&#x22;, &#x22;loc&#x22;: &#x22;India&#x22;}" />

<VisualRef title="Google Inline Products" src="/images/google-api/google-inline-products-results-desktop.png" alt="Google Inline Products in search results" />

<ApiExample mode="response" response="inline_product" />

## Related Links [#related-links]

<Cards>
  <Card title="Google Search API" href="/google-apis/google-search" />

  <Card title="Google Shopping API" href="/google-apis/google-shopping-api" />

  <Card title="Google Ads" href="/google-apis/google-search/google-ads" />
</Cards>


# Inline Videos (/docs/google-apis/google-search/inline-video)





Access Google video results embedded within web search responses, surfacing relevant video content from YouTube and other sources.

<Callout type="warn">
  Requires authentication → provide your API key as a Bearer token in the
  Authorization header.
</Callout>

`POST` `https://api.serphouse.com/google-web`

## Response [#response]

Inline videos appear in the `inline_videos` field within the response results. Each entry contains video metadata, source, and date details.

| Field   | Type   | Description                          |
| ------- | ------ | ------------------------------------ |
| title   | string | Video title                          |
| url     | string | Video URL or relative fragment link. |
| channel | string | Publisher or channel name            |
| source  | string | Video source (e.g., YouTube).        |
| date    | string | Published date.                      |

## Example Request [#example-request]

<ApiExample endpoint="https://api.serphouse.com/google-web" query="how to create app" params="{&#x22;device&#x22;: &#x22;desktop&#x22;, &#x22;loc&#x22;: &#x22;New York,United States&#x22;}" />

<VisualRef title="Google Inline Videos" src="/images/google-api/inline-videos-image.png" alt="Google Inline Video in search results" />

<ApiExample mode="response" response="inline_video" />

## Related Links [#related-links]

<Cards>
  <Card title="Google Search API" href="/google-apis/google-search" />

  <Card title="Google Videos API" href="/google-apis/google-videos-api" />

  <Card title="Google Inline Images" href="/google-apis/google-search/inline-image" />
</Cards>


# Inline Shopping (/docs/google-apis/google-search/inline_shopping)





Access Google's inline shopping results that appear within web search, showing product listings with prices, ratings, and merchant information.

<Callout type="warn">
  Requires authentication → provide your API key as a Bearer token in the
  Authorization header.
</Callout>

`POST` `https://api.serphouse.com/google-web`

## Response [#response]

Inline shopping results appear in the `inline_shopping` field within the response results. Each entry contains the following fields:

| Field  | Type    | Description                          |
| ------ | ------- | ------------------------------------ |
| rank   | integer | Product ranking position             |
| title  | string  | Product name                         |
| link   | string  | Product purchase URL                 |
| image  | string  | Product image URL or Base64 data     |
| price  | string  | Product price                        |
| rating | string  | Product rating or review information |
| shop   | string  | Merchant name                        |

## Example Request [#example-request]

<ApiExample endpoint="https://api.serphouse.com/google-web" query="Buy headphones" params="{&#x22;device&#x22;: &#x22;desktop&#x22;, &#x22;loc&#x22;: &#x22;Surat,Gujarat,India&#x22;}" />

<VisualRef title="Google Inline Shopping" src="/images/google-api/inline-shopping-image.png" alt="Google Inline Shopping results in search" />

<ApiExample mode="response" response="inline_shopping" />

## Related Links [#related-links]

<Cards>
  <Card title="Google Search API" href="/google-apis/google-search" />

  <Card title="Google Shopping API" href="/google-apis/google-shopping-api" />

  <Card title="Google Inline Product" href="/google-apis/google-search/inline-product" />
</Cards>


# Knowledge Panel (/docs/google-apis/google-search/knowlege-pannel)





Access structured entity data from Google's Knowledge Graph, providing detailed information about people, places, organizations, and more.

<Callout type="warn">
  Requires authentication → provide your API key as a Bearer token in the
  Authorization header.
</Callout>

`POST` `https://api.serphouse.com/google-web`

## Response [#response]

The Knowledge Panel appears in the `knowledge_card` field within the response results. It contains structured entity information including name, description, image, and key attributes.

| Field       | Type   | Description                          |
| ----------- | ------ | ------------------------------------ |
| title       | string | Entity name                          |
| description | string | Entity description                   |
| image       | string | Entity image URL                     |
| source      | object | Source attribution details           |
| attributes  | array  | Key-value pairs of entity attributes |

## Example Request [#example-request]

<ApiExample endpoint="https://api.serphouse.com/google-web" query="narendra modi" params="{&#x22;device&#x22;: &#x22;desktop&#x22;, &#x22;loc&#x22;: &#x22;United States&#x22;}" />

<VisualRef title="Google Knowledge Panel" src="/images/google-api/knowledge-panel-image.png" alt="Google Knowledge Panel in search results" />

<ApiExample mode="response" response="knowlege_pannel" />

## Related Links [#related-links]

<Cards>
  <Card title="Google Search API" href="/google-apis/google-search" />

  <Card title="Google People Also Ask" href="/google-apis/google-search/people-ask-for" />

  <Card title="Google Organic" href="/google-apis/google-search/organic" />
</Cards>


# Local Business (/docs/google-apis/google-search/local-buisness)





Access local business listings from Google's Local Pack, providing business details like address, rating, reviews, and contact information.

<Callout type="warn">
  Requires authentication → provide your API key as a Bearer token in the
  Authorization header.
</Callout>

`POST` `https://api.serphouse.com/google-web`

## Response [#response]

Local business results appear in the `local_pack` field within the response results. Each entry contains business listing details.

| Field          | Type    | Description                        |
| -------------- | ------- | ---------------------------------- |
| position       | integer | Ranking position in the local pack |
| title          | string  | Business name                      |
| rating         | string  | Star rating                        |
| reviews\_count | string  | Number of reviews                  |
| type           | string  | Business category                  |
| address        | string  | Business address                   |
| open\_state    | string  | Open/closed status and hours       |
| url            | string  | Google Maps listing URL            |
| website        | string  | Business website                   |
| map\_url       | string  | Direct Google Maps URL             |

## Example Request [#example-request]

<ApiExample endpoint="https://api.serphouse.com/google-web" query="headphones shop near me" params="{&#x22;device&#x22;: &#x22;desktop&#x22;, &#x22;loc&#x22;: &#x22;Surat,Gujarat,India&#x22;}" />

<VisualRef title="Google Local Business" src="/images/google-api/local-business-image.png" alt="Google Local Business in search results" />

<ApiExample mode="response" response="local_buisness" />

## Related Links [#related-links]

<Cards>
  <Card title="Google Search API" href="/google-apis/google-search" />

  <Card title="Google Local API" href="/google-apis/google-local-api" />

  <Card title="Google Organic" href="/google-apis/google-search/organic" />
</Cards>


# Organic (/docs/google-apis/google-search/organic)





Access natural, non-paid search listings from Google's main search results, including title, URL, snippet, and position data.

<Callout type="warn">
  Requires authentication → provide your API key as a Bearer token in the
  Authorization header.
</Callout>

`POST` `https://api.serphouse.com/google-web`

## Response [#response]

Organic results appear in the `organic` field within the response results. Each entry contains standard search listing fields.

| Field              | Type    | Description                                                                                                                                         |
| ------------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| position           | integer | Ranking position on the page                                                                                                                        |
| title              | string  | Page title                                                                                                                                          |
| link               | string  | URL to the page                                                                                                                                     |
| displayed\_link    | string  | Displayed URL in search results                                                                                                                     |
| snippet            | string  | Page description or excerpt                                                                                                                         |
| site\_title        | string  | Source site name                                                                                                                                    |
| cached\_page       | string  | Link to cached version                                                                                                                              |
| snippet\_extension | array   | Additional snippet context                                                                                                                          |
| thumbnail          | string  | Thumbnail image if available                                                                                                                        |
| reviews            | object  | Contains review information, including `rated` (string) and `rating` (string). Returned when a review/rating block is present in the search result. |
| sitelinks          | object  | Contains sitelinks for the result. Includes two sub-keys: `inline` (array of `{link, title}`) and `expanded` (array of `{link, title}`).            |

## Example Request [#example-request]

<ApiExample endpoint="https://api.serphouse.com/google-web" query="how to create app" params="{&#x22;device&#x22;: &#x22;desktop&#x22;, &#x22;loc&#x22;: &#x22;New York,United States&#x22;}" />

<VisualRef title="Google Organic" src="/images/google-api/organic-image.png" alt="Google Organic search results" />

<ApiExample mode="response" response="oganic_result" />

## Related Links [#related-links]

<Cards>
  <Card title="Google Search API" href="/google-apis/google-search" />

  <Card title="Google Ads" href="/google-apis/google-search/google-ads" />

  <Card title="Google Related Searches" href="/google-apis/google-search/related-search" />
</Cards>


# People Also Ask (/docs/google-apis/google-search/people-ask-for)





Access the "People Also Ask" questions and answers that appear in Google search results, revealing related queries users frequently search for.

<Callout type="warn">
  Requires authentication → provide your API key as a Bearer token in the
  Authorization header.
</Callout>

`POST` `https://api.serphouse.com/google-web`

## Response [#response]

People Also Ask entries appear in the `people_also_ask` field within the response results. Each entry contains a question and its expandable answer.

| Field    | Type   | Description                   |
| -------- | ------ | ----------------------------- |
| question | string | The related question text     |
| answer   | string | The expandable answer snippet |

## Example Request [#example-request]

<ApiExample endpoint="https://api.serphouse.com/google-web" query="how to create app" params="{&#x22;device&#x22;: &#x22;desktop&#x22;, &#x22;loc&#x22;: &#x22;New York,United States&#x22;}" />

<VisualRef title="Google People Also Ask" src="/images/google-api/people-also-ask-image.png" alt="Google People Also Ask in search results" />

<ApiExample mode="response" response="People_also_ask" />

## Related Links [#related-links]

<Cards>
  <Card title="Google Search API" href="/google-apis/google-search" />

  <Card title="Google Related Searches" href="/google-apis/google-search/related-search" />

  <Card title="Google Knowledge Panel" href="/google-apis/google-search/knowlege-pannel" />
</Cards>


# Related Searches (/docs/google-apis/google-search/related-search)





Retrieve Google's related search suggestions that appear at the bottom of search results, helping users discover connected topics.

<Callout type="warn">
  Requires authentication → provide your API key as a Bearer token in the
  Authorization header.
</Callout>

`POST` `https://api.serphouse.com/google-web`

## Response [#response]

Related searches appear in the `related_search` field within the response results. Each entry contains a suggested search phrase and its URL.

| Field | Type   | Description                          |
| ----- | ------ | ------------------------------------ |
| title | string | Suggested search phrase              |
| link  | string | Google search URL for the suggestion |

## Example Request [#example-request]

<ApiExample endpoint="https://api.serphouse.com/google-web" query="how to create app" params="{&#x22;device&#x22;: &#x22;desktop&#x22;, &#x22;loc&#x22;: &#x22;New York,United States&#x22;}" />

<VisualRef title="Google Related Searches" src="/images/google-api/related-searches-image.png" alt="Google Related Searches in search results" />

<ApiExample mode="response" response="related_search" />

## Related Links [#related-links]

<Cards>
  <Card title="Google Search API" href="/google-apis/google-search" />

  <Card title="Google People Also Ask" href="/google-apis/google-search/people-ask-for" />

  <Card title="Google Organic" href="/google-apis/google-search/organic" />
</Cards>


# Top Stories (/docs/google-apis/google-search/top-stories)





Retrieve the latest breaking news and headline stories directly from Google search results using the Top Stories result type.

<Callout type="warn">
  Requires authentication → provide your API key as a Bearer token in the
  Authorization header.
</Callout>

`POST` `https://api.serphouse.com/google-web`

## Response [#response]

Top Stories appear in the `top_stories` field within the response results. Each entry contains the article title, link, and image.

| Field | Type   | Description                  |
| ----- | ------ | ---------------------------- |
| title | string | Headline of the news article |
| link  | string | Link to the full article     |
| image | string | Thumbnail image (base64)     |

## Example Request [#example-request]

<ApiExample endpoint="https://api.serphouse.com/google-web" query="narendra modi" params="{&#x22;device&#x22;: &#x22;desktop&#x22;, &#x22;loc&#x22;: &#x22;United States&#x22;}" />

<VisualRef title="Google Top Stories" src="/images/google-api/top-stories-image.png" alt="Google Top Stories in search results" />

<ApiExample mode="response" response="top_stories" />

## Related Links [#related-links]

<Cards>
  <Card title="Google Search API" href="/google-apis/google-search" />

  <Card title="Google News API" href="/google-apis/google-news-api" />

  <Card title="Google Inline Images" href="/google-apis/google-search/inline-image" />
</Cards>


# Tweets (/docs/google-apis/google-search/twitter)





Access Twitter/X results that appear in Google search results, surfacing relevant tweets and social media content.

<Callout type="warn">
  Requires authentication → provide your API key as a Bearer token in the
  Authorization header.
</Callout>

`POST` `https://api.serphouse.com/google-web`

## Response [#response]

Twitter results appear in the `tweets` field within the response results. Each entry contains the tweet content, URL, and published date.

| Field           | Type   | Description          |
| --------------- | ------ | -------------------- |
| tweet           | string | Tweet content        |
| url             | string | Tweet URL            |
| published\_date | string | Tweet published date |

## Example Request [#example-request]

<ApiExample endpoint="https://api.serphouse.com/google-web" query="narendra modi" params="{&#x22;device&#x22;: &#x22;desktop&#x22;, &#x22;loc&#x22;: &#x22;United States&#x22;}" />

<VisualRef title="Google Tweets" src="/images/google-api/tweets-image.png" alt="Google Twitter results in search results" />

<ApiExample mode="response" response="google_twitter" />

## Related Links [#related-links]

<Cards>
  <Card title="Google Search API" href="/google-apis/google-search" />

  <Card title="Google Top Stories" href="/google-apis/google-search/top-stories" />

  <Card title="Google Organic" href="/google-apis/google-search/organic" />
</Cards>


# Ads (/docs/yahoo-apis/yahoo-search/ads)





Access paid advertisement listings from Yahoo search results, including top, bottom, and right bottom ad placements with sitelinks and extensions.

<Callout type="warn">
  Requires authentication → provide your API key as a Bearer token in the
  Authorization header.
</Callout>

`POST` `https://api.serphouse.com/yahoo-web`

## Response [#response]

Paid ads appear in the `ads` field within the response results. Each ad entry includes position, title, description, destination, and optional sitelinks.

| Field           | Type    | Description                                                               |
| --------------- | ------- | ------------------------------------------------------------------------- |
| position        | integer | Ad ranking position                                                       |
| block\_position | string  | Ad placement location (`top`, `bottom`, `rightbottom`)                    |
| title           | string  | Headline title of the advertisement                                       |
| link            | string  | Destination URL of the ad                                                 |
| display\_link   | string  | Displayed URL in the ad snippet                                           |
| description     | string  | Ad text description                                                       |
| sitelinks       | array   | Array of sitelink objects containing `title` (string) and `link` (string) |

## Example Request [#example-request]

<ApiExample endpoint="https://api.serphouse.com/yahoo-web" query="cloud hosting service" domain="fr.yahoo.com" lang="lang_en" params="{&#x22;device&#x22;: &#x22;desktop&#x22;}" />

<VisualRef title="Yahoo Ads" src="/images/yahoo-api/ads-image.png" alt="Yahoo Ads in search results" />

<ApiExample mode="response" response="yahoo_ads" />

## Related Links [#related-links]

<Cards>
  <Card title="Yahoo Search API" href="/yahoo-apis/yahoo-search" />

  <Card title="Yahoo Organic" href="/yahoo-apis/yahoo-search/organic" />

  <Card title="Yahoo Related Searches" href="/yahoo-apis/yahoo-search/related-search" />
</Cards>


# Yahoo Search (/docs/yahoo-apis/yahoo-search)





Access Yahoo's search results in real time, providing relevant web pages, search listings, and content from across the internet.

<Callout type="warn">
  Requires authentication → provide your API key as a Bearer token in the
  Authorization header.
</Callout>

`POST` `https://api.serphouse.com/yahoo-web`

<Callout type="info" title="Response types">
  These are the response types we support. Append a suffix to the endpoint to
  choose the response format.
</Callout>

| Format         | Endpoint                                   |
| -------------- | ------------------------------------------ |
| JSON (default) | `https://api.serphouse.com/yahoo-web`      |
| Markdown       | `https://api.serphouse.com/yahoo-web/md`   |
| HTML           | `https://api.serphouse.com/yahoo-web/html` |

## Headers [#headers]

| Name                                                           | Type   | Description             |
| -------------------------------------------------------------- | ------ | ----------------------- |
| Authorization <span style="{color: &#x22;red&#x22;}">\*</span> | String | Bearer `<YOUR_API_KEY>` |
| Content-Type <span style="{color: &#x22;red&#x22;}">\*</span>  | String | application/json        |

## Request Body [#request-body]

| Name                                                    | Type              | Description                                                                                                                                                                                         |
| ------------------------------------------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| q <span style="{color: &#x22;red&#x22;}">\*</span>      | string            | Search phrase that you want to search                                                                                                                                                               |
| domain <span style="{color: &#x22;red&#x22;}">\*</span> | string            | Choose yahoo domain (e.g. `fr.yahoo.com`).<br /><br />You can retrieve the list of supported Yahoo domains by making a separate request to the [Domains List](/extra-apis/domains-list)             |
| lang <span style="{color: &#x22;red&#x22;}">\*</span>   | string            | You can set language for e.g. `lang_en` for english `lang_fr` for french.<br />Get the list of available languages by making a separate request to the [Languages List](/extra-apis/languages-list) |
| device <span style="{color: &#x22;red&#x22;}">\*</span> | string            | `desktop` To extract desktop result `mobile` To extract mobile result                                                                                                                               |
| page                                                    | integer           | Give specific page to get the result of that page number. By default it will get you first page.                                                                                                    |
| no\_trace                                               | string \| integer | Enterprise only. Enables NoTrace mode. Accepted values: `0`, `1`, `true`, and `false`. When enabled (`1` or `true`), search parameters, files, and metadata are not stored on our servers.          |

<Callout type="info">
  Yahoo requires regional domains → browse the [Domains
  List](/extra-apis/domains-list) to find the right domain for your target
  region. <code>yahoo.com</code> is not valid.
</Callout>

## Response [#response]

<Callout type="info">
  Returns structured JSON with search metadata, parameters, and results
  including organic listings, ads, top stories, inline images and videos,
  knowledge panels, and related searches.
</Callout>

<VisualRef title="Yahoo Search API" src="/images/yahoo/yahoo-search-api.png" alt="Yahoo web search results" />

## Example Request [#example-request]

<ApiExample endpoint="https://api.serphouse.com/yahoo-web" query="cloud hosting service" domain="fr.yahoo.com" lang="lang_en" params="{&#x22;device&#x22;: &#x22;desktop&#x22;}" />

## Example Response [#example-response]

<ApiExample mode="response">
  <ApiTab label="JSON" response="yahooWebSearchJsonResponse" />

  <ApiTab label="Markdown" response="yahooWebSearchMarkdownResponse" lang="markdown" />
</ApiExample>

## Related Links [#related-links]

<Cards>
  <Card title="Yahoo News API" href="/yahoo-apis/yahoo-news-api" />

  <Card title="Yahoo Image API" href="/yahoo-apis/yahoo-image-api" />

  <Card title="Yahoo Organic" href="/yahoo-apis/yahoo-search/organic" />
</Cards>


# Inline Images (/docs/yahoo-apis/yahoo-search/inline-image)





Access Yahoo's inline image results within web search responses, perfect for building image galleries or enhancing applications with relevant visuals.

<Callout type="warn">
  Requires authentication → provide your API key as a Bearer token in the
  Authorization header.
</Callout>

`POST` `https://api.serphouse.com/yahoo-web`

## Response [#response]

Inline images appear in the `inline_image` field within the response results. Each entry contains the image data, source link, and description.

| Field | Type   | Description                                  |
| ----- | ------ | -------------------------------------------- |
| image | string | Image thumbnail URL                          |
| link  | string | Source link or reference URL                 |
| alt   | string | Alternative text or description of the image |

## Example Request [#example-request]

<ApiExample endpoint="https://api.serphouse.com/yahoo-web" query="Narendra Modi" domain="in.yahoo.com" lang="lang_en" params="{&#x22;device&#x22;: &#x22;desktop&#x22;}" />

<VisualRef title="Yahoo Inline Images" src="/images/yahoo-api/inline-image.png" alt="Yahoo Inline Images in search results" />

<ApiExample mode="response" response="yahoo_inline_image" />

## Related Links [#related-links]

<Cards>
  <Card title="Yahoo Search API" href="/yahoo-apis/yahoo-search" />

  <Card title="Yahoo Image API" href="/yahoo-apis/yahoo-image-api" />

  <Card title="Yahoo Inline Videos" href="/yahoo-apis/yahoo-search/inline-videos" />
</Cards>


# Inline Videos (/docs/yahoo-apis/yahoo-search/inline-videos)





Access Yahoo video results embedded within web search responses, surfacing relevant video content from YouTube and other sources.

<Callout type="warn">
  Requires authentication → provide your API key as a Bearer token in the
  Authorization header.
</Callout>

`POST` `https://api.serphouse.com/yahoo-web`

## Response [#response]

Inline videos appear in the `inline_videos` field within the response results. Each entry contains video metadata, source, and date details.

| Field   | Type   | Description                       |
| ------- | ------ | --------------------------------- |
| title   | string | Title of the video                |
| source  | string | Source platform or website domain |
| channel | string | Channel name or publisher         |
| url     | string | Direct link to watch the video    |
| date    | string | Publication date or time snippet  |

## Example Request [#example-request]

<ApiExample endpoint="https://api.serphouse.com/yahoo-web" query="Narendra Modi" domain="in.yahoo.com" lang="lang_en" params="{&#x22;device&#x22;: &#x22;desktop&#x22;}" />

<VisualRef title="Yahoo Inline Videos" src="/images/yahoo-api/inline-videos-image.png" alt="Yahoo Inline Video in search results" />

<ApiExample mode="response" response="yahoo_inline_videos" />

## Related Links [#related-links]

<Cards>
  <Card title="Yahoo Search API" href="/yahoo-apis/yahoo-search" />

  <Card title="Yahoo News API" href="/yahoo-apis/yahoo-news-api" />

  <Card title="Yahoo Inline Images" href="/yahoo-apis/yahoo-search/inline-image" />
</Cards>


# Knowledge Card (/docs/yahoo-apis/yahoo-search/knowledge-card)





Access structured entity data from Yahoo's Knowledge Card, providing detailed information about people, places, organizations, and more.

<Callout type="warn">
  Requires authentication → provide your API key as a Bearer token in the
  Authorization header.
</Callout>

`POST` `https://api.serphouse.com/yahoo-web`

## Response [#response]

The Knowledge Card appears in the `knowledge_card` field within the response results. It contains structured entity information including name, tagline, description, and key attributes.

| Field           | Type   | Description                                                                   |
| --------------- | ------ | ----------------------------------------------------------------------------- |
| title           | string | Main title of the knowledge card                                              |
| tag\_line       | string | Subtitle, category, or tagline                                                |
| info            | string | Overview description summary                                                  |
| images          | array  | Array of image objects containing `image` (string) and `link` (string)        |
| movies\_tvshows | array  | Array of related works containing `title`, `subtitle`, `image`, and `link`    |
| social\_links   | array  | Array of social profile links containing `title` (string) and `link` (string) |
| attribute       | string | Dynamic key-value metadata facts (e.g. `born`, `spouse`, `net_worth`, etc.)   |

## Example Request [#example-request]

<ApiExample endpoint="https://api.serphouse.com/yahoo-web" query="Narendra Modi" domain="in.yahoo.com" lang="lang_en" params="{&#x22;device&#x22;: &#x22;desktop&#x22;}" />

<VisualRef title="Yahoo Knowledge Card" src="/images/yahoo-api/knowledge-card-image.png" alt="Yahoo Knowledge Card in search results" />

<ApiExample mode="response" response="yahoo_knowledge_card" />

## Related Links [#related-links]

<Cards>
  <Card title="Yahoo Search API" href="/yahoo-apis/yahoo-search" />

  <Card title="Yahoo People Also Ask" href="/yahoo-apis/yahoo-search/people-also-ask" />

  <Card title="Yahoo Organic" href="/yahoo-apis/yahoo-search/organic" />
</Cards>


# Organic (/docs/yahoo-apis/yahoo-search/organic)





Access natural, non-paid search listings from Yahoo's main search results, including title, URL, snippet, and position data.

<Callout type="warn">
  Requires authentication → provide your API key as a Bearer token in the
  Authorization header.
</Callout>

`POST` `https://api.serphouse.com/yahoo-web`

## Response [#response]

Organic results appear in the `organic` field within the response results. Each entry contains standard search listing fields.

| Field         | Type    | Description                     |
| ------------- | ------- | ------------------------------- |
| position      | integer | Ranking position on the page    |
| title         | string  | Page title                      |
| link          | string  | URL to the page                 |
| display\_link | string  | Displayed URL in search results |
| snippet       | string  | Page description or snippet     |

## Example Request [#example-request]

<ApiExample endpoint="https://api.serphouse.com/yahoo-web" query="Narendra Modi" domain="in.yahoo.com" lang="lang_en" params="{&#x22;device&#x22;: &#x22;desktop&#x22;}" />

<VisualRef title="Yahoo Organic" src="/images/yahoo-api/organic-image.png" alt="Yahoo Organic search results" />

<ApiExample mode="response" response="yahoo_organic" />

## Related Links [#related-links]

<Cards>
  <Card title="Yahoo Search API" href="/yahoo-apis/yahoo-search" />

  <Card title="Yahoo Ads" href="/yahoo-apis/yahoo-search/ads" />

  <Card title="Yahoo Related Searches" href="/yahoo-apis/yahoo-search/related-search" />
</Cards>


# People Also Ask (/docs/yahoo-apis/yahoo-search/people-also-ask)





Access the "People Also Ask" questions and answers that appear in Yahoo search results, revealing related queries users frequently search for.

<Callout type="warn">
  Requires authentication → provide your API key as a Bearer token in the
  Authorization header.
</Callout>

`POST` `https://api.serphouse.com/yahoo-web`

## Response [#response]

People Also Ask entries appear in the `people_also_ask` field within the response results. Each entry contains a question and its expandable answer.

| Field     | Type   | Description                 |
| --------- | ------ | --------------------------- |
| question  | string | Question text               |
| answer    | string | Answer snippet excerpt      |
| reference | string | Source name or domain title |
| link      | string | URL of the answer source    |

## Example Request [#example-request]

<ApiExample endpoint="https://api.serphouse.com/yahoo-web" query="how to get rid of fruit flies" domain="us.yahoo.com" lang="lang_en" params="{&#x22;device&#x22;: &#x22;desktop&#x22;}" />

<VisualRef title="Yahoo People Also Ask" src="/images/yahoo-api/people-also-ask-image.png" alt="Yahoo People Also Ask in search results" />

<ApiExample mode="response" response="yahoo_people_also_ask" />

## Related Links [#related-links]

<Cards>
  <Card title="Yahoo Search API" href="/yahoo-apis/yahoo-search" />

  <Card title="Yahoo Related Searches" href="/yahoo-apis/yahoo-search/related-search" />

  <Card title="Yahoo Knowledge Card" href="/yahoo-apis/yahoo-search/knowledge-card" />
</Cards>


# Related Searches (/docs/yahoo-apis/yahoo-search/related-search)





Retrieve Yahoo's related search suggestions that appear at the bottom of search results, helping users discover connected topics.

<Callout type="warn">
  Requires authentication → provide your API key as a Bearer token in the
  Authorization header.
</Callout>

`POST` `https://api.serphouse.com/yahoo-web`

## Response [#response]

Related searches appear in the `related_search` field within the response results. Each entry contains a suggested search phrase and its URL.

| Field | Type   | Description                      |
| ----- | ------ | -------------------------------- |
| title | string | Related query text               |
| link  | string | Search URL for the related query |

## Example Request [#example-request]

<ApiExample endpoint="https://api.serphouse.com/yahoo-web" query="Narendra Modi" domain="in.yahoo.com" lang="lang_en" params="{&#x22;device&#x22;: &#x22;desktop&#x22;}" />

<VisualRef title="Yahoo Related Searches" src="/images/yahoo-api/related-searches-image.png" alt="Yahoo Related Searches in search results" />

<ApiExample mode="response" response="yahoo_related_search" />

## Related Links [#related-links]

<Cards>
  <Card title="Yahoo Search API" href="/yahoo-apis/yahoo-search" />

  <Card title="Yahoo People Also Ask" href="/yahoo-apis/yahoo-search/people-also-ask" />

  <Card title="Yahoo Organic" href="/yahoo-apis/yahoo-search/organic" />
</Cards>


# Top Stories (/docs/yahoo-apis/yahoo-search/top-stories)





Retrieve the latest breaking news and headline stories directly from Yahoo search results using the Top Stories result type.

<Callout type="warn">
  Requires authentication → provide your API key as a Bearer token in the
  Authorization header.
</Callout>

`POST` `https://api.serphouse.com/yahoo-web`

## Response [#response]

Top Stories appear in the `top_stories` field within the response results. Each entry contains the article title, link, and image.

| Field | Type   | Description                        |
| ----- | ------ | ---------------------------------- |
| title | string | News article headline              |
| link  | string | URL to the news article            |
| image | string | Thumbnail image URL of the article |

## Example Request [#example-request]

<ApiExample endpoint="https://api.serphouse.com/yahoo-web" query="Narendra Modi" domain="in.yahoo.com" lang="lang_en" params="{&#x22;device&#x22;: &#x22;desktop&#x22;}" />

<VisualRef title="Yahoo Top Stories" src="/images/yahoo-api/top-stories-image.png" alt="Yahoo Top Stories in search results" />

<ApiExample mode="response" response="yahoo_top_stories" />

## Related Links [#related-links]

<Cards>
  <Card title="Yahoo Search API" href="/yahoo-apis/yahoo-search" />

  <Card title="Yahoo News API" href="/yahoo-apis/yahoo-news-api" />

  <Card title="Yahoo Inline Images" href="/yahoo-apis/yahoo-search/inline-image" />
</Cards>