Introduction

All examples are structured as follows:

Request body parameters

Request code example

Response body parameters

Welcome to the SEO Bot API. This API allows access to our search engine proxy service, which is used to query and collect information about search engine results.

You can find usage examples in the dark area to the right, and you can change the programming language of the examples with the tabs in the top right. Examples have been given in Shell, Python, Golang and JavaScript!

If you would like any changes or additions to be made to our documentation, functionality or examples, please send your suggestions to support@seobot.com.

Authentication

SEO Bot expects an access token to be included in the header of each request made to the API. This header field is defined as follows:

Authorization: access-token

SEO Bot uses access tokens to authenticate requests made to the API. Each access token is linked to a single account and is only valid for one unique endpoint i.e. google, bing, yandex or duckduckgo.

Each account may have multiple access tokens across multiple endpoints, and the number of requests that may be made using these tokens will be based on the account limits.

When creating a new account, one token for each supported endpoint will be provided to you by default. To apply for an account, please visit our subscriptions page to see available packages.

Google

Search by Text

The request body must be sent in JSON format with the following structure:

{
  "keywords": "{Keywords}",
  "mobile"  : true/false,
  "type"    : "{Type}",
  "language": "{Language code}",
  "country" : "{Country code}",
  "uule"    : "{UULE}",
  "start"   : {Start},
  "num"     : {Num}
}

Note that fields which are not required may be omitted from the request. An example of a search-by-text request is given below:

curl 'https://api.seobot.com:11115/google/search' \
     -H 'Content-Type: application/json' \
     -H 'Authorization: a5dc16c9d6fd89b30913d2bc988ad096' \
     -d '{
            "keywords": "seo bot api",
            "mobile"  : false,
            "type"    : "shop",

            "language": "en",
            "country" : "za",

            "start"   : 0,
            "num"     : 10
         }'

import requests
import json

api_token = 'a5dc16c9d6fd89b30913d2bc988ad096'
payload = {
             "keywords": "seo bot api",
             "mobile"  : False,
             "type"    : "shop",

             "language": "en",
             "country" : "za",

             "start"   : 0,
             "num"     : 10
         }

request = requests.post('https://api.seobot.com:11115/google/search',
                        headers={'Authorization': api_token},
                        json=payload)
result = json.loads(request.text)

import (
    "encoding/json"
    "net/http"
    "strings"
)

payload := strings.NewReader(`{
             "keywords": "seo bot api",
             "mobile"  : False,
             "type"    : "shop",

             "language": "en",
             "country" : "za",

             "start"   : 0,
             "num"     : 10
         }`)

request, err := http.NewRequest("POST",
    "https://api.seobot.com:11115/google/search",
    payload)
if err != nil {
  // Error handling...
}
request.Header.Set("Authorization", "a5dc16c9d6fd89b30913d2bc988ad096")
request.Header.Set("Content-Type", "application/json")

client := &http.Client{}
response, err := client.Do(request)
if err != nil {
  // Error handling...
}

result map[string]interface{}{}
err := json.NewDecoder(response.Body).Decode(&result)
if err != nil {
  // Error handling...
}

const fetch = require("node-fetch");

const payload = {
                "keywords": "seo bot api",
                "mobile"  : false,
                "type"    : "shop",

                "language": "en",
                "country" : "za",

                "start"   : 0,
                "num"     : 10
            };

fetch('https://api.seobot.com:11115/google/search', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'a5dc16c9d6fd89b30913d2bc988ad096'
  },
  body: JSON.stringify(payload),
})
.then((response) => response.json())
.then((result) => {
  console.log('Response:', result);
})
.catch((error) => {
  console.error('Error:', error);
});

Query results will be returned as a JSON formatted object with the following structure:

{
  "error": "error message",
  "result": "{query results}",
  "requests_remaining": "{# of requests remaining}"
}

This endpoint performs a regular Google search-by-text and returns the results in json format. The type and number of results returned depends on the request's parameters.

HTTP Endpoint

GET https://api.seobot.com:11115/google/search

