# SerpPortal

> SerpPortal sells two products: (1) a self-hosted Google SERP API with SerpApi-compatible output, always-on AI Overview capture, SERP-feature detection, a serpupdate.com-compatible batch Datasets API, and an MCP server so AI agents can search the web as a tool; (2) rotating Vietnamese residential proxies on fibre lines we operate ourselves, sold per key per day. Both are paid from one credit balance (SePay / VietQR). SEO rank tracking (keyword campaigns, ranking history, Share of Voice) is a separate product at https://serpupdate.com/ and is not part of SerpPortal.

## Product

- [Home](https://serp.hoangha.shop/): Product overview and feature highlights.
- [Free SERP check](https://serp.hoangha.shop/serp): Run one free live Google search, no account required.
- [Residential proxies](https://serp.hoangha.shop/residential-proxies): Rotating Vietnamese residential IPv4 proxies on self-operated FPT lines; HTTP + SOCKS5, rotate on demand, priced per key per day in credits.
- [Changelog](https://serp.hoangha.shop/changelog): Product updates, new features, and improvements.
- [Sign up](https://serp.hoangha.shop/sign-up): Create a free account.

## Documentation

- [Introduction](https://serp.hoangha.shop/docs): What the SERP API does and how the job-based flow works.
- [Quickstart](https://serp.hoangha.shop/docs/quickstart): Run your first search in under five minutes.
- [Authentication](https://serp.hoangha.shop/docs/authentication): API keys, the X-API-Key header, tiers, and quotas.
- [Submit a search](https://serp.hoangha.shop/docs/search): POST /v1/search — every request parameter.
- [Retrieve results](https://serp.hoangha.shop/docs/results): GET /v1/search/{id} — polling and output formats.
- [AI Overview & features](https://serp.hoangha.shop/docs/ai-overview): AI Overviews, citations, and SERP features.
- [Usage & quotas](https://serp.hoangha.shop/docs/usage): GET /v1/usage, tiers, and rate limits.
- [Errors](https://serp.hoangha.shop/docs/errors): HTTP status codes and how to handle them.
- [OpenAPI & Swagger](https://serp.hoangha.shop/docs/openapi): Interactive explorer, the OpenAPI schema, and client codegen.
- [SerpApi drop-in](https://serp.hoangha.shop/docs/serpapi): Repoint an existing SerpApi client — same params, same endpoints, same response envelope.
- [Language SDKs](https://serp.hoangha.shop/docs/sdks): Call the API from Node, Python, PHP, Go, Ruby, Java.
- [MCP server](https://serp.hoangha.shop/docs/mcp): Expose the SERP API to AI agents as tools.
- [Guides & recipes](https://serp.hoangha.shop/docs/guides): Async vs sync, rank tracking, caching, migration.
- [Rotating proxies](https://serp.hoangha.shop/docs/proxies): Connect over HTTP/SOCKS5, rotate the IP via GET /api/v1/rotate, key lifecycle and limits.
- [Datasets API](https://serp.hoangha.shop/docs/datasets): serpupdate.com-compatible batch crawl API for exact keyword lists.
- [Developer & MCP overview](https://serp.hoangha.shop/developers): One-page REST API and MCP server reference.

## LLM docs (llms.txt files)

- [llms.txt](https://serp.hoangha.shop/llms.txt): This index.
- [llms-full.txt](https://serp.hoangha.shop/llms-full.txt): The complete documentation in one file.
- [llms-api.txt](https://serp.hoangha.shop/llms-api.txt): The REST API reference only.
- [llms-sdks.txt](https://serp.hoangha.shop/llms-sdks.txt): Language-integration snippets (Node, Python, PHP, Go, Ruby, and OpenAPI codegen).
- [llms-mcp.txt](https://serp.hoangha.shop/llms-mcp.txt): The MCP server only.

## Features

- Multi-engine SERP crawling across Google, Bing, Yahoo, Baidu, Seznam, Naver, with geo and device targeting.
- Full ~100-result depth per keyword; SERP feature detection (9 types plus sitelinks); Google AI Overview captured by default with its citations.
- Output as html, json, or a SerpApi-compatible envelope; a root-mounted SerpApi drop-in surface so an existing SerpApi client needs only a base-URL change.
- Batch Datasets API (serpupdate.com-compatible) for exact keyword lists, up to 200 keywords per snapshot, with an optional pingback webhook.
- MCP server exposing the API to AI agents as tools.
- Rotating Vietnamese residential proxies: one stable HTTP/SOCKS5 endpoint per key, rotate on demand or automatically every 30 minutes, unmetered bandwidth.
- Credit-based billing (SePay / VietQR bank transfer); no seat fees.
- Not sold here: rank tracking / keyword campaigns — see https://serpupdate.com/.

## API (summary)

- Base URL: https://serp-api.hoangha.shop
- Interactive explorer: https://serp-api.hoangha.shop/docs (OpenAPI: https://serp-api.hoangha.shop/openapi.json)
- Auth: `X-API-Key` header. Keys carry a tier and monthly quota.
- `POST /v1/search` {keyword, location, gl, hl, device, stop_domain, capture_aio, async} -> {job_id, status, cached}. The AI Overview is captured by default; capture_aio=false skips it for a faster crawl.
- `GET /v1/search/{job_id}?output=html|json|serpapi` -> parsed results (poll while running; html is the default output)
- `GET /v1/usage` -> tier, monthly quota, usage, remaining
- MCP tools: serp_search, serp_get_results, serp_usage (console script `serp-api-mcp`, stdio transport)
- Datasets API (serpupdate.com-compatible async batch): `POST /datasets/v1/trigger` {id?, input:[{keyword,country,language,brd_mobile,url,uule,start_page,end_page,tbm,capture_aio,id?}]} -> {snapshot_id, id?}; `GET /datasets/v1/snapshot/{id}?output=serpupdate|native|html` -> results array (or status while processing); `PUT /datasets/v1/pingback` {pingback_url} sets webhook. Up to 200 keywords/snapshot. Your `id` is echoed everywhere and names the output=html file. Output modes: serpupdate.com shape (default), native (AI Overview + SERP features), or gzipped raw HTML with page markers.