API Reference Guide

This is a reference guide for the Majestic SEO API. It contains information about the different indexes available, execution environments, authentication mechanisms, how to actually use the API and detailed information about individual commands.


Indexes - Fresh vs Historic
Majestic SEO maintains two search indexes - a Historic index, which contains data aggregated over several years of crawling, providing the ability to conduct historical link growth analysis, and a Fresh index, that focuses on live, fresh data which we aim to update it daily for an up-to-date illustration of backlinks generation.

Use the datasource parameter to control which index is called.

  1. datasource=historic Use historic index.
  2. datasource=fresh Use fresh index.


Note that at present, flow metrics ( where present ) are returned in the Fresh Index only.
Execution Environments - Live vs Development
The Live environment provides access to the full Majestic SEO dataset - commands executed in this environment will affect subscription resources.

A Development sandbox is available for developers to test their applications without affecting subscription resources, however, this does contains a substantially smaller dataset than the live environment!

Switching between environments is easy - whether working at the 'protocol-level' or using our connectors, it's simply a case of changing the service endpoint.

  • Live service endpoint = http://enterprise.majesticseo.com/api_command.
  • Development service endpoint = http://developer.majesticseo.com/api_command.
Authentication
Each request must be authenticated using either 'Internal/Reseller' or 'OpenApp' authentication protocol. Both protocols are supported by our connectors.

To use Majestic OpenApps developers will need to use their Private Key, which is unique to each application, when calling either of the API endpoints. This is instead of the app_api_key that is used when making an API request.

The Access Token is provided by the user of an application once they have authorized the OpenApp to use their resources.

An example of a request URL can be seen below: 
http://enterprise.majesticseo.com/api_command?privatekey=[ private key ]&accessToken=[ access token ]&cmd=GetNewLostBackLinks&item=www.majesticseo.com&Count=10
An example of a request using the Perl Connector can be seen below: 
my $endpoint = "http://enterprise.majesticseo.com/api_command";

my $api_key = shift @ARGV;
my $url = $ARGV[0];

my %params = (
	'Count' => 10,
	'item' => $url, 
	'Mode' => 0, 
	'datasource' => "fresh"
				);

my $api_service = new MJ12::Remote::ApiService('ApplicationApiKey' => $api_key, 'Endpoint' => $endpoint);
my $response = $api_service->executeCommand('Name' => 'GetBackLinkData', 'Params' => \%params);
Using the API
The API works over the HTTP protocol, taking it's parameters from the request and returning an XML response. You do have the option to work at a 'protocol-level' directly, however for ease of development, we suggest you take a look at our suite of connectors.

Return messages contain a set of message level parameters, and optionally, a set of datatables. Zero or more datatables may be returned for each message. Each datatable may optionally contain it's own parameters, and in addition, contains zero or more rows of data. If rows of data are provided, then header information will be provided on a per table basis in order to identify the columns ( ordering of columns is not guarenteed to be consistant between requests so positional data should only be used to map to headers ). Majestic SEO reserve the right to vary the rows, columns and parameters or tables for any message returned at any time.


Illustration of format of data returned from Majestic API.


Each command has it's own set of parameters and characteristics - some support queueing, some support batching - so please refer to the specific command's documentation during integration.

Datatable headers and row data are delimited by the Pipe charactor "|" ( hexadecimal character: 0x7C). It is possible that some text cells may contain a "|" as part of the data, in which case the single pipe will be replaced with a double pipe - "||", so the data "Good Products | USA" is represented in the raw message data as "Good Products || USA".

Some cells may have empty values. In order to differentate an empty cell from a quoted pipe, such empty cells are represented by a single space character (hexadecimal 0x20): 
				Text| |more text
				     ^
The correct interpretation of the space within a cell is context sensitive, and is left to the client application to interprit.

All data is kept is transmitted in UTF-8 format, and may contain HTML entities.
Response Types
We are now able to return API data in JSON format as well as XML format. XML is available through http://enterprise.majesticseo.com/api_command and JSON is available through http://enterprise.majesticseo.com/api/json.
Please note all users of the XML output are not affected by this addition.

Example XML Output


Example JSON Output

For more information about access to the Majestic API suite, visit our Plans & Pricing page.