API Examples

Ready-to-use code examples in multiple languages. Copy, paste, and start building.

Response format

Every successful request returns a JSON object with the following structure. All SERP elements are parsed and organized for you.

{
  "query": "best project management tools",
  "total_results": 2840000000,
  "search_time": 0.38,
  "organic_results": [
    {
      "position": 1,
      "title": "The 10 Best Project Management Tools in 2024",
      "link": "https://example.com/best-pm-tools",
      "snippet": "Compare the top project management tools...",
      "displayed_link": "example.com"
    }
  ],
  "featured_snippet": {
    "title": "Best Project Management Tools",
    "content": "The most popular project management tools include...",
    "source": "https://example.com/pm-guide"
  },
  "related_searches": [
    "free project management tools",
    "project management software for small teams"
  ]
}

Code examples by language

Each example makes a GET request to the search endpoint and prints the results. Replace the API key with your own from the dashboard.

cURL

curl -G https://serpsearch.com/api/v1/search \
  -H "Authorization: Bearer mk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  --data-urlencode "q=best project management tools" \
  -d "num=10" \
  -d "gl=us" \
  -d "hl=en"

Python

import requests

response = requests.get(
    "https://serpsearch.com/api/v1/search",
    headers={"Authorization": "Bearer mk_live_xxxxxxxxxxxxxxxxxxxxxxxx"},
    params={"q": "best project management tools", "num": 10, "gl": "us"},
)
response.raise_for_status()
data = response.json()

for result in data["organic_results"]:
    print(f"{result['position']}. {result['title']}")
    print(f"   {result['link']}")
    print(f"   {result['snippet']}\n")

JavaScript

const response = await fetch(
  "https://serpsearch.com/api/v1/search?q=best+project+management+tools&num=10&gl=us",
  {
    headers: {
      Authorization: "Bearer mk_live_xxxxxxxxxxxxxxxxxxxxxxxx",
    },
  }
);

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.code}: ${error.message}`);
}

const data = await response.json();
data.organic_results.forEach((result) => {
  console.log(`${result.position}. ${result.title}`);
  console.log(`   ${result.link}\n`);
});

Go

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
    "net/url"
)

func main() {
    params := url.Values{}
    params.Set("q", "best project management tools")
    params.Set("num", "10")
    params.Set("gl", "us")

    req, _ := http.NewRequest("GET",
        "https://serpsearch.com/api/v1/search?"+params.Encode(), nil)
    req.Header.Set("Authorization",
        "Bearer mk_live_xxxxxxxxxxxxxxxxxxxxxxxx")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    var data map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&data)
    fmt.Printf("Found %v results\n", data["total_results"])
}

Ruby

require "net/http"
require "json"
require "uri"

uri = URI("https://serpsearch.com/api/v1/search")
uri.query = URI.encode_www_form(
  q: "best project management tools",
  num: 10,
  gl: "us"
)

req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer mk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(req)
end

data = JSON.parse(res.body)
data["organic_results"].each do |result|
  puts "#{result['position']}. #{result['title']}"
  puts "   #{result['link']}\n\n"
end

PHP

<?php
$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => "https://serpsearch.com/api/v1/search?"
        . http_build_query([
            "q"   => "best project management tools",
            "num" => 10,
            "gl"  => "us",
        ]),
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer mk_live_xxxxxxxxxxxxxxxxxxxxxxxx",
    ],
    CURLOPT_RETURNTRANSFER => true,
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
foreach ($data["organic_results"] as $result) {
    echo $result["position"] . ". " . $result["title"] . "\n";
    echo "   " . $result["link"] . "\n\n";
}

Common patterns

Useful patterns for pagination, geo-targeting, error handling, and more.

Pagination

Retrieve multiple pages of results by incrementing the page parameter.

# Page 1 (results 1-10)
GET /api/v1/search?q=ai+tools&num=10&page=1

# Page 2 (results 11-20)
GET /api/v1/search?q=ai+tools&num=10&page=2

# Page 3 (results 21-30)
GET /api/v1/search?q=ai+tools&num=10&page=3

Geo-targeted results

Get localized search results for different countries and languages.

# UK English results
GET /api/v1/search?q=football+scores&gl=gb&hl=en

# French results from France
GET /api/v1/search?q=résultats+football&gl=fr&hl=fr

# Brazilian Portuguese results
GET /api/v1/search?q=resultados+futebol&gl=br&hl=pt

Error handling

All errors follow a consistent envelope format for easy handling.

// Check for errors in every response
const response = await fetch(url, { headers });

if (!response.ok) {
  const { error } = await response.json();

  switch (error.code) {
    case "RATE_LIMIT_EXCEEDED":
      const retryAfter = response.headers.get("Retry-After");
      // Wait and retry
      break;
    case "QUOTA_EXCEEDED":
      // Upgrade plan or wait for billing period reset
      break;
    default:
      console.error(error.code, error.message);
  }
}

POST request with JSON body

Use POST when you need to send complex queries or prefer JSON bodies.

curl -X POST https://serpsearch.com/api/v1/search \
  -H "Authorization: Bearer mk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "machine learning frameworks comparison 2024",
    "num": 20,
    "gl": "us",
    "hl": "en"
  }'

Ready to integrate?

Read the full API reference for detailed parameter docs, error codes, and response headers.

API Documentation View Pricing