Search Parameters

Parameter	Type	Required	Description
keywords	String	Yes	Keywords for which to search
mobile	Bool	No	Indicates whether the user-agent is a mobile or desktop device (Default: false)
type	String	No	Used to set the search type (Default: all) Available Options: • `shop` -> Shopping • `isch` -> Images • `vid` -> Videos • `nws` -> News • `jobs` -> Jobs

Localization parameters

Parameter	Type	Required	Description
language	String	No	Two-letter language code to indicate search language
country	String	No	Two-letter country code to indicate search country
uule	String	No	Encoded location from which to search. A list of valid locations can be found here

Pagination parameters

Parameter	Type	Required	Description
start	Int	No	Indicates the offset of the first result to be returned (Default: 0)
num	Int	No	Indicates the number of results to be returned after the starting offset (Default: 10)

Search by Image

The request body must be sent in JSON format with the following structure:

{
  "image_url" : "{Image URL}",
  "download"  : true/false
}

Note that fields which are not required may be omitted from the request. An example of a search-by-image request is given below:

curl 'https://api.seobot.com:11115/google/images' \
     -H 'Content-Type: application/json' \
     -H 'Authorization: a5dc16c9d6fd89b30913d2bc988ad096' \
     -d '{
            "image_url": "https://images.example.com/image.jgp",
            "download" : false
         }'

import requests
import json

api_token = 'a5dc16c9d6fd89b30913d2bc988ad096'
payload = {
             "image_url": "https://images.example.com/image.jgp",
             "download" : False
         }

request = requests.post('https://api.seobot.com:11115/google/images',
                        headers={'Authorization': api_token},
                        json=payload)
result = json.loads(request.text)

import (
    "encoding/json"
    "net/http"
    "strings"
)

payload := strings.NewReader(`{
             "image_url": "https://images.example.com/image.jgp",
             "download" : false
         }`)

request, err := http.NewRequest("POST",
    "https://api.seobot.com:11115/google/images",
    payload)
if err != nil {
  // Error handling...
}
request.Header.Set("Authorization", "a5dc16c9d6fd89b30913d2bc988ad096")
request.Header.Set("Content-Type", "application/json")

client := &http.Client{}
response, err := client.Do(request)
if err != nil {
  // Error handling...
}

result map[string]interface{}{}
err := json.NewDecoder(response.Body).Decode(&result)
if err != nil {
  // Error handling...
}

const fetch = require("node-fetch");

const payload = {
              "image_url": "https://api.seobot.com:11115/google/images",
              "download" : false
            };

fetch('https://api.seobot.com:11115/google/images', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'a5dc16c9d6fd89b30913d2bc988ad096'
  },
  body: JSON.stringify(payload),
})
.then((response) => response.json())
.then((result) => {
  console.log('Response:', result);
})
.catch((error) => {
  console.error('Error:', error);
});

Query results will be returned as a JSON formatted object with the following structure:

{
  "error": "error message",
  "result": "{query results}",
  "requests_remaining": "{# of requests remaining}"
}

This endpoint performs a Google search-by-image and returns the results in json format.

HTTP Endpoint

GET https://api.seobot.com:11115/google/images

Search Parameters

Parameter	Type	Required	Description
image_url	String	Yes	URL of the image on which the search will be based
download	Bool	No	Indicates whether to perform a regular GET request or to perform a POST request to google with the requested image URL (Default: false)

Reviews

The request body must be sent in JSON format with the following structure:

{
  "fid"     : "{Feature ID}",
  "filter"  : "{Filter words}",
  "sort"    : "{Sort option}",
  "language": "{Language code}",
  "start"   : {Start}
}

Note that fields which are not required may be omitted from the request. An example of a search-by-text request is given below:

curl 'https://api.seobot.com:11115/google/reviews' \
     -H 'Content-Type: application/json' \
     -H 'Authorization: a5dc16c9d6fd89b30913d2bc988ad096' \
     -d '{
            "fid"     : "{Feature ID}",
            "filter"  : "Nice food",
            "sort"    : "ratingHigh",

            "language": "en",
            "start"   : 5
         }'

