Seobility API Documentation

The Seobility SEO API gives you programmatic access to our crawling and SEO analysis technology via a simple RESTful JSON service.

1. Introduction

1.1 Overview

The Seobility SEO API provides access to the Seobility SEO software technology for crawling and SEO analysis of websites. It gives valuable insight into site health and search engine optimization, as well as easy troubleshooting for an entire website.

For easy integration of the technology into your individual environment, the API is built as RESTful service and provides JSON-format data.

1.2 Single Page Check API

The Single Page Check is another part of the SEO API. It provides the SEO Check and the Keyword Check as both consider only one specific URL for the performed analysis. Use this part of the API either to complement the Site Audit API, or to perform (isolated) single page analyses.

1.3 API credit system

The cost is documented accordingly for each method.

Credit packages are available on a monthly basis. For more information and a price quote based on your individual needs, please contact us here.

1.4 Support

The support for the API is available in English and German.

For questions about the Seobility SEO API or if you would like to receive a price quote based on your individual needs, please contact us here.

2. Site Audit API

Replaced by new API, please contact our support team.

3. Single Page Check API

3.1 SEO Check

seocheck - Crawls an URL and returns a broad set of information about the SEO optimization of this page. Please note that the URL is being crawled live, so the response time will vary.

Credits: 100

Example Call:

GET https://api.seobility.net/en/resellerapi/seocheck?apikey={yourapikey}&url=https://www.wikipedia.org/

Request Parameters:

Field	Type	Mandatory	Explanation
url	string	yes	Target URL

Response Parameters (JSON):

Field

Type

Explanation

array

All onsite information:

Parameter	Type	Description
score	int	The SEO score i.e. the overall optimization percentage of the analyzed page
analysedurl	string	The URL that has been analyzed during the SEO check
thumbnailurl	string	The URL to a thumbnail of the analyzed URL's domain (homepage)
quickfacts	object	General information about the analyzed page
loadtime	float	The load time in seconds
filesize	float	The page size in kB
words	int	The word count
mediafiles	int	The number of media files on the analyzed page
internallinks	int	The number of internal links on the analyzed page
externallinks	int	The number of external links on the analyzed page
medialist	object	A list of the media elements found on the analyzed page
images	array	An array of the images
src	string	The image's path
alt	string	The alt value of the image
title	string	The title of the image
videos	array	An array of the videos
src	string	The video's path
width	int	The width of the video
height	int	The height of the video
alt	string	The alt value of the video
audio	array	An array of the audio files
src	string	The audio file's path
alt	string	The alt value of the audio file
linklist	array	A list of the page's links
link	string	The link's URL
target_blank	boolean	Whether it's a link with the target blank
nofollow	boolean	Whether it's a nofollow link
internal	boolean	Whether it's an internal link
subdomain	boolean	Whether the link leads to a subdomain of the website
anchor	string	The link's anchor text
anchortype	string	The link's anchor type
isanchorlink	boolean	Whether the link is an anchor link or not
groupresults	object	A result list of the analysis categories
meta	object	The results for the analysis category "meta"
score	int	The score (percentage) achieved in this category
points	int	The amount of points that has been achieved in this category
maxpoints	int	The maximum amount of points that can be achieved in this category
(...)
hints	array	A list of hints for improving the page
text	string	The hint text
priority	int	The priority i.e. the importance of the hint
keywords	array	A list of keywords found on the analyzed page
keyword	string	The keyword
score	int	Optimization score for the keyword on the analyzed page
robots	string	The website's full robots.txt file
httptags	array	A list of the HTTP response headers received from the server
type	string	The name of the HTTP header
value	string	The value of the HTTP header
metatags	array	A list of all meta tags defined on the analyzed page
name	string	The name of the meta tag
value	string	The value of the meta tag
headingstructure	array	A list of the headers on the analyzed page (h1, h2, ...)
headinglevel	int	The level of the header (h1, h2, h3)
content	string	The content of the header
duplicate	boolean	Whether the header is a duplicate
empty	boolean	Whether the header is empty
factors	object	A list that contains all factors analyzed
meta	object	A factor category that contains all factors belonging to this category
title_content	object	The technical name of the factor
factorname	string	The localized factor name
score	int	The score achieved in this factor (percentage)
impact	string	The impact this factor has i.e. its importance
messages	array	A list of messages regarding this factor
text	string	The localized message
text_label	string	The label of the message
priority	int	The priority of the message (0-3)
(...)
(...)

3.2 Keyword Check

keywordcheck - Crawls an URL and returns information about how well the site is optimized for the specified keyword. Please note that the URL is being crawled live, so the response time will vary.

