# Schedule SERP

Below you will find a detailed description of the fields you can use for setting a task.\
\
All POST data should be sent in the JSON format (UTF-8 encoding). The task setting is done using the POST method when the array of tasks is sent into json format. We recommend to set up to 100 tasks at a time. Such limits were set due to the variations of task setting methods that you may use.

{% hint style="danger" %}
Requires authentication
{% endhint %}

<mark style="color:green;">`POST`</mark> `https://api.serphouse.com/serp/schedule`

#### Headers

| Name                                            | Type   | Description              |
| ----------------------------------------------- | ------ | ------------------------ |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer \<YOUR\_API\_KEY> |
| Content-Type<mark style="color:red;">\*</mark>  | String | application/json         |

#### Request Body

| Name                                         | Type    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| -------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| q<mark style="color:red;">\*</mark>          | string  | Search phrase that you want to search                                                                                                                                                                                                                                                                                                                                                                                                                |
| domain<mark style="color:red;">\*</mark>     | string  | <p>Choose google ,bing or yahoo domain.</p><p>You can get the list of available search engines by making a separate request to the  <a href="/pages/laBnxuxvKvStquXcYCfl">List of Search Engines</a></p>                                                                                                                                                                                                                                             |
| lang<mark style="color:red;">\*</mark>       | string  | <p>You can set language for e.g. <code>en</code> for english <code>fr</code> for french.<br>Get the list of available languages by making a separate request to the <a href="/pages/T3o6bzC5LzinD9qIGamk">List of Language</a></p>                                                                                                                                                                                                                   |
| device<mark style="color:red;">\*</mark>     | string  | <p>Device can be<br><code>desktop</code> To extract desktop result<br><code>mobile</code> To extract mobile result</p>                                                                                                                                                                                                                                                                                                                               |
| serp\_type<mark style="color:red;">\*</mark> | string  | <p>Serp type can be<br><code>web</code> get structured json result search engines web result</p><p><code>news</code> Get news result from search engines<br><code>image</code> Search image over searchengines and get json result</p>                                                                                                                                                                                                               |
| loc<mark style="color:red;">\*</mark>        | string  | <p>Optional field if you specify <code>loc\_id</code><br><strong>when choose yahoo domain then field is optional</strong><br><strong>You must choose one of the fields: <code>loc\_id</code> or <code>loc</code></strong><br>You can receive the list of available locations of search engines with their loc\_id by making a separate request to the  <a href="/pages/jHif4hVWEf1ax1cYtvip">List of Locations</a></p>                               |
| loc\_id<mark style="color:red;">\*</mark>    | integer | <p>Optional field if you specify <code>loc</code><br><strong>you must choose one of the fields: <code>loc\_id</code> or <code>loc</code></strong><br>You can receive the list of available locations of search engines with their loc\_id by making a separate request to the<br><a href="/pages/jHif4hVWEf1ax1cYtvip">List of Locations</a> </p>                                                                                                    |
| verbatim                                     | integer | Set Google Verbatim search, Parameter value can be `0` or `1`                                                                                                                                                                                                                                                                                                                                                                                        |
| gfilter                                      | integer | Parameter defines if the filters for 'Similar Results' and 'Omitted Results' are on or off. It can be set to `1` (default) to enable these filters, or `0` to disable these filters.                                                                                                                                                                                                                                                                 |
| page                                         | integer | Define google/bing serp result page number                                                                                                                                                                                                                                                                                                                                                                                                           |
| num\_result                                  | integer | Define number of result you want to get per page.                                                                                                                                                                                                                                                                                                                                                                                                    |
| postback\_url                                | url     | <p>return URL for sending task results</p><p>If you specify the <a href="/pages/lJY2QpyhY9Bdmw36MR6d#postback-url">Postback URL</a> there will be no need to use Get SERP Tasks Results for obtaining results. We will send the result of a completed task by a POST request to the URL as soon as the task is completed. You can change your webhook setting from <a href="https://app.serphouse.com/wehook-setting">Webhook Settings Page</a>.</p> |
| pingback\_url                                | url     | <p><a href="/pages/lJY2QpyhY9Bdmw36MR6d#pingback-url">Pingback URL</a> is Notification URL of a completed task,<br><strong>When a task is completed we will notify you by GET request sent to the URL you have specified.</strong> You can change your webhook setting from <a href="https://app.serphouse.com/wehook-setting">Webhook Settings Page</a>.</p>                                                                                        |
| date\_range                                  | String  | <p>Sometimes you may want to only find information published during a specific time frame. To limit Google results by date</p><p>Parameter values can be comma seprated date range <code>YYYY-MM-DD,YYYY-MM-DD</code> OR</p><p><code>h</code> Past hour</p><p><code>d</code> Past 24 hours</p><p><code>w</code> Past week</p><p><code>m</code> Past month</p><p><code>y</code> Past year </p>                                                        |

