|
|
Welcome to the Siteliner Premium API for developers.
This API (Application Programming Interface) allows your developers to write scripts on your server
that control Siteliner Premium scans and retrieve their results in JSON format.
Each scan initiated using the API is billed in the same way as an operation performed through the web-based Siteliner Premium service, costing 1c per page scanned. Each API request to retrieve a scan's results also costs 1c. API requests to control scans and retrieve account details are free.
Usage of the API and web-based interface can be mixed. The results of scans initiated via the API can be browsed online freely, and the API can be used to retrieve the results of scans initiated via the web.
Reports are available for 6 months after the scan was started.
Click to download sample code for accessing the Siteliner API in PHP and Python.
To retrieve a list of completed and running scans and account balance, send an HTTP GET request to this URL:
https://www.siteliner.com/api
Usage of this API command is free. Parameters are specified on the URL (using ? and &) as follows:
| Parameter |
Explanation |
Value |
Required? |
Default |
| user |
Your username |
|
Yes |
– |
| key |
Your API key |
|
Yes |
– |
| report |
Report requested |
account |
Yes |
– |
| count |
Maximum number of results |
1 - 100 |
No |
100 |
| start |
Index of first result (results are ordered chronologically by scan start time, with the most recent first) |
1 or greater |
No |
1 |
The API returns a JSON object containing the following elements:
| Element |
Explanation |
Example |
| report |
Provided report parameter |
account |
| value |
Account balance in dollars |
999.50 |
| credits |
Account balance in 1c credits |
99950 |
| resultcount |
Total results available for this report (ignoring count and start parameters) |
31 |
| results |
Array of result objects, details below |
– |
Each object in the results array may contain the following subelements:
| Element |
Explanation |
Example |
| scan |
Scan ID for use in other API requests |
lmjib545ec |
| rooturl |
Initial URL of scan |
http://www.example.com/ |
| viewurl |
URL for viewing this scan online |
https://www.siteliner.com/premium/lmjib545ec |
| status |
One of: running, paused, stopping, stopped, completed |
completed |
| starttime |
Scan start time as Unix timestamp |
1585649722 |
| endtime |
Scan end time, If scan stopped or completed |
1585649742 |
| scancost |
Cost of scan so far, in dollars |
9.50 |
| apicost |
Cost of API requests retrieving scan results so far |
4.27 |
| found |
Number of pages found so far |
25 |
| retrieved |
Number of pages retrieved so far |
16 |
Example API request to retrieve your account summary:
To start a new scan, send an HTTP POST request to this URL:
https://www.siteliner.com/api
Usage of this API command is free, but your account will be charged 1c per page for the scan itself. Parameters can be specified on the URL or using form urlencoding (see below). The following parameters are required:
| Parameter |
Explanation |
Value |
Required? |
| user |
Your username |
|
Yes |
| key |
Your API key |
|
Yes |
| command |
API command |
start |
Yes |
| rooturl |
Initial URL for scan |
[urlencoded URL] |
Yes |
| maxpages |
Maximum number of pages to retrieve |
1 - 30000 |
Yes |
The following optional parameters are also available:
| Parameter |
Explanation |
Value |
Required? |
Default |
| threads |
Maximum number of pages to retrieve simultaneously |
1 - 4 |
No |
4 |
| scanmode |
Control which pages are scanned |
One of: normal, all, excludedir, rooturl, customrobotstxt (see table below) |
No |
normal |
| includenofollow |
Include pages where all inward links are "nofollow"
 |