Credits: 20

Example Call:

GET https://api.seobility.net/en/resellerapi/keywordcheck?apikey={yourapikey}&url=https://www.wikipedia.org/&keyword=wiki

Request Parameters:

Field	Type	Mandatory	Explanation
url	string	yes	Target URL
keyword	string	yes	Keyword that should be checked

Response Parameters (JSON):

Field	Type	Explanation
-	array	All information on the keyword optimization of the page

4. TF*IDF Check API

4.1 TF*IDF Check

tfidfcheck - Performs a TF*IDF check for a given keyword. Several parameters allow individual and localized analysis settings. Returns the complete TF*IDF analysis data and an initial set of term suggestions. Please note that an initial tfidfcheck request will take a moment, as the analysis requires live data from several sources. Consecutive refreshes of an analysis with unchanged parameters will be without delay.

Credits: 175

Example Call:

GET https://api.seobility.net/en/resellerapi/tfidfcheck?apikey={yourapikey}&keyword=example&searchengine=google.com

Request Parameters:

Field	Type	Mandatory	Explanation
keyword	string	yes	The target keyword
searchengine	string	yes	The target searchengine (e.g. Google.com, Google.de, Google.com.pk etc.)
platform	int	no	The target platform (1=desktop, 2=mobile; default=1)
city	string	no	The name of the location for the query (requires lat and lon)
lat	float	no	The latitude of the location for the query (requires city and lon)
lon	float	no	The longitude of the location for the query (requires city and lat)
logbase	float	no	The logarithmic base for the calculation of the TF*IDF scoring (default = 1.05185); only change if you know what you are doing
resultamount	int	no	The amount of top SERP results parsed to the TF*IDF check (default=10, Possible: 3, 7, 10, 15 or 20)
url	string	no	The URL with the text to be optimized (use either url, text or textlength)
text	string	no	Text to be optimized (use either url, text or textlength)
textlength	int	no	Number of words of the target text (use either url, text or textlength)
textmode	string	no	Textparsingmode. Use "singleword" for only single-word keywords (default) or "multiword" for multi-word keyword support.

Response Parameters (JSON):

Field

Type

Explanation

array

Response Array

Parameter	Type	Description
success	boolean	Whether the request was successful
request	array	The provided request information
keyword	string	The keyword provided in the request
searchengine	string	The searchengine provided in the request (e.g. Google.com, Google.de, Google.com.pk etc.)
platform	string	The target platform provided in the request (1=desktop, 2=mobile)
lat	int	The latitude of the location provided in the request
lon	int	The longitude of the location provided in the request
city	string	The name of the location provided in the request
logbase	int	The logarithmic base used for this calculation of the TF*IDF scoring
resultamount	int	The amount of top SERP results parsed for this TF*IDF check
url	string	The given URL used as comparison basis for TF*IDF check
text	string	The text given for calculation basis for this TF*IDF check
textlength	int	The textlength given for calculation basis for this TF*IDF check
calltime	datetime	Time of this request
stats	array	Relevant Keywords and their statistical data
Index	array	Index of the stat
keyword	string	Keyword for the corresponding values attached
avgtfidfused	int	Average TF*IDF value for all results containing this term
avgtfidftotal	int	Average TF*IDF value for all results
occurrence	int	The number of occurrences
maxtfidf	int	Max TF*IDF value for this term
maxtf	int	Max TF value for this term
(...)
results	array	The results for the request
Index	array	Index of the result
link	string	Result URL as given by Google SERP
title	string	SERP title
description	string	SERP title description
rank	int	Rank in the SERP (1-100)
domain	string	Result Domain
tfidf	array	List of keywords with corresponding TF*IDF of this result
keyword	int	The keyword and its corresponding TF*IDF value
(...)
loadtime	int	The time it took to load the result
wordcount	int	The amount of words in the results HTML
crawlerror	boolean	Errors occurred while crawling
(...)
termsuggestions	array	Term suggestions
more	array	Words that should be used more
less	array	Words that should be used less
suggestedamount	array	Suggested optimal frequency/range of this keyword in the text, given the current text length.
ok	array	Perfectly optimized words
text	string	The text on the page. (only relevant if URL was a part of the request)

5. Term Suggestion API

5.1 TF*IDF Term Suggestion

termsuggestion - Provides term suggestions to optimize a text for a given keyword, e.g. in a text editor. The underlying analysis is based on TF*IDF. Several parameters allow individual and localized analysis settings. Please note that an initial termsuggestion request might take a moment, as the analysis requires live data from several sources. Consecutive refreshes of an analysis with unchanged parameters will be without delay.