{% tabs %}
{% tab title="200: OK Successful operation" %}

```json
{
    "status": "success",
    "msg": "Task(s) successfully scheduled",
    "results": [
        {
            "user_id": 4281,
            "se": "google",
            "q": "Coffee",
            "domain": "google.com",
            "lang": "en",
            "country_iso": "US",
            "loc": "Alba,Texas,United States",
            "lat": "32.79",
            "long": "-95.63",
            "device": "desktop",
            "serp_type": "web",
            "verbatim": 0,
            "gfilter": 1,
            "pingback_url": null,
            "postback_url": "https://webhook.site/8f885f1f-c38a-4a10-8506-335441213208",
            "is_scheduled": 1,
            "page": 1,
            "num_result": 10,
            "updated_at": "2023-05-30T10:29:54.000000Z",
            "created_at": "2023-05-30T10:29:54.000000Z",
            "id": 77224194
        },
        {
            "user_id": 4281,
            "se": "google",
            "q": "Tea",
            "domain": "google.com",
            "lang": "en",
            "country_iso": "US",
            "loc": "Alba,Texas,United States",
            "lat": "32.79",
            "long": "-95.63",
            "device": "desktop",
            "serp_type": "web",
            "verbatim": 0,
            "gfilter": 1,
            "pingback_url": "https://webhook.site/8f885f1f-c38a-4a10-8506-335441213208",
            "postback_url": null,
            "is_scheduled": 1,
            "page": 1,
            "num_result": 10,
            "updated_at": "2023-05-30T10:29:54.000000Z",
            "created_at": "2023-05-30T10:29:54.000000Z",
            "id": 77224195
        },
        {
            "user_id": 4281,
            "se": "google",
            "q": "Cold Cofee",
            "domain": "google.co.uk",
            "lang": "ar",
            "country_iso": "GB",
            "loc": "London,England,United Kingdom",
            "lat": "51.51",
            "long": "-0.13",
            "device": "desktop",
            "serp_type": "image",
            "verbatim": 0,
            "gfilter": 1,
            "pingback_url": null,
            "postback_url": "https://webhook.site/8f885f1f-c38a-4a10-8506-335441213208",
            "is_scheduled": 1,
            "page": 1,
            "num_result": 10,
            "updated_at": "2023-05-30T10:29:54.000000Z",
            "created_at": "2023-05-30T10:29:54.000000Z",
            "id": 77224196
        }
    ]
}
```

{% endtab %}

{% tab title="400: Bad Request Failed validation" %}

```json
{
    "status": "error",
    "msg": "validation_error",
    "error": {
        "data.0.q": [
            "The data.0.q field is required."
        ]
    }
}
```

{% endtab %}

{% tab title="402: Payment Required Failed operation" %}

```json
{
    "status": "error",
    "msg": "Your SERPHouse account has either run out of available credits (try upgrading your Plan), or there is a payment problem. Current available credit is -> -1",
    "error": ""
}
```

{% endtab %}

{% tab title="401: Unauthorized Unauthenticated" %}

```json
{
    "status": "error",
    "msg": "Unauthenticated"
}
```

{% endtab %}
{% endtabs %}

## Example request:

{% tabs %}
{% tab title="BASH" %}

