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 ignoresite:for an exit they suspect and return unrelated results; Siftzo recognises that and retries from another exit. When the engine ignoressite:on every attempt, the request fails withtarget_blockedand says so, and is not charged. countrystring- ISO 3166-1 alpha-2 code, for example
dkorus. 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,daorpt-br. Also sent asAccept-Language. Without it, the language follows the exit country. devicedesktop | mobiledefaultdesktop- Search as Chrome on a desktop or on an Android phone.
pageintegerdefault1- 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_htmlbooleandefaultfalse- Also return the result page as
html, for fields Siftzo does not parse. timeout_msintegerdefault60000- Deadline for the whole request including retries, between 5000 and 90000.
asyncbooleandefaultfalse- Queue the request and return
202with a job ID. See GET /v1/serp/{id}. webhook_urlstring- Only with
async: true: Siftzo sends a signedjob.finishedevent withproduct: "serp"to thishttpsURL when the search has finished. See Webhooks.
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
{
"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.
nullwhen 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
statusisfailed:codeandmessage. 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 | failedcomplete: 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. Withpartialandfailed,warningssays why.total_resultsinteger | null- The engine's estimate of matching results, when it shows one.
organicarrayposition,title,url,displayed_url,snippetand, 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 throughgoogle.com/gotoand 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 staygoogle.com/gotolinks and makeparse_statuspartial;displayed_urlstill shows each result's site.adsarrayposition(within its placement),placement(toporbottom),title,urlanddisplayed_url. Ad URLs are the engine's click links where the landing page is not given.featured_snippetobject | nulltitle,url,displayed_urlandsnippet. DuckDuckGo instant answers appear here.answer_boxobject | null- A direct answer as
answer, for example "Paris". people_also_askarray- Related questions as
question. related_searchesarrayqueryandurl.
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
| Engine | Pages | num | Sections |
|---|---|---|---|
google | 1–10 | 10–100 | Organic, sitelinks, ads, featured snippet, answer box, people also ask, related searches, result count |
bing | 1–10 | – | Organic, sitelinks, ads, featured snippet, answer box, people also ask, related searches, result count |
duckduckgo | 1 | – | 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.
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=deGET /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.