import requests
import json

api_token = 'a5dc16c9d6fd89b30913d2bc988ad096'
payload = {
            "fid"     : "{Feature ID}",
            "filter"  : "Nice food",
            "sort"    : "ratingHigh",

            "language": "en",
            "start"   : 5
         }

request = requests.post('https://api.seobot.com:11115/google/reviews',
                        headers={'Authorization': api_token},
                        json=payload)
result = json.loads(request.text)

import (
    "encoding/json"
    "net/http"
    "strings"
)

payload := strings.NewReader(`{
            "fid"     : "{Feature ID}",
            "filter"  : "Nice food",
            "sort"    : "ratingHigh",

            "language": "en",
            "start"   : 5
         }`)

request, err := http.NewRequest("POST",
    "https://api.seobot.com:11115/google/reviews",
    payload)
if err != nil {
  // Error handling...
}
request.Header.Set("Authorization", "a5dc16c9d6fd89b30913d2bc988ad096")
request.Header.Set("Content-Type", "application/json")

client := &http.Client{}
response, err := client.Do(request)
if err != nil {
  // Error handling...
}

result map[string]interface{}{}
err := json.NewDecoder(response.Body).Decode(&result)
if err != nil {
  // Error handling...
}

const fetch = require("node-fetch");

const payload = {
             "fid"     : "{Feature ID}",
             "filter"  : "Nice food",
             "sort"    : "ratingHigh",

             "language": "en",
             "start"   : 5
            };

fetch('https://api.seobot.com:11115/google/reviews', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'a5dc16c9d6fd89b30913d2bc988ad096'
  },
  body: JSON.stringify(payload),
})
.then((response) => response.json())
.then((result) => {
  console.log('Response:', result);
})
.catch((error) => {
  console.error('Error:', error);
});

Query results will be returned as a JSON formatted object with the following structure:

{
  "error": "error message",
  "result": "{query results}",
  "requests_remaining": "{# of requests remaining}"
}

This endpoint performs a Google search of all reviews for a specific feature and returns the results in json format. The type and number of results returned depends on the request's parameters.

HTTP Endpoint

GET https://api.seobot.com:11115/google/reviews

Search Parameters

Parameter	Type	Required	Description
fid	String	Yes	Feature ID for which reviews will be fetched
filter	String	No	Filter keywords, which will only return results that contain the given keywords
sort	String	No	The order in which the reviews are sorted (Default: Most Relevant First) Available Options: • `qualityScore` -> Most relevant first • `newestFirst` -> Newest first • `ratingHigh` -> Highest rating first • `ratingLow` -> Lowest rating first

Localization and Pagination parameters

Parameter	Type	Required	Description
language	String	No	Two-letter language code to indicate search language
start	Int	No	Indicates the offset of the first result to be returned (Default: 0)

Trends

The request body must be sent in JSON format with the following structure:

{
  "keywords": "{Keywords}",
  "category": {Category code},
  "type"    : "{Type}",
  "language": "{Language code}",
  "country" : "{Country code}",
  "date"    : "{Date option}",
  "start"   : "{Custom Start}",
  "stop"    : "{Custom Stop}"
}

Note that fields which are not required may be omitted from the request. An example of a search-by-text request is given below:

curl 'https://api.seobot.com:11115/google/trends' \
     -H 'Content-Type: application/json' \
     -H 'Authorization: a5dc16c9d6fd89b30913d2bc988ad096' \
     -d '{
            "keywords": "seo bot api",
            "category": 0,
            "type"    : "google",

            "language": "en",
            "country" : "za",

            "date"    : "now 7-d",
            "start"   : "2021-01-01",
            "stop"    : "2021-07-01"
         }'

import requests
import json

api_token = 'a5dc16c9d6fd89b30913d2bc988ad096'
payload = {
             "keywords": "seo bot api",
             "category": 0,
             "type"    : "google",

             "language": "en",
             "country" : "za",

             "date"    : "now 7-d",
             "start"   : "2021-01-01",
             "stop"    : "2021-07-01"
         }

