curl --request POST \
--url https://api.rankspot.ai/v1/research/google \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"query": "best screen recording software for mac",
"types": [
"organic",
"discussions_and_forums"
]
}
'import requests
url = "https://api.rankspot.ai/v1/research/google"
payload = {
"query": "best screen recording software for mac",
"types": ["organic", "discussions_and_forums"]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
query: 'best screen recording software for mac',
types: ['organic', 'discussions_and_forums']
})
};
fetch('https://api.rankspot.ai/v1/research/google', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.rankspot.ai/v1/research/google",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'query' => 'best screen recording software for mac',
'types' => [
'organic',
'discussions_and_forums'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.rankspot.ai/v1/research/google"
payload := strings.NewReader("{\n \"query\": \"best screen recording software for mac\",\n \"types\": [\n \"organic\",\n \"discussions_and_forums\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.rankspot.ai/v1/research/google")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"query\": \"best screen recording software for mac\",\n \"types\": [\n \"organic\",\n \"discussions_and_forums\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.rankspot.ai/v1/research/google")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"query\": \"best screen recording software for mac\",\n \"types\": [\n \"organic\",\n \"discussions_and_forums\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"query": "best screen recorder mac",
"location": "United States",
"language": "en",
"items": [
{
"type": "organic",
"rank": 4,
"page": 1,
"domain": "screen.studio",
"title": "Screen Studio — Professional screen recorder",
"url": "https://screen.studio",
"website_name": "Microsoft Community Hub",
"description": "<string>",
"timestamp": "2025-03-26 00:00:00 +00:00",
"rank_group": 123,
"rank_absolute": 123,
"items": [
{}
],
"markdown": "<string>"
}
]
}Search Google
A live Google search, returned as items: the blocks of the results page in page order, each with a type to branch on. types chooses which blocks come back and defaults to organic and discussions_and_forums; ask for ai_overview, people_also_ask, video or related_searches when you will actually read them, since those carry the full text of every answer and dwarf the organic results. Always the top 10; location and language come from the workspace so results match what the rest of RankSpot reports. Costs credits, the same whichever blocks you ask for. Returns 402 when the workspace has none left.
curl --request POST \
--url https://api.rankspot.ai/v1/research/google \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"query": "best screen recording software for mac",
"types": [
"organic",
"discussions_and_forums"
]
}
'import requests
url = "https://api.rankspot.ai/v1/research/google"
payload = {
"query": "best screen recording software for mac",
"types": ["organic", "discussions_and_forums"]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
query: 'best screen recording software for mac',
types: ['organic', 'discussions_and_forums']
})
};
fetch('https://api.rankspot.ai/v1/research/google', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.rankspot.ai/v1/research/google",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'query' => 'best screen recording software for mac',
'types' => [
'organic',
'discussions_and_forums'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.rankspot.ai/v1/research/google"
payload := strings.NewReader("{\n \"query\": \"best screen recording software for mac\",\n \"types\": [\n \"organic\",\n \"discussions_and_forums\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.rankspot.ai/v1/research/google")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"query\": \"best screen recording software for mac\",\n \"types\": [\n \"organic\",\n \"discussions_and_forums\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.rankspot.ai/v1/research/google")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"query\": \"best screen recording software for mac\",\n \"types\": [\n \"organic\",\n \"discussions_and_forums\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"query": "best screen recorder mac",
"location": "United States",
"language": "en",
"items": [
{
"type": "organic",
"rank": 4,
"page": 1,
"domain": "screen.studio",
"title": "Screen Studio — Professional screen recorder",
"url": "https://screen.studio",
"website_name": "Microsoft Community Hub",
"description": "<string>",
"timestamp": "2025-03-26 00:00:00 +00:00",
"rank_group": 123,
"rank_absolute": 123,
"items": [
{}
],
"markdown": "<string>"
}
]
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
What to search Google for.
"best screen recording software for mac"
Which blocks of the results page to return. Everything else Google showed is dropped before the response is built. Ask for what you will actually read: ai_overview and people_also_ask carry the full text of every answer and are many times the size of the organic results.
ai_overview, organic, people_also_ask, discussions_and_forums, video, related_searches Response
"best screen recorder mac"
Resolved from the workspace's settings.
"United States"
Resolved from the workspace's settings.
"en"
The blocks Google showed, in page order, filtered to the types asked for. Empty when Google returned nothing, or nothing of those types.
Hide child attributes
Hide child attributes
Block type: organic, ai_overview, people_also_ask, discussions_and_forums, video, related_searches.
"organic"
organic only: position among the organic results. Not the page-wide position, which moves whenever Google adds a block above them.
4
organic only: which page of results this came from.
1
organic only.
"screen.studio"
"Screen Studio — Professional screen recorder"
"https://screen.studio"
organic only: the site's own name for itself, when it has one.
"Microsoft Community Hub"
Snippet text, when Google showed one.
organic only: when the page was published, when Google dated it. Absent means undated, not new.
"2025-03-26 00:00:00 +00:00"
Every type except organic: position among blocks of the same type, and across the whole page. Organic reports rank instead.
Nested entries for container blocks: the questions under people_also_ask, the threads under discussions_and_forums, the terms under related_searches.
ai_overview only: the overview Google generated, as markdown.
