Spideric API Documentation

Welcome to the Spideric API!

Current version: 0.2.2 (last update: 2019-10-29)
To see changes check API changelog.

List of contents:

  1. Authorization
  2. Projects
    1. Add project
    2. List projects
    3. Delete project
    1. Keywords
      1. Add keywords
      2. List keywords
      3. Delete keywords
    2. Groups
      1. Add group
      2. List groups
      3. Delete group
      4. Add keywords
      5. List keywords
      6. Delete keywords
    3. Locale sub-projects
      1. List locale
  3. Reports
    1. Domain
    2. Keyword
    3. SERP
      1. List all results
      2. List competing domains
      3. List keywords for competing domain
  4. Google settings
    1. Engines
      1. List engines
      2. Engine details
    2. Languages
      1. List languages
      2. Language details
    3. Locations
      1. Location by id
      2. Location by name
  5. Errors

1. Authorization

GET https://www.spideric.com/api/{apiKey}

To access it you need to get authorized using your individual API key. You can find it under "API" tab in the settings page of your account. If no key has been generated yet, you need to request it first.

RESPONSE

{
	"id": 1,
	"name": "Name",
	"valid_until": "2018-11-28 23:59:59"
}

2. Projects

Add project

POST https://www.spideric.com/api/{apiKey}/projects

POST parameters:

domain
- string domain name
scheme
accepts the following values:
  • 1 - http only
  • 2 - https only
  • 3 - http & https
search_device
- integer accepts the following values:
  • 1 - desktop only
  • 2 - mobile only
  • 3 - desktop & mobile
subdomains
- integer accepts the following values:
  • 0 - false
  • 1 - true
maps
- integer accepts the following values:
  • 0 - false
  • 1 - true
name
(optional) string

Adds a new project to account. Returns project Id if successful or error.

RESPONSE

{
	"id": 1
}

List projects

GET https://www.spideric.com/api/{apiKey}/projects

Returns list of projects assigned to the account.

RESPONSE

[
	{
		"id": 1,
		"domain": "spideric.com",
		"added": "2017-05-08 12:30:13",
		"search_device": "desktop",
		"scheme": "http & https",
		"subdomains": true,
		"maps": false,
		"name": "spideric.com"
	}
]

Delete project

GET https://www.spideric.com/api/{apiKey}/project/{projectId}/delete

projectId
- integer

Returns TRUE if the projects was successfully deleted otherwise returns FALSE.

RESPONSE

true

2.1. Keywords

Add keywords

POST https://www.spideric.com/api/{apiKey}/project/{projectId}/keywords

projectId
- integer

POST parameters:

keywords
- array list of keywords to add to the project
search_engine
id of the search engine to track, for more details check Engines
search_language
id of the search engine language to track, for more details check Languages
search_location
id of the search engine location to track, for more details check Locations
group_id
(optional) array ids of groups to add keywords

Adds a list of keywords to the given project. If successful, it returns a list of added keywords followed by their details. It ignores adding already existing keywords in the project.
It returns NULL if no keyword was added.
It returns FALSE if the account keywords limit was exceeded.

RESPONSE

[
    {
    	"id": 3,
        "keyword": "apple",
        "added": "2018-03-20 12:52:18",
        "search_engine": {
            "id": 139,
            "url": "https://www.google.pl"
        },
        "search_language": {
            "id": 127,
            "code": "pl"
        },
        "search_location": null,
        "search_device": {
            "id": 1,
            "name": "desktop"
        },
        "groups": [
        	1
        ]
    }
]

List keywords

GET https://www.spideric.com/api/{apiKey}/project/{projectId}/keywords

projectId
- integer
?locale={searchEngineId}.{searchLanguageId}.{searchLocation}

Returns list of keywords of a given project. Results can be filtered by locale which is a combination of search engine, language and location ids seperated by commas.

RESPONSE