Credits: 20

Example Call:

GET https://api.seobility.net/en/resellerapi/termsuggestion?apikey={yourapikey}&keyword=example&url=https://example.com&searchengine=google.com

Request Parameters:

Field	Type	Mandatory	Explanation
keyword	string	yes	The target keyword
searchengine	string	yes	The target searchengine (e.g. Google.com, Google.de, Google.com.pk etc.)
platform	int	no	The target platform (1=desktop, 2=mobile; default=1)
city	string	no	The name of the location for the query (requires lat and lon)
lat	float	no	The latitude of the location for the query (requires city and lon)
lon	float	no	The longitude of the location for the query (requires city and lat)
logbase	float	no	The logarithmic base for the calculation of the TF*IDF scoring (default = 1.05185); only change if you know what you are doing
resultamount	int	no	The amount of top SERP results parsed to the TF*IDF check (default=10, Possible: 3, 7, 10, 15 or 20)
url	string	yes	The URL with the text to be optimized (use either url or text)
text	string	yes	Text to be optimized (use either url or text)

Response Parameters (JSON):

Field

Type

Explanation

array

Response Array

Parameter	Type	Description
success	boolean	Whether the request was successful
request	array	The provided request information
keyword	string	The keyword provided in the request
searchengine	string	The searchengine provided in the request (e.g. Google.com, Google.de, Google.com.pk etc.)
platform	string	The target platform provided in the request (1=desktop, 2=mobile)
lat	int	The latitude of the location provided in the request
lon	int	The longitude of the location provided in the request
city	string	The name of the location provided in the request
logbase	int	The logarithmic base used for this calculation of the TF*IDF scoring
resultamount	int	The amount of top SERP results parsed for this TF*IDF check
url	string	The given URL used as comparison basis for TF*IDF check
text	string	The text given for calculation basis for this TF*IDF check
calltime	datetime	Time of this request
termsuggestions	array	Term suggestions
more	array	Words that should be used more
less	array	Words that should be used less
ok	array	Perfectly optimized words
text	string	The text on the page. (only relevant if URL was a part of the request)

6. Ranking API

6.1 Ranking (Real Time)

ranking - Returns the SERP Rankings (SERP = Search Engine Result Pages) for a given search term or keyword.

This is a synchronous (direct) API. The average response time is 30 seconds.

Credits: 3

Example Call:

GET https://api.seobility.net/en/resellerapi/ranking?apikey={yourapikey}&keyword=example&searchengine=google.com

Request Parameters:

Field	Type	Mandatory	Explanation
keyword	string	yes	The target keyword
searchengine	string	yes	The target searchengine domain (i.e. Google.com or Google.co.uk)
platform	int	no	Target Platform (1=Desktop, 2=Mobile) (Default Desktop)
city	string	no	Name of the location for query (requires city, lat and lon)
lat	float	no	Latitude of the query (requires city, lat and lon)
lon	float	no	Longitude of the query (requires city, lat and lon)
url	string	no	URL which position is to be determined

Response Parameters (JSON):

Field

Type

Explanation

array

Response Array

Parameter	Type	Description
success	boolean	Whether the request was successful
request	object	The provided request information
keyword	string	The keyword provided in the request
searchengine	string	The searchengine provided in the request (e.g. Google.com, Google.de, Google.com.pk etc.)
platform	string	The type of device i.e. MOBILE
lat	int	Latitude for Google Maps
lon	int	Longitude for Google Maps
city	string	City for Google Maps localisation
targeturl	string	URL given as target for the results
calltime	datetime	Time of TF*IDF analysis
targeturlresult	array	results of the target URL; only provided if target URL is within the top SERPS
rank	int	The ranking of the target url
link	string	Link to the target url
description	string	The meta description of the target url
title	string	The title of the target url
results	array	The results for the request
rank	int	The ranking of the page
link	string	Link to the page
description	string	The meta description of the page
title	string	The title of the page
domain	string	The domain of the page
(...)

7. Error handling

If an error occurred, or if you made an invalid request, the API will return an error message.

The returned JSON will be structured like this:

{
	"error" : "{errormessage}"
}

Seobility API Documentation

1. Introduction

1.1 Overview

1.2 Single Page Check API

1.3 API credit system

1.4 Support

2. Site Audit API

3. Single Page Check API

3.1 SEO Check

3.2 Keyword Check

4. TF*IDF Check API

4.1 TF*IDF Check

5. Term Suggestion API

5.1 TF*IDF Term Suggestion

6. Ranking API

6.1 Ranking (Real Time)

7. Error handling

Did you find this helpful?