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/quick?q=weather+today&engine=google&country=uk" \
  -H "X-API-Key: sk_live_your_api_key"

{
  "success": true,
  "query": "weather today",
  "engine": "google",
  "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" }],
    "featuredSnippet": null,
    "aiOverview": null,
    "richSnippets": [],
    "videos": [],
    "shopping": []
  },
  "meta": {
    "totalOrganic": 7,
    "elapsed": "1200ms",
    "timestamp": "2026-03-03T10:30:00.000Z"
  }
}

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",
  "pages": 3,
  "results": {
    "organic": [
      {
        "position": 1,
        "title": "10 Best SEO Tools for 2026",
        "url": "https://example.com/seo-tools",
        "snippet": "Discover the top SEO tools...",
        "displayedUrl": "example.com"
      }
    ],
    "relatedSearches": [{ "query": "free seo tools" }],
    "ads": { "top": [], "bottom": [], "totalCount": 0 },
    "peopleAlsoAsk": [],
    "featuredSnippet": null,
    "aiOverview": null,
    "richSnippets": [],
    "videos": [],
    "shopping": []
  },
  "metadata": {
    "totalOrganicResults": 30,
    "hasAds": false,
    "hasRelatedSearches": true,
    "hasPeopleAlsoAsk": false,
    "hasVideos": false,
    "hasShopping": false,
    "hasFeaturedSnippet": false,
    "hasAiOverview": false,
    "source": "google"
  },
  "meta": {
    "totalOrganic": 30,
    "requestedNum": 30,
    "elapsed": "8500ms",
    "timestamp": "2026-03-10T10: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",
  "pages": 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...",
        "image": "https://example.com/ai-news-thumb.jpg",
      }
    ],
    "totalResults": 20
  },
  "meta": {
    "totalArticles": 20,
    "elapsed": "1800ms",
    "timestamp": "2026-03-03T10:30:00.000Z"
  }
}

curl "https://apiserpent.com/api/images?q=mountain+landscape&num=20" \
  -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://example.com/thumb/...",
        "original": "https://example.com/image.jpg",
        "width": null,  // reserved, not currently populated
        "height": null, // reserved, not currently populated
        "source": "example.com",
        "pageUrl": "https://example.com/gallery"
      }
    ],
    "totalResults": 20
  },
  "meta": {
    "totalImages": 20,
    "elapsed": "2100ms",
    "timestamp": "2026-03-03T10:30:00.000Z"
  }
}

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

{
  "success": true,
  "query": "python tutorial",
  "type": "videos",
  "engine": "ddg",
  "country": "us",
  "results": {
    "videos": [
      {
        "position": 1,
        "title": "Python Tutorial for Beginners",
        "url": "https://www.youtube.com/watch?v=...",
        "thumbnail": "https://tse2.mm.bing.net/th?...",
        "duration": "6:14:07",
        "viewCount": 45000000,
        "publishedTime": "2023-08-09T00:00:00.0000000",
        "publisher": "YouTube"
      }
    ],
    "totalResults": 20
  },
  "meta": {
    "totalVideos": 20,
    "elapsed": "3800ms",
    "timestamp": "2026-03-10T10:30:00.000Z"
  }
}

curl "https://apiserpent.com/api/shopping?q=nike+running+shoes&engine=google&num=10" \
  -H "X-API-Key: sk_live_your_api_key"

{
  "success": true,
  "query": "nike running shoes",
  "type": "shopping",
  "engine": "google",
  "country": "us",
  "results": {
    "shopping": [
      {
        "position": 1,
        "title": "Nike Vomero 18 Men's Road Running Shoes",
        "link": "https://www.nike.com/...",
        "source": "Nike",
        "price": "$150.00",
        "currency": "USD",
        "thumbnail": "https://example.com/product.jpg",
        "product_rating": 4.7,
        "product_reviews": 128,
        "sponsored": false,
        "snippet": "A stable, responsive daily trainer for neutral runners."
      }
    ],
    "totalResults": 10
  },
  "meta": {
    "totalShopping": 10,
    "elapsed": "4200ms",
    "timestamp": "2026-08-03T10:30:00.000Z"
  }
}

curl "https://apiserpent.com/api/ai/rank?keyword=best+seo+tools&domain=ahrefs.com&engines=claude,chatgpt" \
  -H "X-API-Key: sk_live_your_api_key"