```bash
curl --location --request POST 'https://api.serphouse.com/serp/schedule' \
--header 'Authorization: Bearer <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "data": [
        {
            "q": "Coffee",
            "domain": "google.com",
            "lang": "en",
            "device": "desktop",
            "serp_type": "web",
            "loc": "Alba,Texas,United States",
            "verbatim": 0,
            "postback_url": "https://webhook.site/8f885f1f-c38a-4a10-8506-335441213208",
            "page": 1,
            "num_result":10
        },
        {
            "q": "Tea",
            "domain": "google.com",
            "lang": "en",
            "device": "desktop",
            "serp_type": "web",
            "loc": "Alba,Texas,United States",
            "verbatim": 0,
            "pingback_url": "https://webhook.site/8f885f1f-c38a-4a10-8506-335441213208",
            "page": 1,
            "num_result":10
        },
        {
            "domain": "google.co.uk",
            "lang": "ar",
            "q": "Cold Cofee",
            "loc": "London,England,United Kingdom",
            "postback_url": "https://webhook.site/8f885f1f-c38a-4a10-8506-335441213208",
            "device": "desktop",
            "serp_type": "image",
            "num_result":10
        }
    ]
}'
```

{% endtab %}

{% tab title="RUBY" %}

```ruby
require "uri"
require "json"
require "net/http"

url = URI("https://api.serphouse.com/serp/schedule")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = "Bearer <YOUR_API_KEY>"
request["Content-Type"] = "application/json"
request.body = JSON.dump({
  "data": [
    {
      "q": "Coffee",
      "domain": "google.com",
      "lang": "en",
      "device": "desktop",
      "serp_type": "web",
      "loc": "Alba,Texas,United States",
      "verbatim": 0,
      "postback_url": "https://webhook.site/8f885f1f-c38a-4a10-8506-335441213208",
      "page": 1,
      "num_result": 10
    },
    {
      "q": "Tea",
      "domain": "google.com",
      "lang": "en",
      "device": "desktop",
      "serp_type": "web",
      "loc": "Alba,Texas,United States",
      "verbatim": 0,
      "pingback_url": "https://webhook.site/8f885f1f-c38a-4a10-8506-335441213208",
      "page": 1,
      "num_result": 10
    },
    {
      "domain": "google.co.uk",
      "lang": "ar",
      "q": "Cold Cofee",
      "loc": "London,England,United Kingdom",
      "postback_url": "https://webhook.site/8f885f1f-c38a-4a10-8506-335441213208",
      "device": "desktop",
      "serp_type": "image",
      "num_result": 10
    }
  ]
})

response = https.request(request)
puts response.read_body

```

{% endtab %}

{% tab title="PYTHON" %}

```python
import requests
import json

url = "https://api.serphouse.com/serp/schedule"

payload = json.dumps({
  "data": [
    {
      "q": "Coffee",
      "domain": "google.com",
      "lang": "en",
      "device": "desktop",
      "serp_type": "web",
      "loc": "Alba,Texas,United States",
      "verbatim": 0,
      "postback_url": "https://webhook.site/8f885f1f-c38a-4a10-8506-335441213208",
      "page": 1,
      "num_result": 10
    },
    {
      "q": "Tea",
      "domain": "google.com",
      "lang": "en",
      "device": "desktop",
      "serp_type": "web",
      "loc": "Alba,Texas,United States",
      "verbatim": 0,
      "pingback_url": "https://webhook.site/8f885f1f-c38a-4a10-8506-335441213208",
      "page": 1,
      "num_result": 10
    },
    {
      "domain": "google.co.uk",
      "lang": "ar",
      "q": "Cold Cofee",
      "loc": "London,England,United Kingdom",
      "postback_url": "https://webhook.site/8f885f1f-c38a-4a10-8506-335441213208",
      "device": "desktop",
      "serp_type": "image",
      "num_result": 10
    }
  ]
})
headers = {
  'Authorization': 'Bearer <YOUR_API_KEY>',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

```

{% endtab %}

{% tab title="NODE.JS" %}