1 or 0 |
No |
0 |
| ignorerobotstags |
Ignore robots meta tags
|
1 or 0 |
No |
0 |
| excludedirs |
Exclude specific directories |
[list of excluded directories in website, separated by newlines, e.g. sports/\nbusiness/banking/] |
if scanmode = excludedir |
– |
| customrobotstxt |
Custom robots.txt file |
[robots.txt rows, separated by newlines] |
if scanmode = customrobotstxt |
– |
| usesitemap |
Include pages from sitemap |
1 or 0 |
No |
0 |
| usesitemaponly |
Ignore pages not found in sitemap |
1 or 0 |
No |
0 |
The scanmode parameter can take the following values:
| Value |
Explanation |
| normal |
Scan all pages on the domain of the rooturl, respecting the robots.txt file if found (default). |
| all |
Scan all pages on the domain of the rooturl, ignoring the robots.txt file. |
| excludedirs |
Scan all pages on the domain of the rooturl, but exclude specific directories (see excludedirs parameter) and ignore robots.txt.
|
| customrobotstxt |
Scan all pages on the domain of the rooturl, and apply a custom robots.txt file (see customrobotstxt parameter).
|
| rooturl |
Only scan files within the rooturl directory and ignore robots.txt.
|
Each parameter can be specified in one of two ways:
- Form Encoded. Provide the parameter value as form-urlencoded data within the HTTP POST payload.
This is how web browsers submit forms over HTTP, and will usually be easiest.
If your scripting language lets you create an HTTP POST request with a list of parameter values, it will probably build this automatically.
- Via URL. Provide the parameter value on the URL (using urlencoding and ? and &, as with HTTP GET).
This method may be easier if you are building HTTP requests at a lower level, or using a command-line tool such as curl. Normally, this method cannot be used for excludedirs and customrobotstxt parameters.
If a parameter is specified several times, the last value is used, with Form Encoded overriding Via URL.
The API returns a JSON object described in Scan Management Response below.
To pause a scan, send an HTTP POST request to this URL:
https://www.siteliner.com/api
Usage of this API command is free. Parameters are specified on the URL (using ? and &) as follows:
| Parameter |
Explanation |
Value |
Required? |
| user |
Your username |
|
Yes |
| key |
Your API key |
|
Yes |
| command |
API command |
pause |
Yes |
| scan |
Scan ID (from scan field of other API responses) |
[Scan ID] |
Yes |
The API returns a JSON object described in Scan Management Response below.
To resume a paused scan, send an HTTP POST request to this URL:
https://www.siteliner.com/api
Usage of this API command is free, but your account will be charged 1c per page for the scan itself. Parameters are specified on the URL (using ? and &) as follows:
| Parameter |
Explanation |
Value |
Required? |
| user |
Your username |
|
Yes |
| key |
Your API key |
|
Yes |
| command |
API command |
resume |
Yes |
| scan |
Scan ID (from scan field of other API responses) |
[Scan ID] |
Yes |
The API returns a JSON object described in Scan Management Response below.
To cancel a scan, send an HTTP POST request to this URL:
https://www.siteliner.com/api
Usage of this API command is free. Parameters are specified on the URL (using ? and &) as follows:
| Parameter |
Explanation |
Value |
Required? |
| user |
Your username |
|
Yes |
| key |
Your API key |
|
Yes |
| command |
API command |
cancel |
Yes |
| scan |
Scan ID as returned by 'Start Scan' API, (field scan) |
[Scan ID] |
Yes |
The API returns a JSON object described in Scan Management Response below.
To check the status of a scan, send an HTTP GET request to this URL:
https://www.siteliner.com/api
Usage of this API command is free. Parameters are specified on the URL (using ? and &) as follows:
| Parameter |
Explanation |
Value |
Required? |
| user |
Your username |
|
Yes |
| key |
Your API key |
|
Yes |
| report |
Report requested |
status |
Yes |
| scan |
Scan ID (from scan field of other API responses) |
[Scan ID] |
Yes |
Example API request to check the status of scan lmjib545ec:
The API returns a JSON object described in Scan Management Response below.
All scan management APIs return a JSON object containing the following elements:
| Element |
Explanation |
Present? |
Example |
| scan |
Scan ID |
If scan exists |
lmjib545ec |
| rooturl |
Initial URL of scan |
If scan exists |
https://www.example.com |
| report |
Provided report or command parameter |
Yes |
status |
| viewurl |
URL for viewing this scan online |
If scan exists |
https://www.siteliner.com/premium/lmjib545ec |
| status |
One of: running, paused, stopping, stopped, completed |
If scan exists |
completed |
| starttime |
Scan start time as Unix timestamp |
If scan exists |
1585649722 |
| endtime |
Scan end time |
If stopped or completed |
1585649742 |
| scancost |
Cost of scan so far, in dollars |
If succeeded |
9.50 |
| apicost |
Cost of API requests retrieving scan results so far |
If succeeded |
4.27 |
| found |
Number of pages found so far |
If succeeded |
25 |
| retrieved |
Number of pages retrieved so far |
If succeeded |
16 |
| error |
Error message |
On failure |
Server not found - please check that you entered the URL correctly. |
To retrieve the summary of scan's results, send an HTTP GET request to this URL:
https://www.siteliner.com/api
This API request costs 1c. The scan summary is available for 6 months after the scan was started.
Parameters are specified on the URL (using ? and &) as follows:
| Parameter |
Explanation |
Value |
Required? |
| user |
Your username |
|
Yes |
| key |
Your API key |
|
Yes |
| report |
Report requested |
sitesummary |
Yes |
| scan |
Scan ID (from scan field of other API responses) |
[Scan ID] |
Yes |
The Scan Summary request returns a JSON object containing the following elements:
| Element |
Explanation |
Example |
| scan |
Scan ID |
lmjib545ec |
| rooturl |
Initial URL of scan |
https://www.example.com |
| report |
Provided report parameter |
sitesummary |
| viewurl |
URL for viewing this scan online |
https://www.siteliner.com/premium/lmjib545ec?siteliner=site-dashboard |
| status |
One of: running, paused, stopping, stopped, completed |
completed |
| starttime |
Scan start time as Unix timestamp |
1585649722 |
| endtime |
Scan end time |
1585649742 |
| scancost |
Cost of scan, in dollars |
9.50 |
| apicost |
Cost of API requests retrieving scan results so far |
4.27 |
| found |
Number of pages found (total of retrieved, disallowed, nofollowed and limitreached) |
25 |
| retrieved |
Number of pages retrieved (total of analyzed, redirected, noindexed, notinsitemap, notsupported and failed) |
16 |
| disallowed |
Number of pages not retrieved due to robots.txt or scan options |
2 |
| nofollowed |
Number of pages not retrieved due to all "nofollow" inwards links |
0 |
| limitreached |
Number of pages not retrieved due to scan page limit or scan being stopped |
4 |
| issues |
Array of strings describing site issues found by Siteliner (see online summary report for details) |
|
| analyzed |
Number of pages retrieved whose content was analyzed |
16 |
| redirected |
Number of pages retrieved but which redirected to a different URL |
3 |
| noindexed |
Number of pages retrieved but ignored due a "noindex" robots meta tag |
0 |
| notinsitemap |
Number of pages retrieved but ignored because they were not found in Sitemap |
0 |
| notsupported |
Number of pages retrieved but not supported (e.g. PDFs) |
3 |
| failed |
Number of pages which could not be retrieved due to an error |
2 |
| duplicate |
Percent of duplicate content across all pages |
29.5 |
| common |
Percent of common content across all pages (see FAQs) |
12.3 |
| unique |
Percent of unique content across all pages |
58.2 |
| brokenpages |
Number of pages with broken internal links |
3 |
| brokenlinks |
Number of broken internal links found |
7 |
| totallinks |
Total number of internal links |
60 |
| error |
Error message (only present if an error occurred) |
Scan not found. |
Example API request to retrieve the summary of scan lmjib545ec:
Request and Response
To retrieve a site report for a completed or stopped scan, send an HTTP GET request to this URL:
https://www.siteliner.com/api
Each API request for a site report costs 1c. Site reports are available for 6 months after the scan was started.
Parameters are specified on the URL (using ? and &) as follows:
| Parameter |
Explanation |
Value |
Required? |
Default |
| user |
Your username |
|
Yes |
– |
| key |
Your API key |
|
Yes |
– |
| report |
Report requested |
One of: siteanalyzed, siteskipped, siteduplicate, sitebroken, siterelateddomain |
Yes |
– |
| scan |
Scan ID (from scan field of other API responses) |
[Scan ID] |
Yes |
– |
| count |
Maximum number of results |
1 - 100 |
No |
100 |
| start |
Index of first result to return (see each report's details for ordering) |
1 or greater |
No |
1 |
These APIs return a JSON object containing the following elements:
| Element |
Explanation |
Example |
| scan |
Scan ID |
lmjib545ec |
| rooturl |
Initial URL of scan |
https://www.example.com/ |
| report |
Provided report parameter |
siteanalyzed |
| viewurl |
URL for viewing this report online |
https://www.siteliner.com/premium/lmjib545ec?siteliner=site-overview |
| resultcount |
Total results available for this report (ignoring count and start parameters) |
31 |
| results |
Array of result objects, see each report's details below |
– |
| error |
Error message (only present if an error occurred) |
Scan not found. |
Example API request to retrieve Analyzed Pages report of scan lmjib545ec:
The siteanalyzed report lists the pages whose content was analyzed during the scan. Each object in the results array may contain the following subelements:
| Element |
Explanation |
Example |
| page |
Address of page within domain |
path/page.html |
| url |
Full URL of page |
http://www.example.com/path/page.html |
| viewurl |
URL for viewing cached copy of this page (available up to 60 days from scan start) |
https://www.siteliner.com/premium/lmjib545ec/path/page.html?siteliner=cached |
| title |
Title of page if available |
News |
| inlinks |
Number of pages found with internal links to this page ("nofollow" links excluded) |
4 |
| power |
Page power (see FAQs) |
94 |
| size |
Size of page HTML in bytes |
9378 |
| words |
Number of words on page |
443 |
| modified |
Time page was last modified according to HTTP headers, as Unix timestamp |
1588496264 |
For the Analyzed Pages report, the results array is ordered alphabetically by page.
The siteskipped report lists pages which were found, but whose content was not analyzed during the scan. Each object in the results array may contain the following subelements:
| Element |
Explanation |
Example |
| page |
Address of page within domain |
path/page.html |
| url |
Full URL of page |
http://www.example.com/path/page.html |
| viewurl |
URL for viewing information about this page online (available up to 6 months from scan start) |
https://www.siteliner.com/premium/lmjib545ec/path/page.html?siteliner=page-linkin |
| inlinks |
Number of pages found with internal links to this page ("nofollow" links included only if reason is nofollowed) |
4 |
| power |
Page power (see FAQs) |
94 |
| reason |
Reason for skipping page. One of: disallowed, nofollowed, limitreached, redirectcanonical, redirectframe, redirectheader,
redirecttag, noindexed, notinsitemap, notsupported, failed (see corresponding elements in Scan Summary response for explanations). |
disallowed |
| target |
Redirection target (if reason is redirectcanonical, redirectframe, redirectheader or redirecttag) |
other/page.html |
| error |
Error description (if reason is failed) |
404 - Not Found |
For the Skipped Pages report, the results array is grouped by reason and then ordered by page discovery time.
The siteduplicate report lists pages whose content is duplicated on other analyzed pages. Each object in the results array may contain the following subelements:
| Element |
Explanation |
Example |
| page |
Address of page within domain |
path/page.html |
| url |
Full URL of page |
http://www.example.com/path/page.html |
| viewurl |
URL for viewing the duplicate content on this page (available up to 60 days from scan start) |
https://www.siteliner.com/premium/lmjib545ec/path/page.html?siteliner=duplicate |
| title |
Title of page if available |
News |
| power |
Page power (see FAQs) |
94 |
| matchwords |
Total number of words in this page's duplicate content |
108 |
| matchpercent |
Percent of duplicate content in this page |
43.5 |
| matchpages |
Number of other pages with duplicate content matching this page |
2 |
For the Duplicate Pages report, the results array is ordered descending by matchwords.
The sitebroken report lists pages containing known broken internal links. Each object in the results array may contain the following subelements:
| Element |
Explanation |
Example |
| page |
Address of page within domain |
page/page.html |
| url |
Full URL of page |
http://www.example.com/path/page.html |
| viewurl |
URL for viewing broken links on this page (available up to 60 days from scan start) |
https://www.siteliner.com/premium/lmjib545ec/path/page.html?siteliner=broken |
| title |
Title of page if available |
News |
| power |
Page power (see FAQs) |
94 |
| outlinks |
Number of pages linked from this page ("nofollow" links included) |
3 |
| broken |
Number of pages with broken links from this page ("nofollow" links excluded) |
0 |
For the Internal Broken Links report, the results array is ordered descending by broken.
The siterelateddomain report lists sites with related domains which were linked from analyzed pages. Each object in the results array contains the following subelements:
| Element |
Explanation |
Example |
| url |
Full URL of site with related domain |
http://www.related.example.com/ |
| inlinks |
Number of pages found with links to this site ("nofollow" links included) |
4 |
For the Related Domains report, the results array is ordered alphabetically by url.
To retrieve a page report for a completed or stopped scan, send an HTTP GET request to this URL:
https://www.siteliner.com/api
Each API request for a page report costs 1c. Page reports are available for 185 days after the scan was started.
Parameters are specified on the URL (using ? and &) as follows:
| Parameter |
Explanation |
Value |
Required? |
Default |
| user |
Your username |
|
Yes |
– |
| key |
Your API key |
|
Yes |
– |
| report |
Report requested |
One of: pageduplicate, pagelinkin, pagelinkout, pageexternal |
Yes |
– |
| scan |
Scan ID (from scan field of other API responses) |
[Scan ID] |
Yes |
– |
| page |
Page (from page or url field of other API responses) |
[Page or URL, empty for home page] |
Yes |
– |
| count |
Maximum number of results |
1 - 100 |
No |
100 |
| start |
Index of first result to return (see each report's details for ordering) |
1 or greater |
No |
1 |
These APIs return a JSON object containing the following elements:
| Element |
Explanation |
Example |
| scan |
Scan ID |
lmjib545ec |
| rooturl |
Initial URL of scan |
https://www.example.com/ |
| page |
Address of page within domain |
path/page.html |
| url |
Full URL of page |
http://www.example.com/path/page.html |
| report |
Provided report parameter |
pageduplicate |
| viewurl |
URL for viewing this report online |
https://www.siteliner.com/premium/lmjib545ec/path/page.html?siteliner=page-duplicate |
| title |
Title of page if available |
News |
| resultcount |
Total results available for this report (ignoring count and start parameters) |
31 |
| results |
Array of result objects, see each report's details below |
– |
Example API request to retrieve duplicate report for home page of scan lmjib545ec:
The pageduplicate report lists other analyzed pages containing content which matches the page provided. Each object in the results array may contain the following subelements:
| Element |
Explanation |
Example |
| page |
Address of matching page within domain |
other.html |
| url |
Full URL of matching page |
http://www.example.com/other.html |
| viewurl |
URL for viewing the matching content (available up to 60 days from scan start) |
https://www.siteliner.com/premium/lmjib545ec/page.html?siteliner=duplicate&siteliner-item=05c434334aec4037 |
| title |
Title of matching page if available |
Other |
| matchwords |
Total number of matching words |
108 |
| matchpercent |
Percentage of words matching (out of all words on source page) |
43.5 |
For the Page Duplicate report, the results array is ordered descending by matchwords.
The pagelinkin report lists other analyzed pages which link to the page provided. Each object in the results array may contain the following subelements:
| Element |
Explanation |
Example |
| page |
Address of linking page within domain |
other.html |
| url |
Full URL of linking page |
http://www.example.com/other.html |
| title |
Title of linking page if available |
Other |
| power |
Page power of linking page (see FAQs) |
94 |
| links |
Number of links from linking page to page provided ("nofollow" links included) |
94 |
| status |
Link check if available. One of: ok, nofollow (only if all links are nofollow). |
ok |
For the Internal Links In report, the results array is ordered descending by links.
The pagelinkout report lists other pages on the site which are linked from the page provided. Each object in the results array may contain the following subelements:
| Element |
Explanation |
Example |
| page |
Address of linked page within domain |
other.html |
| url |
Full URL of linked page |
http://www.example.com/other.html |
| title |
Title of linked page or status details if available |
Other |
| links |
Number of links from page provided to linked page (regular and nofollow), status=nofollow only if they are all nofollow |
94 |
| status |
Link check if available. One of: ok, broken, nofollow, unknown |
ok |
For the Internal Links Out report, the results array is ordered descending by links.
The pageexternal report lists external pages which are linked from the page provided. Each object in the results array may contain the following subelements:
| Element |
Explanation |
Example |
| url |
Full URL of external linked page |
http://www.example.com/page.html |
| links |
Number of links from page provided to external linked page |
94 |
For the External Links Out report, the results array is ordered alphabetically by url.
To retrieve a list of analyzed pages which link to a site with a related domain, send an HTTP GET request to this URL:
https://www.siteliner.com/api
The scan must be completed or stopped.
Each API request for a report costs 1c. Related Domain reports are available for 185 days after the scan was started.
Parameters are specified on the URL (using ? and &) as follows:
| Parameter |
Explanation |
Value |
Required? |
Default |
| user |
Your username |
|
Yes |
– |
| key |
Your API key |
|
Yes |
– |
| report |
Report requested |
relatedlinkin |
Yes |
– |
| scan |
Scan ID (from scan field of other API responses) |
[Scan ID] |
Yes |
– |
| url |
Full URL of site with related domain (must match an url from Related Domains Results) |
[Site URL] |
Yes |
– |
| count |
Maximum number of results |
1 - 100 |
No |
100 |
| start |
Index of first result (results are ordered descending by the number of links from each page) |
1 or greater |
No |
1 |
This request returns a JSON object containing the following elements:
| Element |
Explanation |
Example |
| scan |
Scan ID |
lmjib545ec |
| rooturl |
Initial URL of scan |
https://www.example.com/ |
| url |
Provided URL of site with related domain |
http://www1.example.com/ |
| report |
Provided report parameter |
relatedlinkin |
| viewurl |
URL for viewing this report online |
https://www.siteliner.com/premium/lmjib545ec/http://www.related.example.com/?siteliner=page-linkin |
| resultcount |
Total results available for this report (ignoring count and start parameters) |
31 |
| results |
Array of result objects |
– |
Each object in the results array may contain the following subelements:
| Element |
Explanation |
Example |
| page |
Address of linking page within scanned domain |
other.html |
| url |
Full URL of linking page |
http://www.example.com/other.html |
| title |
Title of linking page if available |
Other |
| power |
Page power of linking page (see FAQs) |
94 |
| links |
Number of links from linking page to the provided site ("nofollow" links included) |
94 |
Example API request to retrieve Related Domain Links In report of scan lmjib545ec:
If you have any questions or problems regarding the API, please contact us.
|