curl "https://apiserpent.com/api/ai/rank/claude?keyword=best+crm+software&domain=hubspot.com" \
  -H "X-API-Key: sk_live_your_api_key"

curl "https://apiserpent.com/api/social/youtube/search?q=machine+learning&type=video&num=10&order=viewCount" \
  -H "X-API-Key: sk_live_your_api_key"

curl "https://apiserpent.com/api/social/youtube/video?id=dQw4w9WgXcQ" \
  -H "X-API-Key: sk_live_your_api_key"

curl "https://apiserpent.com/api/social/youtube/channel?handle=@mkbhd&include_videos=true&video_count=5" \
  -H "X-API-Key: sk_live_your_api_key"

curl "https://apiserpent.com/api/social/instagram/profile?username=natgeo" \
  -H "X-API-Key: sk_live_your_api_key"

curl "https://apiserpent.com/api/linkedin/company?url=https://www.linkedin.com/company/microsoft" \
  -H "X-API-Key: sk_live_your_api_key"

curl "https://apiserpent.com/api/linkedin/jobs?keywords=software+engineer&location=San+Francisco+Bay+Area&start=0" \
  -H "X-API-Key: sk_live_your_api_key"

curl "https://apiserpent.com/api/linkedin/job?job_id=3901234567" \
  -H "X-API-Key: sk_live_your_api_key"

curl "https://apiserpent.com/api/linkedin/profile?username=williamhgates" \
  -H "X-API-Key: sk_live_your_api_key"

curl "https://apiserpent.com/api/linkedin/profile/full?username=williamhgates" \
  -H "X-API-Key: sk_live_your_api_key"

curl "https://apiserpent.com/api/linkedin/posts?username=williamhgates" \
  -H "X-API-Key: sk_live_your_api_key"

BASE_URL="${SERPENT_BASE_URL:-http://localhost:3001}"
curl --get "$BASE_URL/api/maps/search/quick" \
  -H "X-API-Key: YOUR_API_KEY" \
  --data-urlencode "q=coffee" \
  --data-urlencode "location=New York, NY" \
  --data-urlencode "country=us"

{
  "success": true,
  "type": "maps",
  "endpoint": "quick",
  "places": [{
    "rank": 1, "place_id": "...", "name": "Example Coffee",
    "website": "https://example.com", "rating": 4.6,
    "detail_status": "complete"
  }],
  "counts": { "requested": 20, "discovered": 20, "returned": 20, "fully_enriched": 19, "core_only": 1 },
  "meta": { "elapsed_ms": 27498, "partial": true }
}

curl --get "$BASE_URL/api/maps/search" \
  -H "X-API-Key: YOUR_API_KEY" \
  --data-urlencode "q=coffee" \
  --data-urlencode "location=New York, NY"

curl --get "$BASE_URL/api/maps/place" \
  -H "X-API-Key: YOUR_API_KEY" \
  --data-urlencode "place_id=ChIJ..."

curl --get "$BASE_URL/api/maps/reviews" \
  -H "X-API-Key: YOUR_API_KEY" \
  --data-urlencode "place_id=ChIJ..." \
  --data-urlencode "sort=newest"

{
  "success": true,
  "count": 112,
  "countries": [
    { "code": "us", "region": "us" },
    { "code": "uk", "region": "uk" },
    ...
  ]
}

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

curl "https://apiserpent.com/api/search?q=meilleurs+outils+seo&country=fr&language=fr" \
  -H "X-API-Key: sk_live_your_api_key"

{
  "success": true,
  "data": {
    "plan": "paid",
    "credits": 45.50,
    "costPerSearch": 0.0006,
    "priceTier": "default",
    "freeSearches": {
      "used": 4,
      "limit": 10,
      "remaining": 6,
      "scope": "all endpoints"
    }
  }
}

{
  "success": true,
  "query": "best seo tools",
  "engine": "google",
  "country": "us",
  "pages": 5,
  "results": {
    "organic": [{ "position", "title", "url", "snippet", "displayedUrl" }],
    "relatedSearches": [{ "query": "free seo tools" }, ...],
    "ads": { "top": [], "bottom": [], "totalCount": 0 },
    "peopleAlsoAsk": [],
    "featuredSnippet": null,     // Google only
    "aiOverview": null,          // Google Deep with include_aio=true
    "richSnippets": [],
    "videos": [],               // Google, Yahoo/Bing
    "shopping": []
  },
  "metadata": {
    "totalOrganicResults": 50,
    "hasAds": false,
    "hasRelatedSearches": true,
    "hasPeopleAlsoAsk": false,
    "hasVideos": false,
    "hasShopping": false,
    "hasFeaturedSnippet": false,
    "hasAiOverview": false,
    "source": "google"
  },
  "meta": { "totalOrganic", "requestedNum", "elapsed", "timestamp" }
}

