Serpshot

https://www.serpshot.com/docs
Admin
Serpshot is a unified Google Search API that supports web search and image search with customizable...
Tokens:4,850
Snippets:29
Trust Score:3.8
Update:8 months ago
Show doc for...
Tokens:
Raw
### Get Available Credits API (JavaScript)

Source: https://www.serpshot.com/docs/api/credit/available-credits

Illustrates how to get available credits using the Serpshot API with JavaScript. This example uses the 'fetch' API and requires an API Key.

```javascript
const apiKey = "YOUR_API_KEY";
const url = "http://127.0.0.1:8000/api/credit/record/available_credits";

fetch(url, {
    method: 'GET',
    headers: {
        'accept': 'application/json',
        'X-API-Key': apiKey
    }
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
```

--------------------------------

### Get Available Credits API (Go)

Source: https://www.serpshot.com/docs/api/credit/available-credits

A Go language example for fetching available credits from the Serpshot API. It demonstrates making an HTTP GET request with the necessary API Key header.

```go
package main

import (
	"fmt"
	"io/ioutil"
	"net/http"
)

func main() {
	apiKey := "YOUR_API_KEY"
	url := "http://127.0.0.1:8000/api/credit/record/available_credits"

	client := &http.Client{}
	req, err := http.NewRequest("GET", url, nil)
	if err != nil {
		fmt.Println("Error creating request:", err)
		return
	}

	req.Header.Add("accept", "application/json")
	req.Header.Add("X-API-Key", apiKey)

	resp, err := client.Do(req)
	if err != nil {
		fmt.Println("Error sending request:", err)
		return
	}
	defer resp.Body.Close()

	body, err := ioutil.ReadAll(resp.Body)
	if err != nil {
		fmt.Println("Error reading response body:", err)
		return
	}

	fmt.Println(string(body))
}
```

--------------------------------

### Install and Use Serpshot Python SDK

Source: https://www.serpshot.com/docs/introduction

This snippet shows how to install the Serpshot Python SDK using pip and then use it to perform a Google search. The SDK supports synchronous operations and provides automatic retry mechanisms.

```bash
pip install serpshot
```

```python
from serpshot import SerpShot

with SerpShot(api_key="your-api-key") as client:
    response = client.search("Python programming")
    print(f"Found {len(response.results)} results")
```

--------------------------------

### Get Available Credits API (Python)

Source: https://www.serpshot.com/docs/api/credit/available-credits

Provides a Python code example to retrieve available credits from the Serpshot API. It uses the 'requests' library and requires an API Key for authentication.

```python
import requests

api_key = "YOUR_API_KEY"
url = "http://127.0.0.1:8000/api/credit/record/available_credits"

headers = {
    "accept": "application/json",
    "X-API-Key": api_key
}

response = requests.get(url, headers=headers)

if response.status_code == 200:
    print(response.json())
else:
    print(f"Error: {response.status_code}")
```

--------------------------------

### Get Available Credits API - Go

Source: https://www.serpshot.com/docs/available-credits

This Go program demonstrates how to retrieve available credits from the Serpshot API. It constructs an HTTP GET request with the necessary headers for authentication and content type. The response body is then read and printed.

```go
package main

import (
	"fmt"
	"io/ioutil"
	"net/http"
	"strings"
)

func main() {
	apiKey := "YOUR_API_KEY"
	url := "http://127.0.0.1:8000/api/credit/record/available_credits"

	client := &http.Client{}
	req, err := http.NewRequest("GET", url, nil)
	if err != nil {
		fmt.Println("Error creating request:", err)
		return
	}

	req.Header.Add("accept", "application/json")
	req.Header.Add("X-API-Key", apiKey)

	res, err := client.Do(req)
	if err != nil {
		fmt.Println("Error sending request:", err)
		return
	}
	defer res.Body.Close()

	body, err := ioutil.ReadAll(res.Body)
	if err != nil {
		fmt.Println("Error reading response body:", err)
		return
	}

	fmt.Println(string(body))
}
```

--------------------------------

### Get Available Credits API (cURL)

Source: https://www.serpshot.com/docs/api/credit/available-credits

Demonstrates how to fetch the current user's available credits using the Serpshot API with cURL. Requires API Key authentication.

```cURL
curl -X 'GET'   'http://127.0.0.1:8000/api/credit/record/available_credits'   -H 'accept: application/json'   -H 'X-API-Key: YOUR_API_KEY'
```

--------------------------------

### GET /api/credit/record/available_credits

Source: https://www.serpshot.com/docs/api/credit/available-credits

Retrieves the current user's available credits. Authentication is handled via an API Key.

