Serpent API Documentation

X-API-Key: sk_live_your_api_key_here

GET /api/search?q=keyword&api_key=sk_live_your_api_key_here

curl "https://apiserpent.com/api/search?q=best+seo+tools&num=30&engine=google&country=us" \
  -H "X-API-Key: sk_live_your_api_key"

{
  "success": true,
  "query": "best seo tools",
  "engine": "google",
  "country": "us",
  "pagesScraped": 3,
  "results": {
    "organic": [
      {
        "position": 1,
        "title": "10 Best SEO Tools for 2025",
        "url": "https://example.com/seo-tools",
        "snippet": "Discover the top SEO tools...",
        "displayedUrl": "example.com"
      }
    ],
    "relatedSearches": [{ "query": "free seo tools" }, { "query": "seo tools for beginners" }],
    "ads": { "top": [], "bottom": [], "totalCount": 0 },
    "peopleAlsoAsk": [],
    "richSnippets": []
  },
  "meta": {
    "totalOrganic": 30,
    "requestedNum": 30,
    "elapsed": "3200ms",
    "timestamp": "2025-01-15T10:30:00.000Z"
  }
}

curl "https://apiserpent.com/api/search/quick?q=weather+today&engine=yahoo&country=uk" \
  -H "X-API-Key: sk_live_your_api_key"

{
  "success": true,
  "query": "weather today",
  "engine": "yahoo",
  "country": "uk",
  "results": {
    "organic": [
      {
        "position": 1,
        "title": "Weather Forecast - Today",
        "url": "https://example.com/weather",
        "snippet": "Today's weather forecast...",
        "displayedUrl": "example.com"
      }
    ],
    "ads": { "top": [], "bottom": [], "totalCount": 0 },
    "peopleAlsoAsk": [],
    "relatedSearches": [{ "query": "weather tomorrow" }, { "query": "weather this week" }]
  },
  "meta": {
    "totalOrganic": 7,
    "elapsed": "1200ms",
    "timestamp": "2025-01-15T10:30:00.000Z"
  }
}

curl "https://apiserpent.com/api/news?q=artificial+intelligence&num=20&country=us" \
  -H "X-API-Key: sk_live_your_api_key"

{
  "success": true,
  "query": "artificial intelligence",
  "type": "news",
  "engine": "google",
  "country": "us",
  "pagesScraped": 2,
  "results": {
    "articles": [
      {
        "position": 1,
        "title": "AI Breakthroughs Reshape Industry",
        "url": "https://example.com/ai-news",
        "source": "Tech News Daily",
        "publishedTime": "2 hours ago",
        "snippet": "Major advances in AI...",
        "thumbnail": "https://..."
      }
    ],
    "totalResults": 20
  },
  "meta": {
    "totalArticles": 20,
    "elapsed": "1800ms",
    "timestamp": "2025-01-15T10:30:00.000Z"
  }
}

curl "https://apiserpent.com/api/images?q=mountain+landscape&num=20&engine=google" \
  -H "X-API-Key: sk_live_your_api_key"

{
  "success": true,
  "query": "mountain landscape",
  "type": "images",
  "engine": "google",
  "country": "us",
  "results": {
    "images": [
      {
        "position": 1,
        "title": "Beautiful Mountain View",
        "thumbnail": "https://tse.mm.bing.net/th/...",
        "original": "https://example.com/image.jpg",
        "width": 1920,
        "height": 1080,
        "source": "example.com",
        "pageUrl": "https://example.com/gallery"
      }
    ],
    "totalResults": 20
  },
  "meta": {
    "totalImages": 20,
    "elapsed": "2100ms",
    "timestamp": "2025-01-15T10:30:00.000Z"
  }
}

curl "https://apiserpent.com/api/videos?q=javascript+tutorial&num=10&engine=yahoo" \
  -H "X-API-Key: sk_live_your_api_key"

{
  "success": true,
  "query": "javascript tutorial",
  "type": "videos",
  "engine": "yahoo",
  "country": "us",
  "results": {
    "videos": [
      {
        "position": 1,
        "title": "Learn JavaScript - Full Course",
        "url": "https://www.youtube.com/watch?v=...",
        "description": "Complete JavaScript tutorial...",
        "publisher": "freeCodeCamp.org",
        "duration": "3:26:43",
        "publishedTime": "2024-01-15T10:00:00.000Z"
      }
    ],
    "totalResults": 10
  },
  "meta": {
    "totalVideos": 10,
    "elapsed": "2500ms",
    "timestamp": "2025-01-15T10:30:00.000Z"
  }
}

