> ## Documentation Index
> Fetch the complete documentation index at: https://docs.semust.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SERP API

> Get real-time search engine results data

## Endpoint

```
POST https://data.semust.com/v1/serp
```

## Authentication

All requests require authentication headers. See [Authentication](/authentication) for details.

| Header                | Type   | Description       |
| --------------------- | ------ | ----------------- |
| `SEMUST-API-USER`     | string | Your API username |
| `SEMUST-API-PASSWORD` | string | Your API password |

## Request Parameters

Send parameters as JSON in the request body with `Content-Type: application/json`.

| Parameter    | Type    | Required | Default  | Description                                |
| ------------ | ------- | -------- | -------- | ------------------------------------------ |
| `keyword`    | string  | Yes      | —        | The search keyword to fetch results for    |
| `language`   | string  | No       | `"en"`   | Language code (e.g., "en", "es", "fr")     |
| `country`    | string  | No       | `"US"`   | Country code (e.g., "US", "GB", "DE")      |
| `format`     | string  | No       | `"json"` | Response format: "json" or "raw"           |
| `mobile`     | boolean | No       | `false`  | Whether to fetch mobile results            |
| `start_page` | integer | No       | `1`      | Starting page number (1-indexed)           |
| `end_page`   | integer | No       | `1`      | Ending page number for multi-page requests |

<Warning>
  **Pagination:** Each page from `start_page` to `end_page` counts as a separate credit charge. Requesting pages 1-3 costs 3x the base credit cost.
</Warning>

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://data.semust.com/v1/serp \
    -H "Content-Type: application/json" \
    -H "SEMUST-API-USER: your_username" \
    -H "SEMUST-API-PASSWORD: your_password" \
    -d '{
      "keyword": "best seo tools",
      "language": "en",
      "country": "US",
      "format": "json"
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://data.semust.com/v1/serp",
      headers={
          "SEMUST-API-USER": "your_username",
          "SEMUST-API-PASSWORD": "your_password",
      },
      json={
          "keyword": "best seo tools",
          "language": "en",
          "country": "US",
          "format": "json",
      },
  )

  if response.status_code == 200:
      data = response.json()
      for result in data.get("organic", []):
          print(f"{result['rank']}. {result['title']}")
          print(f"   URL: {result['link']}")
          print(f"   Source: {result.get('source', 'N/A')}")
  else:
      print(f"Error [{response.status_code}]: {response.text}")
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://data.semust.com/v1/serp", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "SEMUST-API-USER": "your_username",
      "SEMUST-API-PASSWORD": "your_password",
    },
    body: JSON.stringify({
      keyword: "best seo tools",
      language: "en",
      country: "US",
      format: "json",
    }),
  });

  if (response.ok) {
    const data = await response.json();
    data.organic?.forEach((result) => {
      console.log(`${result.rank}. ${result.title}`);
      console.log(`   URL: ${result.link}`);
      console.log(`   Source: ${result.source || "N/A"}`);
    });
  } else {
    const text = await response.text();
    console.error(`Error [${response.status}]: ${text}`);
  }
  ```

  ```go Go theme={null}
  package main

  import (
      "bytes"
      "encoding/json"
      "fmt"
      "io"
      "net/http"
  )

  func main() {
      payload := map[string]interface{}{
          "keyword":  "best seo tools",
          "language": "en",
          "country":  "US",
          "format":   "json",
      }
      body, _ := json.Marshal(payload)

      req, _ := http.NewRequest("POST",
          "https://data.semust.com/v1/serp",
          bytes.NewBuffer(body))
      req.Header.Set("Content-Type", "application/json")
      req.Header.Set("SEMUST-API-USER", "your_username")
      req.Header.Set("SEMUST-API-PASSWORD", "your_password")

      resp, err := (&http.Client{}).Do(req)
      if err != nil {
          fmt.Printf("Request failed: %v\n", err)
          return
      }
      defer resp.Body.Close()
      respBody, _ := io.ReadAll(resp.Body)

      if resp.StatusCode == 200 {
          var data map[string]interface{}
          json.Unmarshal(respBody, &data)
          if organic, ok := data["organic"].([]interface{}); ok {
              for _, item := range organic {
                  r := item.(map[string]interface{})
                  fmt.Printf("%v. %v\n", r["rank"], r["title"])
                  fmt.Printf("   URL: %v\n", r["link"])
                  fmt.Printf("   Source: %v\n", r["source"])
              }
          }
      } else {
          fmt.Printf("Error %d: %s\n", resp.StatusCode, string(respBody))
      }
  }
  ```

  ```php PHP theme={null}
  <?php

  $payload = json_encode([
      "keyword"  => "best seo tools",
      "language" => "en",
      "country"  => "US",
      "format"   => "json",
  ]);

  $ch = curl_init("https://data.semust.com/v1/serp");
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      "Content-Type: application/json",
      "SEMUST-API-USER: your_username",
      "SEMUST-API-PASSWORD: your_password",
  ]);

  $response = curl_exec($ch);
  $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
  curl_close($ch);

  if ($httpCode === 200) {
      $data = json_decode($response, true);
      foreach ($data["organic"] ?? [] as $result) {
          echo $result["rank"] . ". " . $result["title"] . "\n";
          echo "   URL: " . $result["link"] . "\n";
          echo "   Source: " . ($result["source"] ?? "N/A") . "\n";
      }
  } else {
      echo "Error [{$httpCode}]: {$response}\n";
  }
  ```
</CodeGroup>

## Multi-Page Requests

To fetch multiple pages of results, use `start_page` and `end_page` parameters. The response will be an array of result objects, one per page.

```python Python theme={null}
import requests

