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