SERP API — Hypedata Docs

01Overview

The SERP API issues a search against a real engine, parses every block on the page (organic, ads, knowledge panel, shopping, top stories, related questions, maps, images, videos), and returns one normalized JSON envelope. You never look at HTML.

REST JSON Google · Bing · DDG · Baidu · Yandex · Brave · Kagi

02Endpoint

GET https://api.hypedata.io/v1/serp

curl "https://api.hypedata.io/v1/serp?q=best+espresso+machine&engine=google&country=us" \
  -H "Authorization: Bearer $HYPEDATA_API_KEY"

const serp = await hd.serp({
  q: "best espresso machine",
  engine: "google",
  country: "us"
});
console.log(serp.organic[0].title);

serp = hd.serp(q="best espresso machine", engine="google", country="us")
print(serp.organic[0].title)

03Parameters

Name	Type	Description
qrequired	string	Search query. Operators (`site:`, `"phrase"`, `-word`) are forwarded verbatim.
engineoptional	enum	One of `google` (default) · `bing` · `duckduckgo` · `baidu` · `yandex` · `brave` · `kagi`.
countryoptional	string	ISO 3166-1 alpha-2. Sets both the exit IP and the engine's `gl=` parameter.
languageoptional	string	ISO 639-1 (`en`, `fr`, `ja`…). Maps to engine-specific `hl=` / `lr=`.
deviceoptional	enum	`desktop` (default) · `mobile` · `tablet`. SERPs differ markedly across devices.
typeoptional	enum	`web` (default) · `images` · `news` · `shopping` · `videos` · `maps`.
pageoptional	integer	1-indexed page number. See Pagination.
numoptional	integer	Results per page, 10 – 100. Engine-dependent; Google honors up to 100.
safeoptional	enum	`off` (default) · `moderate` · `strict`.
time_rangeoptional	enum	`day` · `week` · `month` · `year` · or a custom range `YYYY-MM-DD..YYYY-MM-DD`.
blocksoptional	array	Restrict parsed output to a subset of block types — e.g. `["organic", "ads"]`. Saves response size.

04Supported engines

Engine	Slug	Coverage	Notes
Google	`google`	Web · Images · News · Shopping · Videos · Maps	Default. Most comprehensive block coverage.
Bing	`bing`	Web · Images · News · Shopping · Videos	Useful for North American B2B coverage.
DuckDuckGo	`duckduckgo`	Web · Images · News · Videos	No personalization — cleanest baseline ranking.
Baidu	`baidu`	Web · Images · News	For Chinese-language coverage. Requires CN proxy.
Yandex	`yandex`	Web · Images · News	Russian / CIS coverage.
Brave	`brave`	Web · News	Independent index, less Big-Tech leakage.
Kagi	`kagi`	Web	Premium upstream; +5 credits surcharge.

05Block types

Every response contains zero or more typed block arrays. Below is the canonical list — engines that don't surface a given block simply omit the field.

organic — classic blue-link results, ranked.
ads — sponsored results, top and bottom of page.
knowledge_panel — entity card (right-rail on Google).
answer_box — featured snippet.
related_questions — "People also ask".
related_searches — query refinements at the bottom.
shopping — product carousel.
top_stories — news carousel.
videos — video pack.
images — image pack.
maps — local pack with markers and reviews summary.
twitter — recent tweets carousel.
recipes · jobs · events · flights · hotels — vertical-specific packs.

06Response

200OK · google · us · ~1.4 s · 5 credits

{
  "status": "ok",
  "query": "best espresso machine",
  "engine": "google",
  "locale": { "country": "us", "language": "en", "device": "desktop" },
  "total_results": 218000000,
  "answer_box": {
    "title": "Top picks for 2026",
    "snippet": "After 70 hours of testing…",
    "source": "https://wirecutter.com/…"
  },
  "organic": [
    {
      "rank": 1,
      "title": "Best Espresso Machines of 2026 — Wirecutter",
      "url": "https://www.nytimes.com/wirecutter/…",
      "displayed_url": "www.nytimes.com › wirecutter",
      "snippet": "After 70 hours of testing 23 machines…",
      "sitelinks": [ { "title": "Under $500", "url": "…" } ]
    },
    /* … */
  ],
  "related_questions": [ { "question": "What espresso machine do baristas use at home?", "answer": "…" } ],
  "related_searches": ["best home espresso machine 2026", "breville barista express"],
  "shopping": [ { "title": "Breville Barista Express", "price": "$699.95", "merchant": "Amazon" } ],
  "meta": { "latency_ms": 1420, "credits_used": 5, "trace_id": "trc_…" }
}

07Pagination

Use page and num to walk results. num=100&page=1 returns ranks 1 – 100; page=2 returns 101 – 200. The response includes has_next_page for safe loops.

let page = 1;
while (true) {
  const r = await hd.serp({ q, engine: "google", num: 100, page });
  yieldResults(r.organic);
  if (!r.has_next_page) break;
  page++;
}

08Locale & geo

SERPs are extremely sensitive to locale. Always pin country + language + device if you intend to compare results over time — one of those changing under your feet will produce noisy data.

For sub-country granularity, pass a location string (e.g. "Brooklyn, New York, United States") which Hypedata canonicalizes against the Google Ads geotargets list and forwards as the engine's uule parameter.

09Credit cost

Base cost is 5 credits per SERP, regardless of engine — with two surcharges:

kagi upstream: +5 credits.
type=maps or type=shopping on Google: +3 credits (more expensive proxy tier).

Failed SERPs (anti-bot wall, captcha, parse failure) are refunded automatically.

SERP API.