Reference

SERP API

Search Google, Bing or DuckDuckGo and get the result page as structured JSON. Proxies, blocks and retries are handled the same way as for scrapes.

POST /v1/serp

The body is a JSON object; unknown fields are rejected with 400 invalid_request. Authentication, concurrency limits and errors work as for POST /v1/scrape.

enginegoogle | bing | duckduckgorequired
The search engine to query.
qstringrequired
The search, 1–512 characters. Search operators such as site: are passed on unchanged. Google and Bing sometimes ignore site: for an exit they suspect and return unrelated results; Siftzo recognises that and retries from another exit. When the engine ignores site: on every attempt, the request fails with target_blocked and says so, and is not charged.
countrystring
ISO 3166-1 alpha-2 code, for example dk or us. Sets both the country the engine localises results for and the exit country of the request. See Proxies.
languagestring
Interface and result language, for example en, da or pt-br. Also sent as Accept-Language. Without it, the language follows the exit country.
devicedesktop | mobiledefault desktop
Search as Chrome on a desktop or on an Android phone.
pageintegerdefault 1
Result page, 1–10. DuckDuckGo supports page 1 only; other pages are refused with 400 invalid_request.
numinteger
Results per page, 10–100. Google only, and Google may still return 10. Refused for the other engines.
include_htmlbooleandefault false
Also return the result page as html, for fields Siftzo does not parse.
timeout_msintegerdefault 60000
Deadline for the whole request including retries, between 5000 and 90000.
asyncbooleandefault false
Queue the request and return 202 with a job ID. See GET /v1/serp/{id}.
webhook_urlstring
Only with async: true: Siftzo sends a signed job.finished event with product: "serp" to this https URL when the search has finished. See Webhooks.
Example
curl https://api.siftzo.com/v1/serp \
  -H "X-API-Key: $SIFTZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "engine": "google",
    "q": "web scraping api",
    "country": "us",
    "language": "en"
  }'

Response

200 OK
{
  "id": "01K6ZQ7F2B9X4M1NQ8T3RJ6VWC",
  "status": "done",
  "engine": "google",
  "query": "web scraping api",
  "page": 1,
  "search_url": "https://www.google.com/search?gl=us&hl=en&pws=0&q=web+scraping+api",
  "status_code": 200,
  "results": {
    "parse_status": "complete",
    "total_results": 1840000000,
    "organic": [
      {
        "position": 1,
        "title": "Siftzo – Web Scraping API with Proxies and Browsers",
        "url": "https://www.siftzo.com/",
        "displayed_url": "https://www.siftzo.com",
        "snippet": "Scrape any page with one API call. …",
        "sitelinks": [
          { "title": "Pricing", "url": "https://www.siftzo.com/pricing" }
        ]
      }
    ],
    "ads": [
      {
        "position": 1,
        "placement": "top",
        "title": "Scraping API - 1,000 Free Requests",
        "url": "https://www.scrapingapi.example/",
        "displayed_url": "https://www.scrapingapi.example"
      }
    ],
    "featured_snippet": {
      "title": "Web scraping - Wikipedia",
      "url": "https://en.wikipedia.org/wiki/Web_scraping",
      "displayed_url": "https://en.wikipedia.org › wiki › Web_scraping",
      "snippet": "A web scraping API is a service that …"
    },
    "answer_box": null,
    "people_also_ask": [{ "question": "What is a web scraping API?" }],
    "related_searches": [
      {
        "query": "web scraping api free",
        "url": "https://www.google.com/search?q=web+scraping+api+free"
      }
    ]
  },
  "tier": "browser",
  "attempts": 2,
  "credits": 10,
  "duration_ms": 6120
}
idstring
Request ID. The same value as the X-Request-Id header and the job ID.
statusdone | failed
Whether Siftzo got a result page from the engine.
engine, query, page
Your search, as Siftzo ran it.
search_urlstring
The URL Siftzo fetched.
status_codeinteger
HTTP status the engine answered with.
resultsobject | null
The parsed page, described below. null when the request failed.
htmlstring
Only with include_html: true.
tierhttp | browser
The tier that fetched the page.
attemptsinteger
Attempts made, at most 3.
creditsinteger
Credits charged: 10, or 0 when the request failed.
duration_msinteger
Time spent inside Siftzo, in milliseconds.
errorobject
Only when status is failed: code and message. See Errors.

The results object

Every engine returns the same shape. Sections an engine does not have are empty lists or null: DuckDuckGo shows no result count, related searches or questions.

parse_statuscomplete | partial | failed
complete: every section on the page was read. partial: there are results, but some could not be read, for example a result without a link. failed: the page was not a result page Siftzo understands. With partial and failed, warnings says why.
total_resultsinteger | null
The engine's estimate of matching results, when it shows one.
organicarray
position, title, url, displayed_url, snippet and, when present, sitelinks (title, url). Positions continue across pages: page 2 with 10 results per page starts at 11. Links are unwrapped from the engine's click tracking. Google links its results through google.com/goto and reveals where a link leads only for the first few of a search; for the rest it asks for verification, which Siftzo does not get around. Siftzo resolves the top results first, so usually the first one or two have their real URL. The others stay google.com/goto links and make parse_status partial; displayed_url still shows each result's site.
adsarray
position (within its placement), placement (top or bottom), title, url and displayed_url. Ad URLs are the engine's click links where the landing page is not given.
featured_snippetobject | null
title, url, displayed_url and snippet. DuckDuckGo instant answers appear here.
answer_boxobject | null
A direct answer as answer, for example "Paris".
people_also_askarray
Related questions as question.
related_searchesarray
query and url.

Search engines change their pages often. A request that fetched the page counts as done even when it could not be parsed (parse_status: "failed"); send include_html: true if you want the page to fall back on. We check every engine daily with real searches.

Engines

What each engine supports
EnginePagesnumSections
google1–1010–100Organic, sitelinks, ads, featured snippet, answer box, people also ask, related searches, result count
bing1–10–Organic, sitelinks, ads, featured snippet, answer box, people also ask, related searches, result count
duckduckgo1–Organic, ads, instant answer (as featured snippet)

GET /v1/serp

The same as a sync POST, with parameters in the query string: engine, q, country, language, device, page, num, include_html and timeout_ms. Async is only available with POST.

Example
curl -G https://api.siftzo.com/v1/serp \
  -H "X-API-Key: $SIFTZO_API_KEY" \
  -d engine=bing --data-urlencode "q=pizza berlin" -d country=de -d language=de

GET /v1/serp/{id}

With async: true, the answer is 202 Accepted with a Location header and a status_url of /v1/serp/{id}. It works like GET /v1/jobs/{id}: id and status until the search has finished, then the full result above with HTTP 200. Results are kept for 24 hours. To skip polling, pass a webhook_url; see Webhooks.

Credits

A SERP request costs 10 credits, whichever engine and tier it ran on. Blocked, timed-out and failed requests cost 0. Siftzo reserves 10 credits before the search runs. See Rate limits & credits.

Google's terms do not allow automated queries. You are responsible for how you use the results; see Responsible use.