NAV
shell python go javascript

Introduction

All examples are structured as follows:

  1. Request body parameters

  2. Request code example

  3. 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.

Sign up for an API key

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
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)

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.