[
    {
    	"id": 3
        "keyword": "apple",
        "added": "2018-03-20 12:52:18",
        "search_engine": {
            "id": 139,
            "url": "https://www.google.pl"
        },
        "search_language": {
            "id": 127,
            "code": "pl"
        },
        "search_location": null,
        "search_device": {
            "id": 1,
            "name": "desktop"
        },
        "groups": [
        	1
        ]
    }
]

Delete keywords

GET https://www.spideric.com/api/{apiKey}/project/{projectId}/keywords/delete?ids={keywords}

projectId
- integer
keywords
- string ids of keywords to delete seperated by commas, e.g. "1,2,15,238"

Returns TRUE if the keyword or keywords were successfully deleted.
For projects tracking ranks in desktop and mobile SERPs it deletes keywords for both devices even if their ids are not given at the request.

RESPONSE

true

2.2. Groups

Add group

POST https://www.spideric.com/api/{apiKey}/project/{projectId}/groups

projectId
- integer

POST parameters:

name
- string

Adds a new keywords group to a project. Returns group id if successful.
It returns NULL if a group name in the project is already taken.

RESPONSE

{
	"id": 1
}

List groups

GET https://www.spideric.com/api/{apiKey}/project/{projectId}/groups

projectId
- integer

Returns list of groups of a given project.

RESPONSE

[
    {
        "id": 13,
        "name": "Name",
        "project_id": 44
    }
]

Delete group

GET https://www.spideric.com/api/{apiKey}/group/{groupId}/delete

groupId
- integer

Returns list of keywords of a given group.

RESPONSE

true

Add keywords

POST https://www.spideric.com/api/{apiKey}/group/{groupId}/keywords

groupId
- integer

POST parameters:

keywords
- array list of keywords to add to the group

Returns list of keywords added to a given group.

RESPONSE

[
    {
    	"id": 1,
        "keyword": "apple",
        "search_engine": {
            "id": 139,
            "url": "https://www.google.pl"
        },
        "search_language": {
            "id": 127,
            "code": "pl"
        },
        "search_location": null,
        "search_device": {
            "id": 1,
            "name": "desktop"
        },
        "groups": [
        	1
        ]
    }
]

List keywords

GET https://www.spideric.com/api/{apiKey}/group/{groupId}/keywords

Returns list of keywords of a given group.

RESPONSE

[
    {
    	"id": 1,
        "keyword": "apple",
        "search_engine": {
            "id": 139,
            "url": "https://www.google.pl"
        },
        "search_language": {
            "id": 127,
            "code": "pl"
        },
        "search_location": null,
        "search_device": {
            "id": 1,
            "name": "desktop"
        },
        "groups": [
        	1
        ]
    }
]

Delete keywords

GET https://www.spideric.com/api/{apiKey}/group/{groupId}/keywords/delete?ids={keywords}

groupId
- integer
keywords
- string ids of keywords to delete seperated by commas, e.g. "1,2,15,238"

Returns TRUE if the keyword or keywords were successfully removed from a group.
For projects tracking ranks in desktop and mobile SERPs it removes keywords for both devices even if their ids are not given at the request.

RESPONSE

true

2.3. Locale sub-projects

List locale

GET https://www.spideric.com/api/{apiKey}/project/{projectId}/locale

Returns list of locale of a given project.

RESPONSE

[
    {
        "search_engine": {
            "id": 139,
            "url": "https://www.google.pl"
        },
        "search_language": {
            "id": 127,
            "code": "pl"
        },
        "search_location": null
    }
]

3. Reports

3.1. Domain

GET https://www.spideric.com/api/{apiKey}/project/{projectId}/{reportType}?dateFrom={dateFrom}&dateTo={dateTo}

projectId
- integer
reportType
accepts the following values:
  • positions
  • urls
  • maps
  • titles
  • descriptions
  • keyword
  • serp
?dateFrom={dateFrom}
(required) ISO formatted date YYYY-MM-DD
?dateTo={dateTo}
(required) ISO formatted date YYYY-MM-DD
?locale={searchEngineId}.{searchLanguageId}.{searchLocation}
?device={device}
accepts only 2 values:
  • desktop
  • mobile