```javascript
var axios = require('axios');
var data = JSON.stringify({
  "data": [
    {
      "q": "Coffee",
      "domain": "google.com",
      "lang": "en",
      "device": "desktop",
      "serp_type": "web",
      "loc": "Alba,Texas,United States",
      "verbatim": 0,
      "postback_url": "https://webhook.site/8f885f1f-c38a-4a10-8506-335441213208",
      "page": 1,
      "num_result": 10
    },
    {
      "q": "Tea",
      "domain": "google.com",
      "lang": "en",
      "device": "desktop",
      "serp_type": "web",
      "loc": "Alba,Texas,United States",
      "verbatim": 0,
      "pingback_url": "https://webhook.site/8f885f1f-c38a-4a10-8506-335441213208",
      "page": 1,
      "num_result": 10
    },
    {
      "domain": "google.co.uk",
      "lang": "ar",
      "q": "Cold Cofee",
      "loc": "London,England,United Kingdom",
      "postback_url": "https://webhook.site/8f885f1f-c38a-4a10-8506-335441213208",
      "device": "desktop",
      "serp_type": "image",
      "num_result": 10
    }
  ]
});

var config = {
  method: 'post',
  url: 'https://api.serphouse.com/serp/schedule',
  headers: { 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer <YOUR_API_KEY>'
  },
  data : data
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
$serphouse = new SERPHouse\SERPHouseClient('YOUR_API_KEY');
$body = [
    'data' => [
        [
            'q' => 'Coffee',
            'domain' => 'google.com',
            'lang' => 'en',
            'device' => 'desktop',
            'serp_type' => 'web',
            'loc' => 'Alba,Texas,United States',
            'verbatim' => 0,
            'postback_url' => 'https://webhook.site/8f885f1f-c38a-4a10-8506-335441213208',
            'page' => 1,
            'num_result' => 100,
        ],
        [
            'q' => 'Tea',
            'domain' => 'google.com',
            'lang' => 'en',
            'device' => 'desktop',
            'serp_type' => 'web',
            'loc' => 'Alba,Texas,United States',
            'verbatim' => 0,
            'pingback_url' => 'https://webhook.site/8f885f1f-c38a-4a10-8506-335441213208',
            'page' => 1,
            'num_result' => 100,
        ],
        [
            'domain' => 'google.co.uk',
            'lang' => 'ar',
            'q' => 'Cold Cofee',
            'loc' => 'London,England,United Kingdom',
            'postback_url' => 'https://webhook.site/8f885f1f-c38a-4a10-8506-335441213208',
            'device' => 'desktop',
            'serp_type' => 'image',
            'num_result' => 100,
        ],
    ],
];

$res = $serphouse->serpApi->schedule($body);
echo $res->getResponse();

```

{% endtab %}

{% tab title="JAVA" %}

```java
OkHttpClient client = new OkHttpClient().newBuilder().build();
MediaType mediaType = MediaType.parse("application/json");

JSONObject jsonObject = new JSONObject();
jsonObject.put("data", new JSONObject[]{
        new JSONObject()
                .put("q", "Coffee")
                .put("domain", "google.com")
                .put("lang", "en")
                .put("device", "desktop")
                .put("serp_type", "web")
                .put("loc", "Alba,Texas,United States")
                .put("verbatim", 0)
                .put("postback_url", "https://webhook.site/8f885f1f-c38a-4a10-8506-335441213208")
                .put("page", 1)
                .put("num_result", 10),
        new JSONObject()
                .put("q", "Tea")
                .put("domain", "google.com")
                .put("lang", "en")
                .put("device", "desktop")
                .put("serp_type", "web")
                .put("loc", "Alba,Texas,United States")
                .put("verbatim", 0)
                .put("pingback_url", "https://webhook.site/bdd3a89a-fa1d-4f02-a2a9-c1bbd9570c40")
                .put("page", 1)
                .put("num_result", 10),
        new JSONObject()
                .put("domain", "google.co.uk")
                .put("lang", "ar")
                .put("q", "Cold Coffee")
                .put("loc", "London,England,United Kingdom")
                .put("postback_url", "https://webhook.site/bdd3a89a-fa1d-4f02-a2a9-c1bbd9570c40")
                .put("device", "desktop")
                .put("serp_type", "image")
                .put("num_result", 10)
});

String bodyJson = jsonObject.toString();

RequestBody body = RequestBody.create(mediaType,bodyJson);
Request request = new Request.Builder()
  .url("https://api.serphouse.com/serp/schedule")
  .method("POST", body)
  .addHeader("Content-Type", "application/json")
  .addHeader("Authorization", "Bearer <YOUR_API_KEY>")
  .build();
Response response = client.newCall(request).execute();
System.out.println(response.body().string());
```

{% endtab %}

{% tab title="JAVASCRIPT" %}