response = requests.post(
    "https://data.semust.com/v1/serp",
    headers={
        "SEMUST-API-USER": "your_username",
        "SEMUST-API-PASSWORD": "your_password",
    },
    json={
        "keyword": "best seo tools",
        "format": "json",
        "start_page": 1,
        "end_page": 3,
    },
)

pages = response.json()
for i, page in enumerate(pages, start=1):
    print(f"--- Page {i} ---")
    for result in page.get("organic", []):
        print(f"  {result['rank']}. {result['title']}")
```

<Warning>
  **Credits:** Each page counts as a separate credit charge. Requesting pages 1-3 will use 3 credits.
</Warning>

## Response Format

### JSON Format (`format: "json"`)

Returns structured data with organic results, knowledge panels, and other SERP elements.

### Raw Format (`format: "raw"`)

Returns the raw HTML of the search results page. Useful for custom parsing or debugging.

## Example Response

### Single Page Response

```json theme={null}
{
  "organic": [
    {
      "rank": 1,
      "global_rank": 1,
      "title": "10 Best SEO Tools in 2025",
      "description": "Discover the top SEO tools for improving your website rankings...",
      "link": "https://example.com/best-seo-tools",
      "display_link": "https://example.com › best-seo-tools",
      "source": "Example.com",
      "extensions": [
        {
          "type": "site_link",
          "text": "Free Tools",
          "link": "https://example.com/free-tools",
          "rank": 1
        }
      ]
    },
    {
      "rank": 2,
      "global_rank": 6,
      "title": "SEO Software & Tools",
      "description": "Get more search traffic with our comprehensive SEO toolkit...",
      "link": "https://www.example.com",
      "display_link": "https://www.example.com",
      "source": "Example"
    }
  ],
  "knowledge": {
    "name": "SEO",
    "subtitle": "Search engine optimization",
    "description": "Search engine optimization is the process of...",
    "description_source": "Wikipedia",
    "facts": [
      { "key": "Full name", "value": [{ "text": "Search Engine Optimization" }] }
    ]
  },
  "people_also_ask": [
    {
      "rank": 1,
      "global_rank": 2,
      "question": "What is SEO?",
      "answer_source": "Wikipedia",
      "answers": [{ "rank": 1, "type": "answer", "value": { "text": "SEO is..." } }]
    }
  ],
  "related": [
    { "rank": 1, "global_rank": 10, "text": "SEO tools free", "link": "https://..." }
  ],
  "navigation": [{ "title": "Images", "href": "https://..." }],
  "perspectives": [{ "title": "SEO Tips", "author": "Expert", "source": "YouTube" }],
  "ai_overview": { "references": [], "texts": [] },
  "images": [{ "rank": 1, "title": "SEO Diagram", "link": "https://...", "image": "https://..." }],
  "top_ads": [{ "rank": 1, "title": "SEO Tool", "link": "https://...", "referral_link": "https://..." }],
  "bottom_ads": []
}
```

### Multi-Page Response

```json theme={null}
[
  {
    "organic": [
      { "rank": 1, "global_rank": 1, "title": "Result 1", "link": "https://...", "source": "..." }
    ],
    "knowledge": { "name": "...", "description": "..." },
    "people_also_ask": [{ "rank": 1, "question": "...", "answers": [] }],
    "navigation": [{ "title": "Images", "href": "https://..." }]
  },
  {
    "organic": [
      { "rank": 1, "global_rank": 11, "title": "Page 2 Result", "link": "https://...", "source": "..." }
    ],
    "related": [{ "rank": 1, "text": "Related search", "link": "https://..." }]
  }
]
```

## Response Fields Reference

### Root-Level Fields

Not all fields are present in every response. Fields are included only when data is available.

| Field             | Type   | Description                                       |
| ----------------- | ------ | ------------------------------------------------- |
| `organic`         | array  | Main organic search results                       |
| `knowledge`       | object | Knowledge panel information (Wikipedia-like data) |
| `people_also_ask` | array  | "People also ask" questions with answers          |
| `related`         | array  | Related searches at bottom of SERP                |
| `navigation`      | array  | Search type tabs (Images, Videos, News, etc.)     |
| `perspectives`    | array  | Social media and forum perspectives               |
| `ai_overview`     | object | AI-generated overview (Google AI Overviews)       |
| `images`          | array  | Image carousel results                            |
| `top_ads`         | array  | Sponsored results at top of page                  |
| `bottom_ads`      | array  | Sponsored results at bottom of page               |
| `overview`        | object | Knowledge graph metadata (kgmid, title)           |

### Organic Result Fields

| Field          | Type    | Description                                 |
| -------------- | ------- | ------------------------------------------- |
| `rank`         | integer | Position within organic results (1-indexed) |
| `global_rank`  | integer | Position across all SERP elements           |
| `title`        | string  | Result title                                |
| `description`  | string  | Result snippet/description                  |
| `link`         | string  | Destination URL                             |
| `display_link` | string  | Formatted URL as displayed in SERP          |
| `source`       | string  | Website or source name                      |
| `extensions`   | array   | Site links, dates, and other extensions     |
| `image`        | string  | Thumbnail URL (for video results)           |
| `duration`     | string  | Video duration (e.g., "19:10")              |
| `duration_sec` | integer | Video duration in seconds                   |

## Error Codes

```json Error Response theme={null}
{
  "error": "Your account does not have enough credits",
  "code": "INSUFFICIENT_CREDITS"
}
```

| Status | Code                   | Description                                 |
| ------ | ---------------------- | ------------------------------------------- |
| 400    | `INVALID_REQUEST`      | Invalid request format or malformed JSON    |
| 400    | `KEYWORD_REQUIRED`     | Missing required keyword parameter          |
| 400    | `INVALID_FORMAT`       | Format must be "json" or "raw"              |
| 401    | `INVALID_API_KEY`      | Authentication failed - invalid credentials |
| 402    | `INSUFFICIENT_CREDITS` | Your account does not have enough credits   |
| 429    | `RATE_LIMIT_EXCEEDED`  | Too many requests, please slow down         |
| 500    | `INTERNAL_ERROR`       | Server-side error occurred                  |
| 502    | `SERP_FAILED`          | Failed to retrieve SERP data                |
| 504    | `TIMEOUT`              | Request timed out                           |

## Credits & Rate Limits

<CardGroup cols={2}>
  <Card title="Credits">
    Each SERP request consumes credits from your account balance. Multi-page requests consume one credit per page.
  </Card>

  <Card title="Rate Limits">
    API requests are rate-limited to ensure fair usage. Contact support if you need higher limits.
  </Card>
</CardGroup>