Returns ranks in organic search results or maps, URLs, titles or descriptions for keywords of a given project. You can narrow down the results by setting the locale.
It returns a value based on the report type, NULL if no result for project domain found in SERP top 100 or FALSE if a keyword hasn't been checked yet.

RESPONSE

[
    {
        "keyword": "apple",
        "search_engine": {
            "id": 139,
            "name": "Poland"
        },
        "search_language": {
            "id": 127,
            "code": "pl"
        },
        "search_location": null,
        "search_device": "desktop",
        "result": [
            {
                "position": null,
                "date": "2018-11-12"
            },
            {
                "position": null,
                "date": "2018-11-13"
            }
        ]
    }
]

3.2. Keyword

GET https://www.spideric.com/api/{apiKey}/project/{projectId}/keyword?keyword={keyword}&locale={searchEngineId}.{searchLanguageId}.{searchLocation}&dateFrom={dateFrom}&dateTo={dateTo}

projectId
- integer
?keyword={keyword}
(required) keyword string encoded according to RFC 3986
?locale={searchEngineId}.{searchLanguageId}.{searchLocation}
(required)
?dateFrom={dateFrom}
(required) ISO formatted date YYYY-MM-DD
?dateTo={dateTo}
(required) ISO formatted date YYYY-MM-DD

Returns data about a given keyword in the given timespan like ranks in organic search results and maps, URLs, titles, and descirptions.

RESPONSE

{
    "4961": {
        "keyword": "spideric",
        "search_engine": {
            "id": 139,
            "name": "Poland"
        },
        "search_language": {
            "id": 127,
            "code": "pl",
            "name": "Polish"
        },
        "search_location": null,
        "search_device": "desktop",
        "positions": [
            {
                "position": null,
                "date": "2018-11-15"
            },
            {
                "position": 1,
                "date": "2018-11-16"
            }
        ],
    	"urls": [
            {
                "url": null,
                "date": "2018-11-15"
            },
            {
                "url": "https://www.spideric.com/",
                "date": "2018-11-16"
            }
        ],
    	"maps": [
            {
                "map": null,
                "date": "2018-11-15"
            },
            {
                "map": 1,
                "url": "https://www.spideric.com/",
                "date": "2018-11-16"
            }
        ],
    	"titles": [
            {
                "title": null,
                "date": "2018-11-15"
            },
            {
                "title": "Rank Tracking Tool - Spideric",
                "date": "2018-11-16"
            }
        ],
    	"descriptions": [
            {
                "description": null,
                "date": "2018-11-15"
            },
            {
                "description": "Want to track daily results in international or local search results. Check reliable and accurate SEO tool - Spideric.",
                "date": "2018-11-16"
            }
        ]
    }
}
    	

3.3. SERP

List all results

GET https://www.spideric.com/api/{apiKey}/project/{projectId}/serp?keyword={keyword}&locale={searchEngineId}.{searchLanguageId}.{searchLocation}&date={date}&device={device}

projectId
- integer
?keyword={keyword}
(required) keyword string encoded according to RFC 3986
?locale={searchEngineId}.{searchLanguageId}.{searchLocation}
(required)
?date={date}
(required) ISO formatted date YYYY-MM-DD
?device={device}
(required) accepts only 2 values:
  • desktop
  • mobile

Returns all search results for a given keyword on the date.

RESPONSE

{
    "keyword": "spideric",
    "search_engine": {
        "id": 139,
        "name": "Poland"
    },
    "search_language": {
        "id": 127,
        "code": "pl",
        "name": "Polish"
    },
    "search_location": null,
    "search_device": "desktop",
    "maps": null,
    "positions": [
        {
            "rank": 1,
            "url": "https://www.spideric.com/pl/",
            "title": "Pozycja w Google - Spideric monitoring pozycji - spideric.com",
            "description": "Chcesz codziennie monitorować lokalne wyniki wyszukiwania w wielu krajach? Sprawdź niezawodne i dokładne narzędzie SEO - Spideric.",
            "time": "2018-11-15 00:36:08"
        }
    ]
}