{
  "success": true,
  "count": 37,
  "countries": [
    { "code": "us", "region": "en-us" },
    { "code": "uk", "region": "en-gb" },
    ...
  ]
}

curl "https://apiserpent.com/api/search?q=beste+seo+tools&country=de" \
  -H "X-API-Key: sk_live_your_api_key"

{
  "success": true,
  "data": {
    "plan": "paid",
    "credits": 45.50,
    "costPerSearch": 0.0001,
    "priceTier": "default",
    "freeSearches": {
      "used": 87,
      "limit": 100,
      "remaining": 13
    }
  }
}

{
  "success": true,
  "query": "best seo tools",
  "engine": "google",
  "country": "us",
  "pagesScraped": 5,
  "results": {
    "organic": [{ "position", "title", "url", "snippet", "displayedUrl" }],
    "relatedSearches": [{ "query": "free seo tools" }, ...],
    "ads": { "top": [], "bottom": [], "totalCount": 0 },
    "peopleAlsoAsk": [],
    "richSnippets": []
  },
  "meta": { "totalOrganic", "requestedNum", "elapsed", "timestamp" }
}

{
  "success": true,
  "query": "best seo tools",
  "engine": "google",
  "country": "us",
  "results": [
    { "position": 1, "title": "...", "url": "..." }
  ],
  "meta": { "total": 50, "requestedNum": 50, "elapsed": "2450ms" }
}

{
  "error": "Query parameter \"q\" is required"
}

const API_KEY = 'sk_live_your_api_key';
const BASE = 'https://apiserpent.com';

// Web search with 30 results from Yahoo
async function webSearch(query, options = {}) {
  const params = new URLSearchParams({
    q: query,
    num: options.num || 10,
    engine: options.engine || 'google',
    country: options.country || 'us',
  });

  const res = await fetch(`${BASE}/api/search?${params}`, {
    headers: { 'X-API-Key': API_KEY }
  });

  const data = await res.json();
  if (!data.success) throw new Error(data.error);
  return data.results.organic;
}

// News search
async function newsSearch(query) {
  const res = await fetch(
    `${BASE}/api/news?q=${encodeURIComponent(query)}&num=20`,
    { headers: { 'X-API-Key': API_KEY } }
  );
  return (await res.json()).results.articles;
}

// Usage
const results = await webSearch('best seo tools', { num: 30, engine: 'yahoo' });
const news = await newsSearch('artificial intelligence');

import requests

API_KEY = 'sk_live_your_api_key'
BASE = 'https://apiserpent.com'
HEADERS = {'X-API-Key': API_KEY}

# Web search
def web_search(query, num=10, engine='google', country='us'):
    resp = requests.get(f'{BASE}/api/search', headers=HEADERS,
        params={'q': query, 'num': num, 'engine': engine, 'country': country})
    data = resp.json()
    if not data.get('success'):
        raise Exception(data.get('error', 'Search failed'))
    return data['results']['organic']

# News search
def news_search(query, num=20):
    resp = requests.get(f'{BASE}/api/news', headers=HEADERS,
        params={'q': query, 'num': num})
    return resp.json()['results']['articles']

# Image search
def image_search(query, num=50):
    resp = requests.get(f'{BASE}/api/images', headers=HEADERS,
        params={'q': query, 'num': num})
    return resp.json()['results']['images']

# Usage
results = web_search('best seo tools', num=50, engine='yahoo')
news = news_search('AI breakthroughs')
images = image_search('sunset beach')

# Web search (30 results from Yahoo in Germany)
curl "https://apiserpent.com/api/search?q=beste+seo+tools&num=30&engine=yahoo&country=de" \
  -H "X-API-Key: sk_live_your_api_key"

# Quick search
curl "https://apiserpent.com/api/search/quick?q=weather+today" \
  -H "X-API-Key: sk_live_your_api_key"

# News search
curl "https://apiserpent.com/api/news?q=technology&num=20&freshness=week" \
  -H "X-API-Key: sk_live_your_api_key"

# Image search
curl "https://apiserpent.com/api/images?q=mountain+landscape&num=50" \
  -H "X-API-Key: sk_live_your_api_key"

# Video search
curl "https://apiserpent.com/api/videos?q=javascript+tutorial&num=10" \
  -H "X-API-Key: sk_live_your_api_key"

# Check credits
curl "https://apiserpent.com/api/status" \
  -H "X-API-Key: sk_live_your_api_key"