```APIDOC
## GET /api/credit/record/available_credits

### Description
Get current user's available credits using API Key authentication.

### Method
GET

### Endpoint
`/api/credit/record/available_credits`

### Parameters
#### Request Headers
- **X-API-Key** (string) - Required - Your API Key
- **accept** (string) - Required - application/json

### Request Example
```json
{
  "example": "curl -X 'GET'   'http://127.0.0.1:8000/api/credit/record/available_credits'   -H 'accept: application/json'   -H 'X-API-Key: YOUR_API_KEY'"
}
```

### Response
#### Success Response (200)
- **code** (integer) - The status code of the response.
- **msg** (string) - A message indicating the status of the operation.
- **data** (integer) - The number of available credits.

#### Response Example
```json
{
  "code": 200,
  "msg": "Success",
  "data": 992
}
```
```

--------------------------------

### Serpshot API Error Response Example

Source: https://www.serpshot.com/docs/error-codes

This JSON object represents a typical error response from the Serpshot API. It includes a 'code' for the HTTP status, a 'msg' for a human-readable error message, and 'data' which may contain additional details or be null.

```json
{
  "code": 401,
  "msg": "Unauthorized, please check if your API key is correct",
  "data": null
}
```

--------------------------------

### Perform Google Web Search using Python SDK

Source: https://www.serpshot.com/docs/index

This snippet demonstrates how to use the Serpshot Python SDK to perform a Google web search. It requires an API key and allows specifying search queries, number of results, page number, and location. The output includes the title, link, snippet, and position of each search result.

```python
from serpshot import SerpShot

# Using the official Python SDK
with SerpShot(api_key="YOUR_API_KEY") as client:
    response = client.search(
        query="coffee shops near me",
        num=10,
        page=1,
        location="US"
    )
    
    print(f"Found {len(response.results)} results")
    for result in response.results:
        print(f"{result.title}: {result.link}")

# Learn more: https://github.com/downdawn/serpshot-python
```

--------------------------------

### API Key Authentication

Source: https://www.serpshot.com/docs/authentication

Learn how to authenticate your API requests using API keys. Include your API key in the X-API-Key header with every request.

```APIDOC
## API Key Authentication

### Description
Serpshot uses API keys to authenticate requests. You can find your API key in your dashboard after signing up. Include your API key in the `X-API-Key` header with every request.

### Obtaining an API Key
1. Sign up for a Serpshot account
2. Navigate to the API Keys section in your dashboard
3. Click 'Create New API Key'
4. Copy your API key and store it securely

### Using Your API Key
Include your API key in the `X-API-Key` header with every request.

### Request Example (cURL)
```bash
curl -X POST https://api.serpshot.com/api/search/google \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"queries": ["coffee shops"], "num": 10}'
```

### Request Example (Python)
```python
import requests

