DEV Community

dodou
dodou

Posted on

SERP API Quick Start: From Zero to Your First Query in 5 Minutes

#api #beginners #seo #tutorial

  • Who This Is For

  • First time using SERP API

  • Want to run "send a query, get JSON" quickly

  • Haven't used Google SERP API before

Step 1: Sign Up and Get Key (30 seconds)

  1. Go to serpbase.dev
  2. Click "Sign Up"
  3. Enter email + password (no card required)
  4. Confirm email
  5. Go to dashboard, see API key

You get 100 free searches (enough to test).

Step 2: First curl (30 seconds)

Copy this to your terminal:

curl -X POST https://api.serpbase.dev/google/search \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q": "best serp api", "gl": "us", "num": 5}'
Enter fullscreen mode Exit fullscreen mode

Returns JSON:

{
  "status": "ok",
  "request_id": "req_abc123",
  "credits_charged": 1,
  "organic": [
    {"title": "...", "link": "...", "snippet": "..."}
  ],
  "people_also_ask": [...],
  "knowledge_graph": {...}
}
Enter fullscreen mode Exit fullscreen mode

Replace YOUR_KEY with your dashboard key.

Step 3: First Python (1 minute) 

import requests

API_KEY = "your-api-key-here"
ENDPOINT = "https://api.serpbase.dev/google/search"

response = requests.post(
    ENDPOINT,
    headers={"X-API-Key": API_KEY},
    json={"q": "best serp api", "gl": "us", "num": 5}
)

data = response.json()
for i, item in enumerate(data["organic"], 1):
    print(f"{i}. {item['title']}")
    print(f"   {item['link']}")
    print(f"   {item.get('snippet', '')}\n")
Enter fullscreen mode Exit fullscreen mode

Output:

1. SERP API Comparison 2026
   https://serpbase.dev/blog/...
   Compare the best SERP APIs...

2. Best SERP API for SEO Tools
   ...
Enter fullscreen mode Exit fullscreen mode

Step 4: First Node.js (1 minute) 

const fetch = require('node-fetch');

const API_KEY = 'your-api-key-here';
const ENDPOINT = 'https://api.serpbase.dev/google/search';

fetch(ENDPOINT, {
  method: 'POST',
  headers: {
    'X-API-Key': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ q: 'best serp api', gl: 'us', num: 5 })
})
  .then(r => r.json())
  .then(data => {
    data.organic.forEach((item, i) => {
      console.log(`${i+1}. ${item.title}`);
      console.log(`   ${item.link}`);
    });
  });
Enter fullscreen mode Exit fullscreen mode

5 Core Parameters

Param Required Purpose
q ✓ Search query
gl ✗ Country (default us)
hl ✗ Language (default en)
num ✗ Result count (default 10)
device ✗ desktop / mobile / tablet

gl and hl determine which country's Google and which language you see.

5 Common Scenarios

Scenario 1: Multi-region Search 

for region in ["us", "uk", "jp", "cn"]:
    r = requests.post(ENDPOINT, headers=headers, json={
        "q": "best laptop",
        "gl": region,
        "hl": "en" if region != "cn" else "zh-CN",
    })
    print(f"{region}: {len(r.json()['organic'])} results")
Enter fullscreen mode Exit fullscreen mode

Scenario 2: Chinese Search 

r = requests.post(ENDPOINT, headers=headers, json={
    "q": "SERP API 哪家好",
    "gl": "cn",
    "hl": "zh-CN",
    "num": 10,
})
Enter fullscreen mode Exit fullscreen mode

Scenario 3: Add Caching 

import redis
REDIS = redis.Redis()

def fetch_with_cache(query):
    cached = REDIS.get(f"serp:{hash(query)}")
    if cached:
        return json.loads(cached)
    r = requests.post(ENDPOINT, headers=headers, json={"q": query})
    data = r.json()
    REDIS.setex(f"serp:{hash(query)}", 300, json.dumps(data))
    return data
Enter fullscreen mode Exit fullscreen mode

Scenario 4: Add Retry 

def fetch_with_retry(query, max_retries=3):
    for attempt in range(max_retries):
        try:
            r = requests.post(ENDPOINT, headers=headers, json={"q": query}, timeout=10)
            r.raise_for_status()
            return r.json()
        except Exception as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt + random.random())
Enter fullscreen mode Exit fullscreen mode

Scenario 5: Batch Concurrency (Mind QPS) 

import concurrent.futures

queries = ["python", "java", "go", "rust", "typescript"]

with concurrent.futures.ThreadPoolExecutor(max_workers=10) as ex:
    futures = [ex.submit(requests.post, ENDPOINT, headers=headers, json={"q": q}) for q in queries]
    for f in concurrent.futures.as_completed(futures):
        data = f.result().json()
        print(data["organic"][0]["title"])
Enter fullscreen mode Exit fullscreen mode

⚠️ Don't exceed 10 workers (SerpBase entry QPS limit 10).

4 Common Errors

Q1: 401 returned? 

# API key wrong or header name wrong
# Correct: X-API-Key (capital X-API + lowercase Key)
# Wrong: x-api-key (all lowercase), Authorization: Bearer xxx
Enter fullscreen mode Exit fullscreen mode

Q2: 429 returned? 

# QPS exceeded
# Check Retry-After header, wait specified time
# Or reduce worker count
Enter fullscreen mode Exit fullscreen mode

Q3: 500 returned? 

# Vendor failure or SERP API internal error
# Add retry + fallback
# Auto-refund 100% triggered
Enter fullscreen mode Exit fullscreen mode

Q4: Empty organic? 

# Query too niche / too specific
# Try more general queries
# Increase num to 20
Enter fullscreen mode Exit fullscreen mode

What's Next

Direction Resource
Deep tutorial "SERP API + Python: 30-minute SEO monitor"
LangChain integration "SERP API + LangChain in practice"
Slack alert bot "SERP API + Slack alert bot"
Cache strategies "SERP API cache layer: 5 strategies compared"
Rate limiting "SERP API rate limiting deep dive"

100 free searches: serpbase.dev signup, 5 minutes to your first query.

Top comments (0)