Spideric API Documentation

Welcome to the Spideric API!

List of contents:

  1. Authorization
  2. Projects
    1. Groups
    2. Locale sub-projects
  3. Reports
    1. Positions
    2. Maps
    3. URLs
    4. Titles
    5. Descriptions
    6. Keyword
    7. SERP
  4. Engines
  5. Languages
  6. Locations
  7. 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

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"
	}
]

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

[
    {
        "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"
        }
    }
]

2.1. Groups

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
    }
]

List keywords

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

Returns list of keywords of a given group.

RESPONSE

[
    {
        "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"
        }
    }
]

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

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.

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": null,
                "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

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"
        }
    ]
}
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
        }
    ]
}
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
        }
    ]
}