headers = {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

data = {
    "queries": ["coffee shops"],
    "num": 10
}

response = requests.post(
    "https://api.serpshot.com/api/search/google",
    headers=headers,
    json=data
)
```

### Important
Replace `YOUR_API_KEY` with your actual API key.

### Security Best Practices
* Never expose your API key in client-side code
* Use environment variables to store API keys
* Rotate your API keys regularly
* Use different API keys for different environments
* Monitor your API usage for unusual activity
```

--------------------------------

### POST /api/search/google

Source: https://www.serpshot.com/docs/index

Unified Google search API supporting web search and image search. Use the type parameter to specify search type.

```APIDOC
## POST /api/search/google

### Description
Unified Google search API supporting web search and image search. Use the type parameter to specify search type.

### Method
POST

### Endpoint
/api/search/google

### Parameters
#### Request Body
- **queries** (array[string]) - Required - Search query list, supports up to 100 queries
- **type** (string) - Optional - Search type: search (web search) or image (image search) - Default: search
- **num** (integer) - Optional - Number of results per page, range: 1-100 - Default: 10
- **page** (integer) - Optional - Page number, starting from 1 - Default: 1
- **location** (string) - Optional - Search location: US, IN, JP, BR, GB, DE, CA, FR, ID, MX, SG - Default: US
- **lr** (string) - Optional - Content language restriction (e.g. en, zh-CN) - Default: en
- **gl** (string) - Optional - Geolocation (e.g. us, cn) - Default: us
- **hl** (string) - Optional - Interface language (e.g. en, zh-CN) - Default: en

### Request Headers
- **X-API-Key** (string) - Required - Your API Key
- **Content-Type** (string) - Required - application/json

### Request Example
```json
{
  "queries": ["coffee shops near me"],
  "type": "search",
  "num": 10,
  "page": 1,
  "location": "US"
}
```

### Response
#### Success Response (200)
- **code** (integer) - HTTP status code
- **msg** (string) - API response message
- **data** (object) - Contains search results and metadata
  - **results** (array) - List of search results
    - **title** (string) - Title of the search result
    - **link** (string) - URL of the search result
    - **snippet** (string) - Description of the search result
    - **position** (integer) - Position of the result in the search rankings
  - **total_results** (string) - Total number of results found
  - **search_time** (float) - Time taken for the search in seconds
  - **credits_used** (integer) - Number of credits used for the request

#### Response Example
```json
{
  "code": 200,
  "msg": "Success",
  "data": {
    "results": [
      {
        "title": "Best Coffee Shops Near Me - Local Guide",
        "link": "https://example.com/coffee-shops",
        "snippet": "Discover the best coffee shops in your area...",
        "position": 1
      },
      {
        "title": "Top 10 Coffee Shops Nearby",
        "link": "https://example.com/top-coffee",
        "snippet": "Find the perfect coffee shop near you...",
        "position": 2
      }
    ],
    "total_results": "About 12,300,000 results",
    "search_time": 0.45,
    "credits_used": 1
  }
}
```
```

--------------------------------

### POST /api/search/google

Source: https://www.serpshot.com/docs/introduction

This endpoint allows you to perform a Google search and retrieve real-time search results. You can specify search queries, the number of results, and other parameters.

```APIDOC
## POST /api/search/google

### Description
Performs a Google search and returns real-time search results in a structured JSON format. Handles all complexities of web scraping, proxy management, and CAPTCHA solving.

### Method
POST

### Endpoint
https://api.serpshot.com/api/search/google

### Parameters
#### Query Parameters
- **num** (integer) - Optional - The number of search results to return (default is 10).
- **location** (string) - Optional - The location to perform the search from (e.g., "United States", "London").
- **language** (string) - Optional - The language for the search results (e.g., "en", "es").

#### Request Body
- **queries** (array of strings) - Required - A list of search queries to perform.

### Request Example
```json
{
  "queries": ["coffee shops"],
  "num": 10
}
```

### Response
#### Success Response (200)
- **results** (array) - A list of search result objects, each containing details like title, link, snippet, etc.
- **search_parameters** (object) - Details about the search performed.

#### Response Example
```json
{
  "results": [
    {
      "title": "Best Coffee Shops in New York - Yelp",
      "link": "https://www.yelp.com/search?find_desc=Coffee+Shops",
      "snippet": "Find the best coffee shops in New York. ...",
      "position": 1
    }
  ],
  "search_parameters": {
    "query": "coffee shops",
    "num": 10,
    "location": "United States",
    "language": "en"
  }
}
```
```

--------------------------------

### POST /api/search/google

Source: https://www.serpshot.com/docs/authentication

Performs a Google search with the specified queries and returns the results.

```APIDOC
## POST /api/search/google

### Description
This endpoint allows you to perform Google searches and retrieve results. You need to authenticate using an API key provided in the `X-API-Key` header.

### Method
POST

### Endpoint
/api/search/google

### Parameters
#### Query Parameters
None

#### Request Body
- **queries** (array[string]) - Required - A list of search queries.
- **num** (integer) - Optional - The number of search results to return per query. Defaults to 10.

### Request Example
```json
{
  "queries": ["coffee shops", "best restaurants near me"],
  "num": 15
}
```

### Response
#### Success Response (200)
- **results** (array[object]) - A list of search results, where each object contains details about a search result.
  - **query** (string) - The original search query.
  - **organic_results** (array[object]) - A list of organic search results.
    - **title** (string) - The title of the search result.
    - **link** (string) - The URL of the search result.
    - **displayed_link** (string) - The displayed URL of the search result.
    - **snippet** (string) - A short description or snippet from the search result.
  - **ads** (array[object]) - A list of ads returned for the query (if any).
  - **related_searches** (array[string]) - A list of related search queries.

#### Response Example
```json
{
  "results": [
    {
      "query": "coffee shops",
      "organic_results": [
        {
          "title": "Best Coffee Shops in [City] - Yelp",
          "link": "https://www.yelp.com/search?find_desc=Coffee+Shops",
          "displayed_link": "www.yelp.com › search › Coffee+Shops",
          "snippet": "Find the best coffee shops in [City]. See ratings, photos, directions, phone numbers and more."
        }
      ],
      "ads": [],
      "related_searches": ["local coffee shops", "best espresso near me"]
    }
  ]
}
```
```

--------------------------------

### Make a Google Search API Call using cURL

Source: https://www.serpshot.com/docs/introduction

This snippet demonstrates how to make a POST request to the Serpshot Google search API using cURL. It requires your API key and specifies the search query and number of results in JSON format.

```bash
curl -X POST https://api.serpshot.com/api/search/google \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"queries": ["coffee shops"], "num": 10}'
```

--------------------------------

### Authenticate API Requests with API Key (Python)

Source: https://www.serpshot.com/docs/authentication

Shows how to authenticate API requests to Serpshot using Python's requests library. The API key is passed in the request headers, and the search parameters are sent as a JSON payload. Ensure you replace 'YOUR_API_KEY' with your actual key.

```python
import requests

headers = {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

data = {
    "queries": ["coffee shops"],
    "num": 10
}

response = requests.post(
    "https://api.serpshot.com/api/search/google",
    headers=headers,
    json=data
)
```
Tokens:
Raw