List competing domains

GET https://www.spideric.com/api/{apiKey}/project/{projectId}/serp?dateFrom={dateFrom}&dateTo={dateTo}

projectId
- integer
?dateFrom={dateFrom}
(required) ISO formatted date YYYY-MM-DD
?dateTo={dateTo}
(required) ISO formatted date YYYY-MM-DD
?device={device}
(required) accepts only 2 values:
  • desktop
  • mobile

Returns list of domains ranking for keywords of a given project and their statistics for a given period of time.

RESPONSE

{
    "mobile": [
        {
            "domain": "https://m.youtube.com",
            "avg": 37.13,
            "avg_change": 1.81,
            "top10": 16,
            "top10_change": -1,
            "top100": 76,
            "top100_change": 2
        }
    ]
}

List keywords for competing domain

GET https://www.spideric.com/api/{apiKey}/project/{projectId}/serp?domain={domain}&dateFrom={dateFrom}&dateTo={dateTo}

projectId
- integer
domain
(required) domain name including http/https protocol encoded according to RFC 3986
?dateFrom={dateFrom}
(required) ISO formatted date YYYY-MM-DD
?dateTo={dateTo}
(required) ISO formatted date YYYY-MM-DD
?locale={searchEngineId}.{searchLanguageId}.{searchLocation}
?device={device}
accepts only 2 values:
  • desktop
  • mobile

Returns list of keywords from a given project filtered for a given domain.

RESPONSE

{
    "mobile": [
        {
            "domain": "https://m.youtube.com",
            "avg": 37.13,
            "avg_change": 1.81,
            "top10": 16,
            "top10_change": -1,
            "top100": 76,
            "top100_change": 2
        }
    ]
}

4. Google settings

4.1. Engines

List engines

GET https://www.spideric.com/api/{apiKey}/engines

Returns a list of all search engines available to track via Spideric.

RESPONSE

[
    {
        "id": 1,
        "name": "Afghanistan",
        "url": "https://www.google.com.af",
        "country_code": "af"
    }
]

Engine details

GET https://www.spideric.com/api/{apiKey}/engines?id={engineId}

engineId
- integer

Returns the details for a given search engine id.

RESPONSE

{
        "id": 1,
        "name": "Afghanistan",
        "url": "https://www.google.com.af",
        "country_code": "af"
    }

4.2. Languages

List languages

GET https://www.spideric.com/api/{apiKey}/languages

Returns a list of all languages supported by Google and available to track via Spideric.

RESPONSE

[
    {
    	"id": 1,
    	"name": "Abkhaz",
    	"code": "ab"
	}
]

Language details

GET https://www.spideric.com/api/{apiKey}/languages?id={languageId}

languageId
- integer

Returns the details for a given search language id.

RESPONSE

{
	"id": 1,
	"name": "Afghanistan",
	"url": "https://www.google.com.af",
	"country_code": "af"
}

4.2. Locations

Location by id

GET https://www.spideric.com/api/{apiKey}/locations?id={locationId}

locationId
- integer

Returns the details for a given search location id.

RESPONSE

{
    "id": 1,
    "name": "Andorra"
}

Location by name

GET https://www.spideric.com/api/{apiKey}/languages?name={name}

name
- string

Returns a list of locations matching the value given as name.
The name value need to be at least 3 characters long. Results per request are limited to 5.

RESPONSE

[
    {
    	"id": 1,
    	"name": "Andorra"
    }
]

5. Errors

The API returns HTTP errors. Below you can find examples of reasons for their occurence.

400
- Bad Request
  • the request URL doesn't match the documentation
  • the method doesn't exist
  • missing required parameters
  • wrong parameters format

401
- Unauthorized
  • wrong API key
  • wrong project id, group id or keyword id
  • plan not allowing the API usage
  • not allowed to use a method