▣ DATA EXTRACTION · SEO

Get SERP Results API

What it does

SERP Results Classic lets you submit search-result tasks, retrieve task status and results, and fetch the raw HTML dump for a completed task. It also includes a location lookup endpoint for resolving supported search locations.

Send a task with an API key and a request body that can include tag, query, device, location_id, pingback_url, language_code, and search_engine. The task endpoints let you create a job, then poll by task_id to get the result or an advanced result payload when you need deeper SERP data. If you need the original page source for analysis or debugging, use the HTML dump endpoint with the same task_id.

Use SERP Results Classic when you need programmatic search engine data for rank tracking, keyword research, competitor monitoring, or QA on location-sensitive search queries. The locations endpoint accepts q, include, and country_code so you can narrow down supported search locations before submitting a task.

This service is a fit when your workflow depends on Google-style search results and you want to automate collection, webhook delivery via pingback_url, and post-processing from a task-based API.

▣ ENDPOINT 01 / 05

POST

Add task

https://api.eu.apyhub.com/se-ranking/serp-results-classic/v1/serp/classic/tasks

QUICKSTART

GUIDE

Quickstart

Create a new classic SERP task with a minimal JSON body and your API key in the query string.

curl -X POST "https://api.eu.apyhub.com/se-ranking/serp-results-classic/v1/serp/classic/tasks" \
  -H "Content-Type: application/json" \
  -H "apy-token: $APY_TOKEN" \
  -d '{
    "query": ["seo report"],
    "device": "desktop",
    "location_id": 12998,
    "language_code": "es",
    "search_engine": "google"
  }'

What you'll get back

Returns an array of task objects, one per query submitted, each with an id you can use to poll for status/results. See the Docs tab for the full response shape.

TRY ITLIVE · 500 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Creates one or more SERP Classic tasks based on the search queries submitted in the request body. If multiple queries are provided in the query array, a separate task is created for each one. The response returns an array of task objects, each representing a queued or in-progress task with its own id, echoed request parameters, and current status. An apikey is accepted as a query parameter for authentication.

Note: tasks are asynchronous — a newly created task will typically have is_completed: false and status: null until it finishes processing. Poll the task using its id via the task status/result endpoint to retrieve the final SERP data.

Request Body

Parameter	Type	Mandatory	Description
query	String Array	Yes	Search queries to submit. One task is created per query.
device	String	Yes	Device type for the task.
location_id	Integer	Yes	Location identifier.
language_code	String	Yes	Language code for the task.
search_engine	String	Yes	Search engine to use.
tag	String	No	Optional task tag.

Response

Returns an array of task objects — one per query submitted. Each object includes a server-generated id, the echoed task parameters, and status-tracking fields (is_completed, status, added). See Output Schema below for the full field-level breakdown.

Body

Name

Type

Description

bodyOPTIONAL

object

—

▣ ENDPOINT 02 / 05

GET

List tasks / Get task results

https://api.eu.apyhub.com/se-ranking/serp-results-classic/v1/serp/classic/tasks

QUICKSTART

GUIDE

Quickstart

Fetch a SERP classic task by its ID using your API key in the query string.

curl -X GET "https://api.eu.apyhub.com/se-ranking/serp-results-classic/v1/serp/classic/tasks?task_id=176899957" \
  -H "apy-token: $APY_TOKEN"

What you'll get back

Returns a status object while the task is still processing (e.g. {"status": "processing"}). Once the task completes, a fuller result payload is expected — see the Docs tab, pending confirmation.

TRY ITLIVE · 250 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Lists SERP Classic tasks, or retrieves a specific task's result when a task_id is provided. Input is supplied entirely via query parameters — there is no request body.

Query Parameter(s)

Attribute	Type	Mandatory	Description
task_id	Integer	No	Identifier of the task to retrieve. If omitted, presumably lists all tasks.

Query parameters

Name

Type

Description

task_idOPTIONAL

string

The task identifier to fetch the HTML dump for.

▣ ENDPOINT 03 / 05

GET

Get HTML dump

https://api.eu.apyhub.com/se-ranking/serp-results-classic/v1/serp/classic/tasks/html

QUICKSTART

GUIDE