```javascript
var myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer <YOUR_API_KEY>");
myHeaders.append("Content-Type", "application/json");

var raw = JSON.stringify({
  "data": [
    {
      "q": "Coffee",
      "domain": "google.com",
      "lang": "en",
      "device": "desktop",
      "serp_type": "web",
      "loc": "Alba,Texas,United States",
      "verbatim": 0,
      "postback_url": "https://webhook.site/8f885f1f-c38a-4a10-8506-335441213208",
      "page": 1,
      "num_result": 10
    },
    {
      "q": "Tea",
      "domain": "google.com",
      "lang": "en",
      "device": "desktop",
      "serp_type": "web",
      "loc": "Alba,Texas,United States",
      "verbatim": 0,
      "pingback_url": "https://webhook.site/8f885f1f-c38a-4a10-8506-335441213208",
      "page": 1,
      "num_result": 10
    },
    {
      "domain": "google.co.uk",
      "lang": "ar",
      "q": "Cold Cofee",
      "loc": "London,England,United Kingdom",
      "postback_url": "https://webhook.site/8f885f1f-c38a-4a10-8506-335441213208",
      "device": "desktop",
      "serp_type": "image",
      "num_result": 10
    }
  ]
});

var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: raw,
  redirect: 'follow'
};

fetch("https://api.serphouse.com/serp/schedule", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));
```

{% endtab %}

{% tab title="GO" %}

```go
package main

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

func main() {

  url := "https://api.serphouse.com/serp/schedule"
  method := "POST"

  payload := strings.NewReader(`{
    "data": [
        {
            "q": "Coffee",
            "domain": "google.com",
            "lang": "en",
            "device": "desktop",
            "serp_type": "web",
            "loc": "Alba,Texas,United States",
            "verbatim": 0,
            "postback_url": "https://webhook.site/8f885f1f-c38a-4a10-8506-335441213208",
            "page": 1,
            "num_result": 10
        },
        {
            "q": "Tea",
            "domain": "google.com",
            "lang": "en",
            "device": "desktop",
            "serp_type": "web",
            "loc": "Alba,Texas,United States",
            "verbatim": 0,
            "pingback_url": "https://webhook.site/8f885f1f-c38a-4a10-8506-335441213208",
            "page": 1,
            "num_result": 10
        },
        {
            "domain": "google.co.uk",
            "lang": "ar",
            "q": "Cold Cofee",
            "loc": "London,England,United Kingdom",
            "postback_url": "https://webhook.site/8f885f1f-c38a-4a10-8506-335441213208",
            "device": "desktop",
            "serp_type": "image",
            "num_result": 10
        }
    ]
}`)

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Content-Type", "application/json")
  req.Header.Add("Authorization", "Bearer <YOUR_API_KEY>")

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

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}
```

{% endtab %}

{% tab title="C#/.NET" %}

```csharp
var client = new RestClient("https://api.serphouse.com/serp/schedule");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Authorization", "Bearer <YOUR_API_KEY>");
var body = @"{
	""data"": [
		{
			""q"": ""Coffee"",
			""domain"": ""google.com"",
			""lang"": ""en"",
			""device"": ""desktop"",
			""serp_type"": ""web"",
			""loc"": ""Alba,Texas,United States"",
			""verbatim"": 0,
			""postback_url"": ""https://webhook.site/8f885f1f-c38a-4a10-8506-335441213208"",
			""page"": 1,
			""num_result"": 10
		},
		{
			""q"": ""Tea"",
			""domain"": ""google.com"",
			""lang"": ""en"",
			""device"": ""desktop"",
			""serp_type"": ""web"",
			""loc"": ""Alba,Texas,United States"",
			""verbatim"": 0,
			""pingback_url"": ""https://webhook.site/8f885f1f-c38a-4a10-8506-335441213208"",
			""page"": 1,
			""num_result"": 10
		},
		{
			""domain"": ""google.co.uk"",
			""lang"": ""ar"",
			""q"": ""Cold Cofee"",
			""loc"": ""London,England,United Kingdom"",
			""postback_url"": ""https://webhook.site/8f885f1f-c38a-4a10-8506-335441213208"",
			""device"": ""desktop"",
			""serp_type"": ""image"",
			""num_result"": 10
		}
	]
}";
request.AddParameter("application/json", body,  ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.serphouse.com/serp-api/schedule-serp.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.