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