LRT Documentation- 03 Discover LRT
- 3 API Integrations
- LRT API
- LRT API Specification
LRT API Specification
LinkResearchTools API
The LinkResearchTools API allows you to start Bulk URL Analyzer (URL) reports for a list of URLs and values. To use the API you need a unique API key which you can find on the Settings page of your account.
You can access the API functionality via simple HTTP POST or GET requests. The response is JSON-formatted.
API URL
The request URL for all API calls is: https://app.linkresearchtools.com/toolkit/api.php
The Link Research Tools API is designed for internal customer applications only and specifically does not permit re-selling (like integration of the data into public available applications) of any data provided through the LinkResearchTools. For a reseller license, please contact us, we would be happy to provide data for your application.
Starting a Bulk URL Analyzer (URL) Report
To start a report send a request with data described in this section to the API URL.
| Field | Value | Comment |
|---|---|---|
api_key |
Your API key | Check your accounts settings area for your personal API key |
action |
start_report |
|
urls[] |
List of input URLs | For example: urls[0]=...&urls[1]=...&urls[2]=... |
url_boost |
URL Boost | Allows you to multiply the maximum number of URLs. Takes values from 1 – 5. |
values[] |
List of value names | You can even request a list of available value names via the API. |
tool |
JUICE |
The tool you want to use. This field is optional and defaults to JUICE. |
title |
Report title | Optional: If not provided, the API will automatically generate a title |
project |
Project name | Optional: If not provided, the project will be the default project. |
Response Object
The response object is an object with the following fields.
| Field | Value | Comment |
|---|---|---|
status |
The request status code | Error codes can be found here. |
message |
A descriptive status message. | |
report |
An object with report information. | This is only set when the API call succeeded. |
report_id |
The id of the report | You need this id to request the report data. |
title |
The title of the report | |
urls |
The URLs for which the report was started. | |
value_names |
The values for which the report was started. | |
tool |
The tool. |
Retrieving Report Data
To get report data send a request with data described in this section to the API URL.
Request
| Field | Value | Comment |
|---|---|---|
api_key |
Your API key | Check your accounts settings area for your personal API key |
action |
get_data |
|
report_id |
The id of the report | You got this id when you started a report. |
data_sections |
Array of data sections which to retrieve. | See below for a list of data sections for each tool. If not set, then all available data sections are returned. |
page |
The page you want to retrieve | If you have more than 25 input URLs in a report, you might have to get the data in separate batches. By default, the first page is shown. |
per_page |
Number of data rows per page | This parameter defines how many data rows (input URLs + metrics) are shown per page. It is generally a good idea not to load 1,000 results in one batch but rather make several smaller requests. Default value is 25. |
Response
The response is an object with the following fields.
| Field | Value | Comment |
|---|---|---|
status |
The request status code | Error codes can be found here. |
message |
A descriptive status message. | |
report |
An object with report information. | This is only set when the API call succeeded. |
report_id |
The id of the report | You need this id to request the report data. |
title |
The title of the report | |
urls |
The URL(s) for which the report was started. | |
value_names |
The values for which the report was started. | |
tool |
The tool. | |
status |
The status of the report. | Based on the status of the report there are additional fields. |
progress |
The progress of the report. | Only set if status is In Progress. (List of report status values) |
overall |
The number of overall jobs. | The report progress in percent is 100 * done/overall |
done |
The number of jobs done. | |
pages |
The progress of the report. | Only set if status is Done, Done with errors or Terminated. (List of report status values) |
columns |
Array with the column titles. | |
data |
Array of arrays with the column values. |
Additionally in the report object are the returned data sections. Each data section is an object with columns and data attributes. Optionally there can also be a rows attribute. The columns and rows attributes are an array with the column and row headers of the data. The dataattribute is an array of arrays with the values associated to a column/row. The inner array holds the values for one row.
Report Status Values
The status field can take the following values
| Value | Comment |
|---|---|
Queued |
Report is waiting to be processed. |
In Progress |
Report is currently processing. |
Done |
Report is finished. |
Done with errors |
Report is done but major errors occurred. |
Broken |
Report is somehow broken. |
Empty |
Report is done, but empty. (Happens if a BLP, SSPT etc. report didn’t return any input values.) |
Suspended |
Report is suspended. This happens if you have no credits left or your subscription is expired. |
removed |
Report was deleted. |
Terminated |
Report got terminated. The data that was crawled so far is available. |
Retrieving a List of SEO Metrics (Value Names)
A request to the API URL with the api_key, the tool and action=list_value_names parameters provided returns a JSON encoded object with the attribute value_names. The value of this attribute is an array with the available value names as description objects (with attributes nameand title).
FYI: Internally, we call our SEO metrics “value names”, therefore the difference between the API documentation and the toolkit.
Retrieving a List of Reports
A request to the API URL with the api_key and the action=list_reports parameters returns a json encoded object with the attribute reports which is a list of objects describing the reports that were started by the API. The report description consists of the attributes report_id, date, title and url_count.
Error Codes
| Code | Description |
|---|---|
| 100 | API call succeeded |
| 200 | Internal API Error |
| 201 | User has no API key |
| 202 | No API key provided or incorrect API key |
| 203 | Incorrect tool name |
| 204 | Incorrect value names provided |
| 205 | No valid URL(s) provided |
| 206 | Not enough credits to start report |
| 207 | Could not create report |
| 208 | Incorrect report id |
| 209 | Not supported action |
| 210 | Wrong account type |
| 211 | Account blocked from API |
| 212 | No Reports found for account |
Download Example Scripts
We prepared test implementations in PHP and Ruby (with and without CURL) that should help you start coding quickly. If you find any problems or have any questions, please contact us using the feedback form!
Questions or Feedback?
We know this can seem a bit complex at first, but we hope the examples get you started.
We’d love to hear how you’re using or planning to use our API.