Built-in tool
Check Google Rankings
View live Google search rankings for a keyword.
Endpoint
Parameters
| Name | Type | Required | Note |
|---|---|---|---|
| keywordstring · required | string | required | The search query to fetch rankings for. |
| depthnumber · optional | number | optional | Number of organic SERP results to fetch, and a hard ceiling on the rows returned. Default 10; higher costs more. SERP page blocks (AI Overview, People Also Ask) share the same budget but rank BEHIND the organic results, so they appear among the rows only if this number leaves room after them; the blocks it leaves no room for are still returned, separately, in `page_blocks`. On a low number over a page carrying about as many blocks as results, neither clearly outnumbers the other, so you get some of each instead. Default: |
| targetstring · optional | string | optional | (Optional) Domain to filter results to, e.g. "example.com". Example: |
| language_namestring · optional | string | optional | Language for results. Defaults to English. One of: Default: |
| location_namestring · optional | string | optional | Country for results. Defaults to United States. One of: Default: |
Response schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"elements"
],
"properties": {
"elements": {
"type": "array",
"items": {
"type": "object",
"properties": {
"url": {
"type": [
"string",
"null"
]
},
"type": {
"type": "string"
},
"title": {
"type": [
"string",
"null"
]
},
"domain": {
"type": [
"string",
"null"
]
},
"sources": {
"type": "array",
"items": {
"type": "string"
},
"description": "On a SERP page block (AI Overview, People Also Ask, …): the bare domains of the pages it cites, deduplicated. Absent on organic rows."
},
"rank_group": {
"type": [
"number",
"null"
]
},
"references": {
"type": "array",
"items": {
"type": "object",
"required": [
"title",
"domain",
"url"
],
"properties": {
"url": {
"type": [
"string",
"null"
]
},
"title": {
"type": [
"string",
"null"
]
},
"domain": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
"description": "On a SERP page block: the pages it cites, in the order shown, up to 20. Absent on organic rows."
},
"description": {
"type": [
"string",
"null"
]
},
"rank_absolute": {
"type": [
"number",
"null"
]
}
},
"additionalProperties": true
}
},
"returned": {
"type": "number",
"description": "How many rows this run returned, after any Limit was applied."
},
"truncated": {
"type": "boolean"
},
"suggestion": {
"type": "string"
},
"totalCount": {
"type": "number",
"description": "How many records the provider says MATCH in total, independent of Limit — routinely in the millions (spotify.com has 2,583,327 ranking pages). It is a match count, NOT how many this endpoint will serve: Limit caps what one call returns, so do not compare it against the row count to judge completeness and do not paginate towards it. Absent when the provider sent no count."
},
"page_blocks": {
"type": "array",
"items": {
"type": "object",
"properties": {
"url": {
"type": [
"string",
"null"
]
},
"type": {
"type": "string"
},
"title": {
"type": [
"string",
"null"
]
},
"domain": {
"type": [
"string",
"null"
]
},
"sources": {
"type": "array",
"items": {
"type": "string"
},
"description": "On a SERP page block (AI Overview, People Also Ask, …): the bare domains of the pages it cites, deduplicated. Absent on organic rows."
},
"rank_group": {
"type": [
"number",
"null"
]
},
"references": {
"type": "array",
"items": {
"type": "object",
"required": [
"title",
"domain",
"url"
],
"properties": {
"url": {
"type": [
"string",
"null"
]
},
"title": {
"type": [
"string",
"null"
]
},
"domain": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
},
"description": "On a SERP page block: the pages it cites, in the order shown, up to 20. Absent on organic rows."
},
"description": {
"type": [
"string",
"null"
]
},
"rank_absolute": {
"type": [
"number",
"null"
]
}
},
"additionalProperties": true
},
"description": "SERP page blocks (AI Overview, People Also Ask, featured snippet, videos…) that Depth left no room for in `elements`, returned here in full with the same fields as a block row in `elements`: `type`, `rank_absolute` (the position it held on the page), `title`, the text it shows in `description`, and the pages it cites in `references` / `sources`. Read a block from `elements` when it is there, otherwise from here. Absent when every block fitted in `elements`."
},
"totalElements": {
"type": "number",
"description": "DEPRECATED — despite the name this is the count RETURNED by this run, not a grand total, so it equals your Limit on a limited run. Kept at that value deliberately: ENG-17058 asked for depth 5 to report 5, and it is a live number in existing flows. Use `returned` for this number or `totalCount` for how many records match."
},
"page_blocks_omitted": {
"type": "array",
"items": {
"type": "object",
"required": [
"type",
"rank_absolute",
"reason"
],
"properties": {
"type": {
"type": [
"string",
"null"
]
},
"reason": {
"enum": [
"depth",
"no_content"
],
"type": "string"
},
"rank_absolute": {
"type": [
"number",
"null"
]
}
},
"additionalProperties": false
},
"description": "SERP page blocks that sat on the page and were not returned at all, neither in `elements` nor in `page_blocks`. `no_content`: the block carried nothing to show (an AI Overview the provider had not finished loading). `depth` is no longer used: a block Depth left no room for is returned in `page_blocks`. A gap in the rank_absolute sequence of `elements` is a block listed here or in `page_blocks`. Absent when no block was left out, and on a target-filtered run."
}
},
"additionalProperties": true
}