> For the complete documentation index, see [llms.txt](https://docs.serphouse.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.serphouse.com/serp-api/schedule-serp.md).

# 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 %}