{
  "success": true,
  "query": "best seo tools",
  "engine": "google",
  "country": "us",
  "results": [
    { "position": 1, "title": "...", "url": "..." },
    // with pixel_position=true:
    {
      "position": 2,
      "title": "...",
      "url": "...",
      "pixel_position": 847,
      "pixel_box": { "x": 180, "y": 847, "w": 600, "h": 96 }
    }
  ],
  "meta": { "total": 50, "requestedNum": 50, "elapsed": "2450ms" }
}

{
  "success": true,
  "query": "artificial intelligence",
  "type": "news",
  "engine": "google",
  "country": "us",
  "results": [
    { "position": 1, "title": "...", "url": "...", "source": "..." }
  ],
  "meta": { "total": 20, "elapsed": "1800ms" }
}

{
  "success": true,
  "query": "mountain landscape",
  "type": "images",
  "engine": "google",
  "country": "us",
  "results": [
    { "position": 1, "title": "...", "original": "...", "thumbnail": "..." }
  ],
  "meta": { "total": 50, "elapsed": "1200ms" }
}

// 400 Bad Request
{ "error": "Query parameter \"q\" is required" }

// 401 Unauthorized
{ "error": "Unauthorized", "message": "API key required. Provide X-API-Key header or api_key query parameter." }

// 402 Payment Required
{ "error": "Payment Required", "message": "Insufficient credits", "credits": 0, "costPerSearch": 0.0001 }

// 503 Service Unavailable
{ "success": false, "error": "Temporarily unavailable", "message": "Please try again later." }

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

// Quick web search (free-tier eligible)
async function quickSearch(query, engine = 'google') {
  const res = await fetch(
    `${BASE}/api/search/quick?q=${encodeURIComponent(query)}&engine=${engine}`,
    { headers }
  );
  return (await res.json()).results.organic;
}

// Deep web search (up to 100 results)
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 });
  const data = await res.json();
  if (!data.success) throw new Error(data.error);
  return data.results.organic;
}

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

// Video search
async function videoSearch(query, engine = 'ddg') {
  const res = await fetch(
    `${BASE}/api/videos?q=${encodeURIComponent(query)}&engine=${engine}`,
    { headers }
  );
  return (await res.json()).results.videos;
}

// AI Ranking check
async function aiRank(keyword, domain) {
  const res = await fetch(
    `${BASE}/api/ai/rank?keyword=${encodeURIComponent(keyword)}&domain=${domain}`,
    { headers }
  );
  return (await res.json());
}

// YouTube search (free-tier eligible)
async function ytSearch(query, num = 10) {
  const res = await fetch(
    `${BASE}/api/social/youtube/search?q=${encodeURIComponent(query)}&num=${num}`,
    { headers }
  );
  return (await res.json());
}

// Google Maps quick place search (free-tier eligible)
async function mapsQuickSearch(query, options = {}) {
  const params = new URLSearchParams({
    q: query,
    location: options.location || '',
    country: options.country || 'us',
  });
  const res = await fetch(`${BASE}/api/maps/search/quick?${params}`, { headers });
  const data = await res.json();
  return data.places;
}

// Google Maps place details
async function mapsPlace(placeId) {
  const res = await fetch(`${BASE}/api/maps/place?place_id=${encodeURIComponent(placeId)}`, { headers });
  return (await res.json()).place;
}

// Google Maps reviews (paginate with next_page_token)
async function mapsReviews(placeId, { sort = 'relevant', pageToken } = {}) {
  const params = new URLSearchParams({ place_id: placeId, sort });
  if (pageToken) params.set('page_token', pageToken);
  const res = await fetch(`${BASE}/api/maps/reviews?${params}`, { headers });
  return await res.json();
}

// Usage
const quick = await quickSearch('weather today');
const deep = await webSearch('best seo tools', { num: 50 });
const news = await newsSearch('artificial intelligence');
const videos = await videoSearch('python tutorial');
const ranking = await aiRank('best crm software', 'hubspot.com');
const yt = await ytSearch('machine learning');
const places = await mapsQuickSearch('coffee shops', { location: 'New York, NY' });
const place = await mapsPlace(places[0].place_id);
const reviews = await mapsReviews(places[0].place_id, { sort: 'newest' });