Quickstart

Fetch a SERP classic task's HTML result by its task_id query parameter.

curl -X GET "https://api.eu.apyhub.com/se-ranking/serp-results-classic/v1/serp/classic/tasks/html?task_id=123456" \
  -H "apy-token: $APY_TOKEN"

What you'll get back

Expected to return the raw HTML content for the task

TRY ITLIVE · 250 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Retrieves the raw HTML dump for a SERP Classic task, identified by its task_id query parameter.

Query Parameter(s)

Attribute	Type	Mandatory	Description
task_id	Integer	Yes	The task identifier to fetch the HTML dump for.

Query parameters

Name

Type

Description

task_idOPTIONAL

string

The task identifier to fetch the HTML dump for.

▣ ENDPOINT 04 / 05

GET

Get advanced results

https://api.eu.apyhub.com/se-ranking/serp-results-classic/v1/serp/classic/tasks/results_advanced

QUICKSTART

GUIDE

Quickstart

Fetch the advanced results for a classic SERP task by passing its task_id as a query parameter.

curl -X GET "https://api.eu.apyhub.com/se-ranking/serp-results-classic/v1/serp/classic/tasks/results_advanced?task_id=123456" \
  -H "apy-token: $APY_TOKEN"

What you'll get back

Returns a single object containing request_metadata, a summary, and an items array with the full ranked SERP content (AI overview, organic results, people-also-ask, related searches, etc.).

TRY ITLIVE · 500 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Retrieves the advanced (detailed) results for a completed SERP Classic task, using the task_id passed as a query parameter. Unlike the basic "Get Task Results" endpoint, this returns the full parsed SERP data — request metadata, a results summary, and a mixed array of SERP item types (AI overview, organic listings, "people also ask", "related searches", etc.) in ranked order.

Query Parameter(s)

Attribute	Type	Mandatory	Description
task_id	Integer	Yes	Identifier of the task to fetch results for.

Response

Returns a single object with three top-level sections:

request_metadata — echoes back the original task's search parameters plus crawl info (when it was crawled, the actual search URL hit).
summary — aggregate counts and a list of which SERP features were detected on the page (e.g. AI overview, videos, reviews).
items — an ordered array of the actual SERP content, ranked by position. Each item has a type field that determines which additional fields are present (see Output Schema below for the per-type breakdow).

Query parameters

Name

Type

Description

task_idOPTIONAL

string

Identifier of the task to fetch results for.

▣ ENDPOINT 05 / 05

GET

Get locations

https://api.eu.apyhub.com/se-ranking/serp-results-classic/v1/serp/classic/locations

QUICKSTART

GUIDE

Quickstart

Fetch the SERP classic locations for a query, with optional filters passed as query parameters.

curl -X GET "https://api.eu.apyhub.com/se-ranking/serp-results-classic/v1/serp/classic/locations?q=new%20york&include=all&country_code=us" \
  -H "apy-token: $APY_TOKEN"

What you'll get back

Expected to return a list of matching locations

TRY ITLIVE · 250 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Looks up SERP Classic-supported search locations, filterable by a free-text query, an include list, and/or a country code. Used to resolve valid location_id values before submitting a task (see Add Task endpoint), so you can target location-sensitive search queries correctly.

Query Parameter(s)

Attribute	Type	Mandatory	Description
q	String	No	Search term used to look up locations.
include	String	No	Additional locations to include in the results.
country_code	String	No	Country code used to scope the location lookup.

Response

Expected to return a list of matching location objects (each likely including at minimum an id — matching the location_id field used in Add Task — plus a display name and possibly country/region info). Not confirmed from a sample response yet.

Query parameters

Name

Type

Description

qOPTIONAL

string

Search term used to look up locations.

includeOPTIONAL

string

Additional locations to include in the results.

country_codeOPTIONAL

string

Country code used to scope the location lookup.

▣ COMMON ERRORS

Errors any endpoint can return

400bad_request

Required parameter missing or malformed body.

401unauthorized

API key missing, revoked, or not authorized for this service.

429rate_limited

Your plan's per-second rate exceeded. Retry with exponential backoff.

503upstream_busy

Backend temporarily unavailable. Try again in a few seconds.