Skip to content
serp.cheap

Find where a url/domain ranks for a keyword across Google result pages.

POST
/v1/rank
 
curl --request POST \
  --url https://api.serp.cheap/v1/rank \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --data '{ "url": "example", "q": "example", "query": "example", "gl": "br", "hl": "example", "tbs": "qdr:h", "pages": 1, "match_type": "domain" }'

Authorizations

Section titled “Authorizations ”

Request Body required

Section titled “Request Body required ”
Media type application/json
object
url
required

The domain or full URL to locate in the results.

string
>= 1 characters <= 2048 characters
q

The keyword to rank for (alias of query).

string
>= 1 characters <= 500 characters
query
string
>= 1 characters <= 500 characters
gl
string
default: us
Allowed values: br us gb de fr es it mx ca au jp nl
hl
string
<= 8 characters /^[a-z]{2}(-[A-Z]{2})?$/
tbs
string
Allowed values: qdr:h qdr:d qdr:w
pages

How many result pages to scan (each ~10 results). Billed per page.

integer
default: 1 >= 1 <= 10
match_type

Domain = any result on the registrable domain; exact = the identical URL.

string
default: domain
Allowed values: domain exact

Responses

Section titled “ Responses ”

200

Section titled “200 ”

The ranking outcome (found/rank/matches). 200 with partial=true if some pages failed.

Media type application/json
object
url
required
string
search
required
string
gl
required
string
match_type
required
string
Allowed values: domain exact
pages_scanned
required
integer
found
required
boolean
rank
required

Absolute rank of the best match, or null if not found.

integer
nullable
matches
required
Array<object>
object
rank
required

Absolute 1-based rank across scanned pages.

integer
page
required
integer
position_on_page
required
integer
link
required
string
title
required
string
organic
required

Every organic result across the scanned pages (absolute position).

Array<object>
object
position
required
integer
title
required
string
link
required
string
snippet
required
string
date
string
sitelinks
Array<object>
object
title
required
string
link
required
string
content

Scraped page content as markdown (present when scrape was requested and succeeded).

string
screenshot_url

Screenshot (1920x1080 by default), 48h presigned URL (present when scrape.screenshot was requested).

string
scrape_error

Why this page couldn’t be scraped (not billed). Mutually exclusive with content.

string
partial
required

True when one or more pages failed to fetch.

boolean
pages_failed
required
Array<integer>
stats
object
balance
integer
cost
integer
pages_cached
integer
pages_fresh
integer
Example 
{
  "match_type": "domain"
}

400

Section titled “400 ”

A typed error.

Media type application/json
object
error
required

Machine code: invalid_request, missing_api_key, unknown_api_key, inactive_api_key, account_blocked, insufficient_credits, rate_limited, request_in_progress, too_many_concurrent_requests, service_temporarily_unavailable, result_timeout.

string
message
string
details
retry_after_ms
integer
required
integer
balance
integer
Example generated
{
  "error": "example",
  "message": "example",
  "details": "example",
  "retry_after_ms": 1,
  "required": 1,
  "balance": 1
}

401

Section titled “401 ”

A typed error.

Media type application/json
object
error
required

Machine code: invalid_request, missing_api_key, unknown_api_key, inactive_api_key, account_blocked, insufficient_credits, rate_limited, request_in_progress, too_many_concurrent_requests, service_temporarily_unavailable, result_timeout.

string
message
string
details
retry_after_ms
integer
required
integer
balance
integer
Example generated
{
  "error": "example",
  "message": "example",
  "details": "example",
  "retry_after_ms": 1,
  "required": 1,
  "balance": 1
}

402

Section titled “402 ”

A typed error.

Media type application/json
object
error
required

Machine code: invalid_request, missing_api_key, unknown_api_key, inactive_api_key, account_blocked, insufficient_credits, rate_limited, request_in_progress, too_many_concurrent_requests, service_temporarily_unavailable, result_timeout.

string
message
string
details
retry_after_ms
integer
required
integer
balance
integer
Example generated
{
  "error": "example",
  "message": "example",
  "details": "example",
  "retry_after_ms": 1,
  "required": 1,
  "balance": 1
}

403

Section titled “403 ”

A typed error.

Media type application/json
object
error
required

Machine code: invalid_request, missing_api_key, unknown_api_key, inactive_api_key, account_blocked, insufficient_credits, rate_limited, request_in_progress, too_many_concurrent_requests, service_temporarily_unavailable, result_timeout.

string
message
string
details
retry_after_ms
integer
required
integer
balance
integer
Example generated
{
  "error": "example",
  "message": "example",
  "details": "example",
  "retry_after_ms": 1,
  "required": 1,
  "balance": 1
}

409

Section titled “409 ”

A typed error.

Media type application/json
object
error
required

Machine code: invalid_request, missing_api_key, unknown_api_key, inactive_api_key, account_blocked, insufficient_credits, rate_limited, request_in_progress, too_many_concurrent_requests, service_temporarily_unavailable, result_timeout.

string
message
string
details
retry_after_ms
integer
required
integer
balance
integer
Example generated
{
  "error": "example",
  "message": "example",
  "details": "example",
  "retry_after_ms": 1,
  "required": 1,
  "balance": 1
}

422

Section titled “422 ”

A typed error.

Media type application/json
object
error
required

Machine code: invalid_request, missing_api_key, unknown_api_key, inactive_api_key, account_blocked, insufficient_credits, rate_limited, request_in_progress, too_many_concurrent_requests, service_temporarily_unavailable, result_timeout.

string
message
string
details
retry_after_ms
integer
required
integer
balance
integer
Example generated
{
  "error": "example",
  "message": "example",
  "details": "example",
  "retry_after_ms": 1,
  "required": 1,
  "balance": 1
}

429

Section titled “429 ”

A typed error.

Media type application/json
object
error
required

Machine code: invalid_request, missing_api_key, unknown_api_key, inactive_api_key, account_blocked, insufficient_credits, rate_limited, request_in_progress, too_many_concurrent_requests, service_temporarily_unavailable, result_timeout.

string
message
string
details
retry_after_ms
integer
required
integer
balance
integer
Example generated
{
  "error": "example",
  "message": "example",
  "details": "example",
  "retry_after_ms": 1,
  "required": 1,
  "balance": 1
}

503

Section titled “503 ”

A typed error.

Media type application/json
object
error
required

Machine code: invalid_request, missing_api_key, unknown_api_key, inactive_api_key, account_blocked, insufficient_credits, rate_limited, request_in_progress, too_many_concurrent_requests, service_temporarily_unavailable, result_timeout.

string
message
string
details
retry_after_ms
integer
required
integer
balance
integer
Example generated
{
  "error": "example",
  "message": "example",
  "details": "example",
  "retry_after_ms": 1,
  "required": 1,
  "balance": 1
}

504

Section titled “504 ”

A typed error.

Media type application/json
object
error
required

Machine code: invalid_request, missing_api_key, unknown_api_key, inactive_api_key, account_blocked, insufficient_credits, rate_limited, request_in_progress, too_many_concurrent_requests, service_temporarily_unavailable, result_timeout.

string
message
string
details
retry_after_ms
integer
required
integer
balance
integer
Example generated
{
  "error": "example",
  "message": "example",
  "details": "example",
  "retry_after_ms": 1,
  "required": 1,
  "balance": 1
}