request = requests.post('https://api.seobot.com:11115/google/trends',
                        headers={'Authorization': api_token},
                        json=payload)
result = json.loads(request.text)

import (
    "encoding/json"
    "net/http"
    "strings"
)

payload := strings.NewReader(`{
             "keywords": "seo bot api",
             "category": 0,
             "type"    : "google",

             "language": "en",
             "country" : "za",

             "date"    : "now 7-d",
             "start"   : "2021-01-01",
             "stop"    : "2021-07-01"
         }`)

request, err := http.NewRequest("POST",
    "https://api.seobot.com:11115/google/trends",
    payload)
if err != nil {
  // Error handling...
}
request.Header.Set("Authorization", "a5dc16c9d6fd89b30913d2bc988ad096")
request.Header.Set("Content-Type", "application/json")

client := &http.Client{}
response, err := client.Do(request)
if err != nil {
  // Error handling...
}

result map[string]interface{}{}
err := json.NewDecoder(response.Body).Decode(&result)
if err != nil {
  // Error handling...
}

const fetch = require("node-fetch");

const payload = {
             "keywords": "seo bot api",
             "category": 0,
             "type"    : "google",

             "language": "en",
             "country" : "za",

             "date"    : "now 7-d",
             "start"   : "2021-01-01",
             "stop"    : "2021-07-01"
            };

fetch('http://localhost:54453/google/trends', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'a5dc16c9d6fd89b30913d2bc988ad096'
  },
  body: JSON.stringify(payload),
})
.then((response) => response.json())
.then((result) => {
  console.log('Response:', result);
})
.catch((error) => {
  console.error('Error:', error);
});

Query results will be returned as a JSON formatted object with the following structure:

{
  "error": "error message",
  "result": "{query results}",
  "requests_remaining": "{# of requests remaining}"
}

This endpoint performs a Google trends search and returns the results in json format. The type and number of results returned depends on the request's parameters.

HTTP Endpoint

GET https://api.seobot.com:11115/google/trends

Search Parameters

Parameter	Type	Required	Description
keywords	String	Yes	Keywords for which to search
category	Int	No	The id of the category in which to search (Default: 0). A list of all categories can be found here
type	String	No	Used to set the search type (Default: Web Search) Available Options: • `images` -> Images • `news` -> News • `google` -> Google • `youtube` -> Google

Localization parameters

Parameter	Type	Required	Description
language	String	No	Two-letter language code to indicate search language
country	String	No	Two-letter country code to indicate search country

Timerange parameters

Parameter	Type	Required	Description
date	String	No	The time range in which to search (Default: Past 12 Months) Available Options: • `now 1-H` - Past hour • `now 4-H` - Past 4 hours • `now 1-d` - Past day • `now 7-d` - Past week • `today 1-m` - Past month • `today 3-m` - Past 3 months • `today 12-m` - Past 12 months • `today 5-y` - Past 5 years
start	String	No	A custom start date from which to query (Format: `YYYY-MM-DD`). This parameter is ignored if the *stop* parameter is not set
stop	String	No	A custom stop date from which to query (Format: `YYYY-MM-DD`). This parameter is ignored if the *start* parameter is not set

Bing

Yandex

DuckDuckGo

Codes

Response codes and meanings:

Code	Meaning	Description
200	OK	The request was accepted and processed successfully.
400	Bad Request	Your request is invalid.
401	Unauthorized	Your API access token is wrong.
402	Payment Required	You have reached the monthly request limit.
403	Forbidden	The requested resource is hidden or available to administrators only.
404	Not Found	The specified resource could not be found.
405	Method Not Allowed	You tried to access a resource with an invalid method.
410	Gone	The requested resource has been removed from our servers.
429	Too Many Requests	You are making an unreasonable number of requests!
500	Internal Server Error	We had a problem with our server. Try again later.
503	Service Unavailable	We're temporarily offline for maintenance. Please try again later.