import requests

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

# Quick search (free-tier eligible)
def quick_search(query, engine='google'):
    resp = requests.get(f'{BASE}/api/search/quick', headers=HEADERS,
        params={'q': query, 'engine': engine})
    return resp.json()['results']['organic']

# Deep web search (up to 100 results)
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']

# Video search
def video_search(query, engine='ddg'):
    resp = requests.get(f'{BASE}/api/videos', headers=HEADERS,
        params={'q': query, 'engine': engine})
    return resp.json()['results']['videos']

# AI Ranking
def ai_rank(keyword, domain=None, engines='claude,chatgpt'):
    params = {'keyword': keyword, 'engines': engines}
    if domain:
        params['domain'] = domain
    resp = requests.get(f'{BASE}/api/ai/rank', headers=HEADERS, params=params)
    return resp.json()

# YouTube search (free-tier eligible)
def yt_search(query, num=10):
    resp = requests.get(f'{BASE}/api/social/youtube/search', headers=HEADERS,
        params={'q': query, 'num': num})
    return resp.json()

# Instagram profile (free-tier eligible)
def ig_profile(username):
    resp = requests.get(f'{BASE}/api/social/instagram/profile', headers=HEADERS,
        params={'username': username})
    return resp.json()

# Google Maps quick place search (free-tier eligible)
def maps_quick_search(query, location=None, country='us'):
    params = {'q': query, 'country': country}
    if location:
        params['location'] = location
    resp = requests.get(f'{BASE}/api/maps/search/quick', headers=HEADERS, params=params)
    return resp.json()['places']

# Google Maps place details
def maps_place(place_id):
    resp = requests.get(f'{BASE}/api/maps/place', headers=HEADERS,
        params={'place_id': place_id})
    return resp.json()['place']

# Google Maps reviews (paginate with next_page_token)
def maps_reviews(place_id, sort='relevant', page_token=None):
    params = {'place_id': place_id, 'sort': sort}
    if page_token:
        params['page_token'] = page_token
    resp = requests.get(f'{BASE}/api/maps/reviews', headers=HEADERS, params=params)
    return resp.json()

# Usage
results = web_search('best seo tools', num=50, engine='google')
news = news_search('AI breakthroughs')
images = image_search('sunset beach')
videos = video_search('python tutorial')
ranking = ai_rank('best crm software', domain='hubspot.com')
yt = yt_search('machine learning')
ig = ig_profile('natgeo')
places = maps_quick_search('coffee shops', location='New York, NY')
place = maps_place(places[0]['place_id'])
reviews = maps_reviews(places[0]['place_id'], sort='newest')

# Quick search (free-tier eligible)
curl "https://apiserpent.com/api/search/quick?q=weather+today&engine=google" \
  -H "X-API-Key: sk_live_your_api_key"

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

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

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

# Video search
curl "https://apiserpent.com/api/videos?q=python+tutorial&engine=ddg&duration=medium" \
  -H "X-API-Key: sk_live_your_api_key"

# AI Ranking (Claude + ChatGPT)
curl "https://apiserpent.com/api/ai/rank?keyword=best+crm+software&domain=hubspot.com&engines=claude,chatgpt" \
  -H "X-API-Key: sk_live_your_api_key"

# Single AI engine ranking
curl "https://apiserpent.com/api/ai/rank/gemini?keyword=best+seo+tools" \
  -H "X-API-Key: sk_live_your_api_key"

# YouTube search (free-tier eligible)
curl "https://apiserpent.com/api/social/youtube/search?q=machine+learning&num=10" \
  -H "X-API-Key: sk_live_your_api_key"

# YouTube video details
curl "https://apiserpent.com/api/social/youtube/video?id=dQw4w9WgXcQ" \
  -H "X-API-Key: sk_live_your_api_key"

# YouTube channel details
curl "https://apiserpent.com/api/social/youtube/channel?handle=@mkbhd&include_videos=true" \
  -H "X-API-Key: sk_live_your_api_key"

# Instagram profile (free-tier eligible)
curl "https://apiserpent.com/api/social/instagram/profile?username=natgeo" \
  -H "X-API-Key: sk_live_your_api_key"

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

# Get pricing (no API key required)
curl "https://apiserpent.com/api/pricing"