API Documentation

Quick Start

Get up and running in three steps:

# 1. Set your API key
API_KEY="mk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

# 2. Make your first search
curl -G https://serpsearch.com/api/v1/search \
  -H "Authorization: Bearer $API_KEY" \
  --data-urlencode "query=web scraping best practices"

# 3. The response is JSON with organic_results, knowledge_graph, etc.

Authentication

All requests must include a valid API key as a Bearer token in the Authorization header.

Authorization: Bearer mk_live_xxxxxxxxxxxxxxxxxxxxxxxx

You can generate API keys from your dashboard. Keys are tied to your subscription and track usage against your monthly quota.

Web Search

Parameters

Response

{
  "organic_results": [
    {
      "title": "OpenAI",
      "url": "https://openai.com",
      "website": "openai.com",
      "position": 1,
      "description": "An AI research company...",
      "visible_url": "openai.com",
      "answer": null
    }
  ],
  "knowledge_graph": { ... },
  "definition_result": { ... },
  "people_also_ask": [ ... ],
  "weather_result": null
}

Example

curl -G "https://serpsearch.com/api/v1/search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "query=latest AI models" \
  -d "page=1"

Autocomplete

Parameters

Response

[
  {
    "title": "openai chatgpt",
    "additional_info": {
      "title": "ChatGPT",
      "description": "AI chatbot by OpenAI",
      "image": "https://..."
    }
  },
  {
    "title": "openai api"
  }
]

Example

curl -G "https://serpsearch.com/api/v1/autocomplete" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "query=openai"

Translation

Parameters

Response

{
  "translation": "Hello world",
  "sentences": [
    {
      "original": "Hola mundo",
      "translation": "Hello world"
    }
  ]
}

Example

curl -G "https://serpsearch.com/api/v1/translate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "query=Hola mundo" \
  -d "lang=en"

News

Parameters

Response

[
  {
    "group_name": "Top stories",
    "articles": [
      {
        "title": "OpenAI announces new model",
        "url": "https://example.com/article",
        "created_at": "2024-01-15T10:30:00Z"
      }
    ]
  }
]

Example

curl -G "https://serpsearch.com/api/v1/news" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "query=artificial intelligence"

Image Search

Parameters

Response

[
  {
    "title": "AI Generated Art",
    "url": "https://example.com/image.jpg",
    "source": "example.com",
    "alt": "AI generated artwork",
    "is_licensable": false,
    "preview": "https://example.com/thumb.jpg",
    "full": "https://example.com/full.jpg"
  }
]

Example

curl -G "https://serpsearch.com/api/v1/images" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "query=sunset photography" \
  -d "page=1"

Video Search

Parameters

Response

[
  {
    "title": "Introduction to Machine Learning",
    "url": "https://youtube.com/watch?v=...",
    "description": "A beginner-friendly guide...",
    "thumbnail": "https://i.ytimg.com/vi/.../default.jpg",
    "duration": "12:34",
    "website": "youtube.com",
    "channel_name": "Tech Channel",
    "upload_date": "2024-01-10"
  }
]

Example

curl -G "https://serpsearch.com/api/v1/videos" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "query=machine learning tutorial" \
  -d "page=1"

Maps Search

Parameters

Response

{
  "results": [
    {
      "name": "Central Park",
      "address": "New York, NY 10024",
      "rating": 4.8,
      "review_count": 120000,
      "price_range": null,
      "place_id": "ChIJ4zGFAZpYwokRGUGph3Mf37k",
      "lat": 40.7829,
      "lng": -73.9654,
      "opening_hours": "Open 24 hours",
      "rating_distribution": { "5": 90000, "4": 20000, "3": 5000, "2": 3000, "1": 2000 }
    }
  ]
}

Example

curl -G "https://serpsearch.com/api/v1/maps" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "query=coffee shops in manhattan"

Place Details

Parameters

Response

{
  "name": "Central Park",
  "address": "New York, NY 10024",
  "rating": 4.8,
  "review_count": 120000,
  "price_range": null,
  "place_id": "ChIJ4zGFAZpYwokRGUGph3Mf37k",
  "lat": 40.7829,
  "lng": -73.9654,
  "opening_hours": "Open 24 hours",
  "rating_distribution": { "5": 90000, "4": 20000, "3": 5000, "2": 3000, "1": 2000 }
}

Example

curl -G "https://serpsearch.com/api/v1/maps/place" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "query=ChIJ4zGFAZpYwokRGUGph3Mf37k"

Distance

Parameters

Response

{
  "distance_text": "5.2 mi",
  "duration_text": "15 mins",
  "distance_meters": 8368
}

Example

curl -G "https://serpsearch.com/api/v1/maps/distance" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "origin=Times Square, NYC" \
  --data-urlencode "destination=Central Park, NYC" \
  -d "mode=walking"

Reviews

Parameters

Response

{
  "reviews": [
    {
      "review": {
        "id": "abc123",
        "rating": 5,
        "text": "Amazing place, highly recommend!",
        "lang": "en",
        "created_at": "2024-01-10T08:00:00Z"
      },
      "user": {
        "name": "John D.",
        "image_url": "https://..."
      },
      "response": {
        "text": "Thank you for your kind words!",
        "created_at": "2024-01-11T10:00:00Z"
      }
    }
  ],
  "next_page": "eyJwYWdlIjoyf..."
}

Example

curl -G "https://serpsearch.com/api/v1/reviews" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d "place_id=ChIJ4zGFAZpYwokRGUGph3Mf37k" \
  -d "sort_by=newest"

Error Codes

All errors follow the same envelope shape:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please slow down your requests."
  }
}

Rate Limits & Quotas

Two separate limits apply to every request:

• Per-second rate limit -- enforced with a sliding window. Exceeding it returns RATE_LIMIT_EXCEEDED (HTTP 429) with a Retry-After: 1 header.
• Monthly quota -- resets with your billing period. Exceeding it returns QUOTA_EXCEEDED (HTTP 429). Upgrade your plan to increase your limit.

You can monitor your current usage from the usage dashboard. Need higher limits? View all plans or contact us for Enterprise pricing.

Response Headers

Every response (including errors) includes the following headers to help you track your usage and rate limits: